@deftai/directive-content 0.104.0 → 0.106.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/Taskfile.yml +12 -6
  2. package/UPGRADING.md +6 -2
  3. package/coding/coding.md +2 -2
  4. package/commands.md +42 -17
  5. package/contracts/agent-hook-readiness.md +3 -3
  6. package/contracts/closed-verb-authz.md +14 -2
  7. package/contracts/design-critique.md +100 -0
  8. package/docs/directive-lifecycle.md +12 -4
  9. package/docs/project-invariants.md +79 -0
  10. package/docs/scope-provenance.md +53 -8
  11. package/main.md +3 -1
  12. package/meta/ralph.md +1 -1
  13. package/package.json +1 -1
  14. package/packs/rules/rules-pack-0.1.json +3 -3
  15. package/packs/skills/skills-pack-0.1.json +31 -11
  16. package/packs/strategies/strategies-pack-0.1.json +13 -13
  17. package/scm/github.md +35 -2
  18. package/skills/deft-directive-build/SKILL.md +26 -1
  19. package/skills/deft-directive-design-critique/SKILL.md +46 -0
  20. package/skills/deft-directive-gh-slice/SKILL.md +2 -2
  21. package/skills/deft-directive-probe/SKILL.md +4 -2
  22. package/skills/deft-directive-refinement/SKILL.md +1 -1
  23. package/skills/deft-directive-release/SKILL.md +5 -3
  24. package/skills/deft-directive-review-cycle/SKILL.md +38 -12
  25. package/skills/deft-directive-setup/SKILL.md +2 -0
  26. package/skills/deft-directive-swarm/SKILL.md +22 -6
  27. package/skills/deft-directive-swarm/references/core-ops.md +3 -1
  28. package/skills/deft-directive-swarm/references/core-phase-0.md +1 -0
  29. package/skills/deft-directive-swarm/references/core-phase-3.md +1 -1
  30. package/skills/deft-directive-swarm/references/core-phase-4.md +27 -11
  31. package/skills/deft-directive-swarm/references/core-phase-5-6.md +4 -1
  32. package/skills/deft-directive-sync/SKILL.md +1 -1
  33. package/strategies/README.md +4 -4
  34. package/strategies/bdd.md +6 -6
  35. package/strategies/discuss.md +8 -8
  36. package/strategies/emit-hints.md +6 -6
  37. package/strategies/enterprise.md +18 -18
  38. package/strategies/interview.md +4 -4
  39. package/strategies/map.md +6 -6
  40. package/strategies/probe.md +22 -18
  41. package/strategies/rapid.md +16 -16
  42. package/strategies/research.md +6 -6
  43. package/strategies/roadmap.md +1 -1
  44. package/strategies/speckit.md +52 -52
  45. package/strategies/v0-20-contract.md +21 -21
  46. package/strategies/yolo.md +12 -12
  47. package/tasks/engine.yml +2 -0
  48. package/tasks/occupancy.yml +17 -0
  49. package/tasks/policy.yml +10 -0
  50. package/tasks/scm.yml +13 -7
  51. package/tasks/scope.yml +2 -2
  52. package/tasks/vbrief.yml +3 -2
  53. package/tasks/verify.yml +34 -4
  54. package/tasks/xbrief.yml +43 -0
  55. package/templates/agent-prompt-preamble.md +16 -7
  56. package/templates/agents-entry.md +8 -3
  57. package/templates/design-critique-brief.md +41 -0
  58. package/vbrief/schemas/vbrief-core.schema.json +72 -0
@@ -69,29 +69,42 @@ tools: explore=0 commit=3 verify=0 coordinate=0 unknown=1 | anomalies: commit-wi
69
69
  | Stop | Default |
70
70
  |------|---------|
71
71
  | max iterations | **3** repair actions for the same leaf/PR failure class (resume prompt, takeover complete-remaining-steps, re-dispatch replacement, review re-trigger) |
72
- | no-progress | same error / same Greptile finding class / same idle stage **3+** times with no material worktree or review change |
72
+ | no-progress | same error / same idle stage **3+** times with no material worktree or review change. Same-fingerprint Greptile residual: [`deft-directive-review-cycle/SKILL.md`](../../deft-directive-review-cycle/SKILL.md) Dual stop — **Same-fingerprint stop** |
73
73
  | budget | honor `pr:watch` / poll max-wait and Greptile service-error single-retry+escalate caps; do not nest an unbounded poll outside them |
74
74
 
75
75
  ! When the failure stop fires: **halt** automatic repair/re-dispatch; emit an **operator-visible halt report** (what was tried, current stage, missing evidence, human decision needed). Prefer `BLOCKED:` over thin `DONE` when the unit cannot reach merge-ready inside the envelope.
76
76
 
