@deftai/directive-content 0.69.0 → 0.71.0

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

@@ -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.vbrief.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.vbrief.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.vbrief.json</i>\"]\n        S[\"📝 Specify<br/><i>WHAT/WHY → proposed/YYYY-MM-DD-*.vbrief.json</i>\"]\n        PL[\"🏗️ Plan<br/><i>HOW → proposed/YYYY-MM-DD-*.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.json`\n- ~ Interview stakeholders about architectural constraints\n- ⊗ Proceed without defined principles\n- ⊗ Create a standalone `project.md` -- principles belong in PROJECT-DEFINITION.vbrief.json\n\n### Transition Criteria\n\n- ! `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.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 `vbrief/proposed/YYYY-MM-DD-*.vbrief.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: vbrief/PROJECT-DEFINITION.vbrief.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 `./vbrief/proposed/`, one per implementation phase or epic, using the filename convention `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.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 `vbrief/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.vbrief.json\", \"TrustLevel\": \"internal\" }\n    ],\n    \"items\": []\n  }\n}\n```\n\n### plan.vbrief.json — Session Tracker Only\n\n- ! `plan.vbrief.json` reverts to its canonical session-todo role defined in [vbrief/vbrief.md — plan.vbrief.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.vbrief.json` MUST carry a `planRef` to that scope vBRIEF in `vbrief/proposed/` or `vbrief/active/`.\n- ⊗ Emit the project-wide Phase 4 task list to `plan.vbrief.json` — write per-IP scope vBRIEFs to `vbrief/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 `./vbrief/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 vBRIEFs in `./vbrief/pending/` or `./vbrief/active/`.\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 `vbrief/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 `vbrief/.eval/decompositions/<parent-slug>.json`; derive `<parent-slug>` from the parent vBRIEF filename by removing `.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.vbrief.json> --draft vbrief/.eval/decompositions/<parent-slug>.json --check`, then apply it without `--check`.\n7. ! Run `task swarm:readiness -- vbrief/active/*.vbrief.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 -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json --check\ntask scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/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 `vbrief/.eval/decompositions/`, which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.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 `vbrief/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 -- vbrief/active/*.vbrief.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 `./vbrief/pending/` (promote to `./vbrief/active/` via `task scope:activate` when work begins). `./vbrief/plan.vbrief.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 `./vbrief/plan.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.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.vbrief.json` — use `vbrief/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 | `vbrief/PROJECT-DEFINITION.vbrief.json` | Governing rules (Principles narrative) |\n| 2. Specify | date-prefixed in `vbrief/proposed/` | WHAT/WHY narratives (v0.20) |\n| 3. Plan | date-prefixed in `vbrief/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 | `./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 | `./vbrief/plan.vbrief.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├── vbrief/\n│   ├── PROJECT-DEFINITION.vbrief.json  # Phase 1: Principles narrative\n│   ├── proposed/                       # Phase 2+: date-prefixed WHAT/WHY/HOW + IP scopes + stories\n│   │   └── YYYY-MM-DD-*.vbrief.json\n│   │   └── YYYY-MM-DD-ip001-....vbrief.json\n│   ├── plan.vbrief.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 `vbrief/` 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 `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (or the ipNNN convention for phases per vbrief.md). For speckit, phases use `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.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).\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 vbrief/ 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| `vbrief/PROJECT-DEFINITION.vbrief.json` | Principles + full items registry | Speckit Phase 1 + `task project:render` |\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` + `YYYY-MM-DD-ipNNN-*.vbrief.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| `vbrief/{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| `vbrief/plan.vbrief.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.vbrief.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.vbrief.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.vbrief.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.vbrief.json</i>\"]\n        S[\"📝 Specify<br/><i>WHAT/WHY → proposed/YYYY-MM-DD-*.vbrief.json</i>\"]\n        PL[\"🏗️ Plan<br/><i>HOW → proposed/YYYY-MM-DD-*.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.json`\n- ~ Interview stakeholders about architectural constraints\n- ⊗ Proceed without defined principles\n- ⊗ Create a standalone `project.md` -- principles belong in PROJECT-DEFINITION.vbrief.json\n\n### Transition Criteria\n\n- ! `Principles` narrative in `vbrief/PROJECT-DEFINITION.vbrief.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 `vbrief/proposed/YYYY-MM-DD-*.vbrief.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: vbrief/PROJECT-DEFINITION.vbrief.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 `./vbrief/proposed/`, one per implementation phase or epic, using the filename convention `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.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 `vbrief/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.vbrief.json\", \"TrustLevel\": \"internal\" }\n    ],\n    \"items\": []\n  }\n}\n```\n\n### plan.vbrief.json — Session Tracker Only\n\n- ! `plan.vbrief.json` reverts to its canonical session-todo role defined in [vbrief/vbrief.md — plan.vbrief.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.vbrief.json` MUST carry a `planRef` to that scope vBRIEF in `vbrief/proposed/` or `vbrief/active/`.\n- ⊗ Emit the project-wide Phase 4 task list to `plan.vbrief.json` — write per-IP scope vBRIEFs to `vbrief/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 `./vbrief/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 vBRIEFs in `./vbrief/pending/` or `./vbrief/active/`.\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 `vbrief/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 `vbrief/.triage-cache/decompositions/<parent-slug>.json`; derive `<parent-slug>` from the parent vBRIEF filename by removing `.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.vbrief.json> --draft vbrief/.triage-cache/decompositions/<parent-slug>.json --check`, then apply it without `--check`.\n7. ! Run `task swarm:readiness -- vbrief/active/*.vbrief.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 -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.triage-cache/decompositions/ip001-auth.json --check\ntask scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.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 `vbrief/.triage-cache/decompositions/`, which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.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 `vbrief/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 -- vbrief/active/*.vbrief.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 `./vbrief/pending/` (promote to `./vbrief/active/` via `task scope:activate` when work begins). `./vbrief/plan.vbrief.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 `./vbrief/plan.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.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.vbrief.json` — use `vbrief/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 | `vbrief/PROJECT-DEFINITION.vbrief.json` | Governing rules (Principles narrative) |\n| 2. Specify | date-prefixed in `vbrief/proposed/` | WHAT/WHY narratives (v0.20) |\n| 3. Plan | date-prefixed in `vbrief/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 | `./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 | `./vbrief/plan.vbrief.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├── vbrief/\n│   ├── PROJECT-DEFINITION.vbrief.json  # Phase 1: Principles narrative\n│   ├── proposed/                       # Phase 2+: date-prefixed WHAT/WHY/HOW + IP scopes + stories\n│   │   └── YYYY-MM-DD-*.vbrief.json\n│   │   └── YYYY-MM-DD-ip001-....vbrief.json\n│   ├── plan.vbrief.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 `vbrief/` 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 `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (or the ipNNN convention for phases per vbrief.md). For speckit, phases use `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.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 `vbrief/PROJECT-DEFINITION.vbrief.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).\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 vbrief/ 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| `vbrief/PROJECT-DEFINITION.vbrief.json` | Principles + full items registry | Speckit Phase 1 + `task project:render` |\n| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` + `YYYY-MM-DD-ipNNN-*.vbrief.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| `vbrief/{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| `vbrief/plan.vbrief.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.vbrief.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",

