From adabb3428de67cf6e493ab5b1308e1cd68472ebc Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Wed, 13 May 2026 07:59:53 +0200
Subject: [PATCH] docs(work): scaffold dag-and-readiness-v1 epic + stories

---
 docs/work/_state.json                         | 26 ++++++++++++++++++-
 .../01-extended-state/_story.md               | 17 ++++++++++++
 .../02-dag-computation/_story.md              | 16 ++++++++++++
 .../03-cli-subcommands/_story.md              | 18 +++++++++++++
 docs/work/dag-and-readiness-v1/_epic.md       | 21 +++++++++++++++
 5 files changed, 97 insertions(+), 1 deletion(-)
 create mode 100644 docs/work/dag-and-readiness-v1/01-extended-state/_story.md
 create mode 100644 docs/work/dag-and-readiness-v1/02-dag-computation/_story.md
 create mode 100644 docs/work/dag-and-readiness-v1/03-cli-subcommands/_story.md
 create mode 100644 docs/work/dag-and-readiness-v1/_epic.md

diff --git a/docs/work/_state.json b/docs/work/_state.json
index 4e9b00f..2f3d122 100644
--- a/docs/work/_state.json
+++ b/docs/work/_state.json
@@ -1,5 +1,5 @@
 {
-  "updated_at": "2026-05-13T05:56:35.878Z",
+  "updated_at": "2026-05-13T05:59:55.392Z",
   "epics": {
     "agent-workflow-docs-v1": {
       "status": "done",
@@ -79,6 +79,30 @@
         }
       }
     },
+    "dag-and-readiness-v1": {
+      "status": "in-progress",
+      "title": "DAG + readiness — depends-on / blocks parsing",
+      "stories": {
+        "01-extended-state": {
+          "status": "in-progress",
+          "title": "Frontmatter array parsing + extended state shape",
+          "ac_total": 4,
+          "ac_completed": 0
+        },
+        "02-dag-computation": {
+          "status": "todo",
+          "title": "DAG computation — ready + blocked story sets",
+          "ac_total": 3,
+          "ac_completed": 0
+        },
+        "03-cli-subcommands": {
+          "status": "todo",
+          "title": "CLI ready / blocked subcommands",
+          "ac_total": 5,
+          "ac_completed": 0
+        }
+      }
+    },
     "frontend-conformance-v1": {
       "status": "done",
       "title": "Frontend conformance rules v1",
diff --git a/docs/work/dag-and-readiness-v1/01-extended-state/_story.md b/docs/work/dag-and-readiness-v1/01-extended-state/_story.md
new file mode 100644
index 0000000..15f4001
--- /dev/null
+++ b/docs/work/dag-and-readiness-v1/01-extended-state/_story.md
@@ -0,0 +1,17 @@
+---
+id: 01-extended-state
+epic: dag-and-readiness-v1
+title: Frontmatter array parsing + extended state shape
+type: technical-story
+status: in-progress
+feature: scripts
+depends-on: []
+blocks: [02-dag-computation]
+---
+
+## Tasks
+
+- [ ] Story scaffold
+- [ ] Extend parseFrontmatter to parse array values like `depends-on: [a, b]`
+- [ ] Extend buildState to include depends_on + blocks per story entry
+- [ ] Update existing tests; add new array-parsing tests
diff --git a/docs/work/dag-and-readiness-v1/02-dag-computation/_story.md b/docs/work/dag-and-readiness-v1/02-dag-computation/_story.md
new file mode 100644
index 0000000..b9136a0
--- /dev/null
+++ b/docs/work/dag-and-readiness-v1/02-dag-computation/_story.md
@@ -0,0 +1,16 @@
+---
+id: 02-dag-computation
+epic: dag-and-readiness-v1
+title: DAG computation — ready + blocked story sets
+type: technical-story
+status: todo
+feature: scripts
+depends-on: [01-extended-state]
+blocks: [03-cli-subcommands]
+---
+
+## Tasks
+
+- [ ] computeReadyBlocked(state) — pure function
+- [ ] Tests
+- [ ] Wire into buildState output
diff --git a/docs/work/dag-and-readiness-v1/03-cli-subcommands/_story.md b/docs/work/dag-and-readiness-v1/03-cli-subcommands/_story.md
new file mode 100644
index 0000000..f56ce95
--- /dev/null
+++ b/docs/work/dag-and-readiness-v1/03-cli-subcommands/_story.md
@@ -0,0 +1,18 @@
+---
+id: 03-cli-subcommands
+epic: dag-and-readiness-v1
+title: CLI ready / blocked subcommands
+type: technical-story
+status: todo
+feature: scripts
+depends-on: [02-dag-computation]
+blocks: []
+---
+
+## Tasks
+
+- [ ] `pnpm work ready` — prints ready stories
+- [ ] `pnpm work blocked` — prints blocked stories with waiting_on
+- [ ] Update `pnpm work next` to use the ready set
+- [ ] CLI smoke tests
+- [ ] Final verification + closeout
diff --git a/docs/work/dag-and-readiness-v1/_epic.md b/docs/work/dag-and-readiness-v1/_epic.md
new file mode 100644
index 0000000..77842b4
--- /dev/null
+++ b/docs/work/dag-and-readiness-v1/_epic.md
@@ -0,0 +1,21 @@
+---
+id: dag-and-readiness-v1
+prd: null
+title: DAG + readiness — depends-on / blocks parsing
+type: epic
+status: in-progress
+features: [scripts]
+created: 2026-05-13
+---
+
+## Goal
+
+Extend the state builder + CLI so `pnpm work next` / `pnpm work ready` /
+`pnpm work blocked` answer "what's actually unblocked right now?"
+from the depends-on graph instead of just the first non-done story.
+
+## Stories
+
+- [ ] [01 — Frontmatter array parsing + extended state shape](01-extended-state/_story.md)
+- [ ] [02 — DAG computation: ready + blocked](02-dag-computation/_story.md)
+- [ ] [03 — CLI ready / blocked subcommands](03-cli-subcommands/_story.md)