@deftai/directive-content 0.108.0 → 0.109.0

package/packs/strategies/strategies-pack-0.1.json

@@ -76,12 +76,12 @@
     {
       "id": "interview",
       "title": "Interview Strategy",
-      "description": "The standard Deft workflow: structured interview → SPECIFICATION. This is the canonical source of truth for the interview process. All entry points (CLI via `run spec`, agent via `deft-directive-setup` Phase 3, and `templates/make-spec.md`) MUST follow this strategy.",
+      "description": "The standard Deft workflow: structured interview → SPECIFICATION. This is the canonical source of truth for the interview process. All entry points (CLI via `directive` / setup Phase 3, agent via `deft-directive-setup` Phase 3, and `templates/make-spec.md`) MUST follow this strategy.",
       "triggers": [
         "interview"
       ],
       "path": "strategies/interview.md",
-      "body": "# Interview Strategy\n\nThe standard Deft workflow: structured interview → SPECIFICATION. This is the\ncanonical source of truth for the interview process. All entry points (CLI via\n`run spec`, agent via `deft-directive-setup` Phase 3, and `templates/make-spec.md`) MUST\nfollow this strategy.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/discuss.md](./discuss.md) | [strategies/yolo.md](./yolo.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [core/glossary.md](../glossary.md)\n\n## When to Use\n\n- ! Default strategy for all new projects\n- ~ Projects with unclear or evolving requirements\n- ~ When stakeholder alignment is needed before implementation\n- ? Skip to SPECIFICATION phase if requirements are already fully documented\n\n---\n\n## Chaining Gate\n\nBefore spec generation, offer the user a chance to run preparatory strategies\nor switch to a different spec-generating strategy. This gate is the single\norchestration point for strategy composition.\n\n! The chaining gate MUST always be shown — even when the interview strategy is\ninvoked directly with no prior strategy.\n! The chaining gate is a **blocking question**. The AI MUST present the options\nand wait for the user to choose before proceeding.\n⊗ Skip the chaining gate or proceed to the sizing gate without presenting it.\n\n### When It Appears\n\n- ! Before the [Sizing Gate](#sizing-gate) on every entry to the interview strategy\n- ! After each completed preparatory strategy (recursive — the gate reappears)\n- ! After the [Acceptance Gate](#acceptance-gate) when the user chooses \"Revise\" or \"Switch\"\n\n### Brownfield Detector\n\nBefore rendering menu options, classify the repo (align with setup Phase 3):\n\n- **Brownfield** when **either**:\n  - `PROJECT-DEFINITION` exists under `./xbrief/` or legacy `./vbrief/` (`PROJECT-DEFINITION.xbrief.json` or `PROJECT-DEFINITION.vbrief.json`), **or**\n  - any lifecycle folder (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/` under `xbrief/` or legacy `vbrief/`) has scope records\n- **Greenfield** otherwise\n\n! The detector MUST run on every Chaining Gate presentation.\n⊗ Offer only the greenfield-framed **Proceed to specification** default on a brownfield repo.\n⊗ Treat brownfield as a full create path without an explicit Replace/scrap confirm.\n\n### Options\n\n! Numbered Chaining Gate menus (greenfield and brownfield examples below) MUST end with `Discuss` and `Back` as the final two options per [deterministic-questions.md](../contracts/deterministic-questions.md).\n\nPresent groups sourced from the `Type` column in\n[strategies/README.md](./README.md#strategy-types). The **default path** depends\non the brownfield detector:\n\n**Default path (greenfield):**\n1. **Proceed to specification** (default) — continue to the [Sizing Gate](#sizing-gate) for a full create path\n\n**Default path (brownfield) — create-vs-update menu:**\n1. **Add scope to this project** (default) — load existing project identity + preparatory artifacts; **skip** the greenfield \"what are we building?\" interview; gather only the new scope; emit **one** proposed scope record; apply the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) on write\n2. **Update project definition** — run a **delta** interview against existing identity; apply the [Spec-Generating Guard](./artifact-guards.md#spec-generating-guard-full); **merge** narratives (prefer enrich/merge when the user declines replace)\n3. **Replace specification (scrap)** — full recreate equivalent to greenfield Proceed; **only** after explicit affirmative (`yes` / `confirmed`); vague replies (`proceed`, `ok`, `go ahead`) are **not** acceptance\n   - ! On confirmed scrap, continue to the [Sizing Gate](#sizing-gate) as a full create path\n   - ⊗ Auto-delete PROJECT-DEFINITION without scrap confirm\n   - ⊗ Rename Proceed to \"Update\" without changing behavior\n\n**Preparatory strategies** (type: `preparatory` — loops back to this gate on completion):\n- Research — investigate the domain, find libraries, identify pitfalls\n- Discuss — lock key decisions using Feynman technique\n- Probe — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n- Map — analyze existing codebase conventions\n\n~ Some preparatory strategies (currently map) also support standalone invocation\nvia `/deft:run:<name>` without entering the interview flow. When invoked standalone,\nthey present their own completion options instead of returning to this gate.\nSee `strategies/map.md` for standalone behavior.\n\n**Switch spec-generating strategy** (type: `spec-generating` — replaces current pipeline):\n- Yolo — auto-pilot, Johnbot picks all answers\n- SpecKit — formal spec process with story readiness before implementation\n\n### Run Count Annotations\n\n- ! Previously-run strategies MUST display with a run count (e.g., `Research (ran 1×)`)\n- ! No strategy is ever removed from the gate — users can re-run any strategy\n- ! Run counts are read from `completedStrategies` in\n  [`./xbrief/plan.xbrief.json`](../vbrief/vbrief.md#strategy-chaining-fields)\n\n### State Tracking\n\n- ! On completion of a preparatory strategy, update `completedStrategies` in\n  `./xbrief/plan.xbrief.json`: increment `runCount`, append artifact paths\n- ! Append all new artifact paths to the flat `artifacts` array\n- ! The next strategy and eventual spec generation MUST load all artifacts\n  listed in `plan.xbrief.json`\n- ! On brownfield **Add scope** or **Update project definition**, load existing\n  PROJECT-DEFINITION identity and preparatory artifacts before asking questions\n\n### Write Guards (interview)\n\n! Interview is a **spec-generating** strategy and MUST follow\n[artifact-guards.md](./artifact-guards.md) before emission (Light or Full path).\n\n- ! **Before writing** scope records to `proposed/`: [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) (xbrief-first: `./xbrief/proposed/`, else legacy `./vbrief/proposed/`)\n- ! **Before writing** or updating `PROJECT-DEFINITION`: [Spec-Generating Guard](./artifact-guards.md#spec-generating-guard-full) against the **single live** identity file only — `./xbrief/PROJECT-DEFINITION.xbrief.json` when present (or after `deft migrate:xbrief`); else, until migrated, the existing legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`. ⊗ Dual-write both roots\n- ! Prefer enrich/merge when the user declines replace\n- ⊗ Silently overwrite PROJECT-DEFINITION or same-slug proposed scopes\n- ⊗ Guard only the legacy `vbrief/` path while an `xbrief/` PROJECT-DEFINITION is the live identity\n- ⊗ Rely on write-time guards alone without the brownfield Chaining Gate menu above\n\nSurface this obligation **inside `interview.md`** so agents that load only this\nfile still hit the guards (#2925; incomplete closeout of #82/#387).\n\n### Example Prompt\n\n**Greenfield:**\n\n```\nReady to generate the specification. Before we proceed, would you like to:\n\n1. Proceed to specification (default)\n\n--- Preparatory (loops back) ---\n2. Run a research phase — investigate the domain, find libraries, identify pitfalls\n3. Run a discuss phase — lock key decisions using Feynman technique\n4. Run a probe phase — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n5. Run a map phase — analyze existing codebase conventions\n\n--- Switch strategy ---\n6. Switch to yolo — auto-pilot picks all answers\n7. Switch to speckit — formal spec process with story readiness before implementation\n8. Other (specify)\n9. Discuss\n10. Back\n```\n\n**Brownfield:**\n\n```\nThis repo already has a project definition and/or scopes. Before we proceed:\n\n1. Add scope to this project (default) — keep identity; add one new proposed scope\n2. Update project definition — delta interview; merge narratives (Spec-Generating Guard)\n3. Replace specification (scrap) — requires explicit yes/confirmed; full recreate\n\n--- Preparatory (loops back) ---\n4. Run a research phase — investigate the domain, find libraries, identify pitfalls\n5. Run a discuss phase — lock key decisions using Feynman technique\n6. Run a probe phase — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n7. Run a map phase — analyze existing codebase conventions\n\n--- Switch strategy ---\n8. Switch to yolo — auto-pilot picks all answers\n9. Switch to speckit — formal spec process with story readiness before implementation\n10. Other (specify)\n11. Discuss\n12. Back\n```\n\n---\n\n## Sizing Gate\n\nBefore the interview begins, determine project complexity to select the\nappropriate path. The gate runs once, immediately after hearing what the user\nwants to build.\n\n! The sizing gate is a **blocking question**. The AI MUST propose a size and\nwait for the user to confirm or override before asking any interview questions.\n⊗ Combine the sizing proposal with the first interview question in the same message.\n⊗ Proceed to interview questions before the user has explicitly confirmed the path.\n\n### Sizing Signals\n\nThe AI SHOULD propose a size based on these signals; the user confirms or overrides:\n\n- Number of features (≤5 → Light, >5 → Full)\n- Number of components/services (1–2 → Light, 3+ → Full)\n- Expected duration (days → Light, weeks/months → Full)\n- Team/agent count (solo → Light, multi-agent/swarm → Full)\n- Integration complexity (standalone → Light, external APIs/auth/DB → Full)\n\n### PROJECT-DEFINITION.vbrief.json Override\n\n`PROJECT-DEFINITION.vbrief.json` narratives ? declare `\"Process\": \"Light\"` or `\"Process\": \"Full\"` to skip the\ngate entirely. `PROJECT.md` (deprecated) may also carry this field. If the field is absent or empty, the AI MUST ask.\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n    subgraph interview [\"Interview Strategy\"]\n        G{\"⚖️ Sizing Gate\"}\n        I_L[\"💬 Interview<br/><i>Light path</i>\"]\n        I_F[\"💬 Interview<br/><i>Full path</i>\"]\n        P[\"📄 PRD<br/><i>What to build</i>\"]\n        S[\"📋 SPECIFICATION<br/><i>How to build it</i>\"]\n    end\n\n    G -->|\"Light\"| I_L\n    G -->|\"Full\"| I_F\n    I_L -->|\"Ambiguity resolved\"| S\n    I_F -->|\"Ambiguity resolved\"| P\n    P -->|\"Approved\"| S\n    S -->|\"Ready\"| IMPL[\"🔨 Implementation\"]\n\n    style G fill:#f0abfc,stroke:#a21caf,color:#000\n    style I_L fill:#c4b5fd,stroke:#7c3aed,color:#000\n    style I_F fill:#c4b5fd,stroke:#7c3aed,color:#000\n    style P fill:#fef08a,stroke:#ca8a04,color:#000\n    style S fill:#6ee7b7,stroke:#059669,color:#000\n    style IMPL fill:#7dd3fc,stroke:#0284c7,color:#000\n```\n\n---\n\n## Interview Rules (shared by both paths)\n\n- ~ Use Claude AskInterviewQuestion when available (emulate if not)\n- ! Ask **ONE** focused, non-trivial question per step\n- ⊗ Ask multiple questions at once or sneak in \"also\" questions\n- ~ Provide numbered answer options when appropriate\n- ! Include \"other\" option for custom/unknown responses\n- ! Indicate which option is RECOMMENDED\n- ! When making an opinionated recommendation, state the principle (1 sentence)\n- ! When done, append all questions asked and answers given to the working document\n\n### Question Areas\n\n- ! Missing decisions (language, framework, deployment)\n- ! Edge cases (errors, boundaries, failure modes)\n- ! Implementation details (architecture, patterns, libraries)\n- ! Requirements (performance, security, scalability)\n- ! UX/constraints (users, timeline, compatibility)\n- ! Tradeoffs (simplicity vs features, speed vs safety)\n\n### Transition Criteria (interview complete)\n\n- ! All major decisions have answers\n- ! Edge cases are addressed\n- ! User has approved key tradeoffs (Interview strategy) or Johnbot has chosen recommended options (Yolo strategy)\n- ~ Little ambiguity remains\n\n---\n\n## Light Path (small/medium projects)\n\nInterview → scope records (date-prefixed in proposed/) + live PROJECT-DEFINITION + rendered SPECIFICATION (v0.20 contract). Paths are **xbrief-first**: use `./xbrief/` when that root is the live project layout; else legacy `./vbrief/`.\n\n### Flow\n\n1. Sizing gate selects Light\n2. Interview (rules above)\n3. Write scope record(s) to the live lifecycle root — `./xbrief/proposed/YYYY-MM-DD-<slug>.xbrief.json` when `./xbrief/` is live; else legacy `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` — date-prefixed with `status: proposed`\n4. Run `task project:render` to create/update the **live** PROJECT-DEFINITION under the resolved layout root (`./xbrief/PROJECT-DEFINITION.xbrief.json`). Engine layout resolution requires `xbrief/` (#2112); if the repo is legacy-only `./vbrief/`, run `deft migrate:xbrief` first, then render. Ensure all five lifecycle folders exist under the live root. ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `xbrief/` is live\n5. Summarize decisions, ask user to review\n6. On approval, use `task scope:promote` (or equivalent) to move scope record(s) to `pending/` under the **same** live root with `status: pending` / `approved`\n7. Run `task project:export-spec` / `task spec:render` as appropriate (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` / `specification.xbrief.json` are legacy and are NOT written by this strategy on the v0.20 path)\n\n! **Before writing** scope records or updating `PROJECT-DEFINITION` on the Light path, follow [artifact-guards.md](./artifact-guards.md): Preparatory Guard for `proposed/` scopes; Spec-Generating Guard against the **live** identity file (xbrief-first). Prefer enrich/merge when the user declines replace.\n! ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `./xbrief/PROJECT-DEFINITION.xbrief.json` is already the live identity.\n\n! At the emission step (step 3 above), after writing the scope record(s) to the live `proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### SPECIFICATION Structure (Light)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary of the project.\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance — [requirement]\n- NFR-2: Security — [requirement]\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n  - Dependencies: none\n  - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n- ! Requirements section MUST appear in SPECIFICATION.md (embedded, no separate PRD)\n- ! Each task SHOULD reference which FR/NFR it implements via `(traces: FR-N)`\n- ⊗ Create a separate PRD.md on the Light path\n\n---\n\n## Full Path (large/complex projects)\n\nInterview → PRD → scope records (date-prefixed in proposed/) + live PROJECT-DEFINITION + rendered SPECIFICATION (v0.20 contract). Paths are **xbrief-first**: use `./xbrief/` when that root is the live project layout; else legacy `./vbrief/`.\n\n### Flow\n\n1. Sizing gate selects Full\n2. Interview (rules above)\n3. Generate `PRD.md` — user approval gate\n4. Write scope record(s) to the live lifecycle root — `./xbrief/proposed/YYYY-MM-DD-<slug>.xbrief.json` when `./xbrief/` is live; else legacy `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` — date-prefixed with `status: proposed`\n5. Run `task project:render` to create/update the **live** PROJECT-DEFINITION under the resolved layout root (`./xbrief/PROJECT-DEFINITION.xbrief.json`). Engine layout resolution requires `xbrief/` (#2112); if the repo is legacy-only `./vbrief/`, run `deft migrate:xbrief` first, then render. Ensure all five lifecycle folders exist under the live root. ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `xbrief/` is live\n6. Summarize decisions, ask user to review\n7. On approval, use `task scope:promote` (or equivalent) to move scope record(s) to `pending/` under the **same** live root with `status: pending` / `approved`\n8. Run `task project:export-spec` / `task spec:render` as appropriate (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` / `specification.xbrief.json` are legacy and are NOT written by this strategy on the v0.20 path)\n\n! **Before writing** PRD, scope records, or updating `PROJECT-DEFINITION` on the Full path, follow [artifact-guards.md](./artifact-guards.md): Preparatory Guard for `proposed/` scopes; Spec-Generating Guard against the **live** identity file (xbrief-first). Prefer enrich/merge when the user declines replace.\n! ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `./xbrief/PROJECT-DEFINITION.xbrief.json` is already the live identity.\n\n! At the emission step (step 4 above), after writing the scope record(s) to the live `proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### PRD Structure (Full path only)\n\n```markdown\n# [Project Name] PRD\n\n## Problem Statement\nWhat problem does this solve? Who has this problem?\n\n## Goals\n- Primary goal\n- Secondary goals\n- Non-goals (explicitly out of scope)\n\n## User Stories\nAs a [user type], I want [capability] so that [benefit].\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance — [requirement]\n- NFR-2: Security — [requirement]\n\n## Success Metrics\nHow do we know this succeeded?\n\n## Open Questions\nAny remaining decisions deferred to implementation.\n```\n\n### PRD Guidelines\n\n- ! Focus on WHAT, not HOW\n- ! Use RFC 2119 language (MUST, SHOULD, MAY)\n- ! Number all requirements for traceability\n- ~ Include acceptance criteria for each requirement\n- ⊗ Include implementation details or architecture\n\n### PRD Transition Criteria\n\n- ! All functional requirements documented\n- ! Non-functional requirements specified\n- ! User has reviewed and approved PRD\n- ~ No blocking open questions remain\n\n### PRD Approval Menu (#740, refs #767)\n\n! After every PRD (Product Requirements Document) review, the agent MUST\npresent the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu replaces ambiguous `Accept / Refine / Edit`\nbuttons with action-shaped labels and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the PRD (Product Requirements Document)?\n\n  1. Approve and continue (lock the PRD, generate the SPECIFICATION)\n  2. Suggest changes (you describe what to change; the agent rewrites)\n  3. Edit yourself (you edit the PRD directly; the agent waits)\n  4. Discuss\n  5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the PRD review surfaces a red/green diff, the agent MUST emit a\nnon-alarming preface above it (per `references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first review\npass and present a plain-English summary of changes; show the diff only\non the second pass or when the user explicitly asks for it.\n\n- ⊗ Use plain `Accept / Refine / Edit` buttons without explanatory\n  parentheticals.\n- ⊗ Add a numbered approval menu where Discuss and Back are not the\n  final two options.\n- ⊗ Show a red/green diff at first review without a non-alarming preface.\n\n### SPECIFICATION Structure (Full)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary and link to PRD.\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n  - Dependencies: none\n  - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n---\n\n## SPECIFICATION Guidelines (both paths)\n\n- ! Reference requirement IDs (FR-1, NFR-2, etc.) in each task\n- ! Break into phases, subphases, tasks\n- ! Mark ALL dependencies explicitly\n- ! Design for parallel work (multiple agents)\n- ! End each phase/subphase with tests that pass\n- ~ Size tasks for 1-4 hours of work\n- ~ Minimize inter-task dependencies\n- ⊗ Write code (specification only)\n\n### Task Format\n\nEach task SHOULD include:\n- ! Clear description\n- ! Dependencies (or \"none\")\n- ! Acceptance criteria\n- ~ Estimated effort\n- ? Assigned agent (for swarm mode)\n\n### Transition Criteria\n\n- ! All requirements mapped to tasks\n- ! Dependencies form a valid DAG (no cycles)\n- ! Scope records exist in the live `proposed/` root (`./xbrief/proposed/` when live; else legacy `./vbrief/proposed/`) with date-prefixed filenames and `status: \"proposed\"`, or promoted to pending/active (with `status: \"approved\" / \"pending\"`)\n- ! Live PROJECT-DEFINITION is present (`./xbrief/PROJECT-DEFINITION.xbrief.json` when that is the identity; else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) populated via `task project:render`\n- ! `SPECIFICATION.md` has been rendered via export/`task spec:render`\n- ! Proceed to [Acceptance Gate](#acceptance-gate)\n\n---\n\n## Acceptance Gate\n\nAfter spec generation, present the user with a final decision before\nimplementation begins.\n\n! The acceptance gate MUST appear after every spec generation (both Light and\nFull paths).\n! The acceptance gate is a **blocking question**. The AI MUST present the\noptions and wait for the user to choose.\n\n### Options\n\n1. **Accept** — spec is approved, proceed to implementation\n   - ! Before handing off to implementation, verify the project toolchain is installed and functional — see [../coding/toolchain.md](../coding/toolchain.md); stop and report if any required tool is missing\n2. **Revise** — return to the [Chaining Gate](#chaining-gate) with all prior\n   context preserved (completed strategies, artifacts). Run additional\n   preparatory strategies or regenerate the spec.\n3. **Switch strategy** — return to the [Chaining Gate](#chaining-gate) to select\n   a different spec-generating strategy (e.g., switch from interview to speckit)\n\n### SPECIFICATION Approval Menu (#740, refs #767)\n\n! In addition to the structured Accept / Revise / Switch options above,\nthe agent MUST present the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu states what each choice will actually do, in\nplain-English action-shaped labels, and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the SPECIFICATION?\n\n  1. Approve and continue (lock the SPEC, proceed to implementation)\n  2. Suggest changes (you describe what to change; the agent rewrites)\n  3. Edit yourself (you edit the SPEC directly; the agent waits)\n  4. Discuss\n  5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! Option 1 (`Approve and continue`) maps to the `Accept` option above\n(which then runs the toolchain verification). Option 2 (`Suggest\nchanges`) and Option 3 (`Edit yourself`) both map to `Revise` (return to\nthe Chaining Gate with prior context preserved). The numbered menu is\nthe user-facing surface; the structured Accept / Revise / Switch above\nis the agent's internal contract.\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the SPECIFICATION review surfaces a red/green diff, the agent\nMUST emit a non-alarming preface above it (per\n`references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first\nreview pass and present a plain-English summary of changes; show the\ndiff only on the second pass or when the user explicitly asks for it.\n\n- ⊗ Add a numbered approval menu where Discuss and Back are not the\n  final two options.\n- ⊗ Show a red/green diff at first review without a non-alarming preface.\n\n### Rejected Spec Archival\n\n- ! When the user chooses \"Revise\" or \"Switch\", the current `SPECIFICATION.md`\n  MUST be archived to `history/specs/` before regeneration\n- ! Archived name format: `SPECIFICATION-rejected-{ISO-timestamp}.md`\n  (e.g., `SPECIFICATION-rejected-2026-03-15T19-23-00Z.md`)\n- ! If a `PRD.md` exists (Full path), it is NOT archived — only the spec\n- ~ Include a one-line header in the archived file noting why it was rejected\n\n### State Preservation\n\n- ! All `completedStrategies` and `artifacts` in `plan.xbrief.json` MUST be\n  preserved across revisions\n- ! The chaining gate will show updated run counts reflecting the full session history\n\n---\n\n## Artifacts Summary\n\n**Light path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `./xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json`) | Scope story records (date-prefixed, v0.20 contract) | Interview |\n| `./xbrief/PROJECT-DEFINITION.xbrief.json` (else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated plan with embedded Requirements (rendered derivative; deprecation sentinel) | export / `task spec:render` |\n| (no `specification.*.json`) | Legacy artifact — omitted on v0.20 path | — |\n\n**Full path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `PRD.md` | What to build (approval gate) | Interview |\n| `./xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json`) | Scope story records (date-prefixed, v0.20 contract) | Post-PRD interview |\n| `./xbrief/PROJECT-DEFINITION.xbrief.json` (else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated implementation plan (rendered derivative; deprecation sentinel) | export / `task spec:render` |\n| (no `specification.*.json`) | Legacy artifact — omitted on v0.20 path | — |\n\n## Invoking This Strategy\n\n```\n/deft:run:interview [project name]\n```\n\nOr explicitly:\n\n```\nUse the interview strategy to plan [project].\n```\n\nAfter completion:\n\n```\nimplement the scope records in ./xbrief/active/ (or legacy ./vbrief/active/)\n```\n"
+      "body": "# Interview Strategy\n\nThe standard Deft workflow: structured interview → SPECIFICATION. This is the\ncanonical source of truth for the interview process. All entry points (CLI via\n`directive` / setup Phase 3, agent via `deft-directive-setup` Phase 3, and `templates/make-spec.md`) MUST\nfollow this strategy.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/discuss.md](./discuss.md) | [strategies/yolo.md](./yolo.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [core/glossary.md](../glossary.md)\n\n## When to Use\n\n- ! Default strategy for all new projects\n- ~ Projects with unclear or evolving requirements\n- ~ When stakeholder alignment is needed before implementation\n- ? Skip to SPECIFICATION phase if requirements are already fully documented\n\n---\n\n## Chaining Gate\n\nBefore spec generation, offer the user a chance to run preparatory strategies\nor switch to a different spec-generating strategy. This gate is the single\norchestration point for strategy composition.\n\n! The chaining gate MUST always be shown — even when the interview strategy is\ninvoked directly with no prior strategy.\n! The chaining gate is a **blocking question**. The AI MUST present the options\nand wait for the user to choose before proceeding.\n⊗ Skip the chaining gate or proceed to the sizing gate without presenting it.\n\n### When It Appears\n\n- ! Before the [Sizing Gate](#sizing-gate) on every entry to the interview strategy\n- ! After each completed preparatory strategy (recursive — the gate reappears)\n- ! After the [Acceptance Gate](#acceptance-gate) when the user chooses \"Revise\" or \"Switch\"\n\n### Brownfield Detector\n\nBefore rendering menu options, classify the repo (align with setup Phase 3):\n\n- **Brownfield** when **either**:\n  - `PROJECT-DEFINITION` exists under `./xbrief/` or legacy `./vbrief/` (`PROJECT-DEFINITION.xbrief.json` or `PROJECT-DEFINITION.vbrief.json`), **or**\n  - any lifecycle folder (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/` under `xbrief/` or legacy `vbrief/`) has scope records\n- **Greenfield** otherwise\n\n! The detector MUST run on every Chaining Gate presentation.\n⊗ Offer only the greenfield-framed **Proceed to specification** default on a brownfield repo.\n⊗ Treat brownfield as a full create path without an explicit Replace/scrap confirm.\n\n### Options\n\n! Numbered Chaining Gate menus (greenfield and brownfield examples below) MUST end with `Discuss` and `Back` as the final two options per [deterministic-questions.md](../contracts/deterministic-questions.md).\n\nPresent groups sourced from the `Type` column in\n[strategies/README.md](./README.md#strategy-types). The **default path** depends\non the brownfield detector:\n\n**Default path (greenfield):**\n1. **Proceed to specification** (default) — continue to the [Sizing Gate](#sizing-gate) for a full create path\n\n**Default path (brownfield) — create-vs-update menu:**\n1. **Add scope to this project** (default) — load existing project identity + preparatory artifacts; **skip** the greenfield \"what are we building?\" interview; gather only the new scope; emit **one** proposed scope record; apply the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) on write\n2. **Update project definition** — run a **delta** interview against existing identity; apply the [Spec-Generating Guard](./artifact-guards.md#spec-generating-guard-full); **merge** narratives (prefer enrich/merge when the user declines replace)\n3. **Replace specification (scrap)** — full recreate equivalent to greenfield Proceed; **only** after explicit affirmative (`yes` / `confirmed`); vague replies (`proceed`, `ok`, `go ahead`) are **not** acceptance\n   - ! On confirmed scrap, continue to the [Sizing Gate](#sizing-gate) as a full create path\n   - ⊗ Auto-delete PROJECT-DEFINITION without scrap confirm\n   - ⊗ Rename Proceed to \"Update\" without changing behavior\n\n**Preparatory strategies** (type: `preparatory` — loops back to this gate on completion):\n- Research — investigate the domain, find libraries, identify pitfalls\n- Discuss — lock key decisions using Feynman technique\n- Probe — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n- Map — analyze existing codebase conventions\n\n~ Some preparatory strategies (currently map) also support standalone invocation\nvia `/deft:run:<name>` without entering the interview flow. When invoked standalone,\nthey present their own completion options instead of returning to this gate.\nSee `strategies/map.md` for standalone behavior.\n\n**Switch spec-generating strategy** (type: `spec-generating` — replaces current pipeline):\n- Yolo — auto-pilot, Johnbot picks all answers\n- SpecKit — formal spec process with story readiness before implementation\n\n### Run Count Annotations\n\n- ! Previously-run strategies MUST display with a run count (e.g., `Research (ran 1×)`)\n- ! No strategy is ever removed from the gate — users can re-run any strategy\n- ! Run counts are read from `completedStrategies` in\n  [`./xbrief/plan.xbrief.json`](../vbrief/vbrief.md#strategy-chaining-fields)\n\n### State Tracking\n\n- ! On completion of a preparatory strategy, update `completedStrategies` in\n  `./xbrief/plan.xbrief.json`: increment `runCount`, append artifact paths\n- ! Append all new artifact paths to the flat `artifacts` array\n- ! The next strategy and eventual spec generation MUST load all artifacts\n  listed in `plan.xbrief.json`\n- ! On brownfield **Add scope** or **Update project definition**, load existing\n  PROJECT-DEFINITION identity and preparatory artifacts before asking questions\n\n### Write Guards (interview)\n\n! Interview is a **spec-generating** strategy and MUST follow\n[artifact-guards.md](./artifact-guards.md) before emission (Light or Full path).\n\n- ! **Before writing** scope records to `proposed/`: [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) (xbrief-first: `./xbrief/proposed/`, else legacy `./vbrief/proposed/`)\n- ! **Before writing** or updating `PROJECT-DEFINITION`: [Spec-Generating Guard](./artifact-guards.md#spec-generating-guard-full) against the **single live** identity file only — `./xbrief/PROJECT-DEFINITION.xbrief.json` when present (or after `deft migrate:xbrief`); else, until migrated, the existing legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`. ⊗ Dual-write both roots\n- ! Prefer enrich/merge when the user declines replace\n- ⊗ Silently overwrite PROJECT-DEFINITION or same-slug proposed scopes\n- ⊗ Guard only the legacy `vbrief/` path while an `xbrief/` PROJECT-DEFINITION is the live identity\n- ⊗ Rely on write-time guards alone without the brownfield Chaining Gate menu above\n\nSurface this obligation **inside `interview.md`** so agents that load only this\nfile still hit the guards (#2925; incomplete closeout of #82/#387).\n\n### Example Prompt\n\n**Greenfield:**\n\n```\nReady to generate the specification. Before we proceed, would you like to:\n\n1. Proceed to specification (default)\n\n--- Preparatory (loops back) ---\n2. Run a research phase — investigate the domain, find libraries, identify pitfalls\n3. Run a discuss phase — lock key decisions using Feynman technique\n4. Run a probe phase — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n5. Run a map phase — analyze existing codebase conventions\n\n--- Switch strategy ---\n6. Switch to yolo — auto-pilot picks all answers\n7. Switch to speckit — formal spec process with story readiness before implementation\n8. Other (specify)\n9. Discuss\n10. Back\n```\n\n**Brownfield:**\n\n```\nThis repo already has a project definition and/or scopes. Before we proceed:\n\n1. Add scope to this project (default) — keep identity; add one new proposed scope\n2. Update project definition — delta interview; merge narratives (Spec-Generating Guard)\n3. Replace specification (scrap) — requires explicit yes/confirmed; full recreate\n\n--- Preparatory (loops back) ---\n4. Run a research phase — investigate the domain, find libraries, identify pitfalls\n5. Run a discuss phase — lock key decisions using Feynman technique\n6. Run a probe phase — adversarially stress-test the plan; surface assumptions, edge cases, and risks\n7. Run a map phase — analyze existing codebase conventions\n\n--- Switch strategy ---\n8. Switch to yolo — auto-pilot picks all answers\n9. Switch to speckit — formal spec process with story readiness before implementation\n10. Other (specify)\n11. Discuss\n12. Back\n```\n\n---\n\n## Sizing Gate\n\nBefore the interview begins, determine project complexity to select the\nappropriate path. The gate runs once, immediately after hearing what the user\nwants to build.\n\n! The sizing gate is a **blocking question**. The AI MUST propose a size and\nwait for the user to confirm or override before asking any interview questions.\n⊗ Combine the sizing proposal with the first interview question in the same message.\n⊗ Proceed to interview questions before the user has explicitly confirmed the path.\n\n### Sizing Signals\n\nThe AI SHOULD propose a size based on these signals; the user confirms or overrides:\n\n- Number of features (≤5 → Light, >5 → Full)\n- Number of components/services (1–2 → Light, 3+ → Full)\n- Expected duration (days → Light, weeks/months → Full)\n- Team/agent count (solo → Light, multi-agent/swarm → Full)\n- Integration complexity (standalone → Light, external APIs/auth/DB → Full)\n\n### PROJECT-DEFINITION.vbrief.json Override\n\n`PROJECT-DEFINITION.vbrief.json` narratives ? declare `\"Process\": \"Light\"` or `\"Process\": \"Full\"` to skip the\ngate entirely. `PROJECT.md` (deprecated) may also carry this field. If the field is absent or empty, the AI MUST ask.\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n    subgraph interview [\"Interview Strategy\"]\n        G{\"⚖️ Sizing Gate\"}\n        I_L[\"💬 Interview<br/><i>Light path</i>\"]\n        I_F[\"💬 Interview<br/><i>Full path</i>\"]\n        P[\"📄 PRD<br/><i>What to build</i>\"]\n        S[\"📋 SPECIFICATION<br/><i>How to build it</i>\"]\n    end\n\n    G -->|\"Light\"| I_L\n    G -->|\"Full\"| I_F\n    I_L -->|\"Ambiguity resolved\"| S\n    I_F -->|\"Ambiguity resolved\"| P\n    P -->|\"Approved\"| S\n    S -->|\"Ready\"| IMPL[\"🔨 Implementation\"]\n\n    style G fill:#f0abfc,stroke:#a21caf,color:#000\n    style I_L fill:#c4b5fd,stroke:#7c3aed,color:#000\n    style I_F fill:#c4b5fd,stroke:#7c3aed,color:#000\n    style P fill:#fef08a,stroke:#ca8a04,color:#000\n    style S fill:#6ee7b7,stroke:#059669,color:#000\n    style IMPL fill:#7dd3fc,stroke:#0284c7,color:#000\n```\n\n---\n\n## Interview Rules (shared by both paths)\n\n- ~ Use Claude AskInterviewQuestion when available (emulate if not)\n- ! Ask **ONE** focused, non-trivial question per step\n- ⊗ Ask multiple questions at once or sneak in \"also\" questions\n- ~ Provide numbered answer options when appropriate\n- ! Include \"other\" option for custom/unknown responses\n- ! Indicate which option is RECOMMENDED\n- ! When making an opinionated recommendation, state the principle (1 sentence)\n- ! When done, append all questions asked and answers given to the working document\n\n### Question Areas\n\n- ! Missing decisions (language, framework, deployment)\n- ! Edge cases (errors, boundaries, failure modes)\n- ! Implementation details (architecture, patterns, libraries)\n- ! Requirements (performance, security, scalability)\n- ! UX/constraints (users, timeline, compatibility)\n- ! Tradeoffs (simplicity vs features, speed vs safety)\n\n### Transition Criteria (interview complete)\n\n- ! All major decisions have answers\n- ! Edge cases are addressed\n- ! User has approved key tradeoffs (Interview strategy) or Johnbot has chosen recommended options (Yolo strategy)\n- ~ Little ambiguity remains\n\n---\n\n## Light Path (small/medium projects)\n\nInterview → scope records (date-prefixed in proposed/) + live PROJECT-DEFINITION + rendered SPECIFICATION (v0.20 contract). Paths are **xbrief-first**: use `./xbrief/` when that root is the live project layout; else legacy `./vbrief/`.\n\n### Flow\n\n1. Sizing gate selects Light\n2. Interview (rules above)\n3. Write scope record(s) to the live lifecycle root — `./xbrief/proposed/YYYY-MM-DD-<slug>.xbrief.json` when `./xbrief/` is live; else legacy `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` — date-prefixed with `status: proposed`\n4. Run `task project:render` to create/update the **live** PROJECT-DEFINITION under the resolved layout root (`./xbrief/PROJECT-DEFINITION.xbrief.json`). Engine layout resolution requires `xbrief/` (#2112); if the repo is legacy-only `./vbrief/`, run `deft migrate:xbrief` first, then render. Ensure all five lifecycle folders exist under the live root. ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `xbrief/` is live\n5. Summarize decisions, ask user to review\n6. On approval, use `task scope:promote` (or equivalent) to move scope record(s) to `pending/` under the **same** live root with `status: pending` / `approved`\n7. Run `task project:export-spec` / `task spec:render` as appropriate (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` / `specification.xbrief.json` are legacy and are NOT written by this strategy on the v0.20 path)\n\n! **Before writing** scope records or updating `PROJECT-DEFINITION` on the Light path, follow [artifact-guards.md](./artifact-guards.md): Preparatory Guard for `proposed/` scopes; Spec-Generating Guard against the **live** identity file (xbrief-first). Prefer enrich/merge when the user declines replace.\n! ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `./xbrief/PROJECT-DEFINITION.xbrief.json` is already the live identity.\n\n! At the emission step (step 3 above), after writing the scope record(s) to the live `proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### SPECIFICATION Structure (Light)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary of the project.\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance — [requirement]\n- NFR-2: Security — [requirement]\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n  - Dependencies: none\n  - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n- ! Requirements section MUST appear in SPECIFICATION.md (embedded, no separate PRD)\n- ! Each task SHOULD reference which FR/NFR it implements via `(traces: FR-N)`\n- ⊗ Create a separate PRD.md on the Light path\n\n---\n\n## Full Path (large/complex projects)\n\nInterview → PRD → scope records (date-prefixed in proposed/) + live PROJECT-DEFINITION + rendered SPECIFICATION (v0.20 contract). Paths are **xbrief-first**: use `./xbrief/` when that root is the live project layout; else legacy `./vbrief/`.\n\n### Flow\n\n1. Sizing gate selects Full\n2. Interview (rules above)\n3. Generate `PRD.md` — user approval gate\n4. Write scope record(s) to the live lifecycle root — `./xbrief/proposed/YYYY-MM-DD-<slug>.xbrief.json` when `./xbrief/` is live; else legacy `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` — date-prefixed with `status: proposed`\n5. Run `task project:render` to create/update the **live** PROJECT-DEFINITION under the resolved layout root (`./xbrief/PROJECT-DEFINITION.xbrief.json`). Engine layout resolution requires `xbrief/` (#2112); if the repo is legacy-only `./vbrief/`, run `deft migrate:xbrief` first, then render. Ensure all five lifecycle folders exist under the live root. ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `xbrief/` is live\n6. Summarize decisions, ask user to review\n7. On approval, use `task scope:promote` (or equivalent) to move scope record(s) to `pending/` under the **same** live root with `status: pending` / `approved`\n8. Run `task project:export-spec` / `task spec:render` as appropriate (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` / `specification.xbrief.json` are legacy and are NOT written by this strategy on the v0.20 path)\n\n! **Before writing** PRD, scope records, or updating `PROJECT-DEFINITION` on the Full path, follow [artifact-guards.md](./artifact-guards.md): Preparatory Guard for `proposed/` scopes; Spec-Generating Guard against the **live** identity file (xbrief-first). Prefer enrich/merge when the user declines replace.\n! ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `./xbrief/PROJECT-DEFINITION.xbrief.json` is already the live identity.\n\n! At the emission step (step 4 above), after writing the scope record(s) to the live `proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### PRD Structure (Full path only)\n\n```markdown\n# [Project Name] PRD\n\n## Problem Statement\nWhat problem does this solve? Who has this problem?\n\n## Goals\n- Primary goal\n- Secondary goals\n- Non-goals (explicitly out of scope)\n\n## User Stories\nAs a [user type], I want [capability] so that [benefit].\n\n## Requirements\n\n### Functional Requirements\n- FR-1: [requirement]\n- FR-2: [requirement]\n\n### Non-Functional Requirements\n- NFR-1: Performance — [requirement]\n- NFR-2: Security — [requirement]\n\n## Success Metrics\nHow do we know this succeeded?\n\n## Open Questions\nAny remaining decisions deferred to implementation.\n```\n\n### PRD Guidelines\n\n- ! Focus on WHAT, not HOW\n- ! Use RFC 2119 language (MUST, SHOULD, MAY)\n- ! Number all requirements for traceability\n- ~ Include acceptance criteria for each requirement\n- ⊗ Include implementation details or architecture\n\n### PRD Transition Criteria\n\n- ! All functional requirements documented\n- ! Non-functional requirements specified\n- ! User has reviewed and approved PRD\n- ~ No blocking open questions remain\n\n### PRD Approval Menu (#740, refs #767)\n\n! After every PRD (Product Requirements Document) review, the agent MUST\npresent the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu replaces ambiguous `Accept / Refine / Edit`\nbuttons with action-shaped labels and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the PRD (Product Requirements Document)?\n\n  1. Approve and continue (lock the PRD, generate the SPECIFICATION)\n  2. Suggest changes (you describe what to change; the agent rewrites)\n  3. Edit yourself (you edit the PRD directly; the agent waits)\n  4. Discuss\n  5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the PRD review surfaces a red/green diff, the agent MUST emit a\nnon-alarming preface above it (per `references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first review\npass and present a plain-English summary of changes; show the diff only\non the second pass or when the user explicitly asks for it.\n\n- ⊗ Use plain `Accept / Refine / Edit` buttons without explanatory\n  parentheticals.\n- ⊗ Add a numbered approval menu where Discuss and Back are not the\n  final two options.\n- ⊗ Show a red/green diff at first review without a non-alarming preface.\n\n### SPECIFICATION Structure (Full)\n\n```markdown\n# [Project Name] SPECIFICATION\n\n## Overview\nBrief summary and link to PRD.\n\n## Architecture\nHigh-level system design, components, data flow.\n\n## Implementation Plan\n\n### Phase 1: Foundation\n#### Subphase 1.1: Setup\n- Task 1.1.1: [description] (traces: FR-1)\n  - Dependencies: none\n  - Acceptance: [criteria]\n\n#### Subphase 1.2: Core (depends on: 1.1)\n- Task 1.2.1: [description] (traces: FR-2, NFR-1)\n\n### Phase 2: Features (depends on: Phase 1)\n...\n\n## Testing Strategy\nHow to verify the implementation meets requirements.\n\n## Deployment\nHow to ship it.\n```\n\n---\n\n## SPECIFICATION Guidelines (both paths)\n\n- ! Reference requirement IDs (FR-1, NFR-2, etc.) in each task\n- ! Break into phases, subphases, tasks\n- ! Mark ALL dependencies explicitly\n- ! Design for parallel work (multiple agents)\n- ! End each phase/subphase with tests that pass\n- ~ Size tasks for 1-4 hours of work\n- ~ Minimize inter-task dependencies\n- ⊗ Write code (specification only)\n\n### Task Format\n\nEach task SHOULD include:\n- ! Clear description\n- ! Dependencies (or \"none\")\n- ! Acceptance criteria\n- ~ Estimated effort\n- ? Assigned agent (for swarm mode)\n\n### Transition Criteria\n\n- ! All requirements mapped to tasks\n- ! Dependencies form a valid DAG (no cycles)\n- ! Scope records exist in the live `proposed/` root (`./xbrief/proposed/` when live; else legacy `./vbrief/proposed/`) with date-prefixed filenames and `status: \"proposed\"`, or promoted to pending/active (with `status: \"approved\" / \"pending\"`)\n- ! Live PROJECT-DEFINITION is present (`./xbrief/PROJECT-DEFINITION.xbrief.json` when that is the identity; else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) populated via `task project:render`\n- ! `SPECIFICATION.md` has been rendered via export/`task spec:render`\n- ! Proceed to [Acceptance Gate](#acceptance-gate)\n\n---\n\n## Acceptance Gate\n\nAfter spec generation, present the user with a final decision before\nimplementation begins.\n\n! The acceptance gate MUST appear after every spec generation (both Light and\nFull paths).\n! The acceptance gate is a **blocking question**. The AI MUST present the\noptions and wait for the user to choose.\n\n### Options\n\n1. **Accept** — spec is approved, proceed to implementation\n   - ! Before handing off to implementation, verify the project toolchain is installed and functional — see [../coding/toolchain.md](../coding/toolchain.md); stop and report if any required tool is missing\n2. **Revise** — return to the [Chaining Gate](#chaining-gate) with all prior\n   context preserved (completed strategies, artifacts). Run additional\n   preparatory strategies or regenerate the spec.\n3. **Switch strategy** — return to the [Chaining Gate](#chaining-gate) to select\n   a different spec-generating strategy (e.g., switch from interview to speckit)\n\n### SPECIFICATION Approval Menu (#740, refs #767)\n\n! In addition to the structured Accept / Revise / Switch options above,\nthe agent MUST present the canonical numbered approval menu defined in\n[`../references/plain-english-ux.md`](../references/plain-english-ux.md)\n`## Rule 4`. The menu states what each choice will actually do, in\nplain-English action-shaped labels, and follows the #767 framework rule\nfor deterministic numbered menus -- the **final two numbered options\nMUST be `Discuss` and `Back`**, in that order.\n\n```\nWhat would you like to do with the SPECIFICATION?\n\n  1. Approve and continue (lock the SPEC, proceed to implementation)\n  2. Suggest changes (you describe what to change; the agent rewrites)\n  3. Edit yourself (you edit the SPEC directly; the agent waits)\n  4. Discuss\n  5. Back\n\nEnter confirm / b back / 0 discuss\n```\n\n! Option 1 (`Approve and continue`) maps to the `Accept` option above\n(which then runs the toolchain verification). Option 2 (`Suggest\nchanges`) and Option 3 (`Edit yourself`) both map to `Revise` (return to\nthe Chaining Gate with prior context preserved). The numbered menu is\nthe user-facing surface; the structured Accept / Revise / Switch above\nis the agent's internal contract.\n\n! When `contracts/deterministic-questions.md` lands (Agent 1, #767), this\nstrategy MUST defer to that contract for canonical menu wording.\n\n! When the SPECIFICATION review surfaces a red/green diff, the agent\nMUST emit a non-alarming preface above it (per\n`references/plain-english-ux.md` Rule 5):\n\n```\nHere's what changed since the previous draft. Red lines were removed,\ngreen lines were added. Nothing here is broken -- this is a normal\nreview.\n```\n\n? Alternatively, the agent MAY hide the diff entirely on the first\nreview pass and present a plain-English summary of changes; show the\ndiff only on the second pass or when the user explicitly asks for it.\n\n- ⊗ Add a numbered approval menu where Discuss and Back are not the\n  final two options.\n- ⊗ Show a red/green diff at first review without a non-alarming preface.\n\n### Rejected Spec Archival\n\n- ! When the user chooses \"Revise\" or \"Switch\", the current `SPECIFICATION.md`\n  MUST be archived to `history/specs/` before regeneration\n- ! Archived name format: `SPECIFICATION-rejected-{ISO-timestamp}.md`\n  (e.g., `SPECIFICATION-rejected-2026-03-15T19-23-00Z.md`)\n- ! If a `PRD.md` exists (Full path), it is NOT archived — only the spec\n- ~ Include a one-line header in the archived file noting why it was rejected\n\n### State Preservation\n\n- ! All `completedStrategies` and `artifacts` in `plan.xbrief.json` MUST be\n  preserved across revisions\n- ! The chaining gate will show updated run counts reflecting the full session history\n\n---\n\n## Artifacts Summary\n\n**Light path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `./xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json`) | Scope story records (date-prefixed, v0.20 contract) | Interview |\n| `./xbrief/PROJECT-DEFINITION.xbrief.json` (else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated plan with embedded Requirements (rendered derivative; deprecation sentinel) | export / `task spec:render` |\n| (no `specification.*.json`) | Legacy artifact — omitted on v0.20 path | — |\n\n**Full path:**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `PRD.md` | What to build (approval gate) | Interview |\n| `./xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json`) | Scope story records (date-prefixed, v0.20 contract) | Post-PRD interview |\n| `./xbrief/PROJECT-DEFINITION.xbrief.json` (else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |\n| `SPECIFICATION.md` | Generated implementation plan (rendered derivative; deprecation sentinel) | export / `task spec:render` |\n| (no `specification.*.json`) | Legacy artifact — omitted on v0.20 path | — |\n\n## Invoking This Strategy\n\n```\n/deft:run:interview [project name]\n```\n\nOr explicitly:\n\n```\nUse the interview strategy to plan [project].\n```\n\nAfter completion:\n\n```\nimplement the scope records in ./xbrief/active/ (or legacy ./vbrief/active/)\n```\n"
     },
     {
       "id": "map",
@@ -121,7 +121,7 @@
         "research"
       ],
       "path": "strategies/research.md",
