@deftai/directive-content 0.70.0 → 0.71.1

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

@@ -0,0 +1,10 @@
+---
+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.
+---
+
+Read and follow: skills/deft-directive-feedback/SKILL.md

package/Taskfile.yml

@@ -248,6 +248,12 @@ includes:
   triage-smoketest:
     taskfile: ./tasks/triage-smoketest.yml
     optional: true
+  # D17 (#1709): `task triage:metrics` trend readout from summary-history.jsonl.
+  # Inner task `metrics` is exposed as the user-facing alias `task triage:metrics`
+  # in the alias block below.
+  triage-metrics:
+    taskfile: ./tasks/triage-metrics.yml
+    optional: true
   # Windows maintainer onboarding fragment (#902). Exposes the inner task
   # `toolchain` as `task setup:toolchain`. Note: the root-level `setup` task
   # below (git-hooks bootstrap) coexists with `setup:toolchain` because
@@ -295,6 +301,21 @@ includes:
   capacity:
     taskfile: ./tasks/capacity.yml
     optional: true
+  # Tier 0 framework-eval surface (#1703). Exposes `task eval:health` --
+  # aggregates static self-consistency gates into a versioned health score.
+  eval:
+    taskfile: ./tasks/eval.yml
+    optional: true
+  # Gap escalation upstream filing (#1709 child 5). Exposes `task feedback:file` --
+  # confirmation-gated, deduped framework-gap issues for consumer projects.
+  feedback:
+    taskfile: ./tasks/feedback.yml
+    optional: true
+  # Pull-based value-awareness readbacks (#1709). Inner task `show` is exposed as
+  # `task value:show` via the include namespace key.
+  value:
+    taskfile: ./tasks/value.yml
+    optional: true
   # Pack-slicing surface (#1283 design, #1294 pilot, ADR-001 Layer B). Exposes
   # `task packs:slice` (named-slice API), `task packs:render` (regenerate the
   # meta/lessons.md projection), and `task packs:verify-drift` (the drift gate,
@@ -854,6 +875,13 @@ tasks:
         vars:
           CLI_ARGS: "{{.CLI_ARGS}}"
 
+  triage:metrics:
+    desc: "Trend lines from summary-history.jsonl (#1709 / D17). -- task triage:metrics -- [--window=7d|30d] [--format=text|json]"
+    cmds:
+      - task: triage-metrics:metrics
+        vars:
+          CLI_ARGS: "{{.CLI_ARGS}}"
+
   triage:queue:
     desc: "Print the ranked triage queue (#1128 / D11). -- task triage:queue [-- --repo OWNER/NAME] [--limit N]"
     cmds:

package/UPGRADING.md

