@dtlabs/ai-toolkit 0.17.4 → 0.18.0

package/src/claude/scripts/templates/gaia-dependency-graph-template.md

@@ -0,0 +1,85 @@
+<!--
+DEPENDENCY GRAPH TEMPLATE — developer-plan/dependency-graph.md
+
+STATUS (as of FTR-025): reference/design-only. No generator currently produces this file — grep
+for "dependency-graph"/"dependencyGraph" across lib/ and src/claude/ turns up nothing that writes
+it. Kept here, moved and renamed alongside the other six templates, for whenever the
+developer-plan/dependency-graph.md concept is actually implemented; do not assume it is wired into
+any real pipeline today.
+
+Human-readable companion to developer-plan/plan.json, produced BY THE SAME GENERATOR that writes
+plan.json — never hand-authored per feature, and never a place to restate plan.json's own arrays.
+This file is pure output: nothing reads it back programmatically (unlike the wbs/ task and phase
+templates, there is no parsing contract here — delete this whole comment block in a generated
+instance, there is nothing downstream to keep honest).
+
+Structure, in this fixed order: (1) a one-line pointer note, (2) the Mermaid dependency graph —
+the ONLY data visualization this file keeps, because a diagram is a genuinely different
+representation of plan.json's `readyQueue[].dependsOn`, not the same facts reformatted as another
+table, (3) a fixed "Sequence and waves" section that explicitly refuses to reprint
+`readyQueue`/`phaseWaves` as Markdown tables, (4) a fixed "Integrity" section. An earlier draft of
+this file DID reprint the ready-queue and phase-waves as tables and was reverted after review —
+same facts in two places drifts the moment plan.json regenerates and this file doesn't. Do not
+reintroduce those tables.
+
+Placeholders:
+  {FEATURE}      feature ID, e.g. FTR-020
+  {PHASE_ID}     a phase ID from plan.json's phases[].id
+  {TASK_ID}      a task ID from plan.json's readyQueue[].id
+  {NODE_ID}      {TASK_ID} with every hyphen removed/underscored so it's a legal Mermaid node
+                 name (Mermaid node IDs can't contain hyphens) — drop the phase prefix once the
+                 node already lives inside that phase's subgraph, drop the literal "TASK", keep
+                 it short and unique within the subgraph (e.g. US-02-TASK-BE-01 -> US02_BE01)
+  {sourceDigest} plan.json's own sourceDigest value, copied verbatim, including the "sha256:"
+                 prefix
+-->
+
+# {FEATURE} — Dependency Graph & Implementation Sequence
+
+> Human-readable companion to [`plan.json`](plan.json) — the machine-readable file is
+> authoritative; this is a rendered view of the same data, regenerated alongside it, never
+> hand-edited independently (same convention as `{PREFIX}-Work-Breakdown.md` being generated
+> from the JSON it describes — see `wb-render.js`).
+
+## Dependency graph
+
+<!--
+One `subgraph {PHASE_ID}` block per phase, in plan.json's phases[] order, listing that phase's
+own taskIds as Mermaid nodes ({NODE_ID}[{TASK_ID}]). Below every subgraph block, one
+`{FROM_NODE_ID} --> {TO_NODE_ID}` edge per (task, dependency) pair found by walking every
+readyQueue[].dependsOn entry — one edge per dependency, not one edge per task (a task with 3
+entries in dependsOn gets 3 edges). Edge order: by readyQueue[].sequence, then by the order the
+dependency appears inside that task's own dependsOn array. A task with an empty dependsOn
+contributes no edges, only its node.
+-->
+
+```mermaid
+graph TD
+  subgraph {PHASE_ID}
+    {NODE_ID}[{TASK_ID}]
+  end
+
+  {FROM_NODE_ID} --> {TO_NODE_ID}
+```
+
+## Sequence and waves
+
+The dispatch order (`readyQueue`), the per-task dependencies (`dependsOn`), and the phase
+waves (`phaseWaves`) are **not repeated here** — they already exist as structured data in
+[`plan.json`](plan.json) and reprinting them as a Markdown table would just be the same facts
+in a second place, free to drift the moment `plan.json` is regenerated and this file isn't.
+Read them straight from there; the Mermaid diagram above is the only rendering kept in this
+file, because it's a genuinely different representation (visual graph) rather than the same
+rows reformatted.
+
+## Integrity
+
+- **Source digest:** `{sourceDigest}` — computed over every file under `wbs/` (sorted by
+  relative path, each length-prefixed before hashing, same technique as
+  `lib/task-executor/plan.js`'s own `_computePlanDigest`, extended from "two byte blobs" to
+  "every file in a directory"). A re-run of the same computation against the current `wbs/`
+  must reproduce this exact value, or this plan is stale and must be regenerated before
+  implementation proceeds — mirrors `plan.js`'s existing resume-safety contract, made an
+  explicit, reviewable file instead of an internal runtime-only check.
+- Per-task and per-phase checksums in `plan.json` let a drift check point at the *specific*
+  file that changed, not just "something changed somewhere."

package/src/claude/scripts/templates/gaia-requirements-index-template.md

@@ -0,0 +1,144 @@
+<!--
+REQUIREMENTS INDEX TEMPLATE — req/index.md
+
+Canonical structure for the Requirements index in the split format (FTR-021). Holds everything
+that is NOT naturally owned by a single Use Case — i.e. everything except each Use Case's own flow
+body, which gets its own file under use-cases/{UC-ID}.md (see gaia-use-case-template.md).
+
+This is the REAL, currently-implemented 9-section contract — authoritative source:
+`src/claude/agents/gaia-generate-requirements.md`'s own "Output Structure" section, and
+`src/claude/scripts/req-skeleton-check.js`/`req-assembler.js`, which require exactly these 9
+numbered top-level `## N. ` headings, in order, to exist. An earlier FTR-020 exploratory draft of
+this template used a different 7-section numbering (no "UI Requirements" or "Open Questions" as
+their own sections) that was never what Requirements generation actually shipped — this file
+reflects the real, current format, not that earlier draft.
+
+SPLITTING PRINCIPLE (apply this test to any new section before deciding where it goes): does this
+content belong to exactly one UC, or does it reference/apply to several? A Business Rule that
+applies to 3 UCs, a Data Requirement describing a schema used by the whole feature, an NFR that
+constrains the feature as a whole — none of these are owned by one UC any more than a shared setup
+module is owned by one Work Breakdown task. Only split out content that is genuinely per-item;
+everything cross-cutting stays here, in one place.
+
+EVERY table in this document (and in every use-case file) MUST be followed immediately by a
+one-line legend (blockquote) explaining each column.
+
+Fill in every placeholder (angle brackets) and delete every HTML comment block (including this
+one) before treating the file as finished.
+-->
+
+# {PREFIX} — Functional Requirements (Index)
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+<prose: brief description of what this requirements document covers>
+
+### 1.2 Scope
+
+<prose: what is in scope and out of scope>
+
+### 1.3 Actors
+
+| Actor | Description |
+|-------|-------------|
+| <actor> | <description> |
+
+## 2. Use Cases
+
+<!-- One row per UC. This table is the single place that lists every UC that exists — the
+     use-cases/ directory listing must match it exactly. Title here is a short label, NOT the
+     full flow description — that's in the UC's own file (FTR-021: a separate call per UC fills
+     in each row's full detail after this skeleton is accepted). -->
+
+| UC ID | Title | Actor | Priority | File |
+|-------|-------|-------|----------|------|
+| UC-{NN} | <short title> | <actor(s)> | <Must \| Should \| Could> | [use-cases/UC-{NN}.md](use-cases/UC-{NN}.md) |
+
+> **Legend:** **UC ID** — unique identifier, referenced from Business Rules' `Applies to` and
+> Acceptance Criteria's `Related UC` columns. **Title** — short label; full flow is in the linked
+> file. **Actor** — who/what initiates or participates. **Priority** — MoSCoW; drives downstream
+> Must-coverage checks. **File** — this UC's own detail file.
+
+## 3. Business Rules
+
+| ID | Rule | Applies to |
+|----|------|-----------|
+| BR-{NN} | <rule statement> | <UC-ID, UC-ID, ... \| All UCs> |
+
+> **Legend:** **ID** — unique identifier. **Rule** — the constraint itself. **Applies to** —
+> which UC(s) this rule constrains, or "All UCs" if universal.
+
+## 4. Data Requirements
+
+### 4.1 Entities
+
+<!-- For each entity: fields, types, constraints, relationships. -->
+
+<prose>
+
+### 4.2 Validation Rules
+
+| Field | Rule |
+|-------|------|
+| <field> | <rule> |
+
+## 5. Non-Functional Requirements
+
+| ID | Category | Requirement |
+|----|----------|-------------|
+| NFR-{NN} | <Security \| Performance \| Usability \| ...> | <requirement statement> |
+
+## 6. UI Requirements
+
+<!-- N/A — internal/technical feature; no UI surface is introduced or changed, if that's true for
+     this feature — otherwise fill in both subsections below. -->
+
+### 6.1 Pages / Screens
+
+<!-- For each page: purpose, layout description, components, interactions. -->
+
+<prose>
+
+### 6.2 Navigation Flow
+
+<prose: how pages connect and how the user moves between them>
+
+## 7. Acceptance Criteria
+
+<!--
+Column contract: first three columns MUST be exactly "ID", "Criterion", "Related UC" in that
+order — parsed as-is by wb-graph-checks.js's parseAcTable (do not reinvent the column format).
+"Related UC" must be a single UC-ID, a comma-separated list, or the literal "All UCs".
+-->
+
+| ID | Criterion | Related UC | Priority |
+|----|-----------|-------------|----------|
+| AC-{NN} | <Given/When/Then or plain testable statement> | <UC-ID \| UC-ID, UC-ID \| All UCs> | <Must \| Should \| Could> |
+
+> **Legend:** **ID** — unique identifier; the anchor used across the whole
+> feature.md↔req↔spec↔Work-Breakdown traceability chain. **Criterion** — a testable Given/When/Then
+> statement. **Related UC** — which UC(s) this AC belongs to, or "All UCs"; machine-parsed by
+> `wb-graph-checks.js`'s `parseAcTable`, not just descriptive. **Priority** — MoSCoW; every Must AC
+> must be covered by ≥1 WB task.
+
+## 8. Dependencies and Assumptions
+
+<!-- External prerequisites, prior features this one builds on, fixed constraints, and anything
+     that must be resolved before Gate 1. -->
+
+<prose / bullet list>
+
+## 9. Open Questions
+
+| # | Question | Impact | Suggested resolution |
+|---|----------|--------|---------------------|
+| <N> | <question> | <impact if unresolved> | <suggested resolution, or "open — deferred"> |
+
+<!--
+PARSING CONTRACT — req-skeleton-check.js/req-assembler.js require exactly these 9 numbered
+`## N. ` headings, in order, to exist (assertCompleteSections's truncation guard in pm-phase1.js
+checks the same 9 headings). Section 2's table is the index into use-cases/{UC-ID}.md — never
+write a UC's flow body inline here.
+-->

package/src/claude/scripts/templates/gaia-task-template.md

@@ -0,0 +1,92 @@
+<!--
+TASK DETAIL TEMPLATE — wbs/tasks/{TASK_ID}.md
+
+Canonical structure for a task file in the FTR-020 split Work Breakdown format. Every task file
+has exactly three parts, in this order: (1) the field block, (2) Implementation notes,
+(3) Verification commands. Fill in every placeholder below (angle brackets) and delete every
+HTML comment block (including this one) before treating the file as finished. Do not add, remove,
+or reorder the 14 fields — they are parsed positionally as the contiguous run immediately after
+the heading (see "Parsing contract" at the bottom of this file).
+-->
+<a id="task-{TASK_ID}"></a>
+### {TASK_ID}
+
+- **Task ID:** {TASK_ID}
+- **Title:** <Short, specific, action-oriented. Not a restatement of the outcome.>
+- **Outcome:** <The ONE observable thing that exists/changed after this task is done — one
+  factual, verifiable sentence. If you need "and" to describe it, the task is probably not
+  atomic — split it (see Atomicity Contract in gaia-generate-work-breakdown.md).>
+- **Domain:** <one of: BE | FE | DB | DevOps | INFRA | TEST>
+- **Agent type:** <one of: developer-backend | developer-frontend | developer-testing | review-solution>
+- **Dependencies:** <comma-separated task IDs this task's work requires to exist first, or `—` if none>
+- **Acceptance criteria:** <comma-separated AC IDs from Requirements that this task covers, scoped
+  to this task's own phase — or `—` if none>
+- **Estimate — agent minutes:** <integer. Target ≤15 (no flag); 16–20 acceptable (no flag);
+  21–30 is a non-blocking warning — justify in Grouping rationale below; >30 is rejected, split
+  the task instead.>
+- **Estimate — tokens:** <integer, rough order of magnitude for the agent invocation>
+- **Output count:** <integer ≥1. Almost always 1 — see Atomicity Contract. >1 requires a non-null
+  Grouping rationale below.>
+- **Grouping rationale:** <required (non-`—`) only when Output count >1 or the estimate is in the
+  21–30 min warning band; otherwise `—`>
+- **Commit type:** <conventional-commit type: feat | fix | refactor | test | chore | docs | ...>
+- **Commit scope:** <optional conventional-commit scope, or `—`>
+- **Commit subject:** <imperative, concise, no trailing period — the renderer prepends
+  `type(scope): ` automatically, do not include it here>
+
+**Implementation notes:**
+
+<!--
+This is the part that makes a task file self-sufficient: someone (human or agent) reading ONLY
+this file — not the whole Tech-Spec — should know exactly what to do and how.
+
+Write:
+- If this task RELOCATES or MODIFIES existing code: name the exact file(s) and, if you know
+  them, the exact current line ranges to copy from or change. Show a before/after snippet, not
+  just a description of the change.
+- If this task CREATES something new: give its real signature(s) (function names, parameters,
+  return shape) and the actual algorithm as pseudocode or real code — not just a description of
+  what it should do.
+- If this task is a TEST: show at least one concrete `test()`/`describe()` block with real
+  assertions against the real function/CLI being tested, not a prose list of "things to check".
+- Length target: not 10 lines (too thin to act on without re-deriving the design yourself), not
+  10 pages (defeats the point of a small, bounded, independently generated task). A few concrete
+  snippets plus the reasoning that connects them is usually right.
+- It is fine — often good — to include a literal example of this exact task-file format inside a
+  fenced code block (e.g. to show another agent's expected output shape). If you do, see the
+  parsing-contract warning at the bottom of this file: it is specifically about this situation.
+-->
+
+<prose + pseudocode/code here>
+
+**Verification commands:**
+
+<!--
+One or more real shell commands (use AGENTS.md's actual build/test commands for this project)
+that verify this task's output. Must be non-empty. Each command gets its own fenced block,
+preserved byte-for-byte verbatim — never edited, escaped, or "cleaned up" by any tool that
+touches this file; this is what lets a command contain `|`, backticks, or other shell syntax
+safely.
+-->
+
+```
+<command>
+```
+
+<!--
+PARSING CONTRACT (do not delete this section from the real template file; delete only from a
+filled-in task instance) — read by wbs-assembler.js's parseTaskDetailBlock:
+1. Field values are read from the CONTIGUOUS RUN of `- **Label:** value` lines starting
+   immediately after the `### {TASK_ID}` heading. Scanning STOPS at the first line that is not
+   in that shape — so an example block further down in Implementation notes that happens to
+   contain `- **Task ID:** ...`-shaped lines is never mistaken for the real fields. (A real bug,
+   found and fixed during this feature's own definition — see US-03-TASK-INFRA-01.md and
+   Tech-Spec §4.)
+2. The verification commands are the fenced block(s) after the LAST occurrence of
+   "**Verification commands:**" in the file — not the first — for the same reason: an
+   illustrative example earlier in the file must never be mistaken for the real section.
+3. Conclusion for anyone writing Implementation notes: you may safely show an example of this
+   format inside your own notes. You may NOT rely on your example being the last occurrence of
+   "**Verification commands:**" in the file — the real one (at the bottom) always is, by
+   construction, as long as you don't add a second real verification section.
+-->

package/src/claude/scripts/templates/gaia-tech-spec-index-template.md

@@ -0,0 +1,137 @@
+<!--
+TECH-SPEC INDEX TEMPLATE — spec/index.md
+
+Canonical structure for the Tech-Spec index (skeleton) in the split format (FTR-024). Holds every
+section genuinely feature-wide, PLUS the Section 9 Components index table — one row per file the
+feature creates or modifies. Each component's own Backend/Frontend/External-Integration/Testing
+detail is produced separately, one call per component (see gaia-component-template.md); this
+skeleton never contains that per-component content inline.
+
+This is the REAL, currently-implemented 12-section contract — authoritative source:
+`src/claude/agents/gaia-generate-tech-spec.md`'s own "Output Structure" section, and
+`src/claude/scripts/tech-spec-assembler.js`/`tech-spec-graph-checks.js`. An earlier FTR-020
+exploratory draft of this template used a completely different 6-section numbering (Baseline /
+Resolution of Open Questions / Components index / Traceability / feature-wide guarantees / Shared
+test fixtures) that predates the Tech-Spec split entirely and was never what generation actually
+shipped — this file reflects the real, current 12-section format, not that earlier draft.
+
+Fill in every placeholder (angle brackets) and delete every HTML comment block (including this
+one) before treating the file as finished.
+-->
+
+# Technical Specification — {Feature Title}
+
+## Document Info
+| Field | Value |
+|-------|-------|
+| Feature | {PREFIX and title} |
+| Version | 1.0 |
+| Date | {today} |
+| Status | Draft |
+
+## 1. Overview
+
+<prose: brief technical summary — what is being built, which systems are affected>
+
+## 2. Architecture
+
+### 2.1 System Context
+
+<prose: where this feature sits in the overall architecture>
+
+### 2.2 Component Diagram
+
+<!-- Text-based diagram showing components and their interactions. -->
+
+```
+[Component A] --(protocol)--> [Component B]
+```
+
+### 2.3 Sequence Diagrams
+
+<!-- For key flows, show the sequence of calls between components (text-based or Mermaid). -->
+
+## 3. Backend
+
+_Per-component detail — see Section 9's Components table and each component's own design file
+(generated separately, one call per component). Do not write any content here._
+
+## 4. Frontend
+
+_Per-component detail — see Section 9's Components table and each component's own design file
+(generated separately, one call per component). Do not write any content here._
+
+## 5. External Integrations
+
+_Per-component detail — see Section 9's Components table and each component's own design file
+(generated separately, one call per component). Do not write any content here._
+
+## 6. Security Considerations
+
+<!-- Authentication & authorization requirements, input validation boundaries, sensitive data
+     handling, CORS implications (if applicable). -->
+
+<prose / bullet list>
+
+## 7. Database Changes
+
+<!-- New tables/columns, indexes recommended, seed data, migration strategy. -->
+
+<prose / bullet list>
+
+## 8. Configuration
+
+<!-- New environment variables, app settings changes, feature flags (if applicable). -->
+
+<prose / bullet list>
+
+## 9. File Inventory
+
+Complete list of files to create or modify:
+
+### New files
+| Path | Purpose | Addresses | Domain | Spec |
+|------|---------|-----------|--------|------|
+| {real file path} | {purpose} | {AC-IDs, comma-separated, or —} | {BE \| FE \| DB \| DevOps \| INFRA \| TEST} | [components/{fileSlug}](components/{fileSlug}) |
+
+### Modified files
+| Path | Change description | Addresses | Domain | Spec |
+|------|-------------------|-----------|--------|------|
+| {real file path} | {change description} | {AC-IDs, comma-separated, or —} | {BE \| FE \| DB \| DevOps \| INFRA \| TEST} | [components/{fileSlug}](components/{fileSlug}) |
+
+<!--
+Column order matters: `Addresses` MUST stay the 3rd column (immediately after
+`Purpose`/`Change description`) — this is the exact position `tech-spec-graph-checks.js`'s
+existing, positional parser reads from, and it reads positionally, not by header name. `Domain`
+and `Spec` are new TRAILING columns, safely ignored by that parser. Do not reorder them. `Domain`
+is the same enum Work Breakdown tasks already use. `Spec` is a provisional link to this file's own
+design file — `components/{the file's own basename, with its extension kept}.md` — the host may
+rewrite this link if two files share a basename, so treat it as provisional, not final.
+-->
+
+## 10. Testing Strategy
+
+_Per-component detail — see each component's own design file's own Tests section (generated
+separately, one call per component). Do not write any content here._
+
+## 11. Implementation Order
+
+<!-- Numbered, dependency-aware sequence of components/tasks. -->
+
+1. {component/task} — depends on: nothing
+2. {component/task} — depends on: 1
+
+## 12. Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|-----------|
+| {risk} | {impact} | {mitigation} |
+
+<!--
+PARSING CONTRACT — tech-spec-assembler.js's tech-spec-graph-checks.js's parsers require exactly
+these 12 numbered `## N. ` headings, in order, to exist (assertCompleteSections's truncation guard
+in pm-phase1.js checks the same 12 headings), plus Section 9's two subtables in the exact column
+order above. Sections 3/4/5/10 must keep their heading even though their real content is deferred
+to per-component generation — the assembler's spliceSectionBody requires the heading to already
+exist to splice into.
+-->

package/src/claude/scripts/templates/gaia-use-case-template.md

@@ -0,0 +1,56 @@
+<!--
+USE CASE TEMPLATE — req/use-cases/{UC-ID}.md
+
+Canonical structure for one Use Case file in the split Requirements format. Every UC file has
+exactly three parts, in this order: (1) the heading + field table, (2) the flow/description
+body, (3) cross-references back to the index (Business Rules and Acceptance Criteria that apply
+to this UC). Fill in every placeholder (angle brackets) and delete every HTML comment block
+(including this one) before treating the file as finished.
+-->
+
+### {UC-ID}: <Title — short, matches the Title column in index.md's Use Cases table exactly>
+
+| Field | Value |
+|---|---|
+| Actor | <who/what initiates or participates in this use case> |
+| Priority | <Must \| Should \| Could> |
+| Preconditions | <what must already be true before this use case can start> |
+| Trigger | <the event that starts this use case> |
+
+> **Legend:** **Actor** — who/what initiates or participates in this use case. **Priority** —
+> MoSCoW (Must/Should/Could). **Preconditions** — what must already be true before this use case
+> can start. **Trigger** — the event that starts it.
+
+<!--
+The body: describe the actual flow. For a technical/internal feature (most of this toolkit's
+own features), this is usually a numbered or prose description of what happens, in enough detail
+that someone reading ONLY this file — not the whole Requirements document — understands exactly
+what this use case requires, without having to infer it from the Tech-Spec or the Work Breakdown.
+Length target: proportional to the use case's real complexity, not padded — a one-paragraph UC is
+fine if that's genuinely all there is to say; a multi-step UC can run longer, but if it's
+sprawling across unrelated concerns, that's a sign it should be two UCs, not one file trying to
+cover both (same atomicity instinct as a Work Breakdown task, just at a coarser grain).
+-->
+
+<prose describing the flow>
+
+**Related Business Rules:** <comma-separated BR-IDs that apply to this UC, derived from the
+`Applies to` column in [index.md](../index.md#3-business-rules) — include any `All UCs` rule
+too, or `—` if none>
+
+**Related Acceptance Criteria:** <comma-separated AC-IDs whose `Related UC` column includes this
+UC (always include any `All UCs` AC too), derived from
+[index.md](../index.md#6-acceptance-criteria). `—` is only valid if index.md's AC table
+genuinely has no AC referencing this UC yet — treat that as a flag worth double-checking, not a
+normal/expected state: per the feature.md<->req<->spec bidirectional traceability check (see
+[index.md](../index.md#traceability)), every UC should normally trace to at least one AC, or
+nothing downstream can verify this UC's Work Breakdown tasks actually satisfy it.
+
+<!--
+Both cross-reference lines above are DERIVED data — they must match what index.md's tables
+actually say. Don't invent a BR/AC reference here that doesn't exist in the index, and don't let
+this line go stale if the index changes later (whatever generates/maintains this file is
+responsible for keeping it in sync — this is the same "which side is authoritative" question the
+Work Breakdown's skeleton/detail split had to answer: here, index.md's tables are authoritative,
+this line is a convenience projection of them, not a second source of truth).
+-->

package/src/claude/scripts/templates/gaia-user-story-template.md

@@ -0,0 +1,61 @@
+<!--
+PHASE / USER-STORY DETAIL TEMPLATE — wbs/user-stories/{PHASE_ID}.md
+
+Canonical structure for a phase file (the INFRA phase and every US-NN phase both use this same
+template — INFRA is not a user story, but lives in the same directory and format; see "Type"
+below). Every phase file has exactly four parts, in this order: (1) the field block,
+(2) Context, (3) Tasks in this phase, (4) Depends on phases. Fill in every placeholder (angle
+brackets) and delete every HTML comment block (including this one) before treating the file as
+finished.
+-->
+<a id="phase-{PHASE_ID}"></a>
+### {PHASE_ID}
+
+- **Phase ID:** {PHASE_ID}
+- **Type:** <infrastructure | user-story>
+- **Source UC:** <comma-separated UC-ID(s) this phase's tasks realize, or `—` for a phase with no
+  single originating UC (e.g. shared infrastructure). Restated here for human readability from
+  `index.json`'s own `sourceUC` array, which is authoritative — this line is a display-only
+  projection, not parsed back out by `parsePhaseDetailBlock` (same convention as `Phase ID`/
+  `Type` above, which are also restated but not re-extracted). Can be MORE than one UC (an
+  orchestration phase) — don't force a single value if that's not true; see Tech-Spec OQ-05.>
+- **Title:** <For `type: user-story`, use the standard form: "As a <role>, I want <capability>,
+  so that <benefit>" — derived directly from this phase's source Use Case(s). For `type:
+  infrastructure` (the one INFRA phase), there is no user-story grammar — use a short descriptive
+  label of what shared setup this phase provides.>
+- **Commit type:** <conventional-commit type, usually `feat`>
+- **Commit scope:** <optional, or `—`>
+- **Commit subject:** <imperative, concise — e.g. "implement {PHASE_ID} <short description>" —
+  the renderer prepends `type(scope): ` automatically, do not include it here>
+
+**Context:**
+
+<!--
+2–4 sentences, no more. Answer: why does this phase exist (which Use Case / need does it map
+to)? How do its own tasks relate to each other? Is there a dependency or sequencing reason other
+phases or tasks need to know about before opening this phase's individual task files? Do NOT
+restate the Title — add information the title doesn't already give.
+-->
+
+<prose>
+
+**Tasks in this phase:**
+
+<!--
+One bullet per task, in the same order as `index.json`'s `taskIds` for this phase. The summary is
+a few words of what the task DOES, not a copy of its full Title (that's one click away via the
+task ID link/filename).
+-->
+
+- `{TASK_ID}` — <one-line summary>
+
+**Depends on phases:** <comma-separated phase IDs this phase's tasks have a `dependsOn` reference
+into, or `none` if this phase has no cross-phase dependency>
+
+<!--
+PARSING CONTRACT — read by wbs-assembler.js's parsePhaseDetailBlock: field values are read from
+the CONTIGUOUS RUN of `- **Label:** value` lines starting immediately after the `### {PHASE_ID}`
+heading, stopping at the first non-matching line. Same rule and same rationale as the task
+template — see task-template.md's parsing-contract note for the full explanation and the real
+bug it fixes.
+-->