package/skills/deft-directive-decompose/SKILL.md

@@ -36,7 +36,7 @@ Convert approved specification/phase/epic scope xBRIEFs into swarm-ready child s
 
 - ! Draft a decomposition JSON proposal with child stories only; do not write child xBRIEFs yet.
 - ! Treat the draft JSON as a temporary proposal artifact, not a xBRIEF.
-- ! Write draft proposals under `xbrief/.eval/decompositions/`, using a parent-derived slug such as `xbrief/.eval/decompositions/ip001-auth.json`.
+- ! Write draft proposals under `xbrief/.triage-cache/decompositions/`, using a parent-derived slug such as `xbrief/.triage-cache/decompositions/ip001-auth.json`.
 - ! Derive `<parent-slug>` from the parent xBRIEF filename by removing `.xbrief.json` and any leading `YYYY-MM-DD-` date prefix; for example, `xbrief/pending/2026-05-12-ip001-auth.xbrief.json` uses `ip001-auth`, while `xbrief/pending/feature-xyz.xbrief.json` uses `feature-xyz`.
 - ⊗ Agents MUST NOT leave decomposition draft JSON files at the workspace root.
 - ! Each story MUST include `id`, `title`, `Description`, `ImplementationPlan`, `UserStory`, executable `items` or `acceptance`, `traces` or explicit trace justification, `swarm.file_scope`, `swarm.verify_commands`, `swarm.expected_outputs`, `swarm.depends_on`, `swarm.conflict_group`, `swarm.size`, `swarm.file_scope_confidence`, and `swarm.model_tier`.
@@ -67,13 +67,13 @@ Convert approved specification/phase/epic scope xBRIEFs into swarm-ready child s
 - ! Validate the approved draft first:
 
 ```bash
-task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.eval/decompositions/ip001-auth.json --check
+task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.triage-cache/decompositions/ip001-auth.json --check
 ```
 
 - ! Apply the approved draft:
 
 ```bash
-task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.eval/decompositions/ip001-auth.json
+task scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.triage-cache/decompositions/ip001-auth.json
 ```
 
 The command creates generated child story xBRIEFs as lifecycle artifacts, defaulting to `xbrief/pending/`. It preserves origin/provenance references, sets each child `planRef` to the parent, updates parent references to include the children, rejects dependency cycles, and rejects ready stories missing executable acceptance, user-story shape, concrete acceptance, narrow file scope, focused verify commands, or traces.