@@ -261,6 +261,7 @@ runs the doctor first gets pointed at this exact two-step before touching `init`
 - **From v0.27.x — mostly auto-handled.** Pick up the install manifest and the `deft/` → `.deft/core/` layout: [From v0.27.x → v0.28](#from-v027x---v028-canonical-install-manifest-at-installversion), [From deft/ → .deft/core/](#from-deft---deftcore), and [From drifted AGENTS.md → current install](#from-drifted-agentsmd---current-install-task-upgrade-repair-path-1061).
 - **From v0.60.x — manual (hook refresh).** After #2049, consumer `.githooks/` dispatch through the `deft` CLI only. Run [From v0.60.0 → v0.61.x (refresh project-root git hooks, #2049)](#from-v0600--v061x-refresh-project-root-git-hooks-2049) after every framework upgrade that touches hook templates.
 - **From v0.28–v0.36 (and the final hop to current) — auto-handled.** If still on the Go-installer layout, follow the [One-time migration from the Go installer](#one-time-migration-from-the-go-installer-legacy--npm) above, then `npm i -g @deftai/directive@latest` for all future upgrades.
+- **From v0.70.x — auto-handled (lazy).** The triage working-set cache moved off `.eval/` to `.triage-cache/`; run any triage/scope/doctor command once after upgrade to trigger the lazy migration: [From v0.70.x → v0.71.0 (triage cache relocation, #1703)](#from-v070x--v0710-triage-cache-relocation-1703).
 
 **Final step for every bucket.** Finish on the canonical npm upgrade path, then let the doctor confirm you are current:
 
@@ -275,6 +276,31 @@ Run those from your project root after any bucket-specific hops (`deft update` r
 
 ---
 
+## From v0.70.x → v0.71.0 (triage cache relocation, #1703)
+
+- **Applies when:** any project on deft v0.70.x (or earlier releases that stored the triage working-set under `<lifecycle-root>/.eval/`) that upgrades to v0.71.0+. Detection: after upgrade, triage append-only logs (`candidates.jsonl`, `slices.jsonl`, `summary-history.jsonl`, `scope-lifecycle.jsonl`, `subscription-history.jsonl`, `doctor-state.json`, `decompositions/`, `README.md`) still live under `<lifecycle-root>/.eval/` instead of `<lifecycle-root>/.triage-cache/`. The `<lifecycle-root>` is `xbrief/` or legacy `vbrief/` depending on your layout.
+- **Safe to auto-run:** Yes (lazy, idempotent). The engine migrates each known legacy file/dir from `.eval/` → `.triage-cache/` the first time any triage/scope/doctor path is resolved after upgrade — for example `deft triage:summary`, `deft triage:bootstrap`, `deft doctor`, or any scope transition that touches the triage cache. Nothing to do manually beyond running one of those commands once; re-runs are no-ops.
+- **Restart required:** No for the filesystem migration itself. Start a **new agent session** after upgrade if your session still cites the old `.eval/` triage paths in AGENTS.md or skill prose loaded before the deposit refresh.
+- **Commands:**
+  - `deft triage:summary` (or any other triage/scope/doctor verb — triggers lazy migration on first resolve)
+  - `deft doctor` (also resolves triage-cache paths during install-integrity checks)
+  - `ls <lifecycle-root>/.triage-cache/` (confirm relocated files after the first trigger)
+
+### What changed
+
+- **Triage working-set moved.** Append-only triage logs, decomposition scratch, and the deposited triage README now resolve under `<lifecycle-root>/.triage-cache/` instead of `<lifecycle-root>/.eval/`.
+- **`.eval/` reclaimed for framework eval.** The `.eval/` namespace is now the version-eval results store at `<lifecycle-root>/.eval/results/` (health/golden/crud ledgers from #1703). This store had no prior home — it is not a rename of the triage cache.
+- **Lazy migration, not upgrade-triggered.** `deft update`, `deft migrate`, and `deft migrate:xbrief` do **not** relocate the triage working-set. The last copies `vbrief/.eval/` → `xbrief/.eval/` as-is when crossing the xbrief rename; the triage relocation fires only on triage/scope/doctor path resolve. There is no dedicated `migrate:triage-cache` verb.
+- **Conflict policy (canonical wins).** When both a legacy `.eval/` copy and a canonical `.triage-cache/` copy of the same basename exist, the legacy `.eval/` entry is skipped — the canonical `.triage-cache/` file wins. The migration is idempotent.
+
+### References
+
+- [#1703](https://github.com/deftai/directive/issues/1703) — triage working-set relocation + framework-eval results store.
+- [#2349](https://github.com/deftai/directive/issues/2349) — operator-facing upgrade documentation for this relocation.
+- [`packages/core/src/triage/cache-path.ts`](../packages/core/src/triage/cache-path.ts) — `migrateLegacyTriageCacheFromEval()` implementation.
+
+---
+
 ## From v0.60.0 → v0.61.x (refresh project-root git hooks, #2049)
 
 - **Applies when:** your project was on deft v0.60.x (or earlier) with `.githooks/` installed via `deft setup` / the npm deposit path, and hooks still invoke legacy Python scripts (`scripts/preflight_branch.py`, `scripts/preflight_gh.py`, etc.). Detection: `deft verify:hooks-installed` fails with "still dispatches through Python scripts (expected deft CLI only, #2049)" or pre-commit/pre-push errors mentioning missing `scripts/*.py` on Python-free installs.

package/contracts/deterministic-questions.md

@@ -1,5 +1,5 @@
 # Deterministic Questions Contract
-Canonical rule for every structured `ask_user_question` prompt and every numbered-menu prompt rendered in skill prose. Lives once here so individual skills can `!` cross-reference instead of duplicating the rule body. Surfaced by #767 after the 2026-04-30 swarm-planning session where users typed `discuss (user-provided)` to break out of a deterministic question and `wait` at a hard gate -- both honored by convention only.
+Canonical rule for every structured `ask_user_question` prompt, every agent-initiated ad-hoc structured question outside any skill (orchestration approvals, dispatch confirmations, decision walkthroughs), and every numbered-menu prompt rendered in skill prose. Lives once here so individual skills and always-loaded policy surfaces can `!` cross-reference instead of duplicating the rule body. Surfaced by #767 after the 2026-04-30 swarm-planning session where users typed `discuss (user-provided)` to break out of a deterministic question and `wait` at a hard gate -- both honored by convention only. Runtime enforcement for agent-initiated prompts is #1470 (AGENTS.md managed section + orchestrator preamble self-check).
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 **See also**: [main.md](../../main.md) | [glossary.md](../glossary.md) (deterministic mode entry) | [skills/deft-directive-interview/SKILL.md](../skills/deft-directive-interview/SKILL.md) (canonical interview loop) | [vbrief/completed/2026-04-20-431-deterministic-questions-rc2-defects.vbrief.json](../../vbrief/completed/2026-04-20-431-deterministic-questions-rc2-defects.vbrief.json) (RC2 prior art)
 ## Prior art reviewed (#431)
@@ -9,12 +9,12 @@ The RC2 work in #431 (closed; "Deterministic questions (RC2): confirm step, back
 3. **Confirmation step before destructive write** -- post-interview confirmation gates (e.g. `skills/deft-directive-setup/SKILL.md` Post-Interview Confirmation Gate) are independent of the option list and ride on top of every deterministic flow.
 This contract EXTENDS that surface by promoting `Discuss` to a peer of `Back` (both are now mandatory final options) and by codifying the Discuss-pause semantic verbatim. It does NOT introduce a separate `Other` option; this contract is purely about adding `Discuss` + `Back` as canonical numbered options. The pre-#767 surface (back navigation, confirm step, Other-vs-escape distinction) remains intact.
 ## The rule
-- ! Every structured `ask_user_question` prompt (single-select OR multi-select) and every numbered-menu prompt rendered in skill prose MUST include `Discuss` and `Back` as the final two numbered options, in that order. The numbering is local to the prompt (it does not need to be the literal "N-1" / "N" -- it just needs to be the last two entries presented to the user).
+- ! Every structured `ask_user_question` prompt (single-select OR multi-select), every agent-initiated ad-hoc structured question emitted outside any skill flow, and every numbered-menu prompt rendered in skill prose MUST include `Discuss` and `Back` as the final two numbered options, in that order. The numbering is local to the prompt (it does not need to be the literal "N-1" / "N" -- it just needs to be the last two entries presented to the user).
 - ! `Discuss` MUST be a top-level numbered option, NOT a sub-choice of any `Other` / `Custom` option. Honoring #431's escape-hatch principle.
 - ! `Back` MUST return to the prior question or decision point. Selecting `Back` from the very first question of a flow returns to the calling skill's entry-point (or surfaces "Nothing earlier to go back to" and re-asks the current question).
 - ⊗ Render a deterministic numbered menu without `Discuss` and `Back` as the final two options.
 - ⊗ Combine `Discuss` and `Other` into one option. They serve different roles -- `Other` widens the question's answer space; `Discuss` exits the question entirely.
-- ⊗ Render `Discuss` or `Back` only in some skills -- the rule is universal across every deterministic-mode skill.
+- ⊗ Render `Discuss` or `Back` only in some skills or only in skill prose -- the rule is universal across every deterministic question, including agent-initiated ad-hoc `ask_user_question` prompts outside any skill.
 ## Host-UI portability rule (#1563)
 Host-native structured question tools are allowed only when they preserve the deterministic menu the user actually sees. The visible labels and the fallback mapping are the contract; host UI affordances are not.
 - ! Deterministic flows MUST render the canonical numbered menu in plain chat text unless the host-native structured UI is known to visibly preserve the canonical numeric option labels and return numeric selections or exact displayed option text.
@@ -56,4 +56,4 @@ Each affected skill carries a `!` cross-reference pointing here, mirroring the R
 - `skills/deft-directive-release/SKILL.md`
 The `interview` and `build` skills are deliberately not edited under #767 (Agents 2 / 3 own those surfaces); the cross-reference will land there in their PRs and read this contract.
 ## Test surface
-`tests/content/test_deterministic_questions.py` scans skill prose for documented numbered menus and asserts that `Discuss` and `Back` are the final two options. The test also asserts that this contract file exists, contains the verbatim Discuss-pause semantic, and is cross-referenced from each affected skill.
+`packages/core/src/content-contracts/skills/deterministic_questions.test.ts` (port of `tests/content/test_deterministic_questions.py`) scans skill prose for documented numbered menus and asserts that `Discuss` and `Back` are the final two options. The test also asserts that this contract file exists, contains the verbatim Discuss-pause semantic, names agent-initiated ad-hoc prompts in scope, and is cross-referenced from each affected skill. Always-loaded runtime obligation markers are enforced separately via `agents_entry_contract.test.ts` (AGENTS.md managed section + template) and the orchestrator preamble self-check section in `templates/agent-prompt-preamble.md` (#1470).

package/events/README.md

@@ -14,7 +14,7 @@ data-file-convention check follow-up
 
 - `registry.json` — single source of truth for every event name, category,
   payload contract, detector / emission pointer, and consumer pointers.
-  Lists 5 `detection-bound` events and 4 `behavioral` events (9 total).
+  Lists 5 `detection-bound` events and 9 `behavioral` events (14 total).
 - `registry.schema.json` — schema validating the registry's shape, including
   the required `category` enum (`detection-bound` | `behavioral`).
 - `event-record.schema.json` — schema for individual emitted event records.

package/events/registry.json

@@ -161,6 +161,83 @@
         "scripts/migrate_vbrief.py -- wires the emitter into all three _emit_legacy_artifacts call sites (SPECIFICATION / PROJECT / PRD captures)",
         "(deferred -- no downstream handler in this PR; future migrate:vbrief audit reporting and consumer-facing legacy-handling skills will subscribe by name)"
       ]
+    },
+    {
+      "name": "value:gate-catch",
+      "category": "behavioral",
+      "description": "A detection-bound gate refused an action (branch protection, session ritual, encoding, etc.) while value feedback is enabled. Powers attributed value readbacks (#1709).",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordGateCatch when verify:branch (or other wired gate) returns a blocking exit and plan.policy.valueFeedback.emitEvents is allowed.",
+      "payload": {
+        "signal_class": "string enum -- always `value` for this event name",
+        "source": "string -- canonical gate id (e.g. verify:branch)",
+        "detail": "string -- one-line human context for the catch"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts -- emit helper gated on valueFeedback",
+        "(deferred) skills/deft-directive-sync -- budgeted session readback (#1709 child 4)"
+      ]
+    },
+    {
+      "name": "value:wip-cap-protect",
+      "category": "behavioral",
+      "description": "verify:wip-cap refused a merge/promote because pending+active count exceeds plan.policy.wipCap (#1124).",
+      "trigger": "packages/core/src/wip-cap/evaluate.ts when count >= cap without --allow-over-cap and valueFeedback emitEvents is allowed.",
+      "payload": {
+        "signal_class": "string enum -- always `value`",
+        "source": "string -- verify:wip-cap",
+        "count": "integer -- in-flight scope count",
+        "cap": "integer -- resolved wipCap"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts::recordWipCapProtect",
+        "(deferred) task deft:value:show trend readout (#1709 child 4)"
+      ]
+    },
+    {
+      "name": "bypass:off-flow",
+      "category": "behavioral",
+      "description": "Consumer went off-flow (skipped checks, wrote code without active vBRIEF, skipped pre-PR, etc.) while value feedback is enabled.",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordBypassSignal from wired bypass detectors (initial taxonomy entry; sources land in follow-up stories).",
+      "payload": {
+        "signal_class": "string enum -- always `bypass`",
+        "source": "string -- detector id",
+        "detail": "string -- one-line context"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts",
+        "(deferred) boundary-awareness readback (#1709 child 4)"
+      ]
+    },
+    {
+      "name": "adoption:unused-capability",
+      "category": "behavioral",
+      "description": "Directive capability was applicable to the current work but unused (decompose, cost, pre-PR, etc.).",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordAdoptionSignal and future adoption-registry module (#1709 child 3).",
+      "payload": {
+        "signal_class": "string enum -- always `adoption`",
+        "source": "string -- registry module id",
+        "capability": "string -- capability slug (e.g. decompose, pre-pr)",
+        "detail": "string -- one-line applicability context"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts",
+        "(deferred) packages/core/src/value/adoption-registry.ts (#1709 child 3)"
+      ]
+    },
+    {
+      "name": "friction:directive-gap",
+      "category": "behavioral",
+      "description": "Directive fell short (improvised workflow, gate false-positive, ambiguous rule) and may warrant upstream feedback.",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordFrictionSignal from friction detectors and gap-escalation skill (#1709 child 5).",
+      "payload": {
+        "signal_class": "string enum -- always `friction`",
+        "source": "string -- detector id",
+        "detail": "string -- one-line gap description"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts",
+        "(deferred) task deft:feedback:file / deft-directive-feedback skill (#1709 child 5)"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.70.0",
+  "version": "0.71.1",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "type": "module",
   "files": [

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

@@ -73,7 +73,7 @@
       ],
       "path": "skills/deft-directive-decompose/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Decompose\n\nUse this skill when a specification, Phase 4 implementation scope, or epic xBRIEF is too broad for direct concurrent swarm work and must be decomposed into story-level xBRIEFs.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [strategies/speckit.md](../../strategies/speckit.md) Phase 4.5 | [vbrief/vbrief.md](../../vbrief/vbrief.md) Swarm-Ready Story Contract | [deft-directive-swarm](../deft-directive-swarm/SKILL.md)\n\n## Purpose\n\nConvert approved specification/phase/epic scope xBRIEFs into swarm-ready child story xBRIEFs. Story xBRIEFs are the only valid input for concurrent swarm worker allocation.\n\n## Phase 0: Inspect\n\n- ! Read `xbrief/specification.xbrief.json` and relevant scope xBRIEFs from `xbrief/proposed/`, `xbrief/pending/`, and `xbrief/active/`.\n- ! Identify broad scopes with `plan.metadata.kind = \"phase\"` or `\"epic\"` or scopes with broad `plan.narratives.Acceptance` and empty `plan.items`.\n- ! Preserve parent acceptance as context; do not treat it as executable story acceptance.\n- ! Treat parent `plan.items` as input signals only; they are not automatically child stories.\n- ! Inspect relevant codebase paths before drafting file scope so stories reflect real product/code boundaries, not only parent scope prose.\n- ! Identify requirement traces, likely file scope, verification commands, outputs/evidence, dependencies, and conflict groups.\n- ⊗ Allocate a broad phase/epic scope to concurrent workers during this skill.\n\n## Phase 1: Draft\n\n- ! Draft a decomposition JSON proposal with child stories only; do not write child xBRIEFs yet.\n- ! Treat the draft JSON as a temporary proposal artifact, not a xBRIEF.\n- ! Write draft proposals under `xbrief/.eval/decompositions/`, using a parent-derived slug such as `xbrief/.eval/decompositions/ip001-auth.json`.\n- ! 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`.\n- ⊗ Agents MUST NOT leave decomposition draft JSON files at the workspace root.\n- ! 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`.\n- ! `Description` MUST provide at least two concrete sentences explaining the user/product behavior, boundaries, and why this story is independently buildable.\n- ! `ImplementationPlan` MUST provide at least two concrete implementation steps that identify the expected code path, state/data changes, and test/evidence approach.\n- ! `UserStory` MUST use the exact product-story shape `As a <role>, I want <capability>, so that <outcome>.`.\n- ! Each ready story MUST have 2-5 concrete acceptance criteria unless `swarm.acceptance_criteria_justification` explains the exception.\n- ! Acceptance criteria MUST be observable behavior, preferably Given/When/Then or equivalent testable product behavior.\n- ⊗ Mark a story ready when acceptance says only \"to refine from parent scope\", duplicates the title/description, is placeholder text, or is vague docs-only acceptance.\n- ⊗ Mark a story ready with broad write scope such as `backend/**`, `frontend/**`, `docs/**`, `xbrief/**`, or any other directory glob.\n- ⊗ Mark a story ready when verification is only generic validation such as `task check`.\n- ⊗ Mark a story ready with `parallel_safe: false` or `file_scope_confidence: low`; use `readiness: sequential` or `readiness: needs_refinement` instead.\n- ! Model dependencies as story IDs and ensure they form a DAG.\n- ~ Draft sequential-safe or low-confidence work as `readiness: sequential` or `readiness: needs_refinement`; it is not eligible for concurrent allocation.\n- ⊗ Use deprecated `subItems` in newly drafted story items; use `items`.\n\n## Phase 2: Approval\n\n- ! Present the decomposition draft to the user before writing files.\n- ! Ask for explicit approval to apply the draft.\n- ! If the user requests changes, revise the draft and re-present it.\n- ! After explicit approval, run `task scope:decompose ... --check`, then apply without `--check`.\n- ? Run `task scope:decompose ... --check` before explicit approval only to validate a draft without writing files.\n- ⊗ Apply `task scope:decompose` without `--check` before explicit approval.\n\n## Phase 3: Apply\n\n- ! Validate the approved draft first:\n\n```bash\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.eval/decompositions/ip001-auth.json --check\n```\n\n- ! Apply the approved draft:\n\n```bash\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.eval/decompositions/ip001-auth.json\n```\n\nThe 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.\n\n## Phase 4: Pending Readiness\n\n- ! Run readiness against the generated pending child story paths after decomposition:\n\n```bash\ntask swarm:readiness -- xbrief/pending/<child-story-1>.xbrief.json xbrief/pending/<child-story-2>.xbrief.json\n```\n\n- ! Treat this as a dry readiness review before activation; do not allocate workers from pending paths.\n- ! Route blocked or overlapping stories back to Phase 1 for draft refinement.\n- ! Leave lifecycle promotion/activation to the existing approved flow (`task scope:promote`, `task scope:activate`, and the swarm skill lifecycle bridge).\n- ⊗ Promote or activate child stories solely because decomposition succeeded.\n\n## Exit\n\ndeft-directive-decompose complete -- exiting skill. Next, activate the approved child story xBRIEFs through the existing lifecycle flow, then run `skills/deft-directive-swarm/SKILL.md` for concurrent allocation.\n",
+      "body": "# Deft Directive Decompose\n\nUse this skill when a specification, Phase 4 implementation scope, or epic xBRIEF is too broad for direct concurrent swarm work and must be decomposed into story-level xBRIEFs.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [strategies/speckit.md](../../strategies/speckit.md) Phase 4.5 | [vbrief/vbrief.md](../../vbrief/vbrief.md) Swarm-Ready Story Contract | [deft-directive-swarm](../deft-directive-swarm/SKILL.md)\n\n## Purpose\n\nConvert approved specification/phase/epic scope xBRIEFs into swarm-ready child story xBRIEFs. Story xBRIEFs are the only valid input for concurrent swarm worker allocation.\n\n## Phase 0: Inspect\n\n- ! Read `xbrief/specification.xbrief.json` and relevant scope xBRIEFs from `xbrief/proposed/`, `xbrief/pending/`, and `xbrief/active/`.\n- ! Identify broad scopes with `plan.metadata.kind = \"phase\"` or `\"epic\"` or scopes with broad `plan.narratives.Acceptance` and empty `plan.items`.\n- ! Preserve parent acceptance as context; do not treat it as executable story acceptance.\n- ! Treat parent `plan.items` as input signals only; they are not automatically child stories.\n- ! Inspect relevant codebase paths before drafting file scope so stories reflect real product/code boundaries, not only parent scope prose.\n- ! Identify requirement traces, likely file scope, verification commands, outputs/evidence, dependencies, and conflict groups.\n- ⊗ Allocate a broad phase/epic scope to concurrent workers during this skill.\n\n## Phase 1: Draft\n\n- ! Draft a decomposition JSON proposal with child stories only; do not write child xBRIEFs yet.\n- ! Treat the draft JSON as a temporary proposal artifact, not a xBRIEF.\n- ! Write draft proposals under `xbrief/.triage-cache/decompositions/`, using a parent-derived slug such as `xbrief/.triage-cache/decompositions/ip001-auth.json`.\n- ! 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`.\n- ⊗ Agents MUST NOT leave decomposition draft JSON files at the workspace root.\n- ! 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`.\n- ! `Description` MUST provide at least two concrete sentences explaining the user/product behavior, boundaries, and why this story is independently buildable.\n- ! `ImplementationPlan` MUST provide at least two concrete implementation steps that identify the expected code path, state/data changes, and test/evidence approach.\n- ! `UserStory` MUST use the exact product-story shape `As a <role>, I want <capability>, so that <outcome>.`.\n- ! Each ready story MUST have 2-5 concrete acceptance criteria unless `swarm.acceptance_criteria_justification` explains the exception.\n- ! Acceptance criteria MUST be observable behavior, preferably Given/When/Then or equivalent testable product behavior.\n- ⊗ Mark a story ready when acceptance says only \"to refine from parent scope\", duplicates the title/description, is placeholder text, or is vague docs-only acceptance.\n- ⊗ Mark a story ready with broad write scope such as `backend/**`, `frontend/**`, `docs/**`, `xbrief/**`, or any other directory glob.\n- ⊗ Mark a story ready when verification is only generic validation such as `task check`.\n- ⊗ Mark a story ready with `parallel_safe: false` or `file_scope_confidence: low`; use `readiness: sequential` or `readiness: needs_refinement` instead.\n- ! Model dependencies as story IDs and ensure they form a DAG.\n- ~ Draft sequential-safe or low-confidence work as `readiness: sequential` or `readiness: needs_refinement`; it is not eligible for concurrent allocation.\n- ⊗ Use deprecated `subItems` in newly drafted story items; use `items`.\n\n## Phase 2: Approval\n\n- ! Present the decomposition draft to the user before writing files.\n- ! Ask for explicit approval to apply the draft.\n- ! If the user requests changes, revise the draft and re-present it.\n- ! After explicit approval, run `task scope:decompose ... --check`, then apply without `--check`.\n- ? Run `task scope:decompose ... --check` before explicit approval only to validate a draft without writing files.\n- ⊗ Apply `task scope:decompose` without `--check` before explicit approval.\n\n## Phase 3: Apply\n\n- ! Validate the approved draft first:\n\n```bash\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.triage-cache/decompositions/ip001-auth.json --check\n```\n\n- ! Apply the approved draft:\n\n```bash\ntask scope:decompose -- xbrief/pending/2026-05-12-ip001-auth.xbrief.json --draft xbrief/.triage-cache/decompositions/ip001-auth.json\n```\n\nThe 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.\n\n## Phase 4: Pending Readiness\n\n- ! Run readiness against the generated pending child story paths after decomposition:\n\n```bash\ntask swarm:readiness -- xbrief/pending/<child-story-1>.xbrief.json xbrief/pending/<child-story-2>.xbrief.json\n```\n\n- ! Treat this as a dry readiness review before activation; do not allocate workers from pending paths.\n- ! Route blocked or overlapping stories back to Phase 1 for draft refinement.\n- ! Leave lifecycle promotion/activation to the existing approved flow (`task scope:promote`, `task scope:activate`, and the swarm skill lifecycle bridge).\n- ⊗ Promote or activate child stories solely because decomposition succeeded.\n\n## Exit\n\ndeft-directive-decompose complete -- exiting skill. Next, activate the approved child story xBRIEFs through the existing lifecycle flow, then run `skills/deft-directive-swarm/SKILL.md` for concurrent allocation.\n",
       "frontmatter_extra": null
     },
     {

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/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,6 +52,16 @@ 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 20 (#2319; raised from the original 10 per umbrella #1119 Current Shape v3)."
     dir: '{{.USER_WORKING_DIR}}'

package/tasks/slice.yml

@@ -56,7 +56,7 @@ tasks:
           ENGINE_CMD: 'slice record-existing {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'
 
   list:
-    desc: "List recorded slices in vbrief/.eval/slices.jsonl (umbrella + child count + actor + sliced_at). -- task slice:list [-- --json]"
+    desc: "List recorded slices in <lifecycle-root>/.triage-cache/slices.jsonl (umbrella + child count + actor + sliced_at). -- task slice:list [-- --json]"
     internal: true
     dir: '{{.USER_WORKING_DIR}}'
     deps:

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/triage-summary.yml

@@ -21,7 +21,7 @@ vars:
 
 tasks:
   summary:
-    desc: "Emit the D2 (#1122) one-line triage state for the session-start ritual (N9 / #1149). Always exits 0; appends a JSONL record to vbrief/.eval/summary-history.jsonl. -- task triage:summary -- [--json] [--no-history]"
+    desc: "Emit the D2 (#1122) one-line triage state for the session-start ritual (N9 / #1149). Always exits 0; appends a JSONL record to <lifecycle-root>/.triage-cache/summary-history.jsonl. -- task triage:summary -- [--json] [--no-history]"
     internal: true
     # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     dir: '{{.USER_WORKING_DIR}}'

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/templates/agent-prompt-preamble.md

@@ -258,6 +258,30 @@ 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.
+
+## 5.8 Deterministic questions runtime self-check (#1470)
+
+The #767 contract applies to skill prose AND to agent-initiated structured questions at runtime. Prose-scanning tests cannot observe host `ask_user_question` tool calls — workers and orchestrators MUST self-enforce before every structured prompt.
+
+- ! Before calling any host structured-question tool (`ask_user_question`, Cursor `AskQuestion`, or equivalent) OR rendering any numbered decision menu in chat — inside or outside a skill — verify the final two options are `Discuss` then `Back`, in that order.
+- ! On `Discuss` selection, halt immediately per the verbatim Discuss-pause semantic in `content/contracts/deterministic-questions.md`: no further tool calls beyond acknowledging the pause; prompt `What would you like to discuss?`; resume only on an explicit user signal (re-asking the original question, saying `resume`/`continue`, or re-issuing the prior selection).
+- ⊗ Rely on the host UI's `Other` affordance as the Discuss escape — it widens the answer space; `Discuss` exits the deterministic flow entirely (#767).
+- ⊗ Omit `Discuss`/`Back` on ad-hoc orchestration prompts (swarm approval, routing decisions, scope confirmations) — the highest-traffic runtime surface (#1470 recurrence).
+
+Reference: AGENTS.md `## Deterministic questions runtime obligation (#1470)`, `content/contracts/deterministic-questions.md`, issue #1470. Refs #767.
+
 ## 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

@@ -99,6 +99,15 @@ Rationale + cross-references: `.deft/core/docs/analysis/2026-07-02-agents-md-inc
 - ! Fetch issue comments via REST (`gh api repos/<owner>/<repo>/issues/<N>/comments`), read the `## Current shape (as of pass-N)` comment, and any linked context or `LockedDecisions` xBRIEF referenced there — following the reading order body -> current-shape comment -> amendment comments (claim-cites-state-surface, #2066). Prefer the deterministic read path: `deft umbrella:current-shape <N>` (or `task umbrella:current-shape <N>`) — it locates the canonical comment, validates #1152 sections, and never falls back to the issue body.
 - ⊗ Conclude umbrella or epic status from the issue body alone. Any "X is done" / "X is the blocker" assertion about an umbrella MUST cite the current-shape comment or another state artifact, not the body.
 
+## Deterministic questions runtime obligation (#1470)
+
+Rationale + cross-references: `.deft/core/content/contracts/deterministic-questions.md` (#767); closes the agent-runtime enforcement gap on issue #1470.
+
+- ! ANY agent-initiated structured question — whether via host `ask_user_question` / `AskQuestion` tooling or a numbered menu rendered in chat — inside OR outside any skill flow MUST include `Discuss` and `Back` as the final two options, in that order, and MUST obey the Discuss-pause semantic documented verbatim in `.deft/core/content/contracts/deterministic-questions.md`.
+- ! Before emitting any structured or numbered question, self-check: confirm `Discuss` and `Back` are present as the final two options; if not, add them before calling the tool or rendering the menu. Host-native `Other` / free-text affordances are NOT substitutes for `Discuss` (#767 / #431).
+- ⊗ Emit a structured or numbered question without `Discuss` and `Back` as the final two options — including ad-hoc orchestration approvals, dispatch confirmations, and decision walkthroughs outside interview/setup/refinement skills.
+- ⊗ Treat the host UI's automatic `Other` option as the stop-and-discuss escape hatch — `Other` widens the answer space; `Discuss` exits the deterministic flow entirely (see contract).
+
 ## Issue body→comments reading (#2143)
 
 Rationale + cross-references: `.deft/core/docs/analysis/2026-07-02-agents-md-incident-rule-rationale.md` § Issue body→comments reading (#2143); preamble § 5.6 in `.deft/core/content/templates/agent-prompt-preamble.md`.
@@ -138,6 +147,23 @@ Skill routing (which skill answers which trigger) is not a table in this policy
 
 ⊗ 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/`