-      "body": "# Research Strategy\n\nLook before you leap — investigate the domain before planning.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [strategies/map.md](./map.md)\n\n> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) research phase.\n\n---\n\n## When to Use\n\n- ~ Before planning a feature in an unfamiliar domain (auth, payments, real-time, etc.)\n- ~ When the feature involves libraries or APIs the agent hasn't used in this project\n- ? Skip for well-understood domains where the agent has strong existing context\n\n## Scope Confirmation Gate (#1273)\n\n! Before autonomous research begins, present one blocking scope-confirmation prompt and wait for the user's selection. Use the deterministic question contract: the final two numbered options MUST be `Discuss` and `Back`.\n\nPrompt:\n> \"What should this research focus on before I investigate autonomously?\"\n\n1. Confirm the inferred feature/domain scope (Recommended)\n2. Refine the feature boundary or priority areas\n3. Provide sample data, artifacts, constraints, or sensitive areas to account for\n4. Discuss\n5. Back\n\n- ! **Confirmed-scope postcondition (required before survey):** research MUST NOT start the survey until a confirmed research scope is recorded in notes. Confirmation is achieved by **any** of: option **1** (accept inferred scope as-is), or option **2**/**3** after free-form capture (the free-form answer **is** the confirmation of scope — it replaces option-1 confirmation; do not re-open option 1 after capture).\n- ! On option **1** (confirm inferred scope): record the inferred feature/domain as the confirmed research scope and proceed to the survey step.\n- ! On option **2** (refine boundary): ask a **follow-up free-form question** in the next message (one question only) to capture the refined feature boundary or priority areas; wait for the user's answer; record that free-form text as the **confirmed** research scope; then proceed to survey. ⊗ Proceed to survey after option 2 without collecting free-form refinement text. ⊗ Leave research blocked after option 2 with no follow-up path.\n- ! On option **3** (artifacts/constraints/sensitivity): ask a **follow-up free-form question** in the next message (one question only) for sample data paths, artifacts to analyze, constraints, or sensitive areas; wait for the user's answer; record provided artifacts/constraints/sensitivity flags **and** treat the current feature/domain (plus those inputs) as the **confirmed** research scope; then proceed to survey. ⊗ Proceed to survey after option 3 without collecting free-form artifact/constraint input. ⊗ Leave research blocked after option 3 with no follow-up path.\n- ! If the user declines free-form input after option 2 or 3 (empty answer / \"skip\" / \"none\"): re-present the Scope Confirmation Gate once; if they pick option **1**, confirm inferred scope and proceed; if they again decline capture without confirming, stop research and return to the chaining gate or invoking menu — do not survey on unconfirmed scope.\n- ! Record the confirmed scope, any provided artifacts, and any sensitivity flags in the research notes before the survey step.\n- ⊗ Start the survey from project description alone without a confirmed research scope (option 1 acceptance or option 2/3 free-form confirmation).\n\n## Output\n\n! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).\n\nProduce `xbrief/proposed/{feature}-research.xbrief.json` with two mandatory narratives:\n\n! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### `DontHandRoll` narrative\n\nProblems that look simple but have existing, battle-tested solutions.\n\n- ! For each problem area, specify: **problem**, **recommended library/tool**, **why not hand-roll**\n- ! Check the project's existing dependencies first -- don't add a library when one is already available\n- ~ Consult official docs for the recommended library (use Context7 or equivalent)\n\n**Example narrative content:**\n```\nProblem: JWT validation\nUse: jose\nRationale: Edge cases in token expiry, key rotation, algorithm confusion\n\nProblem: Email templates\nUse: react-email\nRationale: HTML email rendering is notoriously broken across clients\n\nProblem: Rate limiting\nUse: express-rate-limit\nRationale: IP spoofing, distributed state, Redis integration\n```\n\n### `CommonPitfalls` narrative\n\nWhat goes wrong in this domain, why, and how to avoid it.\n\n- ! For each pitfall: **what happens**, **why it happens**, **how to avoid it**, **warning signs**\n- ~ Informed by library docs, codebase patterns, and known failure modes\n- ~ Prioritize pitfalls that agents specifically tend to hit (stubs, missing error handling, hardcoded values)\n\n**Example narrative content:**\n```\nPitfall: Storing plain-text passwords\nWhat: User passwords saved without hashing\nWhy: Agent implements the happy path and forgets security\nAvoid: Use bcrypt/argon2, never store raw passwords\nWarning signs: No crypto import in auth module, password field stored as-is\n```\n\n### `IPRisk` narrative (#738)\n\n! When the project description, the `Don't Hand-Roll` survey, or the\nresearch notes reference third-party intellectual property (IP), the\nresearch phase MUST run the IP-risk heuristic from\n[`../references/ip-risk.md`](../references/ip-risk.md) -- canonical\nimplementation `scripts/ip_risk.py:detect_ip_terms` -- and persist a\nplain-English `IPRisk` narrative on the research vBRIEF.\n\nThe heuristic is permissive on purpose: recognizable IP names (Magic:\nThe Gathering, Pokemon, etc.), fictional-universe terms (Hogwarts,\nTatooine), branded characters, sports leagues, and trademarked products\nall trigger a hit.\n\n- ! When `detect_ip_terms` returns at least one hit, the research output\n  MUST: (1) ask the explicit monetization-intent question (personal vs\n  commercial); (2) emit `plain_risk_summary(hits, intent)` into the\n  `IPRisk` narrative; (3) plan to inject the protection scope items\n  (`ip_risk_scope_items(intent)`) at SPECIFICATION-generation time.\n- ! On `commercial` intent, surface the **non-optional** lawyer-\n  consultation recommendation in the research output -- this carries\n  forward into the interview output and the SPECIFICATION via the\n  `IPRisk` narrative.\n- ⊗ Treat the absence of detected terms as proof that the project is\n  IP-free. The heuristic only knows about the curated lists; when the\n  research scope is vague, ask the user directly whether the project is\n  based on a game / film / sports league / brand.\n- ⊗ Provide legal advice -- Deft is not a law firm. The only\n  recommendation it makes is **consult a lawyer**.\n\n---\n\n## How Research Feeds Downstream\n\n- ! **Planning** reads research before task decomposition — acceptance criteria account for pitfalls\n- ! **Execution** references \"Don't Hand-Roll\" — agent uses recommended libraries, not custom code\n- ~ **Verification** checks for pitfall warning signs during stub detection\n\n## Research Scope Rules\n\n- ! Research the **current feature only** — not the entire project\n- ! Time-box research — if it takes longer than the feature, scope is wrong\n- ⊗ Research as a reason to delay execution indefinitely\n- ~ Research persists as a vBRIEF in `xbrief/proposed/`\n\n---\n\n## Then: Chaining Gate\n\nAfter research is complete, return to the [chaining gate](./interview.md#chaining-gate)\nso the user can run additional preparatory strategies or proceed to spec generation.\n\n- ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:\n  - Update `completedStrategies`: increment `runCount` for `\"research\"`,\n    append artifact path (`xbrief/proposed/{feature}-research.xbrief.json`)\n  - Append the path to the flat `artifacts` array\n- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)\n- ! Present the chaining gate as a blocking question and wait for a user selection before any spec generation or additional scope vBRIEF generation.\n- ! Explain at handoff that `completedStrategies` records that research ran, while `xbrief/proposed/{feature}-research.xbrief.json` remains a planning artifact in the scope lifecycle until a later strategy promotes or consumes it.\n- ! The research findings MUST inform subsequent strategies and spec generation:\n  - \"Don't Hand-Roll\" items become constraints in the specification\n  - \"Common Pitfalls\" become acceptance criteria or NFRs\n- ⊗ Generate implementation scope vBRIEFs directly from research findings or proceed to spec generation before the user chooses from the chaining gate.\n- ⊗ End the session after research without returning to the chaining gate\n  or the invoking strategy's next-step menu\n\n! **Standalone context:** If invoked from a standalone strategy (e.g. map's\n  standalone next-step menu) rather than from the interview chaining gate,\n  return to the invoking strategy's menu instead.\n\n---\n\n## Workflow\n\n1. **Scope confirmation** -- Ask the blocking scope-confirmation prompt, wait for the user, and record scope/artifact/sensitivity inputs\n2. **Survey** -- Check existing project dependencies, official docs, and known pitfalls\n3. **Document** -- Produce `xbrief/proposed/{feature}-research.xbrief.json` with `DontHandRoll` and `CommonPitfalls` narratives\n4. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above\n\n## Anti-Patterns\n\n- ⊗ Building custom solutions for solved problems\n- ⊗ Skipping research for unfamiliar domains (\"how hard can auth be?\")\n- ⊗ Starting autonomous research before the Scope Confirmation Gate has captured or explicitly skipped user-provided artifacts/constraints\n- ⊗ Research that produces a reading list instead of actionable guidance\n- ⊗ Research that doesn't flow into planning (written and never referenced)\n- ⊗ Ending after research without chaining into specification generation (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))\n"
+      "body": "# Research Strategy\n\nLook before you leap — investigate the domain before planning.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [strategies/map.md](./map.md)\n\n> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) research phase.\n\n---\n\n## When to Use\n\n- ~ Before planning a feature in an unfamiliar domain (auth, payments, real-time, etc.)\n- ~ When the feature involves libraries or APIs the agent hasn't used in this project\n- ? Skip for well-understood domains where the agent has strong existing context\n\n## Scope Confirmation Gate (#1273)\n\n! Before autonomous research begins, present one blocking scope-confirmation prompt and wait for the user's selection. Use the deterministic question contract: the final two numbered options MUST be `Discuss` and `Back`.\n\nPrompt:\n> \"What should this research focus on before I investigate autonomously?\"\n\n1. Confirm the inferred feature/domain scope (Recommended)\n2. Refine the feature boundary or priority areas\n3. Provide sample data, artifacts, constraints, or sensitive areas to account for\n4. Discuss\n5. Back\n\n- ! **Confirmed-scope postcondition (required before survey):** research MUST NOT start the survey until a confirmed research scope is recorded in notes. Confirmation is achieved by **any** of: option **1** (accept inferred scope as-is), or option **2**/**3** after free-form capture (the free-form answer **is** the confirmation of scope — it replaces option-1 confirmation; do not re-open option 1 after capture).\n- ! On option **1** (confirm inferred scope): record the inferred feature/domain as the confirmed research scope and proceed to the survey step.\n- ! On option **2** (refine boundary): ask a **follow-up free-form question** in the next message (one question only) to capture the refined feature boundary or priority areas; wait for the user's answer; record that free-form text as the **confirmed** research scope; then proceed to survey. ⊗ Proceed to survey after option 2 without collecting free-form refinement text. ⊗ Leave research blocked after option 2 with no follow-up path.\n- ! On option **3** (artifacts/constraints/sensitivity): ask a **follow-up free-form question** in the next message (one question only) for sample data paths, artifacts to analyze, constraints, or sensitive areas; wait for the user's answer; record provided artifacts/constraints/sensitivity flags **and** treat the current feature/domain (plus those inputs) as the **confirmed** research scope; then proceed to survey. ⊗ Proceed to survey after option 3 without collecting free-form artifact/constraint input. ⊗ Leave research blocked after option 3 with no follow-up path.\n- ! If the user declines free-form input after option 2 or 3 (empty answer / \"skip\" / \"none\"): re-present the Scope Confirmation Gate once; if they pick option **1**, confirm inferred scope and proceed; if they again decline capture without confirming, stop research and return to the chaining gate or invoking menu — do not survey on unconfirmed scope.\n- ! Record the confirmed scope, any provided artifacts, and any sensitivity flags in the research notes before the survey step.\n- ⊗ Start the survey from project description alone without a confirmed research scope (option 1 acceptance or option 2/3 free-form confirmation).\n\n## Output\n\n! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).\n\nProduce `xbrief/proposed/{feature}-research.xbrief.json` with two mandatory narratives:\n\n! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### `DontHandRoll` narrative\n\nProblems that look simple but have existing, battle-tested solutions.\n\n- ! For each problem area, specify: **problem**, **recommended library/tool**, **why not hand-roll**\n- ! Check the project's existing dependencies first -- don't add a library when one is already available\n- ~ Consult official docs for the recommended library (use Context7 or equivalent)\n\n**Example narrative content:**\n```\nProblem: JWT validation\nUse: jose\nRationale: Edge cases in token expiry, key rotation, algorithm confusion\n\nProblem: Email templates\nUse: react-email\nRationale: HTML email rendering is notoriously broken across clients\n\nProblem: Rate limiting\nUse: express-rate-limit\nRationale: IP spoofing, distributed state, Redis integration\n```\n\n### `CommonPitfalls` narrative\n\nWhat goes wrong in this domain, why, and how to avoid it.\n\n- ! For each pitfall: **what happens**, **why it happens**, **how to avoid it**, **warning signs**\n- ~ Informed by library docs, codebase patterns, and known failure modes\n- ~ Prioritize pitfalls that agents specifically tend to hit (stubs, missing error handling, hardcoded values)\n\n**Example narrative content:**\n```\nPitfall: Storing plain-text passwords\nWhat: User passwords saved without hashing\nWhy: Agent implements the happy path and forgets security\nAvoid: Use bcrypt/argon2, never store raw passwords\nWarning signs: No crypto import in auth module, password field stored as-is\n```\n\n### `IPRisk` narrative (#738)\n\n! When the project description, the `Don't Hand-Roll` survey, or the\nresearch notes reference third-party intellectual property (IP), the\nresearch phase MUST run the IP-risk heuristic from\n[`../references/ip-risk.md`](../references/ip-risk.md) -- canonical\nimplementation `the IP-risk heuristic in references/ip-risk.md` -- and persist a\nplain-English `IPRisk` narrative on the research vBRIEF.\n\nThe heuristic is permissive on purpose: recognizable IP names (Magic:\nThe Gathering, Pokemon, etc.), fictional-universe terms (Hogwarts,\nTatooine), branded characters, sports leagues, and trademarked products\nall trigger a hit.\n\n- ! When `detect_ip_terms` returns at least one hit, the research output\n  MUST: (1) ask the explicit monetization-intent question (personal vs\n  commercial); (2) emit `plain_risk_summary(hits, intent)` into the\n  `IPRisk` narrative; (3) plan to inject the protection scope items\n  (`ip_risk_scope_items(intent)`) at SPECIFICATION-generation time.\n- ! On `commercial` intent, surface the **non-optional** lawyer-\n  consultation recommendation in the research output -- this carries\n  forward into the interview output and the SPECIFICATION via the\n  `IPRisk` narrative.\n- ⊗ Treat the absence of detected terms as proof that the project is\n  IP-free. The heuristic only knows about the curated lists; when the\n  research scope is vague, ask the user directly whether the project is\n  based on a game / film / sports league / brand.\n- ⊗ Provide legal advice -- Deft is not a law firm. The only\n  recommendation it makes is **consult a lawyer**.\n\n---\n\n## How Research Feeds Downstream\n\n- ! **Planning** reads research before task decomposition — acceptance criteria account for pitfalls\n- ! **Execution** references \"Don't Hand-Roll\" — agent uses recommended libraries, not custom code\n- ~ **Verification** checks for pitfall warning signs during stub detection\n\n## Research Scope Rules\n\n- ! Research the **current feature only** — not the entire project\n- ! Time-box research — if it takes longer than the feature, scope is wrong\n- ⊗ Research as a reason to delay execution indefinitely\n- ~ Research persists as a vBRIEF in `xbrief/proposed/`\n\n---\n\n## Then: Chaining Gate\n\nAfter research is complete, return to the [chaining gate](./interview.md#chaining-gate)\nso the user can run additional preparatory strategies or proceed to spec generation.\n\n- ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:\n  - Update `completedStrategies`: increment `runCount` for `\"research\"`,\n    append artifact path (`xbrief/proposed/{feature}-research.xbrief.json`)\n  - Append the path to the flat `artifacts` array\n- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)\n- ! Present the chaining gate as a blocking question and wait for a user selection before any spec generation or additional scope vBRIEF generation.\n- ! Explain at handoff that `completedStrategies` records that research ran, while `xbrief/proposed/{feature}-research.xbrief.json` remains a planning artifact in the scope lifecycle until a later strategy promotes or consumes it.\n- ! The research findings MUST inform subsequent strategies and spec generation:\n  - \"Don't Hand-Roll\" items become constraints in the specification\n  - \"Common Pitfalls\" become acceptance criteria or NFRs\n- ⊗ Generate implementation scope vBRIEFs directly from research findings or proceed to spec generation before the user chooses from the chaining gate.\n- ⊗ End the session after research without returning to the chaining gate\n  or the invoking strategy's next-step menu\n\n! **Standalone context:** If invoked from a standalone strategy (e.g. map's\n  standalone next-step menu) rather than from the interview chaining gate,\n  return to the invoking strategy's menu instead.\n\n---\n\n## Workflow\n\n1. **Scope confirmation** -- Ask the blocking scope-confirmation prompt, wait for the user, and record scope/artifact/sensitivity inputs\n2. **Survey** -- Check existing project dependencies, official docs, and known pitfalls\n3. **Document** -- Produce `xbrief/proposed/{feature}-research.xbrief.json` with `DontHandRoll` and `CommonPitfalls` narratives\n4. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above\n\n## Anti-Patterns\n\n- ⊗ Building custom solutions for solved problems\n- ⊗ Skipping research for unfamiliar domains (\"how hard can auth be?\")\n- ⊗ Starting autonomous research before the Scope Confirmation Gate has captured or explicitly skipped user-provided artifacts/constraints\n- ⊗ Research that produces a reading list instead of actionable guidance\n- ⊗ Research that doesn't flow into planning (written and never referenced)\n- ⊗ Ending after research without chaining into specification generation (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))\n"
     },
     {
       "id": "roadmap",
@@ -141,7 +141,7 @@
         "speckit"
       ],
       "path": "strategies/speckit.md",