package/skills/deft-directive-feedback/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: deft-directive-feedback
+description: >-
+  Batched session-end gap escalation for directive consumers. Collects
+  friction/gap reports, drafts deduped framework-gap issues against
+  deftai/directive, and files upstream only after explicit operator
+  confirmation. Gated on plan.policy.valueFeedback upstreamPrompt.
+---
+
+# Deft Directive Feedback -- gap escalation to upstream
+
+Conversational batched flow for filing framework gaps discovered during consumer sessions. Mirrors the confirmation gate from `deft-directive-article-review` -- the agent drafts and dedups; the operator approves before any upstream issue is created.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## When to Use
+
+- Session end when `friction:*` ledger signals or operator reports a directive shortfall
+- Operator says "file this upstream", "report a framework gap", or "directive feedback"
+- After enabling `plan.policy.valueFeedback.upstreamPrompt` during onboarding
+
+## Preconditions
+
+- ! Run only from a **consumer project** -- the filing path no-ops inside the directive maintainer repo
+- ! `plan.policy.valueFeedback.upstreamPrompt` MUST be ON (`task policy:show --field=valueFeedback`)
+- ⊗ File upstream issues without explicit operator confirmation
+- ⊗ Invoke when `valueFeedback.enabled` is OFF
+
+## Phase 1 -- Collect (batched)
+
+- ! Gather concrete gap reports from the session: what was expected, what happened, and minimal reproduction context
+- ! Batch multiple friction items into one upstream issue when they share a root cause; otherwise prepare separate drafts
+- ~ Prefer attributed phrasing ("encoding gate blocked a valid file") over vague quality claims
+
+## Phase 2 -- Draft + dedup
+
+- ! For each candidate report, run a dry draft:
+
+```bash
+task feedback:file -- --summary "<one-line summary>" --context "<session context>" --expected "<expected>" --actual "<actual>" --notes "<optional>"
+```
+
+- ! Read the printed draft title/body with the operator before proceeding
+- ! If the command reports a duplicate open issue, STOP and link the existing issue instead of filing again
+- ⊗ Proceed past a duplicate-detection block without operator override
+
+## Phase 3 -- Confirm + file
+
+- ! Present the final draft and ask for explicit yes/no confirmation
+- ! Only after approval, re-run with `--confirm`:
+
+```bash
+task feedback:file -- --summary "<one-line summary>" --context "<session context>" --expected "<expected>" --actual "<actual>" --confirm
+```
+
+- ! Print the filed issue URL to the operator
+- ⊗ Use `Closes`/`Fixes`/`Resolves` in the upstream body -- use `Refs #1709` only
+
+## Phase 4 -- Handoff
+
+- ~ Record the upstream issue URL in the session handoff or continue checkpoint if the operator tracks follow-ups locally
+- ~ Return to the prior workflow; gap escalation does not block story completion
+
+## Anti-Patterns
+
+- ⊗ Filing from the maintainer framework repo (consumer-only guard)
+- ⊗ Skipping dedup review when the command reports an existing open issue
+- ⊗ Treating `--confirm` as implicit from broad session approval -- require an explicit filing confirmation step

package/skills/deft-directive-swarm/SKILL.md

