@dtlabs/ai-toolkit 0.17.4 → 0.18.0

package/src/claude/agents/gaia-generate-work-breakdown.md

@@ -1,13 +1,15 @@
 ---
 name: gaia-generate-work-breakdown
-description: "Generates a structured work breakdown (User Stories + Tasks) from validated and approved Requirements and Tech-Spec. Input: path to feature.md"
+description: "Generates the structural skeleton of a Work Breakdown (phases + per-task structural fields) from validated and approved Requirements and Tech-Spec. Input: path to feature.md"
 model: sonnet
 tools: Read, Glob, Grep
 ---
 
-# Generate Work Breakdown
+# Generate Work Breakdown — Skeleton Pass
 
-You are an **expert software architect** specializing in work decomposition and delivery planning. Given a feature's functional requirements and technical specification, produce a structured **work breakdown** as a versioned JSON file (`{PREFIX}-Work-Breakdown.json`, schema v2) that is the sole authoritative source of truth for all tasks.
+You are an **expert software architect** specializing in work decomposition and delivery planning. Given a feature's functional requirements and technical specification, produce the **skeleton** of a structured work breakdown: every phase and, per task, only the structural fields needed to fix the dependency graph and acceptance-criteria assignment — `id`, `title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `estimate`, `outputCount`, `commit`.
+
+This is the **first of two generation passes** (FTR-020). This call decides the whole task graph — IDs, phases, domains, dependencies, AC assignment — once, up front, in one bounded response. A separate per-task agent (`gaia-generate-work-breakdown-task`) is then dispatched once per task, filling in that task's own verification commands and grouping rationale. You do **not** produce verification commands or grouping-rationale prose — see `gaia-generate-work-breakdown-task` for that.
 
 ---
 