-      "body": "# SpecKit Strategy\n\nA spec-driven development workflow inspired by [GitHub's spec-kit](https://github.com/github/spec-kit), with a Phase 4.5 readiness layer for decomposing broad implementation scopes into swarm-safe stories. Fully migrated to v0.20 (phases + stories emitted as date-prefixed vBRIEFs in proposed/; no legacy specification.vbrief.json).\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Speckit now emits only the canonical v0.20 shape (date-prefixed phase/epic + story vBRIEFs in proposed/, full PROJECT-DEFINITION.xbrief.json via task project:render post, seeded lifecycle folders, no legacy specification.vbrief.json). Phase 4/4.5 scopes go to proposed/ (not pending/). Review exports use `task project:export-spec` (gate: export succeeded). See the dedicated ## v0.20 Output Shape section, the Artifacts Summary updated to the contract table, and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md) | [vbrief/vbrief.md](../vbrief/vbrief.md)\n\n## When to Use\n\n- ~ Large or complex projects with multiple contributors\n- ~ Projects requiring formal specification review\n- ~ When parallel agent development is planned\n- ~ Enterprise environments with compliance requirements\n- ? Skip Phase 1 if PROJECT-DEFINITION.xbrief.json Principles narrative already defined\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n    subgraph speckit [\"SpecKit Strategy (v0.20)\"]\n        P[\"📜 Principles<br/><i>PROJECT-DEFINITION.xbrief.json</i>\"]\n        S[\"📝 Specify<br/><i>WHAT/WHY → proposed/YYYY-MM-DD-*.xbrief.json</i>\"]\n        PL[\"🏗️ Plan<br/><i>HOW → proposed/YYYY-MM-DD-*.xbrief.json</i>\"]\n        T[\"✅ Scope<br/><i>Phase/epic vBRIEFs in proposed/</i>\"]\n        D[\"🧩 Decompose<br/><i>Story vBRIEFs in proposed/</i>\"]\n        I[\"🔨 Implement<br/><i>Execute</i>\"]\n    end\n\n    P -->|\"Established\"| S\n    S -->|\"Approved\"| PL\n    PL -->|\"Reviewed\"| T\n    T -->|\"Approved\"| D\n    D -->|\"Ready stories\"| I\n\n    style P fill:#c4b5fd,stroke:#7c3aed,color:#000\n    style S fill:#fef08a,stroke:#ca8a04,color:#000\n    style PL fill:#6ee7b7,stroke:#059669,color:#000\n    style T fill:#7dd3fc,stroke:#0284c7,color:#000\n    style D fill:#fde68a,stroke:#d97706,color:#000\n    style I fill:#f0abfc,stroke:#a855f7,color:#000\n```\n\n(See ## v0.20 Output Shape for exact artifact rules, the mandatory `task project:render` post call and `task project:export-spec` for review exports, and citation of strategies/v0-20-contract.md.)\n\n---\n\n## Phase 1: Principles\n\n**Goal:** Establish immutable project principles before any specification.\n\n**Output:** `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json` (v0.20: plus any early proposed/ context vBRIEFs if needed)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n### Process\n\n- ! Define 3-5 non-negotiable principles\n- ! Include at least one anti-principle (⊗)\n- ! Write principles as the `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json`\n- ~ Interview stakeholders about architectural constraints\n- ⊗ Proceed without defined principles\n- ⊗ Create a standalone `project.md` -- principles belong in PROJECT-DEFINITION.xbrief.json\n\n### Transition Criteria\n\n- ! `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json` is complete\n- ! All stakeholders have reviewed principles\n- ~ No `[NEEDS CLARIFICATION]` markers remain\n\n---\n\n## Phase 2: Specify (WHAT/WHY)\n\n**Goal:** Document WHAT to build and WHY, without implementation details.\n\n**Output:** WHAT/WHY narratives in date-prefixed vBRIEF(s) in `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (v0.20; no singular specification.vbrief.json)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\nWrite the following narrative keys into the proposed/ vBRIEF `plan.narratives`\n\n- `ProblemStatement` -- what problem this solves\n- `Goals` -- desired outcomes\n- `UserStories` -- user scenarios with priorities (P1, P2, P3) and acceptance scenarios (Given/When/Then)\n- `Requirements` -- numbered functional (FR-001) and non-functional (NFR-001) requirements\n- `SuccessMetrics` -- measurable success criteria (SC-001)\n- `EdgeCases` -- boundary conditions and error handling\n\n### Guidelines\n\n- ! Focus on WHAT users need and WHY\n- ! Use `[NEEDS CLARIFICATION: question]` for any ambiguity\n- ! Number all requirements (FR-001, NFR-001) for traceability\n- ! Prioritize user stories (P1, P2, P3)\n- ⊗ Include HOW to implement (no tech stack, APIs, code)\n- ⊗ Guess when uncertain -- mark it instead\n- ⊗ Create `specs/` directories or standalone `spec.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Transition Criteria\n\n- ! No `[NEEDS CLARIFICATION]` markers remain in narratives\n- ! All user stories have acceptance scenarios\n- ! Requirements are testable and unambiguous\n- ! Stakeholders have approved specification narratives\n\n---\n\n## Phase 3: Plan (HOW)\n\n**Goal:** Document HOW to build it with technical decisions.\n\n**Input:** Approved WHAT/WHY narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 2\n\n**Output:** HOW narratives enriching the proposed/ vBRIEF(s) (v0.20; no singular specification.vbrief.json)\n\nAdd the following narrative keys to the proposed/ vBRIEF `plan.narratives`:\n\n- `Architecture` -- high-level system design (components, data model, API contracts)\n- `TechDecisions` -- technology choices with rationale\n- `ImplementationPhases` -- phased delivery plan with dependencies\n- `PreImplementationGates` -- simplicity gate, test-first gate\n\n### Guidelines\n\n- ! Reference spec requirements (FR-001, etc.) from Phase 2 narratives\n- ! Document rationale for every technology choice\n- ! Pass all pre-implementation gates before proceeding\n- ⊗ Write implementation code\n- ⊗ Create `specs/` directories or standalone `plan.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Post-Phase 3 Transition Gate: Export for Review\n\n! Phase 3 -> Phase 4 is gated on a successful spec export for human review, mirroring the Phase 2 approval gate. Complete the steps below **in order** before advancing. [skills/deft-directive-setup/SKILL.md](../skills/deft-directive-setup/SKILL.md) is required to invoke `task project:export-spec` at this boundary when running speckit interactively; the gate fails silently otherwise (yolo-mode agents used to skip it -- that is what this gate exists to prevent).\n\n1. ! Run `task project:export-spec` (use `--audience=internal` when proposed scopes must appear in the `## Scope outlook` section). Legacy migrated trees MAY use `task spec:render` when `vbrief/specification.vbrief.json` exists.\n2. ! Confirm export **succeeded** (command exit 0) and `SPECIFICATION.md` exists at the project root with the greenfield banner (`<!-- Source of truth: xbrief/PROJECT-DEFINITION.xbrief.json -->`) or full-spec banner as appropriate.\n3. ! The proposed/ vBRIEFs + PROJECT-DEFINITION are the source of truth. `SPECIFICATION.md` is a read-only export.\n4. ! Human reviewer approves (or requests changes). On approval, proceed to Phase 4.\n\n### Transition Criteria\n\n- ! All gates pass (or exceptions documented)\n- ! Every spec requirement maps to a plan element\n- ! Architecture reviewed and approved\n- ! **Phase 3 -> Phase 4 transition criterion:** `task project:export-spec` succeeded (exit 0) AND the proposed/ date-prefixed vBRIEF(s) + PROJECT-DEFINITION represent the approved spec (agents MUST NOT advance to Phase 4 without review of the v0.20 artifacts).\n\n---\n\n## Phase 4: Implementation Phase / Epic Scope Emission (v0.20)\n\n**Goal:** Emit one broad scope vBRIEF per implementation phase or epic (plus stories via 4.5) so downstream tooling (`task roadmap:render`, `task project:render`, and Phase 4.5 decomposition) can operate against the lifecycle model described in [vbrief/vbrief.md](../vbrief/vbrief.md). All emitted to `proposed/` per v0.20 contract.\n\n**Input:** Approved HOW narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 3 (`ImplementationPhases` narrative describes IP-1..IP-N).\n\n**Output:** N phase/epic scope vBRIEFs in `./xbrief/proposed/`, one per implementation phase or epic, using the filename convention `YYYY-MM-DD-ip<NNN>-<slug>.xbrief.json` (NNN = 3-digit zero-padded, 001..N). See [vbrief/vbrief.md — speckit Phase 4 scope vBRIEFs](../vbrief/vbrief.md#speckit-phase-4-scope-vbriefs) for the canonical convention. (v0.20: proposed/ not pending/.)\n\nPhase 4 scopes are planning containers. They MAY keep broad acceptance in `plan.narratives.Acceptance` and MAY have `plan.items: []`. They are not valid concurrent swarm worker inputs unless explicitly marked as a single-story scope. Broad phase/epic scopes MUST pass through Phase 4.5 before swarm allocation.\n\n! After emitting the phase/epic scope vBRIEF(s) to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Scope vBRIEF Shape\n\nFor each implementation phase IP-N, write a scope vBRIEF with:\n\n- ! `vBRIEFInfo.version` — current `scripts/_vbrief_build.py::EMITTED_VBRIEF_VERSION`\n- ! `plan.title` — phase title (e.g. \"IP-3: Implement data layer\")\n- ! `plan.status` — `pending` (or proposed per lifecycle)\n- ! `plan.narratives.Description` — short human summary of the phase\n- ! `plan.narratives.Acceptance` — acceptance criteria copied from the spec\n- ! `plan.narratives.Traces` — FR/NFR/IP IDs the phase covers (e.g. `FR-001, FR-003, NFR-002, IP-3`)\n- ! `plan.references` — link back to the parent proposed/ vBRIEF from Phase 3 (`type: x-vbrief/plan`, `TrustLevel: internal`)\n- ! `plan.metadata.kind` — `phase` or `epic`\n- ! `plan.metadata.dependencies` — array of IP IDs this phase depends on / is blocked by (plan-level; mirrors the `edges[].blocks` structure used in earlier drafts)\n\n```json\n{\n  \"vBRIEFInfo\": { \"version\": \"<EMITTED_VBRIEF_VERSION>\" },\n  \"plan\": {\n    \"title\": \"IP-3: Implement data layer\",\n    \"status\": \"pending\",\n    \"narratives\": {\n      \"Description\": \"Stand up the data layer described in the Phase 3 proposed/ vBRIEF Architecture.\",\n      \"Acceptance\": \"Repository interfaces defined; CRUD round-trips pass integration tests.\",\n      \"Traces\": \"FR-001, FR-003, NFR-002, IP-3\"\n    },\n    \"metadata\": {\n      \"kind\": \"phase\",\n      \"dependencies\": [\"ip-1\", \"ip-2\"]\n    },\n    \"references\": [\n      { \"type\": \"x-vbrief/plan\", \"uri\": \"2026-05-26-ip002-plan.xbrief.json\", \"TrustLevel\": \"internal\" }\n    ],\n    \"items\": []\n  }\n}\n```\n\n### plan.xbrief.json — Session Tracker Only\n\n- ! `plan.xbrief.json` reverts to its canonical session-todo role defined in [vbrief/vbrief.md — plan.xbrief.json](../vbrief/vbrief.md#planvbriefjson). It is the agent-private tactical plan for the current session, not the project-wide IP list.\n- ! While working on a specific scope vBRIEF, `plan.xbrief.json` MUST carry a `planRef` to that scope vBRIEF in `xbrief/proposed/` or `xbrief/active/`.\n- ⊗ Emit the project-wide Phase 4 task list to `plan.vbrief.json` — write per-IP scope vBRIEFs to `xbrief/proposed/` instead.\n\n### Migrating Legacy speckit Projects\n\n- ~ Projects that already emitted a speckit-shaped `plan.vbrief.json` (project-wide IP list) can convert to the new model with:\n  ```\n  python scripts/migrate_vbrief.py --speckit-plan vbrief/plan.vbrief.json\n  ```\n  The translator emits one scope vBRIEF per IP into `vbrief/proposed/` (3-digit padded filenames, bilingual `edges` reader so both `from/to` and legacy `source/target` translate correctly) and writes the remaining session-level scaffold back to `plan.vbrief.json`.\n\n### Guidelines\n\n- ! Derive one scope vBRIEF per implementation phase from `ImplementationPhases`\n- ! Populate `Description`, `Acceptance`, and `Traces` narratives per [vbrief/vbrief.md — canonical narrative keys](../vbrief/vbrief.md#scope-vbrief-narrative-keys)\n- ! Use `plan.metadata.dependencies` (plan-level) rather than item-level `blocks` edges for cross-scope dependencies\n- ! Use `plan.metadata.kind = \"phase\"` or `\"epic\"` for broad implementation scopes\n- ~ Size each phase for 1-4 hours of work so the swarm allocator can distribute cleanly\n- ⊗ Create phases not traceable to a spec requirement\n- ⊗ Allocate Phase 4 phase/epic scope vBRIEFs directly to concurrent swarm workers\n\n### Transition Criteria\n\n- ! Every implementation phase from `ImplementationPhases` has a matching scope vBRIEF in `./xbrief/proposed/`\n- ! Each scope vBRIEF has `Description`, `Acceptance`, and `Traces` narratives\n- ! Each scope vBRIEF carries a `references` entry linking back to the parent Phase 3 proposed/ vBRIEF with `TrustLevel: internal`\n- ! Cross-scope dependencies in `plan.metadata.dependencies` form a valid DAG (no cycles)\n\n---\n\n## Phase 4.5: Story Decomposition / Swarm Readiness\n\n**Goal:** Convert approved Phase 4 phase/epic scopes into child story vBRIEFs suitable for parallel agents.\n\n**Input:** Phase 4 phase/epic xBRIEFs in `./xbrief/pending/` or `./xbrief/active/` (else legacy `./vbrief/pending/`).\n\n**Output:** Story-level child vBRIEFs whose executable acceptance criteria live in `plan.items` and whose `plan.metadata.swarm` contract proves they are safe to allocate.\n\n! After emitting the story vBRIEF(s) to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Process\n\n1. ! Inspect approved specification narratives and Phase 4 scope vBRIEFs.\n2. ! Identify `plan.metadata.kind = \"phase\"` or `\"epic\"` scopes that are too broad for direct implementation.\n3. ! Draft a deterministic decomposition proposal: stories, dependencies, expected file scope, verification commands, traces, and conflict groups.\n4. ! Store the temporary proposal artifact under `xbrief/.triage-cache/decompositions/<parent-slug>.json` (legacy scratch `vbrief/.triage-cache/decompositions/ip001-auth.json` is read-accepted); derive `<parent-slug>` from the parent vBRIEF filename by removing `.xbrief.json` or `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix.\n5. ! Ask for explicit user approval before writing child story vBRIEFs.\n6. ! Validate the approved draft with `task scope:decompose -- <parent.xbrief.json> --draft xbrief/.triage-cache/decompositions/<parent-slug>.json --check`, then apply it without `--check`.\n7. ! Run `task swarm:readiness -- xbrief/active/*.xbrief.json` before concurrent allocation, or point it at the candidate child story files for a dry readiness review before activation.\n\n### Story vBRIEF Requirements\n\nEach Phase 4.5 child story vBRIEF MUST include:\n\n- ! `plan.metadata.kind = \"story\"`\n- ! non-empty `plan.items`\n- ! `plan.narratives.Description` with at least two concrete sentences\n- ! `plan.narratives.ImplementationPlan` with at least two concrete implementation steps\n- ! executable acceptance in each story's `plan.items`\n- ! `plan.narratives.UserStory` in the form `As a <role>, I want <capability>, so that <outcome>.`\n- ! 2-5 concrete, observable acceptance criteria unless explicitly justified\n- ! explicit dependencies in `plan.metadata.swarm.depends_on`\n- ! traceability back to requirements via `Traces` narratives or explicit trace justification\n- ! expected file scope in `plan.metadata.swarm.file_scope`\n- ! verify commands in `plan.metadata.swarm.verify_commands`\n- ! expected outputs/evidence in `plan.metadata.swarm.expected_outputs`\n- ! swarm readiness metadata in `plan.metadata.swarm`\n- ! `planRef` pointing to the parent phase/epic scope\n- ! parent phase/epic `references` updated to point to every child story\n\n### Decomposition Command\n\nUse the deterministic command surface:\n\n```bash\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft vbrief/.triage-cache/decompositions/ip001-auth.json --check\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft vbrief/.triage-cache/decompositions/ip001-auth.json\ntask scope:decompose -- --check\n```\n\nThe draft JSON is a temporary proposal artifact, not a vBRIEF. Agents SHOULD write draft proposals under `xbrief/.triage-cache/decompositions/` (legacy `vbrief/.triage-cache/decompositions/` remains read-accepted), which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.xbrief.json` or `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix. Agents MUST NOT leave decomposition draft JSON files at the workspace root. The command validates and applies a proposed decomposition rather than freely inventing one. It creates generated child story vBRIEFs as lifecycle artifacts, defaulting to `xbrief/pending/`, preserves origin/provenance references, sets each child `planRef` to the parent scope, updates parent references to include children, validates the dependency DAG, rejects dependency cycles, and rejects ready stories missing user-story shape, concrete observable acceptance, narrow file scope, focused verify commands, or traces. Parent `plan.items` are input signals, not automatic child stories.\n\nParent phase/epic acceptance MAY remain in `plan.narratives.Acceptance` as context. Executable acceptance for swarm work MUST be redistributed into child story `plan.items`.\n\n### Swarm Readiness Command\n\nUse the readiness gate before swarm allocation:\n\n```bash\ntask swarm:readiness -- xbrief/active/*.xbrief.json\n```\n\nThe readiness report lists ready stories, blocked stories, decomposition-needed epics/phases, dependency waves, conflict groups, a file-overlap matrix, and missing fields. It exits non-zero when candidate work is not swarm-ready for concurrent allocation. `readiness=ready` means ready for concurrent allocation; sequential-safe or low-confidence work MUST use another state such as `sequential` or `needs_refinement` and will fail this gate until refined or scheduled outside concurrent swarm allocation.\n\n### Transition Criteria\n\n- ! Candidate swarm work consists only of `kind=story` vBRIEFs\n- ! Every candidate story has non-empty `plan.items`\n- ! Every candidate story has a product-shaped `UserStory`, 2-5 observable acceptance criteria unless justified, file scope, verify commands, traces or trace justification, and readiness metadata.\n- ! Dependencies resolve and form a DAG\n- ! No unsafe file-scope overlap exists among parallel stories\n- ! No `size=large` story is marked `parallel_safe=true`\n- ! No ready story uses broad file globs, only generic verification such as `task check`, `parallel_safe=false`, or `file_scope_confidence=low`\n\n---\n\n## Phase 5: Implement\n\n**Goal:** Execute scope vBRIEFs following test-first discipline.\n\n**Input:** Story-level scope vBRIEFs in `./xbrief/pending/` (promote to `./xbrief/active/` via `task scope:activate` when work begins). `./xbrief/plan.xbrief.json` holds the current session's tactical todo list and carries a `planRef` to the active scope. Concurrent swarm implementation requires Phase 4.5-ready stories.\n\n### Process\n\n- ! Write tests BEFORE implementation (Red)\n- ! Implement minimal code to pass tests (Green)\n- ! Refactor while keeping tests green (Refactor)\n- ! Update scope vBRIEF `plan.status` and folder via `task scope:*` commands as work progresses (`pending` → `running` → `completed`)\n- ! Update `./xbrief/plan.xbrief.json` session todos as tactical steps progress (session-scoped; do NOT put the project-wide IP list here)\n- ~ Work on story vBRIEFs whose `plan.metadata.swarm.depends_on` entries are already completed in parallel when possible\n\n### File Creation Order\n\n1. Create contract/API specifications\n2. Create test files (contract → integration → unit)\n3. Create source files to make tests pass\n4. Refactor and document\n\n### Guidelines\n\n- ! Follow the `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json` throughout\n- ! Move scope vBRIEFs through lifecycle folders using `task scope:activate|complete|cancel|block|unblock`\n- ⊗ Implement without failing tests first\n- ⊗ Skip refactoring phase\n- ⊗ Write the project-wide IP list to `plan.xbrief.json` — use `xbrief/pending/` scope vBRIEFs as the durable task tracker\n- ⊗ Allocate broad `kind=epic` or `kind=phase` scopes to concurrent swarm workers before decomposition\n\n---\n\n## Artifacts Summary (pre-v0.20, for reference only during migration)\n\n| Phase | Artifact | Purpose |\n|-------|----------|---------|\n| 1. Principles | `xbrief/PROJECT-DEFINITION.xbrief.json` | Governing rules (Principles narrative) |\n| 2. Specify | date-prefixed in `xbrief/proposed/` | WHAT/WHY narratives (v0.20) |\n| 3. Plan | date-prefixed in `xbrief/proposed/` | HOW narratives (enriches Phase 2; v0.20) |\n| 3b. Export (review) | `SPECIFICATION.md` (via `task project:export-spec`) | Read-only human review export (optional; gate requires export succeeded for Phase 3→4) |\n| 3c. Render PRD (derivative) | `PRD.md` (via `task prd:render`, sentinel only) | Optional stakeholder-review export |\n| 4. Tasks | `./xbrief/proposed/YYYY-MM-DD-ip<NNN>-<slug>.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json`; one per IP/epic) | Phase/epic scope vBRIEFs (v0.20: proposed/) drive roadmap/project render + decomposition |\n| 4.5. Story decomposition | Child story vBRIEFs with `plan.metadata.swarm` in proposed/ | Swarm-ready executable units (v0.20) |\n| 4b. Session todos | `./xbrief/plan.xbrief.json` | Session-level tactical plan (carries `planRef` to active scope) |\n| 5. Implement | Code + tests | Working software, optionally via swarm |\n\n## Directory Structure (v0.20)\n\n```\nproject/\n├── xbrief/\n│   ├── PROJECT-DEFINITION.xbrief.json  # Phase 1: Principles narrative\n│   ├── proposed/                       # Phase 2+: date-prefixed WHAT/WHY/HOW + IP scopes + stories\n│   │   └── YYYY-MM-DD-*.xbrief.json\n│   │   └── YYYY-MM-DD-ip001-....xbrief.json\n│   ├── plan.xbrief.json                # Phase 4b: session todos (planRef to active scope)\n│   └── pending/ active/ etc.           # Lifecycle (seeded empty or with promoted)\n├── SPECIFICATION.md                    # Optional export (task project:export-spec)\n├── PRD.md                              # Optional derivative (task prd:render; sentinel only)\n└── src/                                # Phase 5\n```\n\n(See ## v0.20 Output Shape and `strategies/v0-20-contract.md` for the authoritative table row for speckit.)\n\n---\n\n## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so speckit-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the speckit row from the #1166 inconsistency table and the s5 story acceptance criteria, including story-level vBRIEFs in proposed/ instead of only phase/epic in pending/).\n\n- ! Seed the five lifecycle folders under `xbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit all scope items (principles context, spec phases/stories, implementation phases/epics) exclusively as date-prefixed scope vBRIEFs in `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json` (or the ipNNN convention for phases per vbrief.md). For speckit, phases use `YYYY-MM-DD-ip<NNN>-<slug>.xbrief.json` in proposed/; stories from Phase 4.5 also in proposed/. Decompose plans into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ vBRIEFs are written (or at Phase 3/4 boundaries), invoke `task project:render` from the repo root to generate/refresh the complete `xbrief/PROJECT-DEFINITION.xbrief.json` (items registry derived from the lifecycle folders). For human review at Phase 3→4, invoke `task project:export-spec` (or `--audience=internal` when proposed scopes must appear in `## Scope outlook`).\n- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write). Live identity is `xbrief/PROJECT-DEFINITION.xbrief.json`; legacy `vbrief/PROJECT-DEFINITION.vbrief.json` is read-accepted until `deft migrate:xbrief`.\n- ~ `SPECIFICATION.md` / `PRD.md` at the project root, if produced at all, are read-only exports from `task project:export-spec` / `task prd:render`. The source of truth is the xbrief/ lifecycle (proposed/ phases + stories) + PROJECT-DEFINITION. Legacy `task spec:render` applies only to migrated trees with `vbrief/specification.vbrief.json`.\n- ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF (a1: date-prefixed stories in proposed/ + deterministic gate; a2: speckit story-level in proposed/ not only pending phases; a3: no legacy specification.vbrief.json) and the 1166 decomposition.\n- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row (speckit: Yes lifecycle; Yes PROJECT-DEFINITION Phase 1+; proposed/ (phases + stories date-prefixed); Never specification.vbrief.json; `task project:export-spec` for SPEC export).\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Speckit (full 5-phase with Phase 4/4.5):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `xbrief/PROJECT-DEFINITION.xbrief.json` | Principles + full items registry | Speckit Phase 1 + `task project:render` |\n| `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` + `YYYY-MM-DD-ipNNN-*.xbrief.json` | All spec (WHAT/WHY/HOW) + phases/epics/stories (date-prefixed; per v0.20 contract and vbrief.md speckit convention) | Speckit Phases 2-4.5 |\n| `xbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Speckit |\n| (optional export) `SPECIFICATION.md` / `PRD.md` | Human-readable spec export | `task project:export-spec` / `task prd:render` |\n| `xbrief/plan.xbrief.json` | Session-level tactical plan (planRef to active) | Speckit (internal) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `SPECIFICATION.md` or `PRD.md` at project root (without sentinel)\n- Phase/epic scopes in `pending/` (use `proposed/`)\n\nSee the full table and rules in `strategies/v0-20-contract.md` (speckit row reproduced above).\n\n---\n\n## Invoking This Strategy\n\nSet in PROJECT-DEFINITION.xbrief.json narratives:\n```json\n\"Strategy\": \"strategies/speckit.md\"\n```\n\nOr explicitly:\n```\nUse the speckit strategy for this project.\n```\n\nStart with:\n```\nI want to build [project] with features:\n1. [feature]\n2. [feature]\n```\n"
+      "body": "# SpecKit Strategy\n\nA spec-driven development workflow inspired by [GitHub's spec-kit](https://github.com/github/spec-kit), with a Phase 4.5 readiness layer for decomposing broad implementation scopes into swarm-safe stories. Fully migrated to v0.20 (phases + stories emitted as date-prefixed vBRIEFs in proposed/; no legacy specification.vbrief.json).\n\n**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Speckit now emits only the canonical v0.20 shape (date-prefixed phase/epic + story vBRIEFs in proposed/, full PROJECT-DEFINITION.xbrief.json via task project:render post, seeded lifecycle folders, no legacy specification.vbrief.json). Phase 4/4.5 scopes go to proposed/ (not pending/). Review exports use `task project:export-spec` (gate: export succeeded). See the dedicated ## v0.20 Output Shape section, the Artifacts Summary updated to the contract table, and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md) | [vbrief/vbrief.md](../vbrief/vbrief.md)\n\n## When to Use\n\n- ~ Large or complex projects with multiple contributors\n- ~ Projects requiring formal specification review\n- ~ When parallel agent development is planned\n- ~ Enterprise environments with compliance requirements\n- ? Skip Phase 1 if PROJECT-DEFINITION.xbrief.json Principles narrative already defined\n\n## Workflow Overview\n\n```mermaid\nflowchart LR\n    subgraph speckit [\"SpecKit Strategy (v0.20)\"]\n        P[\"📜 Principles<br/><i>PROJECT-DEFINITION.xbrief.json</i>\"]\n        S[\"📝 Specify<br/><i>WHAT/WHY → proposed/YYYY-MM-DD-*.xbrief.json</i>\"]\n        PL[\"🏗️ Plan<br/><i>HOW → proposed/YYYY-MM-DD-*.xbrief.json</i>\"]\n        T[\"✅ Scope<br/><i>Phase/epic vBRIEFs in proposed/</i>\"]\n        D[\"🧩 Decompose<br/><i>Story vBRIEFs in proposed/</i>\"]\n        I[\"🔨 Implement<br/><i>Execute</i>\"]\n    end\n\n    P -->|\"Established\"| S\n    S -->|\"Approved\"| PL\n    PL -->|\"Reviewed\"| T\n    T -->|\"Approved\"| D\n    D -->|\"Ready stories\"| I\n\n    style P fill:#c4b5fd,stroke:#7c3aed,color:#000\n    style S fill:#fef08a,stroke:#ca8a04,color:#000\n    style PL fill:#6ee7b7,stroke:#059669,color:#000\n    style T fill:#7dd3fc,stroke:#0284c7,color:#000\n    style D fill:#fde68a,stroke:#d97706,color:#000\n    style I fill:#f0abfc,stroke:#a855f7,color:#000\n```\n\n(See ## v0.20 Output Shape for exact artifact rules, the mandatory `task project:render` post call and `task project:export-spec` for review exports, and citation of strategies/v0-20-contract.md.)\n\n---\n\n## Phase 1: Principles\n\n**Goal:** Establish immutable project principles before any specification.\n\n**Output:** `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json` (v0.20: plus any early proposed/ context vBRIEFs if needed)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ items; Spec-Generating Guard for PROJECT-DEFINITION).\n\n### Process\n\n- ! Define 3-5 non-negotiable principles\n- ! Include at least one anti-principle (⊗)\n- ! Write principles as the `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json`\n- ~ Interview stakeholders about architectural constraints\n- ⊗ Proceed without defined principles\n- ⊗ Create a standalone `project.md` -- principles belong in PROJECT-DEFINITION.xbrief.json\n\n### Transition Criteria\n\n- ! `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json` is complete\n- ! All stakeholders have reviewed principles\n- ~ No `[NEEDS CLARIFICATION]` markers remain\n\n---\n\n## Phase 2: Specify (WHAT/WHY)\n\n**Goal:** Document WHAT to build and WHY, without implementation details.\n\n**Output:** WHAT/WHY narratives in date-prefixed vBRIEF(s) in `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (v0.20; no singular specification.vbrief.json)\n\n! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).\n\nWrite the following narrative keys into the proposed/ vBRIEF `plan.narratives`\n\n- `ProblemStatement` -- what problem this solves\n- `Goals` -- desired outcomes\n- `UserStories` -- user scenarios with priorities (P1, P2, P3) and acceptance scenarios (Given/When/Then)\n- `Requirements` -- numbered functional (FR-001) and non-functional (NFR-001) requirements\n- `SuccessMetrics` -- measurable success criteria (SC-001)\n- `EdgeCases` -- boundary conditions and error handling\n\n### Guidelines\n\n- ! Focus on WHAT users need and WHY\n- ! Use `[NEEDS CLARIFICATION: question]` for any ambiguity\n- ! Number all requirements (FR-001, NFR-001) for traceability\n- ! Prioritize user stories (P1, P2, P3)\n- ⊗ Include HOW to implement (no tech stack, APIs, code)\n- ⊗ Guess when uncertain -- mark it instead\n- ⊗ Create `specs/` directories or standalone `spec.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Transition Criteria\n\n- ! No `[NEEDS CLARIFICATION]` markers remain in narratives\n- ! All user stories have acceptance scenarios\n- ! Requirements are testable and unambiguous\n- ! Stakeholders have approved specification narratives\n\n---\n\n## Phase 3: Plan (HOW)\n\n**Goal:** Document HOW to build it with technical decisions.\n\n**Input:** Approved WHAT/WHY narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 2\n\n**Output:** HOW narratives enriching the proposed/ vBRIEF(s) (v0.20; no singular specification.vbrief.json)\n\nAdd the following narrative keys to the proposed/ vBRIEF `plan.narratives`:\n\n- `Architecture` -- high-level system design (components, data model, API contracts)\n- `TechDecisions` -- technology choices with rationale\n- `ImplementationPhases` -- phased delivery plan with dependencies\n- `PreImplementationGates` -- simplicity gate, test-first gate\n\n### Guidelines\n\n- ! Reference spec requirements (FR-001, etc.) from Phase 2 narratives\n- ! Document rationale for every technology choice\n- ! Pass all pre-implementation gates before proceeding\n- ⊗ Write implementation code\n- ⊗ Create `specs/` directories or standalone `plan.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)\n\n### Post-Phase 3 Transition Gate: Export for Review\n\n! Phase 3 -> Phase 4 is gated on a successful spec export for human review, mirroring the Phase 2 approval gate. Complete the steps below **in order** before advancing. [skills/deft-directive-setup/SKILL.md](../skills/deft-directive-setup/SKILL.md) is required to invoke `task project:export-spec` at this boundary when running speckit interactively; the gate fails silently otherwise (yolo-mode agents used to skip it -- that is what this gate exists to prevent).\n\n1. ! Run `task project:export-spec` (use `--audience=internal` when proposed scopes must appear in the `## Scope outlook` section). Legacy migrated trees MAY use `task spec:render` when `vbrief/specification.vbrief.json` exists.\n2. ! Confirm export **succeeded** (command exit 0) and `SPECIFICATION.md` exists at the project root with the greenfield banner (`<!-- Source of truth: xbrief/PROJECT-DEFINITION.xbrief.json -->`) or full-spec banner as appropriate.\n3. ! The proposed/ vBRIEFs + PROJECT-DEFINITION are the source of truth. `SPECIFICATION.md` is a read-only export.\n4. ! Human reviewer approves (or requests changes). On approval, proceed to Phase 4.\n\n### Transition Criteria\n\n- ! All gates pass (or exceptions documented)\n- ! Every spec requirement maps to a plan element\n- ! Architecture reviewed and approved\n- ! **Phase 3 -> Phase 4 transition criterion:** `task project:export-spec` succeeded (exit 0) AND the proposed/ date-prefixed vBRIEF(s) + PROJECT-DEFINITION represent the approved spec (agents MUST NOT advance to Phase 4 without review of the v0.20 artifacts).\n\n---\n\n## Phase 4: Implementation Phase / Epic Scope Emission (v0.20)\n\n**Goal:** Emit one broad scope vBRIEF per implementation phase or epic (plus stories via 4.5) so downstream tooling (`task roadmap:render`, `task project:render`, and Phase 4.5 decomposition) can operate against the lifecycle model described in [vbrief/vbrief.md](../vbrief/vbrief.md). All emitted to `proposed/` per v0.20 contract.\n\n**Input:** Approved HOW narratives in the proposed/ date-prefixed vBRIEF(s) from Phase 3 (`ImplementationPhases` narrative describes IP-1..IP-N).\n\n**Output:** N phase/epic scope vBRIEFs in `./xbrief/proposed/`, one per implementation phase or epic, using the filename convention `YYYY-MM-DD-ip<NNN>-<slug>.xbrief.json` (NNN = 3-digit zero-padded, 001..N). See [vbrief/vbrief.md — speckit Phase 4 scope vBRIEFs](../vbrief/vbrief.md#speckit-phase-4-scope-vbriefs) for the canonical convention. (v0.20: proposed/ not pending/.)\n\nPhase 4 scopes are planning containers. They MAY keep broad acceptance in `plan.narratives.Acceptance` and MAY have `plan.items: []`. They are not valid concurrent swarm worker inputs unless explicitly marked as a single-story scope. Broad phase/epic scopes MUST pass through Phase 4.5 before swarm allocation.\n\n! After emitting the phase/epic scope vBRIEF(s) to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Scope vBRIEF Shape\n\nFor each implementation phase IP-N, write a scope vBRIEF with:\n\n- ! `vBRIEFInfo.version` — current `the emitted xBRIEF schema version`\n- ! `plan.title` — phase title (e.g. \"IP-3: Implement data layer\")\n- ! `plan.status` — `pending` (or proposed per lifecycle)\n- ! `plan.narratives.Description` — short human summary of the phase\n- ! `plan.narratives.Acceptance` — acceptance criteria copied from the spec\n- ! `plan.narratives.Traces` — FR/NFR/IP IDs the phase covers (e.g. `FR-001, FR-003, NFR-002, IP-3`)\n- ! `plan.references` — link back to the parent proposed/ vBRIEF from Phase 3 (`type: x-vbrief/plan`, `TrustLevel: internal`)\n- ! `plan.metadata.kind` — `phase` or `epic`\n- ! `plan.metadata.dependencies` — array of IP IDs this phase depends on / is blocked by (plan-level; mirrors the `edges[].blocks` structure used in earlier drafts)\n\n```json\n{\n  \"vBRIEFInfo\": { \"version\": \"<EMITTED_VBRIEF_VERSION>\" },\n  \"plan\": {\n    \"title\": \"IP-3: Implement data layer\",\n    \"status\": \"pending\",\n    \"narratives\": {\n      \"Description\": \"Stand up the data layer described in the Phase 3 proposed/ vBRIEF Architecture.\",\n      \"Acceptance\": \"Repository interfaces defined; CRUD round-trips pass integration tests.\",\n      \"Traces\": \"FR-001, FR-003, NFR-002, IP-3\"\n    },\n    \"metadata\": {\n      \"kind\": \"phase\",\n      \"dependencies\": [\"ip-1\", \"ip-2\"]\n    },\n    \"references\": [\n      { \"type\": \"x-vbrief/plan\", \"uri\": \"2026-05-26-ip002-plan.xbrief.json\", \"TrustLevel\": \"internal\" }\n    ],\n    \"items\": []\n  }\n}\n```\n\n### plan.xbrief.json — Session Tracker Only\n\n- ! `plan.xbrief.json` reverts to its canonical session-todo role defined in [vbrief/vbrief.md — plan.xbrief.json](../vbrief/vbrief.md#planvbriefjson). It is the agent-private tactical plan for the current session, not the project-wide IP list.\n- ! While working on a specific scope vBRIEF, `plan.xbrief.json` MUST carry a `planRef` to that scope vBRIEF in `xbrief/proposed/` or `xbrief/active/`.\n- ⊗ Emit the project-wide Phase 4 task list to `plan.vbrief.json` — write per-IP scope vBRIEFs to `xbrief/proposed/` instead.\n\n### Migrating Legacy speckit Projects\n\n- ~ Projects that already emitted a speckit-shaped `plan.vbrief.json` (project-wide IP list) can convert to the new model with:\n  ```\n  Pin framework v0.59.0, then: task migrate:vbrief -- --speckit-plan vbrief/plan.vbrief.json\n  ```\n  The translator emits one scope vBRIEF per IP into `vbrief/proposed/` (3-digit padded filenames, bilingual `edges` reader so both `from/to` and legacy `source/target` translate correctly) and writes the remaining session-level scaffold back to `plan.vbrief.json`.\n\n### Guidelines\n\n- ! Derive one scope vBRIEF per implementation phase from `ImplementationPhases`\n- ! Populate `Description`, `Acceptance`, and `Traces` narratives per [vbrief/vbrief.md — canonical narrative keys](../vbrief/vbrief.md#scope-vbrief-narrative-keys)\n- ! Use `plan.metadata.dependencies` (plan-level) rather than item-level `blocks` edges for cross-scope dependencies\n- ! Use `plan.metadata.kind = \"phase\"` or `\"epic\"` for broad implementation scopes\n- ~ Size each phase for 1-4 hours of work so the swarm allocator can distribute cleanly\n- ⊗ Create phases not traceable to a spec requirement\n- ⊗ Allocate Phase 4 phase/epic scope vBRIEFs directly to concurrent swarm workers\n\n### Transition Criteria\n\n- ! Every implementation phase from `ImplementationPhases` has a matching scope vBRIEF in `./xbrief/proposed/`\n- ! Each scope vBRIEF has `Description`, `Acceptance`, and `Traces` narratives\n- ! Each scope vBRIEF carries a `references` entry linking back to the parent Phase 3 proposed/ vBRIEF with `TrustLevel: internal`\n- ! Cross-scope dependencies in `plan.metadata.dependencies` form a valid DAG (no cycles)\n\n---\n\n## Phase 4.5: Story Decomposition / Swarm Readiness\n\n**Goal:** Convert approved Phase 4 phase/epic scopes into child story vBRIEFs suitable for parallel agents.\n\n**Input:** Phase 4 phase/epic xBRIEFs in `./xbrief/pending/` or `./xbrief/active/` (else legacy `./vbrief/pending/`).\n\n**Output:** Story-level child vBRIEFs whose executable acceptance criteria live in `plan.items` and whose `plan.metadata.swarm` contract proves they are safe to allocate.\n\n! After emitting the story vBRIEF(s) to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).\n\n### Process\n\n1. ! Inspect approved specification narratives and Phase 4 scope vBRIEFs.\n2. ! Identify `plan.metadata.kind = \"phase\"` or `\"epic\"` scopes that are too broad for direct implementation.\n3. ! Draft a deterministic decomposition proposal: stories, dependencies, expected file scope, verification commands, traces, and conflict groups.\n4. ! Store the temporary proposal artifact under `xbrief/.triage-cache/decompositions/<parent-slug>.json` (legacy scratch `vbrief/.triage-cache/decompositions/ip001-auth.json` is read-accepted); derive `<parent-slug>` from the parent vBRIEF filename by removing `.xbrief.json` or `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix.\n5. ! Ask for explicit user approval before writing child story vBRIEFs.\n6. ! Validate the approved draft with `task scope:decompose -- <parent.xbrief.json> --draft xbrief/.triage-cache/decompositions/<parent-slug>.json --check`, then apply it without `--check`.\n7. ! Run `task swarm:readiness -- xbrief/active/*.xbrief.json` before concurrent allocation, or point it at the candidate child story files for a dry readiness review before activation.\n\n### Story vBRIEF Requirements\n\nEach Phase 4.5 child story vBRIEF MUST include:\n\n- ! `plan.metadata.kind = \"story\"`\n- ! non-empty `plan.items`\n- ! `plan.narratives.Description` with at least two concrete sentences\n- ! `plan.narratives.ImplementationPlan` with at least two concrete implementation steps\n- ! executable acceptance in each story's `plan.items`\n- ! `plan.narratives.UserStory` in the form `As a <role>, I want <capability>, so that <outcome>.`\n- ! 2-5 concrete, observable acceptance criteria unless explicitly justified\n- ! explicit dependencies in `plan.metadata.swarm.depends_on`\n- ! traceability back to requirements via `Traces` narratives or explicit trace justification\n- ! expected file scope in `plan.metadata.swarm.file_scope`\n- ! verify commands in `plan.metadata.swarm.verify_commands`\n- ! expected outputs/evidence in `plan.metadata.swarm.expected_outputs`\n- ! swarm readiness metadata in `plan.metadata.swarm`\n- ! `planRef` pointing to the parent phase/epic scope\n- ! parent phase/epic `references` updated to point to every child story\n\n### Decomposition Command\n\nUse the deterministic command surface:\n\n```bash\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft vbrief/.triage-cache/decompositions/ip001-auth.json --check\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft vbrief/.triage-cache/decompositions/ip001-auth.json\ntask scope:decompose -- --check\n```\n\nThe draft JSON is a temporary proposal artifact, not a vBRIEF. Agents SHOULD write draft proposals under `xbrief/.triage-cache/decompositions/` (legacy `vbrief/.triage-cache/decompositions/` remains read-accepted), which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.xbrief.json` or `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix. Agents MUST NOT leave decomposition draft JSON files at the workspace root. The command validates and applies a proposed decomposition rather than freely inventing one. It creates generated child story vBRIEFs as lifecycle artifacts, defaulting to `xbrief/pending/`, preserves origin/provenance references, sets each child `planRef` to the parent scope, updates parent references to include children, validates the dependency DAG, rejects dependency cycles, and rejects ready stories missing user-story shape, concrete observable acceptance, narrow file scope, focused verify commands, or traces. Parent `plan.items` are input signals, not automatic child stories.\n\nParent phase/epic acceptance MAY remain in `plan.narratives.Acceptance` as context. Executable acceptance for swarm work MUST be redistributed into child story `plan.items`.\n\n### Swarm Readiness Command\n\nUse the readiness gate before swarm allocation:\n\n```bash\ntask swarm:readiness -- xbrief/active/*.xbrief.json\n```\n\nThe readiness report lists ready stories, blocked stories, decomposition-needed epics/phases, dependency waves, conflict groups, a file-overlap matrix, and missing fields. It exits non-zero when candidate work is not swarm-ready for concurrent allocation. `readiness=ready` means ready for concurrent allocation; sequential-safe or low-confidence work MUST use another state such as `sequential` or `needs_refinement` and will fail this gate until refined or scheduled outside concurrent swarm allocation.\n\n### Transition Criteria\n\n- ! Candidate swarm work consists only of `kind=story` vBRIEFs\n- ! Every candidate story has non-empty `plan.items`\n- ! Every candidate story has a product-shaped `UserStory`, 2-5 observable acceptance criteria unless justified, file scope, verify commands, traces or trace justification, and readiness metadata.\n- ! Dependencies resolve and form a DAG\n- ! No unsafe file-scope overlap exists among parallel stories\n- ! No `size=large` story is marked `parallel_safe=true`\n- ! No ready story uses broad file globs, only generic verification such as `task check`, `parallel_safe=false`, or `file_scope_confidence=low`\n\n---\n\n## Phase 5: Implement\n\n**Goal:** Execute scope vBRIEFs following test-first discipline.\n\n**Input:** Story-level scope vBRIEFs in `./xbrief/pending/` (promote to `./xbrief/active/` via `task scope:activate` when work begins). `./xbrief/plan.xbrief.json` holds the current session's tactical todo list and carries a `planRef` to the active scope. Concurrent swarm implementation requires Phase 4.5-ready stories.\n\n### Process\n\n- ! Write tests BEFORE implementation (Red)\n- ! Implement minimal code to pass tests (Green)\n- ! Refactor while keeping tests green (Refactor)\n- ! Update scope vBRIEF `plan.status` and folder via `task scope:*` commands as work progresses (`pending` → `running` → `completed`)\n- ! Update `./xbrief/plan.xbrief.json` session todos as tactical steps progress (session-scoped; do NOT put the project-wide IP list here)\n- ~ Work on story vBRIEFs whose `plan.metadata.swarm.depends_on` entries are already completed in parallel when possible\n\n### File Creation Order\n\n1. Create contract/API specifications\n2. Create test files (contract → integration → unit)\n3. Create source files to make tests pass\n4. Refactor and document\n\n### Guidelines\n\n- ! Follow the `Principles` narrative in `xbrief/PROJECT-DEFINITION.xbrief.json` throughout\n- ! Move scope vBRIEFs through lifecycle folders using `task scope:activate|complete|cancel|block|unblock`\n- ⊗ Implement without failing tests first\n- ⊗ Skip refactoring phase\n- ⊗ Write the project-wide IP list to `plan.xbrief.json` — use `xbrief/pending/` scope vBRIEFs as the durable task tracker\n- ⊗ Allocate broad `kind=epic` or `kind=phase` scopes to concurrent swarm workers before decomposition\n\n---\n\n## Artifacts Summary (pre-v0.20, for reference only during migration)\n\n| Phase | Artifact | Purpose |\n|-------|----------|---------|\n| 1. Principles | `xbrief/PROJECT-DEFINITION.xbrief.json` | Governing rules (Principles narrative) |\n| 2. Specify | date-prefixed in `xbrief/proposed/` | WHAT/WHY narratives (v0.20) |\n| 3. Plan | date-prefixed in `xbrief/proposed/` | HOW narratives (enriches Phase 2; v0.20) |\n| 3b. Export (review) | `SPECIFICATION.md` (via `task project:export-spec`) | Read-only human review export (optional; gate requires export succeeded for Phase 3→4) |\n| 3c. Render PRD (derivative) | `PRD.md` (via `task prd:render`, sentinel only) | Optional stakeholder-review export |\n| 4. Tasks | `./xbrief/proposed/YYYY-MM-DD-ip<NNN>-<slug>.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json`; one per IP/epic) | Phase/epic scope vBRIEFs (v0.20: proposed/) drive roadmap/project render + decomposition |\n| 4.5. Story decomposition | Child story vBRIEFs with `plan.metadata.swarm` in proposed/ | Swarm-ready executable units (v0.20) |\n| 4b. Session todos | `./xbrief/plan.xbrief.json` | Session-level tactical plan (carries `planRef` to active scope) |\n| 5. Implement | Code + tests | Working software, optionally via swarm |\n\n## Directory Structure (v0.20)\n\n```\nproject/\n├── xbrief/\n│   ├── PROJECT-DEFINITION.xbrief.json  # Phase 1: Principles narrative\n│   ├── proposed/                       # Phase 2+: date-prefixed WHAT/WHY/HOW + IP scopes + stories\n│   │   └── YYYY-MM-DD-*.xbrief.json\n│   │   └── YYYY-MM-DD-ip001-....xbrief.json\n│   ├── plan.xbrief.json                # Phase 4b: session todos (planRef to active scope)\n│   └── pending/ active/ etc.           # Lifecycle (seeded empty or with promoted)\n├── SPECIFICATION.md                    # Optional export (task project:export-spec)\n├── PRD.md                              # Optional derivative (task prd:render; sentinel only)\n└── src/                                # Phase 5\n```\n\n(See ## v0.20 Output Shape and `strategies/v0-20-contract.md` for the authoritative table row for speckit.)\n\n---\n\n## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)\n\nThis strategy has been migrated to the full v0.20 output shape so speckit-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the speckit row from the #1166 inconsistency table and the s5 story acceptance criteria, including story-level vBRIEFs in proposed/ instead of only phase/epic in pending/).\n\n- ! Seed the five lifecycle folders under `xbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.\n- ! Emit all scope items (principles context, spec phases/stories, implementation phases/epics) exclusively as date-prefixed scope vBRIEFs in `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json` (or the ipNNN convention for phases per vbrief.md). For speckit, phases use `YYYY-MM-DD-ip<NNN>-<slug>.xbrief.json` in proposed/; stories from Phase 4.5 also in proposed/. Decompose plans into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.\n- ! After the proposed/ vBRIEFs are written (or at Phase 3/4 boundaries), invoke `task project:render` from the repo root to generate/refresh the complete `xbrief/PROJECT-DEFINITION.xbrief.json` (items registry derived from the lifecycle folders). For human review at Phase 3→4, invoke `task project:export-spec` (or `--audience=internal` when proposed scopes must appear in `## Scope outlook`).\n- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write). Live identity is `xbrief/PROJECT-DEFINITION.xbrief.json`; legacy `vbrief/PROJECT-DEFINITION.vbrief.json` is read-accepted until `deft migrate:xbrief`.\n- ~ `SPECIFICATION.md` / `PRD.md` at the project root, if produced at all, are read-only exports from `task project:export-spec` / `task prd:render`. The source of truth is the xbrief/ lifecycle (proposed/ phases + stories) + PROJECT-DEFINITION. Legacy `task spec:render` applies only to migrated trees with `vbrief/specification.vbrief.json`.\n- ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).\n- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF (a1: date-prefixed stories in proposed/ + deterministic gate; a2: speckit story-level in proposed/ not only pending phases; a3: no legacy specification.vbrief.json) and the 1166 decomposition.\n- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row (speckit: Yes lifecycle; Yes PROJECT-DEFINITION Phase 1+; proposed/ (phases + stories date-prefixed); Never specification.vbrief.json; `task project:export-spec` for SPEC export).\n\n---\n\n## Artifacts Summary (v0.20)\n\n**Speckit (full 5-phase with Phase 4/4.5):**\n\n| Artifact | Purpose | Created By |\n|----------|---------|------------|\n| `xbrief/PROJECT-DEFINITION.xbrief.json` | Principles + full items registry | Speckit Phase 1 + `task project:render` |\n| `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` + `YYYY-MM-DD-ipNNN-*.xbrief.json` | All spec (WHAT/WHY/HOW) + phases/epics/stories (date-prefixed; per v0.20 contract and vbrief.md speckit convention) | Speckit Phases 2-4.5 |\n| `xbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Speckit |\n| (optional export) `SPECIFICATION.md` / `PRD.md` | Human-readable spec export | `task project:export-spec` / `task prd:render` |\n| `xbrief/plan.xbrief.json` | Session-level tactical plan (planRef to active) | Speckit (internal) |\n\n**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**\n\n- `vbrief/specification.vbrief.json`\n- Primary handoff `SPECIFICATION.md` or `PRD.md` at project root (without sentinel)\n- Phase/epic scopes in `pending/` (use `proposed/`)\n\nSee the full table and rules in `strategies/v0-20-contract.md` (speckit row reproduced above).\n\n---\n\n## Invoking This Strategy\n\nSet in PROJECT-DEFINITION.xbrief.json narratives:\n```json\n\"Strategy\": \"strategies/speckit.md\"\n```\n\nOr explicitly:\n```\nUse the speckit strategy for this project.\n```\n\nStart with:\n```\nI want to build [project] with features:\n1. [feature]\n2. [feature]\n```\n"
     },
     {
       "id": "v0-20-contract",
@@ -151,7 +151,7 @@
         "v0-20-contract"
       ],
       "path": "strategies/v0-20-contract.md",
