@deftai/directive-content 0.100.0 → 0.102.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; wraps `scripts/preflight_implementation.py` so 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 `scripts/_precutover.py`; 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 -->` 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 (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 -- or the direct form `python .deft/core/scripts/validate_strategy_output.py --project-root <path>` after `deft` install):\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) or `python .deft/core/scripts/validate_strategy_output.py --project-root .`. 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## 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.6\" }`. The validator rejects any other version (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 after a red merge chokepoint | `task check` green | Counts toward the implement/quality fix envelope above (do not open a separate unbounded check-retry loop) |\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## 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## Literal acceptance-command verification (#3267)\n\nAt intake, capture the task statement's **exact** acceptance commands (when present) as executable AC. Before declaring done, run them **verbatim** — same paths, same flags, same working directory. Self-chosen verification is supplementary, never a substitute. Extends #973 machine-verifiable-spec. Required on ceremony dial rapid/minimal (#3214) — verification depth is constant (#3156).\n\n- ! When reading the active scope xBRIEF / issue body at story start, capture stated shell acceptance commands into `plan.metadata.literal_acceptance_commands` (issue:ingest does this automatically). Do not paraphrase into a different command.\n- ! Before claiming phase or story done (and before merge-chokepoint PR handoff), run:\n```\ntask verify:literal-ac -- <active-story-path>\n```\n  Exit 0 = pass or no commands stated; exit 1 = a stated command failed; exit 2 = config.\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 — the check survives light ceremony.\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: <300 lines ideal, <500 recommended, ! <1000 max\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\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, complete each implemented story via `task scope:complete -- <active-story-path>` before final PR handoff.\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` (which wraps `scripts/preflight_implementation.py`) -- 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- ⊗ 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",
+      "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; wraps `scripts/preflight_implementation.py` so 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 `scripts/_precutover.py`; 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 -->` 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 (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 -- or the direct form `python .deft/core/scripts/validate_strategy_output.py --project-root <path>` after `deft` install):\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) or `python .deft/core/scripts/validate_strategy_output.py --project-root .`. 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## 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.6\" }`. The validator rejects any other version (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 after a red merge chokepoint | `task check` green | Counts toward the implement/quality fix envelope above (do not open a separate unbounded check-retry loop) |\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/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: <300 lines ideal, <500 recommended, ! <1000 max\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\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, complete each implemented story via `task scope:complete -- <active-story-path>` before final PR handoff.\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` (which wraps `scripts/preflight_implementation.py`) -- 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- ⊗ 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- ⊗ 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
     },
     {
@@ -161,7 +161,7 @@
       ],
       "path": "skills/deft-directive-portfolio-priority/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Portfolio Priority\n\nPre-promotion **portfolio prioritization pass**: cluster competing RFCs/issues from the local github-issue cache, name conflicts/supersession, emit a **propose-not-apply** priority brief (shortlist + park), then hand off for operator dispose. Parent process + dogfood: **#3198**. Worked example: **#3200** / [`docs/analysis/2026-08-07-portfolio-priority-brief-patterns-pilot.md`](../../../docs/analysis/2026-08-07-portfolio-priority-brief-patterns-pilot.md).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- Maintainer wants a **portfolio priority** brief across competing open issues / RFCs\n- Operator says: portfolio priority, priority brief, competing RFCs, cluster open issues, pre-promotion portfolio, rank this backlog slice\n- After a large classify / label-mirror partition when humans still need a shortlist (B-side; not the ranker)\n- ⊗ Do NOT use for single-issue \"what's next?\" ranking — that is `deft-directive-triage` + `task triage:queue`\n- ⊗ Do NOT use for post-promotion capacity buckets — that is #1419 / #1511\n- ⊗ Do NOT use for review-handoff briefs — that is #1590\n\n## Stance (hard)\n\n- ! **Propose-not-apply** (#3179): the brief proposes; the operator disposes\n- ⊗ SCM label writes, mirror `--apply`, or re-enrich apply from this skill\n- ⊗ `task triage:accept` / reject / defer / needs-ac / mark-duplicate / bulk-*\n- ⊗ Scope lifecycle (`scope:promote` / `activate` / `complete` / `cancel`) from this skill\n- ⊗ Treat the brief as a decision record — dispose via `task decision:write` / plan-sequence / operator comment (#1396)\n\n## Inputs\n\n- ! Local `.deft-cache/github-issue/` (bodies available)\n- ! Classify partition via `task triage:classify -- --mirror` (or cached JSON digest) as **FILTER only**\n- ~ Optional theme slice: label family, title prefix, author, epic parent\n\n## Phases\n\n### Phase 0 — Cache freshness\n\n1. ! Run `task verify:cache-fresh`. Exit 0 → proceed. Exit 1 → refresh (`task cache:fetch-all -- --source=github-issue --repo OWNER/NAME`) or **disclose stale** and continue only with operator consent. Exit 2 → `task triage:bootstrap` first.\n2. ~ When zero cache entries, bootstrap/fetch before clustering (#2575).\n3. ⊗ Cluster against a silent stale cache without disclosing staleness.\n\n### Phase 1 — Classify as FILTER only\n\n1. ! Run `task triage:classify -- --mirror` (dry-run; optional `--json`) to partition dispositions (`no_match` / escalate / defer / already planned).\n2. ! Use classify outcomes only to **filter** the portfolio slice (e.g. deep-dive candidates from `no_match`; keep escalate on an interrupt queue).\n3. ⊗ Use classify disposition chips as the **ranker** or final shortlist order.\n4. ⊗ Pass `--apply` or `--re-enrich` with intent to write labels from this skill.\n\n### Phase 2 — Theme / slice selection\n\n1. ! Name an **explicit slice** (label family, title theme, author, or epic). Unattended full-backlog ranking is out of scope.\n2. ! Record scope counts: open in slice, classify partitions inside the slice, exclusions.\n3. ~ Prefer one coherent theme per brief (pilot: patterns + `no_match`).\n\n### Phase 3 — Cluster + conflict matrix + shortlist + park\n\n1. ! Group candidates into **families** (title/theme/body overlap, shared parent epic, layered pack).\n2. ! Build a **conflict / supersession matrix** per family: overlapping roots, pack-vs-atom, research-vs-product.\n3. ! Emit an ordered **shortlist** (deep dive / promote candidates) and a **park list** with park reasons.\n4. ! Separate **interrupt / non-portfolio** rows (escalate, hold, already dispositioned) so they are not ranked against park list.\n5. ⊗ Claim \"#X supersedes #Y\" from titles alone — see Phase 4 epistemic gates.\n\n### Phase 4 — Epistemic gates (MUST)\n\nBefore citing any `#N` in the brief:\n\n1. ! **Verify existence + state** for every cited issue via live `gh api repos/OWNER/NAME/issues/N` (REST) **or** a proven-fresh cache entry whose state matches the claim.\n2. ! **Read the body** of every issue used for shortlist, park-as-superseded, pack membership, or \"decided\" claims.\n3. ! When claiming decided / superseded / closed-by-comment, also **read comments** (REST `issues/N/comments`).\n4. ! State **open/closed accurately**; never invent issue numbers.\n5. ⊗ **Title-only supersession** or ownership claims.\n6. ⊗ Cite PRs as issues without filtering `pull_request` on mixed issue lists.\n\n### Phase 5 — Emit priority brief\n\n! Write markdown matching the pilot section shape (fill with this run's slice):\n\n1. **Header** — process issue (#3198 or project equivalent), parent tracker if any, generated timestamp, stance (propose-not-apply), epistemic method\n2. **Dispose path** — not a decision record; points at #1396 / plan-sequence / operator comment\n3. **Scope of this pass** — counts table (slice filters + partition sizes)\n4. **Interrupt / non-portfolio** — escalate/hold/already planned (do not rank here)\n5. **Conflict / family matrix** — families with verified state + body claims + recommendation\n6. **Shortlist** — ordered P1/P2/… with why\n7. **Park list** — classes, examples, park reasons\n8. **Epistemic limits** — what was cache-only, what needs follow-up probe\n9. **Operator dispose checklist** — accept/edit shortlist, accept park, record dispose, optional plan-sequence; do not treat as mirror apply\n\n~ Prefer writing under `docs/analysis/YYYY-MM-DD-portfolio-priority-brief-<slice>.md` for durable dogfood; chat-only is allowed if the operator declines a file.\n\n~ Link the worked example: #3200 and `docs/analysis/2026-08-07-portfolio-priority-brief-patterns-pilot.md` (may live on the pilot PR until merged).\n\n### Phase 6 — Dispose checklist (hand off)\n\n1. ! Present the dispose checklist to the operator (accept/edit shortlist + park; record dispose; optional plan-sequence for P1).\n2. ! Point dispose targets: `task decision:write` (#1396 structured decision log under `xbrief/decisions/`; optional interim issue comment only if the write surface is unavailable), and/or `task plan-sequence:set`.\n3. ⊗ Auto-promote shortlist into plan-sequence without explicit operator dispose.\n4. ⊗ Exit treating the brief alone as durable prioritization memory (#2741 class).\n\n## Anti-Patterns\n\n- ⊗ SCM label writes / mirror apply / re-enrich apply from this skill\n- ⊗ `triage:accept` or any triage decision verb from this skill\n- ⊗ Scope lifecycle mutations from this skill\n- ⊗ Title-only supersession or unverified `#N` citations\n- ⊗ Full open-backlog unattended ranking without an explicit slice\n- ⊗ Replacing `triage:queue` for buildable work selection\n- ⊗ Treating the brief as the decision record without dispose\n\n## EXIT\n\n! Confirm: `deft-directive-portfolio-priority complete -- exiting skill.`\n~ Chain: operator dispose (`task decision:write` / plan-sequence) · `deft-directive-triage` for single-item queue work · `deft-directive-refinement` after accept on a different path · do **not** chain into mirror apply.\n⊗ Silent exit.\n\n## References\n\n- #3198 process + dogfood · #3201 this skill · #3200 / patterns pilot brief\n- #1396 decision log · #3179 propose-not-apply · #1423 / #3197 classify filter only\n- Siblings: `deft-directive-triage`, `deft-directive-refinement` — not #1419/#1511 post-promotion\n",
