@deftai/directive-content 0.111.0 → 0.113.0

package/QUICK-START.md

@@ -52,17 +52,20 @@ Run these deterministic checks, in order:
 
 ### 1b. Does `../AGENTS.md`'s managed section match the current template? Do referenced paths resolve?
 
+Do **not** parse managed-section markers, byte-compare an attributed block against the template, or locate a hardcoded v2 managed-section marker. Detection is the four-state classifier (`current | stale | missing | absent`) from `deft agents:refresh --check` — the same plan `deft doctor` uses. v1/v2 markers are force-stale. Truncated or future markers are unreadable (do not append).
+
 Three checks here, in this order. The first match wins; later checks only run when earlier checks pass.
 
-1. **Template-content byte comparison (Case G gate).** Locate the managed section in `../AGENTS.md` (the block bounded by the `<!-- deft:managed-section v2 -->` and `<!-- /deft:managed-section -->` markers). Compare those bytes against the current `./templates/agents-entry.md` rendered managed-section output.
-   - ! If the managed section is **byte-different** from the current template render (or the markers are absent in `../AGENTS.md`), treat as **stale content** -- jump to Case G ("Stale AGENTS.md") in Step 2. Case G is the right remediation for byte-different staleness because the refresh actually rewrites the content.
-2. **Install-path resolution (Case K gate -- #1046 PR-A).** When the managed section IS byte-current, parse the section for its install-path declaration (`Full guidelines: <root>/main.md`, e.g. `.deft/core/main.md` for the canonical install layout or `deft/main.md` for the legacy install layout). Verify that `../<root>/main.md` exists on disk.
-   - ! If the managed section is **byte-identical** to the current template render BUT the declared install path does NOT resolve, jump to **Case K ("Install location mismatch")** in Step 2. Refreshing the managed section is a documented no-op when the content already matches -- Case K is a different failure class than Case G and demands a different remediation (#1046 finding #2).
+1. **Classifier (Case G gate).** Run `deft agents:refresh --check` (or `deft doctor`). If the CLI is not on PATH, run `npx @deftai/directive agents:refresh --check` or `npm i -g @deftai/directive` then the same verb. If the payload is missing, run `deft update`. Pre-canonical layout: frozen Go bridge (see UPGRADING.md / GitHub releases).
+   - ! If state is **stale**, **missing**, **absent**, or **unreadable**, treat as **stale content** -- jump to Case G ("Stale AGENTS.md") in Step 2. Case G remediates with the registered rewrite, not a hand-append.
+   - If state is **current**, continue to the install-path check below.
+2. **Install-path resolution (Case K gate -- #1046 PR-A).** When the classifier reports **current**, parse the section for its install-path declaration (`Full guidelines: <root>/main.md`, e.g. `.deft/core/main.md` for the canonical install layout or `deft/main.md` for the legacy install layout). Verify that `../<root>/main.md` exists on disk.
+   - ! If the classifier reports **current** BUT the declared install path does NOT resolve, jump to **Case K ("Install location mismatch")** in Step 2. Refreshing the managed section is a documented no-op when the content already matches -- Case K is a different failure class than Case G and demands a different remediation (#1046 finding #2).
 3. **Legacy skill-path resolution (v0.19 AGENTS.md backstop).** Parse `../AGENTS.md` for any token matching `deft/skills/<name>/SKILL.md` (the legacy v0.19 path shape) and verify the file exists under `./skills/<name>/SKILL.md` (relative to this QUICK-START.md).
    - ! If any referenced path does not exist on disk, treat `../AGENTS.md` as **stale** -- jump to Case G in Step 2.
    - If all referenced paths exist, continue to 1c.
 
-Priority ordering: Case G (byte-different content) always wins over Case K (install-path mismatch) because the refresh path is the higher-priority remediation -- when the template content has moved on, the refresh closes BOTH the content drift and any incidental install-path mismatch that the new content might re-introduce. Case K only fires when the content is byte-current AND the path is unresolved -- the exact "refresh would be a no-op" failure class issue #1046 documents.
+Priority ordering: Case G (classifier not current) always wins over Case K (install-path mismatch) because the registered refresh is the higher-priority remediation -- when the template content has moved on, the refresh closes BOTH the content drift and any incidental install-path mismatch that the new content might re-introduce. Case K only fires when the classifier is current AND the path is unresolved -- the exact "refresh would be a no-op" failure class issue #1046 documents.
 
 **Big-jump joint check (Case G+H gate).** Before acting on ANY Case G routing above (a byte-different managed section, or an unresolved legacy skill path), first ALSO evaluate the 1c pre-cutover check below against `../`. ! If 1c ALSO holds (real pre-v0.20 `SPECIFICATION.md` / `PROJECT.md` present), the project is in the **joint big-jump state** where both the AGENTS.md refresh (Case G) and the pre-cutover migration (Case H) are due — jump to **Case G+H** (combined single-session remediation) in Step 2 instead of Case G. The combined path runs the refresh and the migration in one session and emits a single restart, avoiding the wasted Case G → restart → Case H round-trip. If 1c does not hold, route to Case G as usual.
 
@@ -91,16 +94,15 @@ Pick exactly one case from Step 1 and follow its instructions. Do not mix cases.
 
 ### Case F — No AGENTS.md (fresh install)
 
-1. Read `./templates/agents-entry.md` (this directory).
-2. Write that content to `../AGENTS.md`.
-3. Tell the user: "✓ Created AGENTS.md at your project root."
-4. Continue to Step 3.
+1. ! Run `deft agents:refresh` (the registered rewrite for classifier state `absent`). ⊗ Do not copy `templates/agents-entry.md` by hand. If the CLI is not on PATH: `npx @deftai/directive agents:refresh` or `npm i -g @deftai/directive`, then the same verb. Payload missing: `deft update`. Pre-canonical layout: frozen Go bridge (UPGRADING.md / GitHub releases).
+2. Tell the user: "✓ Created AGENTS.md at your project root."
+3. Continue to Step 3.
 
 ### Case G — Stale AGENTS.md (v0.19 → v0.20 upgrade)
 
-1. Read `../AGENTS.md` and identify the **Deft-managed section** — bounded by the `deft/main.md` sentinel marker.
-2. If the `deft/main.md` sentinel is **absent**, treat the entire existing file as user-authored and do NOT rewrite it. Instead, read `./templates/agents-entry.md` and **append** its content to `../AGENTS.md` with two blank lines between the existing content and the appended block. This matches the idempotent append behavior documented in `setup.go::WriteAgentsMD` for brownfield projects with a pre-existing AGENTS.md.
-3. If the `deft/main.md` sentinel is **present**, replace only the sentinel-bounded section with the current content of `./templates/agents-entry.md`. Preserve everything outside that region verbatim.
+1. ⊗ Do not locate the `deft/main.md` sentinel, do not append `templates/agents-entry.md`, and do not hand-rewrite markers. QUICK-START is not a second parser.
+2. ! Run `deft agents:refresh`. That command is the four-state plan (`current | stale | missing | absent`; v1/v2 force-stale). Truncated close refuses to write a second section.
+3. If the CLI is not on PATH: `npx @deftai/directive agents:refresh` or `npm i -g @deftai/directive`, then the same verb. Payload missing or drifted: `deft update`. Pre-canonical layout: frozen Go bridge (UPGRADING.md / GitHub releases).
 4. Tell the user: "✓ Refreshed Deft-managed section of AGENTS.md. Your existing additions outside that region were preserved."
 5. ! Instruct the user: **"Framework updated. Start a new agent session to pick up the changes. The current session has stale context."** Do not continue past this instruction in the current session.
 
@@ -118,7 +120,7 @@ Reached only via the **Big-jump joint check** in 1b: the managed section in `../
 
 ! Run the two remediations in this exact order — **AGENTS.md refresh first, frozen migration guidance second** — then emit a **single** restart instruction at the very end:
 
-1. **Refresh AGENTS.md first (Case G work).** Perform Case G steps 1-4 verbatim: identify the managed section, append when the sentinel is absent or byte-replace it when present, and preserve everything outside the managed region. ⊗ Do NOT emit the Case G step-5 restart instruction here — the combined path defers the single restart to step 3.
+1. **Refresh AGENTS.md first (Case G work).** Perform Case G steps 1-4: run `deft agents:refresh` (registered rewrite). ⊗ Do not append. ⊗ Do NOT emit the Case G step-5 restart instruction here — the combined path defers the single restart to step 3.
 2. **Surface frozen migration path second (Case H work).** Perform Case H steps 1-3 verbatim: explain the v0.59.0 pinned migrator path (#2068), run `task migrate:preflight`, and point at UPGRADING.md. The operator (or a machine with v0.59.0 deposited) runs `task migrate:vbrief` outside the current npm deposit. ⊗ Do NOT perform Case H steps 4-5 until migration has completed on the pinned release and the operator has upgraded to current npm.
 3. **Single restart, exactly once.** Only after BOTH the refresh and the operator-confirmed migration + npm upgrade have completed, ! instruct the user EXACTLY ONCE: **"Framework updated and project migrated. Start a new agent session to pick up the changes. The current session has stale context."** ⊗ Do NOT emit a second restart instruction.
 
@@ -140,7 +142,7 @@ For the version-by-version context of a big jump, see the [big-jump triage entry
 The managed section in `../AGENTS.md` is byte-identical to the current `./templates/agents-entry.md` render, BUT the install path the managed section declares (e.g. `.deft/core/main.md`) does NOT resolve on disk. This is the failure class issue #1046 finding #2 documents: Case G's "refresh the managed section" prescription is a byte-for-byte no-op against the current template, so re-running just re-detects the same staleness next session.
 
 1. Tell the user (verbatim phrasing, naming the unresolved path): "AGENTS.md's managed section is byte-identical to the current template, but the install path it declares (`<declared-path>`) does NOT exist on disk. Refreshing the managed section would be a no-op -- Case G's remediation does not fix install-location mismatches."
-2. ! Direct the user to run `task framework:doctor` (forthcoming in PR-B of the #1046 cohort -- the diagnostic + remediation surface that owns Case K's fix path) OR to manually verify that the install path AGENTS.md claims actually exists on disk. Until PR-B merges, the manual check is the operator's only path: confirm the framework is deposited at the path AGENTS.md declares, OR re-run the installer / relocator to deposit at that path, OR hand-edit AGENTS.md to point at the path where the framework actually lives.
+2. ! Direct the user to run `deft doctor` (the diagnostic + remediation surface that owns Case K's fix path) OR to manually verify that the install path AGENTS.md claims actually exists on disk. Confirm the framework is deposited at the path AGENTS.md declares, OR run `deft update` / `npx @deftai/directive update` to deposit at that path, OR hand-edit AGENTS.md to point at the path where the framework actually lives. Pre-canonical layout: frozen Go bridge (UPGRADING.md / GitHub releases).
 3. ⊗ Run a Case G refresh -- it is a documented no-op for Case K. The managed section already byte-matches the current template; refreshing the bytes back to the same bytes does not change which install path is declared.
 4. ! Instruct the user: **"Stop here. Do not continue to Step 3 until the install-path mismatch is resolved -- subsequent sessions will re-enter Case K until then."**
 

package/Taskfile.yml

@@ -469,6 +469,10 @@ tasks:
           CLI_ARGS: "--enforce"
       - verify:codebase-map-fresh
       - verify:spec-prd-fresh
+      # #4095: committed RULE-MAP freshness (byte-identical renderer output).
+      - docs:rule-map:check
+      # #4099: committed capability index freshness (overlay vs registries).
+      - docs:capability-map:check
       - verify-strategy-output
       # #2980 residual: fail-closed product raw-write inventory (allowlist primitives + temporary residual).
       - verify-contained-writes-enforce

package/UPGRADING.md

@@ -9,6 +9,20 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 <!-- xbrief-backcompat-2111 -->
 
+## Current path
+
+Ordinary upgrades use the three-command model. This section is the current recovery path; frozen version-to-version hops stay below as history and keep their existing `UPGRADING.md#` anchors.
+
+| Your situation | Run this |
+| --- | --- |
+| Ordinary upgrade of an existing Directive project | `npm i -g @deftai/directive@latest`, then `directive update` in the project (`pnpm add -g @deftai/directive@latest` on pnpm) |
+| Not sure, or something looks broken | `directive doctor` |
+| First-time adoption, or a legacy / pre-v0.20 layout | `directive init` |
+
+Walkthrough: [Canonical upgrade — npm](#canonical-upgrade--npm-v0551). Multi-version jumps: [Big-jump triage](#big-jump-triage--multi-version-upgrades-start-here). Corporate or mirrored registry: [Corporate or mirrored npm registry](#corporate-or-mirrored-npm-registry). Frozen hop 1: [Frozen pre-v0.20 document-model migration](#frozen-pre-v020-document-model-migration-2068).
+
+---
+
 ## Dual policy block recovery (#3609)
 
 - **Applies when:** PROJECT-DEFINITION contains both legacy bare `plan.policy` and namespaced `plan["x-directive/policy"]`. The namespaced block wins reads, so the bare block is shadowed even when one or more values match.
@@ -98,7 +112,8 @@ Install source of truth for this repo is **pnpm** (`packageManager` field; CI us
 | `*.vbrief.json` | `*.xbrief.json` |
 | `vBRIEF` / “scope vBRIEF” in guidance | `xBRIEF` / “scope xBRIEF” |
 | `x-vbrief/*` reference tokens | `x-xbrief/*` (and migrate-accepted legacy tokens) |
-| `task vbrief:*` / `migrate:vbrief` aliases | Prefer `task xbrief:*` / `deft migrate:xbrief`; keep `vbrief:*` only as deprecated aliases when required for back-compat |
+| `task vbrief:*` aliases | Prefer `task xbrief:*`; keep `vbrief:*` only as deprecated aliases when required for back-compat |
+| Frozen `task migrate:vbrief` (v0.59.0 hop 1 only) | Current hop 2 is `deft migrate:xbrief` / `task migrate:xbrief`. Frozen hop 1 is **not** a current alias of hop 2. |
 | Envelope keys `vBRIEFInfo` | `xBRIEFInfo` (legacy keys still read-accepted on unmigrated files) |
 
 **Why two names existed:** consumer layout and disk SoT moved to `xbrief/` while docs, glossary, and marketing still taught vBRIEF as current. That dual present-day naming is retired (#2907). Schema lineage, fixtures, migrate paths, changelog history, and archive prose may still say vBRIEF — always as **legacy/historical**, never as competing current guidance.
@@ -358,6 +373,8 @@ Non-native-skill harnesses (Codex CLI, OpenCode) report 0 B frontmatter; set `ha
 
 ## xBRIEF layout migration (#2034 / #2110)
 
+This section is **hop 2** for projects already on vBRIEF 0.6 (`vbrief/` lifecycle). Already-current xBRIEF 0.8: skip. Flat pre-v0.20 root docs: start at hop 1 in [Frozen pre-v0.20 document-model migration](#frozen-pre-v020-document-model-migration-2068). ⊗ Pin v0.59.0 or run frozen `migrate:vbrief` for this hop.
+
 After upgrading to a release that ships the xbrief rename, convert legacy on-disk layout if `deft doctor` reports a `vbrief/` tree or `x-vbrief/` reference tokens:
 
 ```bash
@@ -424,44 +441,67 @@ import schema from "@deftai/directive-types/schemas/xbrief-core-0.8.schema.json"
 
 ### `deft migrate` vs pre-v0.20 document-model migration
 
-These commands are unrelated — do not confuse them:
+These three commands are unrelated — do not confuse them:
 
-| Command | When to use | What it does |
-| --- | --- | --- |
-| `deft migrate` / `directive migrate` | Canonical-vendored `.deft/core/` deposit after npm upgrade (#1941) | Stamps `managed_by: npm` into the install manifest. Idempotent; never downloads payload. |
-| Pre-v0.20 document-model migration | Legacy authoritative `SPECIFICATION.md` / `PROJECT.md` only | **Not shipped on current npm releases (#2068).** Use the [frozen-release path](#frozen-pre-v020-document-model-migration-2068) below. |
+| Command | Runtime | When to use | What it does |
+| --- | --- | --- | --- |
+| `deft migrate` / `directive migrate` | Current npm | Canonical-vendored `.deft/core/` deposit after npm upgrade (#1941) | Stamps `managed_by: npm` into the install manifest. Idempotent; never downloads payload. **Not** document-model migration. |
+| `deft migrate:xbrief` / `task migrate:xbrief` | Current npm | Hop 2: vBRIEF 0.6 (`vbrief/`) → xBRIEF 0.8 (`xbrief/`) | Layout + envelope migration. Current Taskfiles ship this as `migrate:xbrief`. |
+| Frozen `task migrate:vbrief` | **v0.59.0 only** | Hop 1: pre-v0.20 flat `SPECIFICATION.md` / `PROJECT.md` → vBRIEF 0.6 | Python migrator. **Not shipped on current npm.** Current Taskfiles have no `migrate:vbrief` target. |
 
 ### Frozen pre-v0.20 document-model migration (#2068)
 
-Current `@deftai/directive` npm releases no longer ship `task migrate:vbrief` or `scripts/migrate_vbrief.py` on the consumer deposit path (#2022 Phase 3). If your project still uses the pre-v0.20 flat document model (authoritative root `SPECIFICATION.md` / `PROJECT.md` without vBRIEF lifecycle folders), migrate **once** on a pinned release that still bundles the Python migrator, then join the normal npm upgrade path.
+Current `@deftai/directive` npm releases no longer ship `task migrate:vbrief` or `scripts/migrate_vbrief.py` on the consumer deposit path (#2022 Phase 3).
+
+**This is a two-hop chain.** The pre-v0.20 flat model does not migrate straight to the current layout:
+
+- **Hop 1** — pin **v0.59.0**, run frozen `task migrate:vbrief` (flat → vBRIEF v0.6).
+- **Hop 2** — on **current npm**, run `deft migrate:xbrief` (vBRIEF v0.6 → xBRIEF v0.8). Not `deft migrate`.
+
+This file owns the numbered hop commands. [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) should point here rather than restate a second procedure. Live `frozenPreCutoverMigrationGuidance()`, QUICK-START Case H, and README are other envelopes.
+
+#### Who runs which hop
+
+| Starting layout | Next step |
+| --- | --- |
+| Flat authoritative root `SPECIFICATION.md` / `PROJECT.md` (no vBRIEF/xBRIEF lifecycle) | Hop 1, then hop 2 |
+| Valid vBRIEF 0.6 (`vbrief/` lifecycle) | Hop 2 only — do not pin v0.59.0 |
+| xBRIEF 0.8 with incomplete lifecycle folders | Current repair/validation only. Not hop 1. |
+| Complete xBRIEF 0.8 | No document-model migration |
+
+⊗ Pin v0.59.0 or run frozen `migrate:vbrief` on an already-current xBRIEF 0.8 project. Incomplete `xbrief/` is not hop-1 input.
+
+`deft doctor` / current `task migrate:preflight` may still print `Pre-cutover: migration needed` for a missing lifecycle folder on an otherwise current tree (runtime `detectPreCutover`). That predicate is not this docs slice. Hop 1 in **this** numbered list is only for flat authoritative root docs.
 
-> **Durability & support horizon (#2297).** This is a **best-effort** path for a document model that predates v0.20. The permanence anchor is the **`v0.59.0` git tag** — GitHub serves a source tarball for any tag on demand (`https://github.com/deftai/directive/archive/refs/tags/v0.59.0.tar.gz`), so recovery does **not** depend on any uploaded release asset staying attached. As long as the tag exists, the migrator is reachable. If you cannot reach the frozen payload at all, use the **[Fresh-start fallback](#fresh-start-fallback-2297)** below.
+> **Durability & support horizon (#2297).** This is a **best-effort** path for a document model that predates v0.20. The permanence anchor is the **`v0.59.0` git tag** — GitHub serves a source tarball for any tag on demand (`https://github.com/deftai/directive/archive/refs/tags/v0.59.0.tar.gz`), so recovery does **not** depend on any uploaded release asset staying attached. Verify the checkout SHA before hop 1: tag `v0.59.0` currently names commit `e8bfd5aa21511a38e4b45b3d5b80edb30e9e2dd0` (a tag is a movable ref). If you cannot reach the frozen payload at all, use the **[Fresh-start fallback](#fresh-start-fallback-2297)** below.
 
-**Applies when:** `deft doctor` reports `Pre-cutover: migration needed`, or `task migrate:preflight` exits non-zero with a `document-model` FAIL line.
+**Applies when:** the project still has authoritative pre-v0.20 root `SPECIFICATION.md` / `PROJECT.md` (no `<!-- deft:deprecated-redirect -->` sentinel, and no `vbrief/` or `xbrief/` lifecycle).
 
 **Pinned tag:** `v0.59.0` — the last release before the Python-free npm deposit; the tagged tree includes `scripts/migrate_vbrief.py`.
 
-**This is a two-hop chain.** The pre-v0.20 flat model does not migrate straight to the current layout: hop 1 is `task migrate:vbrief` on **v0.59.0** (flat → vBRIEF v0.6); hop 2 is `deft migrate:xbrief` on **current npm** (vBRIEF v0.6 → xBRIEF v0.8). Steps 5–6 below cover hop 2.
+**Trust:** run hop 1 only against a **trusted** project checkout. The frozen Python migrator writes under repo-controlled paths (it replaces root docs with redirect stubs). Do not point it at an untrusted tree.
 
 **Steps:**
 
-1. Install **Python 3.11+** and **[uv](https://docs.astral.sh/uv/)** on the migration machine.
-2. Deposit framework **v0.59.0** using one of (git-tag methods first — they survive even if release assets are removed):
-   - **Source tarball from the tag:** `curl -fsSL https://github.com/deftai/directive/archive/refs/tags/v0.59.0.tar.gz | tar xz` (full source tree including the migrator), or
-   - **Git clone / submodule:** `git checkout v0.59.0` in your framework checkout, or
+1. Confirm the starting layout in the table above. Already-current xBRIEF 0.8: stop. Valid vBRIEF 0.6: skip to hop 2 (step 7).
+2. Install **Python 3.11+** and **[uv](https://docs.astral.sh/uv/)** on the migration machine.
+3. Fetch framework **v0.59.0** and verify SHA `e8bfd5aa21511a38e4b45b3d5b80edb30e9e2dd0` (git-tag methods first — they survive even if release assets are removed):
+   - **Git clone (preferred):** `git clone --branch v0.59.0 https://github.com/deftai/directive.git deft-v0.59.0`, then `git -C deft-v0.59.0 rev-parse HEAD` must equal that SHA, or
+   - **Source tarball from the tag:** download `https://github.com/deftai/directive/archive/refs/tags/v0.59.0.tar.gz`, extract to a directory, then confirm the tree matches the SHA, or
    - **Frozen Go installer** at [GitHub Releases tag v0.59.0](https://github.com/deftai/directive/releases/tag/v0.59.0) (legacy bridge; relies on the uploaded asset, so prefer a git-tag method above for durability).
-3. From the project root, preview then apply:
+4. From the **consumer project root** (working directory = the project being migrated), run hop 1 against the **pinned** Taskfile — not the current deposit:
    ```bash
-   task migrate:preflight
-   task migrate:vbrief -- --dry-run
-   task migrate:vbrief
+   task -t /path/to/deft-v0.59.0/Taskfile.yml migrate:vbrief -- --dry-run
+   task -t /path/to/deft-v0.59.0/Taskfile.yml migrate:vbrief
    ```
-   Fallback when the consumer Taskfile has no deft include: `task -t ./.deft/core/Taskfile.yml migrate:vbrief`.
-4. Regenerate exports once: `task roadmap:render`, `task project:render`, and `task prd:render -- --force` when you maintain a `PRD.md`.
-5. Upgrade to current npm: `npm i -g @deftai/directive@latest`, then `deft update`, `deft migrate`, `deft doctor`.
-6. Start a **new agent session** so refreshed AGENTS.md and skills load from a clean context.
+   Frozen `migrate:vbrief` self-invokes `migrate:preflight` on that same pinned Taskfile. Do not run current-npm `task migrate:preflight` as the hop-1 gate. Current deposits have no `migrate:vbrief` target — `task -t ./.deft/core/Taskfile.yml migrate:vbrief` is a dead fallback.
+5. **Hop 1 postcondition** (frozen runtime, not current `deft doctor`): the migrator exits 0, and the project has `vbrief/specification.vbrief.json`, `vbrief/PROJECT-DEFINITION.vbrief.json`, and `vbrief/{proposed,pending,active,completed,cancelled}/`. Root `SPECIFICATION.md` / `PROJECT.md` are deprecation redirects. This is vBRIEF 0.6, not xBRIEF.
+6. Upgrade to current npm: `npm i -g @deftai/directive@latest`, then `deft update` from the project root. Optional: regenerate exports with `task roadmap:render`, `task project:render`, and `task prd:render -- --force` when you maintain a `PRD.md` (frozen-payload renderers; hop 2 will rewrite layout).
+7. **Hop 2:** `deft migrate:xbrief` (or `task migrate:xbrief` from a maintainer checkout). Requires a clean working tree unless `--force`.
+8. **Hop 2 postcondition** (current npm): `deft migrate:xbrief` reports migrated or already done; `xbrief/` exists with `xBRIEFInfo.version` `0.8`; and the xBRIEF signpost is `xBrief migration: none` (or `converged`). A `vbrief/`-only tree must fail this proof. Do not treat `deft doctor` exit 0 as hop-2 proof. `deft migrate` (provenance stamp) is a separate npm-channel step — run it after hop 2 if needed, never instead of hop 2.
+9. Start a **new agent session** so refreshed AGENTS.md and skills load from a clean context.
 
-⊗ Run `npm i -g @deftai/directive@latest` / `deft update` on a project that still has authoritative pre-v0.20 root docs — the current deposit cannot run the migrator; follow the frozen path first.
+⊗ Run `npm i -g @deftai/directive@latest` / `deft update` on a project that still has authoritative pre-v0.20 root docs — the current deposit cannot run hop 1; follow the frozen path first.
 
 #### Fresh-start fallback (#2297)
 
@@ -1031,7 +1071,7 @@ The contract is byte-stable by construction:
 
 ## From any pre-v0.20 version → v0.20.0 (historical; use frozen path)
 
-> **Current releases (#2068):** follow [Frozen pre-v0.20 document-model migration](#frozen-pre-v020-document-model-migration-2068) instead of upgrading straight to latest npm. The section below documents what the v0.20 cutover changed; commands assume framework **v0.59.0** (or another pinned release that still ships `migrate_vbrief.py`).
+> **History.** This From-X-to-Y list records the v0.20.0 cutover. It is **not** the current hop-2 instruction. Current hop 2 is `deft migrate:xbrief` in [Frozen pre-v0.20 document-model migration](#frozen-pre-v020-document-model-migration-2068). Commands below assume pinned **v0.59.0** (hop 1 payload only).
 
 - **Applies when:** `deft doctor` / `task migrate:preflight` reports pre-cutover state. Legacy `SPECIFICATION.md` / `PROJECT.md` without the `<!-- deft:deprecated-redirect -->` sentinel is the canonical signal.
 - **Safe to auto-run:** No — `task migrate:vbrief` on the pinned release rewrites `SPECIFICATION.md` and `PROJECT.md` into deprecation-redirect stubs and creates lifecycle folders; review `--dry-run` first.

package/commands.md

@@ -4,7 +4,7 @@ Current command surfaces for scoped work, generated documents, triage/cache work
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**See also**: [verification/verification.md](./verification/verification.md) | [resilience/continue-here.md](./resilience/continue-here.md) | [vbrief/vbrief.md](./vbrief/vbrief.md) | [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md)
+**See also**: [verification/verification.md](./verification/verification.md) | [resilience/continue-here.md](./resilience/continue-here.md) | [vbrief/vbrief.md](./vbrief/vbrief.md) | [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md) | [docs/capabilities.md](./docs/capabilities.md) (generated capability index; `task docs:capability-map`)
 
 ---
 
@@ -107,8 +107,8 @@ On-demand **write + check** dense xBRIEF SoT artifacts at an explicit path. Thes
 
 | Verb | Meaning |
 |------|---------|
-| `deft xbrief:create` / `task xbrief:create` | Write json, md, or both at `--out` |
-| `deft xbrief:verify` / `task xbrief:verify` | Fail-closed check at `--out` |
+| `deft xbrief:create` | Write json, md, or both at `--out` |
+| `deft xbrief:verify` | Fail-closed check at `--out` |
 | `scope:*` / intake | Lifecycle birth and folder/status transitions |
 | `xbrief:preflight` | Implementation-intent gate (unchanged) |
 
@@ -146,7 +146,7 @@ Common commands:
 - `task scope:fail -- xbrief/active/<file>.xbrief.json` -- mark running work failed when the scope cannot complete.
 - `task scope:cancel -- <path>` -- move a scope to `cancelled/`.
 - `task scope:restore`, `task scope:block`, `task scope:unblock`, `task scope:demote`, and `task scope:undo:*` -- repair or reverse lifecycle transitions.
-- `task issue:sync-from-xbrief -- <path>` -- post a GitHub issue comment summarizing material AC/status changes for an origin-linked scope xBRIEF (`plan.references` with `x-xbrief/github-issue`). Supports `--dry-run` (print without posting), `--repo OWNER/NAME` when the reference URI lacks a repo slug, and `--allow-cross-repo` for intentional cross-repo sync (refused by default; #2633). Skips when no material changes since the last successful sync. Closes the reverse-sync gap after `task issue:ingest` (#2540).
+- `deft issue:sync-from-xbrief -- <path>` -- post a GitHub issue comment summarizing material AC/status changes for an origin-linked scope xBRIEF (`plan.references` with `x-xbrief/github-issue`). Supports `--dry-run` (print without posting), `--repo OWNER/NAME` when the reference URI lacks a repo slug, and `--allow-cross-repo` for intentional cross-repo sync (refused by default; #2633). Skips when no material changes since the last successful sync. Closes the reverse-sync gap after `task issue:ingest` (#2540).
 - `task issue:ingest -- <N>` / `task issue:ingest -- --all [--label L] [--status S] [--dry-run]` -- ingest GitHub issues as scope xBRIEFs (deduplicates via existing references).
 - `task reconcile:issues [-- --apply-lifecycle-fixes]` -- scan origin-linked xBRIEFs for stale or closed GitHub issues.
 
@@ -168,7 +168,7 @@ The implementation gate succeeds only for active scope xBRIEFs with `plan.status
 
 **Slash-command intent containment (#1193):** When a session is originated by a slash command, that command is the *only* authorized verb for the session. Set `DEFT_SESSION_SLASH_VERB` (e.g. `/github-issue`) so `task xbrief:preflight` and PreToolUse hooks enforce the ceiling. Non-implement verbs (`/github-issue`, `/triage`, `/refine`, `/discuss`, `/research`, …) MUST NOT authorize implement, push, PR, merge, or deploy — adjacent bugs noticed during RCA become a second filed issue, not a second PR. Implement verbs: `/build`, `/ship`, `/ship-hotfix`, `/swarm`, `/implement`.
 
-**Human merge gate (#1193):** Typed `plan.policy.requireHumanMerge` (defaults true when `plan.policy.autoDeployOnMerge` is true). Agents may open PRs but must not merge when the gate is ON. Surfaces: (1) `task pr:wait-mergeable-and-merge` refuses agent merge, (2) `task verify:branch` advisory note, (3) branch-protection / setup requiring ≥1 human reviewer. Session-start discloses when ON. Override: `task policy:allow-bot-merge -- --confirm` or `DEFT_ALLOW_BOT_MERGE=1`.
+**Human merge gate (#1193):** Typed `plan.policy.requireHumanMerge` (defaults true when `plan.policy.autoDeployOnMerge` is true). Agents may open PRs but must not merge when the gate is ON. Surfaces: (1) `task pr:wait-mergeable-and-merge` refuses agent merge, (2) `task verify:branch` advisory note, (3) branch-protection / setup requiring ≥1 human reviewer. Session-start discloses when ON. Override: `deft policy:allow-bot-merge -- --confirm` or `DEFT_ALLOW_BOT_MERGE=1`.
 
 **Hotfix classifier (#1193):** Typed `plan.policy.hotfixCriteria` + pure `evaluateHotfixEligibility`. Small fix / pure revert may propose label `hotfix-candidate` only; a human promotes to `hotfix`. Refactors, new exports/handlers, and forbidden paths (Dockerfile, fly.toml, workflows, migrations, auth/secrets) never qualify.
 
@@ -286,7 +286,6 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 - `task check:merge` -- explicit merge-chokepoint alias for `check:framework-source` in the framework source repo (#1704).
 - `task check:framework-source` -- framework-source lane.
 - `task check:consumer` -- consumer-shape lane.
-- `task check:slow` -- slower/full checks.
 
 ### Gate throughput — iteration fast lane (#1704)
 
@@ -302,7 +301,7 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 - `task verify:branch` -- enforce default-branch protection.
 - `task verify:hooks-installed` -- ensure local git hooks are configured; use `deft verify:hooks-installed --scope=agent --live` for fail-closed agent-host registration + command functionality.
 - `task verify:encoding` -- detect mojibake and BOM issues.
-- `task verify:xbrief-conformance` -- validate xBRIEF conformance surfaces.
+- `task verify:vbrief-conformance` -- validate xBRIEF conformance surfaces.
 - `task verify:cache-fresh` -- validate cache freshness where required.
 - `task verify:capacity`, `task verify:wip-cap`, and `task verify:judgment-gates` -- policy/capacity gates.
 - `task verify:orphan-active` -- fail closed when active/running xBRIEFs still point at closed issues or merged PRs (#2321). After merge, `task verify:orphan-active -- --issue N` scans briefs that reference that issue. Confirmed shipped prints `task scope:complete -- <path>`; unresolved lookup prints a retry remediation and still exits 1 (#3429). PR-only briefs stay on the unscoped scan or `task swarm:complete-cohort`.
@@ -403,7 +402,7 @@ After CLI/deposit upgrade, disk can show the new generation while a long-lived s
 
 - ! Successful `init` / payload `update` stamps a monotonic live generation at `.deft/GENERATION.json` (outside `.deft/core` so replace does not wipe the counter).
 - ! Mutation `session:start` (cold and re-arm) binds that generation into `.deft/session-bind.json` when payload surfaces load.
-- ! Query with `deft freshness:report` / `task freshness:report` / `task session:freshness` (`--json` supported). States: `current` | `stale_soft` | `stale_hard` | `unbound`. Exit `0` only when `current`.
+- ! Query with `deft freshness:report` / `deft session:freshness` (`--json` supported). States: `current` | `stale_soft` | `stale_hard` | `unbound`. Exit `0` only when `current`.
 - ! Rebind without restarting a shared host runtime: re-load surfaces into the session, then `deft freshness:bind` (or re-arm / `session:ready`).
 - ! Mid-mission: park and hand off before a hard refresh; an empty session after refresh is not work complete.
 - Soft vs hard meanings, surfaces, and API: `content/docs/freshness-contract.md`.
@@ -457,7 +456,7 @@ Cross-link: spawn three postures and deny recoveries live under § Agent-host di
 ### Mutable ritual (mutation posture)
 
 - ! On **mutation** session start, run `deft session:start` (or `task session:start` in framework source) after loading AGENTS.md. Records quick-tier ritual in `.deft/ritual-state.json`: alignment confirmation, branch-policy disclosure, `deft verify:tools` guidance, default-branch sync warnings, and `deft triage:welcome` one-liner. State is worktree- and HEAD-bound; stale after `plan.policy.sessionRitualStalenessHours` hours (default 4). Mutation start also claims the worktree occupancy lease (`.deft/occupancy.json`); see Session routing (#3433).
-- ! **Orientation compression Now (#3286):** mutation cold `session:start` composes `doctor` + #3282 toolchain preflight (and deposit-sha fast-paths for `agents:refresh` / `verify:cache-fresh`) as inline sections with per-section status lines — composition of existing steps, not a new monolith. When the deposit fingerprint (payload + templates + engine) is unchanged, refresh surfaces print one-line `unchanged - sha match` no-ops. Opt-in compact output: `deft session:start --compact` or `DEFT_SESSION_COMPACT=1` (verbose remains the default). #2176 read-only default is unchanged. Dual-path Later (`deft orient`) stays open until run-summary telemetry shows ritual+gate share ≥ 25% after Now ships (#2899).
+- ! **Orientation compression Now (#3286):** mutation cold `session:start` composes `doctor` + #3282 toolchain preflight (and deposit-sha fast-paths for `agents:refresh` / `verify:cache-fresh`) as inline sections with per-section status lines — composition of existing steps, not a new monolith. When the deposit fingerprint (payload + templates + engine) is unchanged, refresh surfaces print one-line `unchanged - sha match` no-ops. Opt-in compact output: `deft session:start --compact` or `DEFT_SESSION_COMPACT=1` (verbose remains the default). #2176 read-only default is unchanged. Dual-path Later (orient) stays open until run-summary telemetry shows ritual+gate share ≥ 25% after Now ships (#2899).
 - ! Cold `session:start` does **not** run the live agent-hook probe. Functional readiness belongs to the gated mutation path so cold ceremony retains the #2990/#2991 latency profile.
 - ! **Hot path latency (#2991):** by default, mutation `session:start` does **not** block ritual-state write on optional network. It skips the npm release-availability probe and triage cache empty-hydrate / self-heal (`ensureTriageCacheHydrated` / `maybeSelfHealCache`). Targets (operator-facing, not CI-hard): warm hot path typically under a few seconds once tools are on PATH; cold path dominated by local `verify:tools` and git, usually well under ~30s when optional network is off. Empty-cache GitHub fetch-all and npm `view` previously accounted for multi-minute hangs in the WWYSYDH pilot — those stay off the critical path unless opted in.
 - ! **Cold vs re-arm ceremony tiers (#2992):** default `session:start` is the **cold** (full) path. After age staleness or compact re-arm (#2113) on the **same worktree** with continuous HEAD and previously-passing quick steps, prefer `deft session:start --rearm` (alias `--tier=rearm`) to refresh the ritual clock + HEAD/worktree bind without `verify:tools`, triage welcome, release probe, or staleness tickler. Full cold remains required for missing/invalid state, worktree change, discontinuous HEAD, first install, or failed/missing quick steps. Compact marks `rearm_needed`; PreToolUse denial and inspect/verify messages prefer re-arm recovery when cold is unnecessary.
@@ -465,7 +464,7 @@ Cross-link: spawn three postures and deny recoveries live under § Agent-host di
 - ~ `session:start --json` includes `steps[]` with `name` + `duration_ms` for major phases (`alignment`, `branch_policy`, `verify_tools`, `triage_welcome`, `release_probe`, `ritual_write`), plus total `duration_ms`, `optional_network`, and `ceremony_tier` (`cold` | `rearm`). Skipped optional steps report `skipped: true` and `duration_ms: 0`. Use this for attribution when investigating ceremony wall-clock.
 - ~ **Process-cost events (#2994 / #3508):** on mutation `session:start` completion (cold or re-arm), Directive appends a local `session:start` behavioral event to `.deft-cache/events.jsonl` with `ceremony_tier`, `duration_ms`, `exit_code`, and optional `steps[]` (same labels as `--json`). Mutation `session:start` also prints one operator-visible `ceremony <tier> <ms>` line (hidden under `--compact` / `DEFT_SESSION_COMPACT`). When PreToolUse denies for `ritual-not-ready`, a local `session:ritual-blocked` event records `tool_name`, `code`, and optional `recovery_tier` / `detail`. Always-on best-effort (never blocks ceremony or deny path); not gated on `valueFeedback`; **no remote upload** (Product Insights #2603 is a separate opt-in). Pull the rollup with `task value:show` (composed reader; CLI process time, not agent-turn wall clock). See § Process-cost events below. ⊗ Do not use the printed CLI duration as #3286 Later graduation input.
 - ~ At safe idle points (clean tree, no in-flight story), mutation session start and `deft scope:complete` may also run the staleness tickler: an interactive, consent-based offer to upgrade Directive (`npm i -g @deftai/directive@latest`) and/or migrate xBRIEF (`deft migrate:xbrief`). Escalation tiers, snooze windows, and opt-out live under `plan.policy.stalenessTickler` — inspect with `deft policy:show --field=stalenessTickler`. State persists in `xbrief/.triage-cache/staleness-tickler-state.json`. Skips framework source checkouts, dirty trees, CI/headless (`DEFT_SESSION_RITUAL_SKIP=1`), and typed opt-out. Refs #2488 / #2489.
-- ! Before any code-writing tool call or `start_agent` implementation dispatch, run `deft verify:session-ritual -- --tier=gated`. Gated tier fails closed unless quick-tier state is fresh; lazily records the non-deferrable `agent_hooks` readiness gate plus `deft doctor` and `deft verify:cache-fresh` entrypoints. Agent-hook correctness is independent of doctor warnings and throttling. Step 0 of the pre-`start_agent` gate stack.
+- ! Before any code-writing tool call or `start_agent` implementation dispatch, run `deft verify:session-ritual -- --tier=gated`. Gated tier fails closed unless quick-tier state is fresh; lazily records the non-deferrable `agent_hooks` readiness gate plus `deft doctor` and `task verify:cache-fresh` entrypoints. Agent-hook correctness is independent of doctor warnings and throttling. Step 0 of the pre-`start_agent` gate stack.
 - ! **One-shot recovery (#2993 / #3100):** when PreToolUse denies writes for a stale/missing gated ritual, run `deft session:ready` (or `task session:ready`). It composes `session:start` (only when quick-tier is not green) + `verify:session-ritual -- --tier=gated` + `cache fetch-all --force` when `cache_fresh` is the remaining blocker, then re-verifies. Even when gated inspect is already fresh, the fast path forces one live `agent_hooks` check so later drift cannot hide behind cached ritual state; it still avoids unnecessary fetch-all. Flags: `--json`, `--repo OWNER/NAME`, `--with-network` (forwarded to session:start). Prefer this over juggling the multi-step recovery sequence under hook pressure.
 - ? Postpone with `deft session:start --defer step=reason` (`alignment`, `branch_policy`, `triage_welcome`, `doctor`, `cache_fresh`). `agent_hooks` is non-deferrable.
 - Headless workers / CI MAY set `DEFT_SESSION_RITUAL_SKIP=1`; verifier exits 0 but warns when bypass hides failure.
@@ -488,7 +487,7 @@ Agents use this signal to prefer portable syntax and quote zsh-sensitive data su
 - Credential bridging: host-gh (`gh auth login` in the execution env) or injected-token (`GH_TOKEN` / `GITHUB_TOKEN` / `GH_ENTERPRISE_TOKEN`). Never put token values in prompts or transcripts.
 - Contract: `content/contracts/scm-readiness.md`; operator docs: `content/scm/github.md` § Mismatched/headless SCM readiness.
 
-**Pre-`start_agent` gate stack (#1149/#1348):** (0) `deft verify:session-ritual -- --tier=gated` → (1) `deft verify:story-ready` → (2) `deft xbrief:preflight` → (3) `deft verify:cache-fresh` → (4) `deft verify:branch` + hooks → (5) `start_agent`.
+**Pre-`start_agent` gate stack (#1149/#1348):** (0) `deft verify:session-ritual -- --tier=gated` → (1) `deft verify:story-ready` → (2) `deft xbrief:preflight` → (3) `task verify:cache-fresh` → (4) `deft verify:branch` + hooks → (5) `start_agent`.
 
 ```mermaid
 flowchart TD
@@ -597,7 +596,8 @@ Directive does not guess your mix. Either you name the next units in order (**or
 - `task triage:summary`, `task triage:scope`, `task triage:scope-drift`, `task triage:subscribe`, `task triage:unsubscribe`, `task triage:classify`, `task triage:strip-withdrawn-chips`, `task triage:welcome`, and `task triage:smoketest` -- supporting workflow and onboarding commands.
 - `task triage:classify -- --mirror` -- **Withdrawn (#4070).** Dry-run and `--apply` both fail closed with a pointer at #4070. Replacement sieve is #4071. #3579 is transitively withdrawn for the gap. Do not close #1423, #3579, #2611, or #3923. `--list` / `--validate` remain. Strip leftover chips with `task triage:strip-withdrawn-chips` (remaining-set apply, not classify).
 - **Triage write-back pairing (#1423 / ADR-005).** When the author stamps that a lean is mechanism-shaped, write **both**: body-text field `mechanism-shaped: true` (the artifact) **and** mirrored label `design-critique:mechanism-shaped` (what `plan.policy.judgmentGates` matches and lists show). Do not compute the classification. No stamp -> the design-critique gate never fires. Clearance is a separate line on the thread: `design-critique: warranted | not warranted, because ...` -- engine evaluates presence, shape, and authority, never the because-clause content. Advisory/observe; `verify:judgment-gates --enforce` stays opt-in unused; `scope:promote` does not gain `--enforce` in this story.
-- **Design-critique catalog chip (#3642).** Parent attach of `triage-ready` / recut `mechanism-shaped` MUST use `task scm:issue:design-critique-chip -- --issue N --chip triage-ready|mechanism-shaped [--repo OWNER/NAME]` (or `deft scm issue design-critique-chip`). Closed catalog remaining-set replace, one write. ⊗ `gh api POST .../labels`. ⊗ additive `scm:issue:edit --add-label`.
+- **Design-critique catalog chip (#3642 / #4205).** Parent attach of `triage-ready` / `recut-needed` / recut `mechanism-shaped` MUST use `task scm:issue:design-critique-chip -- --issue N --chip triage-ready|mechanism-shaped|recut-needed [--repo OWNER/NAME]` (or `deft scm issue design-critique-chip`). Closed catalog remaining-set replace, one write. Auto-stamp chip from `resolveAutoStampCatalogChip` (`Recut:` token → recut-needed). ⊗ `gh api POST .../labels`. ⊗ additive `scm:issue:edit --add-label`.
+- **Work claim (#4200).** Same-issue busy flag `status:claimed`. `task scm:issue:work-claim -- claim|show|release --issue N [--repo OWNER/NAME]` (`deft scm issue work-claim`). Session-start and `xbrief:preflight` MUST show. Warn is success; not a lock. Claim refuses read-only / no occupancy. Last-write-wins: the board can lie about who. v1 does not detect two-issue path overlap. Catalog in `.github/ISSUE_LABELS.md`; ⊗ invent the name per issue.
 - **Operator discovery for SCM label mirror (#3124).** Withdrawn with classify `--mirror` (#4070). The session/welcome tip does not fire. #3124 discovery and #1423 Wave 1–2 apply are unusable after this lands; those issues stay open.
 
 ### Cache Tasks

package/contracts/design-critique.md

@@ -25,7 +25,7 @@ Boundaries are read off the machinery in this document, not asserted here.
 - Rounds accumulate inside one arc. The auto-stamp denominator is scoped to critic posts in this arc and keeps a Stop 4 retry's post, so a retry continues the arc it retries.
 - Same-round siblings share one ceiling and one panel-deposit. A panel is one round, not N arcs.
 - The arc stays open through the operator-gated loop until a verified synthesis is accepted, or until the halt line. Successor leans are moves inside that loop, so revising a lean before bind is not a boundary.
-- A **recut** opens the next arc, and only after bind: it re-applies `design-critique:mechanism-shaped`, drops `design-critique:triage-ready`, and its new lean is not cleared by the older completed-arc record. That is a post-bind target revision.
+- A **recut** opens the next arc, and only after bind: it re-applies `design-critique:mechanism-shaped`, drops `design-critique:triage-ready` and `design-critique:recut-needed`, and its new lean is not cleared by the older completed-arc record. That is a post-bind target revision.
 
 - ! Read `arc` in this document as that unit.
 - ⊗ Read a new ceiling, a new round, or a pre-bind lean revision as a new arc.
@@ -51,7 +51,7 @@ The Stop 1 write-back records `refutation-target:` naming the triage author's hi
 
 The front door is a session-local run-posture field, not a second ingest switch and not a third occupancy concept. Occupancy mechanics stay on #4020. Cite that rule; do not clone it.
 
-Closed tokens on the operator utterance: `direct`, `forge-only`, `github-only`, `github only`, `no worktrees` for direct; `checkout` for the mutating checkout path. `parseOperatorRunPosture` (`packages/core/src/design-critique/run-posture.ts`) matches those tokens with word boundaries. Missing token, including `arc <N> yolo`, asks before Stop 1. Yolo does not pick a mode. `ingest` is not a front-door mode; that token asks. ⊗ Substring or NLP classification. ⊗ Front-door mode `ingest`. ⊗ A yolo default-direct.
+Closed tokens on the operator utterance: `direct`, `directly`, `forge-only`, `github-only`, `github only`, `on github`, `no worktrees` for direct; `checkout` for the mutating checkout path. `parseOperatorRunPosture` (`packages/core/src/design-critique/run-posture.ts`) matches those tokens with word boundaries. `on github` is a location synonym at this Stop 1 front door: `file an issue on github` and `the comments live on github` resolve `direct`. Missing token, including `arc <N> yolo`, asks before Stop 1. Yolo does not pick a mode. `ingest` is not a front-door mode; that token asks. On grok-bot detect, a missing-token ask resolves to `arc-mode:direct` unless checkout tokens already won. `resolveArcRunPostureForHost` consumes `parseOperatorRunPosture`; do not clone the parser. ⊗ Substring or NLP classification. ⊗ Front-door mode `ingest`. ⊗ A yolo default-direct. ⊗ Default-direct without grok-bot detect. ⊗ An `arc N` proximity check on `on github`.
 
 Record `arc-mode: direct` or `arc-mode: checkout` on the Stop 1 write-back. `evaluateDirectDispatch` is a fixture over parent-claimed actions, not a live occupancy observer.
 
@@ -254,8 +254,9 @@ Keep the arc in this contract until a verified synthesis is accepted.
 - ⊗ Print `accept` / `retry differences` / `walk` / `walk all` when no successor lean is posted for this round. An empty-lean verb menu is a contract miss.
 - ! The halt line remains postable while same-round siblings remain unposted. An unposted sibling with no dispatch-fail evidence is Dual stop envelope exhaustion.
 - ⊗ Auto-dispatch critics (#3578 / #1702).
-- ⊗ Hand the arc to `triage:accept` / `scope:promote` until the completed-arc record is present: `design-critique: synthesis accepted, because …` citing the accepted successor lean (and the verified-claims table when posted). Catalog chips (`design-critique:mechanism-shaped` / `design-critique:triage-ready`) are list-visible convenience, not clearance. A lone synthesis-accepted-shaped comment that does not cite an accepted lean does not unblock ingest.
+- ⊗ Hand the arc to `triage:accept` / `scope:promote` until the completed-arc record is present: `design-critique: synthesis accepted, because …` citing the accepted successor lean (and the verified-claims table when posted). Catalog chips (`design-critique:mechanism-shaped` / `design-critique:triage-ready` / `design-critique:recut-needed`) are list-visible convenience, not clearance. A lone synthesis-accepted-shaped comment that does not cite an accepted lean does not unblock ingest.
 - ⊗ Stamp `design-critique:triage-ready` at critic-post.
+- ⊗ Stamp `design-critique:recut-needed` at critic-post.
 - ⊗ Add a `design-critique:critic-posted` chip or any author/role chip.
 - ⊗ Critic writes issue labels.
 - ⊗ Add a #3607 thread interlock in this contract.
@@ -272,7 +273,9 @@ After this round's same-round siblings are posted, parent posts a successor `**L
 - ! Carry a per-heading take on the successor lean: `accept-into-contract` | `disagree` | `defer`. Defer is not accepted.
 - ! The successor lean is the disposition map. Do not post a third map type.
 - ! The first posted map is an ADR-006 arbitration surface. Record a substantiation token when takes introduce load-bearing premises. Non-self-arbitration applies when the same party authored the triage and the proposed takes.
-- ! Bind synthesis and `design-critique:triage-ready` to the latest successor lean, never a superseded write-back.
+- ! Bind synthesis and the auto-stamp catalog chip (`design-critique:triage-ready` or `design-critique:recut-needed`) to the latest successor lean, never a superseded write-back.
+- ! When the next-build contract is recut (not this body), stamp a Lean-family line-start `Recut:` on that successor lean. Nine spellings: zero to two asterisks counted independently on each side, the same wrapping as `Lean:`. Auto-stamp matches that token through `resolveAutoStampCatalogChip`. It does not parse lean English.
+- ⊗ Classify recut by NLP of the lean.
 - ! Full template (accepted set, residual, supersedes-id, ceiling if retrying) lives only on the successor lean and on a retry disagreement map.
 - ! Walk comments stay slim (model and role lines, Accept X, critic id, heading, decision, and when needed a token plus pointer).
 - ⊗ Edit the ceiling write-back in place.
@@ -322,15 +325,16 @@ The summary leads both artifacts under one fixed heading token: `## In plain Eng
 
 ### Reserved line-starts
 
-Comment bodies are parsed at runtime, so prose in them is not inert. Three predicates in `packages/core/src/design-critique/completed-arc-record.ts` classify a comment by a line-start anywhere in its body: the successor-lean token (`Lean:` with zero to two asterisks on each side, so nine spellings), the verified-claims-table heading, and the fixed accepted sentence. None of the three carries a position predicate, so a fence does not protect a quoted example the way `### Position predicate` protects a citation.
+Comment bodies are parsed at runtime, so prose in them is not inert. Four predicates in `packages/core/src/design-critique/completed-arc-record.ts` classify a comment by a line-start anywhere in its body: the successor-lean token (`Lean:` with zero to two asterisks on each side, so nine spellings), the verified-claims-table heading, the fixed accepted sentence, and `Target-digest:` (same nine spellings). The first three carry no position predicate, so a fence does not protect a quoted example the way `### Position predicate` protects a citation. `Target-digest:` uses `classifyPosition`; fence and quote do not count (#4243).
 
-The prohibition is per-artifact, and the asymmetry is the point. Re-measured at `764f63a6` against the built module, after #3932 and #3929 landed; this supersedes the `c6761881` measurement, which predated both:
+The prohibition is per-artifact, and the asymmetry is the point. Re-measured at `764f63a6` against the built module, after #3932 and #3929 landed; this supersedes the `c6761881` measurement, which predated both. `Target-digest:` is required on a new successor lean as the ingest pin, refused on synthesis, table, critic, and walk comments, and inert for classification when the comment is already lean-shaped:
 
 | Reserved line-start | In a successor lean | In a synthesis |
 | --- | --- | --- |
 | successor-lean token, all nine spellings | inert -- the comment already is the lean, so 0 of 9 changed a verdict | ⊗ -- the synthesis reclassifies as the newest lean; 9 of 9 flip a complete arc to blocked, and the operator can satisfy that error only by citing the comment against itself |
 | `## Verified-claims table` | ⊗ -- the lean stands in as the table on the untyped path: a synthesis naming its table with `comment <id>` or a permalink returns complete with the resolved id equal to the lean id, where the control resolves null. A silent misresolution rather than a visible block. A typed claim now blocks whether or not the lean carries the heading, so the silent half survives only where the synthesis does not type its table citation | ⊗ -- the synthesis reads as its own table |
 | the fixed accepted sentence | ⊗ -- the lean reclassifies as a synthesis and a complete arc flips to blocked. A fence does not help. A blockquote is undetected by this predicate but refused by `### Position predicate`, so no one quoting convention is safe for both parsers | required -- it is the record |
+| `Target-digest:` then `sha256:` and 64 lowercase hex | required on new successor leans as the ingest pin; inert for classification when `Lean:` is already present. Legacy leans with no digest stay admitted | ⊗ -- an operative line reclassifies the synthesis as a successor lean. Fence and quote do not count |
 
 The ghost-table half of the middle cell is the #3932 defect, repaired at `ba3d6a8f` and re-measured above. What this prohibition covers is the classification collision underneath it: the comment reads as an artifact kind it is not, whatever the resolver later does with that.
 
@@ -378,11 +382,12 @@ Contract stops stay internal. Parent prints these phrases when they apply. They
 **walk** iterates recorded parent-disagree headings (successor-lean take is `disagree`). **walk all** is the census of every classified finding in existing order (blocking then sharpening then footnotes — or the critic's numbering). For one release, `walk findings one at a time` is an alias of **walk all**. Short forms of accept synthesis are valid: `accept synt`, `synt accepted`, `synt approved`, `accept synthesis`, `synthesis accepted`, `synthesis approved`. Same idea for other printed verbs when the short form is unambiguous (`retry` for `retry differences`). If the operator types a bare word that could be either **walk** or **walk all** and only one was offered, map it to the offered one. If ambiguous, parent re-prints the offered phrases and waits.
 
 - ! Print the phrases when they apply. An empty-lean verb menu is a miss.
+- ! Host widgets print only the verbs that apply and MUST end the numbered list with Discuss then Back (#1470 / #1563). `operatorVerbApplySet` is the fixture.
 - ! Do not print **walk** until at least one proposed take on the posted lean is `disagree`.
 - ! Do not print **retry differences** until residual headings are named on that map.
 - ! Do not skip the first-lean offer because the draft is all-accept.
 - ! Non-empty disagree set: print **walk** / **walk all** / **retry differences** / **accept**. Walk is an option, not the only path. Do not auto-start the walk.
-- ! When the successor lean's per-heading map is total over a **non-empty** in-envelope classified-finding set, every heading is `accept-into-contract` (no `disagree`, no `defer`), AND zero unresolved audit markers, AND the operator has confirmed or amended that map, AND no unposted same-round siblings remain: parent auto-posts the verified-claims table as its own comment, then auto-posts `design-critique: synthesis accepted, because agents agreed (empty disagreement set)` and remaining-set-replaces the chip via `task scm:issue:design-critique-chip -- --issue N --chip triage-ready`. If that write misses, continue; do not halt. Do not print **accept synthesis**, **post the verified-claims table**, **walk**, or **walk all**.
+- ! When the successor lean's per-heading map is total over a **non-empty** in-envelope classified-finding set, every heading is `accept-into-contract` (no `disagree`, no `defer`), AND zero unresolved audit markers, AND the operator has confirmed or amended that map, AND no unposted same-round siblings remain: parent auto-posts the verified-claims table as its own comment, then auto-posts `design-critique: synthesis accepted, because agents agreed (empty disagreement set)` and remaining-set-replaces the chip via `task scm:issue:design-critique-chip -- --issue N --chip recut-needed` when `resolveAutoStampCatalogChip` matches a Lean-family `Recut:` line-start on the latest successor lean, else `--chip triage-ready`. If that write misses, continue; do not halt. Do not print **accept synthesis**, **post the verified-claims table**, **walk**, or **walk all**.
 - ⊗ Auto-stamp a parent-drafted all-accept map that the operator has not confirmed or amended.
 - ⊗ Auto-stamp while same-round siblings remain unposted.
 - ⊗ Auto-stamp when any audit marker is unresolved.
@@ -473,14 +478,14 @@ Two bind paths authorize:
 design-critique: synthesis accepted, because …
 ```
 
-1. #3640 auto-stamp: when the successor lean map is total over the auto-stamp denominator (critic posts in this arc, including Stop 4 retry output, plus still-open residual headings) and that set is non-empty and every heading is `accept-into-contract` AND zero unresolved audit markers AND the operator has confirmed or amended that map AND no unposted same-round siblings remain, parent posts `design-critique: synthesis accepted, because agents agreed (empty disagreement set)` and remaining-set-replaces the chip to `design-critique:triage-ready` via `task scm:issue:design-critique-chip -- --issue N --chip triage-ready`. If that write misses, continue; do not halt. Do not print **accept synthesis**. Do not auto-stamp on a partial map, an unconfirmed parent draft, or when any audit marker is unresolved, or while same-round siblings remain unposted.
-2. Explicit operator **accept synthesis** (or a listed short form), subject to the two non-empty refusals below. Parent may post that line and cite the verb. Then apply `design-critique:triage-ready` as the exclusive catalog chip via remaining-set write. If that write misses, continue; do not halt.
+1. #3640 auto-stamp: when the successor lean map is total over the auto-stamp denominator (critic posts in this arc, including Stop 4 retry output, plus still-open residual headings) and that set is non-empty and every heading is `accept-into-contract` AND zero unresolved audit markers AND the operator has confirmed or amended that map AND no unposted same-round siblings remain, parent posts `design-critique: synthesis accepted, because agents agreed (empty disagreement set)` and remaining-set-replaces the chip via `task scm:issue:design-critique-chip -- --issue N --chip recut-needed` when `resolveAutoStampCatalogChip` matches a Lean-family `Recut:` line-start on the latest successor lean, else `--chip triage-ready`. If that write misses, continue; do not halt. Do not print **accept synthesis**. Do not auto-stamp on a partial map, an unconfirmed parent draft, or when any audit marker is unresolved, or while same-round siblings remain unposted.
+2. Explicit operator **accept synthesis** (or a listed short form), subject to the two non-empty refusals below. Parent may post that line and cite the verb. Then apply the exclusive catalog chip `resolveAutoStampCatalogChip` selects (`design-critique:recut-needed` or `design-critique:triage-ready`) via remaining-set write. If that write misses, continue; do not halt.
 
-Closed catalog (last chip wins): `design-critique:mechanism-shaped` (in-flight, gate match) and `design-critique:triage-ready` (bound). No halt chip.
+Closed catalog (last chip wins): `design-critique:mechanism-shaped` (in-flight, gate match), `design-critique:triage-ready` (bound implement), and `design-critique:recut-needed` (bound recut / not this body). No halt chip. `CHIP_ALIASES` in `packages/core/src/scm/design-critique-chip.ts` is the same three names. Unknown `--chip` fails closed.
 
 - ⊗ Bind path 2 when the critic posts zero classified headings (stub / blank). The same refusal path 1 carries at Operator verbs. Stop and inform. Do not stamp.
 - ⊗ Bind path 2 on a footnote-only census. A footnote-only post is a valid census and is not a stub, but denominator set (a) is empty, so it carries no bind at either path.
-- ! Exclusive replace is one merged remaining-set write: GET current labels, drop the other catalog names (`design-critique:mechanism-shaped` and `design-critique:triage-ready`), PUT/PATCH that list with the new chip. Other facets stay. Parent write path: `task scm:issue:design-critique-chip -- --issue N --chip triage-ready|mechanism-shaped [--repo OWNER/NAME]` (`deft scm issue design-critique-chip` dual-invoke). The verb GET-drops via `applyDesignCritiqueCatalogChip` / `designCritiqueChipApplyDelta` and one `ScmLabelClient.apply`. Inventory: `LabelClient.apply` / `mergeIssueLabels`.
+- ! Exclusive replace is one merged remaining-set write: GET current labels, drop the other catalog names (`design-critique:mechanism-shaped`, `design-critique:triage-ready`, and `design-critique:recut-needed`), PUT/PATCH that list with the new chip. Other facets stay. Parent write path: `task scm:issue:design-critique-chip -- --issue N --chip triage-ready|mechanism-shaped|recut-needed [--repo OWNER/NAME]` (`deft scm issue design-critique-chip` dual-invoke). The verb GET-drops via `applyDesignCritiqueCatalogChip` / `designCritiqueChipApplyDelta` and one `ScmLabelClient.apply`. Inventory: `LabelClient.apply` / `mergeIssueLabels`.
 - ⊗ `gh api POST .../labels` or additive `scm:issue:edit --add-label` for this facet.
 - ⊗ Intercept mixed `scm issue edit` adds/removes for this facet.
 - ⊗ General-purpose labels CLI.
@@ -493,16 +498,18 @@ Closed catalog (last chip wins): `design-critique:mechanism-shaped` (in-flight,
 - ⊗ Put a set-level graph (dominate / split / corpus parsed from comment English) inside ingest.
 - ! Ingest clearance cites the latest successor lean. An older completed-arc record does not clear a later recut lean. A panel-deposit is in-flight even when the catalog chip missed and no critic has posted.
 - ! The lexical form of that citation, and the requirement that the occurrence be affirmative, are published in `## Citation grammar`. Ingest reads that grammar, not prose intent.
-- ! Keep `plan.policy.judgmentGates` matching only `design-critique:mechanism-shaped`. After `triage-ready` replaces it, the issue leaves the gate match.
+- ! Keep `plan.policy.judgmentGates` matching only `design-critique:mechanism-shaped`. After `triage-ready` or `recut-needed` replaces it, the issue leaves the gate match.
 - ! Chip is list-visible state, not consent. Do not drop `mechanism-shaped` without the synthesis-accepted line (or the #3640 empty-disagreement path).
 - ⊗ Treat `design-critique:triage-ready` as ingest clearance.
+- ⊗ Treat `design-critique:recut-needed` as ingest clearance or as a halt chip.
 - ! Chip apply miss is non-blocking convenience. Do not invent a 403 HTTP parser. Any apply miss is the same miss. Do not use the halt line. Do not block ingest. Optional later remaining-set by a write-capable identity is hygiene.
 - ! Leftover `design-critique:mechanism-shaped` after a chip apply miss does not block ingest. `judgmentGates` match is advisory/observe.
 - ⊗ Use the halt line for a chip apply miss.
 - ! Write-back `mechanism-shaped: true` is history after replace. Current-state authority is the last catalog chip.
-- ! Recut (new lean) applies `design-critique:mechanism-shaped` with the same remaining-set write and drops `triage-ready`.
+- ! Recut (new lean) applies `design-critique:mechanism-shaped` with the same remaining-set write and drops `triage-ready` and `recut-needed`.
 - ~ A live `design-critique:*` count!=1 check is SHOULD, not a new `judgmentGates` match.
 - ⊗ Add `design-critique:triage-ready` to `judgmentGates` labels.any-of.
+- ⊗ Add `design-critique:recut-needed` to `judgmentGates` labels.any-of.
 - ⊗ Infer consent from looks-good.
 - ⊗ DELETE-then-POST the chip (unchipped window if POST fails).
 - ⊗ PUT a naive full wipe of every label.
@@ -560,7 +567,7 @@ The intake cross-ref scanners (`packages/core/src/intake/markdown-scanners.ts`)
 - ! Clearance is set membership: the record clears when the cited set contains the latest successor lean id. Position in the body does not select the lean, so citing the prior lean that `## Successor lean` requires cannot block.
 - ! A block detail reports what was scanned, what was found, and the accepted forms. ⊗ Guess at a cause. A guessed detail sends the operator back to re-post the same body and reproduce the refusal.
 
-`CompletedArcBlockReason` is closed. A block detail names one of these eight:
+`CompletedArcBlockReason` is closed. A block detail names one of these nine:
 
 | Reason | What it reports |
 | --- | --- |
@@ -572,6 +579,7 @@ The intake cross-ref scanners (`packages/core/src/intake/markdown-scanners.ts`)
 | `ambiguous-table-cite` | two typed table claims name different tables |
 | `cancelled` | `design-critique: cancelled, because ...` is the latest terminal record; no later successor lean |
 | `unrecut-body` | completed-arc is present and the latest `target shape:` field is `set-level` |
+| `stale-target` | cited successor lean carries `Target-digest:` and the live REST issue body hash does not match; nothing written. Legacy leans with no digest stay admitted. Recut-without-digest stays on #4237 |
 
 - ! Publish a reason in that table before the evaluator returns it. An unpublished reason code is the same gap as an unpublished citation form.
 - ⊗ Merge two states under one reason when their remedies differ. `missing-table-cite` and `unshaped-table-cite` were one reason and one detail until #3942, and the shared detail asserted an absent id in both, so an author whose table was on the thread read a true citation being called false and had no path to the missing heading.
@@ -593,4 +601,4 @@ This motion ingests untrusted issue threads by design.
 
 ## Test surface
 
-`packages/core/src/content-contracts/standards/design_critique_contract.test.ts` locks required pointer strings, the scaffolds framing, the comment-lead field as model then role from the closed set (not an issue label), the operator-gated loop (successor lean, operator verbs including walk / walk all, dual stop, halt line, exclusive remaining-set replace of the two catalog chips, #3640 auto-stamp on a non-empty all-accept map and no-stamp on stubs, first-lean recording obligation after this round's siblings are posted), the parent-side substantiation token and independence rules, the Stop 1 exclusion (pre-critic premises outside the trigger) and `refutation-target:` field tokens rather than full body sentences, the composed auto-bind conjunct (all-accept map AND zero unresolved audit markers) at Operator verbs and Bind path 1, the variant-table evaluation rule (charter selection and spend permission evaluated independently), the critic-method heading and distinctive obligation tokens (exact class tokens, citations-are-claims, existing mechanisms, injection / swarm trigger nouns, failed-reviewer phrase, finding anatomy) rather than full body sentences, the brief-template forbidden-inputs list, and the thin router skill (existence, line cap, pointer resolution, no-normative-content). `evaluateParentAudit` locks the omission failure modes. This suite locks the SoT MUST and the thin skill pointer for the first-lean recording obligation, including the auto-stamp operator-confirm conjunct and the no-bind-while-unposted-same-round-siblings rule. `evaluateCompletedArcRecord` locks ingest on the completed-arc record rather than a catalog chip. It does not fail-close live parent turns. `packages/core/src/design-critique/citation-grammar.test.ts` locks the `## Citation grammar` closed set, the refused positions, and the diagnostics surface; `packages/core/src/design-critique/completed-arc-record.test.ts` locks one parser for both questions, set membership against the latest lean, and the observation-echoing block details (#3831). Runtime parent-turn detection only if `evaluateParentAudit` is extended; that extension is not required to ship the recording obligation. Panel completeness is locked as contract text only. No predicate observes it on a live arc (#3850). `evaluatePanelSeatComposition` locks claimed-family composition and PATH paste-ready-first; it is a fixture over claimed families, not a live sibling-count gate. `### The arc` and its derived boundaries, the `### Target shape` axis with its twice-run caveat, and the two bind-path-2 non-empty refusals are locked as contract text (#3797). `## Plain-language summary` is locked the same way: the contract test pins the heading token, the MUST-not-SHOULD reasoning, the ADR-006 exemption and its limit, the non-normative marking, and the per-artifact reserved line-start matrix, and `packages/core/src/design-critique/reserved-line-starts.test.ts` exercises each of the three families on each artifact kind against the exported shape predicates and `evaluateCompletedArcRecord`. No predicate observes a summary on a live arc (#3929). `### Verified-claims table heading`, the closed reason vocabulary, and the re-measured line-start matrix are locked as contract text, and `completed-arc-record.test.ts` exercises the typed refusal partition: the two states, details that differ by more than the id, the untyped null table id, and the seven recorded live arc table ids (#3942). `### Run posture` and `parseOperatorRunPosture` / `evaluateDirectDispatch` lock the closed-token front door, the missing-token ask including yolo, the `session:start --read-only` start verb, stdin posting, SHA-pinned reads, and the no-worktree direct panel; `run-posture.test.ts` exercises those fixtures. `evaluateCompletedArcRecord` ignores `arc-mode:` (#4072).
+`packages/core/src/content-contracts/standards/design_critique_contract.test.ts` locks required pointer strings, the scaffolds framing, the comment-lead field as model then role from the closed set (not an issue label), the operator-gated loop (successor lean, operator verbs including walk / walk all, dual stop, halt line, exclusive remaining-set replace of the three catalog chips, #3640 auto-stamp on a non-empty all-accept map and no-stamp on stubs, first-lean recording obligation after this round's siblings are posted), the parent-side substantiation token and independence rules, the Stop 1 exclusion (pre-critic premises outside the trigger) and `refutation-target:` field tokens rather than full body sentences, the composed auto-bind conjunct (all-accept map AND zero unresolved audit markers) at Operator verbs and Bind path 1, the variant-table evaluation rule (charter selection and spend permission evaluated independently), the critic-method heading and distinctive obligation tokens (exact class tokens, citations-are-claims, existing mechanisms, injection / swarm trigger nouns, failed-reviewer phrase, finding anatomy) rather than full body sentences, the brief-template forbidden-inputs list, and the thin router skill (existence, line cap, pointer resolution, no-normative-content). `evaluateParentAudit` locks the omission failure modes. This suite locks the SoT MUST and the thin skill pointer for the first-lean recording obligation, including the auto-stamp operator-confirm conjunct and the no-bind-while-unposted-same-round-siblings rule. `evaluateCompletedArcRecord` locks ingest on the completed-arc record rather than a catalog chip. It does not fail-close live parent turns. `packages/core/src/design-critique/citation-grammar.test.ts` locks the `## Citation grammar` closed set, the refused positions, and the diagnostics surface; `packages/core/src/design-critique/completed-arc-record.test.ts` locks one parser for both questions, set membership against the latest lean, and the observation-echoing block details (#3831). Runtime parent-turn detection only if `evaluateParentAudit` is extended; that extension is not required to ship the recording obligation. Panel completeness is locked as contract text only. No predicate observes it on a live arc (#3850). `evaluatePanelSeatComposition` locks claimed-family composition and PATH paste-ready-first; it is a fixture over claimed families, not a live sibling-count gate. `### The arc` and its derived boundaries, the `### Target shape` axis with its twice-run caveat, and the two bind-path-2 non-empty refusals are locked as contract text (#3797). `## Plain-language summary` is locked the same way: the contract test pins the heading token, the MUST-not-SHOULD reasoning, the ADR-006 exemption and its limit, the non-normative marking, and the per-artifact reserved line-start matrix, and `packages/core/src/design-critique/reserved-line-starts.test.ts` exercises each of the four families on each artifact kind against the exported shape predicates and `evaluateCompletedArcRecord`. No predicate observes a summary on a live arc (#3929). `### Verified-claims table heading`, the closed reason vocabulary, and the re-measured line-start matrix are locked as contract text, and `completed-arc-record.test.ts` exercises the typed refusal partition: the two states, details that differ by more than the id, the untyped null table id, and the seven recorded live arc table ids (#3942). `### Run posture` and `parseOperatorRunPosture` / `evaluateDirectDispatch` lock the closed-token front door, the missing-token ask including yolo, the `session:start --read-only` start verb, stdin posting, SHA-pinned reads, and the no-worktree direct panel; `run-posture.test.ts` exercises those fixtures. `evaluateCompletedArcRecord` ignores `arc-mode:` (#4072).

package/docs/SUPPORT.md

@@ -0,0 +1,43 @@
+# Support and troubleshooting
+
+This page is a **symptom index**. It is not a second recovery ladder.
+
+- If `directive` (or the `deft` alias) will not start, use the [README cold-start](https://github.com/deftai/directive/blob/master/README.md). That committed block is the only payload-independent command ladder.
+- If the CLI runs, start with `directive doctor --full`. Follow its one `Next command:`. Do not pick a competing command from this page.
+
+Doctor caches a clean run for 24 hours and a dirty run for 4 hours. `--full` bypasses that throttle.
+
+Specialist pages below are pointers. Recovery command bytes stay in doctor and the README cold-start.
+
+## Symptom index
+
+| Symptom | Safe diagnostic | Specialist link |
+| --- | --- | --- |
+| PATH / package manager (`command not found`, missing pnpm bin) | Pre-CLI: README cold-start. If the CLI runs: `directive doctor --full` | Follow `Next command:` or the README cold-start rungs |
+| Node missing or too old | Pre-CLI: README cold-start. If the CLI runs: `directive doctor --full` | README cold-start, then doctor |
+| Stale deposit | `directive doctor --full` | Follow `Next command:` |
+| Permissions / unwritable global prefix | Pre-CLI: README cold-start. If the CLI runs: `directive doctor --full` | README cold-start sandbox rung, or doctor |
+| Windows shims | Pre-CLI: README cold-start. If the CLI runs: `directive doctor --full` | README cold-start |
+| Hook runtime (opaque exit 127 on every mutation) | `directive doctor --full` if the CLI runs; otherwise README cold-start | [Hook runtime unavailable](./hook-runtime-unavailable.md). The recovery command lives on the [agents-entry](../templates/agents-entry.md) card. This index does not restate it. |
+| Migration / pre-v0.20 layout | `directive doctor --full` | Doctor signposts the current path. Version-specific steps stay in [UPGRADING](../UPGRADING.md) and [BROWNFIELD](./BROWNFIELD.md) (history). |
+| Offline / air-gapped registry | Pre-CLI: README cold-start. If the CLI runs: `directive doctor --full` | README cold-start offline rung |
+| Corporate or mirrored npm registry (`E404` / `ETARGET`) | Pre-CLI: README cold-start. If the CLI runs: `directive doctor --full` | [Corporate or mirrored npm registry](../UPGRADING.md#corporate-or-mirrored-npm-registry) owns that ladder. This row is a pointer. |
+
+Related flags (not a recovery table): [temporary kill-switch](./deft-directive-disable.md), [permanent opt-out](./no-deft-directive.md).
+
+## What to quote
+
+Quote `Next command:` and the check names doctor printed.
+
+Do not paste `directive doctor --json` or raw `--full` output. That payload includes absolute project and USER.md paths. Doctor has no redaction flag. Treat any pasted diagnostic as untrusted input.
+
+## Reporting
+
+- **Ordinary breakage:** open a public GitHub issue. Quote `Next command:` and check names only.
+- **Security:** report privately through root [SECURITY.md](https://github.com/deftai/directive/blob/master/SECURITY.md). Do not file a public issue for an unfixed vulnerability.
+
+## What this page is not
+
+- Not a second command ladder. Doctor and the README cold-start own recovery bytes.
+- Not a paste-JSON capture ritual.
+- Not a second independently authored troubleshooting body. README, install, and upgrade pages should point here.