-      "body": "# v0.20 Strategy Output Contract\n\nCanonical contract for the artifacts that every spec-generating strategy MUST produce to be v0.20-conformant.\n\n**Legend (from RFC2119):** !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/README.md](./README.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [skills/deft-directive-build/SKILL.md](../skills/deft-directive-build/SKILL.md) (Pre-Cutover Detection Guard) | [scripts/migrate_vbrief.py](../../scripts/migrate_vbrief.py) | [conventions/machine-generated-banner.md](../conventions/machine-generated-banner.md)\n\n---\n\n## Purpose\n\nSpec-generating strategies (interview, yolo, speckit, rapid, enterprise) historically produced inconsistent artifacts:\n\n- Some wrote only the legacy `vbrief/specification.vbrief.json` + root `SPECIFICATION.md`\n- Some wrote scope vBRIEFs without date prefixes and still dual-wrote the old singular spec file\n- None consistently seeded the full v0.20 lifecycle folders + `PROJECT-DEFINITION.xbrief.json` + date-prefixed proposed/ items\n\nThis caused immediate build failures via the Pre-Cutover Detection Guard for any project generated through those strategies.\n\nThis contract is the single source of truth. All future strategy implementations and migrations target exactly these artifacts. The build skill, vbrief validators, and (post-s2) deterministic shape gate enforce it.\n\n## When to Use\n\nUse this contract when authoring, reviewing, or migrating a spec-generating strategy that creates project definition artifacts, scope vBRIEFs, rendered views, or migration handoff material. It also applies when a guard, validator, or setup path needs to decide whether a project is current v0.20 output or legacy pre-cutover content.\n\n## Workflow\n\n1. Identify whether the strategy is spec-generating or preparatory.\n2. Apply the matching row in the per-strategy summary table.\n3. Create the required lifecycle folders before writing scope artifacts.\n4. Write authoritative vBRIEF content to `xbrief/PROJECT-DEFINITION.xbrief.json` and date-prefixed `xbrief/proposed/*.xbrief.json` files.\n5. Omit root `SPECIFICATION.md` / `PROJECT.md`, or write only deprecation redirect stubs when transitional UX requires them.\n6. Run the validator and content gates before treating the strategy output as v0.20-conformant.\n\n## Canonical v0.20 Output Shape\n\nFor a project that has completed any spec-generating strategy (or the full speckit flow), the following MUST exist and be the only authoritative sources:\n\n### Required Directory Structure\n- `xbrief/proposed/`\n- `xbrief/pending/`\n- `xbrief/active/`\n- `xbrief/completed/`\n- `xbrief/cancelled/`\n\nAll five lifecycle folders MUST be present (even if empty). This is the cutover signal used by pre-cutover guards.\n\n### Required Root-Level vBRIEF Artifact\n- `xbrief/PROJECT-DEFINITION.xbrief.json` (complete: narratives + items registry populated from the strategy session)\n\n`task project:render` MAY be invoked by the strategy or left to the user; the end state after strategy + any render MUST have a non-skeleton PROJECT-DEFINITION.\n\n### Scope vBRIEF Placement & Naming (Strict)\n- All new scope vBRIEFs (user stories, phases, epics from speckit Phase 4/4.5, etc.) MUST be written **only** to `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json`\n- Filenames MUST be date-prefixed using the creation date (immutable per vbrief.md conventions)\n- Bare names (e.g. `scaffold.vbrief.json`) or names without date prefix are FORBIDDEN in v0.20\n- The old singular `vbrief/specification.vbrief.json` MUST NOT be written or updated by v0.20 strategies (it is a legacy container; new work uses the lifecycle folders + PROJECT-DEFINITION)\n\n### SPECIFICATION.md & PROJECT.md (Derivative / Deprecated)\n- Strategies SHOULD OMIT writing `SPECIFICATION.md` and `PROJECT.md` entirely. These are **rendered views** only.\n- If a strategy does emit them (for UX continuity during transition), they MUST be written **exclusively** as deprecation-redirect stubs:\n  - Start with the canonical 4-line machine-generated banner (see conventions/machine-generated-banner.md)\n  - Fifth line: `<!-- deft:deprecated-redirect -->`\n  - Short explanatory body pointing to `xbrief/PROJECT-DEFINITION.xbrief.json` and the lifecycle folders\n  - Never contain real spec or project content\n- Real content in these files (without the sentinel) triggers the build/setup/sync pre-cutover guards and forces migration.\n\n### Legacy `specification.vbrief.json`\n- ⊗ No v0.20 strategy may create or dual-write `vbrief/specification.vbrief.json` alongside the new model artifacts.\n- Existing legacy files are handled only by `task migrate:vbrief` (which ingests them into scope vBRIEFs + PROJECT-DEFINITION and leaves a redirect stub at root if needed).\n\n### Greenfield spec export (#2013 / #1502)\n\nGreenfield projects (no `vbrief/specification.vbrief.json`) export stakeholder-facing spec text via `task project:export-spec`:\n\n- ! Source of truth: `xbrief/PROJECT-DEFINITION.xbrief.json` product narratives + lifecycle scope bodies (never the legacy singular spec file).\n- ! Default audience is **stakeholder** — proposed scopes are omitted; only pending/active/completed scopes appear under `## Scope outlook`.\n- ! Internal handoff (setup Phase 3, speckit Phase 3→4 when proposed scopes must be visible) uses `task project:export-spec -- --audience=internal`, which adds `### Not yet accepted (proposed)` under `## Scope outlook` with a fixed disclaimer that proposed scopes are ideas, not approved backlog.\n- ! Phase 3→4 transition gate: **export succeeded** (exit 0), not spec-file `approved` status — PROJECT-DEFINITION has no spec-approval lifecycle on greenfield trees.\n- ~ Legacy migrated trees with `vbrief/specification.vbrief.json` MAY continue using `task spec:render` until fully cut over.\n- ⊗ Invoke `task spec:render` on a greenfield tree that lacks `specification.vbrief.json` — use `task project:export-spec` instead.\n\n### plan.xbrief.json and continue.xbrief.json\n- Session/tactical state files are permitted at xbrief/ root (they carry `planRef` links). They are not part of the \"spec output\" contract but strategies that maintain chaining state (e.g. interview) update them per their own rules.\n\n## Per-Strategy Summary Table (Target State After Migration)\n\n| Strategy     | Type             | Must Create Lifecycle Folders | Must Write PROJECT-DEFINITION | Scope vBRIEFs Location                  | specification.vbrief.json | SPECIFICATION.md / PROJECT.md          |\n|--------------|------------------|-------------------------------|-------------------------------|-----------------------------------------|-----------------------------|----------------------------------------|\n| interview    | spec-generating  | Yes                           | Yes (narratives + items)      | proposed/YYYY-MM-DD-*.xbrief.json only  | Never (post-migration)      | Omit or deprecation redirect only      |\n| yolo         | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |\n| speckit      | spec-generating  | Yes                           | Yes (Phase 1+)                | proposed/YYYY-MM-DD-*.xbrief.json only (phases + stories) | Never             | Omit or `task project:export-spec` (legacy: `task spec:render` on migrated trees) |\n| rapid        | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |\n| enterprise   | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |\n| preparatory (research, discuss, map, etc.) | preparatory | Yes (if first touch)         | No (unless also spec path)    | proposed/YYYY-MM-DD-*.xbrief.json (context/decision vBRIEFs) | N/A                    | N/A (preparatory only)                 |\n\n## Agent & Strategy Author Rules\n\n- ! Every spec-generating strategy document MUST contain an \"Artifacts\" or \"Output\" section that explicitly cites this contract (`strategies/v0-20-contract.md`) and reproduces the relevant row from the table above.\n- ! Before emitting any vBRIEF artifact, follow the guards in `artifact-guards.md` (updated to reference this contract).\n- ! Date prefixes on scope vBRIEFs are mandatory for swarm readiness, filename sorting, and dedup.\n- ⊗ Write real content to root SPECIFICATION.md or PROJECT.md from a strategy.\n- ⊗ Emit bare-named vBRIEFs in proposed/ or anywhere outside the dated convention.\n- ⊗ Dual-write the old `specification.vbrief.json` in a v0.20 flow.\n\n## Verification & Enforcement\n\n- Build / setup / sync skills: Pre-Cutover Detection Guard (any missing lifecycle folder or real-content legacy md triggers redirect to migrate).\n- `task vbrief:validate` + `task check`: filename convention, folder/status consistency, PROJECT-DEFINITION presence.\n- Post-s2: deterministic validation gate (s2 story) will parse strategy output trees against this contract and fail non-conformant generations.\n- Content tests + migration stories exercise the before/after shapes.\n\n## Migration Path for Existing Strategies\n\nThe s3/s4/s5 stories migrate the individual strategy files (and their emitted examples) to the shape defined here. This contract document is the target spec they implement against; do not change strategies first.\n\n## When to Use\n\nUse this contract when:\n- Authoring a new spec-generating strategy (interview, yolo, speckit, rapid, enterprise, etc.).\n- Migrating an existing strategy to v0.20 (the s3/s4/s5 work).\n- Implementing or updating the deterministic validation gate (s2) or build pre-cutover guards.\n- Writing migration tooling (`migrate_vbrief.py`, reconcile scripts, etc.).\n- Auditing a generated project for v0.20 conformance.\n\n## Workflow\n\n1. Read the Canonical v0.20 Output Shape section.\n2. Ensure your strategy (or migration) writes exactly the required folders + `PROJECT-DEFINITION.xbrief.json` + dated proposed/ vBRIEFs.\n3. Never write the legacy `specification.vbrief.json` or real-content `SPECIFICATION.md`/`PROJECT.md`.\n4. Cite this contract explicitly in your strategy's \"Artifacts\" / \"Output\" section (see the Per-Strategy Summary Table).\n5. Run `task check` (or the deterministic gate once s2 lands) to validate.\n\n---\n\n**Owned by**: `xbrief/active/2026-05-26-define-canonical-v020-strategy-output-contract.vbrief.json` (s1-contract of #1166 strategy consistency decomposition)\n\nThis contract lands first so that s2 (gate) and the migration stories have an unambiguous target.\n"
+      "body": "# v0.20 Strategy Output Contract\n\nCanonical contract for the artifacts that every spec-generating strategy MUST produce to be v0.20-conformant.\n\n**Legend (from RFC2119):** !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**: [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/README.md](./README.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [skills/deft-directive-build/SKILL.md](../skills/deft-directive-build/SKILL.md) (Pre-Cutover Detection Guard) | [the frozen v0.59.0 migrator](../../UPGRADING.md) | [conventions/machine-generated-banner.md](../conventions/machine-generated-banner.md)\n\n---\n\n## Purpose\n\nSpec-generating strategies (interview, yolo, speckit, rapid, enterprise) historically produced inconsistent artifacts:\n\n- Some wrote only the legacy `vbrief/specification.vbrief.json` + root `SPECIFICATION.md`\n- Some wrote scope vBRIEFs without date prefixes and still dual-wrote the old singular spec file\n- None consistently seeded the full v0.20 lifecycle folders + `PROJECT-DEFINITION.xbrief.json` + date-prefixed proposed/ items\n\nThis caused immediate build failures via the Pre-Cutover Detection Guard for any project generated through those strategies.\n\nThis contract is the single source of truth. All future strategy implementations and migrations target exactly these artifacts. The build skill, vbrief validators, and (post-s2) deterministic shape gate enforce it.\n\n## When to Use\n\nUse this contract when authoring, reviewing, or migrating a spec-generating strategy that creates project definition artifacts, scope vBRIEFs, rendered views, or migration handoff material. It also applies when a guard, validator, or setup path needs to decide whether a project is current v0.20 output or legacy pre-cutover content.\n\n## Workflow\n\n1. Identify whether the strategy is spec-generating or preparatory.\n2. Apply the matching row in the per-strategy summary table.\n3. Create the required lifecycle folders before writing scope artifacts.\n4. Write authoritative vBRIEF content to `xbrief/PROJECT-DEFINITION.xbrief.json` and date-prefixed `xbrief/proposed/*.xbrief.json` files.\n5. Omit root `SPECIFICATION.md` / `PROJECT.md`, or write only deprecation redirect stubs when transitional UX requires them.\n6. Run the validator and content gates before treating the strategy output as v0.20-conformant.\n\n## Canonical v0.20 Output Shape\n\nFor a project that has completed any spec-generating strategy (or the full speckit flow), the following MUST exist and be the only authoritative sources:\n\n### Required Directory Structure\n- `xbrief/proposed/`\n- `xbrief/pending/`\n- `xbrief/active/`\n- `xbrief/completed/`\n- `xbrief/cancelled/`\n\nAll five lifecycle folders MUST be present (even if empty). This is the cutover signal used by pre-cutover guards.\n\n### Required Root-Level vBRIEF Artifact\n- `xbrief/PROJECT-DEFINITION.xbrief.json` (complete: narratives + items registry populated from the strategy session)\n\n`task project:render` MAY be invoked by the strategy or left to the user; the end state after strategy + any render MUST have a non-skeleton PROJECT-DEFINITION.\n\n### Scope vBRIEF Placement & Naming (Strict)\n- All new scope vBRIEFs (user stories, phases, epics from speckit Phase 4/4.5, etc.) MUST be written **only** to `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json`\n- Filenames MUST be date-prefixed using the creation date (immutable per vbrief.md conventions)\n- Bare names (e.g. `scaffold.vbrief.json`) or names without date prefix are FORBIDDEN in v0.20\n- The old singular `vbrief/specification.vbrief.json` MUST NOT be written or updated by v0.20 strategies (it is a legacy container; new work uses the lifecycle folders + PROJECT-DEFINITION)\n\n### SPECIFICATION.md & PROJECT.md (Derivative / Deprecated)\n- Strategies SHOULD OMIT writing `SPECIFICATION.md` and `PROJECT.md` entirely. These are **rendered views** only.\n- If a strategy does emit them (for UX continuity during transition), they MUST be written **exclusively** as deprecation-redirect stubs:\n  - Start with the canonical 4-line machine-generated banner (see conventions/machine-generated-banner.md)\n  - Fifth line: `<!-- deft:deprecated-redirect -->`\n  - Short explanatory body pointing to `xbrief/PROJECT-DEFINITION.xbrief.json` and the lifecycle folders\n  - Never contain real spec or project content\n- Real content in these files (without the sentinel) triggers the build/setup/sync pre-cutover guards and forces migration.\n\n### Legacy `specification.vbrief.json`\n- ⊗ No v0.20 strategy may create or dual-write `vbrief/specification.vbrief.json` alongside the new model artifacts.\n- Existing legacy files are handled only by `task migrate:vbrief` (which ingests them into scope vBRIEFs + PROJECT-DEFINITION and leaves a redirect stub at root if needed).\n\n### Greenfield spec export (#2013 / #1502)\n\nGreenfield projects (no `vbrief/specification.vbrief.json`) export stakeholder-facing spec text via `task project:export-spec`:\n\n- ! Source of truth: `xbrief/PROJECT-DEFINITION.xbrief.json` product narratives + lifecycle scope bodies (never the legacy singular spec file).\n- ! Default audience is **stakeholder** — proposed scopes are omitted; only pending/active/completed scopes appear under `## Scope outlook`.\n- ! Internal handoff (setup Phase 3, speckit Phase 3→4 when proposed scopes must be visible) uses `task project:export-spec -- --audience=internal`, which adds `### Not yet accepted (proposed)` under `## Scope outlook` with a fixed disclaimer that proposed scopes are ideas, not approved backlog.\n- ! Phase 3→4 transition gate: **export succeeded** (exit 0), not spec-file `approved` status — PROJECT-DEFINITION has no spec-approval lifecycle on greenfield trees.\n- ~ Legacy migrated trees with `vbrief/specification.vbrief.json` MAY continue using `task spec:render` until fully cut over.\n- ⊗ Invoke `task spec:render` on a greenfield tree that lacks `specification.vbrief.json` — use `task project:export-spec` instead.\n\n### plan.xbrief.json and continue.xbrief.json\n- Session/tactical state files are permitted at xbrief/ root (they carry `planRef` links). They are not part of the \"spec output\" contract but strategies that maintain chaining state (e.g. interview) update them per their own rules.\n\n## Per-Strategy Summary Table (Target State After Migration)\n\n| Strategy     | Type             | Must Create Lifecycle Folders | Must Write PROJECT-DEFINITION | Scope vBRIEFs Location                  | specification.vbrief.json | SPECIFICATION.md / PROJECT.md          |\n|--------------|------------------|-------------------------------|-------------------------------|-----------------------------------------|-----------------------------|----------------------------------------|\n| interview    | spec-generating  | Yes                           | Yes (narratives + items)      | proposed/YYYY-MM-DD-*.xbrief.json only  | Never (post-migration)      | Omit or deprecation redirect only      |\n| yolo         | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |\n| speckit      | spec-generating  | Yes                           | Yes (Phase 1+)                | proposed/YYYY-MM-DD-*.xbrief.json only (phases + stories) | Never             | Omit or `task project:export-spec` (legacy: `task spec:render` on migrated trees) |\n| rapid        | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |\n| enterprise   | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.xbrief.json only  | Never                       | Omit or deprecation redirect only      |\n| preparatory (research, discuss, map, etc.) | preparatory | Yes (if first touch)         | No (unless also spec path)    | proposed/YYYY-MM-DD-*.xbrief.json (context/decision vBRIEFs) | N/A                    | N/A (preparatory only)                 |\n\n## Agent & Strategy Author Rules\n\n- ! Every spec-generating strategy document MUST contain an \"Artifacts\" or \"Output\" section that explicitly cites this contract (`strategies/v0-20-contract.md`) and reproduces the relevant row from the table above.\n- ! Before emitting any vBRIEF artifact, follow the guards in `artifact-guards.md` (updated to reference this contract).\n- ! Date prefixes on scope vBRIEFs are mandatory for swarm readiness, filename sorting, and dedup.\n- ⊗ Write real content to root SPECIFICATION.md or PROJECT.md from a strategy.\n- ⊗ Emit bare-named vBRIEFs in proposed/ or anywhere outside the dated convention.\n- ⊗ Dual-write the old `specification.vbrief.json` in a v0.20 flow.\n\n## Verification & Enforcement\n\n- Build / setup / sync skills: Pre-Cutover Detection Guard (any missing lifecycle folder or real-content legacy md triggers redirect to migrate).\n- `task vbrief:validate` + `task check`: filename convention, folder/status consistency, PROJECT-DEFINITION presence.\n- Post-s2: deterministic validation gate (s2 story) will parse strategy output trees against this contract and fail non-conformant generations.\n- Content tests + migration stories exercise the before/after shapes.\n\n## Migration Path for Existing Strategies\n\nThe s3/s4/s5 stories migrate the individual strategy files (and their emitted examples) to the shape defined here. This contract document is the target spec they implement against; do not change strategies first.\n\n## When to Use\n\nUse this contract when:\n- Authoring a new spec-generating strategy (interview, yolo, speckit, rapid, enterprise, etc.).\n- Migrating an existing strategy to v0.20 (the s3/s4/s5 work).\n- Implementing or updating the deterministic validation gate (s2) or build pre-cutover guards.\n- Writing migration tooling (the frozen v0.59.0 migrator in UPGRADING.md, reconcile scripts, etc.).\n- Auditing a generated project for v0.20 conformance.\n\n## Workflow\n\n1. Read the Canonical v0.20 Output Shape section.\n2. Ensure your strategy (or migration) writes exactly the required folders + `PROJECT-DEFINITION.xbrief.json` + dated proposed/ vBRIEFs.\n3. Never write the legacy `specification.vbrief.json` or real-content `SPECIFICATION.md`/`PROJECT.md`.\n4. Cite this contract explicitly in your strategy's \"Artifacts\" / \"Output\" section (see the Per-Strategy Summary Table).\n5. Run `task check` (or the deterministic gate once s2 lands) to validate.\n\n---\n\n**Owned by**: `xbrief/active/2026-05-26-define-canonical-v020-strategy-output-contract.vbrief.json` (s1-contract of #1166 strategy consistency decomposition)\n\nThis contract lands first so that s2 (gate) and the migration stories have an unambiguous target.\n"
     },
     {
       "id": "yolo",

package/patterns/executor-layer-credentials.md

@@ -169,7 +169,7 @@ must invoke a privileged CLI through it, the same rules apply:
 
 - ! MUST set the credential in the subprocess `env=` mapping at spawn time, NOT in the agent's shell session env
 - ⊗ MUST NOT let the agent emit commands that read `$TOKEN`, `printenv`, `Get-ChildItem env:`, `env | grep`, or equivalent without a safety gate (the credential is in the subprocess env precisely so it is not in the agent shell env; an agent that can enumerate its own env defeats the partitioning)
-- ~ SHOULD pair this pattern with a destructive-verb preflight gate (see `coding/security.md` Agent-Specific Threats and the `scripts/preflight_gh.py` reference pattern from #1019) so an agent that gets a credential through the binding layer still cannot use it to delete the repo
+- ~ SHOULD pair this pattern with a destructive-verb preflight gate (see `coding/security.md` Agent-Specific Threats and `task verify:destructive-gh-verbs` from #1019) so an agent that gets a credential through the binding layer still cannot use it to delete the repo
 
 ## Operator runbook
 

package/patterns/multi-agent.md

@@ -81,7 +81,7 @@ blast radius. Those require partitioning the identity itself.
 | Maintainer GraphQL   | Maintainer PAT       | Human review, PR open/merge/ready, manual triage   |
 | Maintainer core REST | Maintainer PAT       | `gh api` reads outside swarm context               |
 | Worker GraphQL       | Bot account / App    | `markPullRequestReadyForReview`, `addPullRequestReview` (the only GraphQL surfaces a worker should hit; see #976 + #961) |
-| Worker core REST     | Bot account / App    | All other reads / mutations via `gh_rest.py` REST helpers |
+| Worker core REST     | Bot account / App    | All other reads / mutations via `gh api` REST helpers |
 
 Each bucket is 5,000 req/hr (REST `core` and GraphQL each). With
 identity separation the maintainer's two buckets are untouched by
@@ -192,7 +192,7 @@ into the worker's env:
 
 ```pwsh path=null start=null
 # Option A (GitHub App): mint installation token at dispatch time.
-$jwt = uv run python scripts/swarm_mint_jwt.py --app-id $env:DEFT_SWARM_APP_ID --pem secrets/swarm-app.pem
+$jwt = <operator-supplied GitHub App JWT>  # Directive does not ship a mint helper in v1 (#983)
 $inst_token = (gh api -X POST "/app/installations/$env:DEFT_SWARM_INSTALLATION_ID/access_tokens" -H "Authorization: Bearer $jwt" --jq .token)
 start_agent ... -e GH_TOKEN=$inst_token
 
@@ -201,7 +201,7 @@ $bot_token = (Get-Content secrets/swarm-bot.env | Where-Object { $_ -like 'SWARM
 start_agent ... -e GH_TOKEN=$bot_token
 ```
 
-Token-mint plumbing (`scripts/swarm_mint_jwt.py`) is intentionally not
+Token-mint plumbing is intentionally not
 shipped in v1 -- the runbook above is operator-facing guidance, not
 deft-supplied automation. v1 is documentation-only per #983 non-goals.
 Operators MAY automate token minting in their own dispatcher; the
@@ -241,7 +241,7 @@ the blast-radius problem this pattern solves.
 
 ## Cross-references
 
-- #976 -- remaining GraphQL drain in `scripts/scm.py` + smoke (the
+- #976 -- remaining GraphQL drain in `task scm:body` + smoke (the
   REST-migration track this pattern complements; this pattern was
   carved out of #976's "Complementary mitigation" section)
 - #588 -- agent identity pattern (distinct attestable identity per

package/platforms/2600.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/platforms/2600.md" -->
 # Atari 2600 (VCS) Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md)
 
 ## Hardware Reference
 

package/platforms/unity.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/platforms/unity.md" -->
 # Unity Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [csharp.md](../languages/csharp.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md) | [csharp.md](../languages/csharp.md)
 
 **Stack**: Unity 6+, C# (see [csharp.md](../languages/csharp.md) for general C# rules); Rendering: URP (default) or HDRP; Testing: Unity Test Framework (NUnit); Asset Management: Addressables
 

package/references/ip-risk.md

@@ -10,7 +10,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 not provide legal advice and ⊗ MUST NOT be used as a substitute for lawyer
 consultation when the project is commercial and IP-adjacent.
 
-**⚠️ See also**: [skills/deft-directive-interview/SKILL.md](../skills/deft-directive-interview/SKILL.md) | [strategies/research.md](../strategies/research.md) | [scripts/ip_risk.py](../../scripts/ip_risk.py)
+**⚠️ See also**: [skills/deft-directive-interview/SKILL.md](../skills/deft-directive-interview/SKILL.md) | [strategies/research.md](../strategies/research.md)
 
 ---
 
@@ -38,10 +38,9 @@ cost of one extra "is this Magic: The Gathering related?" question is
 trivial; the cost of letting a commercial IP-adjacent project ship without
 the question is potentially substantial.
 
-The canonical implementation lives at
-[`scripts/ip_risk.py`](../../scripts/ip_risk.py) and exposes
-`detect_ip_terms(text)`, `is_ip_adjacent(text)`, `ip_risk_scope_items(monetization_intent)`,
-and `plain_risk_summary(hits, monetization_intent)` for callers.
+This document is the canonical procedure. Apply the heuristic below,
+then the question script, then the minimum-protection checklist. There
+is no separate helper binary on the consumer deposit.
 
 ### Categories Scanned
 
@@ -76,17 +75,14 @@ research-phase notes) for terms in these categories:
 ### Updating the Term Lists
 
 ! When you add a recurring miss (a real IP-adjacent project that slipped
-through), append the term to the matching category in
-`scripts/ip_risk.py` AND mention it here in the relevant category. The
-two surfaces MUST stay in sync. The unit tests in
-`tests/scripts/test_ip_risk.py` verify the helpers; add a positive
-detection test for any new term you introduce.
+through), append the term here in the relevant category. This document
+is the single consumer-facing list.
 
 ---
 
 ## Question Script (Monetization Intent)
 
-When `detect_ip_terms` returns at least one hit, the interview MUST ask the
+When the heuristic returns at least one hit, the interview MUST ask the
 user the monetization-intent question before generating the SPECIFICATION.
 
 ### Canonical Question
@@ -143,8 +139,8 @@ risk summary in the interview output. The summary:
 - ⊗ Use legalese ("hereby", "tortious", "in perpetuity", "without
   prejudice"). The audience is the project owner, not a court.
 
-The canonical builder is `plain_risk_summary(hits, monetization_intent)`
-in `scripts/ip_risk.py`.
+The canonical builder is the plain-English risk summary in this
+document's Question Script.
 
 ---
 
@@ -155,9 +151,8 @@ following three protection scope items into the
 `specification.vbrief.json` `plan.items` array (and therefore into the
 rendered SPECIFICATION.md).
 
-The canonical generator is `ip_risk_scope_items(monetization_intent)`
-in `scripts/ip_risk.py` -- it returns the three items shaped for vBRIEF
-v0.6 PlanItem (`title`, `status`, `narrative`). All three items are
+The canonical generator is the three protection items below (`IP-1`,
+`IP-2`, `IP-3`), shaped for a PlanItem (`title`, `status`, `narrative`). All three items are
 emitted regardless of monetization intent because even personal
 IP-adjacent projects can leak into commercial use over time. The
 `Acceptance` narrative is tightened to the commercial-level checklist
@@ -233,13 +228,13 @@ The heuristic exists to **surface the question**, not to answer it.
 
 ```
 1. Capture project description (and research notes if research strategy ran).
-2. Run scripts/ip_risk.py:detect_ip_terms(text).
+2. Apply this document's permissive heuristic to the text.
 3. If empty -> proceed normally.
 4. If non-empty:
    a. Ask the monetization-intent question (Personal / Commercial / Other).
    b. Loop on the freeform follow-up if "Other" is chosen until intent is captured.
-   c. Emit plain_risk_summary(hits, intent) into the interview output.
-   d. Inject ip_risk_scope_items(intent) into the spec vBRIEF.
+   c. Emit the plain-English risk summary into the interview output.
+   d. Inject the IP-1 / IP-2 / IP-3 protection items into the spec xBRIEF.
    e. On commercial intent, surface the non-optional lawyer-consultation
       recommendation in the interview output AND in the IPRisk narrative.
 5. Continue to the rest of the interview flow.

package/scm/changelog.md

@@ -124,7 +124,7 @@ At release time, `[Unreleased]` is renamed to the new version (see Release Proce
 - Export data to CSV format
 ```
 
-The blockquote captures the operator's one-sentence release narrative (recommended 80-160 chars). It is authored once during the release flow (`task release -- <version> --summary "<text>"`; see `skills/deft-directive-release/SKILL.md` Phase 1) and propagates verbatim into the GitHub release body (auto-pickup via `scripts/release.py::_section_for_version`) AND the Phase 8 Slack `*Summary*:` slot. The blockquote is inline Markdown -- `**bold**`, `[link](url)`, etc. are preserved verbatim. Omit the blockquote (no `--summary` flag) to keep the pre-existing Keep-a-Changelog shape.
+The blockquote captures the operator's one-sentence release narrative (recommended 80-160 chars). It is authored once during the release flow (`task release -- <version> --summary "<text>"`; see `skills/deft-directive-release/SKILL.md` Phase 1) and propagates verbatim into the GitHub release body (auto-pickup via `task release --summary`) AND the Phase 8 Slack `*Summary*:` slot. The blockquote is inline Markdown -- `**bold**`, `[link](url)`, etc. are preserved verbatim. Omit the blockquote (no `--summary` flag) to keep the pre-existing Keep-a-Changelog shape.
 
 ⊗ Hand-write a different one-line narrative for each downstream surface (CHANGELOG / GitHub release / Slack) -- author once via `--summary` and let the pipeline propagate.
 

package/scm/git.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/scm/git.md" -->
 # Git Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [github.md](../scm/github.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md) | [github.md](github.md)
 
 **Stack**: git 2.30+, Conventional Commits, `git --no-pager`, task-based workflows