@deftai/directive-content 0.105.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.
package/scm/github.md CHANGED
@@ -503,7 +503,7 @@ Three consumer-facing surfaces enforce the branch-policy contract:
503
503
  - `deft verify:branch` — refuses default-branch commit unless `plan.policy.allowDirectCommitsToMaster = true` (typed) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`.
504
504
  - `.githooks/pre-commit` / `pre-push` — installed via `deft setup`; verify via `deft verify:hooks-installed`. After a framework upgrade, run `deft update` to refresh hook templates (#2049).
505
505
  - `deft policy:show --field=allowDirectCommitsToMaster` — inspect policy; `deft policy:allow-direct-commits -- --confirm` writes typed override with audit row.
506
- - `deft verify:forward-coverage` — forward-coverage gate (#1310), wired into `deft check` + pre-commit (`--staged`); document exceptions via `--allow-list <path>`.
506
+ - `deft verify:forward-coverage` — fail-closed new-source-file existence (#1310) plus warn-first diff coverage of added/modified branches (#3514). Intersects `coverage/coverage-final.json` with the diff (90% per-change branch threshold). That 90% is not the 75 global floor. Wired into `deft check` + pre-commit (`--staged`); `--enforce` fail-closes the diff half; `--allow-list <path>` documents exceptions.
507
507
 
508
508
  When `plan.policy.allowDirectCommitsToMaster = true`, the agent MUST surface at session start (after alignment confirmation):
509
509
 
@@ -0,0 +1,46 @@
1
+ ---
2
+ name: deft-directive-design-critique
3
+ description: >-
4
+ Thin router for the design-critique motion: triggers and five pointer stops
5
+ into the contract. Use when the operator asks for a design critique,
6
+ design-critique, critique panel, or mechanism-shaped triage. Do NOT trigger
7
+ on ordinary implement, build, or swarm work.
8
+ triggers:
9
+ - design critique
10
+ - design-critique
11
+ - critique panel
12
+ - mechanism-shaped triage
13
+ ---
14
+ <!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
15
+ <!-- Purpose: rendered skill -->
16
+ <!-- Source of truth: packs/skills/skills-pack-0.1.json -->
17
+ <!-- Regenerate with: task packs:render -->
18
+ <!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
19
+
20
+ # Design Critique
21
+
22
+ Thin router into the design-critique contract. Operator dispatches from the brief template.
23
+
24
+ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
25
+
26
+ ## When to Use
27
+
28
+ - Operator asks for a design critique, a design-critique, a critique panel, or mechanism-shaped triage
29
+ - ⊗ Ordinary implement, build, or swarm work
30
+
31
+ ## Stops
32
+
33
+ Normative rules live in [`contracts/design-critique.md`](../../contracts/design-critique.md). Fill [`templates/design-critique-brief.md`](../../templates/design-critique-brief.md) and dispatch from there. Phase 1 gate: [`docs/decisions/ADR-005-design-critique-judgment-gate.md`](../../../docs/decisions/ADR-005-design-critique-judgment-gate.md).
34
+
35
+ 1. Stop 1 — Gate
36
+ 2. Stop 2 — Variant selection
37
+ 3. Stop 3 — Critic envelope
38
+ 4. Stop 4 — Residual reiteration
39
+ 5. Stop 5 — Verified synthesis
40
+
41
+ ⊗ Auto-dispatch critics from this skill.
42
+ ⊗ Copy the variant table, synthesis rules, or other contract bodies into this skill.
43
+
44
+ ## EXIT
45
+
46
+ deft-directive-design-critique complete -- exiting skill. Next: fill the brief template and dispatch.
@@ -43,6 +43,8 @@ While probe completion criteria (below) are NOT met:
43
43
 
44
44
  ! Read existing context and interrogate only — artifacts land in the Output phase after completion.
45
45
 
46
+ **Waiver (#3556):** This skill keeps the no-artifact guard and does not require `deft probe-session`. The probe strategy names `deft probe-session`. Silence is not agreement.
47
+
46
48
  ## Workflow
47
49
 
48
50
  ### Step 1: Establish the plan
@@ -95,7 +97,7 @@ Walk the decision tree depth-first. For each unresolved branch:
95
97
 
96
98
  `{scope}` is the project name from `PROJECT-DEFINITION.xbrief.json`, or the feature/component name if probing a sub-scope. Use the same value consistently throughout the session.
97
99
 
98
- - ! Produce a `xbrief/proposed/{scope}-probe.xbrief.json` scope xBRIEF with three mandatory narratives:
100
+ - ! Produce a `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` scope xBRIEF with three mandatory narratives:
99
101
  - `LockedDecisions` — what was resolved and why
100
102
  - `SurfacedRisks` — concerns raised, even if not fully resolved
101
103
  - `DeferredDecisions` — explicitly acknowledged items with justification
@@ -105,7 +107,7 @@ Walk the decision tree depth-first. For each unresolved branch:
105
107
 
106
108
  ## Chaining Gate
107
109
 
108
- After the probe is complete and `xbrief/proposed/{scope}-probe.xbrief.json` is written:
110
+ After the probe is complete and `xbrief/proposed/YYYY-MM-DD-{scope}-probe.xbrief.json` is written:
109
111
 
110
112
  - ! Register artifacts in `./xbrief/plan.xbrief.json` (`completedStrategies`, `artifacts`)
111
113
  - ! Return to [interview.md Chaining Gate](../../strategies/interview.md#chaining-gate) when invoked from the interview flow
@@ -180,7 +180,7 @@ See [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Routine vs hard cut for
180
180
  6. ! **Run `task reconcile:issues -- --apply-lifecycle-fixes` to clear any closed-issue / non-completed-folder xBRIEFs before invoking `task release`** (#734). The release pipeline carries the deterministic gate at Step 3 (`scripts/release.py::check_vbrief_lifecycle_sync`, refuses with `EXIT_VIOLATION` on any Section (c) mismatch), but Phase 1 is the operator's first-line defence -- running the apply-mode flag here is the canonical clean path; `--allow-vbrief-drift` on the pipeline exists only as the explicit-acknowledgment escape hatch (analogous to `--allow-dirty`). The recurrence record is the v0.21.0 cut, which surfaced 13 stranded xBRIEFs (8 cycle-relevant + 5 historical residue) post-publish; the gate now blocks that drift before any irreversible action
181
181
  7. ! **Verify the proposed `v<version>` tag is not already in use locally, on origin, or as a published GitHub release** (#784). The release pipeline carries the deterministic gate at Step 4 (`scripts/release.py::check_tag_available`, refuses with `EXIT_VIOLATION` before any state mutation -- CHANGELOG promotion, ROADMAP refresh, build, commit), but Phase 1 is the operator's first-line defence. Quickly probe with `git tag -l v<version>` (local), `git ls-remote --tags origin refs/tags/v<version>` (remote), and `gh release view v<version> --repo <owner>/<repo>` (release-only, where `gh release view` exits 0 only when the release exists). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01: the operator typed `0.22.0` (the prior release from 12 hours earlier) and the legacy pipeline ran 8 steps before failing at `git tag` -- leaving a wrong-version local commit + `dist/deft-0.22.0.zip` orphan + manual `git reset --hard` recovery. The new pre-flight gate blocks that mode before any irreversible action
182
182
  8. ! **Verify the npm credential path is configured before cutting the tag** (#1910, #1909). A `v*` tag now auto-triggers `.github/workflows/npm-publish.yml`, which publishes the four `@deftai/directive*` packages with `npm publish --provenance`. Confirm the publish path can authenticate: either the `NPM_TOKEN` repo secret is present (`gh secret list --repo <owner>/<repo>` shows `NPM_TOKEN`) OR an npm OIDC trusted publisher is configured for the `@deftai/directive*` packages. If neither is in place, WARN loudly that the tag will fire a publish job that fails (red X on the tag, no packages) -- the operator may still proceed for a GitHub-only release, but the npm channel will not land until #1909's credential is provisioned. Cross-reference #1909.
183
- 9. ! **Disclose npm irrevocability before any tag push (#1972, #2002).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The operator's explicit `yes` in Phase 2 (dry-run) and the decision to invoke `task release` in Phase 4 are the last human gates before npm goes live. Phase 5 only controls GitHub release visibility (draft → public); it does NOT gate npm.
183
+ 9. ! **Disclose npm irrevocability before any tag push (#1972, #2002, #3527).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The last human gates before npm goes live are: (a) Phase 2 dry-run `yes`, (b) a human-origin closed-verb grant (`deft authz:grant -- --template release-publish --target <version>` or `DEFT_ALLOW_RELEASE_PUBLISH=1`). `task release` fails closed at the Step 10–11 tag-push boundary without that grant. Phase 5 only controls GitHub release visibility (draft → public); it does NOT gate npm. The draft-flip `release:publish` closed-verb check remains (#1095).
184
184
  10. ~ Ask the operator for an optional one-line release **summary** (recommended 80-160 chars; can be skipped). The summary is the canonical narrative for THIS release across three audiences: (a) injected as a Markdown blockquote at the top of the promoted `CHANGELOG.md [<version>]` section, (b) auto-flowed into the GitHub release body via the existing `_section_for_version` pickup, and (c) populated VERBATIM into the Phase 8 Slack `*Summary*:` slot. Capture the wording once here; do NOT regenerate per-audience downstream
185
185
 
186
186
  ⊗ Skip the version-bump magnitude check -- a patch release that ships breaking changes is the kind of regression that Repair Authority [AXIOM] (#709) is designed to prevent.
@@ -201,7 +201,7 @@ task release -- <version> --dry-run --skip-tag --skip-release --summary "<text>"
201
201
 
202
202
  The dry-run prints `[N/13] <step>... DRYRUN (would <action>)` for every pipeline step (Step 13 is the post-create verify-isDraft gate added by #724; Step 4 is the tag-availability pre-flight gate added by #784). Step 6 (CHANGELOG promotion) surfaces whether a summary was supplied (truncated to ~60 chars in the preview) so the operator can validate the wording before any file is written. Capture the output and present it to the user, then wait for explicit confirmation before continuing.
203
203
 
204
- ! Wait for explicit user confirmation: `yes` / `back` / `quit`. Remind the operator that Phase 4's tag push will irrevocably publish npm (#1972) -- this `yes` is the last safe abort before that channel opens.
204
+ ! Wait for explicit user confirmation: `yes` / `back` / `quit`. Remind the operator that Phase 4's tag push will irrevocably publish npm (#1972) and requires a `release-publish` grant (or `DEFT_ALLOW_RELEASE_PUBLISH=1`) -- this `yes` is the last safe abort before that channel opens (#3527).
205
205
  - `yes` (or `confirmed` / `approve`) → proceed to Phase 3
206
206
  - `back` → return to Phase 1 for re-validation (e.g. user wants to amend the version or `[Unreleased]` content)
207
207
  - `quit` → abort the workflow cleanly; no state changes
@@ -232,7 +232,7 @@ The harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke
232
232
 
233
233
  ## Phase 4 — Production draft
234
234
 
235
- ! **Last human gate before npm (#1972, #2002).** Immediately before invoking `task release`, re-state that the tag push in this step will irrevocably publish all four `@deftai/directive*` packages to npm via `.github/workflows/npm-publish.yml`. There is no undo on npm; only forward recovery (deprecate / dist-tag / patch). Proceed only when the operator explicitly confirms.
235
+ ! **Last human gate before npm (#1972, #2002, #3527).** Immediately before invoking `task release`, re-state that the tag push in this step will irrevocably publish all four `@deftai/directive*` packages to npm via `.github/workflows/npm-publish.yml`. There is no undo on npm; only forward recovery (deprecate / dist-tag / patch). Proceed only when the operator explicitly confirms **and** a human-origin grant covers `release-publish` for this version (`deft authz:grant -- --template release-publish --target <version>` or `DEFT_ALLOW_RELEASE_PUBLISH=1`). The pipeline fails closed at Step 10–11 without that grant -- that is the npm-distributing boundary. ⊗ Rely on Phase 5 `release:publish` as the npm gate; it only flips the GitHub draft. ⊗ Delete the draft-flip check as a substitute for the tag-push gate.
236
236
 
237
237
  ! Invoke `task release -- <version>` (NO `--dry-run`, NO `--skip-tag`, NO `--skip-release`, NO `--skip-ci`). If Phase 1 collected an operator summary, pass `--summary "<text>"` so the production cut writes the same blockquote the dry-run previewed.
238
238
 
@@ -377,6 +377,8 @@ Where `<one-line guidance>` is one of:
377
377
  - ⊗ Run `task release` without a Phase 2 dry-run preview -- the dry-run is the only safe place to catch a bad version, malformed CHANGELOG, or wrong base branch
378
378
  - ⊗ Skip Phase 3 (e2e rehearsal) on the assumption that "the dry-run is enough" -- the e2e harness catches gh-CLI auth issues, repo permission gaps, and pipeline-shape regressions that the dry-run cannot detect
379
379
  - ⊗ Pass `--no-draft` to `task release` without explicit operator opt-in -- the default-draft contract is the foundation of the safety hardening surface
380
+ - ⊗ Invoke `task release` without `--skip-tag` when no `release-publish` grant or `DEFT_ALLOW_RELEASE_PUBLISH` is present -- the v0.105.0 cut published npm with no authz because the closed-verb check sat only on the later draft flip (#3527)
381
+ - ⊗ Delete the `release:publish` draft-flip closed-verb check as a substitute for the tag-push gate -- placement, not strength; both stay (#3527 / #1095)
380
382
  - ⊗ Treat Phase 5 as the npm authority gate or require a redundant human `publish` prompt when npm already succeeded -- npm ships at tag push (#1972); Phase 5 is GitHub draft QA only
381
383
  - ⊗ Expect `task release:rollback` to retract npm packages -- rollback is GitHub-only; npm recovery is forward-only (deprecate / dist-tag / patch)
382
384
  - ⊗ Run `task release:rollback` against a release that has > 30 minutes of consumer-driven downloads without first weighing the hot-fix path -- a withdrawal note in the next patch is almost always less disruptive than deleting a public artifact
@@ -75,7 +75,7 @@ On OpenClaw hosts with Directive installed (`.deft/core/` or equivalent content
75
75
  ! Before entering the review/fix loop, run the skill-level branch-policy guard (#746 / #747). Halt before any state mutation if the project's `plan.policy.allowDirectCommitsToMaster` is unresolvable AND the operator has not set `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`. Concretely:
76
76
 
77
77
  ```
78
- task verify:branch || exit 1
78
+ deft verify:branch || exit 1
79
79
  ```
80
80
 
81
81
  The skill MUST NOT modify files, push, or comment on the PR until the guard passes -- this catches the case where a malformed PROJECT-DEFINITION quietly disabled the policy and the agent would have committed directly to master mid-review.
@@ -29,7 +29,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
29
29
  ! Before any state mutation (creating worktrees, dispatching sub-agents, opening PRs), run the skill-level branch-policy guard (#746 / #747). Halt with the actionable disclosure message when the project's `plan.policy.allowDirectCommitsToMaster` is unresolvable AND `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT` is unset:
30
30
 
31
31
  ```
32
- task verify:branch || exit 1
32
+ deft verify:branch || exit 1
33
33
  ```
34
34
 
35
35
  The swarm skill creates branches per agent so the guard is mostly informational here, but a malformed PROJECT-DEFINITION (missing `plan.policy` block AND no legacy narrative) is a fail-closed signal worth surfacing before the swarm spawns N agents.
@@ -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