77
- ! **Halt-report resume line (MUST, #3273 / AC6):** Terminal dual-stop / hard-stop / conf-residual halt reports MUST end with a copy-pasteable operator resume affordance so agents discover the follow-up path without prior chat memory:
77
+ ! **Halt-report resume line (MUST, #3273 / #3448):** Terminal dual-stop / hard-stop / conf-residual halt reports MUST end with a copy-pasteable operator resume affordance so agents discover the follow-up path without prior chat memory:
78
78
 
79
79
  ```
80
- RESUME: residual=<class> conf=<n/5|n/a> PR=<url>
81
- Operator may re-authorize **one residual pass** with: pursue residual | follow-up hard-stop | same as conf-hold | continue dual-stopped PR
80
+ RESUME: residual=<class> leftover=<A|B|C> conf=<n/5|n/a> floor=<resolved min|n/a> standing=<yes|one-shot> PR=<url>
81
+ Operator may re-authorize **one residual pass** (one-shot) with: pursue residual | follow-up hard-stop | same as conf-hold | continue dual-stopped PR
82
+ Standing order (open cohort/plan units, class A until resolved floor or same-fingerprint loop): until floor or loop | until greptile meets policy | pursue residuals until told otherwise
82
83
  Skill: deft-directive-swarm § Operator follow-up after dual-stop / hard stop (#3273) · deft-directive-review-cycle same section
83
84
  ```
84
85
 
85
- Residual class examples: `review_cycle_cap` / `greptile_p0_p1` / `conf_floor` / `no_progress` / `ci_weather` / `thin_done`.
86
+ Residual class examples: `review_cycle_cap` / `greptile_p0_p1` / `conf_floor` / `no_progress` / `ci_weather` / `thin_done`. Leftover class: **class A** already-touched in-AC residual · **class B** new subsystem / AC fight · **class C** score-only.
86
87
 
87
88
  ### Operator follow-up after dual-stop / hard stop (#3273)
88
89
 
89
- Operator-initiated resume after dual-stop, hard-stop, or conf-floor residual — **not** automatic re-thrash. Primary discovery is the halt-report resume line above; this section holds the steps. Portable for consumer deposit and maintainer tree (`task` / `deft` dual-invoke; no framework-monorepo-only path).
90
+ Operator-initiated resume after dual-stop, hard-stop, or conf-floor residual — **not** automatic re-thrash. Primary discovery is the halt-report resume line above; this section holds the steps. Portable for consumer deposit and maintainer tree (`task` / `deft` dual-invoke; no framework-monorepo-only path). Continue-until target is the **resolved `#3095` floor** (`plan.policy.review.minGreptileConfidence`: typed project policy > framework dogfood **5** > consumer default **4**; inspect `task policy:show --field=minGreptileConfidence` / `deft policy:show --field=minGreptileConfidence`). ⊗ Hard-code 5/5. ⊗ Lower project policy to clear one PR.
90
91
 
91
- **Triggers:** pursue residual · follow-up hard-stop · same as conf-hold · continue dual-stopped PR · re-babysit residual
92
+ **Leftover classes (A/B/C, #3448):**
92
93
 
93
- **One residual pass (then re-stop):**
94
- 1. Ground-truth: dual-invoke `pr:merge-ready` / `pr:watch --one-shot` on the PR (CLI `deft` first, then `task deft:` — see review-cycle #2893).
94
+ | Class | What it is | Auto-continue? |
95
+ |-------|------------|----------------|
96
+ | **class A** — named leftover on already-touched files | Wrong remediation, dropped field, fixture, same-module hole on files this PR already owns | **in-AC residual.** Continue until the resolved floor or same-fingerprint loop |
97
+ | **class B** — new subsystem / AC fight | New ledger, protocol, cross-cutting contract, or work that expands story meaning | Park or file follow-up. Do not expand mid-babysit |
98
+ | **class C** — score-only, no concrete finding | Confidence below the resolved floor, 0 P0/P1, no named leftover | Document / same-as-conf-hold / operator floor this-PR-only. Not unbounded redesign |
99
+
100
+ ! **Already-touched leftover is class A (#2881 / #3448):** a leftover on files **already in the PR** is class A unless it needs a new ledger, protocol, or story.
101
+
102
+ **One-shot vs standing (#3448):**
103
+ - **One-shot** triggers: pursue residual · follow-up hard-stop · same as conf-hold · continue dual-stopped PR · re-babysit residual — **one** pass on the unit that just halted, then re-stop. Do not silently widen.
104
+ - **Standing** triggers: **until floor or loop** · **until greptile meets policy** · **pursue residuals until told otherwise** — class A leftovers on **every open unit in the active cohort / ordered plan** keep moving until the resolved floor or the **Same-fingerprint stop** in [`deft-directive-review-cycle/SKILL.md`](../../deft-directive-review-cycle/SKILL.md) Dual stop. Class B/C stay parked unless the operator names them.
105
+
106
+ **One residual pass (then re-stop, or one standing batch):**
107
+ 1. Ground-truth: dual-invoke `pr:merge-ready` / `pr:watch --one-shot` on the PR (CLI `deft` first, then `task deft:` — see review-cycle #2893). Classify leftover A/B/C.
95
108
  2. If a delivery attempt is still active, cancel then begin with the **same unit ids** (exit 0 required before residual spawn) (#3228 / #3143):
96
109
  ```
97
110
  task swarm:pre-dispatch -- --scope-id <story-or-issue-or-xbrief-id> --target-id <worktree-path-or-branch> --action cancel
@@ -99,14 +112,17 @@ Operator-initiated resume after dual-stop, hard-stop, or conf-floor residual —
99
112
  ```
100
113
  3. Spawn **one** active residual worker or review-cycle owner (not sleep-only re-poll as the only work). Monitor MUST NOT self-implement product fixes after merge-ready leaf handback (#2843).
101
114
  4. If the operator authorized a conf floor for **this PR only** (e.g. ≥4/5): post a PR audit comment naming the floor, HEAD SHA, and who authorized it. That comment is the **human-merge / documented-override trail** — it does **not** rewrite `plan.policy.review.minGreptileConfidence` or make `pr:merge-ready` / `pr:watch` exit CLEAN below policy. Merge still requires policy CLEAN, bot-merge authority + override path, or human merge after the documented floor is met in the bot body. ⊗ Silent policy edit of `minGreptileConfidence` for one residual.
102
- 5. Wait re-review; merge when policy floor + gates met (or human-merge after documented PR-local floor). Run `scope:complete` + lifecycle land when in scope (#3264 / finalize).
115
+ 5. Wait re-review; merge when policy floor + gates met (or human-merge after documented PR-local floor). Run `scope:complete` + lifecycle land when in scope (#3264 / finalize). Halt reports MUST include leftover class + resolved floor + standing vs one-shot.
116
+
117
+ ! **Same-fingerprint stop:** [`deft-directive-review-cycle/SKILL.md`](../../deft-directive-review-cycle/SKILL.md) Dual stop — review fix loops (#2442) (normative). ⊗ Spawn another continuation leaf after a same-fingerprint `BLOCKED` handoff. `#2442` batch cap (max 3 repair actions) still applies.
103
118
 
104
- ! Dual-stop re-entry: after the residual pass (+ re-review wait), if still blocked, halt again with a fresh resume line. Another pass requires **new** operator consent.
119
+ ! Dual-stop re-entry: after the residual pass (+ re-review wait), if still blocked, halt again with a fresh resume line. Another **one-shot** pass requires **new** operator consent. A **standing** order MAY continue class A with a **new** fingerprint under the `#2442` cap.
105
120
 
106
121
  ⊗ Unlimited auto-retry after dual-stop without new operator consent (#3273 / #2442).
107
122
  ⊗ Sleep-only multi-hour re-poll as the sole residual work.
108
123
  ⊗ Parent/monitor self-implement after merge-ready leaf handback (#2843).
109
124
  ⊗ Lower project-wide `minGreptileConfidence` for one residual.
125
+ ⊗ Treat one-shot `pursue residual` as a standing order, or park a class A leftover on already-touched files because the score is below 5.
110
126
 
111
127
  ! Composes with minimal-subgraph repair (#2439): repairs stay minimal **and** dual-stop bounded. Mechanical delivery/acceptance circuit breaker: **#3143** `packages/core/src/delivery-attempt/` (`evaluatePreDispatch`). Docs: `docs/delivery-attempt.md`.
112
128
 
@@ -232,7 +232,7 @@ This is defense in depth -- run it even when the pre-merge inspection above pass
232
232
 
233
233
  ### Step 1.5: Cohort Completion Sweep (#1487)
234
234
 
235
- ! **REQUIRED.** Once the cohort's PRs are merged (Step 1 complete), the monitor MUST run the deterministic cohort completion sweep so the finished swarm leaves NO stranded xBRIEFs. This step closes the gap where a completed cohort left its story xBRIEFs in `xbrief/active/` and their decompose-created epic parents in `xbrief/pending/` -- nothing in the swarm flow swept them to `completed/` (observed in the 2026-06-03 swarm: after the cohort's PRs merged, the child story xBRIEFs stayed in `active/` and their epic parents stayed in `pending/`).
235
+ ! **REQUIRED.** Once the cohort's PRs are merged (Step 1 complete), the monitor MUST run the deterministic cohort completion sweep so the finished swarm leaves NO stranded xBRIEFs. `task swarm:complete-cohort` / `task swarm:finalize-cohort` release the swarm occupancy lease on a successful non-dry-run sweep (#3433). This step closes the gap where a completed cohort left its story xBRIEFs in `xbrief/active/` and their decompose-created epic parents in `xbrief/pending/` -- nothing in the swarm flow swept them to `completed/` (observed in the 2026-06-03 swarm: after the cohort's PRs merged, the child story xBRIEFs stayed in `active/` and their epic parents stayed in `pending/`).
236
236
 
237
237
  ! **Pre-sweep merge re-poll for human-merge / `stop-at: pr-open` (#3153):** Before invoking `task swarm:complete-cohort` or `task swarm:finalize-cohort`, re-read each cohort PR's merge state via REST. If any PR marked `awaiting-human-merge` is still open, **halt** the sweep, keep durable ownership, and continue the observe path (Phase 5 human-merge section) until merge or operator cancel. ⊗ Sweep on Greptile CLEAN alone while a human-merge PR is still open.
238
238
 
@@ -265,9 +265,12 @@ task swarm:finalize-cohort -- --stories <issue-or-path>... --repo <owner/repo>
265
265
 
266
266
  The finalize surface runs the same `completeCohort(...)` engine as `task swarm:complete-cohort`, fast-forwards the local base branch, creates a `swarm/finalize/<label>` feature branch (branch policy #747 safe), commits the `xbrief/` lifecycle moves, and auto-opens the sweep PR. Pass `--no-commit` to sweep only (manual Step 2b), or `--no-open-pr` to commit locally without opening the PR. Gate on exit 0 plus green `task xbrief:validate` before declaring the swarm closed.
267
267
 
268
+ ! **Drive-to last-leaf close (#3476):** After the last `drive-to: merge-ready` leaf of a cohort announces, parent `done` without same-turn `task swarm:finalize-cohort` (or a land PR already proving `task verify:completed-tracked` green on `origin/<deliveryBranch>`) is a **failed close**. Narrative-only `done` under #2934 is not enough when completed xBRIEFs exist only as untracked worktree residue. `scope:complete` stays filesystem-only -- do not teach every leaf to commit on master. Keep `verify:completed-tracked` off `task check`.
269
+
268
270
  ! **Manual fallback (#1487):** `task swarm:complete-cohort` remains the idempotent manual primitive when finalize automation is unavailable or you need a dry-run preview of transitions only. The headless path above replaces the historical requirement to hand-author a separate `chore(xbrief)` sweep PR every cycle.
269
271
 
270
272
  ⊗ Declare a swarm closed while any cohort story xBRIEF remains in `xbrief/active/` or any fully-childless decompose-created epic parent remains in `xbrief/pending/` -- run `task swarm:complete-cohort` and confirm `task xbrief:validate` is green first (#1487).
273
+ ⊗ After the last `drive-to` leaf, emit parent `done` without finalize-cohort / completed-tracked green on the delivery tip -- that is a failed close (#3476).
271
274
 
272
275
  ### Step 2: Close Issues and Update Origins
273
276
 
@@ -238,7 +238,7 @@ directive doctor
238
238
  - Top-level `xBRIEFInfo` envelope with `version` field present
239
239
  - `plan` object with `title`, `status`, and `items` fields present
240
240
  - `plan.status` values from valid enum: draft, proposed, approved, pending, running, completed, blocked, cancelled
241
- 3. ~ Use `task xbrief:validate` if available for deeper validation
241
+ 3. ~ Use `task xbrief:validate` for deeper validation
242
242
  4. ! Report any validation failures with file name and specific violation
243
243
 
244
244
  ⊗ Overwrite or modify project-level `./xbrief/*.xbrief.json` files -- those are project data, not framework files. Report issues and let the user decide how to fix them.
@@ -36,7 +36,7 @@ Every strategy has a **Type** that determines its behavior in the
36
36
  via `/deft:run:<name>` — when invoked outside an interview context, they present their
37
37
  own next-step options instead of returning to the chaining gate. See each strategy file
38
38
  for standalone support.
39
- - **`spec-generating`** — Produces v0.20-conformant output per [v0-20-contract.md](./v0-20-contract.md) (lifecycle folders + PROJECT-DEFINITION.vbrief.json + date-prefixed proposed/ scope vBRIEFs only; SPECIFICATION.md/PROJECT.md as deprecation stubs or omitted). Selecting one at the chaining gate switches the pipeline to that strategy’s spec flow.
39
+ - **`spec-generating`** — Produces v0.20-conformant output per [v0-20-contract.md](./v0-20-contract.md) (lifecycle folders + PROJECT-DEFINITION.xbrief.json + date-prefixed proposed/ scope vBRIEFs only; SPECIFICATION.md/PROJECT.md as deprecation stubs or omitted). Selecting one at the chaining gate switches the pipeline to that strategy’s spec flow.
40
40
 
41
41
  Custom strategies MUST declare their type in this table. If the `Type` column is missing,
42
42
  the chaining gate cannot include the strategy.
@@ -45,9 +45,9 @@ the chaining gate cannot include the strategy.
45
45
 
46
46
  All spec-generating strategies (interview, yolo, speckit, rapid, enterprise) MUST produce output conforming to [v0-20-contract.md](./v0-20-contract.md):
47
47
 
48
- - Five vbrief/ lifecycle folders (proposed/ pending/ active/ completed/ cancelled/)
49
- - vbrief/PROJECT-DEFINITION.vbrief.json (full)
50
- - Scope vBRIEFs ONLY as date-prefixed in vbrief/proposed/YYYY-MM-DD-*.vbrief.json
48
+ - Five xbrief/ lifecycle folders (proposed/ pending/ active/ completed/ cancelled/)
49
+ - xbrief/PROJECT-DEFINITION.xbrief.json (full)
50
+ - Scope vBRIEFs ONLY as date-prefixed in xbrief/proposed/YYYY-MM-DD-*.xbrief.json
51
51
  - Never dual-write legacy vbrief/specification.vbrief.json
52
52
  - SPECIFICATION.md/PROJECT.md only as deprecation-redirect stubs (banner + sentinel) or omitted
53
53
 
package/strategies/bdd.md CHANGED
@@ -57,7 +57,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
57
57
 
58
58
  ! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
59
59
 
60
- ! Resolve all ambiguities surfaced by Step 3. Record decisions in `vbrief/proposed/{feature}-bdd.vbrief.json`.
60
+ ! Resolve all ambiguities surfaced by Step 3. Record decisions in `xbrief/proposed/{feature}-bdd.xbrief.json`.
61
61
 
62
62
  - ! Write a scope vBRIEF with two narratives:
63
63
  - `Scenarios` -- Given/When/Then scenario descriptions from Step 1
@@ -67,32 +67,32 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
67
67
  - ⊗ Leave ambiguities unresolved -- every question surfaced in Step 3 must have a locked answer
68
68
  - ⊗ Write decisions to a hand-authored markdown file -- use vBRIEF narratives for token-efficient agent consumption
69
69
 
70
- ! After emitting the scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
70
+ ! After emitting the scope vBRIEF to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
71
71
 
72
72
  ### Step 5: Generate Spec
73
73
 
74
74
  ! Derive SPECIFICATION.md tasks from the now-stable test scenarios and locked decisions.
75
75
 
76
76
  - ! Each scenario maps to one or more spec tasks with traceability (`traces: scenario-N`)
77
- - ! Locked decisions from `vbrief/proposed/{feature}-bdd.vbrief.json` `LockedDecisions` narrative flow into the spec as constraints
77
+ - ! Locked decisions from `xbrief/proposed/{feature}-bdd.xbrief.json` `LockedDecisions` narrative flow into the spec as constraints
78
78
  - ~ Use the Light or Full path from [strategies/interview.md](./interview.md) based on project size
79
79
 
80
80
  ### Step 6: Chain into Interview Sizing Gate
81
81
 
82
82
  ! Follow [strategies/interview.md](./interview.md) sizing gate for SPECIFICATION.md finalisation.
83
83
 
84
- - ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
84
+ - ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
85
85
  - Update `completedStrategies`: increment `runCount` for `"bdd"`, append artifact paths
86
86
  - Append all new artifact paths to the flat `artifacts` array
87
87
  - ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
88
- - ! The locked decisions from `vbrief/proposed/{feature}-bdd.vbrief.json` and the acceptance tests MUST flow into subsequent strategies and spec generation
88
+ - ! The locked decisions from `xbrief/proposed/{feature}-bdd.xbrief.json` and the acceptance tests MUST flow into subsequent strategies and spec generation
89
89
 
90
90
  ---
91
91
 
92
92
  ## Output Artifacts
93
93
 
94
94
  - Executable test files in the project's standard test directory -- derived from Given/When/Then scenarios
95
- - `vbrief/proposed/{feature}-bdd.vbrief.json` -- scope vBRIEF with `Scenarios` and `LockedDecisions` narratives
95
+ - `xbrief/proposed/{feature}-bdd.xbrief.json` -- scope vBRIEF with `Scenarios` and `LockedDecisions` narratives
96
96
 
97
97
  ---
98
98
 
@@ -55,7 +55,7 @@ Use the Feynman technique: if the user (or you) can't explain the feature in sim
55
55
 
56
56
  - ! If the user suggests a capability belonging to a different feature, capture it as **deferred**
57
57
  - ~ Redirect: "That sounds like a new capability — I'll note it. For now, let's focus on [current scope]."
58
- - ~ Record deferred ideas in `./vbrief/plan.vbrief.json` with `deferred` status and a narrative explaining why
58
+ - ~ Record deferred ideas in `./xbrief/plan.xbrief.json` with `deferred` status and a narrative explaining why
59
59
 
60
60
  ## Domain-Sensitive Questions
61
61
 
@@ -70,14 +70,14 @@ Adapt question focus to what's being built:
70
70
 
71
71
  ! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
72
72
 
73
- - ! Produce a `vbrief/proposed/{scope}-context.vbrief.json` scope vBRIEF with a `LockedDecisions` narrative
73
+ - ! Produce a `xbrief/proposed/{scope}-context.xbrief.json` scope vBRIEF with a `LockedDecisions` narrative
74
74
  - ! Each decision includes: **what** was decided, **why**, and **alternatives considered**
75
75
  - ! When the lock is an intentional under-build (weaker Now + decided end-product Later), the decision MUST also include dual-path graduation fields: `now`, `later`, `graduationRef`, `trigger`, and `status` (`open` | `shipped` | `cancelled`) — see [Graduation (Now+Later)](#graduation-nowlater-dual-path-locks-2899)
76
76
  - ! This vBRIEF is injected into all downstream work: planning, execution, verification
77
77
  - ! Persist decisions as vBRIEF narratives on the relevant plan items
78
78
  - ⊗ Write decisions to a hand-authored markdown context file -- use vBRIEF narratives for token-efficient agent consumption
79
79
 
80
- ! After emitting the scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
80
+ ! After emitting the scope vBRIEF to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
81
81
 
82
82
  ## Decision Locking
83
83
 
@@ -128,18 +128,18 @@ Glossary naming for this term is owned by sibling work (#2907). Strategy prose h
128
128
 
129
129
  ## Then: Chaining Gate
130
130
 
131
- After alignment is complete and decisions are locked in `vbrief/proposed/{scope}-context.vbrief.json`,
131
+ After alignment is complete and decisions are locked in `xbrief/proposed/{scope}-context.xbrief.json`,
132
132
  return to the [chaining gate](./interview.md#chaining-gate) so the user can
133
133
  run additional preparatory strategies or proceed to spec generation.
134
134
 
135
- - ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
135
+ - ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
136
136
  - Update `completedStrategies`: increment `runCount` for `"discuss"`,
137
- append artifact path (`vbrief/proposed/{scope}-context.vbrief.json`)
137
+ append artifact path (`xbrief/proposed/{scope}-context.xbrief.json`)
138
138
  - Append the path to the flat `artifacts` array
139
139
  - ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
140
140
  (the discuss phase replaces the interview's question-gathering -- decisions are
141
141
  already made, so the interview will be short or skipped entirely)
142
- - ! The locked decisions from `vbrief/proposed/{scope}-context.vbrief.json` MUST flow into subsequent
142
+ - ! The locked decisions from `xbrief/proposed/{scope}-context.xbrief.json` MUST flow into subsequent
143
143
  strategies and spec generation
144
144
  - ⊗ End the session after discuss without returning to the chaining gate
145
145
  or the invoking strategy's next-step menu
@@ -154,7 +154,7 @@ run additional preparatory strategies or proceed to spec generation.
154
154
 
155
155
  1. **Open** -- Start with the user's goal statement; restate it in your own words
156
156
  2. **Explore** -- Follow energy, challenge vagueness, ask domain-sensitive questions
157
- 3. **Lock** -- Record each decision in `vbrief/proposed/{scope}-context.vbrief.json` `LockedDecisions` narrative with what/why/alternatives (and dual-path graduation fields when the lock is an under-build; #2899)
157
+ 3. **Lock** -- Record each decision in `xbrief/proposed/{scope}-context.xbrief.json` `LockedDecisions` narrative with what/why/alternatives (and dual-path graduation fields when the lock is an under-build; #2899)
158
158
  4. **Verify** -- Explain the full picture back to the user (Feynman check)
159
159
  5. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above
160
160
 
@@ -16,7 +16,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
16
16
 
17
17
  ## When to Use
18
18
 
19
- This file is not a standalone strategy — it is a shared hint referenced by other strategies. It activates at the emission step, right after a strategy writes scope vBRIEFs to `vbrief/proposed/` (or `vbrief/pending/`).
19
+ This file is not a standalone strategy — it is a shared hint referenced by other strategies. It activates at the emission step, right after a strategy writes scope vBRIEFs to `xbrief/proposed/` (or `xbrief/pending/`).
20
20
 
21
21
  - ! Referenced by spec-generating strategies: [speckit](./speckit.md) (Phase 4 and Phase 4.5), [enterprise](./enterprise.md), [rapid](./rapid.md), [interview](./interview.md), [yolo](./yolo.md)
22
22
  - ! Referenced by preparatory strategies: [bdd](./bdd.md), [discuss](./discuss.md), [research](./research.md), [map](./map.md), [probe](./probe.md)
@@ -38,12 +38,12 @@ This file is not a standalone strategy — it is a shared hint referenced by oth
38
38
  <strategy> emitted N scope vBRIEF(s).
39
39
 
40
40
  Optional: track these in GitHub issues.
41
- - task deft:issue:emit --umbrella -- vbrief/<path>/<glob> (one roadmap issue, all vBRIEFs reference it)
42
- - task deft:issue:emit --per-vbrief -- vbrief/<path>/<glob> (one issue per vBRIEF)
41
+ - task deft:issue:emit --umbrella -- xbrief/<path>/<glob> (one roadmap issue, all vBRIEFs reference it)
42
+ - task deft:issue:emit --per-vbrief -- xbrief/<path>/<glob> (one issue per vBRIEF)
43
43
  - Default behavior (vBRIEF-only) requires no further action.
44
44
  ```
45
45
 
46
- ~ Replace `<path>/<glob>` with the actual emission target (e.g. `vbrief/proposed/2026-06-15-*.vbrief.json`).
46
+ ~ Replace `<path>/<glob>` with the actual emission target (e.g. `xbrief/proposed/2026-06-15-*.xbrief.json`).
47
47
 
48
48
  Note: `task deft:issue:emit` is the consumer-installed surface (this is what strategies render to). The maintainer-side, in-repo form is `task issue:emit` — the same command without the `deft:` prefix.
49
49
 
@@ -52,8 +52,8 @@ Note: `task deft:issue:emit` is the consumer-installed surface (this is what str
52
52
  ## The Three Patterns
53
53
 
54
54
  1. **None (default)** — emit vBRIEF(s) only; file no GitHub issue. Requires no further user action. This is the framework default and is unchanged by this hint.
55
- 2. **Umbrella** — `task deft:issue:emit --umbrella -- vbrief/<path>/<glob>` files ONE roadmap issue, and every matched vBRIEF references it.
56
- 3. **Per-vBRIEF** — `task deft:issue:emit --per-vbrief -- vbrief/<path>/<glob>` files one issue per matched vBRIEF.
55
+ 2. **Umbrella** — `task deft:issue:emit --umbrella -- xbrief/<path>/<glob>` files ONE roadmap issue, and every matched vBRIEF references it.
56
+ 3. **Per-vBRIEF** — `task deft:issue:emit --per-vbrief -- xbrief/<path>/<glob>` files one issue per matched vBRIEF.
57
57
 
58
58
  - ! Name all three patterns (none / `--umbrella` / `--per-vbrief`) when surfacing the hint — do not hide the umbrella / per-vBRIEF escape hatches.
59
59
  - ⊗ File a GitHub issue automatically as part of emission. No strategy files an issue unless the user explicitly invokes `task deft:issue:emit`.
@@ -8,7 +8,7 @@
8
8
 
9
9
  Compliance-heavy workflow -- v0.20 date-prefixed story/phase vBRIEF + PROJECT-DEFINITION with explicit approval gates at each stage.
10
10
 
11
- **v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Enterprise now emits only the canonical v0.20 shape (date-prefixed story/phase vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). PRD.md and SPECIFICATION.md (if any) are deprecation-redirect derivatives only. See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).
11
+ **v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Enterprise now emits only the canonical v0.20 shape (date-prefixed story/phase vBRIEFs in proposed/, full PROJECT-DEFINITION.xbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). PRD.md and SPECIFICATION.md (if any) are deprecation-redirect derivatives only. See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).
12
12
 
13
13
  Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
14
14
 
@@ -38,12 +38,12 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
38
38
 
39
39
  ! 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).
40
40
 
41
- ! Run the Full interview path from [interview.md](./interview.md) unconditionally -- write PRD narratives as date-prefixed story/phase vBRIEF(s) to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json`.
41
+ ! Run the Full interview path from [interview.md](./interview.md) unconditionally -- write PRD narratives as date-prefixed story/phase vBRIEF(s) to `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json`.
42
42
 
43
43
  - ! Use the Full path regardless of project size -- enterprise always requires a PRD
44
44
  - ! Write PRD content as narratives in the proposed/ vBRIEF `plan.narratives`: `ProblemStatement`, `Goals`, `NonGoals`, `UserStories`, `Requirements` (functional + non-functional), `SuccessMetrics`
45
45
  - ! Record the PRD approver(s) in the `Approvers` narrative
46
- - ! Run `task prd:render` (if UX continuity needed) to produce `PRD.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the vbrief/ artifacts.
46
+ - ! Run `task prd:render` (if UX continuity needed) to produce `PRD.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the xbrief/ artifacts.
47
47
 
48
48
  ### Gate 1: PRD Approval
49
49
 
@@ -76,14 +76,14 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
76
76
 
77
77
  ! 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).
78
78
 
79
- ! Enrich or emit date-prefixed vBRIEF(s) in `vbrief/proposed/` with architecture and plan narratives derived from the approved PRD narratives and accepted ADRs. (No singular `specification.vbrief.json`.)
79
+ ! Enrich or emit date-prefixed vBRIEF(s) in `xbrief/proposed/` with architecture and plan narratives derived from the approved PRD narratives and accepted ADRs. (No singular `specification.vbrief.json`.)
80
80
 
81
81
  - ! Add HOW narratives to the proposed/ vBRIEF `plan.narratives`: `Architecture`, `TechDecisions`, `ImplementationPhases`, `TraceabilityMatrix`
82
82
  - ! Every spec task must trace to a PRD requirement and, where applicable, an ADR
83
83
  - ! Use the Light or Full path from [interview.md](./interview.md) for specification generation
84
84
  - ! Include traceability matrix: spec task → PRD requirement → ADR (where applicable)
85
- - ! Run `task spec:render` (if UX continuity needed) to produce `SPECIFICATION.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the vbrief/ lifecycle + PROJECT-DEFINITION.
86
- - ! After proposed/ vBRIEFs exist, invoke `task project:render` to produce/refresh `vbrief/PROJECT-DEFINITION.vbrief.json`.
85
+ - ! Run `task spec:render` (if UX continuity needed) to produce `SPECIFICATION.md` **only as a deprecation-redirect derivative** (see v0.20 Output Shape); the source of truth is the xbrief/ lifecycle + PROJECT-DEFINITION.
86
+ - ! After proposed/ vBRIEFs exist, invoke `task project:render` to produce/refresh `xbrief/PROJECT-DEFINITION.xbrief.json`.
87
87
 
88
88
  ! After emitting the proposed/ vBRIEF(s), surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
89
89
 
@@ -107,13 +107,13 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
107
107
 
108
108
  ## Output Artifacts
109
109
 
110
- - `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) -- source of truth for PRD and specification narratives (date-prefixed per v0.20 contract)
111
- - `vbrief/PROJECT-DEFINITION.vbrief.json` -- complete via `task project:render`
110
+ - `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (one or more) -- source of truth for PRD and specification narratives (date-prefixed per v0.20 contract)
111
+ - `xbrief/PROJECT-DEFINITION.xbrief.json` -- complete via `task project:render`
112
112
  - `PRD.md` -- rendered export via `task prd:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)
113
113
  - `docs/adr/adr-NNN-*.md` -- accepted Architecture Decision Records (unchanged location)
114
114
  - `SPECIFICATION.md` -- rendered export via `task spec:render` **only if deprecation-redirect sentinel** (read-only stakeholder review artifact; otherwise omit)
115
115
  - Traceability matrix (inline in the proposed/ vBRIEF narratives or as a separate `docs/traceability.md`)
116
- - `vbrief/{proposed,pending,active,completed,cancelled}/` -- all five lifecycle folders seeded
116
+ - `xbrief/{proposed,pending,active,completed,cancelled}/` -- all five lifecycle folders seeded
117
117
 
118
118
  ---
119
119
 
@@ -139,11 +139,11 @@ Enterprise is a **spec-generating** strategy. It uses the Forced-Full path and a
139
139
 
140
140
  This strategy has been migrated to the full v0.20 output shape so enterprise-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the enterprise row from the #1166 inconsistency table and the s5 story acceptance criteria).
141
141
 
142
- - ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.
143
- - ! Emit scope items (PRD, spec phases, etc.) exclusively as date-prefixed scope vBRIEFs: `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.
144
- - ! After the proposed/ vBRIEFs are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry is derived from the lifecycle folders).
142
+ - ! Seed the five lifecycle folders under `xbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.
143
+ - ! Emit scope items (PRD, spec phases, etc.) exclusively as date-prefixed scope vBRIEFs: `xbrief/proposed/YYYY-MM-DD-<kebab-slug>.xbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.
144
+ - ! After the proposed/ vBRIEFs are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `xbrief/PROJECT-DEFINITION.xbrief.json` (items registry is derived from the lifecycle folders).
145
145
  - ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).
146
- - ~ `PRD.md` and `SPECIFICATION.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel (see conventions/machine-generated-banner.md). The source of truth is the vbrief/ lifecycle vBRIEFs + PROJECT-DEFINITION. ADRs remain in `docs/adr/`.
146
+ - ~ `PRD.md` and `SPECIFICATION.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel (see conventions/machine-generated-banner.md). The source of truth is the xbrief/ lifecycle vBRIEFs + PROJECT-DEFINITION. ADRs remain in `docs/adr/`.
147
147
  - ! 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).
148
148
  - ! 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 and the 1166 decomposition.
149
149
  - ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row.
@@ -156,9 +156,9 @@ This strategy has been migrated to the full v0.20 output shape so enterprise-gen
156
156
 
157
157
  | Artifact | Purpose | Created By |
158
158
  |----------|---------|------------|
159
- | `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) | PRD + specification narratives as date-prefixed scope items (per v0.20 contract) | Enterprise |
160
- | `vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Enterprise) |
161
- | `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Enterprise |
159
+ | `xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (one or more) | PRD + specification narratives as date-prefixed scope items (per v0.20 contract) | Enterprise |
160
+ | `xbrief/PROJECT-DEFINITION.xbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Enterprise) |
161
+ | `xbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Enterprise |
162
162
  | `docs/adr/adr-NNN-*.md` | Accepted Architecture Decision Records (traceable) | Enterprise (unchanged) |
163
163
  | (optional derivative) `PRD.md` / `SPECIFICATION.md` | Human-readable (includes deprecated-redirect sentinel only) | `task prd:render` / `task spec:render` (if invoked) |
164
164
 
@@ -168,13 +168,13 @@ This strategy has been migrated to the full v0.20 output shape so enterprise-gen
168
168
  - Primary handoff `PRD.md` or `SPECIFICATION.md` at project root (without sentinel)
169
169
  - Bare-named vBRIEFs in proposed/
170
170
 
171
- See the full table and rules in `strategies/v0-20-contract.md` (enterprise row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.vbrief.json only; specification.vbrief.json: Never; SPECIFICATION.md / PROJECT.md: Omit or deprecation redirect only).
171
+ See the full table and rules in `strategies/v0-20-contract.md` (enterprise row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.xbrief.json only; specification.vbrief.json: Never; SPECIFICATION.md / PROJECT.md: Omit or deprecation redirect only).
172
172
 
173
173
  ---
174
174
 
175
175
  ## Invoking This Strategy
176
176
 
177
- Set in PROJECT-DEFINITION.vbrief.json narratives:
177
+ Set in PROJECT-DEFINITION.xbrief.json narratives:
178
178
  ```json
179
179
  "Strategy": "strategies/enterprise.md"
180
180
  ```
@@ -94,15 +94,15 @@ See `strategies/map.md` for standalone behavior.
94
94
  - ! Previously-run strategies MUST display with a run count (e.g., `Research (ran 1×)`)
95
95
  - ! No strategy is ever removed from the gate — users can re-run any strategy
96
96
  - ! Run counts are read from `completedStrategies` in
97
- [`./vbrief/plan.vbrief.json`](../vbrief/vbrief.md#strategy-chaining-fields)
97
+ [`./xbrief/plan.xbrief.json`](../vbrief/vbrief.md#strategy-chaining-fields)
98
98
 
99
99
  ### State Tracking
100
100
 
101
101
  - ! On completion of a preparatory strategy, update `completedStrategies` in
102
- `./vbrief/plan.vbrief.json`: increment `runCount`, append artifact paths
102
+ `./xbrief/plan.xbrief.json`: increment `runCount`, append artifact paths
103
103
  - ! Append all new artifact paths to the flat `artifacts` array
104
104
  - ! The next strategy and eventual spec generation MUST load all artifacts
105
- listed in `plan.vbrief.json`
105
+ listed in `plan.xbrief.json`
106
106
  - ! On brownfield **Add scope** or **Update project definition**, load existing
107
107
  PROJECT-DEFINITION identity and preparatory artifacts before asking questions
108
108
 
@@ -578,7 +578,7 @@ diff only on the second pass or when the user explicitly asks for it.
578
578
 
579
579
  ### State Preservation
580
580
 
581
- - ! All `completedStrategies` and `artifacts` in `plan.vbrief.json` MUST be
581
+ - ! All `completedStrategies` and `artifacts` in `plan.xbrief.json` MUST be
582
582
  preserved across revisions
583
583
  - ! The chaining gate will show updated run counts reflecting the full session history
584
584
 
package/strategies/map.md CHANGED
@@ -50,7 +50,7 @@ Mapping produces artifacts that feed into planning so the agent **follows existi
50
50
 
51
51
  ! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
52
52
 
53
- Produce a single `vbrief/proposed/{project}-codebase-map.vbrief.json` with four narratives:
53
+ Produce a single `xbrief/proposed/{project}-codebase-map.xbrief.json` with four narratives:
54
54
 
55
55
  ! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
56
56
 
@@ -105,9 +105,9 @@ Produce a single `vbrief/proposed/{project}-codebase-map.vbrief.json` with four
105
105
 
106
106
  ### Artifact Registration (both modes)
107
107
 
108
- - ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
108
+ - ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
109
109
  - Update `completedStrategies`: increment `runCount` for `"map"`,
110
- append artifact path (`vbrief/proposed/{project}-codebase-map.vbrief.json`)
110
+ append artifact path (`xbrief/proposed/{project}-codebase-map.xbrief.json`)
111
111
  - Append the path to the flat `artifacts` array
112
112
  - ! The mapping narratives MUST inform subsequent strategies and spec generation:
113
113
  - `Conventions` -> implementation constraints
@@ -130,7 +130,7 @@ Mapping complete. Here's what I found:
130
130
  - Conventions: [brief summary]
131
131
  - Concerns: [brief summary]
132
132
 
133
- Artifact: vbrief/proposed/{project}-codebase-map.vbrief.json
133
+ Artifact: xbrief/proposed/{project}-codebase-map.xbrief.json
134
134
 
135
135
  What would you like to do next?
136
136
 
@@ -141,7 +141,7 @@ What would you like to do next?
141
141
  ```
142
142
 
143
143
  - ! Present the narrative summary before offering options
144
- - ! If the user chooses a strategy, invoke it (the artifact persists in `vbrief/proposed/`)
144
+ - ! If the user chooses a strategy, invoke it (the artifact persists in `xbrief/proposed/`)
145
145
  - ! If the user chooses "done", confirm the artifact location and exit cleanly
146
146
  - ~ Recommend option 1 (interview) when the user's goal is to build or extend
147
147
  - ~ Recommend option 4 (done) when the user's goal is exploration or onboarding
@@ -173,7 +173,7 @@ Before an interview — analysis-first, then spec:
173
173
  Map this codebase, then use the interview strategy to plan [feature].
174
174
  ```
175
175
 
176
- Or set in PROJECT-DEFINITION.vbrief.json narratives:
176
+ Or set in PROJECT-DEFINITION.xbrief.json narratives:
177
177
  ```json
178
178
  "Strategy": "strategies/map.md"
179
179
  ```
@@ -73,46 +73,50 @@ Walk the decision tree depth-first. For each unresolved branch:
73
73
 
74
74
  ! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
75
75
 
76
- ### Mechanical guard (`scripts/probe_session.py`)
76
+ ### Mechanical guard (`deft probe-session`)
77
77
 
78
78
  Probe completion is enforced mechanically — not by prose alone. A per-clone
79
79
  session file at `.deft/probe-session.json` records whether the session is still
80
80
  `interrogate` or `complete`, plus the probe `target`, `currentBranch`, and
81
81
  `resolvedDecisions`.
82
82
 
83
+ **Waiver (#3556):** The probe skill keeps the no-artifact guard and does not
84
+ require `deft probe-session`. This strategy names `deft probe-session`.
85
+ Silence is not agreement.
86
+
83
87
  - ! At probe start, record the session:
84
- `uv run python scripts/probe_session.py start --target <scope>`
88
+ `deft probe-session start --target <scope>`
85
89
  - ! While interrogating, record locked/deferred/risk-accepted decisions and
86
90
  branch focus with `record` / `set-branch` subcommands as branches resolve
87
91
  - ! Before writing probe output or registering `completedStrategies.probe`,
88
92
  mark the session complete:
89
- `uv run python scripts/probe_session.py complete`
93
+ `deft probe-session complete`
90
94
  - ! Immediately before artifact or plan registration, run the guard:
91
- - `uv run python scripts/probe_session.py guard-artifact --path vbrief/proposed/{scope}-probe.vbrief.json`
92
- - `uv run python scripts/probe_session.py guard-plan-registration`
95
+ - `deft probe-session guard-artifact --path xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json`
96
+ - `deft probe-session guard-plan-registration`
93
97
  - ⊗ Write probe artifacts or update `completedStrategies.probe` while the
94
98
  session state is still `interrogate` — the guard exits non-zero with an
95
99
  actionable recovery message
96
100
 
97
101
  **Recovery when the guard blocks handoff:** continue interrogation until the
98
102
  [transition criteria](#transition-criteria-probe-complete) are met, record
99
- decisions with `probe_session.py record`, run `probe_session.py complete`,
100
- then retry the guard before writing artifacts or updating `plan.vbrief.json`.
103
+ decisions with `deft probe-session record`, run `deft probe-session complete`,
104
+ then retry the guard before writing artifacts or updating `plan.xbrief.json`.
101
105
 
102
- `{scope}` is the project name from `PROJECT-DEFINITION.vbrief.json`, or the
106
+ `{scope}` is the project name from `PROJECT-DEFINITION.xbrief.json`, or the
103
107
  feature/component name if probing a sub-scope. Use the same value consistently
104
108
  throughout the session. Examples: `my-app-probe`, `auth-probe`.
105
109
 
106
- - ! Produce a `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF with three mandatory narratives:
110
+ - ! Produce a `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` scope xBRIEF with three mandatory narratives:
107
111
  - `LockedDecisions` — what was resolved and why (when the lock is an intentional under-build, include dual-path graduation fields: `now`, `later`, `graduationRef`, `trigger`, `status` — see [Graduation (Now+Later)](#graduation-nowlater-when-locking-an-under-build-2899))
108
112
  - `SurfacedRisks` — concerns raised, even if not fully resolved
109
113
  - `DeferredDecisions` — explicitly acknowledged items with justification
110
114
  - ! Each entry in a narrative includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)
111
- - ! This vBRIEF is injected into all downstream work: planning, execution, verification
112
- - ! Persist significant decisions as vBRIEF narratives on the relevant plan items
113
- - ⊗ Write probe output to a hand-authored markdown file — use vBRIEF narratives for token-efficient, machine-consumable agent consumption (mirrors the [discuss](./discuss.md) and [research](./research.md) output contracts so the chaining-gate flow-through guarantee is mechanical, not aspirational)
115
+ - ! This xBRIEF is injected into all downstream work: planning, execution, verification
116
+ - ! Persist significant decisions as xBRIEF narratives on the relevant plan items
117
+ - ⊗ Write probe output to a hand-authored markdown file — use xBRIEF narratives for token-efficient, machine-consumable agent consumption (mirrors the [discuss](./discuss.md) and [research](./research.md) output contracts so the chaining-gate flow-through guarantee is mechanical, not aspirational)
114
118
 
115
- ! After emitting the probe scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
119
+ ! After emitting the probe scope xBRIEF to `xbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
116
120
 
117
121
  ## Graduation (Now+Later) when locking an under-build (#2899)
118
122
 
@@ -142,15 +146,15 @@ Glossary naming for Graduation is owned by sibling work (#2907); this section is
142
146
 
143
147
  ## Then: Chaining Gate
144
148
 
145
- After the probe is complete and `vbrief/proposed/{scope}-probe.vbrief.json` is
149
+ After the probe is complete and `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` is
146
150
  written, return to the [chaining gate](./interview.md#chaining-gate).
147
151
 
148
- - ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
152
+ - ! On completion, register artifacts in `./xbrief/plan.xbrief.json`:
149
153
  - Update `completedStrategies`: increment `runCount` for `"probe"`,
150
- append artifact path (`vbrief/proposed/{scope}-probe.vbrief.json`)
154
+ append artifact path (`xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json`)
151
155
  - Append the path to the flat `artifacts` array
152
156
  - ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
153
- - ! The `LockedDecisions`, `SurfacedRisks`, and `DeferredDecisions` narratives from `vbrief/proposed/{scope}-probe.vbrief.json` MUST flow
157
+ - ! The `LockedDecisions`, `SurfacedRisks`, and `DeferredDecisions` narratives from `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` MUST flow
154
158
  into subsequent strategies and spec generation:
155
159
  - Locked decisions become constraints in the specification
156
160
  - Surfaced risks become NFRs or explicit acceptance criteria
@@ -174,4 +178,4 @@ written, return to the [chaining gate](./interview.md#chaining-gate).
174
178
  - ⊗ Using codebase exploration as a substitute for asking the user about deliberate design choices
175
179
  - ⊗ Stopping when the conversation feels comfortable — stop when no new branches emerge
176
180
  - ⊗ Ending after probe without chaining back to the gate (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))
177
- - ⊗ Writing probe output to a plain markdown file (`{scope}-probe.md`) instead of the canonical `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF — plain markdown bypasses the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) and breaks the downstream-consumer flow-through guarantee
181
+ - ⊗ Writing probe output to a plain markdown file (`{scope}-probe.md`) instead of the canonical `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` scope xBRIEF — plain markdown bypasses the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) and breaks the downstream-consumer flow-through guarantee