+      "body": "# Deft Directive Portfolio Priority\n\nPre-promotion **portfolio prioritization pass**: cluster competing RFCs/issues from the local github-issue cache, name conflicts/supersession, emit a **propose-not-apply** priority brief (shortlist + park), then hand off for operator dispose. Parent process + dogfood: **#3198**. Worked example: **#3200** / [`docs/analysis/2026-08-07-portfolio-priority-brief-patterns-pilot.md`](../../../docs/analysis/2026-08-07-portfolio-priority-brief-patterns-pilot.md).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- Maintainer wants a **portfolio priority** brief across competing open issues / RFCs\n- Operator says: portfolio priority, priority brief, competing RFCs, cluster open issues, pre-promotion portfolio, rank this backlog slice\n- After a large classify / label-mirror partition when humans still need a shortlist (B-side; not the ranker)\n- ⊗ Do NOT use for single-issue \"what's next?\" ranking — that is `deft-directive-triage` + `task triage:queue`\n- ⊗ Do NOT use for post-promotion capacity buckets — that is #1419 / #1511\n- ⊗ Do NOT use for review-handoff briefs — that is #1590\n\n## Stance (hard)\n\n- ! **Propose-not-apply** (#3179): the brief proposes; the operator disposes\n- ⊗ SCM label writes, mirror `--apply`, or re-enrich apply from this skill\n- ⊗ `task triage:accept` / reject / defer / needs-ac / mark-duplicate / bulk-*\n- ⊗ Scope lifecycle (`scope:promote` / `activate` / `complete` / `cancel`) from this skill\n- ⊗ Treat the brief as a decision record — dispose via `task decision:write` / plan-sequence / operator comment (#1396)\n\n## Inputs\n\n- ! Local `.deft-cache/github-issue/` (bodies available)\n- ! Classify partition via `task triage:classify -- --mirror` (or cached JSON digest) as **FILTER only**\n- ~ Optional theme slice: label family, title prefix, author, epic parent\n\n## Phases\n\n### Phase 0 — Cache freshness\n\n1. ! Run `task verify:cache-fresh`. Exit 0 → proceed. Exit 1 → refresh (`task cache:fetch-all -- --source=github-issue --repo OWNER/NAME`) or **disclose stale** and continue only with operator consent. Exit 2 → `task triage:bootstrap` first.\n2. ~ When zero cache entries, bootstrap/fetch before clustering (#2575).\n3. ⊗ Cluster against a silent stale cache without disclosing staleness.\n\n### Phase 1 — Classify as FILTER only\n\n1. ! Run `task triage:classify -- --mirror` (dry-run; optional `--json`) to partition dispositions (`no_match` / escalate / defer / already planned).\n2. ! Use classify outcomes only to **filter** the portfolio slice (e.g. deep-dive candidates from `no_match`; keep escalate on an interrupt queue).\n3. ⊗ Use classify disposition chips as the **ranker** or final shortlist order.\n4. ⊗ Pass `--apply` or `--re-enrich` with intent to write labels from this skill.\n\n### Phase 2 — Theme / slice selection\n\n1. ! Name an **explicit slice** (label family, title theme, author, or epic). Unattended full-backlog ranking is out of scope.\n2. ! Record scope counts: open in slice, classify partitions inside the slice, exclusions.\n3. ~ Prefer one coherent theme per brief (pilot: patterns + `no_match`).\n\n### Phase 3 — Cluster + conflict matrix + shortlist + park\n\n1. ! Group candidates into **families** (title/theme/body overlap, shared parent epic, layered pack).\n2. ! Build a **conflict / supersession matrix** per family: overlapping roots, pack-vs-atom, research-vs-product.\n3. ! Emit an ordered **shortlist** (deep dive / promote candidates) and a **park list** with park reasons.\n4. ! Separate **interrupt / non-portfolio** rows (escalate, hold, already dispositioned) so they are not ranked against park list.\n5. ⊗ Claim \"#X supersedes #Y\" from titles alone — see Phase 4 epistemic gates.\n6. ! **List-before-re-recommend** (#3315): for each cited `#N` before re-recommending an overlap, run `task decision:list -- --issue N --json` and match `relatedIssues` from the JSON. Park / do not re-shortlist as novel overlap only when a dispose decision's `relatedIssues` covers this overlap's members (not some other relationship that merely mentions N), unless `revisitTrigger` applies. Advisory diligence — not a `task check` gate. ⊗ Auto-close issues or treat the brief as the dispose record.\n7. Parent/child, leaf/tracker, and sibling-validator pairs are **not** duplicates — #3066/#3082, #95/#96, #513/#514.\n\n### Phase 4 — Epistemic gates (MUST)\n\nBefore citing any `#N` in the brief:\n\n1. ! **Verify existence + state** for every cited issue via live `gh api repos/OWNER/NAME/issues/N` (REST) **or** a proven-fresh cache entry whose state matches the claim.\n2. ! **Read the body** of every issue used for shortlist, park-as-superseded, duplicate/consolidate classification, pack membership, or \"decided\" claims.\n3. ! When claiming decided / superseded / closed-by-comment, also **read comments** (REST `issues/N/comments`).\n4. ! State **open/closed accurately**; never invent issue numbers.\n5. ⊗ **Title-only supersession**, duplicate, or ownership claims.\n6. ⊗ Cite PRs as issues without filtering `pull_request` on mixed issue lists.\n\n### Phase 5 — Emit priority brief\n\n! Write markdown matching the pilot section shape (fill with this run's slice):\n\n1. **Header** — process issue (#3198 or project equivalent), parent tracker if any, generated timestamp, stance (propose-not-apply), epistemic method\n2. **Dispose path** — not a decision record; points at #1396 / plan-sequence / operator comment\n3. **Scope of this pass** — counts table (slice filters + partition sizes)\n4. **Interrupt / non-portfolio** — escalate/hold/already planned (do not rank here)\n5. **Conflict / family matrix** — families with verified state + body claims + recommendation\n6. **Shortlist** — ordered P1/P2/… with why\n7. **Park list** — classes, examples, park reasons\n8. **Epistemic limits** — what was cache-only, what needs follow-up probe\n9. **Operator dispose checklist** — accept/edit shortlist, accept park, record dispose, optional plan-sequence; do not treat as mirror apply\n\n~ Prefer writing under `docs/analysis/YYYY-MM-DD-portfolio-priority-brief-<slice>.md` for durable dogfood; chat-only is allowed if the operator declines a file.\n\n~ Link the worked example: #3200 and `docs/analysis/2026-08-07-portfolio-priority-brief-patterns-pilot.md` (may live on the pilot PR until merged).\n\n### Phase 6 — Dispose checklist (hand off)\n\n1. ! Present the dispose checklist to the operator (accept/edit shortlist + park; record dispose; optional plan-sequence for P1).\n2. ! Point dispose targets: `task decision:write` (#1396 / [`docs/decision-log.md`](../../docs/decision-log.md)): every overlap-cluster member in `relatedIssues`; include `revisitTrigger`; free-text MAY name relationship. Optional `task plan-sequence:set`. Interim issue comment only if the write surface is unavailable.\n3. ⊗ Auto-promote shortlist into plan-sequence without explicit operator dispose.\n4. ⊗ Exit treating the brief alone as durable prioritization memory (#2741 class).\n~ Dedicated duplicate-clusters ledger is deferred; earn it only when a pass re-litigates a cluster despite a dispose decision listing the members (#3310). Boundaries: #886, #1178, #786, #3198/#3201, #1396.\n\n## Anti-Patterns\n\n- ⊗ SCM label writes / mirror apply / re-enrich apply from this skill\n- ⊗ `triage:accept` or any triage decision verb from this skill\n- ⊗ Scope lifecycle mutations from this skill\n- ⊗ Title-only supersession or unverified `#N` citations\n- ⊗ Full open-backlog unattended ranking without an explicit slice\n- ⊗ Replacing `triage:queue` for buildable work selection\n- ⊗ Treating the brief as the decision record without dispose\n- ⊗ Re-shortlist a disposed overlap without `task decision:list -- --issue N` (#3315)\n\n## EXIT\n\n! Confirm: `deft-directive-portfolio-priority complete -- exiting skill.`\n~ Chain: operator dispose (`task decision:write` / plan-sequence) · `deft-directive-triage` for single-item queue work · `deft-directive-refinement` after accept on a different path · do **not** chain into mirror apply.\n⊗ Silent exit.\n\n## References\n\n- #3198 process + dogfood · #3201 this skill · #3200 / patterns pilot brief\n- #1396 decision log · #3179 propose-not-apply · #1423 / #3197 classify filter only\n- #3315 overlap dispose · #3310 ledger archive · #886 / #1178 / #786 boundaries\n- Siblings: `deft-directive-triage`, `deft-directive-refinement` — not #1419/#1511 post-promotion\n",
       "frontmatter_extra": "triggers:\n  - portfolio priority\n  - priority brief\n  - competing RFCs\n  - cluster open issues\n  - pre-promotion portfolio\n  - portfolio prioritization\n  - rank this backlog slice\nmetadata:\n  clawdbot:\n    requires:\n      bins: [\"gh\"]"
     },
     {
@@ -174,7 +174,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 `scripts/policy.py` / `scripts/preflight_branch.py` (#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```\nuv run python scripts/preflight_branch.py --project-root . --quiet || exit 1\n```\n\nor invoke `task verify:branch`. 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.\n- ! **Merge chokepoint (Phase 3 Lint exit + final confirm):** run full `task check` once before push/PR; Phase 3c targeted coverage precedes but does not replace the full gate.\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\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- ~ 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 merge-chokepoint gate and fix any failures (#1704).\n\n- ! Run full `task check` (fmt + lint + typecheck + tests + coverage + verify:*) — the merge chokepoint, not every pre-PR iteration\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## Literal acceptance-command verification (#3267)\n\n- ! Before Phase 3 Lint exit / push, when the active scope xBRIEF has stated acceptance commands (metadata or narratives), run `task verify:literal-ac -- <active-xbrief>` and fail closed on exit 1.\n- ! Commands must be the exact strings from the task statement — same flags and cwd. Self-chosen verification is supplementary only.\n- ⊗ Skip literal AC run on rapid/minimal ceremony dial — #3267 is required at every depth.\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 `task check` one final time to confirm clean state\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- ⊗ 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- ⊗ 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 `scripts/policy.py` / `scripts/preflight_branch.py` (#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```\nuv run python scripts/preflight_branch.py --project-root . --quiet || exit 1\n```\n\nor invoke `task verify:branch`. 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.\n- ! **Merge chokepoint (Phase 3 Lint exit + final confirm):** run full `task check` once before push/PR; Phase 3c targeted coverage precedes but does not replace the full gate.\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\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- ~ 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 merge-chokepoint gate and fix any failures (#1704).\n\n- ! Run full `task check` (fmt + lint + typecheck + tests + coverage + verify:*) — the merge chokepoint, not every pre-PR iteration\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 `task check` one final time to confirm clean state\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- ⊗ 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
     },
     {
@@ -236,7 +236,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 `scripts/policy.py` / `scripts/preflight_branch.py` (#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 bypass to\n# ONLY this closeout commit+push (do NOT export it for the whole session):\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 git add xbrief/PROJECT-DEFINITION.xbrief.json meta/policy-changes.log\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 git commit -m \"chore(policy): restore branch protection after vX.Y.Z\"\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=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```\nuv run python scripts/preflight_branch.py --project-root . --quiet || exit 1\n```\n\nor invoke `task verify:branch`. 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 ci:local` gate) remain independent of this check.\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`, `task ci:local`, 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.\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 task 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 (`scripts/release.py::_release_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, `task ci:local` / `task check`) 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.\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 / `ci:local` / `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 Step 4 (`task ci:local` or `task check`) 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 `task check` / `ci:local` is green for the failure mode.\n4. Resume the release cut from Phase 1 (re-run Step 4).\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, `coverage/coverage-final.json`, or `task coverage:hotspots` before hatching. 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 is blocked on project `plan.policy.coverageDebt` (#3189) — refuse when `status=unset` or `mode=off`. 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)\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 `task ci:local` passes locally (or `task check` as the graceful-degradation fallback per `tasks/release.yml` line 9-10). The `task release` script will refuse to proceed otherwise -- but Phase 1 catches it earlier — **on failure from a fixable defect, STOP and follow § Fixable check failure below (#2859); do NOT proceed to step 5**\n5. ! Verify `gh auth status` reports authenticated (`task release` will refuse otherwise)\n6. ! **Run `task reconcile:issues -- --apply-lifecycle-fixes` to clear any closed-issue / non-completed-folder xBRIEFs before invoking `task release`** (#734). The release pipeline carries the deterministic gate at Step 3 (`scripts/release.py::check_vbrief_lifecycle_sync`, refuses with `EXIT_VIOLATION` on any Section (c) mismatch), but Phase 1 is the operator's first-line defence -- running the apply-mode flag here is the canonical clean path; `--allow-vbrief-drift` on the pipeline exists only as the explicit-acknowledgment escape hatch (analogous to `--allow-dirty`). The recurrence record is the v0.21.0 cut, which surfaced 13 stranded xBRIEFs (8 cycle-relevant + 5 historical residue) post-publish; the gate now blocks that drift before any irreversible action\n7. ! **Verify the proposed `v<version>` tag is not already in use locally, on origin, or as a published GitHub release** (#784). The release pipeline carries the deterministic gate at Step 4 (`scripts/release.py::check_tag_available`, refuses with `EXIT_VIOLATION` before any state mutation -- CHANGELOG promotion, ROADMAP refresh, build, commit), but Phase 1 is the operator's first-line defence. Quickly probe with `git tag -l v<version>` (local), `git ls-remote --tags origin refs/tags/v<version>` (remote), and `gh release view v<version> --repo <owner>/<repo>` (release-only, where `gh release view` exits 0 only when the release exists). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01: the operator typed `0.22.0` (the prior release from 12 hours earlier) and the legacy pipeline ran 8 steps before failing at `git tag` -- leaving a wrong-version local commit + `dist/deft-0.22.0.zip` orphan + manual `git reset --hard` recovery. The new pre-flight gate blocks that mode before any irreversible action\n8. ! **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.\n9. ! **Disclose npm irrevocability before any tag push (#1972, #2002).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The operator's explicit `yes` in Phase 2 (dry-run) and the decision to invoke `task release` in Phase 4 are the last human gates before npm goes live. Phase 5 only controls GitHub release visibility (draft → public); it does NOT gate npm.\n10. ~ 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) -- this `yes` is the last safe abort before that channel opens.\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 debug (return to Phase 1) or abort (`quit`).\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).** 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.\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`), `scripts/release.py` 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, `scripts/release.py` 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 `scripts/release.py` 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` (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.)\n2. ! 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)\n3. ! 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)\n4. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)\n5. ! 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\n6. ! 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, `ci:local` / `check`) 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- ⊗ 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- ⊗ 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 `scripts/release.py` Step 11 is the only safety net against operator-error variants and partial-success races, and any manual recovery path that bypasses `scripts/release.py` 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` for the entire release session or wrap `task release` / `task ci:local` in it (#1553) -- the env var is process-wide and leaks 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** env prefix on those three git commands only — see Branch-Protection Policy Guard, #2623)\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## Branch-Protection Policy Guard\n\n! Before any Phase 1 state mutation, run the skill-level branch-policy guard documented in `scripts/policy.py` / `scripts/preflight_branch.py` (#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 bypass to\n# ONLY this closeout commit+push (do NOT export it for the whole session):\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 git add xbrief/PROJECT-DEFINITION.xbrief.json meta/policy-changes.log\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 git commit -m \"chore(policy): restore branch protection after vX.Y.Z\"\nDEFT_ALLOW_DEFAULT_BRANCH_COMMIT=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```\nuv run python scripts/preflight_branch.py --project-root . --quiet || exit 1\n```\n\nor invoke `task verify:branch`. 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 ci:local` gate) remain independent of this check.\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`, `task ci:local`, 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.\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 task 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 (`scripts/release.py::_release_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, `task ci:local` / `task check`) 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.\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 / `ci:local` / `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 Step 4 (`task ci:local` or `task check`) 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 `task check` / `ci:local` is green for the failure mode.\n4. Resume the release cut from Phase 1 (re-run Step 4).\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, `coverage/coverage-final.json`, or `task coverage:hotspots` before hatching. 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)\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 `task ci:local` passes locally (or `task check` as the graceful-degradation fallback per `tasks/release.yml` line 9-10). The `task release` script will refuse to proceed otherwise -- but Phase 1 catches it earlier — **on failure from a fixable defect, STOP and follow § Fixable check failure below (#2859); do NOT proceed to step 5**\n5. ! Verify `gh auth status` reports authenticated (`task release` will refuse otherwise)\n6. ! **Run `task reconcile:issues -- --apply-lifecycle-fixes` to clear any closed-issue / non-completed-folder xBRIEFs before invoking `task release`** (#734). The release pipeline carries the deterministic gate at Step 3 (`scripts/release.py::check_vbrief_lifecycle_sync`, refuses with `EXIT_VIOLATION` on any Section (c) mismatch), but Phase 1 is the operator's first-line defence -- running the apply-mode flag here is the canonical clean path; `--allow-vbrief-drift` on the pipeline exists only as the explicit-acknowledgment escape hatch (analogous to `--allow-dirty`). The recurrence record is the v0.21.0 cut, which surfaced 13 stranded xBRIEFs (8 cycle-relevant + 5 historical residue) post-publish; the gate now blocks that drift before any irreversible action\n7. ! **Verify the proposed `v<version>` tag is not already in use locally, on origin, or as a published GitHub release** (#784). The release pipeline carries the deterministic gate at Step 4 (`scripts/release.py::check_tag_available`, refuses with `EXIT_VIOLATION` before any state mutation -- CHANGELOG promotion, ROADMAP refresh, build, commit), but Phase 1 is the operator's first-line defence. Quickly probe with `git tag -l v<version>` (local), `git ls-remote --tags origin refs/tags/v<version>` (remote), and `gh release view v<version> --repo <owner>/<repo>` (release-only, where `gh release view` exits 0 only when the release exists). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01: the operator typed `0.22.0` (the prior release from 12 hours earlier) and the legacy pipeline ran 8 steps before failing at `git tag` -- leaving a wrong-version local commit + `dist/deft-0.22.0.zip` orphan + manual `git reset --hard` recovery. The new pre-flight gate blocks that mode before any irreversible action\n8. ! **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.\n9. ! **Disclose npm irrevocability before any tag push (#1972, #2002).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The operator's explicit `yes` in Phase 2 (dry-run) and the decision to invoke `task release` in Phase 4 are the last human gates before npm goes live. Phase 5 only controls GitHub release visibility (draft → public); it does NOT gate npm.\n10. ~ 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) -- this `yes` is the last safe abort before that channel opens.\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 debug (return to Phase 1) or abort (`quit`).\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).** 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.\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`), `scripts/release.py` 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, `scripts/release.py` 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 `scripts/release.py` 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` (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.)\n2. ! 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)\n3. ! 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)\n4. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)\n5. ! 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\n6. ! 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, `ci:local` / `check`) 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- ⊗ 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- ⊗ 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 `scripts/release.py` Step 11 is the only safety net against operator-error variants and partial-success races, and any manual recovery path that bypasses `scripts/release.py` 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` for the entire release session or wrap `task release` / `task ci:local` in it (#1553) -- the env var is process-wide and leaks 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** env prefix on those three git commands only — see Branch-Protection Policy Guard, #2623)\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
     },
     {