@@ -50,12 +52,7 @@ Extract the **feature prefix** from the folder name containing `feature.md`:
 
 The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`).
 
-**Primary output (write this file):**
-- `{PREFIX}-Work-Breakdown.json` — authoritative machine-readable work breakdown (schema v2), written to the same directory as `feature.md`
-
-**Do NOT write `{PREFIX}-Work-Breakdown.md` or `{PREFIX}-Work-Breakdown.csv`.** Those are generated deterministically from the JSON by `wb-render.js` in a later pipeline step.
-
-"Authoritative" above means authoritative **for this agent's own generation and for `wb-validate.js`'s structural checks** — it does not mean every downstream reader consumes the JSON. The rendered `.md` (plus the dispatch `.csv`) is the tested, complete deliverable for everything that reads a Work Breakdown afterward: `lib/task-executor/plan.js` (the real task executor parses `.md`+`.csv`, never the JSON) and the `gaia-developer-*` agents both read the `.md`, and `tests/wb-render.*.test.js` specifically guards that every field they need (dependencies, verification commands, acceptance criteria, etc.) survives the JSON→Markdown rendering byte-for-byte. Only `gaia-validate-work-breakdown-semantic` reads the JSON directly, for its own programmatic comparison against Requirements ACs.
+You do not have a Write tool. Return the skeleton as your final response, and nothing else — the host persists your response and splits it into `wbs/index.json` plus one `wbs/user-stories/{phaseId}.md` per phase (your `title`/`commit`/`context` values are written there; see Step 7).
 
 ---
 
@@ -74,7 +71,7 @@ Every task must be the **smallest independently implementable, verifiable, and c
 - Bundling two independently verifiable activities (e.g., "add endpoint and write tests") — split into separate tasks.
 - Scope misalignment: a task in US-02 that implements a behavior belonging to US-03.
 - **Duplicate implementation**: a later phase re-describing, as a new `BE`/`FE`/`DB` task, an outcome or file already fully produced by an earlier task (e.g., a controller task that already built audience-claim validation inline, followed by a later phase's task claiming to "implement" that same validation again). Check every earlier task's `outcome` before writing a new one for the same file or behavior. If the behavior already exists, the later phase's task must be `domain: TEST` (`developer-testing`), verifying it with `dependsOn` pointing at the task(s) that built it — never a second implementation task.
-- **Domain mismatch on verification-only tasks**: a task whose outcome is a confirmation of already-built behavior (title starting with "Verify", "Confirm", or similar) and whose verification commands are read-only (`grep`, `test -f`, build-only, no new file created) must be `domain: TEST` / `agentType: developer-testing` — never `BE`/`FE`/`DB` with an implementation agent type.
+- **Domain mismatch on verification-only tasks**: a task whose outcome is a confirmation of already-built behavior (title starting with "Verify", "Confirm", or similar) must be `domain: TEST` / `agentType: developer-testing` — never `BE`/`FE`/`DB` with an implementation agent type.
 
 ---
 
@@ -99,6 +96,7 @@ For each US, derive:
 - **Phase title** — the UC title
 - **Phase type** — `"user-story"`
 - **Phase commit** — a phase-level commit object: `{ "type": "feat", "subject": "implement US-NN title" }` — the subject must not contain `|`, CR, or LF characters; `wb-render.js` prepends the conventional prefix automatically
+- **Phase `sourceUC`** — the UC-ID(s) this phase actually realizes (array). Usually `["UC-NN"]`, matching the phase it derives from — but if this phase's tasks genuinely implement mechanics belonging to more than one UC (e.g. an orchestration/integration phase wiring together several use cases' flows), list every UC it realizes, not just the one its number happens to match. Conversely, if one UC's mechanics are split across more than one phase (e.g. one UC covers two independent technical concerns that you decompose into two phases), each phase's `sourceUC` lists only the UC(s) it actually realizes — do not pad it with a UC a phase doesn't implement just because the phase number suggests it should. **Do not infer this from ID numbering** — decide it from what the phase's tasks actually do.
 - **Acceptance Criteria** — the AC-XX IDs from the Requirements document that apply to this US
 
 **Do not create an additional phase for end-to-end, integration, or overall verification.** Every phase traces to exactly one UC (plus the single `INFRA` phase for shared setup) — never a synthesized "Testing and verification", "Integration tests", or similarly feature-spanning phase. An integration/E2E test still belongs to the US phase of the UC it most directly verifies, as a `domain: TEST` task citing only that phase's own AC(s) — not a phase of its own, and not a grab-bag of ACs borrowed from across the feature.
@@ -124,23 +122,22 @@ Decomposition strategy by domain:
 
 `{DOMAIN}` in the task ID must match the `domain` field. `{NN}` is a two-digit zero-padded counter.
 
-**Required task fields:**
+**Required task fields (this pass — the skeleton):**
 
 | Field | Type | Constraint |
 |-------|------|-----------|
-| `id` | string | Format: `INFRA-TASK-{DOMAIN}-{NN}` or `{US-ID}-TASK-{DOMAIN}-{NN}` |
 | `title` | string | Short descriptive title; must not contain `\|`, CR, or LF |
 | `outcome` | string | Single observable outcome — what exists after this task is done |
 | `domain` | string | One of: `BE`, `FE`, `DB`, `DevOps`, `INFRA`, `TEST` |
 | `agentType` | string | One of: `developer-backend`, `developer-frontend`, `developer-testing`, `review-solution` (deprecated: `developer-database` — maps to `developer-backend`) |
-| `dependsOn` | array of strings | Task IDs this task depends on; may be empty `[]`; all IDs must be defined within this same JSON |
+| `dependsOn` | array of strings | Task IDs this task depends on; may be empty `[]`; all IDs must be defined within this same response |
 | `acceptanceCriteria` | array of strings | AC IDs from Requirements scoped to this task's own phase that this task covers; may be empty `[]`. Never an AC owned by a different phase (see Guidelines) |
-| `verification` | object | `{ "commands": ["..."] }` — one or more shell commands that verify the task output; array must be non-empty |
 | `estimate` | object | `{ "agentMinutes": N, "tokens": N }` — target ≤ 15 minutes; positive integers |
 | `outputCount` | integer | Number of distinct outputs; must be ≥ 1 |
-| `groupingRationale` | string or null | Required (non-null) when `outputCount > 1`; explains why grouping is justified |
 | `commit` | object | `{ "type": "feat", "subject": "..." }` — subject must not contain `\|`, CR, or LF |
 
+`verification.commands` and `groupingRationale` are **not** produced in this pass — they are decided by `gaia-generate-work-breakdown-task`, one call per task, from the skeleton entry you produce here (it is told your task's `outputCount`, so it knows whether a grouping rationale is required).
+
 **Domain → agentType mapping (default):**
 - `DB` → `developer-backend` (note: `developer-database` is a deprecated alias that still resolves — do NOT use it in new Work Breakdowns)
 - `BE`, `INFRA`, `DevOps` → `developer-backend`
@@ -156,6 +153,7 @@ Some tasks are prerequisites for multiple User Stories. Extract these into a ded
 - Phase `type`: `"infrastructure"`
 - Phase `title`: descriptive (e.g., `"Shared infrastructure setup"`)
 - Phase `commit`: a phase-level commit (e.g., `{ "type": "feat", "subject": "shared infrastructure" }`)
+- Phase `sourceUC`: `[]` — shared infrastructure has no single originating UC, by definition
 - Task IDs: `INFRA-TASK-{DOMAIN}-{NN}`
 
 Examples of infrastructure tasks:
@@ -170,7 +168,7 @@ The INFRA phase, if present, must appear first in the `phases` array.
 ### Step 5 — Resolve Dependencies
 
 For each task, determine `dependsOn` as a list of **task IDs** (not phase IDs):
-- All referenced task IDs must be defined within this same JSON (no dangling references)
+- All referenced task IDs must be defined within this same response (no dangling references)
 - A task may reference both INFRA tasks and tasks within its own phase or other US phases
 - No self-references (a task cannot depend on itself)
 - No cycles (A → B → A is invalid)
@@ -186,15 +184,15 @@ Duration guidance:
 | Band | Range | Action |
 |------|-------|--------|
 | Target | ≤ 15 min | No action needed |
-| Above target | 16–20 min | Acceptable; note in `groupingRationale` if applicable |
-| Warning | 21–30 min | Prefer to split; if justified, add `groupingRationale` |
+| Above target | 16–20 min | Acceptable |
+| Warning | 21–30 min | Prefer to split |
 | Split required | > 30 min | **Must split** — the validator will reject this |
 
 - `estimate.tokens`: integer; rough estimate of token consumption (input + output) for the agent invocation; use project norms if available, otherwise estimate based on task complexity (small: 10 000–25 000, medium: 25 000–60 000)
 
-### Step 7 — Return the JSON Output
+### Step 7 — Return the Skeleton
 
-Return `{PREFIX}-Work-Breakdown.json`'s content as your final response, and nothing else (no preamble, no explanatory prose, no Markdown code fence wrapping it) — you do not have a Write tool; the host persists your response verbatim to disk. The content must be:
+Return the skeleton's content as your final response, and nothing else (no preamble, no explanatory prose, no Markdown code fence wrapping it) — you do not have a Write tool; the host persists your response. The content must be:
 - Valid JSON
 - UTF-8 encoded
 - 2-space indentation
@@ -204,15 +202,17 @@ Return `{PREFIX}-Work-Breakdown.json`'s content as your final response, and noth
 
 ```json
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "feature": "{PREFIX}",
-  "phases": [ ... ]
+  "phases": [ ... ],
+  "tasks": { ... }
 }
 ```
 
-- `schemaVersion` must be exactly `2` (integer)
-- `feature` must be the feature prefix string (e.g., `"FTR-014"`)
+- `schemaVersion` must be exactly `3` (integer)
+- `feature` must be the feature prefix string (e.g., `"FTR-020"`)
 - `phases` is an ordered array of phase objects; INFRA phase first (if present), then US phases in priority order
+- `tasks` is a **map keyed by task ID** (not nested inside each phase) — every phase's `taskIds` array indexes into this map
 
 **Phase object:**
 
@@ -222,7 +222,9 @@ Return `{PREFIX}-Work-Breakdown.json`'s content as your final response, and noth
   "type": "infrastructure",
   "title": "Shared infrastructure setup",
   "commit": { "type": "feat", "subject": "shared infrastructure" },
-  "tasks": [ ... ]
+  "sourceUC": [],
+  "context": "2-4 sentences: why this phase exists, how its own tasks relate to each other, and any dependency/sequencing reason other phases need to know before opening this phase's task files. Never restate the title.",
+  "taskIds": ["INFRA-TASK-BE-01"]
 }
 ```
 
