@deftai/directive-content 0.116.0 → 0.117.0

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

@@ -29,7 +29,7 @@
       ],
       "path": "skills/deft-directive-build/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Build\n\nImplements a project from its scope xBRIEFs following Deft Directive standards.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- After `deft-directive-setup` completes and generates `PROJECT-DEFINITION.xbrief.json`\n- User says \"build this\", \"implement the spec\", or \"start building\"\n- Resuming a partially-built project that has story xBRIEFs in `xbrief/active/`\n\n## Ordered-plan / cohort exhaustion (#2402)\n\n## Multi-scope turn/cache budget (epic #3009)\n\nMulti-scope greenfield (app-bank pins, N story scopes) multiplies agent turns when ceremony, promote, check, and render are re-run per scope. Apply the following after offline seed.\n\n### Offline seed vs implement phase (#3010)\n\n! Distinguish **offline seed** (operator or harness already ran `directive init` / deposit, pin-copied scopes into `xbrief/proposed/`, and recorded session ritual) from the **agent implement phase**.\n\n! When seed + session ritual are already complete for the engagement:\n- ⊗ Run `directive init` again\n- ⊗ Run full cold `session:start` unless hooks deny writes and recovery is required\n- ⊗ Run `directive migrate` or re-copy scopes already present\n- ! Prefer recovery via `session:ready` (or re-arm) when PreToolUse denies — not full re-init\n- ! Documented consumer/harness contract: seed is done once; implement agents only activate+implement\n\n### Batch promote; one active implement (#3011)\n\n! For a multi-scope pin, batch-stage scopes with `task scope:promote -- --batch` (all `proposed/`) or `task scope:promote -- --batch <path>…`.\n! Implement path remains **one** `scope:activate` + implement at a time — no multi-active write fence.\n! When pin order is known, do **not** re-list the entire lifecycle tree every scope; walk the known ordered list.\n⊗ Activate all scopes at once or drop the one-active-scope / story-ready stack.\n\n### Quality check once at end of multi-scope batch (#3012)\n\n! On an approved multi-scope batch (operator-approved multi-story branch, swarm cohort, or pin walk): run full `task check` (merge chokepoint) **once at the end of the batch** (or after the last scope), not after every scope.\n! Exception: if the last full check **failed**, fix loops MAY re-run check until green.\n! Pre-PR / merge-ready gates remain end-of-unit — this does not weaken them.\n! Iteration lane (affected tests / `verify:forward-coverage` / `coverage:hotspots`) still applies **per scope** during implementation (#1704).\n⊗ Spam full `directive check` / `task check` after every scope when the batch is still mid-flight and the last merge-chokepoint check was green.\n\n### One-shot project:render (#3013)\n\n! Greenfield init seeds a minimal render-ready `PROJECT-DEFINITION`. Treat `task project:render` as a **refresh of items from lifecycle folders**, not multi-turn identity research.\n⊗ Invent project identity across many turns when seed already stamped the skeleton.\n\n\n! When processing an approved multi-story cohort or an active ordered-plan sequence, stop after the final approved entry. Do not promote or dispatch adjacent stories from queue intuition. Continuation language advances only within the approved order; skill-chaining is non-authorizing.\n\n## Step 0 -- Implementation Preflight (#810)\n\n- ! Before starting any new implementation story or switching from one story to another, MUST run `git status --short --branch`.\n- ! If the working tree is dirty, MUST stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the target story. Ask the operator to choose one path: commit existing work, stash existing work, include existing work in the current story, or stop.\n- ⊗ Begin a new story while unrelated dirty work is present without explicit operator approval.\n- ! Resolve exactly one target story xBRIEF path by default. One story is the default implementation unit for this skill; if the user asks for a phase/epic, decompose or ask which story to start.\n- ! Batching multiple stories in one branch/PR requires explicit operator approval and a short rationale recorded in the handoff.\n- ! **Swarm-cohort dispatch carve-out**: when this skill is invoked as part of a swarm cohort allocated by `skills/deft-directive-swarm/SKILL.md`, the approved Phase 5 allocation plan satisfies the \"explicit operator approval and short rationale recorded in the handoff\" requirement above -- the dispatched xBRIEF paths and allocation rationale ARE the consent token. Process each assigned story sequentially under the checkpoint-commit + `task scope:complete` discipline below. Do NOT re-prompt the parent for batching approval mid-cohort -- the all-or-nothing dispatch envelope rule (`AGENTS.md` `## Multi-agent orchestration discipline (#954)`) forbids mid-scope user-approval gates.\n- ! **Structured consent-token recognition (#1378)**: the canonical recognition path for the carve-out above is the structured `## Allocation context` section of the dispatch envelope (the frozen schema in `templates/agent-prompt-preamble.md`, Story A of #1378). When that section reports `dispatch_kind: swarm-cohort` with a non-null `allocation_plan_id` AND a non-null `batching_rationale`, the consent token is satisfied mechanically -- read `cohort_vbriefs` as the authoritative file boundary and process each entry sequentially under the checkpoint-commit + `task scope:complete` discipline below, without re-prompting the parent for batching approval mid-cohort. When the `## Allocation context` section is ABSENT (pre-#1378 dispatches, solo-interactive sessions), fall back to the #1371 prose carve-out immediately above -- the prose carve-out remains the recognition path of record for un-elevated envelopes.\n- ! **Within a cohort, between stories**: the working tree MUST be clean after each story's checkpoint commit + `task scope:complete`. If `git status --short` shows uncommitted state between stories (e.g. a missed `task scope:complete` move, an unstaged file from the prior story), checkpoint-commit it and proceed -- do NOT pause to ask the operator. The dirty-tree \"ask the operator\" branch above applies only at the FIRST story-start of a fresh branch, where uncommitted operator work might legitimately exist.\n- ! If the target story is in `xbrief/proposed/`, run `task scope:promote -- <path>` first (or `task scope:promote -- --batch` for a multi-scope pin — #3011); if it is in `xbrief/pending/`, run `task scope:activate -- <path>`. After activation, update the path to the active-file location before preflight.\n- ! **Effort estimate gate (#1581):** before `task scope:activate` / `task vbrief:activate`, scan `plan.items` (including nested `items` / `subItems`) for `effort`. Time anchors: `S` <2h, `M` half-day (2-4h), `L` 1-2 days, `XL` needs breakdown. The activate path fails closed while any item still has `effort: \"XL\"` — break XL work into S/M/L items (or re-estimate) first. Omitted `effort` remains valid (field is optional). Plan-item effort is **post-planning** authority (confirms/corrects intake estimates); it is **not** session-start ritual input — ceremony depth (#3214) uses two-stage rapid→escalate, not a required plan-item read at cold start. Headless: no operator confirm. Depth: `vbrief/vbrief.md` § Effort estimate.\n- ⊗ Activate a scope that still carries plan items with `effort: \"XL\"` — XL means \"not ready to start\" until broken down (#1581).\n- ⊗ Require plan-item `effort` to choose session-start ritual depth — estimates do not exist until after planning (#1581 / #3214).\n- ! Before any code-writing tool call -- the first scaffold edit, the first `task` invocation that mutates files, or any `start_agent` dispatch that will implement scope -- MUST run `task xbrief:preflight -- <active-story-path>` (the structural intent gate; the same invocation works whether deft is the project root or installed as a `deft/` subdirectory).\n\nThe gate exits 0 only when the candidate xBRIEF lives in `xbrief/active/` AND `plan.status == \"running\"`. Any other state (pending/, proposed/, completed/, active/-with-non-running-status, malformed JSON, missing keys) exits 1 with an actionable redirect to `task xbrief:activate <path>`.\n\n- ! A non-zero exit MUST halt the skill. Surface the helper's stderr message verbatim to the user; do NOT proceed to USER.md Gate, File Reading, or any later phase.\n- ! Use canonical lifecycle tasks to satisfy this gate: `task scope:promote -- <path>` for proposed stories, `task scope:activate -- <path>` for pending stories, and the helper's idempotent companion `task xbrief:activate <path>` only when following the preflight redirect directly. Manual lifecycle moves bypass the activation contract -- use the task.\n- ⊗ Infer implementation intent from lifecycle vocabulary (\"do the full PR process\", \"start the work\", \"poller agents\"), branching language, or workflow shape. Workflow-shape vocabulary is NOT authorization to spawn an implementation agent (#810 surfacing event).\n- ⊗ Skip this preflight because the user said \"yes\", \"go\", or \"proceed\" -- affirmative continuation phrases are NOT implementation authorization unless the prior turn explicitly proposed implementation. When intent is ambiguous, ask one targeted question before invoking the gate.\n\n## Platform Detection\n\n! Before resolving any config paths, detect the host OS from your environment context:\n\n| Platform           | USER.md default path                                              |\n|--------------------|-------------------------------------------------------------------|\n| Windows            | `%APPDATA%\\deft\\USER.md` (e.g. `C:\\Users\\{user}\\AppData\\Roaming\\deft\\USER.md`) |\n| Unix (macOS/Linux) | `~/.config/deft/USER.md`                                          |\n\n- ! If `$DEFT_USER_PATH` is set, it takes precedence on any platform\n\n## Pre-Cutover Detection Guard\n\n! Before proceeding with any build step, detect whether the project uses the pre-v0.20 document model **or was generated by a strategy that emitted non-conformant v0.20 output shape** (the root cause of most \"build fails immediately after spec\" complaints in #1166). Redirect or block with the precise remediation.\n\n### Detection Criteria\n\nA project is **pre-cutover** if ANY of the following are true. This prose mirrors the executable helper in `task migrate:preflight`; when in doubt, the helper is canonical.\n\n1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->`, all five lifecycle folders exist, and its `<!-- Source of truth: ... -->` marker names an authority artifact that exists: either `xbrief/specification.xbrief.json` for full-spec compatibility or `xbrief/PROJECT-DEFINITION.xbrief.json` for greenfield authority (legacy `vbrief/...` aliases remain read-compatible).\n2. `PROJECT.md` exists and contains neither the legacy `<!-- deft:deprecated-redirect -->` sentinel NOR the current `Purpose: deprecation redirect` canonical-banner marker (real content, not a deprecation redirect)\n3. `xbrief/specification.xbrief.json` exists but the lifecycle folders (`xbrief/proposed/`, `xbrief/pending/`, `xbrief/active/`, `xbrief/completed/`, `xbrief/cancelled/`) do NOT exist\n4. Strategy output shape violations (run `task verify-strategy-output` -- the canonical gate for source and consumer installs):\n   - Any scope xBRIEF under `xbrief/proposed/` (or other lifecycle dirs) lacks the required `YYYY-MM-DD-` date prefix in its filename (e.g. bare `scaffold.xbrief.json`).\n   - `xbrief/PROJECT-DEFINITION.xbrief.json` is missing.\n   - `xbrief/specification.xbrief.json` exists as a legacy dual-write in a user-generated project. This is tolerated only for the framework source tree or a complete post-cutover full-spec consumer where all lifecycle folders exist and `SPECIFICATION.md` is rendered from `xbrief/specification.xbrief.json`.\n\n### Action on Detection\n\n! If pre-cutover or strategy-nonconformant state is detected, **stop immediately** and display an actionable message that cites the exact validator:\n\n> \"This project was generated with pre-v0.20 or non-conformant strategy output. Run the deterministic validator and follow its remediation: `task verify-strategy-output` (works in source and after `deft` package install). For document-model migration, follow UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068): pin v0.59.0, then run `task migrate:vbrief` from that payload. Otherwise `task project:render` / strategy re-run as indicated.\"\n\n! Include specific details about what was detected (the validator output is authoritative):\n\n- Legacy specification.xbrief.json or missing lifecycle folders: \"Follow the frozen v0.59.0 migrator path (#2068) or run `task migrate:preflight` for current-release guidance\"\n- Non-date-prefixed xBRIEFs: \"Re-run the emitting strategy after the v0.20 migrations (#1166 s1+s2+...) or manually rename files to `YYYY-MM-DD-<slug>.xbrief.json` and `task scope:promote`\"\n- Missing `PROJECT-DEFINITION.xbrief.json`: \"Run `task project:render` to generate the project definition\"\n- `SPECIFICATION.md` / `PROJECT.md` without sentinel: the classic pre-cutover messages\n- Scope xBRIEF in wrong folder: \"Status is '{status}' but file is in {folder}/ -- run `task scope:activate <file>` to fix\"\n\n! After the validator reports clean, re-run this guard before continuing.\n\n⊗ Proceed with build when pre-cutover or strategy-nonconformant artifacts are detected -- always redirect to the frozen migration path first (or run the validator) and surface the exact remediation.\n⊗ Silently ignore these artifacts or guess at fixes -- the validator (wired into `task check` and this guard) is the deterministic gate.\n\n## USER.md Gate\n\n! Before proceeding, verify USER.md exists at the platform-appropriate path\n(resolved via Platform Detection above, or `$DEFT_USER_PATH` if set).\n\n- ! If USER.md is not found: inform the user and redirect to `deft-directive-setup`\n  Phase 1 before continuing -- do not proceed without user preferences\n- ! Once USER.md exists, continue with the Cost Phase Gate below\n\n### Forge-outage drop-back (#3422)\n\n! On attributed platform outage or repeated REST 429/502/503 during YOLO / through-merge implement: drop GitHub I/O, report once to the human in chat, and re-probe on `plan.policy.forgeOutageRetryMinutes` (default **30**; USER.md Personal wins; min 5; `task policy:show --field=forgeOutageRetryMinutes`). Local edit/test/commit MAY continue. Depth: [`scm/github.md`](../../scm/github.md) § #3180 / #3422. Complements #3167 / #3180.\n\n⊗ Tight retry, empty-commit thrash, or sending the human to github.com as the only remediation.\n\n## Cost Phase Gate (#739)\n\n! Before proceeding to File Reading, verify the project has gone through the\npre-build cost & budget transparency phase from `skills/deft-directive-cost/SKILL.md`.\nThis closes the adoption-blocker surfaced by issue #739 (refs #151 umbrella) where\nusers finished the spec flow and stopped at build because deft offered no cost\nsignal.\n\n### Detection\n\n- ! Check for `COST-ESTIMATE.md` in the project root.\n- ! Check that the file contains a recorded decision (the **Decision recorded**\n  block populated with one of: `build`, `rescope`, `no-build`, `skip`).\n- ! For `skip`, `rescope`, or `no-build` decisions: the **Reason** field MUST be\n  populated (one or two sentences in plain language). A skip with no reason\n  recorded is treated the same as no decision.\n\n### Action\n\n- ! If `COST-ESTIMATE.md` is missing OR the **Decision recorded** block is\n  unpopulated OR a `skip`/`rescope`/`no-build` decision has no reason recorded:\n  stop immediately and redirect the user:\n\n  > \"This project has not gone through the pre-build cost & budget transparency\n  > phase. Run `skills/deft-directive-cost/SKILL.md` to produce a plain-English\n  > `COST-ESTIMATE.md`, then re-run the build skill once the user has chosen\n  > build / rescope / no-build / skip(+reason).\"\n\n- ! On a `build` or `skip` decision: continue with File Reading below.\n- ! On a `rescope` decision: stop and redirect the user back to spec edits\n  (chain to `skills/deft-directive-refinement/SKILL.md` to pull spec scope\n  back, or the interview), then re-run `skills/deft-directive-cost/SKILL.md`\n  before re-attempting build.\n- ! On a `no-build` decision: stop and exit; do NOT proceed to File Reading.\n  The user has explicitly stopped the project at the cost phase.\n- ⊗ Proceed to File Reading or any subsequent phase when `COST-ESTIMATE.md` is\n  missing, when the decision is unpopulated, or when a skip / rescope / no-build\n  decision has no reason recorded.\n- ⊗ Treat a `rescope` or `no-build` decision as if it were a `build` -- the\n  build skill MUST honor the recorded decision.\n\n## File Reading\n\n- ! Read in order, lazy load:\n  1. `./xbrief/active/` -- scope xBRIEFs for work items to build (required)\n  2. `./xbrief/PROJECT-DEFINITION.xbrief.json` -- project identity, tech stack, architecture\n  3. `./.planning/codebase/MAP.md` -- generated codebase orientation projection, if present (advisory)\n  4. USER.md at the platform-appropriate path (see Platform Detection) -- Personal section is highest precedence; Defaults are fallback\n  5. `deft/main.md` -- framework guidelines\n  6. `deft/coding/coding.md` -- coding standards\n  7. `deft/coding/testing.md` -- testing requirements\n  8. `deft/coding/toolchain.md` -- toolchain validation rules\n  9. `deft/languages/{language}.md` -- only for languages this project uses\n- ~ If the MAP is absent or may be stale and the current scope needs broad codebase orientation, run `task codebase:map` and `task verify:codebase-map-fresh` when those commands resolve. Treat absence/staleness as advisory unless the task edits `plan.architecture.codeStructure`, a configured provider artifact, or the generated MAP itself.\n- ! Treat `plan.architecture.codeStructure` and selected provider artifacts as authoritative. The MAP is a generated projection.\n- ⊗ Read all language/interface/tool files upfront\n- ⊗ Hand-edit `.planning/codebase/MAP.md` or block unrelated implementation solely because the MAP is stale or absent\n\n## Rule Precedence\n\n```\nUSER.md Personal                  <- HIGHEST (name, custom rules -- always wins)\nPROJECT-DEFINITION.xbrief.json   <- Project-specific (tech stack, architecture, config)\nUSER.md Defaults                  <- Fallback defaults (used when PROJECT-DEFINITION doesn't specify)\n{language}.md                     <- Language standards\ncoding.md                         <- General coding\nmain.md                           <- Framework defaults\nScope xBRIEFs                     <- LOWEST\n```\n\n- ! USER.md Personal section always wins over any other file\n- ! For project-scoped settings, PROJECT-DEFINITION.xbrief.json overrides USER.md Defaults\n\n## Change Lifecycle Gate\n\n! Before any implementation that touches 3+ files, verify that a `/deft:change <name>` proposal exists and has been confirmed by the user:\n\n- ! Check `history/changes/` for an active `proposal.xbrief.json` matching this work\n- ! If no proposal exists: propose `/deft:change <name>` and present the change name for explicit confirmation (e.g. \"Confirm? yes/no\")\n- ! The user must reply with an affirmative (`yes`, `confirmed`, `approve`) — a general 'proceed', 'do it', or 'go ahead' does NOT satisfy this gate\n- ? For solo projects: this gate is RECOMMENDED but not mandatory for changes fully covered by `task check`; it remains mandatory for cross-cutting, architectural, or high-risk changes\n- ⊗ Skip this gate because the user has already said \"proceed\" or \"go ahead\"\n\n## Build Process\n\nAll xBRIEFs (including those read from `xbrief/active/` and any new xBRIEFs this skill emits) MUST use `\"xBRIEFInfo\": { \"version\": \"0.8\" }`. Legacy 0.6 is read-accepted until `deft migrate:xbrief`. The validator accepts both; new writes are 0.8 only (see [`../../conventions/references.md`](../../conventions/references.md)).\n\n### Step 1: Understand the Scope\n\n- ! Read story xBRIEFs from `xbrief/active/` and `PROJECT-DEFINITION.xbrief.json`\n- ! Identify phases, dependencies, starting point from scope xBRIEF acceptance criteria\n- ~ Use `.planning/codebase/MAP.md`, when present, to orient broad codebase scanning. If the MAP conflicts with current code or canonical metadata, surface the drift and trust `plan.architecture.codeStructure` / provider artifacts plus the working tree over generated prose.\n- ! When scanning the existing codebase during scope understanding, MUST surface any contradicting patterns (two error-handling shapes, two state-management approaches, two naming conventions, etc.) before implementation begins -- apply `coding/hygiene.md` `## Surface Conflicts: Pick One, Explain, Flag the Other (#1005)` and choose ONE pattern (more recent OR more tested), explain the choice in the scope summary, and flag the other for cleanup\n- ⊗ Begin implementation against an averaged blend of two contradicting patterns -- \"average code that satisfies both rules is the worst code\" (#1005)\n- ! Present brief summary to user:\n\n> \"Here's what I see: {N} story xBRIEFs in active/. I'll start with {name}. Ready?\"\n\n### Step 2: Verify Toolchain\n\n- ! Before any implementation, verify all tools required by this project are installed and functional — see `deft/coding/toolchain.md` for full rules\n- ! At minimum: confirm task runner (`task --version`), language compiler/runtime, and platform SDK (if applicable) are available\n- ! If any required tool is missing, stop and report — do not proceed to Step 3\n- ⊗ Assume tools are available because the spec references them\n\n### Gate throughput — iteration fast lane vs merge chokepoint (#1704)\n\n> **Invariant:** every change MUST pass the full gate at least once before merge. Iteration MAY use a cheaper proxy; the merge chokepoint MUST NOT be skipped.\n\n- ! **Iteration lane (agents + humans):** during implementation commits, use affected/static gates — targeted tests on changed paths (`vitest run --coverage <paths>` or project equivalent), static `verify:*` gates relevant to touched files, and `task coverage:hotspots` / `task verify:forward-coverage` — NOT full `task check` on every commit.\n- ! **Merge chokepoint:** run full `task check` (or `task check:merge` in the framework source repo) once before push/PR and again when CI merge gate runs. Pre-PR skill exit and review-cycle fix batches still require a green full gate.\n- ! **Escape-rate safety (#1703 Tier-1):** before tightening fast-lane defaults fleet-wide, consult `#1703` measurement — `task eval:health` (Tier 0) and Tier-1 session telemetry (`helped/crud-metrics.jsonl` via instrumented CRUD / workflow metrics). Do NOT invent a separate fast-lane escape-rate surface (#1704 LockedDecisions).\n- ~ **In-engine incrementality (#1713):** content-hash task cache and runner-delegated affected selection are sibling work — not required for this policy face.\n- ⊗ Run full `task check` on every iteration commit when a cheaper proxy suffices — reserve the full gate for PR/merge (#1704).\n- ⊗ Skip the merge chokepoint because the iteration lane passed — the fast lane is convenience only.\n\n**Cost model (swarm-heavy path):** moves from roughly `O(commits × full-gate)` toward `O(merges × full-gate) + O(iterations × cheap-proxy)` when workers iterate with affected/static gates and run full `task check` only at PR/merge.\n\n### Dual stop — multi-iteration implement and pre-PR loops (#2442)\n\nMulti-iteration implement-fix and pre-PR polish loops MUST carry **both** a success stop and a failure/budget stop (`main.md` `## Dual Stop Rule (#2442)`). Single-turn edits and one-shot probes are exempt.\n\n**Defaults for this skill (override only with an explicit operator envelope or xBRIEF field):**\n\n| Loop class | Success stop | Default failure stop |\n|------------|--------------|----------------------|\n| Implement / quality fix (tests, lint, typecheck, coverage, AC) | Affected/static gates green for the change; AC met | **max 5** fix iterations **or** **3** consecutive identical outcomes (same failing command + same primary error class) with no material code/config change |\n| Pre-PR polish (`deft-directive-pre-pr` Read-Write-Lint-Diff) | Full pass with zero further edits | **max 3** polish passes **or** **2** consecutive no-diff / same-diff outcomes |\n| Full `task check` re-run | `task check` green after a red merge chokepoint or a new commit | Counts toward the implement/quality fix envelope above (do not open a separate unbounded check-retry loop) |\n\n- ! Re-run full `task check` only after a red merge chokepoint or a new commit.\n\n**On failure stop:**\n\n- ! Halt the loop. Surface an **operator-visible halt report** with: (1) iterations attempted and which stop fired (max-iter / no-progress / budget), (2) commands and primary failure fingerprints tried, (3) what is still red or missing, (4) the human decision needed (unblock dependency, rescope AC, waive with audit, abandon).\n- ! Prefer a structured `BLOCKED:` terminal (preamble §11 / #2843) when exiting a drive-to:merge-ready or parent-dispatched unit early because the envelope is exhausted.\n- ⊗ Continue \"one more fix\" after the envelope is exhausted.\n- ⊗ Reset the counter by opening a new commit, rewording the same change, or swapping workers while the same failure class remains.\n\n\n### Budget-aware effort - bank the pass before deepening (#3266)\n\nWhen a hard turn or cost budget is detectable (session:start `effort_budget` / env `DEFT_MAX_TURNS` / `DEFT_MAX_BUDGET` / host descriptor #1461), size effort to the **stated** acceptance bar first. This is the success-side analog of dual-stop (#2442): dual-stop stops thrash on failure; bank-the-pass stops budget exhaustion on over-deepening.\n\n- ! At implement start, read the session effort-budget signal (`task session:start` lines or JSON `effort_budget`, or env). When `posture=hard-capped`, treat the run as budget-constrained.\n- ! **Bank the pass first:** satisfy stated acceptance criteria (xBRIEF items / issue AC / official checker) and produce the passing artifact **before** any self-imposed deeper verification suite that exceeds the stated bar.\n- ! Only with **remaining** budget after the stated pass, extend verification depth. Never deepen past the point where a found defect could not also be fixed within budget (default reserve: enough turns/cost for one fix batch).\n- ! Self-verification scope scales with remaining budget - prefer the official/stated checks under a tight cap.\n- ! When deepening is skipped for budget, MUST say so in the run summary / handoff (`deepening_skipped=true` + reason) - fail-loud (#1006). Use `formatDeepeningSkippedNote` semantics from `packages/core/src/session/effort-budget.ts`.\n- ~ When no hard budget is detected (`posture=unbounded`), normal dual-stop defaults still apply; bank-the-pass is optional discipline, not a license to skip stated AC.\n- ⊗ Exhaust the turn/cost budget on self-imposed gold-plating after the stated bar is already within reach (#3266).\n- ⊗ Silently skip deepening without naming it, or silently gold-plate under a hard cap (#1006 / #3266).\n- ⊗ Treat bank-the-pass as permission to ship without meeting stated AC - stated AC remains the success stop.\n\nCore helper: `packages/core/src/session/effort-budget.ts` (`detectHardEffortBudget`, `recommendVerificationDepth`). Composes #2442, #1581, #3214, #1006.\n**Enforcement note:** skill defaults are behavioral. Durable delivery/acceptance circuit-breaker: **#3143** `packages/core/src/delivery-attempt/` (`evaluatePreDispatch`, `.deft/delivery-attempts/`). Docs: `docs/delivery-attempt.md`. Route delivery/acceptance automatic retries through that gate; do not invent a parallel ledger in this skill.\n\n### AC-pass banking checkpoint - finalize on green (#3285)\n\nSharpens #3266: the **first** moment stated/official acceptance criteria pass is a **banking checkpoint**, not a license to keep spending the turn budget on self-imposed depth.\n\n- ! When stated acceptance criteria first pass (`task verify:ac` / product-first done-gate #3284 / official checker), the **next** action is **FINALIZE**: checkpoint-commit the green state and record the bank (durable under `.deft/cache/ac-pass-banks/`; optional run-summary line when `DEFT_RUN_SUMMARY_PATH` is set).\n- ! **Deepening after the bank requires surplus budget.** Self-imposed extra verification, refactors, or polish are permitted only when remaining budget meets `plan.policy.acPassBanking.surplusThreshold` (default **0.2** = 20% of max turns/cost still remaining) **and** the absolute reserve from #3266. Env override: `DEFT_AC_PASS_SURPLUS_THRESHOLD`.\n- ! Deepening, when allowed, happens **on top of** the committed checkpoint so a failed experiment can revert to banked green.\n- ! **Post-bank discoveries are reported, not chased** when surplus is insufficient: file a note/issue in the deliverable for out-of-scope defects unless they **regress stated AC** (then fix-regression). Finding beyond the bar is a win; thrashing a dying budget into a zero is the failure mode this rule closes.\n- ! When surplus is insufficient, ship the banked state and fail-loud (`deepening_skipped=true` + surplus reason) via `evaluateAcPassBanking` / `formatDeepeningSkippedNote` semantics.\n- ~ When no hard budget is detected, dual-stop still applies; bank-on-first-AC-pass remains good discipline but is not a hard surplus gate.\n- ⊗ Convert a banked official pass into a scored failure by chasing post-bank polish until the turn budget dies (#3285).\n- ⊗ Start post-bank deepening without a finalize checkpoint when a hard budget is active (#3285).\n- ⊗ Chase out-of-scope post-bank findings when surplus is below threshold (#3285).\n\nCore helpers: `packages/core/src/session/ac-pass-banking.ts` (`evaluateAcPassBanking`, `bankAcPass`, `decidePostBankFinding`, `simulateSurplusInsufficientRun`); policy: `packages/core/src/policy/ac-pass-banking.ts` (`plan.policy.acPassBanking`). Composes #3266, #3284, #3282 (optional bank-event JSONL), #1006.\n\n## Step 3: Build Phase by Phase\n\nFor each phase:\n\n1. ! **Scaffold** — file structure, dependencies, config\n2. ! **Test first** — write tests before implementation (TDD)\n3. ! **Implement** — make tests pass, following deft coding standards\n4. ! **Verify (iteration lane)** — run affected/static gates per `#1704` fast lane above; fix failures before checkpoint commits\n5. ! **Origin sync** — when this phase materially changed an origin-linked scope xBRIEF (`plan.references` includes `x-xbrief/github-issue`), run `task issue:sync-from-xbrief -- <path>` (or `--dry-run` to preview) so the linked GitHub issue receives a sync comment; if skipped, document why in the PR or session notes (#2540)\n6. ! **Checkpoint** — tell user what's done, what's next\n\n- ⊗ Move to next phase until current phase passes all checks\n\n### Step 4: Quality Gates\n\nAfter EVERY phase (iteration lane — #1704):\n\n```bash\nvitest run --coverage <changed-paths>   # or project test runner on touched modules\ntask coverage:hotspots                  # branch headroom before merge\ntask verify:forward-coverage            # new-source coverage (#1310)\n```\n\nBefore PR / phase handoff (merge chokepoint):\n\n```bash\ntask check          # Full gate — format, lint, typecheck, tests, coverage, verify:*\ntask test:coverage  # >=85% or PROJECT-DEFINITION.xbrief.json override\n```\n\n- ! Phase checkpoint commits MAY use the iteration lane; phase is NOT done for PR handoff until full `task check` passes at the merge chokepoint\n- ⊗ Skip quality gates or claim they passed without running\n- ⊗ Treat iteration-lane green as merge-ready without full `task check`\n- ! **Multi-scope batch (#3012):** when implementing an approved multi-scope pin/cohort, reserve full `task check` for end-of-batch (or after last scope) unless the last full check failed — then re-run on the fix loop. Do not run full check after every intermediate scope.\n- ⊗ Re-run full install/session ceremony after offline seed when ritual is already complete (#3010) — use `session:ready` for recovery only.\n\n\n## Product-first done-gate (#3284) / literal AC (#3267)\n\nAt intake, capture the task statement's **exact** acceptance commands as executable AC (`plan.acceptance.commands` + #3267 `literal_acceptance_commands`). Empty is allowed only with `none_stated: true` (ladder: stated → derived → project_floor). Before declaring done, run them **verbatim** — same paths, same flags, same working directory. Self-chosen verification is supplementary, never a substitute. Extends #973. `task check` runs `verify:ac` **first** (fail-fast); hygiene is second and may become advisory under pressure. Rapid ceremony = **AC-only**.\n\n- ! When reading the active scope xBRIEF / issue body at story start, capture stated shell acceptance commands into `plan.acceptance.commands` (issue:ingest stamps this + the #3267 ledger automatically). Do not paraphrase.\n- ! Before claiming phase or story done (and before merge-chokepoint PR handoff), run:\n```\ntask verify:ac -- <active-story-path>\n```\n  Exit 0 = pass or none stated with valid marker; exit 1 = a stated command failed; exit 2 = config. (`verify:literal-ac` is the #3267 mechanism alias.)\n- ! Quote the literal invocations and their outputs in the completion note when commands were stated.\n- ⊗ Substitute a self-chosen approximation (`pnpm test` when the statement said `pnpm exec vitest run packages/core/src`) for the stated command.\n- ⊗ Skip this gate because ceremony dial is rapid/minimal — rapid's positive content is exactly this check (#3284).\n- ⊗ Leave `plan.acceptance.commands` empty without `none_stated: true` — absence must be an explicit decision.\n\n## Product-oracle gate integrity (#3322 / #3156)\n\nA red product verification may be resolved only by a product change or an independently re-derived oracle (both sides rebuilt from scratch, different method). In-place repair of the failing comparison then pass is not a pass — it is an unresolved discrepancy.\n\n- ! When a product oracle is red, resolve it by changing the product or by independently re-deriving the oracle, and record `independent_rederivation` on the run-summary `verification` event.\n- ! Emit a run-summary verification event `{check_id, method_fingerprint, outcome}` for each product-oracle attempt when `DEFT_RUN_SUMMARY_PATH` is set. `fail` then a different `method_fingerprint` then `pass` on one check id is machine-flagged.\n- ! `task verify:ac` treats comparison-method mutation as unresolved (exit non-zero) unless independent re-derivation is recorded. Lead the done report with any unresolved discrepancy (#1006).\n- ⊗ Self-adjudicate a red product oracle by editing the comparison (reference file, diff invocation, one-sided regenerate) and shipping the new pass as success.\n\n## Operator-log hygiene (lazy-load, #1940)\n\nWhen the story touches **operator-facing** services (dashboards, multi-process\nworkers, WARN/ERROR operators triage):\n\n- ~ SHOULD load `patterns/operator-log-hygiene.md` and apply the copy-paste\n  checklist in `docs/operator-log-hygiene-checklist.md` to story AC or probe\n  locked decisions before claiming logging done\n- ⊗ MUST NOT treat this as Product Insights (#2603) or LLM-call telemetry\n  (#481) — those are different lanes\n- ⊗ MUST NOT assume core `deft check` enforces a log schema by default —\n  consumer-owned shape; optional pack stub under\n  `docs/operator-log-hygiene-consumer-pack-stub.md`\n\nDiscovery keywords: operator log, operator-facing logs, observability checklist\n— also indexed in `REFERENCES.md`.\n\n## Goal-gate determinism (lazy-load, #852)\n\nWhen authoring or tightening story acceptance criteria, quality gates, or skill\nsteps during build:\n\n- ~ SHOULD load `patterns/goal-gate-determinism.md` — goals, AC, gates, exit,\n  scope, stop, and preserve are rigid; pure execution path is flexible guidance\n- ⊗ MUST NOT treat \"all process steps done\" as verification — outcomes and\n  gates own \"done\" (see also `verification/verification.md` and Fail Loud #1006)\n\nDiscovery keywords: goal-gate-determinism, rigid goals flexible path — also\nindexed in `REFERENCES.md`.\n\n## Coding Standards (Summary)\n\nRead full files when you need detail:\n\n- ! TDD: write tests first — implementation incomplete without passing tests\n- ! Coverage: ≥85% lines, functions, branches, statements\n- ~ Files: stay small; line counts live in the file-size-thresholds policy module (review trigger, not a hard cap; #1488 / #3424)\n- ~ Naming: hyphens for filenames unless language idiom dictates otherwise\n- ! Contracts first: define interfaces/types before implementation\n- ! Secrets: in `secrets/` dir with `.example` templates; ⊗ secrets in code\n- ! Commits: Conventional Commits format; ! use iteration fast lane before checkpoint commits; ! run full `task check` at PR/merge chokepoint only (#1704)\n\nSee `deft/coding/coding.md` and `deft/coding/testing.md` for full rules.\n\n## Pre-Commit File Review\n\n! Before every commit, re-read ALL modified files and explicitly check for:\n\n1. ! **Encoding errors** -- em-dashes corrupted to replacement characters, BOM artifacts, mojibake from round-trip read/write\n2. ! **Unintended duplication** -- accidental double entries in CHANGELOG.md, scope xBRIEF files, or structured data files\n3. ! **Structural issues** -- malformed CHANGELOG entries, broken table rows, mismatched index entries, invalid JSON/YAML\n4. ! **Semantic accuracy** -- verify that counts, claims, and summaries in CHANGELOG entries and ROADMAP changelog lines match the actual data in the commit (e.g. \"triaged 4 issues\" must match the number actually triaged, issue numbers cited must match the issues actually added)\n5. ! **Semantic contradictions** -- when adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing\n6. ! **Strength duplicates** -- when strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains\n7. ! **Forward test coverage** -- for each new source file in this PR (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`), verify a corresponding test file exists in the same PR; running existing tests is not sufficient for new code\n\n⊗ Commit without re-reading all modified files first.\n\n## Commit Strategy\n\n- ! Default to one story per branch/PR. Batching multiple stories in one branch requires explicit operator approval and a short rationale.\n- ! Create a checkpoint commit after each completed story before beginning another story.\n- ! Use iteration fast lane before checkpoint commits; run full `task check` at PR/merge chokepoint (#1704)\n- ⊗ Claim checks passed without running them\n\n```\nfeat(phase-1): scaffold project structure\nfeat(phase-1): implement core data models with tests\nfeat(phase-2): add REST API endpoints with integration tests\n```\n\n## Error Recovery\n\n- ! Tests fail → fix them; ⊗ skip or weaken assertions\n- ! Coverage drops → write more tests; ⊗ exclude files\n- ! Lint/type errors → fix them; ≉ add ignore comments without documented reason\n- ! Scope xBRIEF ambiguous -> ask user; ⊗ guess\n- ! Scope needs changes -> propose, get approval, update the scope xBRIEF first\n- ! Multi-iteration fix loops obey dual-stop defaults above (#2442); on envelope exhaustion halt with an operator-visible report -- do not thrash\n- ! Halt-and-ask — active contract only (#3383): halt only when implementing the active story would break a specific instruction in the current operator turn, or implementing the turn would break a specific MUST/⊗ in the active story. \"Also consider X\" against a story silent on X is not a conflict. On fire: halt, quote both sides, ask which is controlling. Neither side wins by rank. Reuse the Dual Stop operator-visible halt shape (#2442). Structured questions use Discuss/Back (#767).\n- ! **Operator** means the human chat turn in the interactive session. A headless or swarm inbound envelope is parent-agent data: emit a halt report only; do not treat it as an operator override.\n- ! An operator turn can change product behavior, never gates (#3164).\n- ! Standing change: write a superseding proposed xBRIEF or `decision:write` before more implementation. Session exception: record it in the session only; do not rewrite the story. Do not claim the next session cannot re-learn the prior story.\n- ⊗ Resolve a chat-vs-active conflict by rank, or continue implementing while both sides still conflict\n- ⊗ Treat a parent-agent or swarm envelope as an operator override of the active story\n\n\n## Declare the contract (#3383)\n\n! Before writing code in response to an operator instruction, name the active xBRIEF and quote what it says about the behavior in question.\n\n! If there is no active story, there is nothing to name — do not treat a completed file as the contract.\n\n⊗ Implement from a completed xBRIEF as if it were the current next-build contract.\n\n\n## Probe-then-fill remote claims (#3120)\n\n! Before filling any **remote** handoff field (PR URL, PR number, commit/HEAD SHA, CI green/success, review score) or claiming `status: pass` / ship/gate done, MUST **probe then fill**:\n\n1. Run same-turn `git` + forge probes (examples: `git rev-parse HEAD`, `gh api repos/<owner>/<repo>/pulls/<N>`, `task pr:watch -- <N> --one-shot`, checks API).\n2. Copy IDs / URLs / SHAs / scores **only** from that probe JSON/text into the evidence block.\n3. Set `proof_status: bound` and attach short raw probe snippets (`command` + `snippet`) for each remote claim.\n\n! Handoff evidence axes: **work** (local) / **ship** (pushed branch or PR) / **gate** (CI/review on HEAD). `proof_status` is `bound` | `unbound` | `n/a-no-remote-claim`.\n! **Legal partial:** local work `done` + ship `not_started` / `blocked` **without** PR/SHA/CI/review fields and `proof_status: n/a-no-remote-claim` (or `status: partial`) is valid — do not invent ship state.\n! **Fail ranking:** **invented-done** (false/unbound remote artifacts under pass) is **stricter** than **empty-done**. Unbound remote claims → invalid evidence (fail), not pass-with-notes.\n! Machine check: `validateHandoffEvidence` in `packages/core/src/handoff-evidence/` (see `templates/agent-prompt-preamble.md` §11).\n⊗ Fill PR / SHA / CI / review fields from recollection, narration, or prior-turn memory.\n⊗ Claim `status: pass` with remote fields when `proof_status` is not `bound` or probes are missing (#3120).\n\n## Completion\n\n- ! When all phases pass and `task check` is green, run `task scope:complete -- <active-story-path>` only as the post-merge scope lifecycle in `templates/agent-prompt-preamble.md` §9 (AGENTS.md `#2321`) specifies for `drive-to: merge-ready` versus `stop-at: pr-open`. That section is the single statement of the ordering; this skill does not restate it.\n\n> \"The project is built and all quality checks pass. Describe any new features you'd like to add — I'll follow the deft standards we've set up.\"\n\n\n## Significant decision log (#1396)\n\n! When this scope makes a **significant** choice (architecture, product behavior, security, public/private boundary, data model, runtime topology, hard-to-reverse process), record it with `task decision:write` (or `--body-file` for multi-line fields) so later agents load rationale without inventing it.\n\n~ Prefer attaching with `--scope <active-xbrief>` when the decision is bound to this story; use standalone `xbrief/decisions/` for cross-cutting / multi-scope process choices.\n\n~ Before claiming a process/architecture path was 'already decided', run `task decision:list -- --query <topic>` (or `--issue N`).\n\n⊗ Require a decision record for every trivial scope or routine fix.\n⊗ Merge lessons (#1513) into decision records, or replace ADRs under `docs/decisions/ADR-*.md`.\n\nDocs: `docs/decision-log.md` · `xbrief/decisions/README.md`.\n\n## Anti-Patterns\n\n- ⊗ Skip tests or write them after implementation\n- ⊗ Ignore `task check` failures\n- ⊗ Implement things not in scope xBRIEF without asking\n- ⊗ Read every deft file upfront\n- ⊗ Move to next phase before current passes checks\n- ⊗ Make commits without running iteration-lane validation; ⊗ skip full `task check` at PR/merge chokepoint (#1704)\n- ⊗ Proceed without USER.md -- always run the USER.md Gate first\n- ⊗ Re-run `directive init`, cold `session:start`, migrate, or re-copy pin scopes after offline seed when ritual is already complete (#3010)\n- ⊗ Run full `task check` after every intermediate scope of an approved multi-scope batch when the last merge-chokepoint check was green (#3012)\n- ⊗ Promote scopes one-by-one for a known multi-scope pin when `scope:promote --batch` would stage them in one turn (#3011)\n\n- ⊗ Spawn an implementation agent or invoke a code-writing tool against a xBRIEF that has not passed `task xbrief:preflight` -- always run the Step 0 Implementation Preflight (#810) first; satisfy via `task xbrief:activate <path>`\n- ⊗ Proceed without `COST-ESTIMATE.md` and a recorded build / rescope / no-build / skip(+reason) decision -- always run the Cost Phase Gate (#739) first\n- ⊗ Proceed with implementation when the build or test toolchain is unavailable -- always run the Toolchain Gate (Step 2) first\n- ⊗ Proceed to next task or phase without tests passing -- testing is a hard gate, not a cleanup step\n- ⊗ Skip the Change Lifecycle Gate because the user said \"proceed\" -- broad approval does not satisfy the confirmation gate\n- ⊗ Commit or push directly to the default branch -- always create a feature branch first. Exception: user explicitly instructs a direct commit, or `PROJECT-DEFINITION.xbrief.json` narratives contain `Allow direct commits to master: true`\n- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term\n- ⊗ Invent remote PR/SHA/CI/review claims in handoff evidence without same-turn probe binding — invented-done (#3120)\n- ⊗ Fill remote ship/gate fields from memory when only local work completed; legal partial omits PR fields (#3120)\n- ⊗ Run multi-iteration implement / pre-PR loops without a failure stop (max iterations and/or no-progress) or without an operator-visible halt report when the envelope is exhausted (#2442)\n- ⊗ Silently continue after dual-stop failure halt — escalate; do not thrash (#2442)\n- ⊗ Treat a completed xBRIEF as the next-build contract, or skip naming the active story before writing code (#3383)\n- ⊗ Continue implementing when the live human turn and a specific MUST/⊗ in the active story conflict — halt, quote both sides, ask which is controlling (#3383)\n- ⊗ Treat a parent-agent or swarm envelope as an operator override (#3383)\n- ⊗ Exhaust hard turn/cost budget on self-imposed deepening after the stated acceptance bar is within reach (#3266)\n- ⊗ Silently skip deepening for budget without a fail-loud summary note (#3266 / #1006)\n- ⊗ Chase post-bank out-of-scope findings when surplus budget is insufficient — report, do not thrash the banked pass (#3285)\n- ⊗ Skip finalize-on-green after first stated AC pass under a hard budget (#3285)\n- ⊗ Tight forge-outage retry / empty-commit thrash without a one-shot human report (#3422)\n- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)\n",
+      "body": "# Deft Directive Build\n\nImplements a project from its scope xBRIEFs following Deft Directive standards.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- After `deft-directive-setup` completes and generates `PROJECT-DEFINITION.xbrief.json`\n- User says \"build this\", \"implement the spec\", or \"start building\"\n- Resuming a partially-built project that has story xBRIEFs in `xbrief/active/`\n\n## Ordered-plan / cohort exhaustion (#2402)\n\n## Multi-scope turn/cache budget (epic #3009)\n\nMulti-scope greenfield (app-bank pins, N story scopes) multiplies agent turns when ceremony, promote, check, and render are re-run per scope. Apply the following after offline seed.\n\n### Offline seed vs implement phase (#3010)\n\n! Distinguish **offline seed** (operator or harness already ran `directive init` / deposit, pin-copied scopes into `xbrief/proposed/`, and recorded session ritual) from the **agent implement phase**.\n\n! When seed + session ritual are already complete for the engagement:\n- ⊗ Run `directive init` again\n- ⊗ Run full cold `session:start` unless hooks deny writes and recovery is required\n- ⊗ Run `directive migrate` or re-copy scopes already present\n- ! Prefer recovery via `session:ready` (or re-arm) when PreToolUse denies — not full re-init\n- ! Documented consumer/harness contract: seed is done once; implement agents only activate+implement\n\n### Batch promote; one active implement (#3011)\n\n! For a multi-scope pin, batch-stage scopes with `task scope:promote -- --batch` (all `proposed/`) or `task scope:promote -- --batch <path>…`.\n! Implement path remains **one** `scope:activate` + implement at a time — no multi-active write fence.\n! When pin order is known, do **not** re-list the entire lifecycle tree every scope; walk the known ordered list.\n⊗ Activate all scopes at once or drop the one-active-scope / story-ready stack.\n\n### Quality check once at end of multi-scope batch (#3012)\n\n! On an approved multi-scope batch (operator-approved multi-story branch, swarm cohort, or pin walk): run the merge chokepoint **once at the end of the batch** (or after the last scope), not after every scope — prefer `deft check`; if the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` in framework source). Do not run both.\n! Exception: if the last full check **failed**, fix loops MAY re-run check until green.\n! Pre-PR / merge-ready gates remain end-of-unit — this does not weaken them.\n! Iteration lane (affected tests / `verify:forward-coverage` / `coverage:hotspots`) still applies **per scope** during implementation (#1704).\n⊗ Spam full `directive check` / `task check` after every scope when the batch is still mid-flight and the last merge-chokepoint check was green.\n\n### One-shot project:render (#3013)\n\n! Greenfield init seeds a minimal render-ready `PROJECT-DEFINITION`. Treat `task project:render` as a **refresh of items from lifecycle folders**, not multi-turn identity research.\n⊗ Invent project identity across many turns when seed already stamped the skeleton.\n\n\n! When processing an approved multi-story cohort or an active ordered-plan sequence, stop after the final approved entry. Do not promote or dispatch adjacent stories from queue intuition. Continuation language advances only within the approved order; skill-chaining is non-authorizing.\n\n## Step 0 -- Implementation Preflight (#810)\n\n- ! Before starting any new implementation story or switching from one story to another, MUST run `git status --short --branch`.\n- ! If the working tree is dirty, MUST stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the target story. Ask the operator to choose one path: commit existing work, stash existing work, include existing work in the current story, or stop.\n- ⊗ Begin a new story while unrelated dirty work is present without explicit operator approval.\n- ! Resolve exactly one target story xBRIEF path by default. One story is the default implementation unit for this skill; if the user asks for a phase/epic, decompose or ask which story to start.\n- ! Batching multiple stories in one branch/PR requires explicit operator approval and a short rationale recorded in the handoff.\n- ! **Swarm-cohort dispatch carve-out**: when this skill is invoked as part of a swarm cohort allocated by `skills/deft-directive-swarm/SKILL.md`, the approved Phase 5 allocation plan satisfies the \"explicit operator approval and short rationale recorded in the handoff\" requirement above -- the dispatched xBRIEF paths and allocation rationale ARE the consent token. Process each assigned story sequentially under the checkpoint-commit + `task scope:complete` discipline below. Do NOT re-prompt the parent for batching approval mid-cohort -- the all-or-nothing dispatch envelope rule (`AGENTS.md` `## Multi-agent orchestration discipline (#954)`) forbids mid-scope user-approval gates.\n- ! **Structured consent-token recognition (#1378)**: the canonical recognition path for the carve-out above is the structured `## Allocation context` section of the dispatch envelope (the frozen schema in `templates/agent-prompt-preamble.md`, Story A of #1378). When that section reports `dispatch_kind: swarm-cohort` with a non-null `allocation_plan_id` AND a non-null `batching_rationale`, the consent token is satisfied mechanically -- read `cohort_vbriefs` as the authoritative file boundary and process each entry sequentially under the checkpoint-commit + `task scope:complete` discipline below, without re-prompting the parent for batching approval mid-cohort. When the `## Allocation context` section is ABSENT (pre-#1378 dispatches, solo-interactive sessions), fall back to the #1371 prose carve-out immediately above -- the prose carve-out remains the recognition path of record for un-elevated envelopes.\n- ! **Within a cohort, between stories**: the working tree MUST be clean after each story's checkpoint commit + `task scope:complete`. If `git status --short` shows uncommitted state between stories (e.g. a missed `task scope:complete` move, an unstaged file from the prior story), checkpoint-commit it and proceed -- do NOT pause to ask the operator. The dirty-tree \"ask the operator\" branch above applies only at the FIRST story-start of a fresh branch, where uncommitted operator work might legitimately exist.\n- ! If the target story is in `xbrief/proposed/`, run `task scope:promote -- <path>` first (or `task scope:promote -- --batch` for a multi-scope pin — #3011); if it is in `xbrief/pending/`, run `task scope:activate -- <path>`. After activation, update the path to the active-file location before preflight.\n- ! **Effort estimate gate (#1581):** before `task scope:activate` / `task vbrief:activate`, scan `plan.items` (including nested `items` / `subItems`) for `effort`. Time anchors: `S` <2h, `M` half-day (2-4h), `L` 1-2 days, `XL` needs breakdown. The activate path fails closed while any item still has `effort: \"XL\"` — break XL work into S/M/L items (or re-estimate) first. Omitted `effort` remains valid (field is optional). Plan-item effort is **post-planning** authority (confirms/corrects intake estimates); it is **not** session-start ritual input — ceremony depth (#3214) uses two-stage rapid→escalate, not a required plan-item read at cold start. Headless: no operator confirm. Depth: `vbrief/vbrief.md` § Effort estimate.\n- ⊗ Activate a scope that still carries plan items with `effort: \"XL\"` — XL means \"not ready to start\" until broken down (#1581).\n- ⊗ Require plan-item `effort` to choose session-start ritual depth — estimates do not exist until after planning (#1581 / #3214).\n- ! Before any code-writing tool call -- the first scaffold edit, the first `task` invocation that mutates files, or any `start_agent` dispatch that will implement scope -- MUST run `task xbrief:preflight -- <active-story-path>` (the structural intent gate; the same invocation works whether deft is the project root or installed as a `deft/` subdirectory).\n\nThe gate exits 0 only when the candidate xBRIEF lives in `xbrief/active/` AND `plan.status == \"running\"`. Any other state (pending/, proposed/, completed/, active/-with-non-running-status, malformed JSON, missing keys) exits 1 with an actionable redirect to `task xbrief:activate <path>`.\n\n- ! A non-zero exit MUST halt the skill. Surface the helper's stderr message verbatim to the user; do NOT proceed to USER.md Gate, File Reading, or any later phase.\n- ! Use canonical lifecycle tasks to satisfy this gate: `task scope:promote -- <path>` for proposed stories, `task scope:activate -- <path>` for pending stories, and the helper's idempotent companion `task xbrief:activate <path>` only when following the preflight redirect directly. Manual lifecycle moves bypass the activation contract -- use the task.\n- ⊗ Infer implementation intent from lifecycle vocabulary (\"do the full PR process\", \"start the work\", \"poller agents\"), branching language, or workflow shape. Workflow-shape vocabulary is NOT authorization to spawn an implementation agent (#810 surfacing event).\n- ⊗ Skip this preflight because the user said \"yes\", \"go\", or \"proceed\" -- affirmative continuation phrases are NOT implementation authorization unless the prior turn explicitly proposed implementation. When intent is ambiguous, ask one targeted question before invoking the gate.\n\n## Platform Detection\n\n! Before resolving any config paths, detect the host OS from your environment context:\n\n| Platform           | USER.md default path                                              |\n|--------------------|-------------------------------------------------------------------|\n| Windows            | `%APPDATA%\\deft\\USER.md` (e.g. `C:\\Users\\{user}\\AppData\\Roaming\\deft\\USER.md`) |\n| Unix (macOS/Linux) | `~/.config/deft/USER.md`                                          |\n\n- ! If `$DEFT_USER_PATH` is set, it takes precedence on any platform\n\n## Pre-Cutover Detection Guard\n\n! Before proceeding with any build step, detect whether the project uses the pre-v0.20 document model **or was generated by a strategy that emitted non-conformant v0.20 output shape** (the root cause of most \"build fails immediately after spec\" complaints in #1166). Redirect or block with the precise remediation.\n\n### Detection Criteria\n\nA project is **pre-cutover** if ANY of the following are true. This prose mirrors the executable helper in `task migrate:preflight`; when in doubt, the helper is canonical.\n\n1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->`, all five lifecycle folders exist, and its `<!-- Source of truth: ... -->` marker names an authority artifact that exists: either `xbrief/specification.xbrief.json` for full-spec compatibility or `xbrief/PROJECT-DEFINITION.xbrief.json` for greenfield authority (legacy `vbrief/...` aliases remain read-compatible).\n2. `PROJECT.md` exists and contains neither the legacy `<!-- deft:deprecated-redirect -->` sentinel NOR the current `Purpose: deprecation redirect` canonical-banner marker (real content, not a deprecation redirect)\n3. `xbrief/specification.xbrief.json` exists but the lifecycle folders (`xbrief/proposed/`, `xbrief/pending/`, `xbrief/active/`, `xbrief/completed/`, `xbrief/cancelled/`) do NOT exist\n4. Strategy output shape violations (run `task verify-strategy-output` -- the canonical gate for source and consumer installs):\n   - Any scope xBRIEF under `xbrief/proposed/` (or other lifecycle dirs) lacks the required `YYYY-MM-DD-` date prefix in its filename (e.g. bare `scaffold.xbrief.json`).\n   - `xbrief/PROJECT-DEFINITION.xbrief.json` is missing.\n   - `xbrief/specification.xbrief.json` exists as a legacy dual-write in a user-generated project. This is tolerated only for the framework source tree or a complete post-cutover full-spec consumer where all lifecycle folders exist and `SPECIFICATION.md` is rendered from `xbrief/specification.xbrief.json`.\n\n### Action on Detection\n\n! If pre-cutover or strategy-nonconformant state is detected, **stop immediately** and display an actionable message that cites the exact validator:\n\n> \"This project was generated with pre-v0.20 or non-conformant strategy output. Run the deterministic validator and follow its remediation: `task verify-strategy-output` (works in source and after `deft` package install). For document-model migration, follow UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068): pin v0.59.0, then run `task migrate:vbrief` from that payload. Otherwise `task project:render` / strategy re-run as indicated.\"\n\n! Include specific details about what was detected (the validator output is authoritative):\n\n- Legacy specification.xbrief.json or missing lifecycle folders: \"Follow the frozen v0.59.0 migrator path (#2068) or run `task migrate:preflight` for current-release guidance\"\n- Non-date-prefixed xBRIEFs: \"Re-run the emitting strategy after the v0.20 migrations (#1166 s1+s2+...) or manually rename files to `YYYY-MM-DD-<slug>.xbrief.json` and `task scope:promote`\"\n- Missing `PROJECT-DEFINITION.xbrief.json`: \"Run `task project:render` to generate the project definition\"\n- `SPECIFICATION.md` / `PROJECT.md` without sentinel: the classic pre-cutover messages\n- Scope xBRIEF in wrong folder: \"Status is '{status}' but file is in {folder}/ -- run `task scope:activate <file>` to fix\"\n\n! After the validator reports clean, re-run this guard before continuing.\n\n⊗ Proceed with build when pre-cutover or strategy-nonconformant artifacts are detected -- always redirect to the frozen migration path first (or run the validator) and surface the exact remediation.\n⊗ Silently ignore these artifacts or guess at fixes -- the validator (wired into `task check` and this guard) is the deterministic gate.\n\n## USER.md Gate\n\n! Before proceeding, verify USER.md exists at the platform-appropriate path\n(resolved via Platform Detection above, or `$DEFT_USER_PATH` if set).\n\n- ! If USER.md is not found: inform the user and redirect to `deft-directive-setup`\n  Phase 1 before continuing -- do not proceed without user preferences\n- ! Once USER.md exists, continue with the Cost Phase Gate below\n\n### Forge-outage drop-back (#3422)\n\n! On attributed platform outage or repeated REST 429/502/503 during YOLO / through-merge implement: drop GitHub I/O, report once to the human in chat, and re-probe on `plan.policy.forgeOutageRetryMinutes` (default **30**; USER.md Personal wins; min 5; `task policy:show --field=forgeOutageRetryMinutes`). Local edit/test/commit MAY continue. Depth: [`scm/github.md`](../../scm/github.md) § #3180 / #3422. Complements #3167 / #3180.\n\n⊗ Tight retry, empty-commit thrash, or sending the human to github.com as the only remediation.\n\n## Cost Phase Gate (#739)\n\n! Before proceeding to File Reading, verify the project has gone through the\npre-build cost & budget transparency phase from `skills/deft-directive-cost/SKILL.md`.\nThis closes the adoption-blocker surfaced by issue #739 (refs #151 umbrella) where\nusers finished the spec flow and stopped at build because deft offered no cost\nsignal.\n\n### Detection\n\n- ! Check for `COST-ESTIMATE.md` in the project root.\n- ! Check that the file contains a recorded decision (the **Decision recorded**\n  block populated with one of: `build`, `rescope`, `no-build`, `skip`).\n- ! For `skip`, `rescope`, or `no-build` decisions: the **Reason** field MUST be\n  populated (one or two sentences in plain language). A skip with no reason\n  recorded is treated the same as no decision.\n\n### Action\n\n- ! If `COST-ESTIMATE.md` is missing OR the **Decision recorded** block is\n  unpopulated OR a `skip`/`rescope`/`no-build` decision has no reason recorded:\n  stop immediately and redirect the user:\n\n  > \"This project has not gone through the pre-build cost & budget transparency\n  > phase. Run `skills/deft-directive-cost/SKILL.md` to produce a plain-English\n  > `COST-ESTIMATE.md`, then re-run the build skill once the user has chosen\n  > build / rescope / no-build / skip(+reason).\"\n\n- ! On a `build` or `skip` decision: continue with File Reading below.\n- ! On a `rescope` decision: stop and redirect the user back to spec edits\n  (chain to `skills/deft-directive-refinement/SKILL.md` to pull spec scope\n  back, or the interview), then re-run `skills/deft-directive-cost/SKILL.md`\n  before re-attempting build.\n- ! On a `no-build` decision: stop and exit; do NOT proceed to File Reading.\n  The user has explicitly stopped the project at the cost phase.\n- ⊗ Proceed to File Reading or any subsequent phase when `COST-ESTIMATE.md` is\n  missing, when the decision is unpopulated, or when a skip / rescope / no-build\n  decision has no reason recorded.\n- ⊗ Treat a `rescope` or `no-build` decision as if it were a `build` -- the\n  build skill MUST honor the recorded decision.\n\n## File Reading\n\n- ! Read in order, lazy load:\n  1. `./xbrief/active/` -- scope xBRIEFs for work items to build (required)\n  2. `./xbrief/PROJECT-DEFINITION.xbrief.json` -- project identity, tech stack, architecture\n  3. `./.planning/codebase/MAP.md` -- generated codebase orientation projection, if present (advisory)\n  4. USER.md at the platform-appropriate path (see Platform Detection) -- Personal section is highest precedence; Defaults are fallback\n  5. `deft/main.md` -- framework guidelines\n  6. `deft/coding/coding.md` -- coding standards\n  7. `deft/coding/testing.md` -- testing requirements\n  8. `deft/coding/toolchain.md` -- toolchain validation rules\n  9. `deft/languages/{language}.md` -- only for languages this project uses\n- ~ If the MAP is absent or may be stale and the current scope needs broad codebase orientation, run `task codebase:map` and `task verify:codebase-map-fresh` when those commands resolve. Treat absence/staleness as advisory unless the task edits `plan.architecture.codeStructure`, a configured provider artifact, or the generated MAP itself.\n- ! Treat `plan.architecture.codeStructure` and selected provider artifacts as authoritative. The MAP is a generated projection.\n- ⊗ Read all language/interface/tool files upfront\n- ⊗ Hand-edit `.planning/codebase/MAP.md` or block unrelated implementation solely because the MAP is stale or absent\n\n## Rule Precedence\n\n```\nUSER.md Personal                  <- HIGHEST (name, custom rules -- always wins)\nPROJECT-DEFINITION.xbrief.json   <- Project-specific (tech stack, architecture, config)\nUSER.md Defaults                  <- Fallback defaults (used when PROJECT-DEFINITION doesn't specify)\n{language}.md                     <- Language standards\ncoding.md                         <- General coding\nmain.md                           <- Framework defaults\nScope xBRIEFs                     <- LOWEST\n```\n\n- ! USER.md Personal section always wins over any other file\n- ! For project-scoped settings, PROJECT-DEFINITION.xbrief.json overrides USER.md Defaults\n\n## Change Lifecycle Gate\n\n! Before any implementation that touches 3+ files, verify that a `/deft:change <name>` proposal exists and has been confirmed by the user:\n\n- ! Check `history/changes/` for an active `proposal.xbrief.json` matching this work\n- ! If no proposal exists: propose `/deft:change <name>` and present the change name for explicit confirmation (e.g. \"Confirm? yes/no\")\n- ! The user must reply with an affirmative (`yes`, `confirmed`, `approve`) — a general 'proceed', 'do it', or 'go ahead' does NOT satisfy this gate\n- ? For solo projects: this gate is RECOMMENDED but not mandatory for changes fully covered by `task check`; it remains mandatory for cross-cutting, architectural, or high-risk changes\n- ⊗ Skip this gate because the user has already said \"proceed\" or \"go ahead\"\n\n## Build Process\n\nAll xBRIEFs (including those read from `xbrief/active/` and any new xBRIEFs this skill emits) MUST use `\"xBRIEFInfo\": { \"version\": \"0.8\" }`. Legacy 0.6 is read-accepted until `deft migrate:xbrief`. The validator accepts both; new writes are 0.8 only (see [`../../conventions/references.md`](../../conventions/references.md)).\n\n### Step 1: Understand the Scope\n\n- ! Read story xBRIEFs from `xbrief/active/` and `PROJECT-DEFINITION.xbrief.json`\n- ! Identify phases, dependencies, starting point from scope xBRIEF acceptance criteria\n- ~ Use `.planning/codebase/MAP.md`, when present, to orient broad codebase scanning. If the MAP conflicts with current code or canonical metadata, surface the drift and trust `plan.architecture.codeStructure` / provider artifacts plus the working tree over generated prose.\n- ! When scanning the existing codebase during scope understanding, MUST surface any contradicting patterns (two error-handling shapes, two state-management approaches, two naming conventions, etc.) before implementation begins -- apply `coding/hygiene.md` `## Surface Conflicts: Pick One, Explain, Flag the Other (#1005)` and choose ONE pattern (more recent OR more tested), explain the choice in the scope summary, and flag the other for cleanup\n- ⊗ Begin implementation against an averaged blend of two contradicting patterns -- \"average code that satisfies both rules is the worst code\" (#1005)\n- ! Present brief summary to user:\n\n> \"Here's what I see: {N} story xBRIEFs in active/. I'll start with {name}. Ready?\"\n\n### Step 2: Verify Toolchain\n\n- ! Before any implementation, verify all tools required by this project are installed and functional — see `deft/coding/toolchain.md` for full rules\n- ! At minimum: confirm task runner (`task --version`), language compiler/runtime, and platform SDK (if applicable) are available\n- ! If any required tool is missing, stop and report — do not proceed to Step 3\n- ⊗ Assume tools are available because the spec references them\n\n### Gate throughput — iteration fast lane vs merge chokepoint (#1704)\n\n> **Invariant:** every change MUST pass the full gate at least once before merge. Iteration MAY use a cheaper proxy; the merge chokepoint MUST NOT be skipped.\n\n- ! **Iteration lane (agents + humans):** during implementation commits, use affected/static gates — targeted tests on changed paths (`vitest run --coverage <paths>` or project equivalent), static `verify:*` gates relevant to touched files, and `task coverage:hotspots` / `task verify:forward-coverage` — NOT full `task check` on every commit.\n- ! **Merge chokepoint:** prefer `deft check` once before push/PR (and again when CI merge gate runs). If the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` / `task check:merge` in framework source). These are one gate, not two sequential runs. Do not add a fourth probe (#2893 / #4379). A bare `task check` miss on an include-only consumer is not \"gate unavailable\". Pre-PR skill exit and review-cycle fix batches still require a green full gate.\n- ! **Escape-rate safety (#1703 Tier-1):** before tightening fast-lane defaults fleet-wide, consult `#1703` measurement — `task eval:health` (Tier 0) and Tier-1 session telemetry (`helped/crud-metrics.jsonl` via instrumented CRUD / workflow metrics). Do NOT invent a separate fast-lane escape-rate surface (#1704 LockedDecisions).\n- ~ **In-engine incrementality (#1713):** content-hash task cache and runner-delegated affected selection are sibling work — not required for this policy face.\n- ⊗ Run full `task check` on every iteration commit when a cheaper proxy suffices — reserve the full gate for PR/merge (#1704).\n- ⊗ Skip the merge chokepoint because the iteration lane passed — the fast lane is convenience only.\n\n**Cost model (swarm-heavy path):** moves from roughly `O(commits × full-gate)` toward `O(merges × full-gate) + O(iterations × cheap-proxy)` when workers iterate with affected/static gates and run full `task check` only at PR/merge.\n\n### Dual stop — multi-iteration implement and pre-PR loops (#2442)\n\nMulti-iteration implement-fix and pre-PR polish loops MUST carry **both** a success stop and a failure/budget stop (`main.md` `## Dual Stop Rule (#2442)`). Single-turn edits and one-shot probes are exempt.\n\n**Defaults for this skill (override only with an explicit operator envelope or xBRIEF field):**\n\n| Loop class | Success stop | Default failure stop |\n|------------|--------------|----------------------|\n| Implement / quality fix (tests, lint, typecheck, coverage, AC) | Affected/static gates green for the change; AC met | **max 5** fix iterations **or** **3** consecutive identical outcomes (same failing command + same primary error class) with no material code/config change |\n| Pre-PR polish (`deft-directive-pre-pr` Read-Write-Lint-Diff) | Full pass with zero further edits | **max 3** polish passes **or** **2** consecutive no-diff / same-diff outcomes |\n| Full `deft check` re-run | tree-correct full gate green after a red merge chokepoint or a new commit | Counts toward the implement/quality fix envelope above (do not open a separate unbounded check-retry loop) |\n\n- ! Re-run the full gate (prefer `deft check`; else the tree-correct task form) only after a red merge chokepoint or a new commit. Do not run both.\n\n**On failure stop:**\n\n- ! Halt the loop. Surface an **operator-visible halt report** with: (1) iterations attempted and which stop fired (max-iter / no-progress / budget), (2) commands and primary failure fingerprints tried, (3) what is still red or missing, (4) the human decision needed (unblock dependency, rescope AC, waive with audit, abandon).\n- ! Prefer a structured `BLOCKED:` terminal (preamble §11 / #2843) when exiting a drive-to:merge-ready or parent-dispatched unit early because the envelope is exhausted.\n- ⊗ Continue \"one more fix\" after the envelope is exhausted.\n- ⊗ Reset the counter by opening a new commit, rewording the same change, or swapping workers while the same failure class remains.\n\n\n### Budget-aware effort - bank the pass before deepening (#3266)\n\nWhen a hard turn or cost budget is detectable (session:start `effort_budget` / env `DEFT_MAX_TURNS` / `DEFT_MAX_BUDGET` / host descriptor #1461), size effort to the **stated** acceptance bar first. This is the success-side analog of dual-stop (#2442): dual-stop stops thrash on failure; bank-the-pass stops budget exhaustion on over-deepening.\n\n- ! At implement start, read the session effort-budget signal (`task session:start` lines or JSON `effort_budget`, or env). When `posture=hard-capped`, treat the run as budget-constrained.\n- ! **Bank the pass first:** satisfy stated acceptance criteria (xBRIEF items / issue AC / official checker) and produce the passing artifact **before** any self-imposed deeper verification suite that exceeds the stated bar.\n- ! Only with **remaining** budget after the stated pass, extend verification depth. Never deepen past the point where a found defect could not also be fixed within budget (default reserve: enough turns/cost for one fix batch).\n- ! Self-verification scope scales with remaining budget - prefer the official/stated checks under a tight cap.\n- ! When deepening is skipped for budget, MUST say so in the run summary / handoff (`deepening_skipped=true` + reason) - fail-loud (#1006). Use `formatDeepeningSkippedNote` semantics from `packages/core/src/session/effort-budget.ts`.\n- ~ When no hard budget is detected (`posture=unbounded`), normal dual-stop defaults still apply; bank-the-pass is optional discipline, not a license to skip stated AC.\n- ⊗ Exhaust the turn/cost budget on self-imposed gold-plating after the stated bar is already within reach (#3266).\n- ⊗ Silently skip deepening without naming it, or silently gold-plate under a hard cap (#1006 / #3266).\n- ⊗ Treat bank-the-pass as permission to ship without meeting stated AC - stated AC remains the success stop.\n\nCore helper: `packages/core/src/session/effort-budget.ts` (`detectHardEffortBudget`, `recommendVerificationDepth`). Composes #2442, #1581, #3214, #1006.\n**Enforcement note:** skill defaults are behavioral. Durable delivery/acceptance circuit-breaker: **#3143** `packages/core/src/delivery-attempt/` (`evaluatePreDispatch`, `.deft/delivery-attempts/`). Docs: `docs/delivery-attempt.md`. Route delivery/acceptance automatic retries through that gate; do not invent a parallel ledger in this skill.\n\n### AC-pass banking checkpoint - finalize on green (#3285)\n\nSharpens #3266: the **first** moment stated/official acceptance criteria pass is a **banking checkpoint**, not a license to keep spending the turn budget on self-imposed depth.\n\n- ! When stated acceptance criteria first pass (`task verify:ac` / product-first done-gate #3284 / official checker), the **next** action is **FINALIZE**: checkpoint-commit the green state and record the bank (durable under `.deft/cache/ac-pass-banks/`; optional run-summary line when `DEFT_RUN_SUMMARY_PATH` is set).\n- ! **Deepening after the bank requires surplus budget.** Self-imposed extra verification, refactors, or polish are permitted only when remaining budget meets `plan.policy.acPassBanking.surplusThreshold` (default **0.2** = 20% of max turns/cost still remaining) **and** the absolute reserve from #3266. Env override: `DEFT_AC_PASS_SURPLUS_THRESHOLD`.\n- ! Deepening, when allowed, happens **on top of** the committed checkpoint so a failed experiment can revert to banked green.\n- ! **Post-bank discoveries are reported, not chased** when surplus is insufficient: file a note/issue in the deliverable for out-of-scope defects unless they **regress stated AC** (then fix-regression). Finding beyond the bar is a win; thrashing a dying budget into a zero is the failure mode this rule closes.\n- ! When surplus is insufficient, ship the banked state and fail-loud (`deepening_skipped=true` + surplus reason) via `evaluateAcPassBanking` / `formatDeepeningSkippedNote` semantics.\n- ~ When no hard budget is detected, dual-stop still applies; bank-on-first-AC-pass remains good discipline but is not a hard surplus gate.\n- ⊗ Convert a banked official pass into a scored failure by chasing post-bank polish until the turn budget dies (#3285).\n- ⊗ Start post-bank deepening without a finalize checkpoint when a hard budget is active (#3285).\n- ⊗ Chase out-of-scope post-bank findings when surplus is below threshold (#3285).\n\nCore helpers: `packages/core/src/session/ac-pass-banking.ts` (`evaluateAcPassBanking`, `bankAcPass`, `decidePostBankFinding`, `simulateSurplusInsufficientRun`); policy: `packages/core/src/policy/ac-pass-banking.ts` (`plan.policy.acPassBanking`). Composes #3266, #3284, #3282 (optional bank-event JSONL), #1006.\n\n## Step 3: Build Phase by Phase\n\nFor each phase:\n\n1. ! **Scaffold** — file structure, dependencies, config\n2. ! **Test first** — write tests before implementation (TDD)\n3. ! **Implement** — make tests pass, following deft coding standards\n4. ! **Verify (iteration lane)** — run affected/static gates per `#1704` fast lane above; fix failures before checkpoint commits\n5. ! **Origin sync** — when this phase materially changed an origin-linked scope xBRIEF (`plan.references` includes `x-xbrief/github-issue`), run `task issue:sync-from-xbrief -- <path>` (or `--dry-run` to preview) so the linked GitHub issue receives a sync comment; if skipped, document why in the PR or session notes (#2540)\n6. ! **Checkpoint** — tell user what's done, what's next\n\n- ⊗ Move to next phase until current phase passes all checks\n\n### Step 4: Quality Gates\n\nAfter EVERY phase (iteration lane — #1704):\n\n```bash\nvitest run --coverage <changed-paths>   # or project test runner on touched modules\ntask coverage:hotspots                  # branch headroom before merge\ntask verify:forward-coverage            # new-source coverage (#1310)\n```\n\nBefore PR / phase handoff (merge chokepoint):\n\n```bash\ndeft check          # preferred full gate (getting-started / #2893)\n# else tree-correct: task deft:check on include-only consumers; task check in framework source\ntask test:coverage  # >=85% or PROJECT-DEFINITION.xbrief.json override\n```\n\n- ! Phase checkpoint commits MAY use the iteration lane; phase is NOT done for PR handoff until full `task check` passes at the merge chokepoint\n- ⊗ Skip quality gates or claim they passed without running\n- ⊗ Treat iteration-lane green as merge-ready without full `task check`\n- ! **Multi-scope batch (#3012):** when implementing an approved multi-scope pin/cohort, reserve full `task check` for end-of-batch (or after last scope) unless the last full check failed — then re-run on the fix loop. Do not run full check after every intermediate scope.\n- ⊗ Re-run full install/session ceremony after offline seed when ritual is already complete (#3010) — use `session:ready` for recovery only.\n\n\n## Product-first done-gate (#3284) / literal AC (#3267)\n\nAt intake, capture the task statement's **exact** acceptance commands as executable AC (`plan.acceptance.commands` + #3267 `literal_acceptance_commands`). Empty is allowed only with `none_stated: true` (ladder: stated → derived → project_floor). Before declaring done, run them **verbatim** — same paths, same flags, same working directory. Self-chosen verification is supplementary, never a substitute. Extends #973. `task check` runs `verify:ac` **first** (fail-fast); hygiene is second and may become advisory under pressure. Rapid ceremony = **AC-only**.\n\n- ! When reading the active scope xBRIEF / issue body at story start, capture stated shell acceptance commands into `plan.acceptance.commands` (issue:ingest stamps this + the #3267 ledger automatically). Do not paraphrase.\n- ! Before claiming phase or story done (and before merge-chokepoint PR handoff), run:\n```\ntask verify:ac -- <active-story-path>\n```\n  Exit 0 = pass or none stated with valid marker; exit 1 = a stated command failed; exit 2 = config. (`verify:literal-ac` is the #3267 mechanism alias.)\n- ! Quote the literal invocations and their outputs in the completion note when commands were stated.\n- ⊗ Substitute a self-chosen approximation (`pnpm test` when the statement said `pnpm exec vitest run packages/core/src`) for the stated command.\n- ⊗ Skip this gate because ceremony dial is rapid/minimal — rapid's positive content is exactly this check (#3284).\n- ⊗ Leave `plan.acceptance.commands` empty without `none_stated: true` — absence must be an explicit decision.\n\n## Product-oracle gate integrity (#3322 / #3156)\n\nA red product verification may be resolved only by a product change or an independently re-derived oracle (both sides rebuilt from scratch, different method). In-place repair of the failing comparison then pass is not a pass — it is an unresolved discrepancy.\n\n- ! When a product oracle is red, resolve it by changing the product or by independently re-deriving the oracle, and record `independent_rederivation` on the run-summary `verification` event.\n- ! Emit a run-summary verification event `{check_id, method_fingerprint, outcome}` for each product-oracle attempt when `DEFT_RUN_SUMMARY_PATH` is set. `fail` then a different `method_fingerprint` then `pass` on one check id is machine-flagged.\n- ! `task verify:ac` treats comparison-method mutation as unresolved (exit non-zero) unless independent re-derivation is recorded. Lead the done report with any unresolved discrepancy (#1006).\n- ⊗ Self-adjudicate a red product oracle by editing the comparison (reference file, diff invocation, one-sided regenerate) and shipping the new pass as success.\n\n## Operator-log hygiene (lazy-load, #1940)\n\nWhen the story touches **operator-facing** services (dashboards, multi-process\nworkers, WARN/ERROR operators triage):\n\n- ~ SHOULD load `patterns/operator-log-hygiene.md` and apply the copy-paste\n  checklist in `docs/operator-log-hygiene-checklist.md` to story AC or probe\n  locked decisions before claiming logging done\n- ⊗ MUST NOT treat this as Product Insights (#2603) or LLM-call telemetry\n  (#481) — those are different lanes\n- ⊗ MUST NOT assume core `deft check` enforces a log schema by default —\n  consumer-owned shape; optional pack stub under\n  `docs/operator-log-hygiene-consumer-pack-stub.md`\n\nDiscovery keywords: operator log, operator-facing logs, observability checklist\n— also indexed in `REFERENCES.md`.\n\n## Goal-gate determinism (lazy-load, #852)\n\nWhen authoring or tightening story acceptance criteria, quality gates, or skill\nsteps during build:\n\n- ~ SHOULD load `patterns/goal-gate-determinism.md` — goals, AC, gates, exit,\n  scope, stop, and preserve are rigid; pure execution path is flexible guidance\n- ⊗ MUST NOT treat \"all process steps done\" as verification — outcomes and\n  gates own \"done\" (see also `verification/verification.md` and Fail Loud #1006)\n\nDiscovery keywords: goal-gate-determinism, rigid goals flexible path — also\nindexed in `REFERENCES.md`.\n\n## Coding Standards (Summary)\n\nRead full files when you need detail:\n\n- ! TDD: write tests first — implementation incomplete without passing tests\n- ! Coverage: ≥85% lines, functions, branches, statements\n- ~ Files: stay small; line counts live in the file-size-thresholds policy module (review trigger, not a hard cap; #1488 / #3424)\n- ~ Naming: hyphens for filenames unless language idiom dictates otherwise\n- ! Contracts first: define interfaces/types before implementation\n- ! Secrets: in `secrets/` dir with `.example` templates; ⊗ secrets in code\n- ! Commits: Conventional Commits format; ! use iteration fast lane before checkpoint commits; ! run full `deft check` (else tree-correct `task deft:check` / `task check`) at PR/merge chokepoint only (#1704 / #4379)\n\nSee `deft/coding/coding.md` and `deft/coding/testing.md` for full rules.\n\n## Pre-Commit File Review\n\n! Before every commit, re-read ALL modified files and explicitly check for:\n\n1. ! **Encoding errors** -- em-dashes corrupted to replacement characters, BOM artifacts, mojibake from round-trip read/write\n2. ! **Unintended duplication** -- accidental double entries in CHANGELOG.md, scope xBRIEF files, or structured data files\n3. ! **Structural issues** -- malformed CHANGELOG entries, broken table rows, mismatched index entries, invalid JSON/YAML\n4. ! **Semantic accuracy** -- verify that counts, claims, and summaries in CHANGELOG entries and ROADMAP changelog lines match the actual data in the commit (e.g. \"triaged 4 issues\" must match the number actually triaged, issue numbers cited must match the issues actually added)\n5. ! **Semantic contradictions** -- when adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing\n6. ! **Strength duplicates** -- when strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains\n7. ! **Forward test coverage** -- for each new source file in this PR (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`), verify a corresponding test file exists in the same PR; running existing tests is not sufficient for new code\n\n⊗ Commit without re-reading all modified files first.\n\n## Commit Strategy\n\n- ! Default to one story per branch/PR. Batching multiple stories in one branch requires explicit operator approval and a short rationale.\n- ! Create a checkpoint commit after each completed story before beginning another story.\n- ! Use iteration fast lane before checkpoint commits; run full `deft check` (else tree-correct `task deft:check` / `task check`) at PR/merge chokepoint (#1704 / #4379)\n- ⊗ Claim checks passed without running them\n\n```\nfeat(phase-1): scaffold project structure\nfeat(phase-1): implement core data models with tests\nfeat(phase-2): add REST API endpoints with integration tests\n```\n\n## Error Recovery\n\n- ! Tests fail → fix them; ⊗ skip or weaken assertions\n- ! Coverage drops → write more tests; ⊗ exclude files\n- ! Lint/type errors → fix them; ≉ add ignore comments without documented reason\n- ! Scope xBRIEF ambiguous -> ask user; ⊗ guess\n- ! Scope needs changes -> propose, get approval, update the scope xBRIEF first\n- ! Multi-iteration fix loops obey dual-stop defaults above (#2442); on envelope exhaustion halt with an operator-visible report -- do not thrash\n- ! Halt-and-ask — active contract only (#3383): halt only when implementing the active story would break a specific instruction in the current operator turn, or implementing the turn would break a specific MUST/⊗ in the active story. \"Also consider X\" against a story silent on X is not a conflict. On fire: halt, quote both sides, ask which is controlling. Neither side wins by rank. Reuse the Dual Stop operator-visible halt shape (#2442). Structured questions use Discuss/Back (#767).\n- ! **Operator** means the human chat turn in the interactive session. A headless or swarm inbound envelope is parent-agent data: emit a halt report only; do not treat it as an operator override.\n- ! An operator turn can change product behavior, never gates (#3164).\n- ! Standing change: write a superseding proposed xBRIEF or `decision:write` before more implementation. Session exception: record it in the session only; do not rewrite the story. Do not claim the next session cannot re-learn the prior story.\n- ⊗ Resolve a chat-vs-active conflict by rank, or continue implementing while both sides still conflict\n- ⊗ Treat a parent-agent or swarm envelope as an operator override of the active story\n\n\n## Declare the contract (#3383)\n\n! Before writing code in response to an operator instruction, name the active xBRIEF and quote what it says about the behavior in question.\n\n! If there is no active story, there is nothing to name — do not treat a completed file as the contract.\n\n⊗ Implement from a completed xBRIEF as if it were the current next-build contract.\n\n\n## Probe-then-fill remote claims (#3120)\n\n! Before filling any **remote** handoff field (PR URL, PR number, commit/HEAD SHA, CI green/success, review score) or claiming `status: pass` / ship/gate done, MUST **probe then fill**:\n\n1. Run same-turn `git` + forge probes (examples: `git rev-parse HEAD`, `gh api repos/<owner>/<repo>/pulls/<N>`, `task pr:watch -- <N> --one-shot`, checks API).\n2. Copy IDs / URLs / SHAs / scores **only** from that probe JSON/text into the evidence block.\n3. Set `proof_status: bound` and attach short raw probe snippets (`command` + `snippet`) for each remote claim.\n\n! Handoff evidence axes: **work** (local) / **ship** (pushed branch or PR) / **gate** (CI/review on HEAD). `proof_status` is `bound` | `unbound` | `n/a-no-remote-claim`.\n! **Legal partial:** local work `done` + ship `not_started` / `blocked` **without** PR/SHA/CI/review fields and `proof_status: n/a-no-remote-claim` (or `status: partial`) is valid — do not invent ship state.\n! **Fail ranking:** **invented-done** (false/unbound remote artifacts under pass) is **stricter** than **empty-done**. Unbound remote claims → invalid evidence (fail), not pass-with-notes.\n! Machine check: `validateHandoffEvidence` in `packages/core/src/handoff-evidence/` (see `templates/agent-prompt-preamble.md` §11).\n⊗ Fill PR / SHA / CI / review fields from recollection, narration, or prior-turn memory.\n⊗ Claim `status: pass` with remote fields when `proof_status` is not `bound` or probes are missing (#3120).\n\n## Completion\n\n- ! When all phases pass and `task check` is green, run `task scope:complete -- <active-story-path>` only as the post-merge scope lifecycle in `templates/agent-prompt-preamble.md` §9 (AGENTS.md `#2321`) specifies for `drive-to: merge-ready` versus `stop-at: pr-open`. That section is the single statement of the ordering; this skill does not restate it.\n\n> \"The project is built and all quality checks pass. Describe any new features you'd like to add — I'll follow the deft standards we've set up.\"\n\n\n## Significant decision log (#1396)\n\n! When this scope makes a **significant** choice (architecture, product behavior, security, public/private boundary, data model, runtime topology, hard-to-reverse process), record it with `task decision:write` (or `--body-file` for multi-line fields) so later agents load rationale without inventing it.\n\n~ Prefer attaching with `--scope <active-xbrief>` when the decision is bound to this story; use standalone `xbrief/decisions/` for cross-cutting / multi-scope process choices.\n\n~ Before claiming a process/architecture path was 'already decided', run `task decision:list -- --query <topic>` (or `--issue N`).\n\n⊗ Require a decision record for every trivial scope or routine fix.\n⊗ Merge lessons (#1513) into decision records, or replace ADRs under `docs/decisions/ADR-*.md`.\n\nDocs: `docs/decision-log.md` · `xbrief/decisions/README.md`.\n\n## Anti-Patterns\n\n- ⊗ Skip tests or write them after implementation\n- ⊗ Ignore `task check` failures\n- ⊗ Implement things not in scope xBRIEF without asking\n- ⊗ Read every deft file upfront\n- ⊗ Move to next phase before current passes checks\n- ⊗ Make commits without running iteration-lane validation; ⊗ skip full `task check` at PR/merge chokepoint (#1704)\n- ⊗ Proceed without USER.md -- always run the USER.md Gate first\n- ⊗ Re-run `directive init`, cold `session:start`, migrate, or re-copy pin scopes after offline seed when ritual is already complete (#3010)\n- ⊗ Run full `task check` after every intermediate scope of an approved multi-scope batch when the last merge-chokepoint check was green (#3012)\n- ⊗ Promote scopes one-by-one for a known multi-scope pin when `scope:promote --batch` would stage them in one turn (#3011)\n\n- ⊗ Spawn an implementation agent or invoke a code-writing tool against a xBRIEF that has not passed `task xbrief:preflight` -- always run the Step 0 Implementation Preflight (#810) first; satisfy via `task xbrief:activate <path>`\n- ⊗ Proceed without `COST-ESTIMATE.md` and a recorded build / rescope / no-build / skip(+reason) decision -- always run the Cost Phase Gate (#739) first\n- ⊗ Proceed with implementation when the build or test toolchain is unavailable -- always run the Toolchain Gate (Step 2) first\n- ⊗ Proceed to next task or phase without tests passing -- testing is a hard gate, not a cleanup step\n- ⊗ Skip the Change Lifecycle Gate because the user said \"proceed\" -- broad approval does not satisfy the confirmation gate\n- ⊗ Commit or push directly to the default branch -- always create a feature branch first. Exception: user explicitly instructs a direct commit, or `PROJECT-DEFINITION.xbrief.json` narratives contain `Allow direct commits to master: true`\n- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term\n- ⊗ Invent remote PR/SHA/CI/review claims in handoff evidence without same-turn probe binding — invented-done (#3120)\n- ⊗ Fill remote ship/gate fields from memory when only local work completed; legal partial omits PR fields (#3120)\n- ⊗ Run multi-iteration implement / pre-PR loops without a failure stop (max iterations and/or no-progress) or without an operator-visible halt report when the envelope is exhausted (#2442)\n- ⊗ Silently continue after dual-stop failure halt — escalate; do not thrash (#2442)\n- ⊗ Treat a completed xBRIEF as the next-build contract, or skip naming the active story before writing code (#3383)\n- ⊗ Continue implementing when the live human turn and a specific MUST/⊗ in the active story conflict — halt, quote both sides, ask which is controlling (#3383)\n- ⊗ Treat a parent-agent or swarm envelope as an operator override (#3383)\n- ⊗ Exhaust hard turn/cost budget on self-imposed deepening after the stated acceptance bar is within reach (#3266)\n- ⊗ Silently skip deepening for budget without a fail-loud summary note (#3266 / #1006)\n- ⊗ Chase post-bank out-of-scope findings when surplus budget is insufficient — report, do not thrash the banked pass (#3285)\n- ⊗ Skip finalize-on-green after first stated AC pass under a hard budget (#3285)\n- ⊗ Tight forge-outage retry / empty-commit thrash without a one-shot human report (#3422)\n- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)\n",
       "frontmatter_extra": null
     },
     {
@@ -89,7 +89,7 @@
       ],
       "path": "skills/deft-directive-design-critique/SKILL.md",
       "version": "0.1",
-      "body": "# Design Critique\n\nThin router into the design-critique contract. Operator dispatches from the brief template.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- Operator asks for a design critique, a design-critique, a critique panel, mechanism-shaped triage, arc, or run an arc\n- ⊗ Ordinary implement, build, or swarm work\n\n## Stops\n\nNormative 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). Parent-audit principle: [`docs/decisions/ADR-006-parent-side-substantiation.md`](../../../docs/decisions/ADR-006-parent-side-substantiation.md).\n\n1. Stop 1 — Gate\n2. Stop 2 — Variant selection\n3. Stop 3 — Critic envelope\n4. Stop 4 — Residual reiteration\n5. Stop 5 — Verified synthesis\n\nComment lead (model then role): Stop 3 — Critic envelope.\nOperator-gated loop. Successor lean. Parent-side substantiation. Operator verbs. Dual stop. Halt line. Bind after accepted synthesis.\nAfter this round's siblings are posted: successor lean, then verbs.\nAuto-stamp after operator confirm; not while same-round siblings outstanding.\nYolo standing confirm of a posted all-accept map: Operator verbs. Confirm conjunct only. Not ingest.\nWalk / walk all. Auto-stamp when agents agree: Operator verbs.\nParent chip write: scm:issue:design-critique-chip.\nChip apply miss is non-blocking convenience; do not halt. Ingest waits on the completed-arc record, not a catalog chip.\nRun posture: parse closed tokens; else ask. Field lives in the contract.\nGrok-bot detect default and widget apply-set live in the contract. Consume parseOperatorRunPosture.\nWidgets: numbered Discuss and Back. Plain English first in main-chat. `## Plain-language summary`.\n\nEach critic dispatch EXITs after posting.\n\n## Motion shape\n\nNot sequential review. Same-round critics are isolated: each reads one fixed input ceiling and cannot read other siblings' posts through the thread. More: [`references/motion-shape.md`](references/motion-shape.md).\n\nAfter same-round siblings are posted, the parent posts the successor lean; the operator confirms or amends before bind or stamp.\n\n⊗ Auto-dispatch critics from this skill.\n⊗ Copy the variant table, synthesis rules, or other contract bodies into this skill.\n\nSeat families and Grok Build launcher: Envelope and ceiling.\nDispatch-composition miss: offer or file a prevention issue.\n\n## EXIT\n\ndeft-directive-design-critique complete -- exiting skill. After Recut bind: Next: run `task issue:ingest`. Else: operator fills the brief template and dispatches the next envelope. Direct EXIT: ingest is a separate operator verb.\n",
+      "body": "# Design Critique\n\nThin router into the design-critique contract. Operator dispatches from the brief template.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- Operator asks for a design critique, a design-critique, a critique panel, mechanism-shaped triage, arc, or run an arc\n- ⊗ Ordinary implement, build, or swarm work\n\n## Stops\n\nNormative 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). Parent-audit principle: [`docs/decisions/ADR-006-parent-side-substantiation.md`](../../../docs/decisions/ADR-006-parent-side-substantiation.md).\n\n1. Stop 1 — Gate\n2. Stop 2 — Variant selection\n3. Stop 3 — Critic envelope\n4. Stop 4 — Residual reiteration\n5. Stop 5 — Verified synthesis\n\nComment lead (model then role): Stop 3 — Critic envelope.\nOperator-gated loop. Successor lean. Parent-side substantiation. Operator verbs. Dual stop. Halt line. Bind after accepted synthesis.\nAfter this round's siblings are posted: successor lean, then verbs.\nAuto-stamp after operator confirm; not while same-round siblings outstanding.\nYolo standing confirm of a posted all-accept map: Operator verbs. Confirm conjunct only. Not ingest.\nWalk / walk all. Auto-stamp when agents agree: Operator verbs.\nParent chip write: scm:issue:design-critique-chip.\nChip apply miss is non-blocking convenience; do not halt. Ingest waits on the completed-arc record, not a catalog chip.\nRun posture: parse closed tokens; else ask. Field lives in the contract.\nGrok-bot detect default and widget apply-set live in the contract. Consume parseOperatorRunPosture.\nWidgets: numbered Discuss and Back. Plain English first in main-chat. `## Plain-language summary`.\n\nEach critic dispatch EXITs after posting.\n\n## Motion shape\n\nNot sequential review. Same-round critics are isolated: each reads one fixed input ceiling and cannot read other siblings' posts through the thread. More: [`references/motion-shape.md`](references/motion-shape.md).\n\nAfter same-round siblings are posted, the parent posts the successor lean; the operator confirms or amends before bind or stamp.\n\n⊗ Auto-dispatch critics from this skill.\n⊗ Copy the variant table, synthesis rules, or other contract bodies into this skill.\n\nSeat families and Grok Build launcher: Envelope and ceiling. Grok critic recovery: Design-critique dispatch (dest-rooted grok --cwd --prompt-file after recorded native deny). Native admit without skip-class is not a critic.\nDispatch-composition miss: offer or file a prevention issue.\n\n## EXIT\n\ndeft-directive-design-critique complete -- exiting skill. After an admitted completed-arc record: Next: run `task issue:ingest`. Mid-arc EXIT: operator fills the brief template and dispatches the next envelope. Direct EXIT: ingest is a separate operator verb.\n",
       "frontmatter_extra": "triggers:\n  - design critique\n  - design-critique\n  - critique panel\n  - mechanism-shaped triage\n  - arc\n  - run an arc"
     },
     {
@@ -196,7 +196,7 @@
     },
     {
       "id": "deft-directive-pre-pr",
-      "description": "Iterative pre-PR quality improvement loop. Use before pushing a branch for PR creation -- after completing implementation but before task check. Cycles through Read-Write-Lint-Diff until a full pass produces zero changes.",
+      "description": "Iterative pre-PR quality improvement loop. Use before pushing a branch for PR creation -- after completing implementation but before deft check. Cycles through Read-Write-Lint-Diff until a full pass produces zero changes.",
       "triggers": [
         "pre-pr",
         "quality loop",
@@ -204,7 +204,7 @@
       ],
       "path": "skills/deft-directive-pre-pr/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Pre-PR -- Read, Write, Lint, Diff, Loop\n\nStructured self-review loop agents run before submitting a PR. Catches inconsistencies, missing enforcement markers, incomplete acceptance criteria, scope creep, and unintended changes before they reach the reviewer.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) | [deft-directive-build](../deft-directive-build/SKILL.md) | [RWLDL tool](../../tools/RWLDL.md)\n\n> **Formerly `deft-rwldl`** -- renamed and scoped to PR readiness. For the broader iterative quality improvement loop (micro/macro review), see [tools/RWLDL.md](../../tools/RWLDL.md).\n\n## Branch-Protection Policy Guard\n\n! Before entering Phase 1 (Read), run the skill-level branch-policy guard documented in `task policy:show` / dual-invoke `deft verify:branch` (#746 / #747). Halt before any state mutation (the Phase 2 Write phase, the Phase 3 Lint phase that may touch files) when the policy is unresolvable AND no env-var bypass is active:\n\n```\ndeft verify:branch\n```\n\nor `task deft:verify:branch` when the consumer Taskfile include is present. Do not add a consumer `verify:branch` task. Pre-PR is the last gate before push, so a stale / unresolvable policy here is the highest-leverage place to catch the bug before it reaches the bot reviewer.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (per-finding decision menus in Phase 4 Diff, the Phase 5 Loop restart-vs-exit gate) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. The Discuss-pause semantic is documented verbatim there -- implicit resumption is forbidden.\n\n\n## Ordered-plan target gate (#2402)\n\n! Before opening or pushing a PR, when an ordered-plan sequence may be active, verify the work unit matches the current authorized entry:\n\n1. Resolve the current entry kind and id:\n\n```\ntask plan-sequence:current\n```\n\n   Use `task plan-sequence:current -- --json` when you need machine-readable `kind` / `id` fields from the current entry.\n\n2. Verify with the **entry kind** (not hardcoded `pr` — `story` / `issue` entries are common):\n\n```\ntask verify:plan-sequence -- --target-kind <entry-kind> --target <entry-id>\n```\n\n- ! Exit non-zero → fail closed; do not open an unauthorized PR.\n- ! Exit 0 with \"skipped (no active ordered-plan sequence)\" → proceed under normal pre-PR rules.\n- ⊗ Hardcode `--target-kind pr` when the current entry is `kind=story` or `kind=issue` — the verifier matches entry kind exactly (#2662).\n- ! After the PR's review cycle completes successfully, run `task plan-sequence:advance` so \"next\" resolves to the following entry (or exhausted).\n- ⊗ Treat skill-chaining or \"what's next?\" as permission to open a PR outside the current sequence entry.\n\n## Gate throughput — iteration fast lane vs merge chokepoint (#1704)\n\n> **Invariant:** every change MUST pass the full gate at least once before merge. Pre-PR is the merge chokepoint — NOT every iteration commit.\n\n- ! **Iteration lane (Phases 2–3 loop):** use affected/static gates on changed paths — `vitest run --coverage <paths>`, relevant `verify:*` on touched files, `task coverage:hotspots` — instead of full `task check` on every pre-PR iteration. Phase 3 sits inside this loop, so it uses the iteration lane, not a full suite.\n- ! **Merge chokepoint (once after the loop, before push/PR):** run full `task check` once before push/PR. This is a #1704 revision of the prior Phase 3 Lint exit + final confirm (two runs, one inside every iteration). The escape-rate guard below still applies; do not invent a separate surface.\n- ! **Escape-rate safety (#1703 Tier-1):** before recommending fleet-wide fast-lane tightening, cite `#1703` Tier-1 telemetry (`helped/crud-metrics.jsonl`) and `task eval:health` — do NOT invent a separate escape-rate surface.\n- ~ **In-engine incrementality (#1713):** content-hash cache + runner-delegated affected selection are sibling work (#1713).\n- ⊗ Treat Phase 3c targeted coverage alone as PR-ready without full `task check` at the merge chokepoint.\n- ⊗ Run full `task check` inside every pre-PR Phase 3 iteration — Phase 3 is inside the loop; the chokepoint is once after exit.\n\n## When to Use\n\n- ! Before pushing a branch for PR creation\n- ! After completing implementation but before the final merge-chokepoint `task check` (#1704)\n- ~ After addressing bot reviewer findings (run one pre-PR pass before pushing the fix batch)\n- ? During mid-implementation checkpoints on large changes\n\n## Loop Phases\n\nEach iteration proceeds through all phases in order. Do NOT skip phases or reorder them.\n\n### Phase 1 -- Read\n\n! Re-read each changed file end-to-end (`git diff master --name-only` to get the list).\n\n- ! Read every changed file in full -- do not skim or skip sections\n- ! Compare each file against its scope xBRIEF acceptance criteria in `xbrief/active/`\n- ~ If changed files include `xbrief/PROJECT-DEFINITION.xbrief.json`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md`, read the MAP and canonical metadata together. The MAP is orientation; `plan.architecture.codeStructure` and provider artifacts remain authoritative.\n- ! When adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing\n- ! When strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains\n- ! When adding a weaker rule (`~`, `≉`, or prose that recommends or permits a command/pattern) beside an existing `!` or `⊗` for the same command/pattern in the same file, resolve the contradiction in the same commit — weaken-beside-a-MUST is the same-commit reconcile as adding or strengthening a MUST (#4135 / #4324)\n- ~ Note any inconsistencies, missing RFC2119 markers, stale cross-references, or incomplete sections\n- ~ Check that CHANGELOG.md entries match the actual changes made\n- ! If the change alters **user-visible behavior**, apply [coding/docs.md](../../coding/docs.md) (#447): update the matching user-facing surface (CHANGELOG when user/operator-visible, CLI help / commands.md for new or changed verbs/flags, README/getting-started for install/first-run, skill/strategy triggers when entry points change) in this PR\n- ⊗ Claim documentation was updated without those files in the diff\n- ~ Pure internal refactors with no user-visible behavior change do not require user-facing doc updates\n\n### Phase 2 -- Write\n\n! Fix any issues found in the Read phase.\n\n- ! Fix inconsistencies, add missing RFC2119 enforcement markers (`!`, `~`, `⊗`)\n- ! Complete any incomplete acceptance criteria or missing content\n- ! Update stale cross-references\n- ~ Improve clarity where intent is ambiguous\n- ⊗ Make changes beyond the scope of the current task -- if you notice unrelated issues, file them as ideas or future work, do not fix them now\n\n### Phase 3 -- Lint\n\n! Run the iteration-lane gates and fix any failures (#1704). Full `task check` is the post-loop merge chokepoint, not this per-iteration phase.\n\n- ! Run affected/static gates on changed paths (`vitest run --coverage <paths>`, relevant `verify:*`, `task coverage:hotspots`) — not full `task check` inside the loop\n- ! Fix all failures before proceeding to Phase 3b\n- ~ If a lint fix requires changing a file, that counts as a change for the Loop phase\n\n~ **Windows + Grok Build (#1353):** Avoid `|`, `>`, or `2>&1` in `run_terminal_command` strings -- use Python `pathlib`/`subprocess` or plain task commands instead.\n\n### Phase 3c -- Coverage headroom (#2683)\n\n! Before the full `task check` coverage gate, run targeted coverage on changed modules and verify headroom above the project floor.\n\n- ! Run targeted coverage first: `vitest run --coverage <changed-paths>` (or language equivalent) — not only full `task check`.\n- ! Exercise both sides of new branches (ternary / early-return / catch / default switch / `||` / `??`).\n- ! Treat barely ≥ floor as insufficient — aim for ≥ floor + 0.3–0.5pp headroom on the branch metric relative to **your project's** vitest/coverage floor (may differ from 85%).\n- ! Run `task coverage:hotspots` / `deft coverage:hotspots` to locate uncovered branches before opening a PR; complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573).\n\n### Phase 3b -- Auto-Render Exports\n\n! If `xbrief/specification.xbrief.json` exists, refresh rendered exports before the diff check:\n\n- ! Run `task prd:render` if `PRD.md` already exists in the project root\n- ! Run `task spec:render` if `SPECIFICATION.md` already exists and does not contain `<!-- deft:deprecated-redirect -->`\n- ! If `plan.architecture.codeStructure`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md` changed, run `task codebase:map` and `task verify:codebase-map-fresh` so the generated orientation projection matches its canonical inputs.\n- ⊗ Create export files that don't already exist -- only refresh existing ones\n- ⊗ Hand-edit `.planning/codebase/MAP.md` to satisfy review; update canonical metadata or provider artifacts, then regenerate it\n\n### Phase 4 -- Diff\n\n! Review the full diff against the base branch for unintended changes.\n\n```\ngit --no-pager diff master\n```\n\n- ! Verify no files outside the task scope were modified\n- ! Check for scope creep -- changes that go beyond the spec task acceptance criteria\n- ! Verify no debug code, TODO comments, or temporary scaffolding remains\n- ! Confirm no unintended whitespace-only changes or formatting drift\n- ! **Closing-keyword policy (#3015 class D / #737 Layer 0):** Default PR body uses `Tracking: #N` / `Related: #N` / `Refs #N` only. Use `Closes` / `Fixes` / `Resolves #N` only when the **full issue DoD** is met (not Phase A partial / multi-phase mid-stream).\n- ⊗ Write `Closes #N Phase A`, `only if`, `partial`, or other conditional English around a real closing keyword — GitHub ignores the condition and auto-closes (#3015 enterprize#29).\n- ! **Run `task pr:check-closing-keywords` before opening the PR (default mode `both` = FP #737 + intent #3015).** Offline: `--body-file` / `--commits-file`. Scans body and commits for closing-keyword tokens in negation / quotation / example / code-block contexts (FP) and for any unallowlisted real close (intent). When full DoD close is intentional, pass `--allow-close <N,M>` (CLI allowlist only — body trailers are not an authorization path). FP-only: `--mode fp`. Known-safe quoted tokens: `--allow-known-false-positives`. Recurrence stack: #167, #697 / #698, #401 / #700, #735 (class A), #3015 (class D enterprize#29).\n- ~ Verify the diff tells a coherent story -- a reviewer reading it top-to-bottom should understand the change\n- ~ If the PR adds or moves any documentation, verify each new doc is reachable from the AGENTS.md reference chain -- an orphan doc is discovered <10% of the time yet still costs context when found (the reference-chain contract, #644 / #647). Add a pointer or fold it in rather than leaving it stranded.\n- ! **Gate integrity (#3156):** If the branch cleared a red gate, confirm the fix changed the product/process/test under test — not the gate definition, verifier, reward, required check, coverage floor, policy flag, or eval fixture that was failing. Deliberate gate changes need issue/PR rationale (constitution-tier disposal under #3164). Doctrine: [docs/gate-integrity.md](../../docs/gate-integrity.md). Refine-internal SkillOpt region stays on #2436 — do not re-implement it here.\n\n### Phase 5 -- Loop\n\n! Decide whether to restart or exit.\n\n- ! If ANY fixes were made in Phase 2 (Write) or Phase 3 (Lint): restart from Phase 1 (Read)\n- ~ Phase 3b auto-renders are intentional output refreshes; they do NOT trigger a loop restart\n- ! If a full Read-Write-Lint-Diff cycle produced zero changes: exit the loop\n- ~ Track iteration count -- if you exceed 3 iterations, pause and assess whether you are oscillating between competing fixes\n\n\n\n## Budget-aware pre-PR depth (#3266)\n\nWhen session effort-budget is hard-capped (`DEFT_MAX_TURNS` / `DEFT_MAX_BUDGET` / session:start `effort_budget`):\n\n- ! Complete the merge-chokepoint path that proves stated AC (full `task check` once, stated AC evidence) before optional polish that only deepens beyond the bar.\n- ! If remaining budget cannot fund another full Read-Write-Lint-Diff pass **and** a fix for a new finding, stop after the stated-pass chokepoint and record `deepening_skipped=true` with reason (#1006).\n- ! Dual-stop pre-PR defaults (max 3 polish / 2 no-diff) still apply; under a hard cap, prefer fewer polish iterations once AC + check are green.\n- ⊗ Start an unbounded self-imposed verification suite that exceeds stated AC while the hard budget is nearly exhausted (#3266).\n\n## Product-first done-gate (#3284) / literal AC (#3267)\n\n- ! Before Phase 3 Lint exit / push, when the active scope xBRIEF has acceptance commands (`plan.acceptance` or #3267 metadata/narratives), run `task verify:ac -- <active-xbrief>` and fail closed on exit 1. (`verify:literal-ac` is the mechanism alias.)\n- ! Commands must be the exact strings from the task statement — same flags and cwd. Self-chosen verification is supplementary only.\n- ! Full `task check` already runs `verify:ac` first; still run it explicitly before push when AC is stated so failures are visible without the full hygiene suite.\n- ⊗ Skip AC run on rapid/minimal ceremony dial — rapid = AC-only; AC never degrades when commands exist (#3284 / #3156).\n\n## Product-oracle gate integrity (#3322 / #3156)\n\nA red product verification may be resolved only by a product change or an independently re-derived oracle (both sides rebuilt from scratch, different method). In-place repair of the failing comparison then pass is not a pass — it is an unresolved discrepancy.\n\n- ! When a product oracle is red, resolve it by changing the product or by independently re-deriving the oracle, and record `independent_rederivation` on the run-summary `verification` event.\n- ! Emit a run-summary verification event `{check_id, method_fingerprint, outcome}` for each product-oracle attempt when `DEFT_RUN_SUMMARY_PATH` is set. `fail` then a different `method_fingerprint` then `pass` on one check id is machine-flagged.\n- ! `task verify:ac` treats comparison-method mutation as unresolved (exit non-zero) unless independent re-derivation is recorded. Lead the done report with any unresolved discrepancy (#1006).\n- ⊗ Self-adjudicate a red product oracle by editing the comparison (reference file, diff invocation, one-sided regenerate) and shipping the new pass as success.\n\n## Probe-then-fill remote claims (#3120)\n\n! Before filling any **remote** handoff field (PR URL, PR number, commit/HEAD SHA, CI green/success, review score) or claiming `status: pass` / ship/gate done, MUST **probe then fill**:\n\n1. Run same-turn `git` + forge probes (examples: `git rev-parse HEAD`, `gh api repos/<owner>/<repo>/pulls/<N>`, `task pr:watch -- <N> --one-shot`, checks API).\n2. Copy IDs / URLs / SHAs / scores **only** from that probe JSON/text into the evidence block.\n3. Set `proof_status: bound` and attach short raw probe snippets (`command` + `snippet`) for each remote claim.\n\n! Handoff evidence axes: **work** (local) / **ship** (pushed branch or PR) / **gate** (CI/review on HEAD). `proof_status` is `bound` | `unbound` | `n/a-no-remote-claim`.\n! **Legal partial:** local work `done` + ship `not_started` / `blocked` **without** PR/SHA/CI/review fields and `proof_status: n/a-no-remote-claim` (or `status: partial`) is valid — do not invent ship state.\n! **Fail ranking:** **invented-done** (false/unbound remote artifacts under pass) is **stricter** than **empty-done**. Unbound remote claims → invalid evidence (fail), not pass-with-notes.\n! Machine check: `validateHandoffEvidence` in `packages/core/src/handoff-evidence/` (see `templates/agent-prompt-preamble.md` §11).\n⊗ Fill PR / SHA / CI / review fields from recollection, narration, or prior-turn memory.\n⊗ Claim `status: pass` with remote fields when `proof_status` is not `bound` or probes are missing (#3120).\n\n## Exit Condition\n\n! Exit when a complete Read-Write-Lint-Diff cycle produces **zero changes** -- no file edits in Write, no lint fixes in Lint, and no scope issues in Diff.\n\nAfter exiting:\n- ! Run full `task check` once — the merge chokepoint. Phase 3 used the iteration lane, so this is the first full suite in the loop, not a second run.\n- ! If that post-loop `task check` is red and the fix changes files, restart from Phase 1 (Read). Do not only re-run the gate — those edits must pass Read and Diff (#4324).\n- ! After that restart exits with zero changes, run full `task check` once again (recovery after a red merge chokepoint).\n- ! Re-run the full gate only after a red merge chokepoint or a new commit.\n- ~ The branch is now ready for push and PR creation\n\n\n## Significant decision log (#1396)\n\n! Before push, if this PR encodes a **significant** choice not already recorded, run `task decision:write` (significance filter: architecture, product behavior, security, boundaries, data model, topology, hard-to-reverse process).\n\n~ Check `task decision:list` for related process policy so the PR does not silently reverse a dogfood decision.\n\n⊗ Invent revisit-free rationale in the PR body as a substitute for a decision record when the choice is significant.\n⊗ Noise the log with trivial scope completions.\n\nDocs: `docs/decision-log.md`.\n\n## Anti-Patterns\n\n- ⊗ Submit a PR without running this pre-PR loop (Read-Write-Lint-Diff) -- every PR branch should pass at least one full cycle\n- ⊗ Exit the loop after the Lint phase without completing the Diff phase -- Diff catches scope creep and unintended changes that Lint cannot detect\n- ⊗ Skip the Read phase and jump directly to Lint -- Read catches semantic issues (missing content, wrong RFC2119 markers, incomplete acceptance criteria) that linters do not check\n- ⊗ Make out-of-scope fixes during Write -- this introduces scope creep that Diff will flag, forcing another iteration\n- ⊗ Ignore the iteration count -- more than 3 iterations usually indicates oscillating fixes or an unclear spec task\n- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term\n- ⊗ Add a weaker rule (`~` / `≉`) beside an existing `!` / `⊗` for the same command/pattern without reconciling in the same commit\n- ⊗ After a red post-loop `task check`, fix files and re-run only the gate without restarting Read-Write-Lint-Diff\n- ⊗ Skip `task pr:check-closing-keywords` (#737) before pushing a PR. Intent mode (#3015) also refuses bare/conditional real `Closes #N` without `--allow-close`. The negation-context substring match is the Layer 0 (prevention) gate that prevents the recurring auto-close of umbrella / staying-OPEN issues observed in #697 (closed #642), #401 (closed #642), #700 (closed #233), and #735 (closed #734) -- each incident required manual reopen and downstream cleanup. The lint's three-state exit (0 clean / 1 hits found / 2 config error) MUST be treated as a hard refusal: rewrite the PR body / commit messages until clean, OR pass `--allow-known-false-positives` ONLY for legitimately-quoted occurrences (test fixtures, documentation that discusses the trigger token literally). See `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1 for the corresponding Layer 3 (recovery) `pr:check-protected-issues` rule (#701)\n- ⊗ Invent remote PR/SHA/CI/review claims in handoff evidence without same-turn probe binding — invented-done (#3120)\n- ⊗ Fill remote ship/gate fields from memory when only local work completed; legal partial omits PR fields (#3120)\n- ⊗ Clear a failing gate by editing the gate (definition, verifier, reward, required check, coverage floor, policy, eval fixture) instead of the work under test — gate integrity (#3156); see [docs/gate-integrity.md](../../docs/gate-integrity.md)\n- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)\n- ⊗ Under a hard turn/cost budget, gold-plate pre-PR polish past the stated bar until the budget expires (#3266)\n- ⊗ Exit pre-PR after skipping deepen-for-budget without naming the skip in the summary (#3266 / #1006)\n",
+      "body": "# Deft Directive Pre-PR -- Read, Write, Lint, Diff, Loop\n\nStructured self-review loop agents run before submitting a PR. Catches inconsistencies, missing enforcement markers, incomplete acceptance criteria, scope creep, and unintended changes before they reach the reviewer.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) | [deft-directive-build](../deft-directive-build/SKILL.md) | [RWLDL tool](../../tools/RWLDL.md)\n\n> **Formerly `deft-rwldl`** -- renamed and scoped to PR readiness. For the broader iterative quality improvement loop (micro/macro review), see [tools/RWLDL.md](../../tools/RWLDL.md).\n\n## Branch-Protection Policy Guard\n\n! Before entering Phase 1 (Read), run the skill-level branch-policy guard documented in `task policy:show` / dual-invoke `deft verify:branch` (#746 / #747). Halt before any state mutation (the Phase 2 Write phase, the Phase 3 Lint phase that may touch files) when the policy is unresolvable AND no env-var bypass is active:\n\n```\ndeft verify:branch\n```\n\nor `task deft:verify:branch` when the consumer Taskfile include is present. Do not add a consumer `verify:branch` task. Pre-PR is the last gate before push, so a stale / unresolvable policy here is the highest-leverage place to catch the bug before it reaches the bot reviewer.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (per-finding decision menus in Phase 4 Diff, the Phase 5 Loop restart-vs-exit gate) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. The Discuss-pause semantic is documented verbatim there -- implicit resumption is forbidden.\n\n\n## Ordered-plan target gate (#2402)\n\n! Before opening or pushing a PR, when an ordered-plan sequence may be active, verify the work unit matches the current authorized entry:\n\n1. Resolve the current entry kind and id:\n\n```\ntask plan-sequence:current\n```\n\n   Use `task plan-sequence:current -- --json` when you need machine-readable `kind` / `id` fields from the current entry.\n\n2. Verify with the **entry kind** (not hardcoded `pr` — `story` / `issue` entries are common):\n\n```\ntask verify:plan-sequence -- --target-kind <entry-kind> --target <entry-id>\n```\n\n- ! Exit non-zero → fail closed; do not open an unauthorized PR.\n- ! Exit 0 with \"skipped (no active ordered-plan sequence)\" → proceed under normal pre-PR rules.\n- ⊗ Hardcode `--target-kind pr` when the current entry is `kind=story` or `kind=issue` — the verifier matches entry kind exactly (#2662).\n- ! After the PR's review cycle completes successfully, run `task plan-sequence:advance` so \"next\" resolves to the following entry (or exhausted).\n- ⊗ Treat skill-chaining or \"what's next?\" as permission to open a PR outside the current sequence entry.\n\n## Gate throughput — iteration fast lane vs merge chokepoint (#1704)\n\n> **Invariant:** every change MUST pass the full gate at least once before merge. Pre-PR is the merge chokepoint — NOT every iteration commit.\n\n- ! **Iteration lane (Phases 2–3 loop):** use affected/static gates on changed paths — `vitest run --coverage <paths>`, relevant `verify:*` on touched files, `task coverage:hotspots` — instead of full `task check` on every pre-PR iteration. Phase 3 sits inside this loop, so it uses the iteration lane, not a full suite.\n- ! **Merge chokepoint (once after the loop, before push/PR):** prefer `deft check` once before push/PR. If the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` in framework source). These are one gate, not two sequential runs. Do not add a fourth probe (#2893 / #4379). A bare `task check` miss on an include-only consumer is not \"gate unavailable\". This is a #1704 revision of the prior Phase 3 Lint exit + final confirm (two runs, one inside every iteration). The escape-rate guard below still applies; do not invent a separate surface.\n- ! **Escape-rate safety (#1703 Tier-1):** before recommending fleet-wide fast-lane tightening, cite `#1703` Tier-1 telemetry (`helped/crud-metrics.jsonl`) and `task eval:health` — do NOT invent a separate escape-rate surface.\n- ~ **In-engine incrementality (#1713):** content-hash cache + runner-delegated affected selection are sibling work (#1713).\n- ⊗ Treat Phase 3c targeted coverage alone as PR-ready without full `task check` at the merge chokepoint.\n- ⊗ Run full `task check` inside every pre-PR Phase 3 iteration — Phase 3 is inside the loop; the chokepoint is once after exit.\n\n## When to Use\n\n- ! Before pushing a branch for PR creation\n- ! After completing implementation but before the final merge-chokepoint `deft check` (#1704 / #4379)\n- ~ After addressing bot reviewer findings (run one pre-PR pass before pushing the fix batch)\n- ? During mid-implementation checkpoints on large changes\n\n## Loop Phases\n\nEach iteration proceeds through all phases in order. Do NOT skip phases or reorder them.\n\n### Phase 1 -- Read\n\n! Re-read each changed file end-to-end (`git diff master --name-only` to get the list).\n\n- ! Read every changed file in full -- do not skim or skip sections\n- ! Compare each file against its scope xBRIEF acceptance criteria in `xbrief/active/`\n- ~ If changed files include `xbrief/PROJECT-DEFINITION.xbrief.json`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md`, read the MAP and canonical metadata together. The MAP is orientation; `plan.architecture.codeStructure` and provider artifacts remain authoritative.\n- ! When adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing\n- ! When strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains\n- ! When adding a weaker rule (`~`, `≉`, or prose that recommends or permits a command/pattern) beside an existing `!` or `⊗` for the same command/pattern in the same file, resolve the contradiction in the same commit — weaken-beside-a-MUST is the same-commit reconcile as adding or strengthening a MUST (#4135 / #4324)\n- ~ Note any inconsistencies, missing RFC2119 markers, stale cross-references, or incomplete sections\n- ~ Check that CHANGELOG.md entries match the actual changes made\n- ! If the change alters **user-visible behavior**, apply [coding/docs.md](../../coding/docs.md) (#447): update the matching user-facing surface (CHANGELOG when user/operator-visible, CLI help / commands.md for new or changed verbs/flags, README/getting-started for install/first-run, skill/strategy triggers when entry points change) in this PR\n- ⊗ Claim documentation was updated without those files in the diff\n- ~ Pure internal refactors with no user-visible behavior change do not require user-facing doc updates\n\n### Phase 2 -- Write\n\n! Fix any issues found in the Read phase.\n\n- ! Fix inconsistencies, add missing RFC2119 enforcement markers (`!`, `~`, `⊗`)\n- ! Complete any incomplete acceptance criteria or missing content\n- ! Update stale cross-references\n- ~ Improve clarity where intent is ambiguous\n- ⊗ Make changes beyond the scope of the current task -- if you notice unrelated issues, file them as ideas or future work, do not fix them now\n\n### Phase 3 -- Lint\n\n! Run the iteration-lane gates and fix any failures (#1704). Full `task check` is the post-loop merge chokepoint, not this per-iteration phase.\n\n- ! Run affected/static gates on changed paths (`vitest run --coverage <paths>`, relevant `verify:*`, `task coverage:hotspots`) — not full `task check` inside the loop\n- ! Fix all failures before proceeding to Phase 3b\n- ~ If a lint fix requires changing a file, that counts as a change for the Loop phase\n\n~ **Windows + Grok Build (#1353):** Avoid `|`, `>`, or `2>&1` in `run_terminal_command` strings -- use Python `pathlib`/`subprocess` or plain task commands instead.\n\n### Phase 3c -- Coverage headroom (#2683)\n\n! Before the full `task check` coverage gate, run targeted coverage on changed modules and verify headroom above the project floor.\n\n- ! Run targeted coverage first: `vitest run --coverage <changed-paths>` (or language equivalent) — not only full `task check`.\n- ! Exercise both sides of new branches (ternary / early-return / catch / default switch / `||` / `??`).\n- ! Treat barely ≥ floor as insufficient — aim for ≥ floor + 0.3–0.5pp headroom on the branch metric relative to **your project's** vitest/coverage floor (may differ from 85%).\n- ! Run `task coverage:hotspots` / `deft coverage:hotspots` to locate uncovered branches before opening a PR; complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573).\n\n### Phase 3b -- Auto-Render Exports\n\n! If `xbrief/specification.xbrief.json` exists, refresh rendered exports before the diff check:\n\n- ! Run `task prd:render` if `PRD.md` already exists in the project root\n- ! Run `task spec:render` if `SPECIFICATION.md` already exists and does not contain `<!-- deft:deprecated-redirect -->`\n- ! If `plan.architecture.codeStructure`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md` changed, run `task codebase:map` and `task verify:codebase-map-fresh` so the generated orientation projection matches its canonical inputs.\n- ⊗ Create export files that don't already exist -- only refresh existing ones\n- ⊗ Hand-edit `.planning/codebase/MAP.md` to satisfy review; update canonical metadata or provider artifacts, then regenerate it\n\n### Phase 4 -- Diff\n\n! Review the full diff against the base branch for unintended changes.\n\n```\ngit --no-pager diff master\n```\n\n- ! Verify no files outside the task scope were modified\n- ! Check for scope creep -- changes that go beyond the spec task acceptance criteria\n- ! Verify no debug code, TODO comments, or temporary scaffolding remains\n- ! Confirm no unintended whitespace-only changes or formatting drift\n- ! **Closing-keyword policy (#3015 class D / #737 Layer 0):** Default PR body uses `Tracking: #N` / `Related: #N` / `Refs #N` only. Use `Closes` / `Fixes` / `Resolves #N` only when the **full issue DoD** is met (not Phase A partial / multi-phase mid-stream).\n- ⊗ Write `Closes #N Phase A`, `only if`, `partial`, or other conditional English around a real closing keyword — GitHub ignores the condition and auto-closes (#3015 enterprize#29).\n- ! **Run `task pr:check-closing-keywords` before opening the PR (default mode `both` = FP #737 + intent #3015).** Offline: `--body-file` / `--commits-file`. Scans body and commits for closing-keyword tokens in negation / quotation / example / code-block contexts (FP) and for any unallowlisted real close (intent). When full DoD close is intentional, pass `--allow-close <N,M>` (CLI allowlist only — body trailers are not an authorization path). FP-only: `--mode fp`. Known-safe quoted tokens: `--allow-known-false-positives`. Recurrence stack: #167, #697 / #698, #401 / #700, #735 (class A), #3015 (class D enterprize#29).\n- ~ Verify the diff tells a coherent story -- a reviewer reading it top-to-bottom should understand the change\n- ~ If the PR adds or moves any documentation, verify each new doc is reachable from the AGENTS.md reference chain -- an orphan doc is discovered <10% of the time yet still costs context when found (the reference-chain contract, #644 / #647). Add a pointer or fold it in rather than leaving it stranded.\n- ! **Gate integrity (#3156):** If the branch cleared a red gate, confirm the fix changed the product/process/test under test — not the gate definition, verifier, reward, required check, coverage floor, policy flag, or eval fixture that was failing. Deliberate gate changes need issue/PR rationale (constitution-tier disposal under #3164). Doctrine: [docs/gate-integrity.md](../../docs/gate-integrity.md). Refine-internal SkillOpt region stays on #2436 — do not re-implement it here.\n\n### Phase 5 -- Loop\n\n! Decide whether to restart or exit.\n\n- ! If ANY fixes were made in Phase 2 (Write) or Phase 3 (Lint): restart from Phase 1 (Read)\n- ~ Phase 3b auto-renders are intentional output refreshes; they do NOT trigger a loop restart\n- ! If a full Read-Write-Lint-Diff cycle produced zero changes: exit the loop\n- ~ Track iteration count -- if you exceed 3 iterations, pause and assess whether you are oscillating between competing fixes\n\n\n\n## Budget-aware pre-PR depth (#3266)\n\nWhen session effort-budget is hard-capped (`DEFT_MAX_TURNS` / `DEFT_MAX_BUDGET` / session:start `effort_budget`):\n\n- ! Complete the merge-chokepoint path that proves stated AC (full `task check` once, stated AC evidence) before optional polish that only deepens beyond the bar.\n- ! If remaining budget cannot fund another full Read-Write-Lint-Diff pass **and** a fix for a new finding, stop after the stated-pass chokepoint and record `deepening_skipped=true` with reason (#1006).\n- ! Dual-stop pre-PR defaults (max 3 polish / 2 no-diff) still apply; under a hard cap, prefer fewer polish iterations once AC + check are green.\n- ⊗ Start an unbounded self-imposed verification suite that exceeds stated AC while the hard budget is nearly exhausted (#3266).\n\n## Product-first done-gate (#3284) / literal AC (#3267)\n\n- ! Before Phase 3 Lint exit / push, when the active scope xBRIEF has acceptance commands (`plan.acceptance` or #3267 metadata/narratives), run `task verify:ac -- <active-xbrief>` and fail closed on exit 1. (`verify:literal-ac` is the mechanism alias.)\n- ! Commands must be the exact strings from the task statement — same flags and cwd. Self-chosen verification is supplementary only.\n- ! Full `task check` already runs `verify:ac` first; still run it explicitly before push when AC is stated so failures are visible without the full hygiene suite.\n- ⊗ Skip AC run on rapid/minimal ceremony dial — rapid = AC-only; AC never degrades when commands exist (#3284 / #3156).\n\n## Product-oracle gate integrity (#3322 / #3156)\n\nA red product verification may be resolved only by a product change or an independently re-derived oracle (both sides rebuilt from scratch, different method). In-place repair of the failing comparison then pass is not a pass — it is an unresolved discrepancy.\n\n- ! When a product oracle is red, resolve it by changing the product or by independently re-deriving the oracle, and record `independent_rederivation` on the run-summary `verification` event.\n- ! Emit a run-summary verification event `{check_id, method_fingerprint, outcome}` for each product-oracle attempt when `DEFT_RUN_SUMMARY_PATH` is set. `fail` then a different `method_fingerprint` then `pass` on one check id is machine-flagged.\n- ! `task verify:ac` treats comparison-method mutation as unresolved (exit non-zero) unless independent re-derivation is recorded. Lead the done report with any unresolved discrepancy (#1006).\n- ⊗ Self-adjudicate a red product oracle by editing the comparison (reference file, diff invocation, one-sided regenerate) and shipping the new pass as success.\n\n## Probe-then-fill remote claims (#3120)\n\n! Before filling any **remote** handoff field (PR URL, PR number, commit/HEAD SHA, CI green/success, review score) or claiming `status: pass` / ship/gate done, MUST **probe then fill**:\n\n1. Run same-turn `git` + forge probes (examples: `git rev-parse HEAD`, `gh api repos/<owner>/<repo>/pulls/<N>`, `task pr:watch -- <N> --one-shot`, checks API).\n2. Copy IDs / URLs / SHAs / scores **only** from that probe JSON/text into the evidence block.\n3. Set `proof_status: bound` and attach short raw probe snippets (`command` + `snippet`) for each remote claim.\n\n! Handoff evidence axes: **work** (local) / **ship** (pushed branch or PR) / **gate** (CI/review on HEAD). `proof_status` is `bound` | `unbound` | `n/a-no-remote-claim`.\n! **Legal partial:** local work `done` + ship `not_started` / `blocked` **without** PR/SHA/CI/review fields and `proof_status: n/a-no-remote-claim` (or `status: partial`) is valid — do not invent ship state.\n! **Fail ranking:** **invented-done** (false/unbound remote artifacts under pass) is **stricter** than **empty-done**. Unbound remote claims → invalid evidence (fail), not pass-with-notes.\n! Machine check: `validateHandoffEvidence` in `packages/core/src/handoff-evidence/` (see `templates/agent-prompt-preamble.md` §11).\n⊗ Fill PR / SHA / CI / review fields from recollection, narration, or prior-turn memory.\n⊗ Claim `status: pass` with remote fields when `proof_status` is not `bound` or probes are missing (#3120).\n\n## Exit Condition\n\n! Exit when a complete Read-Write-Lint-Diff cycle produces **zero changes** -- no file edits in Write, no lint fixes in Lint, and no scope issues in Diff.\n\nAfter exiting:\n- ! Run the merge chokepoint once: prefer `deft check`; if the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` in framework source). These are one gate, not two sequential runs. Do not add a fourth probe (#2893 / #4379). Phase 3 used the iteration lane, so this is the first full suite in the loop, not a second run.\n- ! If that post-loop full gate is red and the fix changes files, restart from Phase 1 (Read). Do not only re-run the gate — those edits must pass Read and Diff (#4324).\n- ! After that restart exits with zero changes, run the same tree-correct full gate once again (recovery after a red merge chokepoint).\n- ! Re-run the full gate only after a red merge chokepoint or a new commit.\n- ~ The branch is now ready for push and PR creation\n\n\n## Significant decision log (#1396)\n\n! Before push, if this PR encodes a **significant** choice not already recorded, run `task decision:write` (significance filter: architecture, product behavior, security, boundaries, data model, topology, hard-to-reverse process).\n\n~ Check `task decision:list` for related process policy so the PR does not silently reverse a dogfood decision.\n\n⊗ Invent revisit-free rationale in the PR body as a substitute for a decision record when the choice is significant.\n⊗ Noise the log with trivial scope completions.\n\nDocs: `docs/decision-log.md`.\n\n## Anti-Patterns\n\n- ⊗ Submit a PR without running this pre-PR loop (Read-Write-Lint-Diff) -- every PR branch should pass at least one full cycle\n- ⊗ Exit the loop after the Lint phase without completing the Diff phase -- Diff catches scope creep and unintended changes that Lint cannot detect\n- ⊗ Skip the Read phase and jump directly to Lint -- Read catches semantic issues (missing content, wrong RFC2119 markers, incomplete acceptance criteria) that linters do not check\n- ⊗ Make out-of-scope fixes during Write -- this introduces scope creep that Diff will flag, forcing another iteration\n- ⊗ Ignore the iteration count -- more than 3 iterations usually indicates oscillating fixes or an unclear spec task\n- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term\n- ⊗ Add a weaker rule (`~` / `≉`) beside an existing `!` / `⊗` for the same command/pattern without reconciling in the same commit\n- ⊗ After a red post-loop `task check`, fix files and re-run only the gate without restarting Read-Write-Lint-Diff\n- ⊗ Skip `task pr:check-closing-keywords` (#737) before pushing a PR. Intent mode (#3015) also refuses bare/conditional real `Closes #N` without `--allow-close`. The negation-context substring match is the Layer 0 (prevention) gate that prevents the recurring auto-close of umbrella / staying-OPEN issues observed in #697 (closed #642), #401 (closed #642), #700 (closed #233), and #735 (closed #734) -- each incident required manual reopen and downstream cleanup. The lint's three-state exit (0 clean / 1 hits found / 2 config error) MUST be treated as a hard refusal: rewrite the PR body / commit messages until clean, OR pass `--allow-known-false-positives` ONLY for legitimately-quoted occurrences (test fixtures, documentation that discusses the trigger token literally). See `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1 for the corresponding Layer 3 (recovery) `pr:check-protected-issues` rule (#701)\n- ⊗ Invent remote PR/SHA/CI/review claims in handoff evidence without same-turn probe binding — invented-done (#3120)\n- ⊗ Fill remote ship/gate fields from memory when only local work completed; legal partial omits PR fields (#3120)\n- ⊗ Clear a failing gate by editing the gate (definition, verifier, reward, required check, coverage floor, policy, eval fixture) instead of the work under test — gate integrity (#3156); see [docs/gate-integrity.md](../../docs/gate-integrity.md)\n- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)\n- ⊗ Under a hard turn/cost budget, gold-plate pre-PR polish past the stated bar until the budget expires (#3266)\n- ⊗ Exit pre-PR after skipping deepen-for-budget without naming the skip in the summary (#3266 / #1006)\n",
       "frontmatter_extra": null
     },
     {
@@ -266,7 +266,7 @@
       ],
       "path": "skills/deft-directive-release/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Release\n\nStructured 8-phase workflow for cutting a v0.X.Y release of the deft framework. Operationalizes the `task release` / `task release:publish` / `task release:rollback` / `task release:e2e` surface introduced in #716 (safety hardening of #74).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-swarm](../deft-directive-swarm/SKILL.md) Phase 6 Step 5 (Slack announcement template re-used by Phase 8 below) | [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) (user-gate pattern) | [deft-directive-refinement](../deft-directive-refinement/SKILL.md) (conversational phased flow).\n\n## Platform Requirements\n\n! GitHub as the SCM platform; the **GitHub CLI (`gh`)** must be installed and authenticated. The full pipeline plus the rehearsal target (`task release:e2e`) all dispatch through `gh`.\n\n## Branch-Protection Policy Guard\n\n! Before any Phase 1 state mutation, run the skill-level branch-policy guard documented in `task policy:show` / dual-invoke `deft verify:branch` (#746 / #747). Releases run on the configured base branch (default `master`), so the operator MUST be on the explicit-opt-in side of the policy before the pipeline starts writing files.\n\n**Preferred path — typed direct-commit policy opt-out (#1553).** For a release session on the default branch, prefer the audited typed flag over the emergency env-var bypass:\n\n```\ntask policy:allow-direct-commits -- --confirm\n```\n\nThis writes `plan.policy.allowDirectCommitsToMaster = true` on `xbrief/PROJECT-DEFINITION.xbrief.json` with a capability-cost disclosure. After the release completes (or if the session aborts), restore enforcement **and commit the restore in the same closeout** (#2623):\n\n```\ntask policy:enforce-branches\n# enforce flips the typed flag to false locally — the commit that lands that\n# flip cannot use the typed opt-in anymore. Scope the emergency env bypasses to\n# ONLY this closeout commit+push (do NOT export them for the whole session):\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 git add xbrief/PROJECT-DEFINITION.xbrief.json meta/policy-changes.log\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 git commit -m \"chore(policy): restore branch protection after vX.Y.Z\"\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 git push origin HEAD\n```\n\n⊗ Leave `allowDirectCommitsToMaster=true` on origin after publish. ⊗ Run `policy:enforce-branches` and leave the dirty restore under protection ON without committing (forces a follow-up PR — the v0.79.0 / #2619 failure mode).\n\n**Branch-guard probe (either path).** Regardless of which opt-out path you chose, confirm the guard passes before Phase 1 mutates state:\n\n```\ndeft verify:branch\n```\n\nor `task deft:verify:branch` when the consumer Taskfile include is present. Do not add a consumer `verify:branch` task. This is the canonical surface that surfaces the policy state to the operator before the pipeline starts writing files. The release pipeline's other safety surfaces (the dirty-tree guard, base-branch check, `task check` gate) remain independent of this check. (`task ci:local` is historical and removed.)\n\n**Emergency env-var bypass — narrow scope only (#1553).** `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is process-wide: every child process, nested test, and temporary repository spawned from the same shell inherits it. During the v0.43.0 release attempt, wrapping the entire `task release` invocation in this env var let the bypass leak into the Step 5 `task ci:local` preflight, which caused `TestWriteConsumerGitHooks_VendoredCommitBlocked_RealGit` to fail because the vendored test repo allowed a direct `master` commit the test expected the hook to block.\n\n- ! Prefer `task policy:allow-direct-commits -- --confirm` for release sessions instead of exporting `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the whole shell.\n- ⊗ Wrap `task release` or `task check` in `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` -- the env var is inherited by every subprocess and can produce false preflight failures before any release mutation. (`task ci:local` is historical; same leak class.)\n- ? If the env-var path is unavoidable, scope it to a **single** branch-guard probe only (e.g. `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 deft verify:branch`) and do NOT export it for the release session. The release pipeline itself passes the bypass only in scoped subprocess `env=` for its authorised commit/tag/push mutations (#867); operators MUST NOT mirror that pattern at the shell level.\n\nThe release pipeline's Step 9/10/11 git mutations carry the bypass in subprocess `env=` only (`the release pipeline subprocess env`, #867) so the parent shell stays clean. Operator-side env-var exports defeat that isolation.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (Phase 1 version-bump magnitude check, Phase 2 dry-run review `yes`/`back`/`quit`, Phase 5 optional `defer`/`rollback`/`Discuss` (happy path auto-publishes after draft QA)) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. Existing `back`/`quit` options remain valid; this contract simply adds `Discuss` as a peer alongside `Back`. The Discuss-pause semantic is documented verbatim in the contract -- implicit resumption is forbidden.\n\n## When to Use\n\n- User says \"release\", \"cut release\", \"v0.X.Y\", \"publish release\", \"ship a release\"\n- The framework's `[Unreleased]` CHANGELOG section is non-empty and the operator wants to cut a tagged release\n- A previous release rehearsal succeeded and the operator is ready for the production cut\n\n## Phase 1 — Pre-flight\n\n! Validate the local + remote state before any irreversible action.\n\n\n### Parallel prep — #1880 Gap D (#2692)\n\n! Phase 1 long steps (`task reconcile:issues -- --apply-lifecycle-fixes`, cache refresh when ritual-stale) and Phase 3 `task release:e2e` MUST be backgrounded or subagent-dispatched when the host supports it (Cursor: Task tool `run_in_background: true`), with progress surfaced via DONE/heartbeat — same ownership as review-cycle / merge-ready workers (#1880 Gap D). The operator conversation MUST stay interactive for version magnitude confirmation, `--summary`, and the Phase 2 dry-run `yes`/`back`/`quit` gate while prep runs. (`task ci:local` is historical and removed.)\n\n! **Checklist:** Phase 1 prep parallelized — long prep started in background before (or while) collecting version magnitude / summary / npm irrevocability disclosure.\n\n! On Windows PowerShell, do NOT wrap long task output in `Select-Object -Last` (it buffers until the process exits); stream to the terminal or log to a file and read incrementally. See `scm/github.md` § #2646 / Windows encoding guidance for related PS pitfalls.\n\n⊗ Foreground-block the operator chat on reconcile / `release:e2e` when background dispatch is available (#1880 Gap D / #2692).\n\n### Fixable check failure — file-and-merge before resume (#2859)\n\n! When **pipeline Step 5** fails on a **fixable product or test defect** (hang, failing test, validation bug — not operator env misconfiguration), the release cut MUST pause and route the blocker through normal issue → xBRIEF → feature branch → PR → merge before resuming Phase 1.\n\n? **Step 5 branch-coverage threshold misses** during `task release` (Vitest branch coverage below 85% with no other failure mode) are carved out to § Step 5 branch-coverage threshold — open-issue ledger hatch (#2866) below — not this file-and-merge path.\n\n**Required path:**\n1. File a GitHub issue with root cause, recurrence signature, and acceptance criteria.\n2. Ingest / promote / activate scope xBRIEF; implement on a feature branch with `drive-to: merge-ready`.\n3. Merge; confirm pipeline Step 5 is green for the failure mode.\n4. Resume the release cut from Phase 1 (re-run pipeline Step 5).\n\n⊗ Lead with an inline-only hotfix on the release branch / default branch without a tracked issue and merged PR.\n⊗ Suggest untracked `--skip-ci` or `--allow-skip-ci` without a **tracked issue number** as the first recovery when the failure is a clear, shippable bug.\n⊗ Continue the cut with \"raise timeouts,\" \"fix it here,\" or other shortcut theater before file-and-merge completes.\n\n? **`--skip-ci` / `--allow-skip-ci=#N` remains valid** only under explicit operator incident review with a **tracked issue** cited on the flag (Phase 4 contract). It is NOT a substitute for filing and merging a fixable defect discovered in Phase 1.\n\n**AGENTS.md bulk rejected (#2859):** Expanding `AGENTS.md` / `content/templates/agents-entry.md` with an always-on pin for this release-phase reminder was considered and **rejected**. This rule lives in the release skill (and optional lesson); do NOT add AGENTS.md / agents-entry bulk for it.\n\nSee [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Fixable check failure during release for the operator runbook and the existing `--allow-skip-ci=#N` incident contract.\n\n### Step 5 branch-coverage threshold — open-issue ledger hatch (#2866 / #3187)\n\n! When **`task release` Step 5** fails on Vitest coverage below the 85% goal, apply this hatch **only** when **branches** is the **sole** metric below 85% (hairline branch miss — lines, functions, and statements all ≥ 85%). Confirm via the Step 5 failure output or `task coverage:hotspots` before hatching. Do not treat `coverage/coverage-final.json` as live until [#4244](https://github.com/deftai/directive/issues/4244). If **any other metric** is also below 85%, or the failure is a hang / failing test / non-coverage defect, STOP — use § Fixable check failure — file-and-merge before resume (#2859) instead.\n\n**Runtime disclosure (#2573):** `--allow-coverage-debt=#N` sets vitest coverage thresholds to zero for the release Step 5 run (`vitest.config.ts`). The hatch is justified only for branch-only hairlines; the filed debt issue MUST require restoring **all four metrics** (lines, functions, branches, statements) to ≥ 85% before close.\n\n**Auto-hatch in `task release` Step 5 (#3187):** the pipeline classifies a non-zero Step 5 as `REAL_FAILURE` | `BRANCH_HAIRLINE` | `OTHER_COVERAGE` | `UNKNOWN` after **one** suite run.\n\n1. `REAL_FAILURE` | `OTHER_COVERAGE` | `UNKNOWN` → **fail closed** (no auto-issue). Route product defects via #2859.\n2. `BRANCH_HAIRLINE` + **any open** coverage-debt ledger entry → **fail closed** (\"restore coverage; close `#N` first\") — consecutive soft-pass ban (#2866).\n3. `BRANCH_HAIRLINE` + **empty** open debt ledger → **auto-file** `#N` with markers `coverage-debt` and `--allow-coverage-debt`, measured metrics, cut version, and acceptance (all four metrics ≥ 85%); mark Step 5 `PASS_WITH_DEBT(#N)`; **continue the cut without re-running vitest**. Loud stderr banner + cite `#N` in CHANGELOG / release notes.\n\n! **File before continue** — never soft-pass without a durable issue number.\n\n? Operators MAY still pass `--allow-coverage-debt=#N` manually (PowerShell-safe: `--allow-coverage-debt=N` or `--allow-coverage-debt=\"#N\"` — #2621) when re-running after a pre-filed debt issue.\n\n**SHA suite stamp (#3187, coordinates with #3188 check ordering):** after suite **green** or `PASS_WITH_DEBT`, write a local SHA-bound stamp under `.deft/release-suite-stamp.json` (gitignored). Re-entry at the **same clean HEAD** skips the suite; dirty tree or different HEAD invalidates the stamp. ⊗ CI never trusts the stamp (GHA has no committed stamp; `CI`/`GITHUB_ACTIONS` force miss).\n\n**Open-issue ledger (release-scoped only):**\n\n1. Check for an **open coverage-debt tracking issue** (unpaid hatch from a prior cut) — union all three probes and dedupe by issue number:\n   - **Marker search** (new-format debt issues):\n     ```\n     gh issue list --repo <owner>/<repo> --state open --search \"coverage-debt in:title,body\" --limit 20\n     gh issue list --repo <owner>/<repo> --state open --search \"allow-coverage-debt in:body\" --limit 20\n     ```\n   - **CHANGELOG citation scan** (legacy hatch issues filed before markers were mandatory): parse `CHANGELOG.md` `[Unreleased]` plus the last three `## [version]` sections for `--allow-coverage-debt=#N` / `allow-coverage-debt=#N` citations; for each `#N`, probe issue state via REST — `OPEN` (or unknown) counts as unpaid debt even when title/body lack the new markers (#2866).\n2. If **no open coverage-debt issue exists** → auto-hatch files `#N` (or operator files manually) with title prefix `coverage-debt:` and body containing both markers. The open `#N` remains WIP until coverage is restored and the issue is closed.\n3. If an **open coverage-debt issue from a prior hatch still exists** → ⊗ soft-pass again; restore real coverage (all four metrics ≥ 85%) and close the debt issue before the cut proceeds.\n\n**Framework-release-first (#3187):** auto-hatch applies to framework `task release` Step 5 (e.g. deftai/directive). Consumer expansion of auto-hatch via `plan.policy.coverageDebt` is reserved; consumer expansion is not implemented (#3314). Refuse when unset or off. Live hatch is `--allow-coverage-debt=#N` (#2866). Do not auto-file debt on the framework repo from consumer trees; consumer ledger is always the consumer repo.\n\n⊗ Auto-pass on a near-miss band without `#N` (#2573).\n⊗ Silent soft-pass with no tracked issue.\n⊗ File a debt issue without `coverage-debt` / `allow-coverage-debt` markers in title or body — the ledger query will miss it and permit a consecutive soft-pass (#2866).\n⊗ Use this carve-out when lines, functions, or statements are also below 85%, or for hangs, failing tests, or non-coverage Step 5 failures — those stay under #2859 file-and-merge.\n⊗ Treat file-debt-then-hatch as the default for ordinary PR / `task check` work outside a release cut — this hatch is release-scoped only.\n⊗ Trust a laptop suite stamp in CI or after HEAD/tree drift (#3187).\n\nSee [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Coverage debt hatch during release.\n\n### Routine vs hard cut for Step 5 (#2953)\n\n! Treat **hard cut** as the default: full Step 5 (`task check` + Vitest coverage) with no `--skip-ci`.\n\n~ Treat **routine cut** as the same full Step 5, sped up by default-excluding `.deft-scratch/` (and legacy `swarm-worktrees/`) from content/link/path/build-dist walks, plus pre-cut hygiene (green required checks on the tip SHA; prune stale `.deft-scratch/worktrees`).\n\n! Confirm required CI is green on the tip you will tag when aiming for a calm routine cut — green tip CI is a precondition, not a replacement for Step 5.\n\n⊗ Invent a silent lighter Step 5 that skips or soft-passes coverage without an explicit hatch (`--allow-coverage-debt=#N` for branch-only hairlines, or `--skip-ci` + `--allow-skip-ci=#N` for incidents). Silent soft-pass is forbidden in every mode.\n\n~ Prefer pruning abandoned worktrees / cutting from a clean clone over re-scanning scratch noise.\n\nSee [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Routine vs hard cut for Step 5 (#2953).\n\n\n~ **Frozen Go-installer bridge (#1912 / #1972 / #1987):** by default a release tag *above* the frozen line (the `LAST_GO_INSTALLER` constant in `packages/core/src/legacy-bridge/sot.ts`) will NOT rebuild the 6 Go binaries -- the CI `freeze-gate` job in `.github/workflows/release.yml` skips the build (the run stays green; npm still ships from the separate `npm-publish.yml`). If this release must rebuild the Go installer, follow the runbook in [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Frozen Go-installer bridge: roll `LAST_GO_INSTALLER` forward to the cut tag BEFORE tagging (pinning to the exact cut tag both releases the gate AND re-freezes at the new line), then see that section's \"After the release\" step for the re-pin.\n\n1. ! Verify the operator is on the configured base branch (default `master`) and the working tree is clean\n2. ! Confirm the next version number (`X.Y.Z`) with the user. Major / minor / patch decision flows from the `[Unreleased]` content (breaking change → major; new feature → minor; fix-only → patch)\n! After the version is confirmed, name the mint CLI for that version. The operator runs it immediately before Phase 4 (not now): `deft authz:grant -- --template release-publish --target <version> --confirm` plus typed `mint` on a real TTY. Do **not** wait for a live grant before Phase 3 — a grant for the cut version cannot satisfy rehearsal `target=0.0.1` in a clone with no `.deft/authz`, and a Phase-1 mint can expire (`1h`) during long e2e before production Step 10. ⊗ `task authz:grant` (not a Taskfile target). ⊗ Treat a live grant as a Phase 3 precondition.\n3. ! Inspect `[Unreleased]` content vs the proposed version bump. If a breaking change appears in `### Changed` / `### Removed` but only a patch is proposed, surface the mismatch and ask the user to choose\n4. ! Verify `gh auth status` reports authenticated (`task release` will refuse otherwise)\n5. ! **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 (`task reconcile:issues -- --apply-lifecycle-fixes`, 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\n6. ! **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 (`the release tag-availability gate`, 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\n7. ! **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.\n8. ! **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> --confirm` 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).\n9. ~ 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\n\n⊗ 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.\n\n⊗ Skip the xBRIEF-lifecycle-sync check (#734); the gate exists because operators consistently forget the manual `task scope:complete` move step. The v0.21.0 cut surfaced 13 stranded xBRIEFs (8 cycle-relevant + 5 historical residue) post-publish as the recurrence record this gate prevents. If `task release` reports `[3/13] Pre-flight xBRIEF lifecycle sync... FAIL (<count> mismatches; run task reconcile:issues -- --apply-lifecycle-fixes to fix)`, the canonical recovery is the apply-mode invocation -- `--allow-vbrief-drift` is reserved for cases where the operator has explicitly reviewed the drift and chosen to defer the lifecycle reconcile to the next refinement pass (e.g. an emergency hot-fix release).\n\n⊗ Skip the tag-availability check (#784); the gate exists because the legacy 12-step pipeline only invoked `git tag` at Step 9, after Steps 1-8 had already mutated state (CHANGELOG promoted, ROADMAP refreshed, dist built, release commit made locally). A duplicate-tag failure at Step 9 stranded the operator with an unpushed wrong-version commit + orphaned `dist/deft-<wrong>.zip` artifact + manual `git reset --hard` recovery (forbidden by AGENTS.md SCM rules without explicit permission). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01. If `task release` reports `[4/13] Pre-flight tag availability... FAIL (<surface> tag v<version> already exists ...)`, the canonical recovery is to choose a different version (the most likely cause is operator typo of a prior release).\n\n⊗ Hand-write a different one-line narrative for each of the three downstream surfaces (CHANGELOG / GitHub release / Slack) -- that drift is exactly the gap the `--summary` flag is designed to close. If the operator insists on per-audience tone, populate the canonical `--summary` ONCE here and document the deviation in the Phase 8 anti-pattern.\n\n## Phase 2 — Dry-run review\n\n! Invoke `task release -- <version> --dry-run --skip-tag --skip-release` and present the plan to the user. If Phase 1 collected an operator summary, also pass `--summary \"<text>\"` so the dry-run preview reflects the canonical narrative the operator just authored.\n\n```\ntask release -- <version> --dry-run --skip-tag --skip-release --summary \"<text>\"\n```\n\nThe 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.\n\n! 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).\n- `yes` (or `confirmed` / `approve`) → proceed to Phase 3\n- `back` → return to Phase 1 for re-validation (e.g. user wants to amend the version or `[Unreleased]` content)\n- `quit` → abort the workflow cleanly; no state changes\n\n⊗ Skip the dry-run preview. The dry-run is the operator's last opportunity to catch a bad version number, malformed CHANGELOG, or wrong base branch before the pipeline starts writing files.\n\n## Phase 3 — E2E sanity\n\n! Invoke `task release:e2e` against an auto-created temp repo to verify the full pipeline shape works end-to-end before touching the real repo.\n\n! **#1880 Gap D (#2692):** `task release:e2e` is a long-running step — MUST background / subagent-dispatch it when the host supports it so Phase 2 confirmation and other human gates stay interactive. Do not wrap its output in PowerShell `Select-Object -Last`.\n\n```\ntask release:e2e\n```\n\nThe harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke-test rehearsal, and **by default keeps** the temp repo (#2572). Stderr always includes the full `owner/slug` and a copy-pasteable manual-cleanup command (`gh repo delete <owner>/<slug> --yes`). Privileged environments (CI or an operator with `delete_repo`) MAY pass `task release:e2e -- --destroy-repo` to attempt auto-delete; destroy failure emits a WARN and does **not** block Phase 4 when the rehearsal succeeded.\n\n! After Phase 3, the agent MUST NOT retry or escalate temp-repo deletion. Include any leftover temp repo(s) in the phase summary for the operator to clean up manually.\n\n! Treat a non-zero exit from `task release:e2e` as a hard refusal to proceed to Phase 4. Surface the diagnostic and ask whether to retry (return to Phase 1) or stop (`quit`).\n\n! Rehearsal uses sentinel version `0.0.1` on a throwaway repo. The landed rehearsal exemption lets `task release:e2e` reach npm dry-run without a `release-publish` grant. ⊗ Ask the operator to mint `0.0.1`. ⊗ Wait for a live grant before Phase 3. Mint remains immediately before Phase 4.\n\n? **Skip allowed** when the operator has just run `task release:e2e` successfully against the same branch in the past 30 minutes. Note the prior run timestamp in the user-facing summary.\n\n! **`task release:e2e` now also rehearses the npm publish (#1910).** Unless `--skip-npm` is passed (or `npm` is absent from PATH, which soft-skips), the rehearsal runs `npm publish --dry-run --access public` for all four `@deftai/directive*` packages against the throwaway clone in dependency order (types -> core -> content -> cli), after `pnpm install` + `pnpm -w run build` and a version-alignment pass. This catches a broken `files` allowlist, a version-drift bug, or a dependency-order error BEFORE the real `v*` tag fires the publish workflow -- without touching the real registry. The install+build exceeds the <90s fast budget, so pass `task release:e2e -- --skip-npm` when you only need the GitHub-pipeline shape check.\n\n! **Tag -> npm coupling + irrevocability (#1910, #1972, #2002).** A `v<version>` tag is a TWO-channel action: the GitHub release (this skill's pipeline) AND `.github/workflows/npm-publish.yml`, which runs in a SEPARATE workflow that does NOT block the GitHub release and is NOT draft-gated. The npm workflow derives the published version from the tag (`${GITHUB_REF_NAME#v}`); this skill owns the version chosen in Phase 1. These MUST stay consistent -- the tag you cut IS the npm version that ships; there is no separate npm version bump. **npm publish is irrevocable** (#1972): once the tag fires, packages are live on npm and cannot be unpulled; `task release:rollback` does NOT retract npm (forward-only recovery). A red npm job on a green GitHub release means the npm channel did not ship (verify in Phase 5/7).\n\n## Phase 4 — Production draft\n\n! **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> --confirm` 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.\n\n! 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.\n\n⊗ Use `--skip-ci` on a production cut except under explicit operator incident review — it skips Step 5 vitest coverage and ships untested npm builds (#2652). When unavoidable, pass `--allow-skip-ci=#N` citing the tracked issue; Step 5 emits a loud WARN. See [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Vitest coverage hang recovery. The next patch after the hang fix must cut without `--skip-ci`.\n\n```\ntask release -- <version> --summary \"<text>\"\n```\n\nPer #716 default-draft hardening, this lands the release as a `--draft` on the real repo. Binaries upload via release.yml CI, but the artifact is NOT yet visible to consumers. The operator-authored summary becomes part of the promoted `CHANGELOG.md [<version>]` section AND the GitHub release body (auto-pickup via `_section_for_version`). The same wording is the canonical source for the Phase 8 Slack `*Summary*:` slot.\n\n! **Maintainer-mode release notes auto-lead with an \"Upgrading from an older version?\" banner (#1413).** When the cut targets the canonical framework repo (`deftai/directive`), `task release` Step 12 prepends the banner from the editable template at `.github/release-notes/upgrade-banner.md` to the notes passed to `gh release create` (via `_prepend_upgrade_banner`). The banner points consumers at the canonical `deft-install --yes --upgrade --repo-root . --json` upgrade command and #1411. This is **GitHub-release-body-only** -- it is NEVER injected into `CHANGELOG.md`, so the CHANGELOG section and the release body intentionally differ by this leading block. To change the wording, edit the template file; do not hand-edit the published release body. **Consumer-mode releases (any non-`deftai/directive` repo) are unaffected** -- a downstream project that vendors the release pipeline never inherits deft's upgrade guidance. A missing/unreadable template degrades gracefully (notes ship without the banner; the cut is never blocked).\n\n! **Verify isDraft within 5 seconds; flip immediately if not (#724).** Immediately after `gh release create --draft` returns success, `task release` Step 11 polls `gh release view v<version> --json isDraft` up to 5 times at 1-second intervals. If the release exists with `isDraft=false`, the pipeline auto-flips it via `gh release edit v<version> --draft=true` and emits a `WARNING: release landed as public; flipping to draft (defense-in-depth, see #724)` line. This closes the ~90-second public-exposure window observed during the v0.21.0 cut where a manual recovery created a public release before the operator noticed and flipped it. The verify gate is defense in depth even when `--draft` was passed correctly: it catches the case where `gh release create` partially succeeded (release record written, error returned) AND the operator-error variant where an alternate code path sent the release without `--draft`. A release-not-found-within-budget result emits a WARN and does NOT fail the pipeline (release.yml CI may still be processing).\n\n! Wait for `task release` to exit 0 before continuing. A non-zero exit means the pipeline halted partway through; consult Phase 7's `task release:rollback` recovery before retrying.\n\n⊗ Pass `--no-draft` here unless the operator has explicitly opted into direct-publish (e.g. automated security patch). The default-draft contract is the foundation of the safety hardening surface.\n\n⊗ Skip the post-create verify-isDraft gate -- the gate is the only reliable safety net against \"create call exited 0 but the release somehow landed as public\" variants (#724). If `task release` is invoked manually outside the canonical `task release` flow, the operator MUST run `gh release view v<version> --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` BEFORE handing off to Phase 5.\n\n## Phase 5 — GitHub draft QA (optional; NOT the npm authority gate)\n\n! After `task release` exits 0, QA the **GitHub draft release** only. npm packages typically **already shipped** when the tag push in Phase 4 fired `.github/workflows/npm-publish.yml` (#1972, #2002). Phase 5 is NOT a \"user-only authority before going live\" gate for the release as a whole -- it is optional draft QA for GitHub assets, notes, and binaries.\n\n1. ! **Verify npm publish status FIRST (in parallel with draft inspection).** Run `gh run list --workflow=npm-publish.yml --repo <owner>/<repo> --limit 5` and confirm the tag run for `v<version>` is `completed`/`success`. If npm failed, surface immediately -- the GitHub draft QA is secondary to a red npm channel.\n2. ! Run `gh release view v<version> --json url,name,body,assets,isDraft --repo <owner>/<repo>` and present the output to the user\n3. ! Surface the asset list (size + filename) so the user can verify binaries uploaded correctly\n4. ! Surface the auto-generated release notes (or the CHANGELOG section that was promoted into the release body)\n\n### Happy path (default when npm succeeded and draft assets look correct)\n\n! When the npm workflow succeeded AND draft assets/notes pass inspection, **auto-proceed to Phase 6 Publish branch** -- run `task release:publish -- <version>` without a redundant human publish prompt (#2002). npm already shipped at tag push; waiting for a separate `publish` confirmation does not protect the npm channel.\n\n? **Operator override:** if the operator wants to hold the GitHub release in draft (e.g. embargo, last-minute notes edit), they MAY say `defer` before auto-publish runs.\n\n### Exception paths (operator-initiated)\n\n- `rollback` → proceed to Phase 6 (Rollback branch). **Reminder:** rollback unwinds the GitHub release only; npm packages already published at tag push are NOT retracted (#1972).\n- `defer` → halt and exit. Surface the draft URL so the operator can return later with `task release:publish -- <version>` or `task release:rollback -- <version>`.\n\n⊗ Treat Phase 5 as the npm publish-authority gate -- npm ships at tag push (Phase 4), not at `task release:publish`. A human `publish` prompt here is redundant when npm already succeeded and only delays flipping the GitHub draft to public.\n⊗ Skip npm workflow verification in Phase 5 and defer it entirely to post-publish Phase 7 -- npm status MUST be checked before or in parallel with the GitHub publish flip.\n\n## Phase 6 — Publish or rollback\n\n! Branch on the Phase 5 outcome. The happy path auto-enters the Publish branch when npm succeeded and draft QA passed (#2002).\n\n### Publish branch (happy path auto-run, or resumed after `defer`)\n\n```\ntask release:publish -- <version>\n```\n\nThe companion script flips `--draft=false`, then re-reads the release to verify `isDraft == false` actually flipped. State machine:\n- `draft` found → flip to public; verify; exit 0\n- already `published` → exit 0 no-op (idempotent re-runs are safe)\n- `not-found` → exit 1 (cannot publish a missing release)\n- gh-error → exit 1 with diagnostic\n\n! Wait for `task release:publish` to exit 0 before continuing. On the happy path this runs immediately after Phase 5 draft QA without a separate human publish prompt.\n\n### Rollback branch (user said `rollback`)\n\n```\ntask release:rollback -- <version>\n```\n\nThe state-aware unwind detects the post-release state and applies the matching tiered recovery. Time-windowed download-count guard:\n- release age `< 5 min` → threshold = 0 (rollback safe; nobody noticed yet)\n- release age `5-30 min` → threshold = max(`--allow-low-downloads`, 10) (filters bot fetches)\n- release age `> 30 min` → refuse without `--allow-data-loss`\n\nThree escape hatches (escalating warnings):\n- `--allow-low-downloads N` -- accept up to N downloads\n- `--allow-data-loss` -- accept any count (consumer impact)\n- `--force-strict-0` -- require exactly 0 regardless of release age\n\nRace-condition mitigation: `download_count` is double-read with a 5s sleep between reads; rollback only proceeds if both reads agree below threshold.\n\n! When the guard refuses, surface the recommendation to the user: rollback is risky on a released artifact with non-zero downloads. Prefer the **hot-fix path** (cut the next patch with a withdrawal note in `[Unreleased]/Changed` rather than deleting the broken release).\n\n! **`task release:rollback` does NOT retract npm (#1972, #2002).** Rollback unwinds GitHub release state (draft/public, tag, assets) only. npm packages published at tag push remain on the registry irrevocably. Recovery is forward-only: deprecate the bad version, move a dist-tag, or ship a patch release.\n\n## Phase 7 — Post-publish verification\n\n! Only enter Phase 7 if Phase 6 took the Publish branch (rollback branch ends here with the unwind log).\n\n1. ! **Re-verify npm publish landed (#1910, #1909, #2002).** Phase 5 checked workflow status before the GitHub publish flip; Phase 7 confirms registry truth AFTER `task release:publish`. For each of `@deftai/directive-types`, `@deftai/directive-core`, `@deftai/directive-content`, and `@deftai/directive`, run `npm view <pkg>@<version> version --prefer-online` (expect `<version>`) and confirm provenance on the npm page. A green GitHub release with missing npm packages means consumers cannot `npm i -g @deftai/directive@<version>` -- escalate immediately. (Real-registry verification depends on #1909's credential; until then verify workflow-run status and flag credential gaps.) Reading one package is not sufficient — sibling publish is not atomic.\n2. ! **Report local-vs-released CLI drift (#3753).** After the all-four registry check, print the local global CLI version, the released version, whether they match, and the exact remediation `npm i -g @deftai/directive@<version> --prefer-online`. Compare versions with `checkActiveCliAgainstTarget` (not bare `deft --version`) so a PATH-shadowed install cannot report success (#3233). If some siblings are visible and others are not, report **still propagating**. If none are visible after this wait, report **publish incomplete**. `task release` already emitted a non-blocking snapshot of the same report at pipeline completion (single probe, no wait — Step 13 returns before `npm-publish.yml` is green). Phase 7 is the bounded wait. ⊗ Run `npm i -g`. The report must not fail the release.\n3. ! Verify GitHub auto-closed the discrete-task issue(s) referenced via `Closes #N` in the release notes (mirrors `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 2)\n4. ! Run `gh issue view <N> --json state --jq .state` for each closed issue. If any didn't auto-close, manually close with `gh issue close <N> --comment \"Closed by release v<version> (squash auto-close did not trigger)\"` (Layer 1, #167)\n5. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)\n6. ! Verify binaries are downloadable from the public release URL: `gh release view v<version> --json assets --jq '.assets[].url'` and curl one to confirm 200 OK\n7. ! For any umbrella / staying-OPEN issue (`Refs #N`) referenced in the release notes, run the Layer 3 reopen sweep from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1: any protected issue that auto-closed MUST be reopened with a comment citing #701\n\n⊗ Skip the post-publish verification. The closing-keyword false-positive (Layer 1 / Layer 2 / Layer 3) and the incremental-renderer-drift (#641, #614) are exactly the kind of issues that surface only AFTER a release is public.\n\n## Phase 8 — Slack announcement\n\n! Generate the canonical Slack release announcement and present it to the user for copy-paste, re-using the template from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 5.\n\nThe announcement block MUST include:\n\n```\n:rocket: *deft v<version>* -- <release title>\n\n*Summary*: <one-sentence description of the release scope>\n\n*Key Changes*:\n- <bullet per significant change, 3-5 items max>\n\n*Stats*: 1 release | ~<duration> elapsed | <N> commits since v<previous>\n*Release*: <GitHub release URL>\n```\n\n! Populate version from the freshly-published `gh release view v<version>` output. Populate release title from the CHANGELOG section heading (or the GitHub release title). Summarize key changes from the promoted `[Unreleased]` -> `[<version>]` CHANGELOG section (NOT raw commit messages). Populate stats from `git log v<previous>..v<version> --oneline | wc -l`.\n\n! Populate the `*Summary*:` slot VERBATIM from the operator-authored blockquote at the top of the CHANGELOG `[<version>]` section (the line beginning with `> ` immediately after the `## [<version>] - <date>` heading). The Phase 1 prompt + Phase 4 `--summary` flag exist precisely so this populate step is mechanical -- one canonical narrative authored once at Phase 1, propagated through Phase 4 promotion, and copy-pasted here without re-authoring. If the CHANGELOG section has no blockquote (operator skipped the Phase 1 prompt), generate a one-sentence summary from the `### Added` / `### Changed` bullets and surface to the operator that this is a regenerated narrative (NOT canonical) so they can decide whether to amend the CHANGELOG before publishing.\n\n! Present the block as a code-fenced snippet the user can copy directly. Do NOT post to Slack from inside this skill -- the user owns the actual broadcast.\n\n## Skill Completion\n\n! When Phase 8 completes (or when Phase 5 took the `defer` / `quit` path, or when Phase 6 completed the rollback branch), explicitly confirm skill exit:\n\n```\ndeft-directive-release complete -- exiting skill.\nNext: <one-line guidance>\n```\n\nWhere `<one-line guidance>` is one of:\n- \"release v<version> live -- monitor consumer reports for ~24h before cutting v<next>\"\n- \"release v<version> rolled back -- the underlying defect needs a hot-fix in the next CHANGELOG entry\"\n- \"release deferred -- resume by running `task release:publish -- <version>` (GitHub only; npm already shipped at tag push) or `task release:rollback -- <version>` (GitHub unwind only; npm is forward-recovery) when ready\"\n\n⊗ Exit silently without confirming completion or providing next-step guidance.\n\n## Anti-Patterns\n\n- ⊗ Foreground-block the operator chat on Phase 1 long prep (`reconcile:issues`, cache refresh) or Phase 3 `release:e2e` when background / subagent dispatch is available (#1880 Gap D / #2692) — the interactive channel must stay free for version confirmation, `--summary`, and the Phase 2 dry-run gate\n- ⊗ Wrap long release-prep task output in PowerShell `Select-Object -Last` — it buffers until exit and makes the session look hung (#2692)\n- ⊗ 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\n- ⊗ 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\n- ⊗ Pass `--no-draft` to `task release` without explicit operator opt-in -- the default-draft contract is the foundation of the safety hardening surface\n- ⊗ 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)\n- ⊗ Delete the `release:publish` draft-flip closed-verb check as a substitute for the tag-push gate -- placement, not strength; both stay (#3527 / #1095)\n- ⊗ 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\n- ⊗ Expect `task release:rollback` to retract npm packages -- rollback is GitHub-only; npm recovery is forward-only (deprecate / dist-tag / patch)\n- ⊗ 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\n- ⊗ Use `--allow-data-loss` without first reading the script docstring's hot-fix-path recommendation -- the flag is an explicit acknowledgment of consumer impact, not a default\n- ⊗ Skip the Phase 7 Layer 3 reopen sweep -- protected umbrellas can auto-close on a release-merge squash even when the release notes use `Refs #N` only\n- ⊗ Run `npm i -g` from the release pipeline or Phase 7 (#3753) -- report local-vs-released drift only; no global mutation\n- ⊗ Trust bare `deft --version` after a cut -- use `checkActiveCliAgainstTarget` so a PATH-shadowed install cannot report success (#3233 / #3753)\n- ⊗ Treat a missing sibling package as a failed publish without distinguishing still-propagating from publish-incomplete (#3753)\n- ⊗ Post the Phase 8 Slack announcement directly from this skill -- the user owns the broadcast; the skill only generates the template\n- ⊗ Hardcode `master` as the base branch -- delegate to the configured base branch from `task release --base-branch <branch>`\n- ⊗ Skip the post-create verify-isDraft gate (#724) -- a successful `gh release create` exit code does NOT prove the release actually landed in draft state; the 5-second poll-and-flip gate in `task release` Step 11 is the only safety net against operator-error variants and partial-success races, and any manual recovery path that bypasses `task release` MUST run `gh release view --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` before handing off to Phase 5\n- ⊗ Manually rewrite the Phase 8 Slack `*Summary*:` line to deviate from the CHANGELOG `[<version>]` blockquote -- the canonical narrative is authored ONCE at Phase 1 via `--summary` and propagates verbatim across all three audiences (CHANGELOG / GitHub release body / Slack). Per-audience hand-edits create documentation drift that the deterministic `--summary` flow is designed to prevent. If the operator wants Slack-specific tone, fold it into the canonical Phase 1 wording before passing `--summary`, OR amend the CHANGELOG blockquote BEFORE Phase 8 so all three surfaces stay aligned\n- ⊗ Export `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` or `DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1` for the entire release session or wrap `task release` / `task check` in them (#1553) -- the env vars are process-wide and leak into nested tests and temporary repos, producing false preflight failures. Prefer `task policy:allow-direct-commits -- --confirm` and restore with `task policy:enforce-branches` after the cut (closeout commit+push may use a **scoped** prefix of both `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` and `DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1` on those three git commands only — see Branch-Protection Policy Guard, #2623)\n- ⊗ `task authz:grant` — not a Taskfile target. Name `deft authz:grant -- --template release-publish --target <version> --confirm`.\n- ⊗ Wait for a live grant before Phase 3, or ask the operator to mint rehearsal `0.0.1` — mint the confirmed cut version immediately before Phase 4.\n- ⊗ Pass `--allow-coverage-debt=#N` unquoted on Windows PowerShell (#2621) -- `#` starts a comment and silently drops the issue number. Use `--allow-coverage-debt=N` or `--allow-coverage-debt=\"#N\"`\n- ⊗ Soft-pass coverage debt while an **open** coverage-debt issue from a prior hatch still exists (#2866 / #2573 / #3187) -- restore real branch coverage >= 85% and close the debt issue before reusing `--allow-coverage-debt` or expecting auto-hatch; the ledger is open GitHub issues, not prior CHANGELOG citations (#2618 superseded by open-issue ledger)\n- ⊗ Re-run the full Step 5 suite after a legal branch-only hairline when auto-hatch already filed `#N` and continued (`PASS_WITH_DEBT`) — that is the ceremony tax #3187 removes\n- ⊗ Trust `.deft/release-suite-stamp.json` in CI or after HEAD/tree drift (#3187)\n",
+      "body": "# Deft Directive Release\n\nStructured 8-phase workflow for cutting a v0.X.Y release of the deft framework. Operationalizes the `task release` / `task release:publish` / `task release:rollback` / `task release:e2e` surface introduced in #716 (safety hardening of #74).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-swarm](../deft-directive-swarm/SKILL.md) Phase 6 Step 5 (Slack announcement template re-used by Phase 8 below) | [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) (user-gate pattern) | [deft-directive-refinement](../deft-directive-refinement/SKILL.md) (conversational phased flow).\n\n## Platform Requirements\n\n! GitHub as the SCM platform; the **GitHub CLI (`gh`)** must be installed and authenticated. The full pipeline plus the rehearsal target (`task release:e2e`) all dispatch through `gh`.\n\n## Primary occupancy — trusted producer (#4266)\n\n! Mutation `session:start` on a contended primary MUST pass `--primary-claim-exception=release-cut` **before any state-changing preflight command** (`task policy:allow-direct-commits -- --confirm`, reconcile, cache refresh). Occupancy already implements that exception; session:start CLI argv is the trusted producer.\n\n```\ndeft session:start --primary-claim-exception=release-cut\n```\n\nor `task session:start -- --primary-claim-exception=release-cut`. Sibling values: `policy-restore`, `operator-default-branch`. Unknown values fail closed (exit 2). `--read-only` never claims.\n\n⊗ Invent a process-wide env producer for the exception.\n⊗ Name the exception in spawn JSON.\n⊗ Run `task policy:allow-direct-commits` (or any other mutation) before mutation `session:start --primary-claim-exception=release-cut` on a contended primary.\n\n## Branch-Protection Policy Guard\n\n! Before any Phase 1 state mutation, run the skill-level branch-policy guard documented in `task policy:show` / dual-invoke `deft verify:branch` (#746 / #747). Releases run on the configured base branch (default `master`), so the operator MUST be on the explicit-opt-in side of the policy before the pipeline starts writing files.\n\n**Preferred path — typed direct-commit policy opt-out (#1553).** For a release session on the default branch, prefer the audited typed flag over the emergency env-var bypass:\n\n```\ntask policy:allow-direct-commits -- --confirm\n```\n\nThis writes `plan.policy.allowDirectCommitsToMaster = true` on `xbrief/PROJECT-DEFINITION.xbrief.json` with a capability-cost disclosure. After the release completes (or if the session aborts), restore enforcement **and commit the restore in the same closeout** (#2623):\n\n```\ntask policy:enforce-branches\n# enforce flips the typed flag to false locally — the commit that lands that\n# flip cannot use the typed opt-in anymore. Scope the emergency env bypasses to\n# ONLY this closeout commit+push (do NOT export them for the whole session):\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 git add xbrief/PROJECT-DEFINITION.xbrief.json meta/policy-changes.log\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 git commit -m \"chore(policy): restore branch protection after vX.Y.Z\"\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 git push origin HEAD\n```\n\n⊗ Leave `allowDirectCommitsToMaster=true` on origin after publish. ⊗ Run `policy:enforce-branches` and leave the dirty restore under protection ON without committing (forces a follow-up PR — the v0.79.0 / #2619 failure mode).\n\n**Branch-guard probe (either path).** Regardless of which opt-out path you chose, confirm the guard passes before Phase 1 mutates state:\n\n```\ndeft verify:branch\n```\n\nor `task deft:verify:branch` when the consumer Taskfile include is present. Do not add a consumer `verify:branch` task. This is the canonical surface that surfaces the policy state to the operator before the pipeline starts writing files. The release pipeline's other safety surfaces (the dirty-tree guard, base-branch check, `task check` gate) remain independent of this check. (`task ci:local` is historical and removed.)\n\n**Emergency env-var bypass — narrow scope only (#1553).** `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is process-wide: every child process, nested test, and temporary repository spawned from the same shell inherits it. During the v0.43.0 release attempt, wrapping the entire `task release` invocation in this env var let the bypass leak into the Step 5 `task ci:local` preflight, which caused `TestWriteConsumerGitHooks_VendoredCommitBlocked_RealGit` to fail because the vendored test repo allowed a direct `master` commit the test expected the hook to block.\n\n- ! Prefer `task policy:allow-direct-commits -- --confirm` for release sessions instead of exporting `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the whole shell.\n- ⊗ Wrap `task release` or `task check` in `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` -- the env var is inherited by every subprocess and can produce false preflight failures before any release mutation. (`task ci:local` is historical; same leak class.)\n- ? If the env-var path is unavoidable, scope it to a **single** branch-guard probe only (e.g. `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 deft verify:branch`) and do NOT export it for the release session. The release pipeline itself passes the bypass only in scoped subprocess `env=` for its authorised commit/tag/push mutations (#867); operators MUST NOT mirror that pattern at the shell level.\n\nThe release pipeline's Step 9/10/11 git mutations carry the bypass in subprocess `env=` only (`the release pipeline subprocess env`, #867) so the parent shell stays clean. Operator-side env-var exports defeat that isolation.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (Phase 1 version-bump magnitude check, Phase 2 dry-run review `yes`/`back`/`quit`, Phase 5 optional `defer`/`rollback`/`Discuss` (happy path auto-publishes after draft QA)) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. Existing `back`/`quit` options remain valid; this contract simply adds `Discuss` as a peer alongside `Back`. The Discuss-pause semantic is documented verbatim in the contract -- implicit resumption is forbidden.\n\n## When to Use\n\n- User says \"release\", \"cut release\", \"v0.X.Y\", \"publish release\", \"ship a release\"\n- The framework's `[Unreleased]` CHANGELOG section is non-empty and the operator wants to cut a tagged release\n- A previous release rehearsal succeeded and the operator is ready for the production cut\n\n## Phase 1 — Pre-flight\n\n! Validate the local + remote state before any irreversible action.\n\n### Parallel prep — #1880 Gap D (#2692)\n\n! Phase 1 long steps (`task reconcile:issues -- --apply-lifecycle-fixes`, cache refresh when ritual-stale) and Phase 3 `task release:e2e` MUST be backgrounded or subagent-dispatched when the host supports it (Cursor: Task tool `run_in_background: true`), with progress surfaced via DONE/heartbeat — same ownership as review-cycle / merge-ready workers (#1880 Gap D). The operator conversation MUST stay interactive for version magnitude confirmation, `--summary`, and the Phase 2 dry-run `yes`/`back`/`quit` gate while prep runs. (`task ci:local` is historical and removed.)\n\n! **Checklist:** Phase 1 prep parallelized — long prep started in background before (or while) collecting version magnitude / summary / npm irrevocability disclosure.\n\n! On Windows PowerShell, do NOT wrap long task output in `Select-Object -Last` (it buffers until the process exits); stream to the terminal or log to a file and read incrementally. See `scm/github.md` § #2646 / Windows encoding guidance for related PS pitfalls.\n\n⊗ Foreground-block the operator chat on reconcile / `release:e2e` when background dispatch is available (#1880 Gap D / #2692).\n\n### Orientation-dirty / check-class stale-by-drift (#4399)\n\n! Treat `[deft orientation] cache_fresh: dirty` or check-class `verify:cache-fresh` stale-by-drift as a hard Phase 1 preflight, distinct from ritual-stale (gated ritual age / compact stale). The parallel-prep ritual-stale cache refresh does not cover this class. Run `deft cache fetch-all --source github-issue --repo <owner>/<repo>` before `task release`. Skip-drift gated-verify green is not cache-ready.\n\n⊗ Proceed to `task release` when session:start printed `cache_fresh: dirty` or check-class `verify:cache-fresh` (no `--skip-drift-probe`) reports stale-by-drift.\n\n\n### Fixable check failure — file-and-merge before resume (#2859)\n\n! When **pipeline Step 5** fails on a **fixable product or test defect** (hang, failing test, validation bug — not operator env misconfiguration), the release cut MUST pause and route the blocker through normal issue → xBRIEF → feature branch → PR → merge before resuming Phase 1.\n\n? **Step 5 branch-coverage threshold misses** during `task release` (Vitest branch coverage below 85% with no other failure mode) are carved out to § Step 5 branch-coverage threshold — open-issue ledger hatch (#2866) below — not this file-and-merge path.\n\n**Required path:**\n1. File a GitHub issue with root cause, recurrence signature, and acceptance criteria.\n2. Ingest / promote / activate scope xBRIEF; implement on a feature branch with `drive-to: merge-ready`.\n3. Merge; confirm pipeline Step 5 is green for the failure mode.\n4. Resume the release cut from Phase 1 (re-run pipeline Step 5).\n\n⊗ Lead with an inline-only hotfix on the release branch / default branch without a tracked issue and merged PR.\n⊗ Suggest untracked `--skip-ci` or `--allow-skip-ci` without a **tracked issue number** as the first recovery when the failure is a clear, shippable bug.\n⊗ Continue the cut with \"raise timeouts,\" \"fix it here,\" or other shortcut theater before file-and-merge completes.\n\n? **`--skip-ci` / `--allow-skip-ci=#N` remains valid** only under explicit operator incident review with a **tracked issue** cited on the flag (Phase 4 contract). It is NOT a substitute for filing and merging a fixable defect discovered in Phase 1.\n\n**AGENTS.md bulk rejected (#2859):** Expanding `AGENTS.md` / `content/templates/agents-entry.md` with an always-on pin for this release-phase reminder was considered and **rejected**. This rule lives in the release skill (and optional lesson); do NOT add AGENTS.md / agents-entry bulk for it.\n\nSee [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Fixable check failure during release for the operator runbook and the existing `--allow-skip-ci=#N` incident contract.\n\n### Step 5 branch-coverage threshold — open-issue ledger hatch (#2866 / #3187)\n\n! When **`task release` Step 5** fails on Vitest coverage below the 85% goal, apply this hatch **only** when **branches** is the **sole** metric below 85% (hairline branch miss — lines, functions, and statements all ≥ 85%). Confirm via the Step 5 failure output or `task coverage:hotspots` before hatching. Do not treat `coverage/coverage-final.json` as live until [#4244](https://github.com/deftai/directive/issues/4244). If **any other metric** is also below 85%, or the failure is a hang / failing test / non-coverage defect, STOP — use § Fixable check failure — file-and-merge before resume (#2859) instead.\n\n**Runtime disclosure (#2573):** `--allow-coverage-debt=#N` sets vitest coverage thresholds to zero for the release Step 5 run (`vitest.config.ts`). The hatch is justified only for branch-only hairlines; the filed debt issue MUST require restoring **all four metrics** (lines, functions, branches, statements) to ≥ 85% before close.\n\n**Auto-hatch in `task release` Step 5 (#3187):** the pipeline classifies a non-zero Step 5 as `REAL_FAILURE` | `BRANCH_HAIRLINE` | `OTHER_COVERAGE` | `UNKNOWN` after **one** suite run.\n\n1. `REAL_FAILURE` | `OTHER_COVERAGE` | `UNKNOWN` → **fail closed** (no auto-issue). Route product defects via #2859.\n2. `BRANCH_HAIRLINE` + **any open** coverage-debt ledger entry → **fail closed** (\"restore coverage; close `#N` first\") — consecutive soft-pass ban (#2866).\n3. `BRANCH_HAIRLINE` + **empty** open debt ledger → **auto-file** `#N` with markers `coverage-debt` and `--allow-coverage-debt`, measured metrics, cut version, and acceptance (all four metrics ≥ 85%); mark Step 5 `PASS_WITH_DEBT(#N)`; **continue the cut without re-running vitest**. Loud stderr banner + cite `#N` in CHANGELOG / release notes.\n\n! **File before continue** — never soft-pass without a durable issue number.\n\n? Operators MAY still pass `--allow-coverage-debt=#N` manually (PowerShell-safe: `--allow-coverage-debt=N` or `--allow-coverage-debt=\"#N\"` — #2621) when re-running after a pre-filed debt issue.\n\n**SHA suite stamp (#3187, coordinates with #3188 check ordering):** after suite **green** or `PASS_WITH_DEBT`, write a local SHA-bound stamp under `.deft/release-suite-stamp.json` (gitignored). Re-entry at the **same clean HEAD** skips the suite; dirty tree or different HEAD invalidates the stamp. ⊗ CI never trusts the stamp (GHA has no committed stamp; `CI`/`GITHUB_ACTIONS` force miss).\n\n**Open-issue ledger (release-scoped only):**\n\n1. Check for an **open coverage-debt tracking issue** (unpaid hatch from a prior cut) — union all three probes and dedupe by issue number:\n   - **Marker search** (new-format debt issues):\n     ```\n     gh issue list --repo <owner>/<repo> --state open --search \"coverage-debt in:title,body\" --limit 20\n     gh issue list --repo <owner>/<repo> --state open --search \"allow-coverage-debt in:body\" --limit 20\n     ```\n   - **CHANGELOG citation scan** (legacy hatch issues filed before markers were mandatory): parse `CHANGELOG.md` `[Unreleased]` plus the last three `## [version]` sections for `--allow-coverage-debt=#N` / `allow-coverage-debt=#N` citations; for each `#N`, probe issue state via REST — `OPEN` (or unknown) counts as unpaid debt even when title/body lack the new markers (#2866).\n2. If **no open coverage-debt issue exists** → auto-hatch files `#N` (or operator files manually) with title prefix `coverage-debt:` and body containing both markers. The open `#N` remains WIP until coverage is restored and the issue is closed.\n3. If an **open coverage-debt issue from a prior hatch still exists** → ⊗ soft-pass again; restore real coverage (all four metrics ≥ 85%) and close the debt issue before the cut proceeds.\n\n**Framework-release-first (#3187):** auto-hatch applies to framework `task release` Step 5 (e.g. deftai/directive). Consumer expansion of auto-hatch via `plan.policy.coverageDebt` is reserved; consumer expansion is not implemented (#3314). Refuse when unset or off. Live hatch is `--allow-coverage-debt=#N` (#2866). Do not auto-file debt on the framework repo from consumer trees; consumer ledger is always the consumer repo.\n\n⊗ Auto-pass on a near-miss band without `#N` (#2573).\n⊗ Silent soft-pass with no tracked issue.\n⊗ File a debt issue without `coverage-debt` / `allow-coverage-debt` markers in title or body — the ledger query will miss it and permit a consecutive soft-pass (#2866).\n⊗ Use this carve-out when lines, functions, or statements are also below 85%, or for hangs, failing tests, or non-coverage Step 5 failures — those stay under #2859 file-and-merge.\n⊗ Treat file-debt-then-hatch as the default for ordinary PR / `task check` work outside a release cut — this hatch is release-scoped only.\n⊗ Trust a laptop suite stamp in CI or after HEAD/tree drift (#3187).\n\nSee [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Coverage debt hatch during release.\n\n### Routine vs hard cut for Step 5 (#2953)\n\n! Treat **hard cut** as the default: full Step 5 (`task check` + Vitest coverage) with no `--skip-ci`.\n\n~ Treat **routine cut** as the same full Step 5, sped up by default-excluding `.deft-scratch/` (and legacy `swarm-worktrees/`) from content/link/path/build-dist walks, plus pre-cut hygiene (green required checks on the tip SHA; prune stale `.deft-scratch/worktrees`).\n\n! Confirm required CI is green on the tip you will tag when aiming for a calm routine cut — green tip CI is a precondition, not a replacement for Step 5.\n\n⊗ Invent a silent lighter Step 5 that skips or soft-passes coverage without an explicit hatch (`--allow-coverage-debt=#N` for branch-only hairlines, or `--skip-ci` + `--allow-skip-ci=#N` for incidents). Silent soft-pass is forbidden in every mode.\n\n~ Prefer pruning abandoned worktrees / cutting from a clean clone over re-scanning scratch noise.\n\nSee [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Routine vs hard cut for Step 5 (#2953).\n\n\n~ **Frozen Go-installer bridge (#1912 / #1972 / #1987):** by default a release tag *above* the frozen line (the `LAST_GO_INSTALLER` constant in `packages/core/src/legacy-bridge/sot.ts`) will NOT rebuild the 6 Go binaries -- the CI `freeze-gate` job in `.github/workflows/release.yml` skips the build (the run stays green; npm still ships from the separate `npm-publish.yml`). If this release must rebuild the Go installer, follow the runbook in [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Frozen Go-installer bridge: roll `LAST_GO_INSTALLER` forward to the cut tag BEFORE tagging (pinning to the exact cut tag both releases the gate AND re-freezes at the new line), then see that section's \"After the release\" step for the re-pin.\n\n1. ! Verify the operator is on the configured base branch (default `master`) and the working tree is clean\n2. ! Confirm the next version number (`X.Y.Z`) with the user. Major / minor / patch decision flows from the `[Unreleased]` content (breaking change → major; new feature → minor; fix-only → patch)\n! After the version is confirmed, name the mint CLI for that version. The operator runs it immediately before Phase 4 (not now): `deft authz:grant -- --template release-publish --target <version> --confirm` plus typed `mint` on a real TTY. Do **not** wait for a live grant before Phase 3 — a grant for the cut version cannot satisfy rehearsal `target=0.0.1` in a clone with no `.deft/authz`, and a Phase-1 mint can expire (`1h`) during long e2e before production Step 10. ⊗ `task authz:grant` (not a Taskfile target). ⊗ Treat a live grant as a Phase 3 precondition.\n3. ! Inspect `[Unreleased]` content vs the proposed version bump. If a breaking change appears in `### Changed` / `### Removed` but only a patch is proposed, surface the mismatch and ask the user to choose\n4. ! Verify `gh auth status` reports authenticated (`task release` will refuse otherwise)\n5. ! **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 (`task reconcile:issues -- --apply-lifecycle-fixes`, 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\n6. ! **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 (`the release tag-availability gate`, 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\n7. ! **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.\n8. ! **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> --confirm` 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).\n9. ~ 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\n\n10. ! **Treat orientation-dirty `cache_fresh` or check-class stale-by-drift as a hard preflight (#4399).** Distinct from ritual-stale. If `session:start` printed `[deft orientation] cache_fresh: dirty`, or `deft verify:cache-fresh` (no `--skip-drift-probe`) reports stale-by-drift, run `deft cache fetch-all --source github-issue --repo <owner>/<repo>` before invoking `task release`. Do not treat skip-drift `verify:session-ritual` green as cache-ready.\n\n\n\n⊗ 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.\n\n⊗ Skip the xBRIEF-lifecycle-sync check (#734); the gate exists because operators consistently forget the manual `task scope:complete` move step. The v0.21.0 cut surfaced 13 stranded xBRIEFs (8 cycle-relevant + 5 historical residue) post-publish as the recurrence record this gate prevents. If `task release` reports `[3/13] Pre-flight xBRIEF lifecycle sync... FAIL (<count> mismatches; run task reconcile:issues -- --apply-lifecycle-fixes to fix)`, the canonical recovery is the apply-mode invocation -- `--allow-vbrief-drift` is reserved for cases where the operator has explicitly reviewed the drift and chosen to defer the lifecycle reconcile to the next refinement pass (e.g. an emergency hot-fix release).\n\n⊗ Skip the tag-availability check (#784); the gate exists because the legacy 12-step pipeline only invoked `git tag` at Step 9, after Steps 1-8 had already mutated state (CHANGELOG promoted, ROADMAP refreshed, dist built, release commit made locally). A duplicate-tag failure at Step 9 stranded the operator with an unpushed wrong-version commit + orphaned `dist/deft-<wrong>.zip` artifact + manual `git reset --hard` recovery (forbidden by AGENTS.md SCM rules without explicit permission). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01. If `task release` reports `[4/13] Pre-flight tag availability... FAIL (<surface> tag v<version> already exists ...)`, the canonical recovery is to choose a different version (the most likely cause is operator typo of a prior release).\n\n⊗ Hand-write a different one-line narrative for each of the three downstream surfaces (CHANGELOG / GitHub release / Slack) -- that drift is exactly the gap the `--summary` flag is designed to close. If the operator insists on per-audience tone, populate the canonical `--summary` ONCE here and document the deviation in the Phase 8 anti-pattern.\n\n## Phase 2 — Dry-run review\n\n! Invoke `task release -- <version> --dry-run --skip-tag --skip-release` and present the plan to the user. If Phase 1 collected an operator summary, also pass `--summary \"<text>\"` so the dry-run preview reflects the canonical narrative the operator just authored.\n\n```\ntask release -- <version> --dry-run --skip-tag --skip-release --summary \"<text>\"\n```\n\nThe 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.\n\n! 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).\n- `yes` (or `confirmed` / `approve`) → proceed to Phase 3\n- `back` → return to Phase 1 for re-validation (e.g. user wants to amend the version or `[Unreleased]` content)\n- `quit` → abort the workflow cleanly; no state changes\n\n⊗ Skip the dry-run preview. The dry-run is the operator's last opportunity to catch a bad version number, malformed CHANGELOG, or wrong base branch before the pipeline starts writing files.\n\n## Phase 3 — E2E sanity\n\n! Invoke `task release:e2e` against an auto-created temp repo to verify the full pipeline shape works end-to-end before touching the real repo.\n\n! **#1880 Gap D (#2692):** `task release:e2e` is a long-running step — MUST background / subagent-dispatch it when the host supports it so Phase 2 confirmation and other human gates stay interactive. Do not wrap its output in PowerShell `Select-Object -Last`.\n\n```\ntask release:e2e\n```\n\nThe harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke-test rehearsal, and **by default keeps** the temp repo (#2572). Stderr always includes the full `owner/slug` and a copy-pasteable manual-cleanup command (`gh repo delete <owner>/<slug> --yes`). Privileged environments (CI or an operator with `delete_repo`) MAY pass `task release:e2e -- --destroy-repo` to attempt auto-delete; destroy failure emits a WARN and does **not** block Phase 4 when the rehearsal succeeded.\n\n! After Phase 3, the agent MUST NOT retry or escalate temp-repo deletion. Include any leftover temp repo(s) in the phase summary for the operator to clean up manually.\n\n! Treat a non-zero exit from `task release:e2e` as a hard refusal to proceed to Phase 4. Surface the diagnostic and ask whether to retry (return to Phase 1) or stop (`quit`).\n\n! Rehearsal uses sentinel version `0.0.1` on a throwaway repo. The landed rehearsal exemption lets `task release:e2e` reach npm dry-run without a `release-publish` grant. ⊗ Ask the operator to mint `0.0.1`. ⊗ Wait for a live grant before Phase 3. Mint remains immediately before Phase 4.\n\n? **Skip allowed** when the operator has just run `task release:e2e` successfully against the same branch in the past 30 minutes. Note the prior run timestamp in the user-facing summary.\n\n! **`task release:e2e` now also rehearses the npm publish (#1910).** Unless `--skip-npm` is passed (or `npm` is absent from PATH, which soft-skips), the rehearsal runs `npm publish --dry-run --access public` for all four `@deftai/directive*` packages against the throwaway clone in dependency order (types -> core -> content -> cli), after `pnpm install` + `pnpm -w run build` and a version-alignment pass. This catches a broken `files` allowlist, a version-drift bug, or a dependency-order error BEFORE the real `v*` tag fires the publish workflow -- without touching the real registry. The install+build exceeds the <90s fast budget, so pass `task release:e2e -- --skip-npm` when you only need the GitHub-pipeline shape check.\n\n! **Tag -> npm coupling + irrevocability (#1910, #1972, #2002).** A `v<version>` tag is a TWO-channel action: the GitHub release (this skill's pipeline) AND `.github/workflows/npm-publish.yml`, which runs in a SEPARATE workflow that does NOT block the GitHub release and is NOT draft-gated. The npm workflow derives the published version from the tag (`${GITHUB_REF_NAME#v}`); this skill owns the version chosen in Phase 1. These MUST stay consistent -- the tag you cut IS the npm version that ships; there is no separate npm version bump. **npm publish is irrevocable** (#1972): once the tag fires, packages are live on npm and cannot be unpulled; `task release:rollback` does NOT retract npm (forward-only recovery). A red npm job on a green GitHub release means the npm channel did not ship (verify in Phase 5/7).\n\n## Phase 4 — Production draft\n\n! **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> --confirm` 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.\n\n! 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.\n\n⊗ Use `--skip-ci` on a production cut except under explicit operator incident review — it skips Step 5 vitest coverage and ships untested npm builds (#2652). When unavoidable, pass `--allow-skip-ci=#N` citing the tracked issue; Step 5 emits a loud WARN. See [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Vitest coverage hang recovery. The next patch after the hang fix must cut without `--skip-ci`.\n\n```\ntask release -- <version> --summary \"<text>\"\n```\n\nPer #716 default-draft hardening, this lands the release as a `--draft` on the real repo. Binaries upload via release.yml CI, but the artifact is NOT yet visible to consumers. The operator-authored summary becomes part of the promoted `CHANGELOG.md [<version>]` section AND the GitHub release body (auto-pickup via `_section_for_version`). The same wording is the canonical source for the Phase 8 Slack `*Summary*:` slot.\n\n! **Maintainer-mode release notes auto-lead with an \"Upgrading from an older version?\" banner (#1413).** When the cut targets the canonical framework repo (`deftai/directive`), `task release` Step 12 prepends the banner from the editable template at `.github/release-notes/upgrade-banner.md` to the notes passed to `gh release create` (via `_prepend_upgrade_banner`). The banner points consumers at the canonical `deft-install --yes --upgrade --repo-root . --json` upgrade command and #1411. This is **GitHub-release-body-only** -- it is NEVER injected into `CHANGELOG.md`, so the CHANGELOG section and the release body intentionally differ by this leading block. To change the wording, edit the template file; do not hand-edit the published release body. **Consumer-mode releases (any non-`deftai/directive` repo) are unaffected** -- a downstream project that vendors the release pipeline never inherits deft's upgrade guidance. A missing/unreadable template degrades gracefully (notes ship without the banner; the cut is never blocked).\n\n! **Verify isDraft within 5 seconds; flip immediately if not (#724).** Immediately after `gh release create --draft` returns success, `task release` Step 11 polls `gh release view v<version> --json isDraft` up to 5 times at 1-second intervals. If the release exists with `isDraft=false`, the pipeline auto-flips it via `gh release edit v<version> --draft=true` and emits a `WARNING: release landed as public; flipping to draft (defense-in-depth, see #724)` line. This closes the ~90-second public-exposure window observed during the v0.21.0 cut where a manual recovery created a public release before the operator noticed and flipped it. The verify gate is defense in depth even when `--draft` was passed correctly: it catches the case where `gh release create` partially succeeded (release record written, error returned) AND the operator-error variant where an alternate code path sent the release without `--draft`. A release-not-found-within-budget result emits a WARN and does NOT fail the pipeline (release.yml CI may still be processing).\n\n! Wait for `task release` to exit 0 before continuing. A non-zero exit means the pipeline halted partway through; consult Phase 7's `task release:rollback` recovery before retrying.\n\n⊗ Pass `--no-draft` here unless the operator has explicitly opted into direct-publish (e.g. automated security patch). The default-draft contract is the foundation of the safety hardening surface.\n\n⊗ Skip the post-create verify-isDraft gate -- the gate is the only reliable safety net against \"create call exited 0 but the release somehow landed as public\" variants (#724). If `task release` is invoked manually outside the canonical `task release` flow, the operator MUST run `gh release view v<version> --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` BEFORE handing off to Phase 5.\n\n## Phase 5 — GitHub draft QA (optional; NOT the npm authority gate)\n\n! After `task release` exits 0, QA the **GitHub draft release** only. npm packages typically **already shipped** when the tag push in Phase 4 fired `.github/workflows/npm-publish.yml` (#1972, #2002). Phase 5 is NOT a \"user-only authority before going live\" gate for the release as a whole -- it is optional draft QA for GitHub assets, notes, and binaries.\n\n1. ! **Verify npm publish status FIRST (in parallel with draft inspection).** Run `gh run list --workflow=npm-publish.yml --repo <owner>/<repo> --limit 5` and confirm the tag run for `v<version>` is `completed`/`success`. If npm failed, surface immediately -- the GitHub draft QA is secondary to a red npm channel.\n2. ! Run `gh release view v<version> --json url,name,body,assets,isDraft --repo <owner>/<repo>` and present the output to the user\n3. ! Surface the asset list (size + filename) so the user can verify binaries uploaded correctly\n4. ! Surface the auto-generated release notes (or the CHANGELOG section that was promoted into the release body)\n\n### Happy path (default when npm succeeded and draft assets look correct)\n\n! When the npm workflow succeeded AND draft assets/notes pass inspection, **auto-proceed to Phase 6 Publish branch** -- run `task release:publish -- <version>` without a redundant human publish prompt (#2002). npm already shipped at tag push; waiting for a separate `publish` confirmation does not protect the npm channel.\n\n? **Operator override:** if the operator wants to hold the GitHub release in draft (e.g. embargo, last-minute notes edit), they MAY say `defer` before auto-publish runs.\n\n### Exception paths (operator-initiated)\n\n- `rollback` → proceed to Phase 6 (Rollback branch). **Reminder:** rollback unwinds the GitHub release only; npm packages already published at tag push are NOT retracted (#1972).\n- `defer` → halt and exit. Surface the draft URL so the operator can return later with `task release:publish -- <version>` or `task release:rollback -- <version>`.\n\n⊗ Treat Phase 5 as the npm publish-authority gate -- npm ships at tag push (Phase 4), not at `task release:publish`. A human `publish` prompt here is redundant when npm already succeeded and only delays flipping the GitHub draft to public.\n⊗ Skip npm workflow verification in Phase 5 and defer it entirely to post-publish Phase 7 -- npm status MUST be checked before or in parallel with the GitHub publish flip.\n\n## Phase 6 — Publish or rollback\n\n! Branch on the Phase 5 outcome. The happy path auto-enters the Publish branch when npm succeeded and draft QA passed (#2002).\n\n### Publish branch (happy path auto-run, or resumed after `defer`)\n\n```\ntask release:publish -- <version>\n```\n\nThe companion script flips `--draft=false`, then re-reads the release to verify `isDraft == false` actually flipped. State machine:\n- `draft` found → flip to public; verify; exit 0\n- already `published` → exit 0 no-op (idempotent re-runs are safe)\n- `not-found` → exit 1 (cannot publish a missing release)\n- gh-error → exit 1 with diagnostic\n\n! Wait for `task release:publish` to exit 0 before continuing. On the happy path this runs immediately after Phase 5 draft QA without a separate human publish prompt.\n\n### Rollback branch (user said `rollback`)\n\n```\ntask release:rollback -- <version>\n```\n\nThe state-aware unwind detects the post-release state and applies the matching tiered recovery. Time-windowed download-count guard:\n- release age `< 5 min` → threshold = 0 (rollback safe; nobody noticed yet)\n- release age `5-30 min` → threshold = max(`--allow-low-downloads`, 10) (filters bot fetches)\n- release age `> 30 min` → refuse without `--allow-data-loss`\n\nThree escape hatches (escalating warnings):\n- `--allow-low-downloads N` -- accept up to N downloads\n- `--allow-data-loss` -- accept any count (consumer impact)\n- `--force-strict-0` -- require exactly 0 regardless of release age\n\nRace-condition mitigation: `download_count` is double-read with a 5s sleep between reads; rollback only proceeds if both reads agree below threshold.\n\n! When the guard refuses, surface the recommendation to the user: rollback is risky on a released artifact with non-zero downloads. Prefer the **hot-fix path** (cut the next patch with a withdrawal note in `[Unreleased]/Changed` rather than deleting the broken release).\n\n! **`task release:rollback` does NOT retract npm (#1972, #2002).** Rollback unwinds GitHub release state (draft/public, tag, assets) only. npm packages published at tag push remain on the registry irrevocably. Recovery is forward-only: deprecate the bad version, move a dist-tag, or ship a patch release.\n\n## Phase 7 — Post-publish verification\n\n! Only enter Phase 7 if Phase 6 took the Publish branch (rollback branch ends here with the unwind log).\n\n1. ! **Re-verify npm publish landed (#1910, #1909, #2002).** Phase 5 checked workflow status before the GitHub publish flip; Phase 7 confirms registry truth AFTER `task release:publish`. For each of `@deftai/directive-types`, `@deftai/directive-core`, `@deftai/directive-content`, and `@deftai/directive`, run `npm view <pkg>@<version> version --prefer-online` (expect `<version>`) and confirm provenance on the npm page. A green GitHub release with missing npm packages means consumers cannot `npm i -g @deftai/directive@<version>` -- escalate immediately. (Real-registry verification depends on #1909's credential; until then verify workflow-run status and flag credential gaps.) Reading one package is not sufficient — sibling publish is not atomic.\n2. ! **Report local-vs-released CLI drift (#3753).** After the all-four registry check, print the local global CLI version, the released version, whether they match, and the exact remediation `npm i -g @deftai/directive@<version> --prefer-online`. Compare versions with `checkActiveCliAgainstTarget` (not bare `deft --version`) so a PATH-shadowed install cannot report success (#3233). If some siblings are visible and others are not, report **still propagating**. If none are visible after this wait, report **publish incomplete**. `task release` already emitted a non-blocking snapshot of the same report at pipeline completion (single probe, no wait — Step 13 returns before `npm-publish.yml` is green). Phase 7 is the bounded wait. ⊗ Run `npm i -g`. The report must not fail the release.\n3. ! Verify GitHub auto-closed the discrete-task issue(s) referenced via `Closes #N` in the release notes (mirrors `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 2)\n4. ! Run `gh issue view <N> --json state --jq .state` for each closed issue. If any didn't auto-close, manually close with `gh issue close <N> --comment \"Closed by release v<version> (squash auto-close did not trigger)\"` (Layer 1, #167)\n5. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)\n6. ! Verify binaries are downloadable from the public release URL: `gh release view v<version> --json assets --jq '.assets[].url'` and curl one to confirm 200 OK\n7. ! For any umbrella / staying-OPEN issue (`Refs #N`) referenced in the release notes, run the Layer 3 reopen sweep from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1: any protected issue that auto-closed MUST be reopened with a comment citing #701\n\n⊗ Skip the post-publish verification. The closing-keyword false-positive (Layer 1 / Layer 2 / Layer 3) and the incremental-renderer-drift (#641, #614) are exactly the kind of issues that surface only AFTER a release is public.\n\n## Phase 8 — Slack announcement\n\n! Generate the canonical Slack release announcement and present it to the user for copy-paste, re-using the template from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 5.\n\nThe announcement block MUST include:\n\n```\n:rocket: *deft v<version>* -- <release title>\n\n*Summary*: <one-sentence description of the release scope>\n\n*Key Changes*:\n- <bullet per significant change, 3-5 items max>\n\n*Stats*: 1 release | ~<duration> elapsed | <N> commits since v<previous>\n*Release*: <GitHub release URL>\n```\n\n! Populate version from the freshly-published `gh release view v<version>` output. Populate release title from the CHANGELOG section heading (or the GitHub release title). Summarize key changes from the promoted `[Unreleased]` -> `[<version>]` CHANGELOG section (NOT raw commit messages). Populate stats from `git log v<previous>..v<version> --oneline | wc -l`.\n\n! Populate the `*Summary*:` slot VERBATIM from the operator-authored blockquote at the top of the CHANGELOG `[<version>]` section (the line beginning with `> ` immediately after the `## [<version>] - <date>` heading). The Phase 1 prompt + Phase 4 `--summary` flag exist precisely so this populate step is mechanical -- one canonical narrative authored once at Phase 1, propagated through Phase 4 promotion, and copy-pasted here without re-authoring. If the CHANGELOG section has no blockquote (operator skipped the Phase 1 prompt), generate a one-sentence summary from the `### Added` / `### Changed` bullets and surface to the operator that this is a regenerated narrative (NOT canonical) so they can decide whether to amend the CHANGELOG before publishing.\n\n! Present the block as a code-fenced snippet the user can copy directly. Do NOT post to Slack from inside this skill -- the user owns the actual broadcast.\n\n## Skill Completion\n\n! When Phase 8 completes (or when Phase 5 took the `defer` / `quit` path, or when Phase 6 completed the rollback branch), explicitly confirm skill exit:\n\n```\ndeft-directive-release complete -- exiting skill.\nNext: <one-line guidance>\n```\n\nWhere `<one-line guidance>` is one of:\n- \"release v<version> live -- monitor consumer reports for ~24h before cutting v<next>\"\n- \"release v<version> rolled back -- the underlying defect needs a hot-fix in the next CHANGELOG entry\"\n- \"release deferred -- resume by running `task release:publish -- <version>` (GitHub only; npm already shipped at tag push) or `task release:rollback -- <version>` (GitHub unwind only; npm is forward-recovery) when ready\"\n\n⊗ Exit silently without confirming completion or providing next-step guidance.\n\n## Anti-Patterns\n\n- ⊗ Foreground-block the operator chat on Phase 1 long prep (`reconcile:issues`, cache refresh) or Phase 3 `release:e2e` when background / subagent dispatch is available (#1880 Gap D / #2692) — the interactive channel must stay free for version confirmation, `--summary`, and the Phase 2 dry-run gate\n- ⊗ Proceed to `task release` on orientation-dirty `cache_fresh` or check-class stale-by-drift, or treat skip-drift ritual green / ritual-stale as that bar (#4399) — fetch-all first\n\n- ⊗ Wrap long release-prep task output in PowerShell `Select-Object -Last` — it buffers until exit and makes the session look hung (#2692)\n- ⊗ 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\n- ⊗ 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\n- ⊗ Pass `--no-draft` to `task release` without explicit operator opt-in -- the default-draft contract is the foundation of the safety hardening surface\n- ⊗ 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)\n- ⊗ Delete the `release:publish` draft-flip closed-verb check as a substitute for the tag-push gate -- placement, not strength; both stay (#3527 / #1095)\n- ⊗ 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\n- ⊗ Expect `task release:rollback` to retract npm packages -- rollback is GitHub-only; npm recovery is forward-only (deprecate / dist-tag / patch)\n- ⊗ 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\n- ⊗ Use `--allow-data-loss` without first reading the script docstring's hot-fix-path recommendation -- the flag is an explicit acknowledgment of consumer impact, not a default\n- ⊗ Skip the Phase 7 Layer 3 reopen sweep -- protected umbrellas can auto-close on a release-merge squash even when the release notes use `Refs #N` only\n- ⊗ Run `npm i -g` from the release pipeline or Phase 7 (#3753) -- report local-vs-released drift only; no global mutation\n- ⊗ Trust bare `deft --version` after a cut -- use `checkActiveCliAgainstTarget` so a PATH-shadowed install cannot report success (#3233 / #3753)\n- ⊗ Treat a missing sibling package as a failed publish without distinguishing still-propagating from publish-incomplete (#3753)\n- ⊗ Post the Phase 8 Slack announcement directly from this skill -- the user owns the broadcast; the skill only generates the template\n- ⊗ Hardcode `master` as the base branch -- delegate to the configured base branch from `task release --base-branch <branch>`\n- ⊗ Skip the post-create verify-isDraft gate (#724) -- a successful `gh release create` exit code does NOT prove the release actually landed in draft state; the 5-second poll-and-flip gate in `task release` Step 11 is the only safety net against operator-error variants and partial-success races, and any manual recovery path that bypasses `task release` MUST run `gh release view --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` before handing off to Phase 5\n- ⊗ Manually rewrite the Phase 8 Slack `*Summary*:` line to deviate from the CHANGELOG `[<version>]` blockquote -- the canonical narrative is authored ONCE at Phase 1 via `--summary` and propagates verbatim across all three audiences (CHANGELOG / GitHub release body / Slack). Per-audience hand-edits create documentation drift that the deterministic `--summary` flow is designed to prevent. If the operator wants Slack-specific tone, fold it into the canonical Phase 1 wording before passing `--summary`, OR amend the CHANGELOG blockquote BEFORE Phase 8 so all three surfaces stay aligned\n- ⊗ Cut a release mutation `session:start` on the contended primary without `--primary-claim-exception=release-cut` (#4266) — occupancy already implements the exception; the CLI argv is the trusted producer. ⊗ Invent a process-wide env producer.\n- ⊗ Export `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` or `DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1` for the entire release session or wrap `task release` / `task check` in them (#1553) -- the env vars are process-wide and leak into nested tests and temporary repos, producing false preflight failures. Prefer `task policy:allow-direct-commits -- --confirm` and restore with `task policy:enforce-branches` after the cut (closeout commit+push may use a **scoped** prefix of both `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` and `DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1` on those three git commands only — see Branch-Protection Policy Guard, #2623)\n- ⊗ `task authz:grant` — not a Taskfile target. Name `deft authz:grant -- --template release-publish --target <version> --confirm`.\n- ⊗ Wait for a live grant before Phase 3, or ask the operator to mint rehearsal `0.0.1` — mint the confirmed cut version immediately before Phase 4.\n- ⊗ Pass `--allow-coverage-debt=#N` unquoted on Windows PowerShell (#2621) -- `#` starts a comment and silently drops the issue number. Use `--allow-coverage-debt=N` or `--allow-coverage-debt=\"#N\"`\n- ⊗ Soft-pass coverage debt while an **open** coverage-debt issue from a prior hatch still exists (#2866 / #2573 / #3187) -- restore real branch coverage >= 85% and close the debt issue before reusing `--allow-coverage-debt` or expecting auto-hatch; the ledger is open GitHub issues, not prior CHANGELOG citations (#2618 superseded by open-issue ledger)\n- ⊗ Re-run the full Step 5 suite after a legal branch-only hairline when auto-hatch already filed `#N` and continued (`PASS_WITH_DEBT`) — that is the ceremony tax #3187 removes\n- ⊗ Trust `.deft/release-suite-stamp.json` in CI or after HEAD/tree drift (#3187)\n",
       "frontmatter_extra": null
     },
     {
@@ -318,7 +318,7 @@
       ],
       "path": "skills/deft-directive-setup/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Setup\n\nAgent-driven alternative to `directive init` plus setup Phases 1-3 (`task project:render` / spec interview).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- User says \"set up deft\", \"configure deft\", or \"bootstrap my project\"\n- User asks to create USER.md, PROJECT-DEFINITION.xbrief.json, or a specification\n- User clones a deft-enabled repo for the first time with no config\n- User says \"revisit experimental rules\", \"toggle experimental meta\", \"enable SOUL\", \"disable morals\", or wants to change Experimental Rules after bootstrap (#46)\n\n## Opt-out flag (`.no-deft-directive`) (#2926)\n\n! Before Pre-Cutover Detection Guard, Phase 1, or any install/setup step, check the **project root** for `.no-deft-directive` (exact lowercase name; presence = flag; empty or short `#` comment OK).\n\n| Condition | Action |\n|-----------|--------|\n| Flag **present** | Stop. Tell the human: \"Directive disabled via `.no-deft-directive`\". ⊗ Offer install, session ritual, or setup interview. |\n| Flag **absent**, no Directive deposit (`.deft/core`) | ? Ask whether to use Directive. On **no** → create root `.no-deft-directive` (optional one-line rationale) and stop. On **yes** → continue setup and ⊗ create the flag. |\n| Operator says **stop using DD** | Create `.no-deft-directive`. ⊗ Auto-delete `.deft/` (explicit cleanup only). |\n| Operator says **start using DD** | Remove `.no-deft-directive` and ensure install (`directive init` / deposit). |\n\n! Flag is **root-only** (workspace root opened). Nested monorepo package roots are out of scope for v1.\n! Flag **wins locally** over trusted-org / product-signal force-on (v1).\n! Flag + deposit = inconsistent: warn loudly; doctor diagnoses; do not silently refresh. See `content/docs/no-deft-directive.md`.\n\n## Consumer-first default (#1813)\n\n! Assume the operator is **using Deft in their project** (consumer path). Proceed directly to the Pre-Cutover Detection Guard and Phase 1 — do NOT open with a contributor-vs-consumer fork.\n\n~ The overwhelming majority of setup sessions are consumer installs; contributor onboarding is a separate, opt-in path (see below).\n\n## Contributor / framework-maintainer path (secondary)\n\n? Only enter this branch when the user **explicitly** says they are working on Deft itself (framework source checkout, `deftai/directive` clone, or maintainer tooling).\n\nWhen that happens:\n\n1. ! Tell the user: \"Contributor setup lives in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) and this repo's root [`AGENTS.md`](../../../AGENTS.md). Use the maintainer installer: `deft-install --yes --upgrade --maintainer --repo-root . --json`.\"\n2. ⊗ Continue the consumer USER.md / PROJECT-DEFINITION interview — the maintainer path does not use the first-session consumer flow.\n3. **Stop here** unless the user explicitly asks to continue with consumer setup anyway.\n\n## Pre-Cutover Detection Guard\n\n! Before proceeding with any setup phase, detect whether the project uses the pre-v0.20 document model and redirect to migration if so.\n\n### Detection Criteria\n\nA project is **pre-cutover** if ANY of the following are true. When in doubt, run `task verify:pre-cutover` (the deterministic helper).\n\n1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: xbrief/specification.xbrief.json -->`, and `xbrief/specification.xbrief.json` plus all five lifecycle folders exist.\n2. `PROJECT.md` exists and contains neither the legacy `<!-- deft:deprecated-redirect -->` sentinel NOR the current `Purpose: deprecation redirect` canonical-banner marker (same one-release-cycle grace window).\n3. `xbrief/specification.xbrief.json` exists but the lifecycle folders (`xbrief/proposed/`, `xbrief/pending/`, `xbrief/active/`, `xbrief/completed/`, `xbrief/cancelled/`) do NOT exist\n\n### Action on Detection\n\n! If pre-cutover state is detected, **stop immediately** and display an actionable message pointing at the frozen-release migration path (#2068):\n\n> \"This project uses the pre-v0.20 document model. Current npm releases no longer ship in-product `task migrate:vbrief`. Follow UPGRADING.md § Frozen pre-v0.20 document-model migration: pin framework v0.59.0 (frozen Go installer or git tag), install Python 3.11+ and uv, run `task migrate:vbrief` once from that payload, then upgrade to current npm.\"\n\n! Include specific details about what was detected:\n\n- Missing lifecycle folders: \"Create lifecycle folders via the frozen-release migrator on v0.59.0, or manually add `xbrief/{proposed,pending,active,completed,cancelled}/` after migrating narratives\"\n- `SPECIFICATION.md` with real content: \"SPECIFICATION.md contains non-redirect content — migrate on pinned v0.59.0 before upgrading to current npm\"\n- `PROJECT.md` with real content: \"PROJECT.md contains non-redirect content — migrate on pinned v0.59.0 before upgrading to current npm\"\n- Missing `PROJECT-DEFINITION.xbrief.json`: \"Run `task project:render` after document-model migration completes\"\n\n### Preflight (optional diagnostic)\n\n~ Run `task migrate:preflight` to confirm pre-cutover state and print the frozen-release guidance. It does **not** run migration.\n\n⊗ Offer to run `task migrate:vbrief` from the current npm deposit — the migrator is not bundled on current releases (#2068).\n⊗ Proceed with setup phases when pre-cutover artifacts are detected — always redirect to the frozen migration path first.\n⊗ Silently ignore pre-cutover artifacts — the user must be informed with an actionable command to fix the state.\n\n### Greenfield Projects (No Migration Needed)\n\n! For new projects (no existing `SPECIFICATION.md`, `PROJECT.md`, or `xbrief/specification.xbrief.json`), the guard passes silently and setup proceeds normally.\n\n! Greenfield setup creates the full xBRIEF-centric structure from scratch:\n\n1. `./xbrief/` directory with all 5 lifecycle subdirectories: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`\n2. `./xbrief/PROJECT-DEFINITION.xbrief.json` generated from Phase 2 interview results\n3. First scope xBRIEF created in `proposed/` or `pending/` depending on Phase 3 interview outcome\n\n~ This is already handled by Phase 2 Output Path (creates `./xbrief/` and lifecycle subfolders) and Phase 3 Output (creates scope xBRIEFs in lifecycle folders). The guard ensures migrating projects are redirected before reaching these phases.\n\n### Migration safety flags (frozen v0.59.0 release only)\n\nWhen guiding an operator through migration on the pinned release, mention the migrator safety affordances (#497, #506 D7):\n\n- **`task migrate:vbrief -- --dry-run` (preview)** on v0.59.0\n- **Dirty-tree guard** — migrator refuses when the working tree is dirty unless `--force`\n- **`task migrate:vbrief -- --rollback`** on v0.59.0 to restore `.premigrate.*` backups\n\n⊗ Offer in-product migration from a current npm deposit — use the frozen path (#2068).\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (Phase 1 depth question, Phase 2 project type / deployment / language / strategy / branching gates, Phase 3 onboarding question, end-of-phase transition prompts, post-interview confirmation gate) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options MUST be `Discuss` and `Back`, in that order. The Discuss-pause semantic is documented verbatim there -- on `Discuss` selection the agent MUST halt the in-progress sequence immediately, prompt `What would you like to discuss?`, and resume only on an explicit user signal (re-asks original question, says `resume`/`continue`, or re-issues prior selection). Implicit resumption is forbidden. Fallback chat replies MUST map only to the displayed number or exact displayed option text; do not infer from alphabetic host affordances.\n\n## Platform Detection\n\n! Before resolving any config paths, detect the host OS from your environment context:\n\n| Platform           | USER.md default path                                              |\n|--------------------|-------------------------------------------------------------------|\n| Windows            | `%APPDATA%\\deft\\USER.md` (e.g. `C:\\Users\\{user}\\AppData\\Roaming\\deft\\USER.md`) |\n| Unix (macOS/Linux) | `~/.config/deft/USER.md`                                          |\n\n- ! If `$DEFT_USER_PATH` is set, it takes precedence on any platform\n- ! Create parent directories as needed when writing USER.md\n- ~ `$DEFT_PROJECT_PATH` overrides the default project config path (`./xbrief/PROJECT-DEFINITION.xbrief.json`) if set\n- ! Resolve `<policy-project-root>` to the user's working directory at skill entry. When `$DEFT_PROJECT_PATH` is set, resolve it relative to that root and preserve the environment variable for every Phase 2 command; the public policy writer, inspector, lock, and conformance gate honor the configured file even when it is outside the canonical `xbrief/` path.\n- ! Pass `--project-root <policy-project-root>` to every Phase 2 policy inspector, writer, and conformance command. Do not unset or rewrite `$DEFT_PROJECT_PATH`, and do not let those commands fall back to a different working directory.\n\n## Agent Behavior\n\n**Flow:**\n- ! Start asking immediately — everything you need is in THIS file\n- ⊗ Explore the codebase, read framework files, or gather context before asking\n- ? Read `deft/main.md` or language files LATER when generating output\n\n**Interaction:**\n- ~ Use structured question tools only when their visible option labels preserve the canonical numbers (for example, `1. Yes`) and their return value is the numeric selection or exact displayed option text.\n- ! Fall back to the numbered chat menu when the host UI may replace numbers with alphabetic affordances, unlabeled buttons, or any other non-canonical choice labels.\n- ⊗ Infer deterministic answers from host-added letters or shortcuts unless those letters were actually displayed in the canonical menu labels.\n\n**Defaults:**\n- ! Communicate that deft ships with best-in-class standards for 20+ languages\n- ! Frame setup as \"tell me your overrides\" — not \"configure everything\"\n- ~ \"Deft has solid opinions on how code should be written and tested — I just need a few things about you and your project.\"\n\n**Adapt to Technical Level:**\n- ! First question gauges whether user is technical or non-technical\n- ! Technical user: ask about languages, strategy, coverage directly — they'll have opinions\n- ! Non-technical user: skip jargon, use sensible defaults, ask about what they're building not how\n- ⊗ Ask non-technical users about coverage thresholds, strategies, or framework choices\n\n## Available Languages\n\nC, C++, C#, Dart, Delphi, Elixir, Go, Java, JavaScript, Julia, Kotlin,\nOffice.js (Excel JavaScript API), Python, R, Rust, SQL, Swift, TypeScript,\nVBA (Excel macros), VHDL, Visual Basic (.NET), Zig, 6502-DASM\n\n- ? Read `deft/languages/{name}.md` when generating output — not before asking\n\n## Available Strategies\n\n~ When presenting strategies to the user, always use this numbered list format (not a plain table).\n~ Always include the chaining note below the list.\n! Always show the FULL strategy list at every chaining gate — never remove a strategy because it was previously run.\n~ If a strategy has been run already, indicate it with a note e.g. `(run 1x)` but keep it selectable.\n\n1. **interview** ★ (recommended) — Structured interview with sizing gate: Light or Full path\n2. **yolo** — Auto-pilot interview — Johnbot picks all recommended options\n3. **map** — Analyze existing codebase conventions before adding features\n4. **discuss** — Front-load decisions and alignment before planning\n5. **probe** — Adversarially stress-test the plan; surface assumptions, edge cases, and risks before spec\n6. **research** — Investigate the domain before planning\n7. **speckit** — Five-phase spec-driven workflow for large/complex projects\n\n> 💡 Strategies can be chained — after one completes, you'll be asked if you want to run another.\n\n---\n\n## Phase 1 — User Preferences (USER.md)\n\n**Goal:** Personal preferences file with two sections:\n- **Personal** — always wins over everything (name, custom rules)\n- **Defaults** — fallback values that PROJECT-DEFINITION.xbrief.json can override (strategy, coverage)\n\n- ~ Skip if USER.md exists at the platform-appropriate path (see Platform Detection) and user doesn't want to overwrite\n- ⊗ Scan filesystem beyond checking that one path\n\n### USER.md Freshness Detection\n\n! When an existing USER.md is found (returning user), check its `deft_version` field before skipping Phase 1:\n\n1. ! If `deft_version` is **missing**: the USER.md predates versioning -- treat as stale\n2. ! If `deft_version` is present but **differs from the current framework version** (0.20.0): check whether any expected fields are missing from the USER.md\n3. ! If fields are missing: query the user for each missing field individually -- do NOT re-run the full Phase 1 interview\n4. ! After completing any field queries (even if none were needed), write the current `deft_version` (0.20.0) to USER.md\n5. ~ If `deft_version` matches the current version and all expected fields are present: USER.md is fresh — do **not** re-run Phase 1. ! Still offer the **Returning-user re-entry** menu below so the operator can revisit Experimental Rules or continue to Phase 2 without a full re-interview (#46).\n\nExpected USER.md fields: **Name**, **Custom Rules**, **Default Strategy**, and optionally **Coverage** and **Experimental Rules**.\n\n⊗ Re-run the full Phase 1 interview when only individual fields are missing from a stale USER.md -- query missing fields individually instead.\n\n### Returning-user re-entry (#46)\n\n! When USER.md already exists (fresh or after individual missing-field fill), present a deterministic numbered menu before assuming Phase 1 is \"done and silent\":\n\n> \"USER.md is in place. What next?\"\n> 1. Continue to Phase 2 (project configuration) ★ (recommended when project config is still missing)\n> 2. **Revisit experimental rules** — enable/disable SOUL / morals / code-field without hand-editing schema\n> 3. Not now (exit setup)\n> 4. Discuss\n> 5. Back\n\n- ! Final two numbered options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md)\n- ! On option 2, enter **Revisit experimental rules** (next section) — not a full Phase 1 re-interview\n- ⊗ Silently skip past a complete USER.md with no re-entry offer when the operator entered setup (or asked to configure preferences)\n- ⊗ Invent a `deft config` / `task config:*` verb family for this slice — setup skill re-entry is the product surface (#46)\n\n### Interview Rules\n\n! This phase follows the deterministic interview loop defined in `skills/deft-directive-interview/SKILL.md`. The core rules (one question per turn, numbered options with stated default, explicit \"other\" escape, depth gate, default acceptance, confirmation gate, structured handoff) apply here. Key points repeated for emphasis:\n\n! **Each message you send MUST contain exactly ONE question.** This is the most\nimportant rule in this file. After the user answers, send the NEXT question in\na new message. Repeat until all questions for their track are answered.\n\n- ⊗ Include two or more questions in the same message under any circumstances\n- ⊗ List upcoming questions — only show the current one\n- ~ Provide numbered answer options with an \"other\" choice where appropriate\n- ! Mark which option is RECOMMENDED when showing choices\n- ~ Use structured question tools only when visible option labels preserve the canonical numbers and returns map to numeric selections or exact displayed option text.\n\n### Question Sequence\n\n**Step 0 — Opening (all users):**\nAsk: \"How deep do you want to go?\"\n  1. I'm technical — ask me everything\n  2. I have some opinions but keep it simple\n  3. Just pick good defaults — I care about the product, not the tools\n\nWait for answer. Then follow the track below.\n\n**Track 1 (technical) — 7 steps:**\n- Step 1: Ask their name\n- Step 2: Ask strategy preference (show Available Strategies numbered list from the Available Strategies section, with descriptions and recommended marker; fallback — projects can override)\n- Step 3: Ask coverage threshold (default 85%; fallback — projects can override)\n- Step 4: Ask for custom rules — if user has rules, collect them one per line (empty line to finish); if none, skip\n- Step 5a: Present SOUL.md and ask whether to include it (default: yes):\n  > **SOUL.md** — Results-first agent persona (inspired by Winston Wolf). Enforces assess-before-acting,\n  > finish-what-you-start, right-tool-for-the-job, and play-the-long-game. Keeps the AI decisive and\n  > concise. Includes a named persona ('Vinston') — drop if you prefer to define your own agent personality.\n  > Include SOUL.md? (Y/n)\n- Step 5b: Present morals.md and ask whether to include it (default: yes):\n  > **morals.md** — Epistemic honesty rules. No presenting speculation as fact, label unverified claims,\n  > self-correct when wrong. Foundational trust rules for any AI agent. Strongly recommended.\n  > Include morals.md? (Y/n)\n- Step 5c: Present code-field.md and ask whether to include it (default: yes):\n  > **code-field.md** — Pre-code assumption protocol. Requires stating assumptions and naming failure modes\n  > before writing a single line. Fights the 'it compiles, ship it' instinct. Based on NeoVertex1 context-field.\n  > Include code-field.md? (Y/n)\n\n**Track 2 (middle ground) — 2 steps:**\n- Step 1: Ask their name\n- Step 2: Ask for custom rules — if user has rules, collect them one per line (empty line to finish); if none, skip\n- Set defaults without asking: strategy = \"interview\", coverage = 85%, all meta-guidelines included\n\n**Track 3 (non-technical) — 2 steps:**\n- Step 1: Ask their name\n- Step 2: Ask what they're building (brief description — used for PROJECT-DEFINITION.xbrief.json later)\n- Set defaults: strategy = \"interview\", coverage = 85%, all meta-guidelines included\n\n### Output Path\n\nResolve using Platform Detection above. Write to the platform-appropriate path\n(or `$DEFT_USER_PATH` if set). Create parent directories as needed.\n\n### Template\n\n```markdown\n# User Preferences\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**deft_version**: 0.20.0\n\n## Personal (always wins)\n\nSettings in this section have HIGHEST precedence — override all other deft rules,\nincluding PROJECT-DEFINITION.xbrief.json.\n\n**Name**: Address the user as: **{name}**\n\n**Custom Rules**:\n{custom rules or \"No custom rules defined yet.\"}\n\n**Forge outage retry** (optional): `forgeOutageRetryMinutes: 30` — integer minutes, minimum 5. Default 30. Personal wins over `plan.policy.forgeOutageRetryMinutes`. Omit to use project policy or the framework default. Inspect: `task policy:show --field=forgeOutageRetryMinutes`.\n\n## Defaults (fallback)\n\nSettings in this section are fallback defaults. PROJECT-DEFINITION.xbrief.json overrides these\nfor project-scoped settings (strategy, coverage).\n\n**Default Strategy**: [{strategy name}](../strategies/{strategy-file}.md)\n\n{If coverage != 85: \"**Coverage**: ! ≥{N}% test coverage\"}\n\n{If any experimental rules selected:\n\"## Experimental Rules\n\n{one line per selected rule, e.g.:\n- ! Use meta/SOUL.md for strategic context and purpose-driven guidance\n- ! Use meta/morals.md for ethical AI development principles\n- ~ Use meta/code-field.md for advanced architecture patterns}\"}\n\n---\n\n**Note**: Edit this file anytime to update your preferences.\n**See**: [../../main.md](../../../main.md) for framework defaults.\n```\n\n### Then\n\n- ! Emit a structured-tool question asking whether to continue to Phase 2 (project configuration) only when the host preserves numeric labels; otherwise emit the deterministic numbered menu in chat. Options: `1. Yes (continue)`, `2. Not now (exit setup)`, `3. Discuss`, `4. Back (revisit previous phase)`. The numeric labels MUST remain visible and be returned as numeric selections or exact displayed option text.\n- ⊗ Ask the phase-transition question as unnumbered conversational prose or through a structured UI that hides the canonical numeric labels -- it is a deterministic menu and MUST preserve visible numbers (#478, #1563).\n\n---\n\n## Revisit experimental rules (#46)\n\n**Goal:** Guided enable/disable of USER.md **Experimental Rules** entries that *reference* framework deposit meta files (`meta/SOUL.md`, `meta/morals.md`, `meta/code-field.md`). This is a post-bootstrap return path — not Phase 1 bootstrap, not a general preferences UI, and not an editor for framework meta file bodies.\n\n### When to enter\n\n- Returning-user re-entry option **Revisit experimental rules**\n- Direct user ask: \"revisit experimental rules\", \"toggle experimental meta\", \"turn on SOUL\", \"disable code-field\", etc.\n- USER.md exists and is complete enough to edit (Name present); missing non-meta fields still use Freshness Detection individual queries first\n\n### Out of scope\n\n- ⊗ General preferences UI / rewriting Personal or Defaults sections as part of this path\n- ⊗ Editing framework `meta/*.md` content (deposit owns SOUL / morals / code-field bodies; `directive update` refreshes deposit)\n- ⊗ Deposit layout changes\n- ⊗ Inventing a full `deft config` mega-surface or new `task config:*` verb family for this slice\n- ⊗ Re-building USER.md bootstrap / non-overwrite semantics\n- ⊗ Treating Experimental Rules lines as project-local copies of meta files — they are **references** only\n\n### Flow\n\n! **Each message MUST contain exactly ONE question** (same interview rule as Phase 1).\n\n1. ! Resolve USER.md via Platform Detection (`$DEFT_USER_PATH` → platform path). Read the file as **UTF-8**.\n2. ! Parse current Experimental Rules state (on/off) for the three paths:\n   - `meta/SOUL.md`\n   - `meta/morals.md`\n   - `meta/code-field.md`\n   - Detection: any line containing that path counts as **on** (custom wording still counts).\n3. ! Show a **current state** summary (table or short list), for example:\n\n   | Entry | State | Role |\n   |-------|-------|------|\n   | SOUL.md | on/off | Results-first agent persona |\n   | morals.md | on/off | Epistemic honesty |\n   | code-field.md | on/off | Pre-code assumption protocol |\n\n4. ! Ask which entry to change with a deterministic numbered menu (one question). Options MUST include each of the three entries as toggle targets, plus **Done (save)** / **Done (discard)**, and final two options `Discuss` and `Back`:\n\n   > \"Toggle which experimental meta entry? (current state shown above)\"\n   > 1. SOUL.md — currently {on|off}\n   > 2. morals.md — currently {on|off}\n   > 3. code-field.md — currently {on|off}\n   > 4. Done — save changes\n   > 5. Done — discard changes\n   > 6. Discuss\n   > 7. Back\n\n5. ! When the user picks an entry (1–3), optionally show the short Phase 1 explainer (steps **5a–5c** copy below), then confirm the new on/off value with a Y/n or numbered keep/flip menu. Update the **in-memory** desired state; do not write yet. Return to the toggle menu (step 4) until Done.\n6. ! On **Done — save**: show a confirmation summary of the three final on/off values and require explicit affirmative (`yes` / `confirmed` / `approve`) before write — same Post-Interview Confirmation Gate strictness.\n7. ! On **Done — discard** or **Back** without save: leave USER.md unchanged and return to the Returning-user re-entry menu (or exit if invoked directly).\n\n### Explainers (reuse Phase 1 steps 5a–5c)\n\n- **SOUL.md** — Results-first agent persona (inspired by Winston Wolf). Enforces assess-before-acting, finish-what-you-start, right-tool-for-the-job, and play-the-long-game. Keeps the AI decisive and concise. Includes a named persona ('Vinston') — drop if you prefer to define your own agent personality.\n- **morals.md** — Epistemic honesty rules. No presenting speculation as fact, label unverified claims, self-correct when wrong. Foundational trust rules for any AI agent. Strongly recommended.\n- **code-field.md** — Pre-code assumption protocol. Requires stating assumptions and naming failure modes before writing a single line. Fights the 'it compiles, ship it' instinct. Based on NeoVertex1 context-field.\n\n### Safe write rules (non-clobber)\n\n! When persisting toggles to USER.md:\n\n1. ! Write **UTF-8** (no BOM). Create parent directories only if the resolved path's parent is missing — never relocate USER.md.\n2. ! Change **only** the `## Experimental Rules` section (add the section if enabling when absent; remove the section when all three are off and no custom bullets remain).\n3. ! Canonical enable lines (match Phase 1 template):\n   - `- ! Use meta/SOUL.md for strategic context and purpose-driven guidance`\n   - `- ! Use meta/morals.md for ethical AI development principles`\n   - `- ~ Use meta/code-field.md for advanced architecture patterns`\n4. ! Disable = remove lines that mention that path. Preserve any **custom** non-meta bullets under Experimental Rules.\n5. ! **Personal** and **Defaults** section bodies MUST remain byte-identical to the pre-write file (non-clobber).\n6. ~ Prefer the pure helper `applyExperimentalRulesState` / `setExperimentalRule` from `@deftai/directive-core` `userConfig` (`packages/core/src/user-config/experimental-rules.ts`) when the package is importable (framework checkout, tests, or a thin local script). When editing by hand as an agent, apply the same rules: section-only edit, UTF-8, path-based match, canonical enable lines.\n7. ! After write, re-read USER.md and show the final on/off state to the user.\n\n⊗ Rewrite the whole USER.md from the Phase 1 template when only Experimental Rules changed\n⊗ Clobber or reformat **Personal** / **Defaults** content while toggling experimental meta\n⊗ Hand-edit framework `meta/SOUL.md`, `meta/morals.md`, or `meta/code-field.md` bodies as part of this path\n⊗ Invent `deft config` / `task config:experimental-*` for this product slice when setup re-entry suffices\n\n### Then\n\n- ! After a successful save (or discard), re-offer the Returning-user re-entry menu (Continue to Phase 2 / Revisit again / Exit / Discuss / Back) unless the user asked only for the toggle and is done.\n- ~ If Phase 2 is already complete, prefer Exit over Continue unless the user wants project reconfiguration.\n\n## Phase 2 — Project Configuration (PROJECT-DEFINITION.xbrief.json)\n\n**Goal:** Project-specific configuration — tech stack, type, quality standards — written as a xBRIEF file at `./xbrief/PROJECT-DEFINITION.xbrief.json`.\n\n! **Path Resolution Anchor**: Resolve ALL paths relative to the user's working directory (pwd) at skill entry -- never relative to the skill file location, AGENTS.md location, or any framework directory (e.g. `./deft/`). When deft is cloned as a subdirectory, the skill file lives inside the clone but all project artifacts (`./xbrief/PROJECT-DEFINITION.xbrief.json`, build files, etc.) must be resolved from the user's pwd.\n\n- ~ Skip if `./xbrief/PROJECT-DEFINITION.xbrief.json` exists (or `$DEFT_PROJECT_PATH` if set) and user doesn't want to replace\n- ⊗ Count `./deft/PROJECT-DEFINITION.xbrief.json` or `./deft/core/project.md` as the user's project config — those are framework-internal\n\n### Re-entry shadow guard (#3609)\n\n! Before any Phase 2 confirmation or file mutation when PROJECT-DEFINITION already exists, run `deft policy:show --field=plan.policy.allowDirectCommitsToMaster --project-root <policy-project-root>` and inspect **stderr as well as the exit code**. The inspector intentionally exits 0 when it can still read the namespaced value, so a warning that bare `plan.policy` coexists with `plan[\"x-directive/policy\"]` is a hard stop even when the command succeeds.\n\n! On that warning, do not regenerate, overwrite, or run a policy writer. Inventory the keys in both blocks; fold every bare-only key into `plan[\"x-directive/policy\"]`; resolve every collision explicitly; delete bare `plan.policy`; then rerun the inspector. Preserve all unrelated PROJECT-DEFINITION content. Resume only when exactly one policy block remains.\n\n⊗ Treat matching `allowDirectCommitsToMaster` values as safe while other keys may still be stranded in the shadowed block\n⊗ Copy arbitrary policy values into a diagnostic or silently choose one side of a collision\n\n### Inference\n\n- ! Before asking, infer from codebase — look for `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, `pyproject.toml`, `*.csproj`\n- ! Use inferences to pre-fill answers and confirm — don't ask blind\n- ⊗ Look inside `./deft/` for build files (`go.mod`, `package.json`, `pyproject.toml`, `Cargo.toml`, `*.csproj`, etc.) — those are framework-internal. Only inspect files at the project root and its non-`deft` subdirectories.\n- ⊗ Run git commands inside `./deft/` to determine project identity — that directory is the framework repo, not the user's project.\n- ~ If no build files are found at the project root, default the project name to the current directory name and ask for confirmation.\n\n### Track Detection\n\n! If Phase 1 was skipped (USER.md already existed), the user's track is unknown.\nBefore asking any Phase 2 questions, ask the depth question:\n\n> \"How deep do you want to go?\"\n> 1. I'm technical — ask me everything\n> 2. I have some opinions but keep it simple\n> 3. Just pick good defaults — I care about the product, not the tools\n\nWait for answer. Then follow the corresponding track in the Question Sequence below.\n\n⊗ Assume Track 1 (technical) because USER.md exists or contains strategy/coverage fields.\n⊗ Infer the track from USER.md content — always ask.\n\n### Defaults in Agentic Mode\n\n! When a question has a USER.md default, phrase it as:\n> \"{Field}: **{value}** from USER.md — keep this, or enter a different value?\"\n\n! Accept any affirmative response (\"keep\", \"yes\", \"same\", \"default\", ✓) as confirmation to use the default.\n⊗ Phrase defaults as \"press Enter to keep\" — there is no Enter in conversational mode.\n\n### Interview Rules (same as Phase 1)\n\n! **Each message MUST contain exactly ONE question.** The Phase 1 interview rules\napply here too. Do not combine questions. See `skills/deft-directive-interview/SKILL.md` for the canonical deterministic interview loop.\n\n### Question Sequence\n\n**Track 1 (technical) — 8 steps:**\n- Step 1: Ask project name (infer from build files or directory name, confirm)\n- Step 2: Ask project type (CLI, TUI, Desktop App, REST API, Web App, Library, other)\n- Step 3: Ask deployment platform:\n  1. Cross-platform (Linux / macOS / Windows)\n  2. Windows-native\n  3. macOS-native\n  4. Linux / Unix\n  5. Embedded / low-resource\n  6. Web / Cloud\n  7. Mobile (iOS / Android)\n  8. Other / not sure\n- Step 4: Ask languages — show a filtered shortlist (3–4 recommendations) based on project type + platform. If codebase markers exist (`go.mod`, `pyproject.toml`, etc.), skip and confirm: \"Detected {lang} — correct?\"\n  - If user selects \"Other\": show remaining plausible languages for the type+platform context (Tier 2)\n  - If still not found: free text input (Tier 3)\n  - If entered language has no deft `languages/{lang}.md` standards file, warn: \"deft doesn't have a standards file for {lang} yet — general defaults will be used. Continue?\"\n- Step 5: Ask tech stack (frameworks, libraries)\n- Step 6: Ask strategy (default to USER.md Defaults; ask if this project needs different — show Available Strategies numbered list with descriptions and recommended marker)\n- Step 7: Ask coverage (default to USER.md Defaults; ask if this project needs different)\n- Step 8: Ask for project-specific rules (optional, same one-per-line format as Phase 1 custom rules)\n- Step 9: Ask branching preference (typed `plan.policy.allowDirectCommitsToMaster` flag per #746):\n\n  ! Render this as a deterministic numbered menu. Default `1. Branch-based`. Final two options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md):\n\n  > \"Do you prefer branch-based workflow (create a feature branch for every change) or\n  > trunk-based (commit directly to master)? Branch-based is the default and recommended\n  > for teams; trunk-based is common for solo projects.\"\n  > 1. Branch-based ★ (recommended -- default; enforces feature branches via the deft branch-protection policy)\n  > 2. Trunk-based (direct commits to master) -- see capability-cost disclosure below\n  > 3. Discuss\n  > 4. Back\n\n  ! **Capability-cost disclosure (#746):** When the user picks option 2 (trunk-based), the agent MUST present the capability-cost disclosure verbatim BEFORE writing the typed flag, then re-prompt for explicit confirmation:\n\n  > \"Capability-cost disclosure -- enabling direct commits to the default branch turns OFF the deft branch-protection policy. The pre-commit + pre-push hooks will no longer block default-branch commits, `deft verify:branch` / `task deft:verify:branch` will pass on the default branch, and the skill-level guards in deft-directive-{swarm,review-cycle,pre-pr,release} will not halt for default-branch work. The change is reversible (`task policy:enforce-branches`) and is recorded to meta/policy-changes.log for auditability. The CI sanity check (head_ref != base_ref) remains independent and will continue to flag master->master PRs. Are you sure?\"\n  > 1. Yes, opt out -- persist `allowDirectCommitsToMaster=true` through the policy writer\n  > 2. No, keep branch-protection enforced -- persist `allowDirectCommitsToMaster=false` through the policy writer\n  > 3. Discuss\n  > 4. Back\n\n  ! Default to option 2 (enforce). Explicit affirmative on option 1 is required to opt out -- a broad `proceed` does NOT satisfy this gate. The same affirmative-only rule applies as in `/deft:change` (`yes`, `confirmed`, `approve`).\n\n  ! Record the answer as the logical field `plan.policy.allowDirectCommitsToMaster`, but do not hand-write either policy block. The common Output Path gate below invokes the only writer and stores the boolean under `plan[\"x-directive/policy\"].allowDirectCommitsToMaster`. Default `false` (enforce branches) when the user picks option 2 OR omits the question entirely. Agents MUST NOT write bare `plan.policy` or the legacy free-form `Allow direct commits to master:` narrative key.\n\n  ! **Re-running the interview detects the existing flag (#746 part G2):** After the Re-entry shadow guard passes, surface the resolved current value (e.g. \"Current setting: `allowDirectCommitsToMaster=false` (branch-protection ON)\") and ask whether to keep it or change it before re-prompting. A keep choice still runs the selected writer so legacy-only storage is migrated; an already-namespaced match is a no-op with no audit append. On Track 2 or 3, preserve an existing resolved boolean by default without asking a new branching question. Never replace an existing `true` with the greenfield `false` default unless the operator explicitly chooses the Track 1 change flow.\n\n  ! **Consumer command alternatives (#746 part G2):** Once the project is set up, use the public CLI directly:\n  - `deft policy:show --field=plan.policy.allowDirectCommitsToMaster --project-root <policy-project-root>` -- display the current resolved policy and source\n  - `deft policy:enforce-branches --actor agent:deft-directive-setup --project-root <policy-project-root>` -- set `allowDirectCommitsToMaster=false`\n  - `deft policy:allow-direct-commits --confirm --actor agent:deft-directive-setup --project-root <policy-project-root>` -- set `allowDirectCommitsToMaster=true`\n\n  Each transition is recorded to `meta/policy-changes.log` for auditability.\n\n**Track 2 (middle ground) — 4 steps:**\n- Step 1: Ask project name (infer from build files or directory name, confirm)\n- Step 2: Ask project type (CLI, TUI, Desktop App, REST API, Web App, Library, other)\n- Step 3: Ask languages (show detected, confirm or adjust; if none detected, infer from type and ask)\n- Step 4: Ask strategy (default to USER.md Defaults; ask if this project needs different — show Available Strategies numbered list with descriptions and recommended marker)\n- Default coverage to USER.md Defaults without asking\n- ! Do not ask a branching question. For greenfield or absent policy, the common Output Path gate persists `allowDirectCommitsToMaster=false`. On re-entry it preserves the resolved existing boolean, including `true`; change it only through the Track 1 disclosure gate.\n\n**Track 3 (non-technical) — 1 step:**\n- Step 1: Present summary of inferences: \"Based on your project: {name} ({type}), built with {stack}. Look right?\"\n- ⊗ Ask about strategy or coverage — use Phase 1 defaults\n- ! Do not ask a branching question. For greenfield or absent policy, the common Output Path gate persists `allowDirectCommitsToMaster=false`. On re-entry it preserves the resolved existing boolean, including `true`; change it only through the Track 1 disclosure gate.\n\n### Output Path\n\n`./xbrief/PROJECT-DEFINITION.xbrief.json` (or the resolved `$DEFT_PROJECT_PATH` if set). Create `<policy-project-root>/xbrief/` and its lifecycle subfolders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`) if they don't exist. A configured PROJECT-DEFINITION may live elsewhere; the lifecycle root remains under `<policy-project-root>`.\n\n### Branch-policy persistence gate (#3609)\n\n! This gate applies to **every track**, including default/greenfield and keep/re-entry paths. For greenfield setup, first write the confirmed PROJECT-DEFINITION base without any hand-authored policy block. On re-entry, merge base changes while preserving the existing policy block byte-for-byte: keep a legacy-only bare `plan.policy` intact until the shared writer migrates the whole block, and keep a namespaced block intact until that writer updates it. Never delete or reconstruct a legacy-only block before the writer because it may contain unrelated keys such as `wipCap`. Then invoke exactly one public writer:\n\n- Branch-based/greenfield-default/keep-false: `deft policy:enforce-branches --actor agent:deft-directive-setup --project-root <policy-project-root>`\n- Explicitly confirmed trunk-based/keep-true/Track 2 or 3 existing-true: `deft policy:allow-direct-commits --confirm --actor agent:deft-directive-setup --project-root <policy-project-root>`\n\n! A nonzero writer exit halts Phase 2 immediately. Do not print a completion claim and do not retry by hand-editing JSON. Resolve the reported configuration problem, rerun the Re-entry shadow guard, and invoke the writer again.\n\n! Before Phase 2 can complete, re-read PROJECT-DEFINITION and verify all three postconditions: `plan[\"x-directive/policy\"].allowDirectCommitsToMaster` is the selected boolean; bare `plan.policy` is absent; and `deft verify:vbrief-conformance --project-root <policy-project-root>` exits 0. Also run `deft policy:show --field=plan.policy.allowDirectCommitsToMaster --project-root <policy-project-root>` and confirm its resolved value matches the selection. Any mismatch is a hard stop.\n\n⊗ Finish Phase 2 after writing only the narrative template\n⊗ Add a setup-specific policy writer or weaken conformance to permit bare `plan.policy`\n\n### GitHub PR Template Scaffolding (#531)\n\n! Before writing `PROJECT-DEFINITION.xbrief.json`, offer to scaffold a default GitHub PR template so downstream skills (`deft-directive-refinement` Pre-Flight, `deft-directive-pre-pr`) can satisfy their `.github/PULL_REQUEST_TEMPLATE.md` checks without blocking.\n\n1. ! Ask the user with a deterministic numbered menu: \"Create a default GitHub PR template at `.github/PULL_REQUEST_TEMPLATE.md`?\" Options: `1. Yes`, `2. No`, `3. Discuss`, `4. Back`. Use a structured question tool only if those numeric labels remain visible and are returned as numeric selections or exact displayed option text.\n2. ! If the user accepts AND `.github/PULL_REQUEST_TEMPLATE.md` does NOT already exist: copy `templates/PULL_REQUEST_TEMPLATE.md` (shipped with deft) to `./.github/PULL_REQUEST_TEMPLATE.md` in the consumer project. Create `.github/` if it does not exist.\n3. ! If the file already exists, do NOT overwrite it — report that it is present and continue.\n4. ~ If the user declines, note that `deft-directive-refinement` Pre-Flight will offer to scaffold later when needed.\n\n⊗ Overwrite an existing `.github/PULL_REQUEST_TEMPLATE.md` without explicit user approval.\n\n### Headless Coverage Warning — display-bound GUI entry points (#1027)\n\n! The trigger is a **display-bound GUI event loop** (pygame, tkinter, PyQt/PySide, Kivy, Electron) that cannot run without a real display — typically a **Desktop App** project type, or a TUI that embeds such a GUI. Terminal-UI frameworks (textual, urwid, blessed, ncurses) run in the terminal and DO support headless testing (e.g. textual's `App.run_async()` + `Pilot`), so a standard TUI is NOT in scope — do not omit its coverage. The concrete commands below assume a **Python** GUI stack (pygame/tkinter); the same \"omit the un-runnable loop, test the logic\" principle applies to non-Python desktop stacks (Electron/JS, .NET/WPF, Qt/C++) using that language's own headless-test and coverage-exclusion tooling. When the Phase 2 project type resolves to a display-bound GUI project, warn the user BEFORE writing `PROJECT-DEFINITION.xbrief.json` (adapt the wording to the project's language):\n\n> \"Heads up: pygame/tkinter event loops can't be tested headlessly, so the display-bound entry point (e.g. `src/ui.py`) reports near-zero coverage and drags the overall percentage below the 85% threshold. I recommend excluding the UI entry point from coverage measurement and keeping it thin — push testable logic (state, scoring, input handling) into separate modules.\"\n\n! When scaffolding or advising on `pyproject.toml` for a display-bound GUI project, add the display-bound entry point to `[tool.coverage.run] omit` so `task check` measures logic modules only:\n\n```toml\n[tool.coverage.run]\nomit = [\n  \"*/tests/*\",\n  \"*/venv/*\",\n  \"*/.venv/*\",\n  \"src/ui.py\",        # display-bound pygame/tkinter event loop -- cannot run headlessly (#1027)\n]\n```\n\n- ! Keep the omit narrow — exclude only the event-loop shell, never a module that also holds business logic. If logic and the loop are mixed, recommend refactoring the logic into a separate, fully-tested module first.\n- ~ For a Python project, point the user at `languages/python.md` (the `Headless GUI / event-loop testing` section under Patterns) for the headless-test pattern (`SDL_VIDEODRIVER=dummy`) and the full coverage-omit rationale; for a non-Python GUI stack, apply the same principle with that language's headless-test and coverage-exclusion tooling.\n- ⊗ Apply the omit to a headless-capable terminal-UI project (textual/urwid/blessed/ncurses) — those frameworks test headlessly, so omitting them hides measurable coverage, the opposite of the intended effect.\n- ⊗ Silently accept the default 85% coverage gate for a display-bound GUI project without surfacing the headless blind spot — the agent reports an inflated per-session coverage that collapses when the full `src/` is measured (the 2026-05-10 tic-tac-toe desktop-UI swarm recurrence).\n\n### Template\n\n! The output MUST conform to the canonical xBRIEF v0.8 schema (`xbrief/schemas/xbrief-core-0.8.schema.json`, strict `const: \"0.8\"`). See [`../../conventions/references.md`](../../conventions/references.md). Write-path default is **0.8 only** (#2971); legacy 0.6 remains read-accepted until `deft migrate:xbrief`.\n\n```json\n{\n  \"xBRIEFInfo\": {\n    \"version\": \"0.8\",\n    \"author\": \"agent:deft-directive-setup\",\n    \"description\": \"Project identity gestalt\",\n    \"created\": \"{ISO-8601 timestamp}\"\n  },\n  \"plan\": {\n    \"title\": \"{Project Name}\",\n    \"status\": \"running\",\n    \"narratives\": {\n      \"Overview\": \"{Brief project description}\",\n      \"TechStack\": \"{project type} using {languages} — {tech stack details}\",\n      \"Strategy\": \"Use {strategy name} for this project\",\n      \"Quality\": \"Run task check before every commit. Achieve >= {coverage}% coverage overall + per-module. Store secrets in secrets/ dir.\",\n      \"ProjectRules\": \"{Any rules the user specified, or 'No project-specific rules defined.'}\",\n      \"Branching\": \"{If confirmed trunk-based: 'Trunk-based workflow', otherwise 'Branch-based workflow (default)'}\"\n    },\n    \"items\": []\n  }\n}\n```\n\n- ! All `narratives` values MUST be plain strings — never objects or arrays\n- ! `items` starts empty — populated as scope xBRIEFs are created in lifecycle folders\n\n### Then\n\n- ! Emit a structured-tool question asking whether to continue to Phase 3 (specification) only when the host preserves numeric labels; otherwise emit the deterministic numbered menu in chat. Options: `1. Yes (continue)`, `2. Process-only (keep Phase 2 identity)`, `3. Discuss`, `4. Back (revisit previous phase)`. The numeric labels MUST remain visible and be returned as numeric selections or exact displayed option text.\n- ! Option 2 is the process-only adoption: leave setup with Phase 2 identity in place. Point at session ritual (`deft session:start` / `deft verify:session-ritual -- --tier=gated`) / `deft check` / later Add scope when a slice is ready. Do not write `xbrief/proposed/*.xbrief.json`. Do not overwrite PROJECT-DEFINITION narratives. GitHub issues stay cache/queue inputs. Docs stay described content. Skip Lifecycle Bridge, export prompt, Acceptance Gate, and build handoff.\n- ⊗ Bind docs or GitHub issues as the next-build plan.\n- ⊗ Use Back or Other as the process-only adoption path.\n- ⊗ Ask the phase-transition question as unnumbered conversational prose or through a structured UI that hides the canonical numeric labels -- it is a deterministic menu and MUST preserve visible numbers (#478, #1563).\n\n### Follow-up: triage onboarding (#1143)\n\n- ~ After Phase 2 writes `PROJECT-DEFINITION.xbrief.json`, recommend `task triage:welcome` to the user as the single chained command for picking up the v0.27 triage surface. The N3 ritual (#1143) is the consolidating onboarding step for the #1119 governance swarm verbs (`task triage:bootstrap` / `task triage:scope` / `plan.policy.wipCap` writes / `task scope:demote --batch` relief / `task triage:summary`); without it consumers must learn each verb individually from the v0.27 release notes.\n- ~ `task triage:welcome` is idempotent and detection-bound -- each phase emits an informational stderr line and skips when its precondition is already satisfied, so a re-run after a partial completion resumes cleanly. The destructive phases (subscription / `wipCap` writes, optional WIP-relief invocation) are gated by numbered-menu prompts per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md). See [`../../UPGRADING.md`](../../UPGRADING.md) `## From v0.26.x -> v0.27` for the full walkthrough.\n### Consumer AGENTS always-pin recommendations (#2508)\n\n! After Phase 2 completes (or when closing a greenfield bootstrap), tell the consumer that process-critical directive skills should be named in their project's AGENTS.md **unmanaged header** when false-negative risk matters — full tier definitions: [`../../docs/skill-pin-policy.md`](../../docs/skill-pin-policy.md).\n~ Recommend the default consumer pin set for lifecycle work: `deft-directive-build` (implementation), `deft-directive-pre-pr` (before PR), `deft-directive-review-cycle` (bot review loop), and `deft-directive-swarm` when they plan parallel agents. Each is referenced by skill id + `.deft/core/.agents/skills/<id>/SKILL.md` path — not by pasting skill bodies.\n⊗ Recommend pinning entire `languages/`, `deployments/`, or other framework doc packs into AGENTS.md (#2508 anti-pattern).\n\n---\n\n## Phase 3 — Specification\n\n**Goal:** Generate an implementable spec using the strategy chosen in Phase 2, producing scope xBRIEFs in `xbrief/proposed/` and PROJECT-DEFINITION narratives for human approval — greenfield v0.20 does not create `specification.xbrief.json`.\n\n! **Path Resolution Anchor**: Same rule as Phase 2 -- resolve ALL paths relative to the user's pwd at skill entry, never relative to the skill file, AGENTS.md, or any framework directory.\n\n- ~ Skip if user already has scope xBRIEFs in `./xbrief/` they're happy with\n- ! Check `./xbrief/PROJECT-DEFINITION.xbrief.json` and `./xbrief/proposed/` for existing greenfield authority; treat `./xbrief/specification.xbrief.json` as a full-spec compatibility artifact only\n- ⊗ Count ANY file inside `./deft/` as the project's spec — those are framework-internal\n  (e.g. `deft/PROJECT.md`, `deft/specs/`, `deft/templates/`, `deft/core/project.md`\n  are all part of the framework, NOT the user's project)\n\n### Onboarding Question\n\n! Before proceeding with the strategy gate, ask the onboarding question. Use the same add-scope / update / replace vocabulary as the Chaining Gate in [strategies/interview.md](../../strategies/interview.md#chaining-gate).\n\n**Brownfield detector** (same as Chaining Gate): `PROJECT-DEFINITION` exists (`./xbrief/` or legacy `./vbrief/`) **OR** any lifecycle folder (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`) has scope records.\n\n> \"How should we treat this project's specification?\"\n> 1. **Add scope to this project** [default when brownfield] — load existing identity; skip greenfield \"what are we building?\"; emit one proposed scope; Preparatory Guard on write\n> 2. **Update project definition** — delta interview → Spec-Generating Guard → merge narratives into existing PROJECT-DEFINITION\n> 3. **Replace specification (scrap)** — only after explicit affirmative (`yes` / `confirmed`); then full new-spec path\n> 4. **Starting a new project specification** [default when greenfield] — proceed to the Strategy Gate below\n> 5. **Process-only (keep Phase 2 identity)** — same exit as Phase 2 option 2; no new scope; no spec write\n> 6. **Discuss** — explore these options before choosing\n> 7. **Back** — return to the previous setup question\n\n- ! Default based on repo state via the brownfield detector above (brownfield → Add scope; greenfield → Starting new)\n- ! Final two numbered options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md)\n- ! If **Add scope**: skip the full interview, create a new scope xBRIEF in `./xbrief/proposed/` with the user's description, apply Preparatory Guard on write, then surface the Lifecycle Bridge + End-of-Phase-3 Export Prompt + handoff sections below (do not dead-end after the write)\n- ! If **Update project definition**: run a delta interview; apply Spec-Generating Guard against `./xbrief/PROJECT-DEFINITION.xbrief.json` (or legacy `./vbrief/PROJECT-DEFINITION.vbrief.json` if that is the existing identity); merge narratives (do not wholesale replace unless the user confirmed scrap)\n- ! If **Replace specification (scrap)**: require explicit `yes`/`confirmed`, then proceed to the Strategy Gate as a greenfield-style full path\n- ! If **Starting new**: proceed to the Strategy Gate below\n- ! If **Process-only (keep Phase 2 identity)**: same exit as Phase 2 option 2. Do not write a scope xBRIEF. Do not merge or scrap PROJECT-DEFINITION narratives. Skip Lifecycle Bridge, End-of-Phase-3 Export Prompt, Acceptance Gate, and build handoff. Point at session ritual / `deft check` / later Add scope. GitHub issues stay cache/queue inputs. Docs stay described content.\n- ⊗ Treat brownfield repos as \"Starting new\" by default\n- ⊗ Accept vague confirmation (`proceed`, `ok`) for Replace/scrap\n- ⊗ Exit immediately after Add-scope write without the lifecycle bridge / export / handoff guidance\n\n### ⚠️ MANDATORY: Strategy Gate — Do This First\n\n! **STOP.** You MUST determine the correct strategy before doing anything else.\n\n1. ! Open `./xbrief/PROJECT-DEFINITION.xbrief.json` (the file written in Phase 2)\n2. ! Find the `narratives.Strategy` value\n3. ! Extract the strategy name from the narrative\n\n**Dispatch:**\n\n- **interview** (or default) → Continue to the Sizing Gate below ✅\n- **anything else** (discuss, yolo, speckit, research, brownfield, map, etc.) →\n  1. ! Read `deft/strategies/{strategy-name}.md` **right now, in this same turn**\n  2. ! Begin the strategy's workflow immediately — ask its first question\n  3. ! For `research`, the first question is the strategy's Scope Confirmation Gate (#1273); ask it and wait before any autonomous research begins.\n  4. ! For `research`, after the research artifact is written, surface the strategy's Then: Chaining Gate and wait for a user selection; do NOT create scope xBRIEFs from research output unless the user later chooses a spec-generating path; do NOT fall through to the interview output path after research.\n  5. ! **STOP reading this section** — do NOT use the interview process below\n\n- ⊗ Default to interview without reading PROJECT-DEFINITION.xbrief.json\n- ⊗ Continue reading below when PROJECT-DEFINITION.xbrief.json specifies a non-interview strategy\n- ⊗ Assume interview because the sections below describe the interview process\n- ⊗ Fabricate justification for using interview when the user chose a different strategy\n- ⊗ Announce the strategy choice and then stop — you must immediately read the file and start\n\n---\n\n*⬇️ Everything below applies ONLY to the interview strategy. If your strategy is anything else, STOP — follow your strategy file instead.*\n\n### Sizing Gate (interview and yolo strategies only)\n\n! After hearing what the user wants to build and their feature list, determine\nproject complexity per [strategies/interview.md](../../strategies/interview.md#sizing-gate).\n\n- ! Check `PROJECT-DEFINITION.xbrief.json` narratives for `Light` or `Full` — if declared, use that path\n- ! If not declared, propose a size and **ask the user to confirm in a dedicated message**\n- ! **Wait for the user's response** before asking any interview questions\n- ⊗ Combine the sizing proposal with the first interview question\n- ⊗ Proceed to interview questions before the user has confirmed the path\n\n**Light** (small/medium): Interview → slim narratives (Overview + Architecture) in `PROJECT-DEFINITION.xbrief.json` → scope xBRIEFs in `xbrief/proposed/`.\n**Full** (large/complex): Interview → rich PROJECT-DEFINITION narratives for user approval → scope xBRIEFs with traceability.\n\n! Neither greenfield path creates `xbrief/specification.xbrief.json`; that file remains a full-spec compatibility artifact.\n\n### Interview Process (interview strategy)\n\nPer [strategies/interview.md](../../strategies/interview.md#interview-rules-shared-by-both-paths):\n\n- ! Ask what to build and features first\n- ! Ask **ONE** focused, non-trivial question per step\n- ~ Provide numbered options with an \"other\" choice\n- ! Mark which option is RECOMMENDED\n- ⊗ Ask multiple questions at once\n- ⊗ Make assumptions without clarifying\n- ~ Use structured question tools for interview questions only when they preserve visible numeric option labels and return numeric selections or exact displayed option text; otherwise render the numbered menu in chat.\n\n**Question Areas:**\n- ! Missing decisions (language, framework, deployment)\n- ! Edge cases (errors, boundaries, failure modes)\n- ! Implementation details (architecture, patterns, libraries)\n- ! Requirements (performance, security, scalability)\n- ! UX/constraints (users, timeline, compatibility)\n- ! Tradeoffs (simplicity vs features, speed vs safety)\n\n**Non-Technical Users:**\n- ~ Adjust vocabulary: \"How do you want to store data?\" not \"What database engine?\"\n- ~ \"Will other apps talk to this?\" not \"REST or GraphQL?\"\n\n**Completion:**\n- ! Continue until little ambiguity remains\n- ! Spec must be comprehensive enough to implement\n\n### Output — Light Path\n\n1. ! Merge the confirmed slim narratives into `./xbrief/PROJECT-DEFINITION.xbrief.json`:\n   - `Overview`: Brief project summary\n   - `Architecture`: System design description\n2. ! Create scope xBRIEFs in `./xbrief/proposed/` for each identified work item\n   - Each scope xBRIEF follows the `YYYY-MM-DD-descriptive-slug.xbrief.json` filename convention (slug rules in [`../../conventions/vbrief-filenames.md`](../../conventions/vbrief-filenames.md))\n   - Each MUST use `\"xBRIEFInfo\": { \"version\": \"0.8\" }`\n   - Each MUST include embedded Requirements (FR-N, NFR-N) in its `narrative`\n   - Each task SHOULD reference which FR/NFR it implements via `narrative.Traces`\n   - When the scope originates from a GitHub issue, include a `references` entry in the canonical form (see [`../../conventions/references.md`](../../conventions/references.md)):\n     ```json\n     \"references\": [\n       {\n         \"uri\": \"https://github.com/{owner}/{repo}/issues/{N}\",\n         \"type\": \"x-xbrief/github-issue\",\n         \"title\": \"Issue #{N}: {issue title}\"\n       }\n     ]\n     ```\n3. ! Summarize decisions and ask the user to approve the PROJECT-DEFINITION narratives and proposed scope set\n4. ! Record approval in the setup session; do not manufacture or require `specification.xbrief.json`\n- ⊗ Create a separate PRD.md on the Light path\n- ⊗ Generate an authoritative PRD.md — if needed, users run `task prd:render`\n\n! The xBRIEF files MUST conform to `xbrief/schemas/xbrief-core-0.8.schema.json` (v0.8):\n\n- ! All `narratives` and `narrative` values MUST be plain strings — never objects or arrays\n- ! Nested children within a PlanItem use `items` (preferred field); `subItems` is the deprecated legacy alias kept for backward compatibility only\n- ⊗ Mix `items` and `subItems` on the same PlanItem — pick one (prefer `items`)\n- ⊗ Emit `\"version\": \"0.6\"` on any new write path — current engine write-default is `0.8` only (#2971)\n\n### Output — Full Path\n\n1. ! Merge these rich narratives into `./xbrief/PROJECT-DEFINITION.xbrief.json` for review:\n   - `ProblemStatement`: What problem this project solves\n   - `Goals`: High-level project goals\n   - `UserStories`: User stories in standard format\n   - `Requirements`: Structured requirements (FR-N: ..., NFR-N: ...)\n   - `SuccessMetrics`: Measurable success criteria\n   - `Architecture`: System design and technical architecture\n   - `Overview`: Brief project summary\n2. ! **Human approval gate**: Present the PROJECT-DEFINITION narratives and proposed scope plan to the user for review. The user may request changes before approving.\n3. ! Record approval in the setup session and proceed to downstream generation; do not manufacture or require `specification.xbrief.json`\n4. ! Create scope xBRIEFs in `./xbrief/proposed/` with traceability to requirement IDs from the narratives\n- ! Scope xBRIEFs MUST trace tasks back to requirement IDs (FR-1, NFR-1) from the `Requirements` narrative\n- ⊗ Generate an authoritative PRD.md — if needed, users run `task prd:render`\n\n**Spec Structure (both paths):**\n- ! Overview, Architecture\n- ! Implementation Plan: scope xBRIEFs in `xbrief/proposed/` with phases and dependencies\n- ! Explicit dependency mapping MUST use the field consumers actually read for the scope shape:\n  - **Story-shaped scopes** (`plan.metadata.kind = \"story\"` or scopes intended for swarm allocation / decompose): sequential/blocked work MUST set `plan.metadata.swarm.depends_on` to an array of **resolvable story identifiers**. Swarm readiness, decompose, and queue traversal read **only** this field for story ordering — not `plan.metadata.dependencies` alone. ! Each `depends_on` entry MUST equal the blocking scope's `plan.id` when that field is set; otherwise the blocking artifact's **filename stem** (basename with `.xbrief.json` / `.vbrief.json` stripped — the same stem readiness uses as `story_id`). ⊗ Use rendered titles, free-form prose, date-only prefixes, or unstripped full filenames — those do not resolve and leave the generated scope blocked.\n  - **Phase/epic or cross-scope roadmap batches**: MAY also set plan-level `plan.metadata.dependencies` for roadmap/export readers.\n  - `edges` / `references` may supplement documentation but **do not** replace `plan.metadata.swarm.depends_on` for sequential story scopes.\n- ! When multiple scopes are produced in one Phase 3 pass, encode machine-readable dependency ordering before finishing the write: independent scopes use empty `plan.metadata.swarm.depends_on` (`[]`); sequential/blocked story scopes use non-empty `plan.metadata.swarm.depends_on`. Optionally mirror the same DAG in `plan.metadata.dependencies` for roadmap views.\n- ~ Scopes designed for parallel work by multiple agents\n- ⊗ Deposit sequential story-shaped scopes with only `plan.metadata.dependencies` / `edges` / `references` and missing `plan.metadata.swarm.depends_on` — orchestration will treat them as independent or reject readiness.\n- ⊗ Deposit multiple generated scope xBRIEFs with no dependency metadata and rely on filenames or human prose for ordering.\n- ! Testing Strategy and Deployment captured in narratives\n- ⊗ Write code — specification only\n\n### Lifecycle Bridge to Downstream Skills (#1025)\n\n! Scope xBRIEFs created by Phase 3 (both Light and Full paths) AND by the Onboarding Question \"Add scope to this project\" branch land in `xbrief/proposed/` with `plan.status: proposed`. This is the canonical deposit point per the deft lifecycle (`proposed -> pending -> active -> completed`). The #810 implementation-intent gate (`task xbrief:preflight`) and the deft-directive-swarm Phase 0 Step 1 preflight BOTH require candidate xBRIEFs to live in `xbrief/active/` with `plan.status == \"running\"` before any agent can dispatch against them; setup deliberately stops at `proposed/` because the lifecycle commitment (promote + activate) belongs to the downstream skill, not the setup interview.\n\n! Surface this bridge to the user in the Phase 3 → next-skill handoff so they are not surprised by a wholesale preflight rejection downstream:\n\n  - **If the next step is `skills/deft-directive-swarm/SKILL.md`**: the swarm skill's Phase 0 Step 0.5 (Lifecycle Bridge -- Promote and Activate Proposed Scope xBRIEFs) is the canonical bridge. The monitor will scan `xbrief/proposed/` and `xbrief/pending/`, present in-scope candidates, and run `task scope:promote -- <path>` then `task scope:activate -- <path>` on explicit user approval. No manual operator action is required ahead of the swarm invocation.\n  - **If the next step is `skills/deft-directive-refinement/SKILL.md`**: the refinement skill's Phase 4 (Promote/Demote) owns the same `task scope:promote` / `task scope:activate` surface and runs the bridge as part of the refinement loop. The refinement skill MAY leave xBRIEFs in `pending/` deliberately when they are queued for prioritisation rather than immediate dispatch.\n  - **If the user wants to invoke an implementation agent directly via `skills/deft-directive-build/SKILL.md` or `start_agent`**: the bridge MUST be run manually before dispatch -- `task scope:promote -- xbrief/proposed/<file>` then `task scope:activate -- xbrief/pending/<file>`. Both commands are idempotent and exit 0 on no-op. The #810 preflight gate (`task xbrief:preflight -- <active-path>`) will exit 0 only after the activate step.\n\n⊗ Auto-run `task scope:promote` or `task scope:activate` from the setup skill on the Phase 3 outputs. The lifecycle commitment belongs to the user (\"I am ready to swarm/build on this scope\"), not the setup interview; silent promotion would clear the #810 implementation-intent gate without explicit user authorisation and bypass the deterministic-questions contract that protects every other Phase 3 transition.\n\n⊗ Drop the user at the end of Phase 3 with scope xBRIEFs in `xbrief/proposed/` and no forward pointer to the bridge. Without this section the user discovers the gap at runtime when the swarm Phase 0 Step 1 preflight rejects every candidate (`Invalid transition: 'activate' requires file in pending/`), as in the originating 2026-05-10 first-session consumer tic-tac-toe swarm (issue #1025).\n\n### End-of-Phase-3 Export Prompt (project:export-spec)\n\n! After scope xBRIEFs are written to `xbrief/proposed/` and PROJECT-DEFINITION is populated, but BEFORE handing off to `deft-directive-build` (or advancing speckit Phase 3 → Phase 4), ask the user whether to generate human-readable exports. Greenfield v0.20 projects export via `task project:export-spec` (not legacy `task spec:render`). This replaces the invisible skip-if-absent behavior of `task check` (#398), closes the greenfield gap (#433), and is the Phase 3 → Phase 4 transition gate required by [strategies/speckit.md Post-Phase 3 Transition Gate](../../strategies/speckit.md#post-phase-3-transition-gate-export-for-review) (#432 / #2013).\n\n1. ! Prompt: \"Your scope xBRIEFs are ready. Generate a stakeholder-facing spec export and/or `PRD.md` now? (recommended for stakeholder review)\"\n   1. Yes — export spec (+ PRD if selected)\n   2. Spec export only (`SPECIFICATION.md`)\n   3. `PRD.md` only\n   4. Skip — I'll export later with `task project:export-spec` / `task prd:render`\n2. ! Run the selected export command(s):\n   - `task project:export-spec` → writes `SPECIFICATION.md` from PROJECT-DEFINITION + lifecycle scopes (greenfield default; stakeholder audience)\n   - `task project:export-spec -- --audience=internal` → same export but includes proposed scopes under `## Scope outlook` (use for setup/speckit internal handoff when proposed scopes need visibility)\n   - `task prd:render` → writes `PRD.md` (optional stakeholder review)\n   - Legacy `task spec:render` — migrated trees only (when `xbrief/specification.xbrief.json` exists); do NOT use on greenfield v0.20 projects\n3. ! If the user picked a speckit-strategy project: export is **mandatory** at this boundary — invoke `task project:export-spec` (with `--audience=internal` when proposed scopes exist) even if the user declined the prompt, because speckit Phase 3 → Phase 4 is gated on **export succeeded** (exit 0), not on `specification.xbrief.json` approval.\n4. ! Confirm to the user which files were written and remind them that direct edits to `SPECIFICATION.md` / `PRD.md` are overwritten on the next export — edit xBRIEF narratives in `xbrief/proposed/` and PROJECT-DEFINITION instead.\n5. ~ If the user skipped export and is NOT on a speckit strategy, no-op and continue.\n\n⊗ Advance a speckit project to Phase 4 without a successful `task project:export-spec` at this gate — export must succeed (exit 0) for the Phase 3 transition criterion.\n⊗ Silently skip the prompt — greenfield users who never open a PR will miss the exports without it.\n⊗ Invoke legacy `task spec:render` on a greenfield v0.20 project — use `task project:export-spec` instead (#2013).\n\n### Handoff to deft-directive-build\n\n- ! Emit a structured-tool question asking whether to continue toward the build phase only when the host preserves numeric labels; otherwise emit the deterministic numbered menu in chat. Options: `1. Yes (run cost phase)`, `2. Not now (exit setup)`, `3. Discuss`, `4. Back (revisit previous phase)`. The numeric labels MUST remain visible and be returned as numeric selections or exact displayed option text.\n- ! If the user picks Yes, invoke `skills/deft-directive-cost/SKILL.md`; only a recorded Build or Skip decision from that skill may hand off to `skills/deft-directive-build/SKILL.md`\n- ⊗ Invoke the build skill directly from setup and bypass the required cost decision\n- ⊗ Leave user with a dead end -- always offer the next step via the structured-tool phase-transition question\n- ⊗ Ask the handoff-to-build question as unnumbered conversational prose or through a structured UI that hides the canonical numeric labels -- it is a deterministic menu and MUST preserve visible numbers (#478, #1563).\n\n## Warp Auto-Approve Warning\n\n! **Recommended Warp setting**: Before running deft-directive-setup, ensure Warp's AI autonomy is set to **\"Always ask\"** in **AI -> Profile Settings**. When set to a higher autonomy level (e.g. \"Auto-run\"), Warp may silently self-answer interview questions without user input, producing garbage USER.md/PROJECT-DEFINITION.xbrief.json with no error or warning. The post-interview confirmation gate (below) is the last line of defense, but prevention is better than detection.\n\n## Post-Interview Confirmation Gate\n\n! After completing ALL interview questions for any phase (Phase 1, Phase 2, or Phase 3), but BEFORE writing any files:\n\n1. ! Display a **summary of all captured values** in a clearly formatted list -- include every field that will be written to the output file (e.g. name, strategy, coverage, languages, project type, custom rules, etc.)\n2. ! Ask the user for explicit confirmation: \"These are the values I captured. Write files? (yes/no)\"\n3. ! Accept only explicit affirmative responses (`yes`, `confirmed`, `approve`) -- reject vague responses (`proceed`, `do it`, `go ahead`) the same way `/deft:change` does\n4. ! If the user says `no`: re-display the values and ask which ones to correct, then re-confirm before writing\n5. ! If any value appears to be auto-generated filler (e.g. repeated default text, placeholder strings, or values that echo the question prompt), warn the user explicitly: \"Some values look like they may have been auto-filled rather than provided by you. Please review carefully.\"\n\n⊗ Write USER.md, PROJECT-DEFINITION.xbrief.json, lifecycle scope xBRIEFs, or any other deft-directive-setup artifact without first displaying captured values and receiving explicit user confirmation.\n⊗ Create `specification.xbrief.json` on a greenfield Light or Full path solely to satisfy export, cost, or build handoff.\n⊗ Treat a broad \"proceed\" or \"continue\" as confirmation to write files -- the user must explicitly confirm the displayed values.\n\n? **Yolo strategy carve-out**: When the user's chosen strategy is `yolo` (auto-pilot), the confirmation gate still applies but the agent (Johnbot) may self-confirm on the user's behalf by displaying the summary and immediately proceeding -- the user has already opted into auto-pilot by selecting yolo. The summary must still be displayed so the user can interrupt if values look wrong.\n\n## Anti-Patterns\n\n- ! When deft-directive-setup generates or updates USER.md, the `deft_version` field MUST be set to the current framework version. USER.md is the only artifact that carries this field.\n- ⊗ Generate a USER.md without including the `deft_version` field\n- ⊗ Write `deft_version` or `DeftVersion` into PROJECT-DEFINITION, specification, or plan xBRIEFs. Those stamps are retired (HASH4271). Specification `deft_version` has no framework seeding path; Pass 1 absence locks are the only control.\n- ⊗ Explore codebase before Phase 1 questions\n- ⊗ Read framework files before first question\n- ⊗ Batch multiple questions into one message — ask one at a time, interview style\n- ⊗ Ask jargon-heavy questions to non-technical users\n- ⊗ Ask about things inferable from codebase (Phase 2+)\n- ⊗ Skip phases without asking\n- ⊗ Generate files without confirming content\n- ⊗ Present choices through a host UI that replaces the canonical numbers with alphabetic affordances or unlabeled buttons\n- ⊗ Resolve paths relative to the skill file, AGENTS.md, or framework directory instead of the user's pwd at skill entry\n- ⊗ Generate an authoritative PRD.md — PRD.md is a read-only export via `task prd:render`, never a source of truth\n- ⊗ Skip the Returning-user re-entry / Revisit experimental rules path when USER.md exists and the operator entered setup to change experimental meta (#46)\n- ⊗ Clobber Personal or Defaults while toggling Experimental Rules (#46)\n- ⊗ Invent a full `deft config` verb family for experimental meta when setup re-entry suffices (#46)\n",
+      "body": "# Deft Directive Setup\n\nAgent-driven alternative to `directive init` plus setup Phases 1-3 (`task project:render` / spec interview).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- User says \"set up deft\", \"configure deft\", or \"bootstrap my project\"\n- User asks to create USER.md, PROJECT-DEFINITION.xbrief.json, or a specification\n- User clones a deft-enabled repo for the first time with no config\n- User says \"revisit experimental rules\", \"toggle experimental meta\", \"enable SOUL\", \"disable morals\", or wants to change Experimental Rules after bootstrap (#46)\n\n## Opt-out flag (`.no-deft-directive`) (#2926)\n\n! Before Pre-Cutover Detection Guard, Phase 1, or any install/setup step, check the **project root** for `.no-deft-directive` (exact lowercase name; presence = flag; empty or short `#` comment OK).\n\n| Condition | Action |\n|-----------|--------|\n| Flag **present** | Stop. Tell the human: \"Directive disabled via `.no-deft-directive`\". ⊗ Offer install, session ritual, or setup interview. |\n| Flag **absent**, no Directive deposit (`.deft/core`) | ? Ask whether to use Directive. On **no** → create root `.no-deft-directive` (optional one-line rationale) and stop. On **yes** → continue setup and ⊗ create the flag. |\n| Operator says **stop using DD** | Create `.no-deft-directive`. ⊗ Auto-delete `.deft/` (explicit cleanup only). |\n| Operator says **start using DD** | Remove `.no-deft-directive` and ensure install (`directive init` / deposit). |\n\n! Flag is **root-only** (workspace root opened). Nested monorepo package roots are out of scope for v1.\n! Flag **wins locally** over trusted-org / product-signal force-on (v1).\n! Flag + deposit = inconsistent: warn loudly; doctor diagnoses; do not silently refresh. See `content/docs/no-deft-directive.md`.\n\n## Consumer-first default (#1813)\n\n! Assume the operator is **using Deft in their project** (consumer path). Proceed directly to the Pre-Cutover Detection Guard and Phase 1 — do NOT open with a contributor-vs-consumer fork.\n\n~ The overwhelming majority of setup sessions are consumer installs; contributor onboarding is a separate, opt-in path (see below).\n\n## Contributor / framework-maintainer path (secondary)\n\n? Only enter this branch when the user **explicitly** says they are working on Deft itself (framework source checkout, `deftai/directive` clone, or maintainer tooling).\n\nWhen that happens:\n\n1. ! Tell the user: \"Contributor setup lives in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) and this repo's root [`AGENTS.md`](../../../AGENTS.md). Use the maintainer installer: `deft-install --yes --upgrade --maintainer --repo-root . --json`.\"\n2. ⊗ Continue the consumer USER.md / PROJECT-DEFINITION interview — the maintainer path does not use the first-session consumer flow.\n3. **Stop here** unless the user explicitly asks to continue with consumer setup anyway.\n\n## Pre-Cutover Detection Guard\n\n! Before proceeding with any setup phase, detect whether the project uses the pre-v0.20 document model and redirect to migration if so.\n\n### Detection Criteria\n\nA project is **pre-cutover** if ANY of the following are true. When in doubt, run `task verify:pre-cutover` (the deterministic helper).\n\n1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: xbrief/specification.xbrief.json -->`, and `xbrief/specification.xbrief.json` plus all five lifecycle folders exist.\n2. `PROJECT.md` exists and contains neither the legacy `<!-- deft:deprecated-redirect -->` sentinel NOR the current `Purpose: deprecation redirect` canonical-banner marker (same one-release-cycle grace window).\n3. `xbrief/specification.xbrief.json` exists but the lifecycle folders (`xbrief/proposed/`, `xbrief/pending/`, `xbrief/active/`, `xbrief/completed/`, `xbrief/cancelled/`) do NOT exist\n\n### Action on Detection\n\n! If pre-cutover state is detected, **stop immediately** and display an actionable message pointing at the frozen-release migration path (#2068):\n\n> \"This project uses the pre-v0.20 document model. Current npm releases no longer ship in-product `task migrate:vbrief`. Follow UPGRADING.md § Frozen pre-v0.20 document-model migration: pin framework v0.59.0 (frozen Go installer or git tag), install Python 3.11+ and uv, run `task migrate:vbrief` once from that payload, then upgrade to current npm.\"\n\n! Include specific details about what was detected:\n\n- Missing lifecycle folders: \"Create lifecycle folders via the frozen-release migrator on v0.59.0, or manually add `xbrief/{proposed,pending,active,completed,cancelled}/` after migrating narratives\"\n- `SPECIFICATION.md` with real content: \"SPECIFICATION.md contains non-redirect content — migrate on pinned v0.59.0 before upgrading to current npm\"\n- `PROJECT.md` with real content: \"PROJECT.md contains non-redirect content — migrate on pinned v0.59.0 before upgrading to current npm\"\n- Missing `PROJECT-DEFINITION.xbrief.json`: \"Run `task project:render` after document-model migration completes\"\n\n### Preflight (optional diagnostic)\n\n~ Run `task migrate:preflight` to confirm pre-cutover state and print the frozen-release guidance. It does **not** run migration.\n\n⊗ Offer to run `task migrate:vbrief` from the current npm deposit — the migrator is not bundled on current releases (#2068).\n⊗ Proceed with setup phases when pre-cutover artifacts are detected — always redirect to the frozen migration path first.\n⊗ Silently ignore pre-cutover artifacts — the user must be informed with an actionable command to fix the state.\n\n### Greenfield Projects (No Migration Needed)\n\n! For new projects (no existing `SPECIFICATION.md`, `PROJECT.md`, or `xbrief/specification.xbrief.json`), the guard passes silently and setup proceeds normally.\n\n! Greenfield setup creates the full xBRIEF-centric structure from scratch:\n\n1. `./xbrief/` directory with all 5 lifecycle subdirectories: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`\n2. `./xbrief/PROJECT-DEFINITION.xbrief.json` generated from Phase 2 interview results\n3. First scope xBRIEF created in `proposed/` or `pending/` depending on Phase 3 interview outcome\n\n~ This is already handled by Phase 2 Output Path (creates `./xbrief/` and lifecycle subfolders) and Phase 3 Output (creates scope xBRIEFs in lifecycle folders). The guard ensures migrating projects are redirected before reaching these phases.\n\n### Migration safety flags (frozen v0.59.0 release only)\n\nWhen guiding an operator through migration on the pinned release, mention the migrator safety affordances (#497, #506 D7):\n\n- **`task migrate:vbrief -- --dry-run` (preview)** on v0.59.0\n- **Dirty-tree guard** — migrator refuses when the working tree is dirty unless `--force`\n- **`task migrate:vbrief -- --rollback`** on v0.59.0 to restore `.premigrate.*` backups\n\n⊗ Offer in-product migration from a current npm deposit — use the frozen path (#2068).\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (Phase 1 depth question, Phase 2 project type / deployment / language / strategy / branching gates, Phase 3 onboarding question, end-of-phase transition prompts, post-interview confirmation gate) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options MUST be `Discuss` and `Back`, in that order. The Discuss-pause semantic is documented verbatim there -- on `Discuss` selection the agent MUST halt the in-progress sequence immediately, prompt `What would you like to discuss?`, and resume only on an explicit user signal (re-asks original question, says `resume`/`continue`, or re-issues prior selection). Implicit resumption is forbidden. Fallback chat replies MUST map only to the displayed number or exact displayed option text; do not infer from alphabetic host affordances.\n\n## Platform Detection\n\n! Before resolving any config paths, detect the host OS from your environment context:\n\n| Platform           | USER.md default path                                              |\n|--------------------|-------------------------------------------------------------------|\n| Windows            | `%APPDATA%\\deft\\USER.md` (e.g. `C:\\Users\\{user}\\AppData\\Roaming\\deft\\USER.md`) |\n| Unix (macOS/Linux) | `~/.config/deft/USER.md`                                          |\n\n- ! If `$DEFT_USER_PATH` is set, it takes precedence on any platform\n- ! Create parent directories as needed when writing USER.md\n- ~ `$DEFT_PROJECT_PATH` overrides the default project config path (`./xbrief/PROJECT-DEFINITION.xbrief.json`) if set\n- ! Resolve `<policy-project-root>` to the user's working directory at skill entry. When `$DEFT_PROJECT_PATH` is set, resolve it relative to that root and preserve the environment variable for every Phase 2 command; the public policy writer, inspector, lock, and conformance gate honor the configured file even when it is outside the canonical `xbrief/` path.\n- ! Pass `--project-root <policy-project-root>` to every Phase 2 policy inspector, writer, and conformance command. Do not unset or rewrite `$DEFT_PROJECT_PATH`, and do not let those commands fall back to a different working directory.\n\n## Agent Behavior\n\n**Flow:**\n- ! Start asking immediately — everything you need is in THIS file\n- ⊗ Explore the codebase, read framework files, or gather context before asking\n- ? Read `deft/main.md` or language files LATER when generating output\n\n**Interaction:**\n- ~ Use structured question tools only when their visible option labels preserve the canonical numbers (for example, `1. Yes`) and their return value is the numeric selection or exact displayed option text.\n- ! Fall back to the numbered chat menu when the host UI may replace numbers with alphabetic affordances, unlabeled buttons, or any other non-canonical choice labels.\n- ⊗ Infer deterministic answers from host-added letters or shortcuts unless those letters were actually displayed in the canonical menu labels.\n\n**Defaults:**\n- ! Communicate that deft ships with best-in-class standards for 20+ languages\n- ! Frame setup as \"tell me your overrides\" — not \"configure everything\"\n- ~ \"Deft has solid opinions on how code should be written and tested — I just need a few things about you and your project.\"\n\n**Adapt to Technical Level:**\n- ! First question gauges whether user is technical or non-technical\n- ! Technical user: ask about languages, strategy, coverage directly — they'll have opinions\n- ! Non-technical user: skip jargon, use sensible defaults, ask about what they're building not how\n- ⊗ Ask non-technical users about coverage thresholds, strategies, or framework choices\n\n## Available Languages\n\nC, C++, C#, Dart, Delphi, Elixir, Go, Java, JavaScript, Julia, Kotlin,\nOffice.js (Excel JavaScript API), Python, R, Rust, SQL, Swift, TypeScript,\nVBA (Excel macros), VHDL, Visual Basic (.NET), Zig, 6502-DASM\n\n- ? Read `deft/languages/{name}.md` when generating output — not before asking\n\n## Available Strategies\n\n~ When presenting strategies to the user, always use this numbered list format (not a plain table).\n~ Always include the chaining note below the list.\n! Always show the FULL strategy list at every chaining gate — never remove a strategy because it was previously run.\n~ If a strategy has been run already, indicate it with a note e.g. `(run 1x)` but keep it selectable.\n\n1. **interview** ★ (recommended) — Structured interview with sizing gate: Light or Full path\n2. **yolo** — Auto-pilot interview — Johnbot picks all recommended options\n3. **map** — Analyze existing codebase conventions before adding features\n4. **discuss** — Front-load decisions and alignment before planning\n5. **probe** — Adversarially stress-test the plan; surface assumptions, edge cases, and risks before spec\n6. **research** — Investigate the domain before planning\n7. **speckit** — Five-phase spec-driven workflow for large/complex projects\n\n> 💡 Strategies can be chained — after one completes, you'll be asked if you want to run another.\n\n---\n\n## Phase 1 — User Preferences (USER.md)\n\n**Goal:** Personal preferences file with two sections:\n- **Personal** — always wins over everything (name, custom rules)\n- **Defaults** — fallback values that PROJECT-DEFINITION.xbrief.json can override (strategy, coverage)\n\n- ~ Skip if USER.md exists at the platform-appropriate path (see Platform Detection) and user doesn't want to overwrite\n- ⊗ Scan filesystem beyond checking that one path\n\n### USER.md Freshness Detection\n\n! When an existing USER.md is found (returning user), check its `deft_version` field before skipping Phase 1:\n\n1. ! If `deft_version` is **missing**: the USER.md predates versioning -- treat as stale\n2. ! If `deft_version` is present but **differs from the current framework version** (0.20.0): check whether any expected fields are missing from the USER.md\n3. ! If fields are missing: query the user for each missing field individually -- do NOT re-run the full Phase 1 interview\n4. ! After completing any field queries (even if none were needed), write the current `deft_version` (0.20.0) to USER.md\n5. ~ If `deft_version` matches the current version and all expected fields are present: USER.md is fresh — do **not** re-run Phase 1. ! Still offer the **Returning-user re-entry** menu below so the operator can revisit Experimental Rules or continue to Phase 2 without a full re-interview (#46).\n\nExpected USER.md fields: **Name**, **Custom Rules**, **Default Strategy**, and optionally **Coverage** and **Experimental Rules**.\n\n⊗ Re-run the full Phase 1 interview when only individual fields are missing from a stale USER.md -- query missing fields individually instead.\n\n### Returning-user re-entry (#46)\n\n! When USER.md already exists (fresh or after individual missing-field fill), present a deterministic numbered menu before assuming Phase 1 is \"done and silent\":\n\n> \"USER.md is in place. What next?\"\n> 1. Continue to Phase 2 (project configuration) ★ (recommended when project config is still missing)\n> 2. **Revisit experimental rules** — enable/disable SOUL / morals / code-field without hand-editing schema\n> 3. Not now (exit setup)\n> 4. Discuss\n> 5. Back\n\n- ! Final two numbered options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md)\n- ! On option 2, enter **Revisit experimental rules** (next section) — not a full Phase 1 re-interview\n- ⊗ Silently skip past a complete USER.md with no re-entry offer when the operator entered setup (or asked to configure preferences)\n- ⊗ Invent a `deft config` / `task config:*` verb family for this slice — setup skill re-entry is the product surface (#46)\n\n### Interview Rules\n\n! This phase follows the deterministic interview loop defined in `skills/deft-directive-interview/SKILL.md`. The core rules (one question per turn, numbered options with stated default, explicit \"other\" escape, depth gate, default acceptance, confirmation gate, structured handoff) apply here. Key points repeated for emphasis:\n\n! **Each message you send MUST contain exactly ONE question.** This is the most\nimportant rule in this file. After the user answers, send the NEXT question in\na new message. Repeat until all questions for their track are answered.\n\n- ⊗ Include two or more questions in the same message under any circumstances\n- ⊗ List upcoming questions — only show the current one\n- ~ Provide numbered answer options with an \"other\" choice where appropriate\n- ! Mark which option is RECOMMENDED when showing choices\n- ~ Use structured question tools only when visible option labels preserve the canonical numbers and returns map to numeric selections or exact displayed option text.\n\n### Question Sequence\n\n**Step 0 — Opening (all users):**\nAsk: \"How deep do you want to go?\"\n  1. I'm technical — ask me everything\n  2. I have some opinions but keep it simple\n  3. Just pick good defaults — I care about the product, not the tools\n\nWait for answer. Then follow the track below.\n\n**Track 1 (technical) — 7 steps:**\n- Step 1: Ask their name\n- Step 2: Ask strategy preference (show Available Strategies numbered list from the Available Strategies section, with descriptions and recommended marker; fallback — projects can override)\n- Step 3: Ask coverage threshold (default 85%; fallback — projects can override)\n- Step 4: Ask for custom rules — if user has rules, collect them one per line (empty line to finish); if none, skip\n- Step 5a: Present SOUL.md and ask whether to include it (default: yes):\n  > **SOUL.md** — Results-first agent persona (inspired by Winston Wolf). Enforces assess-before-acting,\n  > finish-what-you-start, right-tool-for-the-job, and play-the-long-game. Keeps the AI decisive and\n  > concise. Includes a named persona ('Vinston') — drop if you prefer to define your own agent personality.\n  > Include SOUL.md? (Y/n)\n- Step 5b: Present morals.md and ask whether to include it (default: yes):\n  > **morals.md** — Epistemic honesty rules. No presenting speculation as fact, label unverified claims,\n  > self-correct when wrong. Foundational trust rules for any AI agent. Strongly recommended.\n  > Include morals.md? (Y/n)\n- Step 5c: Present code-field.md and ask whether to include it (default: yes):\n  > **code-field.md** — Pre-code assumption protocol. Requires stating assumptions and naming failure modes\n  > before writing a single line. Fights the 'it compiles, ship it' instinct. Based on NeoVertex1 context-field.\n  > Include code-field.md? (Y/n)\n\n**Track 2 (middle ground) — 2 steps:**\n- Step 1: Ask their name\n- Step 2: Ask for custom rules — if user has rules, collect them one per line (empty line to finish); if none, skip\n- Set defaults without asking: strategy = \"interview\", coverage = 85%, all meta-guidelines included\n\n**Track 3 (non-technical) — 2 steps:**\n- Step 1: Ask their name\n- Step 2: Ask what they're building (brief description — used for PROJECT-DEFINITION.xbrief.json later)\n- Set defaults: strategy = \"interview\", coverage = 85%, all meta-guidelines included\n\n### Output Path\n\nResolve using Platform Detection above. Write to the platform-appropriate path\n(or `$DEFT_USER_PATH` if set). Create parent directories as needed.\n\n### Template\n\n```markdown\n# User Preferences\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**deft_version**: 0.20.0\n\n## Personal (always wins)\n\nSettings in this section have HIGHEST precedence — override all other deft rules,\nincluding PROJECT-DEFINITION.xbrief.json.\n\n**Name**: Address the user as: **{name}**\n\n**Custom Rules**:\n{custom rules or \"No custom rules defined yet.\"}\n\n**Forge outage retry** (optional): `forgeOutageRetryMinutes: 30` — integer minutes, minimum 5. Default 30. Personal wins over `plan.policy.forgeOutageRetryMinutes`. Omit to use project policy or the framework default. Inspect: `task policy:show --field=forgeOutageRetryMinutes`.\n\n## Defaults (fallback)\n\nSettings in this section are fallback defaults. PROJECT-DEFINITION.xbrief.json overrides these\nfor project-scoped settings (strategy, coverage).\n\n**Default Strategy**: [{strategy name}](../strategies/{strategy-file}.md)\n\n{If coverage != 85: \"**Coverage**: ! ≥{N}% test coverage\"}\n\n{If any experimental rules selected:\n\"## Experimental Rules\n\n{one line per selected rule, e.g.:\n- ! Use meta/SOUL.md for strategic context and purpose-driven guidance\n- ! Use meta/morals.md for ethical AI development principles\n- ~ Use meta/code-field.md for advanced architecture patterns}\"}\n\n---\n\n**Note**: Edit this file anytime to update your preferences.\n**See**: [../../main.md](../../../main.md) for framework defaults.\n```\n\n### Then\n\n- ! Emit a structured-tool question asking whether to continue to Phase 2 (project configuration) only when the host preserves numeric labels; otherwise emit the deterministic numbered menu in chat. Options: `1. Yes (continue)`, `2. Not now (exit setup)`, `3. Discuss`, `4. Back (revisit previous phase)`. The numeric labels MUST remain visible and be returned as numeric selections or exact displayed option text.\n- ⊗ Ask the phase-transition question as unnumbered conversational prose or through a structured UI that hides the canonical numeric labels -- it is a deterministic menu and MUST preserve visible numbers (#478, #1563).\n\n---\n\n## Revisit experimental rules (#46)\n\n**Goal:** Guided enable/disable of USER.md **Experimental Rules** entries that *reference* framework deposit meta files (`meta/SOUL.md`, `meta/morals.md`, `meta/code-field.md`). This is a post-bootstrap return path — not Phase 1 bootstrap, not a general preferences UI, and not an editor for framework meta file bodies.\n\n### When to enter\n\n- Returning-user re-entry option **Revisit experimental rules**\n- Direct user ask: \"revisit experimental rules\", \"toggle experimental meta\", \"turn on SOUL\", \"disable code-field\", etc.\n- USER.md exists and is complete enough to edit (Name present); missing non-meta fields still use Freshness Detection individual queries first\n\n### Out of scope\n\n- ⊗ General preferences UI / rewriting Personal or Defaults sections as part of this path\n- ⊗ Editing framework `meta/*.md` content (deposit owns SOUL / morals / code-field bodies; `directive update` refreshes deposit)\n- ⊗ Deposit layout changes\n- ⊗ Inventing a full `deft config` mega-surface or new `task config:*` verb family for this slice\n- ⊗ Re-building USER.md bootstrap / non-overwrite semantics\n- ⊗ Treating Experimental Rules lines as project-local copies of meta files — they are **references** only\n\n### Flow\n\n! **Each message MUST contain exactly ONE question** (same interview rule as Phase 1).\n\n1. ! Resolve USER.md via Platform Detection (`$DEFT_USER_PATH` → platform path). Read the file as **UTF-8**.\n2. ! Parse current Experimental Rules state (on/off) for the three paths:\n   - `meta/SOUL.md`\n   - `meta/morals.md`\n   - `meta/code-field.md`\n   - Detection: any line containing that path counts as **on** (custom wording still counts).\n3. ! Show a **current state** summary (table or short list), for example:\n\n   | Entry | State | Role |\n   |-------|-------|------|\n   | SOUL.md | on/off | Results-first agent persona |\n   | morals.md | on/off | Epistemic honesty |\n   | code-field.md | on/off | Pre-code assumption protocol |\n\n4. ! Ask which entry to change with a deterministic numbered menu (one question). Options MUST include each of the three entries as toggle targets, plus **Done (save)** / **Done (discard)**, and final two options `Discuss` and `Back`:\n\n   > \"Toggle which experimental meta entry? (current state shown above)\"\n   > 1. SOUL.md — currently {on|off}\n   > 2. morals.md — currently {on|off}\n   > 3. code-field.md — currently {on|off}\n   > 4. Done — save changes\n   > 5. Done — discard changes\n   > 6. Discuss\n   > 7. Back\n\n5. ! When the user picks an entry (1–3), optionally show the short Phase 1 explainer (steps **5a–5c** copy below), then confirm the new on/off value with a Y/n or numbered keep/flip menu. Update the **in-memory** desired state; do not write yet. Return to the toggle menu (step 4) until Done.\n6. ! On **Done — save**: show a confirmation summary of the three final on/off values and require explicit affirmative (`yes` / `confirmed` / `approve`) before write — same Post-Interview Confirmation Gate strictness.\n7. ! On **Done — discard** or **Back** without save: leave USER.md unchanged and return to the Returning-user re-entry menu (or exit if invoked directly).\n\n### Explainers (reuse Phase 1 steps 5a–5c)\n\n- **SOUL.md** — Results-first agent persona (inspired by Winston Wolf). Enforces assess-before-acting, finish-what-you-start, right-tool-for-the-job, and play-the-long-game. Keeps the AI decisive and concise. Includes a named persona ('Vinston') — drop if you prefer to define your own agent personality.\n- **morals.md** — Epistemic honesty rules. No presenting speculation as fact, label unverified claims, self-correct when wrong. Foundational trust rules for any AI agent. Strongly recommended.\n- **code-field.md** — Pre-code assumption protocol. Requires stating assumptions and naming failure modes before writing a single line. Fights the 'it compiles, ship it' instinct. Based on NeoVertex1 context-field.\n\n### Safe write rules (non-clobber)\n\n! When persisting toggles to USER.md:\n\n1. ! Write **UTF-8** (no BOM). Create parent directories only if the resolved path's parent is missing — never relocate USER.md.\n2. ! Change **only** the `## Experimental Rules` section (add the section if enabling when absent; remove the section when all three are off and no custom bullets remain).\n3. ! Canonical enable lines (match Phase 1 template):\n   - `- ! Use meta/SOUL.md for strategic context and purpose-driven guidance`\n   - `- ! Use meta/morals.md for ethical AI development principles`\n   - `- ~ Use meta/code-field.md for advanced architecture patterns`\n4. ! Disable = remove lines that mention that path. Preserve any **custom** non-meta bullets under Experimental Rules.\n5. ! **Personal** and **Defaults** section bodies MUST remain byte-identical to the pre-write file (non-clobber).\n6. ~ Prefer the pure helper `applyExperimentalRulesState` / `setExperimentalRule` from `@deftai/directive-core` `userConfig` (`packages/core/src/user-config/experimental-rules.ts`) when the package is importable (framework checkout, tests, or a thin local script). When editing by hand as an agent, apply the same rules: section-only edit, UTF-8, path-based match, canonical enable lines.\n7. ! After write, re-read USER.md and show the final on/off state to the user.\n\n⊗ Rewrite the whole USER.md from the Phase 1 template when only Experimental Rules changed\n⊗ Clobber or reformat **Personal** / **Defaults** content while toggling experimental meta\n⊗ Hand-edit framework `meta/SOUL.md`, `meta/morals.md`, or `meta/code-field.md` bodies as part of this path\n⊗ Invent `deft config` / `task config:experimental-*` for this product slice when setup re-entry suffices\n\n### Then\n\n- ! After a successful save (or discard), re-offer the Returning-user re-entry menu (Continue to Phase 2 / Revisit again / Exit / Discuss / Back) unless the user asked only for the toggle and is done.\n- ~ If Phase 2 is already complete, prefer Exit over Continue unless the user wants project reconfiguration.\n\n## Phase 2 — Project Configuration (PROJECT-DEFINITION.xbrief.json)\n\n**Goal:** Project-specific configuration — tech stack, type, quality standards — written as a xBRIEF file at `./xbrief/PROJECT-DEFINITION.xbrief.json`.\n\n! **Path Resolution Anchor**: Resolve ALL paths relative to the user's working directory (pwd) at skill entry -- never relative to the skill file location, AGENTS.md location, or any framework directory (e.g. `./deft/`). When deft is cloned as a subdirectory, the skill file lives inside the clone but all project artifacts (`./xbrief/PROJECT-DEFINITION.xbrief.json`, build files, etc.) must be resolved from the user's pwd.\n\n- ~ Skip if `./xbrief/PROJECT-DEFINITION.xbrief.json` exists (or `$DEFT_PROJECT_PATH` if set) and user doesn't want to replace\n- ⊗ Count `./deft/PROJECT-DEFINITION.xbrief.json` or `./deft/core/project.md` as the user's project config — those are framework-internal\n\n### Re-entry shadow guard (#3609)\n\n! Before any Phase 2 confirmation or file mutation when PROJECT-DEFINITION already exists, run `deft policy:show --field=plan.policy.allowDirectCommitsToMaster --project-root <policy-project-root>` and inspect **stderr as well as the exit code**. The inspector intentionally exits 0 when it can still read the namespaced value, so a warning that bare `plan.policy` coexists with `plan[\"x-directive/policy\"]` is a hard stop even when the command succeeds.\n\n! On that warning, do not regenerate, overwrite, or run a policy writer. Inventory the keys in both blocks; fold every bare-only key into `plan[\"x-directive/policy\"]`; resolve every collision explicitly; delete bare `plan.policy`; then rerun the inspector. Preserve all unrelated PROJECT-DEFINITION content. Resume only when exactly one policy block remains.\n\n⊗ Treat matching `allowDirectCommitsToMaster` values as safe while other keys may still be stranded in the shadowed block\n⊗ Copy arbitrary policy values into a diagnostic or silently choose one side of a collision\n\n### Inference\n\n- ! Before asking, infer from codebase — look for `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, `pyproject.toml`, `*.csproj`\n- ! Use inferences to pre-fill answers and confirm — don't ask blind\n- ⊗ Look inside `./deft/` for build files (`go.mod`, `package.json`, `pyproject.toml`, `Cargo.toml`, `*.csproj`, etc.) — those are framework-internal. Only inspect files at the project root and its non-`deft` subdirectories.\n- ⊗ Run git commands inside `./deft/` to determine project identity — that directory is the framework repo, not the user's project.\n- ~ If no build files are found at the project root, default the project name to the current directory name and ask for confirmation.\n\n### Track Detection\n\n! If Phase 1 was skipped (USER.md already existed), the user's track is unknown.\nBefore asking any Phase 2 questions, ask the depth question:\n\n> \"How deep do you want to go?\"\n> 1. I'm technical — ask me everything\n> 2. I have some opinions but keep it simple\n> 3. Just pick good defaults — I care about the product, not the tools\n\nWait for answer. Then follow the corresponding track in the Question Sequence below.\n\n⊗ Assume Track 1 (technical) because USER.md exists or contains strategy/coverage fields.\n⊗ Infer the track from USER.md content — always ask.\n\n### Defaults in Agentic Mode\n\n! When a question has a USER.md default, phrase it as:\n> \"{Field}: **{value}** from USER.md — keep this, or enter a different value?\"\n\n! Accept any affirmative response (\"keep\", \"yes\", \"same\", \"default\", ✓) as confirmation to use the default.\n⊗ Phrase defaults as \"press Enter to keep\" — there is no Enter in conversational mode.\n\n### Interview Rules (same as Phase 1)\n\n! **Each message MUST contain exactly ONE question.** The Phase 1 interview rules\napply here too. Do not combine questions. See `skills/deft-directive-interview/SKILL.md` for the canonical deterministic interview loop.\n\n### Question Sequence\n\n**Track 1 (technical) — 8 steps:**\n- Step 1: Ask project name (infer from build files or directory name, confirm)\n- Step 2: Ask project type (CLI, TUI, Desktop App, REST API, Web App, Library, other)\n- Step 3: Ask deployment platform:\n  1. Cross-platform (Linux / macOS / Windows)\n  2. Windows-native\n  3. macOS-native\n  4. Linux / Unix\n  5. Embedded / low-resource\n  6. Web / Cloud\n  7. Mobile (iOS / Android)\n  8. Other / not sure\n- Step 4: Ask languages — show a filtered shortlist (3–4 recommendations) based on project type + platform. If codebase markers exist (`go.mod`, `pyproject.toml`, etc.), skip and confirm: \"Detected {lang} — correct?\"\n  - If user selects \"Other\": show remaining plausible languages for the type+platform context (Tier 2)\n  - If still not found: free text input (Tier 3)\n  - If entered language has no deft `languages/{lang}.md` standards file, warn: \"deft doesn't have a standards file for {lang} yet — general defaults will be used. Continue?\"\n- Step 5: Ask tech stack (frameworks, libraries)\n- Step 6: Ask strategy (default to USER.md Defaults; ask if this project needs different — show Available Strategies numbered list with descriptions and recommended marker)\n- Step 7: Ask coverage (default to USER.md Defaults; ask if this project needs different)\n- Step 8: Ask for project-specific rules (optional, same one-per-line format as Phase 1 custom rules)\n- Step 9: Ask branching preference (typed `plan.policy.allowDirectCommitsToMaster` flag per #746):\n\n  ! Render this as a deterministic numbered menu. Default `1. Branch-based`. Final two options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md):\n\n  > \"Do you prefer branch-based workflow (create a feature branch for every change) or\n  > trunk-based (commit directly to master)? Branch-based is the default and recommended\n  > for teams; trunk-based is common for solo projects.\"\n  > 1. Branch-based ★ (recommended -- default; enforces feature branches via the deft branch-protection policy)\n  > 2. Trunk-based (direct commits to master) -- see capability-cost disclosure below\n  > 3. Discuss\n  > 4. Back\n\n  ! **Capability-cost disclosure (#746):** When the user picks option 2 (trunk-based), the agent MUST present the capability-cost disclosure verbatim BEFORE writing the typed flag, then re-prompt for explicit confirmation:\n\n  > \"Capability-cost disclosure -- enabling direct commits to the default branch turns OFF the deft branch-protection policy. The pre-commit + pre-push hooks will no longer block default-branch commits, `deft verify:branch` / `task deft:verify:branch` will pass on the default branch, and the skill-level guards in deft-directive-{swarm,review-cycle,pre-pr,release} will not halt for default-branch work. The change is reversible (`task policy:enforce-branches`) and is recorded to meta/policy-changes.log for auditability. The CI sanity check (head_ref != base_ref) remains independent and will continue to flag master->master PRs. Are you sure?\"\n  > 1. Yes, opt out -- persist `allowDirectCommitsToMaster=true` through the policy writer\n  > 2. No, keep branch-protection enforced -- persist `allowDirectCommitsToMaster=false` through the policy writer\n  > 3. Discuss\n  > 4. Back\n\n  ! Default to option 2 (enforce). Explicit affirmative on option 1 is required to opt out -- a broad `proceed` does NOT satisfy this gate. The same affirmative-only rule applies as in `/deft:change` (`yes`, `confirmed`, `approve`).\n\n  ! Record the answer as the logical field `plan.policy.allowDirectCommitsToMaster`, but do not hand-write either policy block. The common Output Path gate below invokes the only writer and stores the boolean under `plan[\"x-directive/policy\"].allowDirectCommitsToMaster`. Default `false` (enforce branches) when the user picks option 2 OR omits the question entirely. Agents MUST NOT write bare `plan.policy` or the legacy free-form `Allow direct commits to master:` narrative key.\n\n  ! **Re-running the interview detects the existing flag (#746 part G2):** After the Re-entry shadow guard passes, surface the resolved current value (e.g. \"Current setting: `allowDirectCommitsToMaster=false` (branch-protection ON)\") and ask whether to keep it or change it before re-prompting. A keep choice still runs the selected writer so legacy-only storage is migrated; an already-namespaced match is a no-op with no audit append. On Track 2 or 3, preserve an existing resolved boolean by default without asking a new branching question. Never replace an existing `true` with the greenfield `false` default unless the operator explicitly chooses the Track 1 change flow.\n\n  ! **Consumer command alternatives (#746 part G2):** Once the project is set up, use the public CLI directly:\n  - `deft policy:show --field=plan.policy.allowDirectCommitsToMaster --project-root <policy-project-root>` -- display the current resolved policy and source\n  - `deft policy:enforce-branches --actor agent:deft-directive-setup --project-root <policy-project-root>` -- set `allowDirectCommitsToMaster=false`\n  - `deft policy:allow-direct-commits --confirm --actor agent:deft-directive-setup --project-root <policy-project-root>` -- set `allowDirectCommitsToMaster=true`\n\n  Each transition is recorded to `meta/policy-changes.log` for auditability.\n\n**Track 2 (middle ground) — 4 steps:**\n- Step 1: Ask project name (infer from build files or directory name, confirm)\n- Step 2: Ask project type (CLI, TUI, Desktop App, REST API, Web App, Library, other)\n- Step 3: Ask languages (show detected, confirm or adjust; if none detected, infer from type and ask)\n- Step 4: Ask strategy (default to USER.md Defaults; ask if this project needs different — show Available Strategies numbered list with descriptions and recommended marker)\n- Default coverage to USER.md Defaults without asking\n- ! Do not ask a branching question. For greenfield or absent policy, the common Output Path gate persists `allowDirectCommitsToMaster=false`. On re-entry it preserves the resolved existing boolean, including `true`; change it only through the Track 1 disclosure gate.\n\n**Track 3 (non-technical) — 1 step:**\n- Step 1: Present summary of inferences: \"Based on your project: {name} ({type}), built with {stack}. Look right?\"\n- ⊗ Ask about strategy or coverage — use Phase 1 defaults\n- ! Do not ask a branching question. For greenfield or absent policy, the common Output Path gate persists `allowDirectCommitsToMaster=false`. On re-entry it preserves the resolved existing boolean, including `true`; change it only through the Track 1 disclosure gate.\n\n### Output Path\n\n`./xbrief/PROJECT-DEFINITION.xbrief.json` (or the resolved `$DEFT_PROJECT_PATH` if set). Create `<policy-project-root>/xbrief/` and its lifecycle subfolders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`) if they don't exist. A configured PROJECT-DEFINITION may live elsewhere; the lifecycle root remains under `<policy-project-root>`.\n\n### Branch-policy persistence gate (#3609)\n\n! This gate applies to **every track**, including default/greenfield and keep/re-entry paths. For greenfield setup, first write the confirmed PROJECT-DEFINITION base without any hand-authored policy block. On re-entry, merge base changes while preserving the existing policy block byte-for-byte: keep a legacy-only bare `plan.policy` intact until the shared writer migrates the whole block, and keep a namespaced block intact until that writer updates it. Never delete or reconstruct a legacy-only block before the writer because it may contain unrelated keys such as `wipCap`. Then invoke exactly one public writer:\n\n- Branch-based/greenfield-default/keep-false: `deft policy:enforce-branches --actor agent:deft-directive-setup --project-root <policy-project-root>`\n- Explicitly confirmed trunk-based/keep-true/Track 2 or 3 existing-true: `deft policy:allow-direct-commits --confirm --actor agent:deft-directive-setup --project-root <policy-project-root>`\n\n! A nonzero writer exit halts Phase 2 immediately. Do not print a completion claim and do not retry by hand-editing JSON. Resolve the reported configuration problem, rerun the Re-entry shadow guard, and invoke the writer again.\n\n! Before Phase 2 can complete, re-read PROJECT-DEFINITION and verify all three postconditions: `plan[\"x-directive/policy\"].allowDirectCommitsToMaster` is the selected boolean; bare `plan.policy` is absent; and `deft verify:vbrief-conformance --project-root <policy-project-root>` exits 0. Also run `deft policy:show --field=plan.policy.allowDirectCommitsToMaster --project-root <policy-project-root>` and confirm its resolved value matches the selection. Any mismatch is a hard stop.\n\n⊗ Finish Phase 2 after writing only the narrative template\n⊗ Add a setup-specific policy writer or weaken conformance to permit bare `plan.policy`\n\n### GitHub PR Template Scaffolding (#531)\n\n! Before writing `PROJECT-DEFINITION.xbrief.json`, offer to scaffold a default GitHub PR template so downstream skills (`deft-directive-refinement` Pre-Flight, `deft-directive-pre-pr`) can satisfy their `.github/PULL_REQUEST_TEMPLATE.md` checks without blocking.\n\n1. ! Ask the user with a deterministic numbered menu: \"Create a default GitHub PR template at `.github/PULL_REQUEST_TEMPLATE.md`?\" Options: `1. Yes`, `2. No`, `3. Discuss`, `4. Back`. Use a structured question tool only if those numeric labels remain visible and are returned as numeric selections or exact displayed option text.\n2. ! If the user accepts AND `.github/PULL_REQUEST_TEMPLATE.md` does NOT already exist: copy `templates/PULL_REQUEST_TEMPLATE.md` (shipped with deft) to `./.github/PULL_REQUEST_TEMPLATE.md` in the consumer project. Create `.github/` if it does not exist.\n3. ! If the file already exists, do NOT overwrite it — report that it is present and continue.\n4. ~ If the user declines, note that `deft-directive-refinement` Pre-Flight will offer to scaffold later when needed.\n\n⊗ Overwrite an existing `.github/PULL_REQUEST_TEMPLATE.md` without explicit user approval.\n\n### Headless Coverage Warning — display-bound GUI entry points (#1027)\n\n! The trigger is a **display-bound GUI event loop** (pygame, tkinter, PyQt/PySide, Kivy, Electron) that cannot run without a real display — typically a **Desktop App** project type, or a TUI that embeds such a GUI. Terminal-UI frameworks (textual, urwid, blessed, ncurses) run in the terminal and DO support headless testing (e.g. textual's `App.run_async()` + `Pilot`), so a standard TUI is NOT in scope — do not omit its coverage. The concrete commands below assume a **Python** GUI stack (pygame/tkinter); the same \"omit the un-runnable loop, test the logic\" principle applies to non-Python desktop stacks (Electron/JS, .NET/WPF, Qt/C++) using that language's own headless-test and coverage-exclusion tooling. When the Phase 2 project type resolves to a display-bound GUI project, warn the user BEFORE writing `PROJECT-DEFINITION.xbrief.json` (adapt the wording to the project's language):\n\n> \"Heads up: pygame/tkinter event loops can't be tested headlessly, so the display-bound entry point (e.g. `src/ui.py`) reports near-zero coverage and drags the overall percentage below the 85% threshold. I recommend excluding the UI entry point from coverage measurement and keeping it thin — push testable logic (state, scoring, input handling) into separate modules.\"\n\n! When scaffolding or advising on `pyproject.toml` for a display-bound GUI project, add the display-bound entry point to `[tool.coverage.run] omit` so `task check` measures logic modules only:\n\n```toml\n[tool.coverage.run]\nomit = [\n  \"*/tests/*\",\n  \"*/venv/*\",\n  \"*/.venv/*\",\n  \"src/ui.py\",        # display-bound pygame/tkinter event loop -- cannot run headlessly (#1027)\n]\n```\n\n- ! Keep the omit narrow — exclude only the event-loop shell, never a module that also holds business logic. If logic and the loop are mixed, recommend refactoring the logic into a separate, fully-tested module first.\n- ~ For a Python project, point the user at `languages/python.md` (the `Headless GUI / event-loop testing` section under Patterns) for the headless-test pattern (`SDL_VIDEODRIVER=dummy`) and the full coverage-omit rationale; for a non-Python GUI stack, apply the same principle with that language's headless-test and coverage-exclusion tooling.\n- ⊗ Apply the omit to a headless-capable terminal-UI project (textual/urwid/blessed/ncurses) — those frameworks test headlessly, so omitting them hides measurable coverage, the opposite of the intended effect.\n- ⊗ Silently accept the default 85% coverage gate for a display-bound GUI project without surfacing the headless blind spot — the agent reports an inflated per-session coverage that collapses when the full `src/` is measured (the 2026-05-10 tic-tac-toe desktop-UI swarm recurrence).\n\n### Template\n\n! The output MUST conform to the canonical xBRIEF v0.8 schema (`xbrief/schemas/xbrief-core-0.8.schema.json`, strict `const: \"0.8\"`). See [`../../conventions/references.md`](../../conventions/references.md). Write-path default is **0.8 only** (#2971); legacy 0.6 remains read-accepted until `deft migrate:xbrief`.\n\n```json\n{\n  \"xBRIEFInfo\": {\n    \"version\": \"0.8\",\n    \"author\": \"agent:deft-directive-setup\",\n    \"description\": \"Project identity gestalt\",\n    \"created\": \"{ISO-8601 timestamp}\"\n  },\n  \"plan\": {\n    \"title\": \"{Project Name}\",\n    \"status\": \"running\",\n    \"narratives\": {\n      \"Overview\": \"{Brief project description}\",\n      \"TechStack\": \"{project type} using {languages} — {tech stack details}\",\n      \"Strategy\": \"Use {strategy name} for this project\",\n      \"Quality\": \"Run task check before every commit. Achieve >= {coverage}% coverage overall + per-module. Store secrets in secrets/ dir.\",\n      \"ProjectRules\": \"{Any rules the user specified, or 'No project-specific rules defined.'}\",\n      \"Branching\": \"{If confirmed trunk-based: 'Trunk-based workflow', otherwise 'Branch-based workflow (default)'}\"\n    },\n    \"items\": []\n  }\n}\n```\n\n- ! All `narratives` values MUST be plain strings — never objects or arrays\n- ! `items` starts empty — populated as scope xBRIEFs are created in lifecycle folders\n\n### Then\n\n- ! Emit a structured-tool question asking whether to continue to Phase 3 (specification) only when the host preserves numeric labels; otherwise emit the deterministic numbered menu in chat. Options: `1. Yes (continue)`, `2. Process-only (keep Phase 2 identity)`, `3. Discuss`, `4. Back (revisit previous phase)`. The numeric labels MUST remain visible and be returned as numeric selections or exact displayed option text.\n- ! Option 2 is the process-only adoption: leave setup with Phase 2 identity in place. Point at session ritual (`deft session:start` / `deft verify:session-ritual -- --tier=gated`) / `deft check` / later Add scope when a slice is ready. Do not write `xbrief/proposed/*.xbrief.json`. Do not overwrite PROJECT-DEFINITION narratives. GitHub issues stay cache/queue inputs. Docs stay described content. Skip Lifecycle Bridge, export prompt, Acceptance Gate, and build handoff.\n- ⊗ Bind docs or GitHub issues as the next-build plan.\n- ⊗ Use Back or Other as the process-only adoption path.\n- ⊗ Ask the phase-transition question as unnumbered conversational prose or through a structured UI that hides the canonical numeric labels -- it is a deterministic menu and MUST preserve visible numbers (#478, #1563).\n\n### Follow-up: triage onboarding (#1143)\n\n- ~ After Phase 2 writes `PROJECT-DEFINITION.xbrief.json`, recommend `task triage:welcome` to the user as the single chained command for picking up the v0.27 triage surface. The N3 ritual (#1143) is the consolidating onboarding step for the #1119 governance swarm verbs (`task triage:bootstrap` / `task triage:scope` / `plan.policy.wipCap` writes / `task scope:demote --batch` relief / `task triage:summary`); without it consumers must learn each verb individually from the v0.27 release notes.\n- ~ `task triage:welcome` is idempotent and detection-bound -- each phase emits an informational stderr line and skips when its precondition is already satisfied, so a re-run after a partial completion resumes cleanly. The destructive phases (subscription / `wipCap` writes, optional WIP-relief invocation) are gated by numbered-menu prompts per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md). See [`../../UPGRADING.md`](../../UPGRADING.md) `## From v0.26.x -> v0.27` for the full walkthrough.\n### Consumer AGENTS always-pin recommendations (#2508)\n\n! After Phase 2 completes (or when closing a greenfield bootstrap), tell the consumer that process-critical directive skills should be named in their project's AGENTS.md **unmanaged header** when false-negative risk matters — full tier definitions: [`../../docs/skill-pin-policy.md`](../../docs/skill-pin-policy.md).\n~ Recommend the default consumer pin set for lifecycle work: `deft-directive-build` (implementation), `deft-directive-pre-pr` (before PR), `deft-directive-review-cycle` (bot review loop), and `deft-directive-swarm` when they plan parallel agents. Each is referenced by skill id + `.deft/core/.agents/skills/<id>/SKILL.md` path — not by pasting skill bodies.\n⊗ Recommend pinning entire `languages/`, `deployments/`, or other framework doc packs into AGENTS.md (#2508 anti-pattern).\n\n---\n\n## Phase 3 — Specification\n\n**Goal:** Generate an implementable spec using the strategy chosen in Phase 2, producing scope xBRIEFs in `xbrief/proposed/` and PROJECT-DEFINITION narratives for human approval — greenfield v0.20 does not create `specification.xbrief.json`.\n\n! **Path Resolution Anchor**: Same rule as Phase 2 -- resolve ALL paths relative to the user's pwd at skill entry, never relative to the skill file, AGENTS.md, or any framework directory.\n\n- ~ Skip if user already has scope xBRIEFs in `./xbrief/` they're happy with\n- ! Check `./xbrief/PROJECT-DEFINITION.xbrief.json` and `./xbrief/proposed/` for existing greenfield authority; treat `./xbrief/specification.xbrief.json` as a full-spec compatibility artifact only\n- ⊗ Count ANY file inside `./deft/` as the project's spec — those are framework-internal\n  (e.g. `deft/PROJECT.md`, `deft/specs/`, `deft/templates/`, `deft/core/project.md`\n  are all part of the framework, NOT the user's project)\n\n### Onboarding Question\n\n! Before proceeding with the strategy gate, ask the onboarding question. Use the same add-scope / update / replace vocabulary as the Chaining Gate in [strategies/interview.md](../../strategies/interview.md#chaining-gate).\n\n**Brownfield detector** (same as Chaining Gate; #4390 recut of the #2925 identity-OR-scopes probe):\n\n- **Identity-only** when BOTH: live PROJECT-DEFINITION `plan.items` is empty (`[]` or absent), AND no convention-valid `*.xbrief.json` / `*.vbrief.json` in lifecycle folders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/` under `./xbrief/` or legacy `./vbrief/`). Exclude `.gitkeep` and `*.premigrate.*`. PROJECT-DEFINITION itself is identity, not a scope record.\n- **Scoped (brownfield)** when `plan.items` is non-empty OR at least one convention-valid scope file exists.\n- **Greenfield** when there is no PROJECT-DEFINITION and no convention-valid scope file.\n\n! One rule on both surfaces — this detector and the Chaining Gate share identity-only. ⊗ Treat PROJECT-DEFINITION existence alone as brownfield. ⊗ Use session-age (\"this setup turn just wrote identity\") as the probe. ⊗ Invent a \"finished Phase 3\" marker.\n\n> \"How should we treat this project's specification?\"\n> 1. **Add scope to this project** [default when brownfield] — load existing identity; skip greenfield \"what are we building?\" only after an explicit product or slice description; emit one proposed scope; Preparatory Guard on write\n> 2. **Update project definition** — delta interview → Spec-Generating Guard → merge narratives into existing PROJECT-DEFINITION\n> 3. **Replace specification (scrap)** — only after explicit affirmative (`yes` / `confirmed`); then full new-spec path\n> 4. **Starting a new project specification** [default when identity-only or greenfield] — proceed to the Strategy Gate below and ask what to build\n> 5. **Process-only (keep Phase 2 identity)** — same exit as Phase 2 option 2; no new scope; no spec write\n> 6. **Discuss** — explore these options before choosing\n> 7. **Back** — return to the previous setup question\n\n- ! Default based on repo state via the brownfield detector above (scoped/brownfield → Add scope; identity-only or greenfield → Starting new)\n- ! Final two numbered options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md)\n- ! If **Add scope**: skip the full interview only after capturing an explicit product or slice description from the operator. Create a new scope xBRIEF in `./xbrief/proposed/` with that description, apply Preparatory Guard on write, then surface the Lifecycle Bridge + End-of-Phase-3 Export Prompt + handoff sections below (do not dead-end after the write)\n- ! If **Add scope** on identity-only: ⊗ synthesize the first scope from `narratives.Overview`, directory name, or init-seed identity. Capture a product or slice description, or do not emit a proposed xBRIEF. Swarm Phase 0 Step 0.5 `xbrief/proposed/` scan is in scope for that skip.\n- ! If **Update project definition**: run a delta interview; apply Spec-Generating Guard against `./xbrief/PROJECT-DEFINITION.xbrief.json` (or legacy `./vbrief/PROJECT-DEFINITION.vbrief.json` if that is the existing identity); merge narratives (do not wholesale replace unless the user confirmed scrap)\n- ! If **Replace specification (scrap)**: require explicit `yes`/`confirmed`, then proceed to the Strategy Gate as a greenfield-style full path\n- ! If **Starting new**: proceed to the Strategy Gate below. Ask what to build before writing a scope. On identity-only, this invocation MAY skip the interview Chaining Gate (see [strategies/interview.md](../../strategies/interview.md#chaining-gate) Starting-new skip) because the identity-only default is already Proceed.\n- ! If **Process-only (keep Phase 2 identity)**: same exit as Phase 2 option 2. Do not write a scope xBRIEF. Do not merge or scrap PROJECT-DEFINITION narratives. Skip Lifecycle Bridge, End-of-Phase-3 Export Prompt, Acceptance Gate, and build handoff. Point at session ritual / `deft check` / later Add scope. GitHub issues stay cache/queue inputs. Docs stay described content.\n- ⊗ Treat brownfield repos as \"Starting new\" by default\n- ⊗ Default identity-only to Add-scope because PROJECT-DEFINITION exists\n- ⊗ Accept vague confirmation (`proceed`, `ok`) for Replace/scrap\n- ⊗ Exit immediately after Add-scope write without the lifecycle bridge / export / handoff guidance\n- ⊗ Auto-promote proposed scopes from this skill\n- ⊗ Change `directive init` brownfield-install classification from this Phase 3 detector\n\n### ⚠️ MANDATORY: Strategy Gate — Do This First\n\n! **STOP.** You MUST determine the correct strategy before doing anything else.\n\n1. ! Open `./xbrief/PROJECT-DEFINITION.xbrief.json` (the file written in Phase 2)\n2. ! Find the `narratives.Strategy` value\n3. ! Extract the strategy name from the narrative\n\n**Dispatch:**\n\n- **interview** (or default) → On identity-only Starting-new, continue to the Sizing Gate below and ask what to build (Chaining Gate skip allowed for that invocation per [strategies/interview.md](../../strategies/interview.md#chaining-gate)). On scoped/brownfield, present the Chaining Gate first. ✅\n- **anything else** (discuss, yolo, speckit, research, brownfield, map, etc.) →\n  1. ! Read `deft/strategies/{strategy-name}.md` **right now, in this same turn**\n  2. ! Begin the strategy's workflow immediately — ask its first question\n  3. ! For `research`, the first question is the strategy's Scope Confirmation Gate (#1273); ask it and wait before any autonomous research begins.\n  4. ! For `research`, after the research artifact is written, surface the strategy's Then: Chaining Gate and wait for a user selection; do NOT create scope xBRIEFs from research output unless the user later chooses a spec-generating path; do NOT fall through to the interview output path after research.\n  5. ! **STOP reading this section** — do NOT use the interview process below\n\n- ⊗ Default to interview without reading PROJECT-DEFINITION.xbrief.json\n- ⊗ Continue reading below when PROJECT-DEFINITION.xbrief.json specifies a non-interview strategy\n- ⊗ Assume interview because the sections below describe the interview process\n- ⊗ Fabricate justification for using interview when the user chose a different strategy\n- ⊗ Announce the strategy choice and then stop — you must immediately read the file and start\n\n---\n\n*⬇️ Everything below applies ONLY to the interview strategy. If your strategy is anything else, STOP — follow your strategy file instead.*\n\n### Sizing Gate (interview and yolo strategies only)\n\n! After hearing what the user wants to build and their feature list, determine\nproject complexity per [strategies/interview.md](../../strategies/interview.md#sizing-gate).\n\n- ! Check `PROJECT-DEFINITION.xbrief.json` narratives for `Light` or `Full` — if declared, use that path\n- ! If not declared, propose a size and **ask the user to confirm in a dedicated message**\n- ! **Wait for the user's response** before asking any interview questions\n- ⊗ Combine the sizing proposal with the first interview question\n- ⊗ Proceed to interview questions before the user has confirmed the path\n\n**Light** (small/medium): Interview → slim narratives (Overview + Architecture) in `PROJECT-DEFINITION.xbrief.json` → scope xBRIEFs in `xbrief/proposed/`.\n**Full** (large/complex): Interview → rich PROJECT-DEFINITION narratives for user approval → scope xBRIEFs with traceability.\n\n! Neither greenfield path creates `xbrief/specification.xbrief.json`; that file remains a full-spec compatibility artifact.\n\n### Interview Process (interview strategy)\n\nPer [strategies/interview.md](../../strategies/interview.md#interview-rules-shared-by-both-paths):\n\n- ! Ask what to build and features first\n- ! Ask **ONE** focused, non-trivial question per step\n- ~ Provide numbered options with an \"other\" choice\n- ! Mark which option is RECOMMENDED\n- ⊗ Ask multiple questions at once\n- ⊗ Make assumptions without clarifying\n- ~ Use structured question tools for interview questions only when they preserve visible numeric option labels and return numeric selections or exact displayed option text; otherwise render the numbered menu in chat.\n\n**Question Areas:**\n- ! Missing decisions (language, framework, deployment)\n- ! Edge cases (errors, boundaries, failure modes)\n- ! Implementation details (architecture, patterns, libraries)\n- ! Requirements (performance, security, scalability)\n- ! UX/constraints (users, timeline, compatibility)\n- ! Tradeoffs (simplicity vs features, speed vs safety)\n\n**Non-Technical Users:**\n- ~ Adjust vocabulary: \"How do you want to store data?\" not \"What database engine?\"\n- ~ \"Will other apps talk to this?\" not \"REST or GraphQL?\"\n\n**Completion:**\n- ! Continue until little ambiguity remains\n- ! Spec must be comprehensive enough to implement\n\n### Output — Light Path\n\n1. ! Merge the confirmed slim narratives into `./xbrief/PROJECT-DEFINITION.xbrief.json`:\n   - `Overview`: Brief project summary\n   - `Architecture`: System design description\n2. ! Create scope xBRIEFs in `./xbrief/proposed/` for each identified work item\n   - Each scope xBRIEF follows the `YYYY-MM-DD-descriptive-slug.xbrief.json` filename convention (slug rules in [`../../conventions/vbrief-filenames.md`](../../conventions/vbrief-filenames.md))\n   - Each MUST use `\"xBRIEFInfo\": { \"version\": \"0.8\" }`\n   - Each MUST include embedded Requirements (FR-N, NFR-N) in its `narrative`\n   - Each task SHOULD reference which FR/NFR it implements via `narrative.Traces`\n   - When the scope originates from a GitHub issue, include a `references` entry in the canonical form (see [`../../conventions/references.md`](../../conventions/references.md)):\n     ```json\n     \"references\": [\n       {\n         \"uri\": \"https://github.com/{owner}/{repo}/issues/{N}\",\n         \"type\": \"x-xbrief/github-issue\",\n         \"title\": \"Issue #{N}: {issue title}\"\n       }\n     ]\n     ```\n3. ! Summarize decisions and ask the user to approve the PROJECT-DEFINITION narratives and proposed scope set\n4. ! Record approval in the setup session; do not manufacture or require `specification.xbrief.json`\n- ⊗ Create a separate PRD.md on the Light path\n- ⊗ Generate an authoritative PRD.md — if needed, users run `task prd:render`\n\n! The xBRIEF files MUST conform to `xbrief/schemas/xbrief-core-0.8.schema.json` (v0.8):\n\n- ! All `narratives` and `narrative` values MUST be plain strings — never objects or arrays\n- ! Nested children within a PlanItem use `items` (preferred field); `subItems` is the deprecated legacy alias kept for backward compatibility only\n- ⊗ Mix `items` and `subItems` on the same PlanItem — pick one (prefer `items`)\n- ⊗ Emit `\"version\": \"0.6\"` on any new write path — current engine write-default is `0.8` only (#2971)\n\n### Output — Full Path\n\n1. ! Merge these rich narratives into `./xbrief/PROJECT-DEFINITION.xbrief.json` for review:\n   - `ProblemStatement`: What problem this project solves\n   - `Goals`: High-level project goals\n   - `UserStories`: User stories in standard format\n   - `Requirements`: Structured requirements (FR-N: ..., NFR-N: ...)\n   - `SuccessMetrics`: Measurable success criteria\n   - `Architecture`: System design and technical architecture\n   - `Overview`: Brief project summary\n2. ! **Human approval gate**: Present the PROJECT-DEFINITION narratives and proposed scope plan to the user for review. The user may request changes before approving.\n3. ! Record approval in the setup session and proceed to downstream generation; do not manufacture or require `specification.xbrief.json`\n4. ! Create scope xBRIEFs in `./xbrief/proposed/` with traceability to requirement IDs from the narratives\n- ! Scope xBRIEFs MUST trace tasks back to requirement IDs (FR-1, NFR-1) from the `Requirements` narrative\n- ⊗ Generate an authoritative PRD.md — if needed, users run `task prd:render`\n\n**Spec Structure (both paths):**\n- ! Overview, Architecture\n- ! Implementation Plan: scope xBRIEFs in `xbrief/proposed/` with phases and dependencies\n- ! Explicit dependency mapping MUST use the field consumers actually read for the scope shape:\n  - **Story-shaped scopes** (`plan.metadata.kind = \"story\"` or scopes intended for swarm allocation / decompose): sequential/blocked work MUST set `plan.metadata.swarm.depends_on` to an array of **resolvable story identifiers**. Swarm readiness, decompose, and queue traversal read **only** this field for story ordering — not `plan.metadata.dependencies` alone. ! Each `depends_on` entry MUST equal the blocking scope's `plan.id` when that field is set; otherwise the blocking artifact's **filename stem** (basename with `.xbrief.json` / `.vbrief.json` stripped — the same stem readiness uses as `story_id`). ⊗ Use rendered titles, free-form prose, date-only prefixes, or unstripped full filenames — those do not resolve and leave the generated scope blocked.\n  - **Phase/epic or cross-scope roadmap batches**: MAY also set plan-level `plan.metadata.dependencies` for roadmap/export readers.\n  - `edges` / `references` may supplement documentation but **do not** replace `plan.metadata.swarm.depends_on` for sequential story scopes.\n- ! When multiple scopes are produced in one Phase 3 pass, encode machine-readable dependency ordering before finishing the write: independent scopes use empty `plan.metadata.swarm.depends_on` (`[]`); sequential/blocked story scopes use non-empty `plan.metadata.swarm.depends_on`. Optionally mirror the same DAG in `plan.metadata.dependencies` for roadmap views.\n- ~ Scopes designed for parallel work by multiple agents\n- ⊗ Deposit sequential story-shaped scopes with only `plan.metadata.dependencies` / `edges` / `references` and missing `plan.metadata.swarm.depends_on` — orchestration will treat them as independent or reject readiness.\n- ⊗ Deposit multiple generated scope xBRIEFs with no dependency metadata and rely on filenames or human prose for ordering.\n- ! Testing Strategy and Deployment captured in narratives\n- ⊗ Write code — specification only\n\n### Scope acceptance write shape (#4374)\n\n! When a Phase 3 (Light or Full) or Add-scope write includes independently testable acceptance criteria, put them on `plan.narratives.AcceptanceCriteria` as markdown list items (`- ` or `1.`). `Test` and `Verification` use the same shapes. The JSON key is the section delimiter — do not duplicate `## Acceptance Criteria` inside the string. Labeled lines (`test:` / `acceptance:`) are also derivable.\n\n! Bare prose in those keys is not derivable. `scope:promote` / `scope:activate` then name the unparseable shape instead of silently no-op'ing. Do not hand-author `plan.acceptance` to pass activate.\n\n⊗ Stamp write-time `plan.acceptance: { \"none_stated\": true }` as a derive-and-stamp. Derivation already engages on an absent block; that write opens activate with 0 clauses.\n\n~ A successful #3323 stamp writes `commands`, `none_stated`, `source_rung`, `derived_reason`, `clauses`, and `ambiguity_attestation`. Do not emit `file_scope` or a second attestation writer here — that compose is #4380.\n\n### plan.acceptance exclusive writer (#4380)\n\n! Derivation (`#3323` / `#3360`) owns `plan.acceptance`. Setup stays silent on that block.\n⊗ Emit `plan.acceptance`, `ambiguity_attestation`, or a schema-complete acceptance stamp from this skill.\n? Collect `plan.metadata.swarm.file_scope` only as operator-named declared members for later derived-stamp bind (`#4008`). ⊗ Invent paths. ⊗ Mint an approved-scope digest (`#3145` / `#3110`).\n! Fields the gate requires: [`../../docs/plan-acceptance.md`](../../docs/plan-acceptance.md).\n\n### Lifecycle Bridge to Downstream Skills (#1025)\n\n! Scope xBRIEFs created by Phase 3 (both Light and Full paths) AND by the Onboarding Question \"Add scope to this project\" branch land in `xbrief/proposed/` with `plan.status: proposed`. This is the canonical deposit point per the deft lifecycle (`proposed -> pending -> active -> completed`). The #810 implementation-intent gate (`task xbrief:preflight`) and the deft-directive-swarm Phase 0 Step 1 preflight BOTH require candidate xBRIEFs to live in `xbrief/active/` with `plan.status == \"running\"` before any agent can dispatch against them; setup deliberately stops at `proposed/` because the lifecycle commitment (promote + activate) belongs to the downstream skill, not the setup interview.\n\n! Surface this bridge to the user in the Phase 3 → next-skill handoff so they are not surprised by a wholesale preflight rejection downstream:\n\n  - **If the next step is `skills/deft-directive-swarm/SKILL.md`**: the swarm skill's Phase 0 Step 0.5 (Lifecycle Bridge -- Promote and Activate Proposed Scope xBRIEFs) is the canonical bridge. The monitor will scan `xbrief/proposed/` and `xbrief/pending/`, present in-scope candidates, and run `task scope:promote -- <path>` then `task scope:activate -- <path>` on explicit user approval. No manual operator action is required ahead of the swarm invocation.\n  - **If the next step is `skills/deft-directive-refinement/SKILL.md`**: the refinement skill's Phase 4 (Promote/Demote) owns the same `task scope:promote` / `task scope:activate` surface and runs the bridge as part of the refinement loop. The refinement skill MAY leave xBRIEFs in `pending/` deliberately when they are queued for prioritisation rather than immediate dispatch.\n  - **If the user wants to invoke an implementation agent directly via `skills/deft-directive-build/SKILL.md` or `start_agent`**: the bridge MUST be run manually before dispatch -- `task scope:promote -- xbrief/proposed/<file>` then `task scope:activate -- xbrief/pending/<file>`. Both commands are idempotent and exit 0 on no-op. The #810 preflight gate (`task xbrief:preflight -- <active-path>`) will exit 0 only after the activate step.\n\n⊗ Auto-run `task scope:promote` or `task scope:activate` from the setup skill on the Phase 3 outputs. The lifecycle commitment belongs to the user (\"I am ready to swarm/build on this scope\"), not the setup interview; silent promotion would clear the #810 implementation-intent gate without explicit user authorisation and bypass the deterministic-questions contract that protects every other Phase 3 transition.\n\n⊗ Drop the user at the end of Phase 3 with scope xBRIEFs in `xbrief/proposed/` and no forward pointer to the bridge. Without this section the user discovers the gap at runtime when the swarm Phase 0 Step 1 preflight rejects every candidate (`Invalid transition: 'activate' requires file in pending/`), as in the originating 2026-05-10 first-session consumer tic-tac-toe swarm (issue #1025).\n\n### End-of-Phase-3 Export Prompt (project:export-spec)\n\n! After scope xBRIEFs are written to `xbrief/proposed/` and PROJECT-DEFINITION is populated, but BEFORE handing off to `deft-directive-build` (or advancing speckit Phase 3 → Phase 4), ask the user whether to generate human-readable exports. Greenfield v0.20 projects export via `task project:export-spec` (not legacy `task spec:render`). This replaces the invisible skip-if-absent behavior of `task check` (#398), closes the greenfield gap (#433), and is the Phase 3 → Phase 4 transition gate required by [strategies/speckit.md Post-Phase 3 Transition Gate](../../strategies/speckit.md#post-phase-3-transition-gate-export-for-review) (#432 / #2013).\n\n1. ! Prompt: \"Your scope xBRIEFs are ready. Generate a stakeholder-facing spec export and/or `PRD.md` now? (recommended for stakeholder review)\"\n   1. Yes — export spec (+ PRD if selected)\n   2. Spec export only (`SPECIFICATION.md`)\n   3. `PRD.md` only\n   4. Skip — I'll export later with `task project:export-spec` / `task prd:render`\n2. ! Run the selected export command(s):\n   - `task project:export-spec` → writes `SPECIFICATION.md` from PROJECT-DEFINITION + lifecycle scopes (greenfield default; stakeholder audience)\n   - `task project:export-spec -- --audience=internal` → same export but includes proposed scopes under `## Scope outlook` (use for setup/speckit internal handoff when proposed scopes need visibility)\n   - `task prd:render` → writes `PRD.md` (optional stakeholder review)\n   - Legacy `task spec:render` — migrated trees only (when `xbrief/specification.xbrief.json` exists); do NOT use on greenfield v0.20 projects\n3. ! If the user picked a speckit-strategy project: export is **mandatory** at this boundary — invoke `task project:export-spec` (with `--audience=internal` when proposed scopes exist) even if the user declined the prompt, because speckit Phase 3 → Phase 4 is gated on **export succeeded** (exit 0), not on `specification.xbrief.json` approval.\n4. ! Confirm to the user which files were written and remind them that direct edits to `SPECIFICATION.md` / `PRD.md` are overwritten on the next export — edit xBRIEF narratives in `xbrief/proposed/` and PROJECT-DEFINITION instead.\n5. ~ If the user skipped export and is NOT on a speckit strategy, no-op and continue.\n\n⊗ Advance a speckit project to Phase 4 without a successful `task project:export-spec` at this gate — export must succeed (exit 0) for the Phase 3 transition criterion.\n⊗ Silently skip the prompt — greenfield users who never open a PR will miss the exports without it.\n⊗ Invoke legacy `task spec:render` on a greenfield v0.20 project — use `task project:export-spec` instead (#2013).\n\n### Handoff to deft-directive-build\n\n- ! Emit a structured-tool question asking whether to continue toward the build phase only when the host preserves numeric labels; otherwise emit the deterministic numbered menu in chat. Options: `1. Yes (run cost phase)`, `2. Not now (exit setup)`, `3. Discuss`, `4. Back (revisit previous phase)`. The numeric labels MUST remain visible and be returned as numeric selections or exact displayed option text.\n- ! If the user picks Yes, invoke `skills/deft-directive-cost/SKILL.md`; only a recorded Build or Skip decision from that skill may hand off to `skills/deft-directive-build/SKILL.md`\n- ⊗ Invoke the build skill directly from setup and bypass the required cost decision\n- ⊗ Leave user with a dead end -- always offer the next step via the structured-tool phase-transition question\n- ⊗ Ask the handoff-to-build question as unnumbered conversational prose or through a structured UI that hides the canonical numeric labels -- it is a deterministic menu and MUST preserve visible numbers (#478, #1563).\n\n## Warp Auto-Approve Warning\n\n! **Recommended Warp setting**: Before running deft-directive-setup, ensure Warp's AI autonomy is set to **\"Always ask\"** in **AI -> Profile Settings**. When set to a higher autonomy level (e.g. \"Auto-run\"), Warp may silently self-answer interview questions without user input, producing garbage USER.md/PROJECT-DEFINITION.xbrief.json with no error or warning. The post-interview confirmation gate (below) is the last line of defense, but prevention is better than detection.\n\n## Post-Interview Confirmation Gate\n\n! After completing ALL interview questions for any phase (Phase 1, Phase 2, or Phase 3), but BEFORE writing any files:\n\n1. ! Display a **summary of all captured values** in a clearly formatted list -- include every field that will be written to the output file (e.g. name, strategy, coverage, languages, project type, custom rules, etc.)\n2. ! Ask the user for explicit confirmation: \"These are the values I captured. Write files? (yes/no)\"\n3. ! Accept only explicit affirmative responses (`yes`, `confirmed`, `approve`) -- reject vague responses (`proceed`, `do it`, `go ahead`) the same way `/deft:change` does\n4. ! If the user says `no`: re-display the values and ask which ones to correct, then re-confirm before writing\n5. ! If any value appears to be auto-generated filler (e.g. repeated default text, placeholder strings, or values that echo the question prompt), warn the user explicitly: \"Some values look like they may have been auto-filled rather than provided by you. Please review carefully.\"\n\n⊗ Write USER.md, PROJECT-DEFINITION.xbrief.json, lifecycle scope xBRIEFs, or any other deft-directive-setup artifact without first displaying captured values and receiving explicit user confirmation.\n⊗ Create `specification.xbrief.json` on a greenfield Light or Full path solely to satisfy export, cost, or build handoff.\n⊗ Treat a broad \"proceed\" or \"continue\" as confirmation to write files -- the user must explicitly confirm the displayed values.\n\n? **Yolo strategy carve-out**: When the user's chosen strategy is `yolo` (auto-pilot), the confirmation gate still applies but the agent (Johnbot) may self-confirm on the user's behalf by displaying the summary and immediately proceeding -- the user has already opted into auto-pilot by selecting yolo. The summary must still be displayed so the user can interrupt if values look wrong.\n\n## Anti-Patterns\n\n- ! When deft-directive-setup generates or updates USER.md, the `deft_version` field MUST be set to the current framework version. USER.md is the only artifact that carries this field.\n- ⊗ Generate a USER.md without including the `deft_version` field\n- ⊗ Write `deft_version` or `DeftVersion` into PROJECT-DEFINITION, specification, or plan xBRIEFs. Those stamps are retired (HASH4271). Specification `deft_version` has no framework seeding path; Pass 1 absence locks are the only control.\n- ⊗ Explore codebase before Phase 1 questions\n- ⊗ Read framework files before first question\n- ⊗ Batch multiple questions into one message — ask one at a time, interview style\n- ⊗ Ask jargon-heavy questions to non-technical users\n- ⊗ Ask about things inferable from codebase (Phase 2+)\n- ⊗ Skip phases without asking\n- ⊗ Generate files without confirming content\n- ⊗ Present choices through a host UI that replaces the canonical numbers with alphabetic affordances or unlabeled buttons\n- ⊗ Resolve paths relative to the skill file, AGENTS.md, or framework directory instead of the user's pwd at skill entry\n- ⊗ Generate an authoritative PRD.md — PRD.md is a read-only export via `task prd:render`, never a source of truth\n- ⊗ Skip the Returning-user re-entry / Revisit experimental rules path when USER.md exists and the operator entered setup to change experimental meta (#46)\n- ⊗ Clobber Personal or Defaults while toggling Experimental Rules (#46)\n- ⊗ Invent a full `deft config` verb family for experimental meta when setup re-entry suffices (#46)\n- ⊗ Default identity-only Phase 3 to Add-scope because PROJECT-DEFINITION exists (#4390)\n- ⊗ Synthesize the first proposed scope from Overview, directory name, or init seed (#4390)\n",
       "frontmatter_extra": null
     },
     {