@@ -84,7 +84,7 @@ This path became first-class in #1342 (platform adapter slices 1-3) and is fully
 
 - ! Run `task triage:summary` to emit the current triage-cache one-liner (`[triage] N untriaged ... WIP X/Y [⚠]`). The monitor uses the result to:
   - confirm the cache is fresh enough to act on (the D5 / #1127 `task verify:cache-fresh` warning is silent on a fresh cache; D2's one-liner is the human-readable parallel for the operator);
-  - read the current `pending/ + active/` count against the configured `wipCap` (default 10 per umbrella #1119 Current Shape v3, exposed via `plan.policy.wipCap`).
+  - read the current `pending/ + active/` count against the configured `wipCap` (default 20 per #2319, raised from the original 10 per umbrella #1119 Current Shape v3, exposed via `plan.policy.wipCap`).
 - ! If the summary reports an empty cache (no candidates ever ingested), surface the bootstrap remediation (`task triage:bootstrap` or the N3 / #1143 onboarding ritual `task triage:welcome`) and HALT Phase 0 -- there is no queue to drive cohort selection from.
 
 ```pwsh path=null start=null
@@ -235,7 +235,7 @@ Cross-references:
 - ! **Large/complex stories** get dedicated agents — a story with broad file scope or high acceptance criteria count should not share an agent
 - ! **Dependency-aware grouping** — xBRIEFs that share `planRef` to the same epic or have `edges` between them should be assigned to the same agent when possible, OR sequenced with clear ordering
 - ! The monitor decides allocation dynamically — no hardcoded 1:1 rule
-- ! **WIP cap awareness (#1124 / D4 of #1119)** — the cohort + any bridge-promoted candidates (Step 0.5) MUST fit within `plan.policy.wipCap` (default 10 per umbrella #1119 Current Shape v3). When `pending/ + active/` count is at-or-above the cap, `task scope:promote` refuses with an error message naming `task scope:demote <existing>` and `task scope:demote --batch --older-than-days 30` as the relief valves. The monitor MUST drain the WIP set via `task scope:demote` (D1 / #1121) before promoting more candidates, OR open a per-promote `task scope:promote <file> --force` (audit-logged as `wip_cap_override` in `xbrief/.eval/scope-lifecycle.jsonl`) for the genuinely time-critical case. `task triage:summary` (D2 / #1122) surfaces the cap as `WIP X/Y` with a warning glyph when at-or-above cap.
+- ! **WIP cap awareness (#1124 / D4 of #1119)** — the cohort + any bridge-promoted candidates (Step 0.5) MUST fit within `plan.policy.wipCap` (default 20 per #2319, raised from the original 10 per umbrella #1119 Current Shape v3). When `pending/ + active/` count is at-or-above the cap, `task scope:promote` refuses with an error message naming `task scope:demote <existing>` and `task scope:demote --batch --older-than-days 30` as the relief valves. The monitor MUST drain the WIP set via `task scope:demote` (D1 / #1121) before promoting more candidates, OR open a per-promote `task scope:promote <file> --force` (audit-logged as `wip_cap_override` in `xbrief/.eval/scope-lifecycle.jsonl`) for the genuinely time-critical case. `task triage:summary` (D2 / #1122) surfaces the cap as `WIP X/Y` with a warning glyph when at-or-above cap.
 
 ### Step 4: Present Analysis
 

package/skills/deft-directive-triage/SKILL.md

@@ -97,7 +97,7 @@ What would you like to do with this candidate?
 ! Confirm the session's decisions landed coherently before exiting the skill.
 
 1. ! Run `task triage:audit --format=json` (D11 / #1128) -- emits the stable `{generated_at, repo, vbrief_staleness, entry_count, entries: [...]}` schema; pipe through `jq` to surface this session's appended entries. For historical look-back, add the #1180 filters: `task triage:audit --since=30d --action=demote --format=json | jq` answers "how many demotes in the last 30 days?" in one call. `--since=<window>` accepts the framework duration grammar (`Nd` / `Nh` / `Nm` / `Nw` / `Ns` or ISO-8601 `PnDTnHnMnS`); `--action=<verb>` filters to a single decision verb (`accept` / `reject` / `defer` / `needs-ac` / `mark-duplicate` / `reset` / `resume-eligible`). Both filters compose with `--format=text` and `--format=json`. The framework deliberately does NOT compute trend lines or apply falsification gates -- the contract is read raw, transform with `jq`.
-2. ! Run `task triage:summary` (D2 / #1122) -- prints the canonical one-liner `[triage] N untriaged · S stale-defer · M in-flight · WIP X/Y [⚠] [· [scope-drift] N]`. The WIP cap default is 10 per the umbrella Current Shape v3 (overridable via typed `plan.policy.wipCap`). The `⚠` glyph fires only at-or-above cap. The `[scope-drift] N` segment (D14 / #1133) appears only when at least one unsubscribed label/milestone meets the framework `_DRIFT_MIN_ISSUES = 3` threshold; suppressed at zero.
+2. ! Run `task triage:summary` (D2 / #1122) -- prints the canonical one-liner `[triage] N untriaged · S stale-defer · M in-flight · WIP X/Y [⚠] [· [scope-drift] N]`. The WIP cap default is 20 per #2319, raised from the original 10 per the umbrella Current Shape v3 (overridable via typed `plan.policy.wipCap`). The `⚠` glyph fires only at-or-above cap. The `[scope-drift] N` segment (D14 / #1133) appears only when at least one unsubscribed label/milestone meets the framework `_DRIFT_MIN_ISSUES = 3` threshold; suppressed at zero.
 3. ~ When the summary surfaces a non-zero `[scope-drift] N` (D14 / #1133), surface it to the operator alongside `task triage:scope-drift` output and the matching `task triage:subscribe` / `task triage:unsubscribe` / `task triage:scope-drift -- --ignore-label=<L>` remediation. Subscription mutations record a `subscription-change` audit entry under `xbrief/.eval/subscription-history.jsonl` (sidecar of the existing `candidates.jsonl` audit surface) so future operators can replay how the subscription evolved. After every mutation, run `task triage:bootstrap -- --resume` to backfill newly-subscribed entries / mark newly-out-of-scope entries.
 4. ~ When the audit surfaces a stale acceptance (`accept` decision whose issue is no longer referenced by any `xbrief/active/`), surface it to the operator -- the typical fix is a fresh ingest via `task issue:ingest -- <N>` or a `task triage:reset <N>` if the acceptance was in error.
 5. ⊗ Skip the Phase 4 audit -- silent exit leaves the operator without a record of what landed in `xbrief/proposed/` this session, which is the typical recurrence vector for "what did I just accept?" confusion.

package/strategies/speckit.md

@@ -252,9 +252,9 @@ For each implementation phase IP-N, write a scope vBRIEF with:
 1. ! Inspect approved specification narratives and Phase 4 scope vBRIEFs.
 2. ! Identify `plan.metadata.kind = "phase"` or `"epic"` scopes that are too broad for direct implementation.
 3. ! Draft a deterministic decomposition proposal: stories, dependencies, expected file scope, verification commands, traces, and conflict groups.
-4. ! Store the temporary proposal artifact under `vbrief/.eval/decompositions/<parent-slug>.json`; derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix.
+4. ! Store the temporary proposal artifact under `vbrief/.triage-cache/decompositions/<parent-slug>.json`; derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix.
 5. ! Ask for explicit user approval before writing child story vBRIEFs.
-6. ! Validate the approved draft with `task scope:decompose -- <parent.vbrief.json> --draft vbrief/.eval/decompositions/<parent-slug>.json --check`, then apply it without `--check`.
+6. ! Validate the approved draft with `task scope:decompose -- <parent.vbrief.json> --draft vbrief/.triage-cache/decompositions/<parent-slug>.json --check`, then apply it without `--check`.
 7. ! Run `task swarm:readiness -- vbrief/active/*.vbrief.json` before concurrent allocation, or point it at the candidate child story files for a dry readiness review before activation.
 
 ### Story vBRIEF Requirements
@@ -282,12 +282,12 @@ Each Phase 4.5 child story vBRIEF MUST include:
 Use the deterministic command surface:
 
 ```bash
-task scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json --check
-task scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.eval/decompositions/ip001-auth.json
+task scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.triage-cache/decompositions/ip001-auth.json --check
+task scope:decompose -- vbrief/pending/2026-05-12-ip001-auth.vbrief.json --draft vbrief/.triage-cache/decompositions/ip001-auth.json
 task scope:decompose -- --check
 ```
 
-The draft JSON is a temporary proposal artifact, not a vBRIEF. Agents SHOULD write draft proposals under `vbrief/.eval/decompositions/`, which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.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 `vbrief/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.
+The draft JSON is a temporary proposal artifact, not a vBRIEF. Agents SHOULD write draft proposals under `vbrief/.triage-cache/decompositions/`, which is gitignored specifically for local decomposition scratch. Derive `<parent-slug>` from the parent vBRIEF filename by removing `.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 `vbrief/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.
 
 Parent phase/epic acceptance MAY remain in `plan.narratives.Acceptance` as context. Executable acceptance for swarm work MUST be redistributed into child story `plan.items`.
 

package/tasks/eval.yml

@@ -0,0 +1,32 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  health:
+    desc: "Tier 0 static self-consistency aggregation -- versioned framework health score (#1703). -- task eval:health [-- --json] [--no-persist] [--project-root PATH]"
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'eval:health --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  run:
+    desc: "Tier 2 golden corpus champion-challenger eval (#1703). -- task eval:run -- --model MODEL [--seed N] [--directive-version V] [--harness NAME] [--json] [--no-persist] [--project-root PATH]"
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'eval:run --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  report:
+    desc: "Tier 2 version-diff report with significance (#1703). -- task eval:report -- --champion V --challenger V --model MODEL [--json] [--project-root PATH]"
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'eval:report --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/feedback.yml

@@ -0,0 +1,14 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  file:
+    desc: "Draft or file a deduped framework-gap issue upstream (#1709). -- task feedback:file -- [--summary TEXT | positional] [--context ...] [--confirm] [--dry-run] [--json]"
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'feedback:file --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/policy.yml

@@ -52,8 +52,18 @@ tasks:
         vars:
           ENGINE_CMD: 'policy allow-direct-commits --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
+  enable-value-feedback:
+    desc: "Opt in to value-feedback surfaces (#1709). Requires --confirm after the capability-cost disclosure prints. -- task policy:enable-value-feedback -- [--confirm] [--json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'policy enable-value-feedback --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
   wip-cap:
-    desc: "Set plan.policy.wipCap=N (#1124 / D4 of #1119). Requires --set N --confirm. Default cap is 10 per umbrella #1119 Current Shape v3."
+    desc: "Set plan.policy.wipCap=N (#1124 / D4 of #1119). Requires --set N --confirm. Default cap is 20 (#2319; raised from the original 10 per umbrella #1119 Current Shape v3)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build

package/tasks/triage-metrics.yml

@@ -0,0 +1,24 @@
+version: '3'
+
+# tasks/triage-metrics.yml -- D17 triage metrics alias for value-readback (#1709).
+#
+# Inner task `metrics` is exposed as the user-facing alias `task triage:metrics`
+# in the root Taskfile.yml alias block (same pattern as triage:summary).
+#
+# Per `conventions/task-caching.md`, tasks forwarding user-facing flags via
+# {{.CLI_ARGS}} MUST NOT declare `sources:` / `generates:`.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  metrics:
+    desc: "Trend lines from summary-history.jsonl (#1709 / D17). -- task triage:metrics -- [--window=7d|30d] [--format=text|json]"
+    internal: true
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'triage:metrics --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/value.yml

@@ -0,0 +1,20 @@
+version: '3'
+
+# tasks/value.yml -- pull-based value-awareness readbacks (#1709).
+#
+# Per `conventions/task-caching.md`, tasks forwarding user-facing flags via
+# {{.CLI_ARGS}} MUST NOT declare `sources:` / `generates:`.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  show:
+    desc: "Pull-based attributed-value trend readout (#1709). -- task value:show -- [--window=7d|30d] [--format=text|json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'value:show --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/verify.yml

@@ -364,7 +364,7 @@ tasks:
           ENGINE_CMD: 'verify:judgment-gates --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   wip-cap:
-    desc: "Pre-merge re-validation that pending/+active/ count is within plan.policy.wipCap (#1124 / D4 of #1119). Catches stale-branch merges + --force overrides. Default cap is 10 per umbrella #1119 Current Shape v3. The framework's own task check passes --allow-over-cap during landing-day overage; consumer projects MUST NOT pass that flag."
+    desc: "Pre-merge re-validation that pending/+active/ count is within plan.policy.wipCap (#1124 / D4 of #1119). Catches stale-branch merges + --force overrides. Default cap is 20 (#2319; raised from the original 10 per umbrella #1119 Current Shape v3). The framework's own task check passes --allow-over-cap during landing-day overage; consumer projects MUST NOT pass that flag."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build

package/templates/agent-prompt-preamble.md

@@ -198,6 +198,14 @@ Before pushing any branch:
 
 Anti-pattern: pushing without pre-pr and relying on Greptile to find issues. That burns review-cycle iterations on issues you could have caught locally; each iteration costs GraphQL budget under your shared identity.
 
+## 4.5 Review-surface precedence -- deft review-cycle wins over host review tools (#2308)
+
+The active host harness may expose its own review-labeled surfaces. On Cursor these are the `bugbot` and `security-review` Task **subagent types** and the `review-bugbot` / `review-security` **skills**; other harnesses may ship equivalents. A generic operator request to "review" / "get this reviewed" / "use sub-agents for reviews" must NOT be routed to those host-native tools as the review of record.
+
+- ! Route ALL review work through the canonical `skills/deft-directive-review-cycle/SKILL.md` surface. Map a generic review request to the review cycle **by intent**, not by literal keyword -- "review this", "get this reviewed", and "use sub-agents for reviews" all mean run `deft-directive-review-cycle` (extends the #1862 / #2261 intent-routing fix).
+- ~ Host review tools (Cursor `bugbot` / `security-review` subagent types, `review-bugbot` / `review-security` skills, or any future host equivalent) MAY be folded in as *advisory* finding sources INSIDE the review cycle -- the #2019 harness-aware-reviewer path -- with their findings batched alongside the Greptile / bot findings the cycle already processes.
+- ⊗ Substitute a host-native review subagent type or `review-*` skill for `deft-directive-review-cycle` as the review surface. The host tools are advisory inputs folded into the cycle, never a replacement for it. Reaching for them on a bare "review" request is the 3rd recurrence of the #1862 / #2261 wrong-review-surface class (see also #2019, #2018).
+
 ## 5. REST-by-default for read-only gh calls
 
 The GraphQL bucket (5000 pts/hr) is the operational bottleneck under shared-identity workflows, not the REST `core` bucket. Every read-only GitHub API call MUST prefer REST:
@@ -250,6 +258,19 @@ Anti-pattern: reading only the issue body and building a dispatch envelope from
 
 Reference: AGENTS.md `## Issue body→comments reading (#2143)`, `## Umbrella current-shape convention (#1152)`, issue #2143.
 
+## 5.7 Value feedback opt-in and gap escalation (#1709)
+
+Value attribution, budgeted session readbacks, and upstream gap escalation are gated on `plan.policy.valueFeedback` (default OFF). Workers MUST NOT emit value claims, session readback lines, or file upstream framework-gap issues unless the relevant sub-flag is ON and the operator has confirmed enablement where required.
+
+- ! While `valueFeedback.enabled` is false, treat every value-feedback path as a no-op -- no ledger writes, no session lines, no upstream prompts, no token spend.
+- ! Value claims MUST cite concrete attributed ledger events; silence when nothing is attributable.
+- ! Session readback repeats suppress for 4 hours per attribution event id (same debounce class as #1279 triage welcome). Pull-based detail uses `task value:show` / `deft value:show`, not ambient pushes.
+- ! Upstream gap filing is confirmation-gated -- route through `deft-directive-feedback`; draft + dedup with `task feedback:file` / `deft feedback:file`, then re-run with `--confirm` only after explicit operator approval. Consumer projects only; maintainer repo no-ops unless `DEFT_VALUE_SELF_DOGFOOD=1`.
+- ⊗ File upstream issues without operator confirmation or past duplicate detection.
+- ⊗ Use `Closes`/`Fixes`/`Resolves` on upstream gap bodies -- use `Refs #1709` only.
+
+Reference: AGENTS.md `## Value feedback and attribution (#1709)`, issue #1709.
+
 ## 6. No Draft re-toggling within a single review cycle
 
 Once a PR transitions Draft -> Ready, keep it Ready unless a P0 finding requires re-Draft. Repeated Draft<->Ready toggles cost GraphQL mutations and trigger stale CheckRun states downstream (Greptile re-runs, branch-protection re-evaluations).

package/templates/agents-entry.md

@@ -76,7 +76,7 @@ Check what exists before doing anything else:
 
 ## WIP cap
 
-The `plan.policy.wipCap` field caps the number of in-flight scope xBRIEFs (`xbrief/pending/` + `xbrief/active/`). The framework default is 10 (per umbrella #1119 Current Shape v3). When the cap is reached, `deft scope:promote` refuses with a relief hint pointing at `deft scope:demote --batch --older-than-days 30` (D1 / #1121). Operators can override the cap from the consumer side via `deft triage:welcome --onboard` (the Phase 4 wipCap prompt) or by inspecting / editing the typed field via `deft policy:show --field=wipCap`.
+The `plan.policy.wipCap` field caps the number of in-flight scope xBRIEFs (`xbrief/pending/` + `xbrief/active/`). The framework default is 20 (#2319; raised from the original 10 per umbrella #1119 Current Shape v3). When the cap is reached, `deft scope:promote` refuses with a relief hint pointing at `deft scope:demote --batch --older-than-days 30` (D1 / #1121). Operators can override the cap from the consumer side via `deft triage:welcome --onboard` (the Phase 4 wipCap prompt) or by inspecting / editing the typed field via `deft policy:show --field=wipCap`.
 
 ## xBRIEF layout (#2034 / #2110)
 
@@ -130,6 +130,31 @@ Deft ships versioned content packs (e.g. lessons learned from prior work) under
 
 Skill routing (which skill answers which trigger) is not a table in this policy section. To pick a skill, scan the **Skills Index** (Level-0) in `.deft/core/REFERENCES.md` — it lists every skill under `.deft/core/.agents/skills/` with a one-sentence description and trigger keywords, unified with the framework doc routing so you consult one place to decide what to load. Read a `SKILL.md` (Level-1) only when the index indicates a match. Before improvising a multi-step workflow, scan the skills catalog first — skills are versioned and tested. The `welcome` / `onboard triage` trigger invokes `deft triage:welcome --onboard` (N3 / #1143); for `lessons` / `prior art`, discover packs with `deft packs:slice --list-packs` then load the relevant slice (see Content packs above).
 
+## Review-surface precedence (#2308)
+
+! When the active host harness exposes its own review-labeled surfaces -- Cursor's `bugbot` / `security-review` Task **subagent types**, the `review-bugbot` / `review-security` **skills**, or any future host equivalent -- the orchestrator MUST route review work through the canonical `deft-directive-review-cycle` skill. A generic "review this" / "get this reviewed" / "use sub-agents for reviews" request maps to `deft-directive-review-cycle` by intent, not literal keyword (extends #1862 / #2261).
+
+~ Host review tools MAY be folded in as *advisory* finding sources inside the review cycle (the #2019 harness-aware-reviewer path) -- their findings are batched alongside Greptile / bot findings, never treated as the review of record.
+
+⊗ Substitute a host-native review subagent type or `review-*` skill for `deft-directive-review-cycle` as the review surface -- the host review tools are advisory inputs, not a replacement. This is the 3rd recurrence of the #1862 / #2261 intent-routing / wrong-review-surface class (see also #2019, #2018).
+
+## Value feedback and attribution (#1709)
+
+- ! `plan.policy.valueFeedback.enabled` defaults OFF -- while false, every downstream path (emit-only ledger, budgeted session readback, upstream gap escalation) short-circuits with zero token spend. Opt-in ONLY via `deft policy:enable-value-feedback -- --confirm` after the capability-cost disclosure prints. Inspect with `deft policy:show --field=valueFeedback`.
+- ! Value claims MUST be attributed-only -- point to concrete logged events ("encoding gate caught 2 corruptions"), never vague quality claims. Silence when the ledger has nothing attributable for the session slot.
+- ! Budgeted awareness -- at most one session readback line when `sessionLine` is allowed; repeat suppression uses a 4-hour window per attribution event id (parity with #1279 triage welcome debounce). Pull-based detail is `deft value:show`, not pushed.
+- ! Gap escalation to `deftai/directive` is confirmation-gated -- route conversational filing through `deft-directive-feedback`; the agent drafts + dedups; the operator approves before `deft feedback:file -- --confirm`. Use `Refs #1709` in upstream bodies, not `Closes`.
+- ! Gap escalation is consumer-only -- no-op inside the directive maintainer repo unless `DEFT_VALUE_SELF_DOGFOOD=1`.
+- ⊗ Enable value-feedback surfaces without explicit operator confirmation on the typed policy flag.
+- ⊗ File upstream framework-gap issues without operator confirmation or past duplicate detection.
+- ⊗ Treat unattributed self-promotion as value feedback -- if there is no ledger event, emit nothing.
+
+## Eval and framework health (#1703)
+
+- ! Three tiers: **Tier 0** `deft eval:health` (static gate score + contradictory-gate detector; ledger: `.eval/results/health-history.jsonl`). **Tier 1** CRUD telemetry on scope transitions (`.eval/results/crud-metrics.jsonl`, automatic). **Tier 2** `deft eval:run` / `deft eval:report` (golden corpus champion–challenger + holdout tripwire).
+- ! Run `deft eval:health` when orienting, after gate/policy/doc changes, or when session start emits a budgeted `[eval]` nudge (score drop or contradictory gate; 4-hour debounce, parity #1279/#1709). Tier 2 is for maintainer release eval (`eval:run -- --model M`; `eval:report -- --champion V --challenger V --model M`).
+- ⊗ Discover eval only via CHANGELOG/`deft --list` — AGENTS.md and `deft triage:help` are canonical. ⊗ Treat Tier 1 telemetry as operator-invoked.
+
 ## Branch policy & branch verification
 
 Three consumer-facing surfaces enforce the branch-policy contract (#746 / #747):

package/vbrief/vbrief.md

@@ -19,7 +19,7 @@ Key `task` commands for working with vBRIEF files:
 - `task issue:ingest -- <N>` / `task issue:ingest -- --all [--label L] [--status S] [--dry-run]` — Ingest GitHub issues as scope vBRIEFs in `vbrief/proposed/` (deduplicates via existing references)
 - `task vbrief:validate` — Validate schema, filenames, folder/status consistency (part of `task check`)
 - `task scope:promote|activate|complete|cancel|restore|block|unblock <file>` — Lifecycle transitions
-- `task scope:decompose -- <parent.vbrief.json> --draft vbrief/.eval/decompositions/<parent-slug>.json` — Apply an approved phase/epic to story decomposition
+- `task scope:decompose -- <parent.vbrief.json> --draft vbrief/.triage-cache/decompositions/<parent-slug>.json` — Apply an approved phase/epic to story decomposition
 - `task swarm:readiness -- vbrief/active/*.vbrief.json` — Report whether candidate stories are safe for concurrent swarm allocation
 
 For interactive creation workflows, use `run` commands (`.deft/core/run bootstrap`, `.deft/core/run spec`). See [commands.md](../commands.md) for the full command lifecycle.
@@ -40,7 +40,7 @@ vbrief/
   plan.vbrief.json                 <- session-level tactical plan (singular)
   continue.vbrief.json             <- interruption checkpoint (singular, ephemeral)
   playbook-{name}.vbrief.json      <- reusable operational patterns
-  .eval/decompositions/             <- ignored temporary decomposition proposal drafts
+  .triage-cache/decompositions/             <- ignored temporary decomposition proposal drafts
   proposed/                         <- ideas, not committed to (draft, proposed)
   pending/                          <- accepted backlog (approved, pending)
   active/                           <- in progress (running, blocked)
@@ -277,10 +277,10 @@ When a scope grows too large, the parent vBRIEF becomes an epic and children are
 
 1. Agent identifies the scope is too large (collaboratively with user)
 2. Parent vBRIEF promoted to epic
-3. Agent drafts a temporary decomposition proposal under `vbrief/.eval/decompositions/<parent-slug>.json`
+3. Agent drafts a temporary decomposition proposal under `vbrief/.triage-cache/decompositions/<parent-slug>.json`
 4. Agent presents the draft to the user and gets explicit approval
-5. `task scope:decompose -- <parent> --draft vbrief/.eval/decompositions/<parent-slug>.json --check` validates the approved draft
-6. `task scope:decompose -- <parent> --draft vbrief/.eval/decompositions/<parent-slug>.json` creates child story vBRIEFs with `planRef` back to parent
+5. `task scope:decompose -- <parent> --draft vbrief/.triage-cache/decompositions/<parent-slug>.json --check` validates the approved draft
+6. `task scope:decompose -- <parent> --draft vbrief/.triage-cache/decompositions/<parent-slug>.json` creates child story vBRIEFs with `planRef` back to parent
 7. Parent epic's `references` updated to list all child paths
 8. Update `plan.vbrief.json` (and `continue.vbrief.json` if present) `planRef` to reference child scope vBRIEFs
 9. Acceptance criteria redistributed by agent with user approval
@@ -288,7 +288,7 @@ When a scope grows too large, the parent vBRIEF becomes an epic and children are
 
 - ! Scope splitting MUST use an approved draft and `task scope:decompose` for child writes
 - ! Decomposition draft JSON is a temporary proposal artifact, not a vBRIEF
-- ! Agents SHOULD write decomposition draft proposals under `vbrief/.eval/decompositions/`
+- ! Agents SHOULD write decomposition draft proposals under `vbrief/.triage-cache/decompositions/`
 - ! Derive `<parent-slug>` from the parent vBRIEF filename by removing `.vbrief.json` and any leading `YYYY-MM-DD-` date prefix; for example, `2026-05-12-ip001-auth.vbrief.json` becomes `ip001-auth`
 - ⊗ Agents MUST NOT leave decomposition draft JSON files at the workspace root
 - ! Generated child story vBRIEFs remain lifecycle artifacts and default to `vbrief/pending/`