@@ -234,18 +236,37 @@ For user-story phases:
   "type": "user-story",
   "title": "As a... I want... so that...",
   "commit": { "type": "feat", "subject": "implement US-01 user management" },
-  "tasks": [ ... ]
+  "sourceUC": ["UC-01"],
+  "context": "2-4 sentences: why this phase exists, how its own tasks relate to each other, and any dependency/sequencing reason other phases need to know before opening this phase's task files. Never restate the title.",
+  "taskIds": ["US-01-TASK-DB-01", "US-01-TASK-BE-01"]
 }
 ```
 
 - `phase.commit.subject` must not contain `|`, CR, or LF — `wb-render.js` constructs the full conventional message from it
+- `phase.context` is persisted verbatim into this phase's own `wbs/user-stories/{id}.md` detail file (the host does not re-derive or summarize it) — it is the one piece of phase-detail content that genuinely needs your judgment; "Tasks in this phase" and "Depends on phases" are both derived mechanically by the host from `taskIds`/each task's own `title`/`dependsOn`, so do not restate those here
 - Each phase must have at least one task
 
-**Full example JSON:**
+**Task entry (in the `tasks` map, keyed by its own ID):**
+
+```json
+{
+  "title": "Create base repository interface",
+  "outcome": "IRepository<T> interface exists at src/interfaces/IRepository.ts with CRUD method signatures",
+  "domain": "BE",
+  "agentType": "developer-backend",
+  "dependsOn": [],
+  "acceptanceCriteria": [],
+  "estimate": { "agentMinutes": 8, "tokens": 15000 },
+  "outputCount": 1,
+  "commit": { "type": "feat", "subject": "add IRepository base interface" }
+}
+```
+
+**Full example response:**
 
 ```json
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "feature": "FTR-NNN",
   "phases": [
     {
@@ -253,88 +274,60 @@ For user-story phases:
       "type": "infrastructure",
       "title": "Shared infrastructure setup",
       "commit": { "type": "feat", "subject": "shared infrastructure" },
-      "tasks": [
-        {
-          "id": "INFRA-TASK-BE-01",
-          "title": "Create base repository interface",
-          "outcome": "IRepository<T> interface exists at src/interfaces/IRepository.ts with CRUD method signatures",
-          "domain": "BE",
-          "agentType": "developer-backend",
-          "dependsOn": [],
-          "acceptanceCriteria": [],
-          "verification": { "commands": ["npx tsc --noEmit"] },
-          "estimate": { "agentMinutes": 8, "tokens": 15000 },
-          "outputCount": 1,
-          "groupingRationale": null,
-          "commit": { "type": "feat", "subject": "add IRepository base interface" }
-        }
-      ]
+      "sourceUC": [],
+      "context": "Shared repository interface every other phase's data-access tasks depend on — opened first so downstream phases never block on it later.",
+      "taskIds": ["INFRA-TASK-BE-01"]
     },
     {
       "id": "US-01",
       "type": "user-story",
       "title": "As an admin, I want to create a user, so that new members can access the system",
       "commit": { "type": "feat", "subject": "implement US-01 user creation" },
-      "tasks": [
-        {
-          "id": "US-01-TASK-DB-01",
-          "title": "Create User entity and migration",
-          "outcome": "User entity class and initial migration exist; database table is created on migration run",
-          "domain": "DB",
-          "agentType": "developer-database",
-          "dependsOn": ["INFRA-TASK-BE-01"],
-          "acceptanceCriteria": ["AC-01", "AC-03"],
-          "verification": { "commands": ["npx tsc --noEmit", "npm test -- --testPathPattern=user.entity"] },
-          "estimate": { "agentMinutes": 12, "tokens": 28000 },
-          "outputCount": 1,
-          "groupingRationale": null,
-          "commit": { "type": "feat", "subject": "add User entity and migration" }
-        },
-        {
-          "id": "US-01-TASK-BE-01",
-          "title": "Implement CreateUserService",
-          "outcome": "CreateUserService class exists with createUser method; validates input, persists User, returns created entity",
-          "domain": "BE",
-          "agentType": "developer-backend",
-          "dependsOn": ["US-01-TASK-DB-01"],
-          "acceptanceCriteria": ["AC-02"],
-          "verification": { "commands": ["npx tsc --noEmit"] },
-          "estimate": { "agentMinutes": 14, "tokens": 35000 },
-          "outputCount": 1,
-          "groupingRationale": null,
-          "commit": { "type": "feat", "subject": "add CreateUserService" }
-        }
-      ]
+      "sourceUC": ["UC-01"],
+      "context": "Covers the full create-user path end to end: the entity/migration task establishes storage, the service task implements validation and persistence on top of it.",
+      "taskIds": ["US-01-TASK-DB-01", "US-01-TASK-BE-01"]
+    }
+  ],
+  "tasks": {
+    "INFRA-TASK-BE-01": {
+      "title": "Create base repository interface",
+      "outcome": "IRepository<T> interface exists at src/interfaces/IRepository.ts with CRUD method signatures",
+      "domain": "BE",
+      "agentType": "developer-backend",
+      "dependsOn": [],
+      "acceptanceCriteria": [],
+      "estimate": { "agentMinutes": 8, "tokens": 15000 },
+      "outputCount": 1,
+      "commit": { "type": "feat", "subject": "add IRepository base interface" }
+    },
+    "US-01-TASK-DB-01": {
+      "title": "Create User entity and migration",
+      "outcome": "User entity class and initial migration exist; database table is created on migration run",
+      "domain": "DB",
+      "agentType": "developer-backend",
+      "dependsOn": ["INFRA-TASK-BE-01"],
+      "acceptanceCriteria": ["AC-01", "AC-03"],
+      "estimate": { "agentMinutes": 12, "tokens": 28000 },
+      "outputCount": 1,
+      "commit": { "type": "feat", "subject": "add User entity and migration" }
+    },
+    "US-01-TASK-BE-01": {
+      "title": "Implement CreateUserService",
+      "outcome": "CreateUserService class exists with createUser method; validates input, persists User, returns created entity",
+      "domain": "BE",
+      "agentType": "developer-backend",
+      "dependsOn": ["US-01-TASK-DB-01"],
+      "acceptanceCriteria": ["AC-02"],
+      "estimate": { "agentMinutes": 14, "tokens": 35000 },
+      "outputCount": 1,
+      "commit": { "type": "feat", "subject": "add CreateUserService" }
     }
-  ]
+  }
 }
 ```
 
 ---
 
-## Verification Commands
-
-For each task, supply one or more shell commands in `verification.commands` that an agent can run to confirm the task output is correct. The array must be non-empty. Use commands appropriate for the project's tech stack (read from `AGENTS.md`). Examples:
-- Compilation check: `npx tsc --noEmit`, `dotnet build`
-- Targeted test run: `npm test -- --testPathPattern=<file>`, `dotnet test --filter <class>`
-- File existence: `test -f <path>`
-- Lint: `npx eslint <file>`
-
-**Directory-only tasks must never verify with `test -d` alone.** Git does not track empty
-directories — `test -d <path>` only confirms the directory exists in the *current* working tree,
-which is exactly what the agent that just created it will have. It tells you nothing about
-whether anything was actually committed: a fresh clone, or any downstream agent/review step that
-re-checks out the branch, will find the directory simply missing, even though this task's own
-verification reported success. If a task's sole outcome is creating one or more directories (no
-files):
-- Give it a `.gitkeep` (or equivalent) placeholder file in every leaf directory it creates, so
-  there is something for git to actually track.
-- Verify with a command that checks the directory is *tracked*, not just present on disk — e.g.
-  `git ls-files <path> | grep -q .` or `test -f <path>/.gitkeep` — instead of (or in addition to)
-  `test -d <path>`.
-
----
-
 ## Clarification Protocol
 
 When decomposing User Stories into tasks, if the Requirements or Tech-Spec are ambiguous, **stop and ask the user** before proceeding. Use the `AskUserQuestion` tool to present:
@@ -354,11 +347,12 @@ Do NOT guess or invent task decompositions when the source is unclear. Ask first
 - **Atomicity is mandatory** — each task must have one outcome, one domain, one agent type, one commit subject
 - **Task granularity**: target ≤ 15 minutes of agent time; split any task that cannot be scoped to ≤ 15 minutes
 - **Domain assignment must be unambiguous** — use the domain table in Step 3
-- **dependsOn must reference only task IDs defined in this JSON** — no dangling references
+- **dependsOn must reference only task IDs defined in this response** — no dangling references
 - **Cross-phase dependencies are expected** — US tasks may depend on INFRA tasks; cross-US task dependencies are also valid
 - **INFRA phase first** (if present), then US phases in priority order (Must before Should before Could)
 - **Within a phase, order tasks by layer dependency** (DB → BE → FE → TEST); independent tasks within the same layer may be listed in any order
 - **acceptanceCriteria** must list only AC IDs whose Requirements AC-table scope ("Related UC") matches this task's own phase, or that are marked cross-cutting ("All UCs"/multiple UCs including this phase's). **Never cite an AC owned by a different phase on this task, even when this task is prerequisite or contributing work for it** — an INFRA task that lays groundwork for an AC verified in a later US does not "cover" that AC; leave `acceptanceCriteria` empty `[]` on that task instead (e.g., pure infrastructure setup, or groundwork for an AC owned elsewhere). If an AC is genuinely cross-cutting, reflect that in the AC's own "Related UC" column, not by citing it from an unrelated task.
-- **schemaVersion must be exactly 2** — do not omit it, do not use any other value
+- **`sourceUC` must reflect what a phase's tasks actually implement, not its number** — see Step 2.
+- **schemaVersion must be exactly 3** — do not omit it, do not use any other value
 - **No pipes, CR, or LF** in `phase.title`, `task.title`, or `commit.subject` — these characters break CSV generation
 - **Traceability**: every UC must map to a US phase; every Must-priority AC must be covered by at least one task's `acceptanceCriteria` **within that AC's own owning US phase** (per its "Related UC" scope) — not by a task in an earlier or later phase, even one that contributes toward satisfying it eventually

package/src/claude/agents/gaia-validate-feature-docs.md

@@ -7,18 +7,23 @@ tools: Read, Glob, Grep
 
 # Validate Feature Docs
 
-A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md` and `{PREFIX}-Tech-Spec.md` and identifies coverage gaps in a single validation pass. The host workflow owns revisions and the three-cycle limit. Do not dispatch other agents or revise the input documents.
+A QA agent that cross-references `feature.md` against the Requirements and Tech-Spec documents and identifies coverage gaps in a single validation pass. The host workflow owns revisions and the three-cycle limit. Do not dispatch other agents or revise the input documents.
 
 ---
 
 ## Phase 1 — Load Documents
 
 1. Extract the prefix from the folder name (`FTR-001-user-management` → `FTR-001`)
-2. Read all three documents fully:
-   - `feature.md` — source of truth
-   - `{PREFIX}-Requirements.md`
-   - `{PREFIX}-Tech-Spec.md`
-3. If an input document is missing, record a finding identifying it, skip checks that require it, and complete Phases 6 and 7 with `valid: false`. Never claim full coverage when an input could not be read.
+2. Read `feature.md` fully — its path is given to you first; use your Read tool.
+3. The Requirements and Tech-Spec document text is included directly below, inlined into this
+   prompt under `Requirements:` and `Tech-Spec:` labels — do NOT attempt to locate or Read
+   `{PREFIX}-Requirements.md`/`{PREFIX}-Tech-Spec.md` on disk; they are not guaranteed to exist
+   (both documents are generated and stored in a split, per-item format by default — `req/`,
+   `spec/` — and only assembled into a single file when a user explicitly requests it). Use the
+   inlined text as the complete, authoritative content of each document for this validation pass.
+4. If either inlined document's text is empty or missing, record a finding identifying it, skip
+   checks that require it, and complete Phases 6 and 7 with `valid: false`. Never claim full
+   coverage when an input could not be read.
 
 ---
 
@@ -44,7 +49,7 @@ Label each claim with its origin section in `feature.md`.
 
 For each claim extracted in Phase 2, check whether it is addressed in the target document:
 
-### Requirements coverage (against `{PREFIX}-Requirements.md`)
+### Requirements coverage (against the inlined Requirements text)
 
 | Check | Pass condition |
 |-------|---------------|
@@ -55,7 +60,7 @@ For each claim extracted in Phase 2, check whether it is addressed in the target
 | Every out-of-scope item → Out of Scope section | Listed |
 | Every functional behaviour → at least one Acceptance Criterion | AC in Given/When/Then format |
 
-### Tech-Spec coverage (against `{PREFIX}-Tech-Spec.md`)
+### Tech-Spec coverage (against the inlined Tech-Spec text)
 
 | Check | Pass condition |
 |-------|---------------|

package/src/claude/commands/assemble-docs.md

@@ -0,0 +1,16 @@
+---
+description: "Assemble Docs — renders the split Requirements/Tech-Spec/Work-Breakdown sources into single combined documents, on demand. Usage: /assemble-docs <feature-slug> [req|spec|wbs|all]"
+argument-hint: <feature-slug> [req|spec|wbs|all]
+allowed-tools: Bash, Glob, Read
+---
+
+Produce an on-demand, single-file view of one or more of this feature's split documents.
+
+Approach:
+1. Locate the feature folder under `docs/features/` (match by slug or FTR id) from the first argument.
+2. Extract the prefix from the folder name (`FTR-025-slug` → `FTR-025`).
+3. Determine `which` from the second argument (default `all`).
+4. Run: `node .claude/scripts/assemble-docs.js <feature-dir> <prefix> <which>`
+5. Report exactly what was written (the script's own JSON `written` array), or surface its error message verbatim if it failed — do not retry or guess an alternative path.
+
+This command is a read-only rendering action: it never affects Gate 1/Gate 2, approvals, or any digest. Running it is always safe, at any point in the pipeline.

package/src/claude/commands/feature-status.md

@@ -10,10 +10,15 @@ Steps:
 1. Locate the feature folder under `docs/features/`. Match by slug or FTR id (e.g. `FTR-001-user-login` matches both `001` and `user-login`).
 2. For each of the following artifacts, check presence and basic completeness:
    - `feature.md` — the source brief
-   - `{PREFIX}-Requirements.md` — functional requirements
-   - `{PREFIX}-Tech-Spec.md` — technical specification
-   - `{PREFIX}-Work-Breakdown.md` — user stories + tasks
-   - Implementation status: cross-check tasks in the work breakdown against the codebase. For each task, report `done` / `partial` / `not started` based on whether the referenced files/symbols exist.
+   - Requirements — ✅ if either `req/index.md` (split, default) or `{PREFIX}-Requirements.md`
+     (assembled, legacy or user-requested via `/assemble-docs`) exists; note which shape was found
+   - Tech-Spec — ✅ if either `spec/index.md` (split, default) or `{PREFIX}-Tech-Spec.md`
+     (assembled) exists; note which shape was found
+   - Work Breakdown — ✅ if either `wbs/index.json` (split, always the case since FTR-020) or
+     `{PREFIX}-Work-Breakdown.md` (rendered, only present if `/assemble-docs` was run) exists
+   - Implementation status: cross-check tasks in the work breakdown against the codebase (read
+     `wbs/` directly). For each task, report `done` / `partial` / `not started` based on whether
+     the referenced files/symbols exist.
 3. Output a single markdown table with columns: `Artifact | Status | Notes`. Status uses ✅ / ⚠️ / ❌. Keep notes under 80 chars.
 4. After the table, list the next 1–3 actionable items in priority order.
 

package/src/claude/scripts/ac-task-matrix.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-022: deterministic renderer producing {PREFIX}-AC-Task-Matrix.md — a table mapping every
+// Requirements Acceptance Criterion to the Work Breakdown task(s)/phase(s) that cover it. No new
+// data, no new validation: every fact here is already computed and enforced by wb-validate.js's
+// checks 19-21 (checkAcCoverage, wb-graph-checks.js). This script never re-validates; it assumes
+// its inputs already passed those checks and only renders what they already guarantee.
+
+const fs = require('fs')
+const path = require('path')
+const { loadWorkBreakdown } = require('./wbs-assembler')
+const { parseAcTable } = require('./wb-graph-checks')
+const { parseFileInventoryEntries } = require('./tech-spec-graph-checks')
+
+function computeCoverage(wb, acMap) {
+  // taskPhase mirrors checkAcCoverage's own seenTaskIds pattern — not read by this function's
+  // own return value, kept available for any future lookup that needs "which phase owns task X"
+  // directly instead of iterating coverage's per-AC sets.
+  const taskPhase = new Map()
+  for (const phase of wb.phases) for (const task of phase.tasks) taskPhase.set(task.id, phase.id)
+
+  const coverage = new Map([...acMap.keys()].map(acId => [acId, { taskIds: new Set(), phaseIds: new Set() }]))
+  for (const phase of wb.phases) {
+    for (const task of phase.tasks) {
+      for (const acId of (task.acceptanceCriteria || [])) {
+        if (!coverage.has(acId)) continue // AC_NOT_FOUND is wb-validate.js's job, not this script's
+        coverage.get(acId).taskIds.add(task.id)
+        coverage.get(acId).phaseIds.add(phase.id)
+      }
+    }
+  }
+  return coverage
+}
+
+// FTR-023: acId -> Set<filePath>, built from Tech-Spec §9 File Inventory "Addresses" cells.
+function computeTechSpecCoverage(entries, acMap) {
+  const coverage = new Map([...acMap.keys()].map(acId => [acId, new Set()]))
+  for (const entry of entries) {
+    for (const acId of entry.acIds) {
+      if (coverage.has(acId)) coverage.get(acId).add(entry.filePath)
+    }
+  }
+  return coverage
+}
+
+function renderMatrix(prefix, acMap, coverage, techSpecCoverage = new Map()) {
+  const rows = [...acMap.entries()].map(([acId, ac]) => {
+    const relatedUc = ac.unscoped ? 'All UCs' : ac.relatedUCs.join(', ')
+    const cov = coverage.get(acId)
+    const taskIds = [...cov.taskIds].join(', ') || '—'
+    const phaseIds = [...cov.phaseIds].join(', ') || '—'
+    const techSpecFiles = [...(techSpecCoverage.get(acId) || [])].join(', ') || '—'
+    return `| ${acId} | ${ac.criterion} | ${ac.priority} | ${relatedUc} | ${techSpecFiles} | ${taskIds} | ${phaseIds} |`
+  })
+  return `# AC ↔ Task Traceability Matrix — ${prefix}\n\n` +
+    '| AC ID | Criterion | Priority | Related UC | Addressed by Tech-Spec File(s) | Covering Task(s) | Covering Phase(s) |\n' +
+    '|---|---|---|---|---|---|---|\n' +
+    rows.join('\n') + '\n\n' +
+    '> **Legend:** **AC ID** — unique identifier from the Requirements Acceptance Criteria ' +
+    'table. **Criterion** — the testable Given/When/Then statement, copied verbatim. ' +
+    '**Priority** — MoSCoW; every `Must` row is guaranteed non-empty in **Covering Task(s)** by ' +
+    'wb-validate.js check 21 before this file is ever generated. **Related UC** — which Use ' +
+    'Case(s) this AC belongs to, or `All UCs`. **Addressed by Tech-Spec File(s)** — every ' +
+    'Tech-Spec file whose `Addresses` column cites this AC, comma-separated, or `—` if none. ' +
+    '**Covering Task(s)** — every Work Breakdown task whose `acceptanceCriteria` cites this AC, ' +
+    'comma-separated, or `—` if none. **Covering Phase(s)** — the distinct phase(s) those tasks ' +
+    'belong to, comma-separated, or `—` if none.\n'
+}
+
+if (require.main === module) {
+  const [wbsPath, requirementsPath, techSpecPath, prefix] = process.argv.slice(2)
+  if (!wbsPath || !requirementsPath || !techSpecPath || !prefix) {
+    process.stderr.write('Usage: node ac-task-matrix.js <wbs-path> <requirements-path> <tech-spec-path> <prefix>\n')
+    process.exit(1)
+  }
+  const wb = loadWorkBreakdown(path.resolve(wbsPath))
+  const acMap = parseAcTable(path.resolve(requirementsPath))
+  const coverage = computeCoverage(wb, acMap)
+  const techSpecEntries = parseFileInventoryEntries(fs.readFileSync(path.resolve(techSpecPath), 'utf8'))
+  const techSpecCoverage = computeTechSpecCoverage(techSpecEntries, acMap)
+  const outPath = path.join(path.dirname(path.resolve(requirementsPath)), `${prefix}-AC-Task-Matrix.md`)
+  fs.writeFileSync(outPath, renderMatrix(prefix, acMap, coverage, techSpecCoverage))
+  console.log(JSON.stringify({ outputPath: outPath }))
+}
+
+module.exports = { computeCoverage, renderMatrix, computeTechSpecCoverage }

package/src/claude/scripts/assemble-docs.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-025: on-demand assembly of the split Requirements/Tech-Spec/Work-Breakdown sources into
+// single-file views. Runs as a plain Node CLI outside the sandboxed workflow runtime, so it can
+// `require()` req-assembler.js/tech-spec-assembler.js directly (no subprocess round-trip needed)
+// — it shells out only to wb-render.js, which is CLI-only (writes its own two output files and
+// exits, no exported function to call in-process). This script never runs automatically as part
+// of generation; it is the explicit, user-triggered alternative to that.
+
+const fs = require('fs')
+const path = require('path')
+const { execFileSync } = require('child_process')
+const { loadRequirements, AssemblyError: ReqAssemblyError } = require('./req-assembler')
+const { loadTechSpec, AssemblyError: SpecAssemblyError } = require('./tech-spec-assembler')
+
+// loadRequirements()/loadTechSpec() already throw a structured AssemblyError naming the exact
+// missing path when the directory doesn't exist (fs.statSync(inputPath, {throwIfNoEntry:false})
+// returning null) — no separate existence pre-check needed here, it would only duplicate what
+// the assembler already does correctly.
+function assembleReq(featureDir, prefix) {
+  const outPath = path.join(featureDir, `${prefix}-Requirements.md`)
+  fs.writeFileSync(outPath, loadRequirements(path.join(featureDir, 'req')))
+  return outPath
+}
+
+function assembleSpec(featureDir, prefix) {
+  const outPath = path.join(featureDir, `${prefix}-Tech-Spec.md`)
+  fs.writeFileSync(outPath, loadTechSpec(path.join(featureDir, 'spec')))
+  return outPath
+}
+
+function assembleWbs(featureDir, prefix) {
+  const wbsDir = path.join(featureDir, 'wbs')
+  if (!fs.existsSync(wbsDir)) throw new ReqAssemblyError(`wbs/ not found at ${wbsDir}`)
+  // wb-render.js is CLI-only (writes {prefix}-Work-Breakdown.md/.csv itself and exits) — shell
+  // out, same subprocess convention pm-phase2.js used for its own (now-removed) automatic call.
+  // No destination-dir argument needed: wb-render.js defaults it to the parent of its own
+  // <wbs-dir> argument, which is already featureDir.
+  execFileSync(process.execPath, [path.join(__dirname, 'wb-render.js'), wbsDir, prefix])
+  return [path.join(featureDir, `${prefix}-Work-Breakdown.md`), path.join(featureDir, `${prefix}-Work-Breakdown.csv`)]
+}
+
+const HANDLERS = { req: assembleReq, spec: assembleSpec, wbs: assembleWbs }
+
+if (require.main === module) {
+  const [featureDir, prefix, which = 'all'] = process.argv.slice(2)
+  if (!featureDir || !prefix) {
+    process.stderr.write('Usage: node assemble-docs.js <feature-dir> <prefix> [req|spec|wbs|all]\n')
+    process.exit(1)
+  }
+  const targets = which === 'all' ? Object.keys(HANDLERS) : [which]
+  if (!targets.every(t => HANDLERS[t])) {
+    process.stderr.write(`Unknown target "${which}" — expected req, spec, wbs, or all\n`)
+    process.exit(1)
+  }
+  try {
+    const written = targets.map(t => HANDLERS[t](path.resolve(featureDir), prefix)).flat()
+    process.stdout.write(JSON.stringify({ written }) + '\n')
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exit((err instanceof ReqAssemblyError || err instanceof SpecAssemblyError) ? 2 : 1)
+  }
+}
+
+module.exports = { assembleReq, assembleSpec, assembleWbs }