@deftai/directive-runtime 0.127.0 → 0.128.0

package/docs/known-limitations.md

@@ -20,6 +20,7 @@ Accepted product decisions for the launcher + pinned-runtime install model. Docu
 | **Only package/readiness ignore entries change** | Ignore updates cover `node_modules` and `.deft/directive/wiring-ready.*.json`; `GENERATION.json` stays committed | Broader housekeeping stays where it is |
 | **Node 20 is best-effort** | Warning on Node 20; gates test 22 and 24 | Broad compatibility without blocking |
 | **`@deftai/directive` is the launcher** | Adding it locally does not activate a project; meaning changes from “the product” to “the launcher” at the split | Pin `@deftai/directive-runtime` via `directive install` |
+| **FF alone is not tip dogfood** | On the maintainer monorepo, ordinary `task` and hooks stay on the checkout pin; workspace `packages/runtime/dist` is not a silent ordinary-verb fallback (#5805) | Run `task materialize:runtime` in the checkout that should dogfood tip; dest worktrees do not inherit primary materialize |
 | **Hooks cannot run while their runtime package is absent** | Host may block edits until packages are restored | No fallback to another version; recover with `npm i -g @deftai/directive`, then `directive install --repair` |
 | **No `--force`** | Conflicts are named and left | Destructive bypass is out of scope |
 | **Three private packages are not consumable** | `directive-core`, `directive-content`, and `directive-types` are not on npm for external use | Bundled into the runtime; loose ranges were part of the bug |

package/docs/launcher.md

@@ -32,6 +32,16 @@ npm i -g @deftai/directive
 directive install --repair
 ```
 
+## Maintainer dogfood (this repository)
+
+On the Directive monorepo, ordinary unprefixed `task <verb>` paths and Git hooks both execute the **checkout pin** at `node_modules/@deftai/directive-runtime/dist/bin.js` (#5805 / AC9.9). Fast-forwarding `master` alone does not run tip source. Tip without a public publish:
+
+```bash
+task materialize:runtime
+```
+
+That stages and packs tip via `packages/runtime/scripts/stage-bundle.mjs` + `pack-staged-runtime.mjs`, then replaces **this checkout's** pin only (no `package.json` / lockfile location-spec rewrite; primary materialize does not update dest worktree pins). CI tip probes that call `packages/runtime/dist/bin.js` directly stay carved out.
+
 ## Related
 
 - [Known limitations](./known-limitations.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-runtime",
-  "version": "0.127.0",
+  "version": "0.128.0",
   "description": "Directive runtime — pinned product commands, hooks, content, and engine.",
   "license": "MIT",
   "homepage": "https://deftai.github.io/directive/",

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

@@ -207,7 +207,7 @@
       ],
       "path": "skills/deft-directive-pre-pr/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Pre-PR -- Read, Write, Lint, Diff, Loop\n\nStructured self-review loop agents run before submitting a PR. Catches inconsistencies, missing enforcement markers, incomplete acceptance criteria, scope creep, and unintended changes before they reach the reviewer.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) | [deft-directive-build](../deft-directive-build/SKILL.md) | [RWLDL tool](../../tools/RWLDL.md)\n\n> **Formerly `deft-rwldl`** -- renamed and scoped to PR readiness. For the broader iterative quality improvement loop (micro/macro review), see [tools/RWLDL.md](../../tools/RWLDL.md).\n\n## Branch-Protection Policy Guard\n\n! Before entering Phase 1 (Read), run the skill-level branch-policy guard documented in `task policy:show` / dual-invoke `deft verify:branch` (#746 / #747). Halt before any state mutation (the Phase 2 Write phase, the Phase 3 Lint phase that may touch files) when the policy is unresolvable AND no env-var bypass is active:\n\n```\ndeft verify:branch\n```\n\nor `task deft:verify:branch` when the consumer Taskfile include is present. Do not add a consumer `verify:branch` task. Pre-PR is the last gate before push, so a stale / unresolvable policy here is the highest-leverage place to catch the bug before it reaches the bot reviewer.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (per-finding decision menus in Phase 4 Diff, the Phase 5 Loop restart-vs-exit gate) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. The Discuss-pause semantic is documented verbatim there -- implicit resumption is forbidden.\n\n\n## Ordered-plan target gate (#2402)\n\n! Before opening or pushing a PR, when an ordered-plan sequence may be active, verify the work unit matches the current authorized entry:\n\n1. Resolve the current entry kind and id:\n\n```\ntask plan-sequence:current\n```\n\n   Use `task plan-sequence:current -- --json` when you need machine-readable `kind` / `id` fields from the current entry.\n\n2. Verify with the **entry kind** (not hardcoded `pr` — `story` / `issue` entries are common):\n\n```\ntask verify:plan-sequence -- --target-kind <entry-kind> --target <entry-id>\n```\n\n- ! Exit non-zero → fail closed; do not open an unauthorized PR.\n- ! Exit 0 with \"skipped (no active ordered-plan sequence)\" → proceed under normal pre-PR rules.\n- ⊗ Hardcode `--target-kind pr` when the current entry is `kind=story` or `kind=issue` — the verifier matches entry kind exactly (#2662).\n- ! After the PR's review cycle completes successfully, run `task plan-sequence:advance` so \"next\" resolves to the following entry (or exhausted).\n- ⊗ Treat skill-chaining or \"what's next?\" as permission to open a PR outside the current sequence entry.\n\n## Three-axis candidate validation (#4888)\n\nGitHub `mergeable_state` is **textual only**. Post-open behavioral/policy gates stay invisible until the merge-chokepoint `task check` / `deft check` runs against the current base (#4888).\n\n- ! On **conflict-resolve** and **behind-rebase** (PR open; local HEAD matches live remote PR head), MUST treat the merge-chokepoint full gate as candidate validation against current base — not optional polish. Prefer `deft check`; else tree-correct `task check` / `task deft:check`. Then MUST call `evaluateNonCascadeCandidateGreen` with an attestation from `buildCandidateValidationAttestationFromProbe` (allowlisted probe exit 0; blessed producer) keyed to `(pr_head_sha, target_head_sha)`. Fail closed names the probe.\n- ! On **pre-push**, MUST run that same merge-chokepoint full gate locally against current base before pushing. Do **not** require `evaluateNonCascadeCandidateGreen` until after push when a PR exists and local HEAD matches the live remote PR head — then obtain the SHA-pair attestation. First push (no PR yet) and tip-ahead-of-remote pushes use the local gate only (#4888).\n- ! Frame `#4883` CLEAN / forge `mergeable_state=clean` as axis-1 necessity only — never three-axis sufficiency.\n- ⊗ Skip the merge-chokepoint `task check` after conflict-resolve or behind-rebase because GitHub shows mergeable/clean (#4888).\n- ⊗ Call `evaluateNonCascadeCandidateGreen` as a pre-push blocker when no PR exists or local HEAD does not yet match the remote PR head (#4888).\n- ⊗ Satisfy semantic-drift visibility with a withdrawn Python semantic-drift script SoT (TS evaluateSemanticGreen owns the probe).\n- Depth: `scm/github.md` § Cascade / Three-axis (#4888); forge supersession `#633`/`#1517`.\n\n## Gate throughput — iteration fast lane vs merge chokepoint (#1704)\n\n> **Invariant:** every change MUST pass the full gate at least once before merge. Pre-PR is the merge chokepoint — NOT every iteration commit.\n\n- ! **Iteration lane (Phases 2–3 loop):** use affected/static gates on changed paths — `vitest run --coverage <paths>`, relevant `verify:*` on touched files, `task coverage:hotspots` — instead of full `task check` on every pre-PR iteration. Phase 3 sits inside this loop, so it uses the iteration lane, not a full suite.\n- ! **Merge chokepoint (once after the loop, before push/PR):** prefer `deft check` once before push/PR. If the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` in framework source). These are one gate, not two sequential runs. Do not add a fourth probe (#2893 / #4379). A bare `task check` miss on an include-only consumer is not \"gate unavailable\". This is a #1704 revision of the prior Phase 3 Lint exit + final confirm (two runs, one inside every iteration). The escape-rate guard below still applies; do not invent a separate surface.\n- ! **Escape-rate safety (#1703 Tier-1):** before recommending fleet-wide fast-lane tightening, cite `#1703` Tier-1 telemetry (`helped/crud-metrics.jsonl`) and `task eval:health` — do NOT invent a separate escape-rate surface.\n- ~ **In-engine incrementality (#1713):** content-hash cache + runner-delegated affected selection are sibling work (#1713).\n- ⊗ Treat Phase 3c targeted coverage alone as PR-ready without full `task check` at the merge chokepoint.\n- ⊗ Run full `task check` inside every pre-PR Phase 3 iteration — Phase 3 is inside the loop; the chokepoint is once after exit.\n\n## When to Use\n\n- ! Before pushing a branch for PR creation\n- ! After completing implementation but before the final merge-chokepoint `deft check` (#1704 / #4379)\n- ~ After addressing bot reviewer findings (run one pre-PR pass before pushing the fix batch)\n- ? During mid-implementation checkpoints on large changes\n\n## Controller invocation (#4912)\n\n! Start the prescribed pre-PR workflow through `deft pre-pr:run`. Opening this skill file is not completion. A generic mark-complete cannot mint a pass.\n\n- ! `deft pre-pr:run` starts a controller run. The run id is a lookup hint; the private store is authoritative.\n- ⊗ Treat reading this SKILL.md as pre-PR completion.\n- ⊗ Mint a passing record from an author-supplied run id, checkbox, gitignored marker, or generic mark-complete.\n- ⊗ Reuse a one-PR-unit verdict as pre-PR success.\n\nLive skip detection on deftai/directive additionally requires Limb 5 enrollment (#4976).\n\n## Loop Phases\n\nEach iteration proceeds through all phases in order. Do NOT skip phases or reorder them.\n\n### Phase 1 -- Read\n\n! Re-read each changed file end-to-end (`git diff master --name-only` to get the list).\n\n- ! Read every changed file in full -- do not skim or skip sections\n- ! Compare each file against its scope xBRIEF acceptance criteria in `xbrief/active/`\n- ~ If changed files include `xbrief/PROJECT-DEFINITION.xbrief.json`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md`, read the MAP and canonical metadata together. The MAP is orientation; `plan.architecture.codeStructure` and provider artifacts remain authoritative.\n- ! When adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing\n- ! When strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains\n- ! When adding a weaker rule (`~`, `≉`, or prose that recommends or permits a command/pattern) beside an existing `!` or `⊗` for the same command/pattern in the same file, resolve the contradiction in the same commit — weaken-beside-a-MUST is the same-commit reconcile as adding or strengthening a MUST (#4135 / #4324)\n- ~ Note any inconsistencies, missing RFC2119 markers, stale cross-references, or incomplete sections\n- ~ Check that CHANGELOG.md entries match the actual changes made\n- ! If the change alters **user-visible behavior**, apply [coding/docs.md](../../coding/docs.md) (#447): update the matching user-facing surface (CHANGELOG when user/operator-visible, CLI help / commands.md for new or changed verbs/flags, README/getting-started for install/first-run, skill/strategy triggers when entry points change) in this PR\n- ⊗ Claim documentation was updated without those files in the diff\n- ~ Pure internal refactors with no user-visible behavior change do not require user-facing doc updates\n\n### Phase 2 -- Write\n\n! Fix any issues found in the Read phase.\n\n- ! Fix inconsistencies, add missing RFC2119 enforcement markers (`!`, `~`, `⊗`)\n- ! Complete any incomplete acceptance criteria or missing content\n- ! Update stale cross-references\n- ~ Improve clarity where intent is ambiguous\n- ⊗ Make changes beyond the scope of the current task -- if you notice unrelated issues, file them as ideas or future work, do not fix them now\n\n### Phase 3 -- Lint\n\n! Run the iteration-lane gates and fix any failures (#1704). Full `task check` is the post-loop merge chokepoint, not this per-iteration phase.\n\n- ! Run affected/static gates on changed paths (`vitest run --coverage <paths>`, relevant `verify:*`, `task coverage:hotspots`) — not full `task check` inside the loop\n- ! Fix all failures before proceeding to Phase 3b\n- ~ If a lint fix requires changing a file, that counts as a change for the Loop phase\n\n~ **Windows + Grok Build (#1353):** Avoid `|`, `>`, or `2>&1` in `run_terminal_command` strings -- use Python `pathlib`/`subprocess` or plain task commands instead.\n\n### Phase 3c -- Coverage headroom (#2683 / #5421)\n\n! Before the full `task check` coverage gate, decide coverage applicability for the complete reviewed diff, then either measure headroom or record authorized not-applicable.\n\n- ! Run the shared applicability path (`deft coverage:hotspots` classifies before requiring Istanbul when the reviewed base/head/tree binding is available): **applicable** → measured path; **not-applicable** → skip channel; **refuse** → fail closed.\n- ! When applicable: run targeted coverage first: `vitest run --coverage <changed-paths>` (or language equivalent) — not only full `task check`. Then run `task coverage:hotspots` / `deft coverage:hotspots` for uncovered branches / headroom. Exercise both sides of new branches (ternary / early-return / catch / default switch / `||` / `??`). 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%). Complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573).\n- ! When not-applicable (every changed path proven inert): record `coverage_headroom` via **non-zero exit + exact skip reason** `reviewed diff has no coverable paths` (`ALLOWED_SKIP_REASONS.coverage_headroom`). The controller re-derives applicability from the run's PrePrInputBinding before honoring that skip. Hotspots exit 3 emits the machine-readable N/A artifact for this channel.\n- ! When coverage is N/A: do **not** invent `vitest --coverage`; keep applicable static / `verify:*` gates in Phase 3. Do not treat \"no coverable code\" as \"no lint obligations.\" A closed `lint_iteration` skip remains deferred.\n- ⊗ Satisfy `coverage_headroom` with an unbound exit-0 changed-file audit or any free-form exit-0 command that is not the authorized `deft coverage:hotspots` measured pass.\n- ⊗ Invent an Istanbul report, ask the operator to waive an irrelevant metric, or treat report-missing alone as not-applicable.\n- ⊗ Soften `coverage_headroom` to optional, lower the coverage floor, or claim a general docs-only CI bypass.\n- ! Toolchain-only N/A for executable changes on non-Istanbul projects (Coverlet adapters) remains open — do not paper over executable .NET with inert-classifier N/A.\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## First-PR-open closed-PR path-intersection (#1178)\n\n! Own the **first-PR-open** closed-PR path-intersection pass here (and any implement-leaf `gh pr create` bypass MUST call this same contract). Swarm Phase 6 stays merge / protected-issue / finalize and MUST point at this pre-pr owner — ⊗ treat Phase 6 as the first-open closed-PR search owner.\n\nShared retrieval tokens match article-review pre-filing (#1178): closed-PR walk uses named default `PREFILING_CLOSED_PR_WINDOW` = **100**, outcome tokens `window-exhausted` | `list-exhausted` | `cap` | `error`, and file-list pagination must complete before path-intersection.\n\n- ! Before opening a product PR, walk closed/merged PRs inside `PREFILING_CLOSED_PR_WINDOW` (`GET .../pulls?state=closed&sort=updated&direction=desc`).\n- ! For each candidate, paginate `GET .../pulls/<n>/files` to completion. If file enumeration truncates or errors, record `error` / incomplete — ⊗ path-intersect on a truncated file list as a verified clear.\n- ! Mechanical trigger: any closed/merged PR inside the window whose files intersect the candidate changed-path set → MUST cite that PR and state what differs (disposition may still be `partial` / `unresolved`; overlap alone is not duplicate-scope proof).\n- ! Record the walk outcome token. Bounded no-match requires `window-exhausted` or `list-exhausted` with complete file lists for inspected PRs.\n- ⊗ Open a product PR with no closed-PR path-intersection pass.\n- ⊗ Import #5099 feedback:file closed-walk constants for this pass unless separately exported (cite-only).\n\n## Exit Condition\n\n! Exit when a complete Read-Write-Lint-Diff cycle produces **zero changes** -- no file edits in Write, no lint fixes in Lint, and no scope issues in Diff.\n\nAfter exiting:\n- ! Run the merge chokepoint once: prefer `deft check`; if the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` in framework source). These are one gate, not two sequential runs. Do not add a fourth probe (#2893 / #4379). Phase 3 used the iteration lane, so this is the first full suite in the loop, not a second run.\n- ! If that post-loop full gate is red and the fix changes files, restart from Phase 1 (Read). Do not only re-run the gate — those edits must pass Read and Diff (#4324).\n- ! After that restart exits with zero changes, run the same tree-correct full gate once again (recovery after a red merge chokepoint).\n- ! Re-run the full gate only after a red merge chokepoint or a new commit.\n- ~ The branch is now ready for push and PR creation\n\n\n## Significant decision log (#1396)\n\n! Before push, if this PR encodes a **significant** choice not already recorded, run `task decision:write` (significance filter: architecture, product behavior, security, boundaries, data model, topology, hard-to-reverse process).\n\n~ Check `task decision:list` for related process policy so the PR does not silently reverse a dogfood decision.\n\n⊗ Invent revisit-free rationale in the PR body as a substitute for a decision record when the choice is significant.\n⊗ Noise the log with trivial scope completions.\n\nDocs: `docs/decision-log.md`.\n\n## Anti-Patterns\n\n- ⊗ Open a product PR with no closed-PR path-intersection pass inside `PREFILING_CLOSED_PR_WINDOW` (#1178)\n- ⊗ Submit a PR without running this pre-PR loop (Read-Write-Lint-Diff) -- every PR branch should pass at least one full cycle\n- ⊗ Exit the loop after the Lint phase without completing the Diff phase -- Diff catches scope creep and unintended changes that Lint cannot detect\n- ⊗ Skip the Read phase and jump directly to Lint -- Read catches semantic issues (missing content, wrong RFC2119 markers, incomplete acceptance criteria) that linters do not check\n- ⊗ Make out-of-scope fixes during Write -- this introduces scope creep that Diff will flag, forcing another iteration\n- ⊗ Ignore the iteration count -- more than 3 iterations usually indicates oscillating fixes or an unclear spec task\n- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term\n- ⊗ Add a weaker rule (`~` / `≉`) beside an existing `!` / `⊗` for the same command/pattern without reconciling in the same commit\n- ⊗ After a red post-loop `task check`, fix files and re-run only the gate without restarting Read-Write-Lint-Diff\n- ⊗ Skip `task pr:check-closing-keywords` (#737) before pushing a PR. Intent mode (#3015) also refuses bare/conditional real `Closes #N` without `--allow-close`. The negation-context substring match is the Layer 0 (prevention) gate that prevents the recurring auto-close of umbrella / staying-OPEN issues observed in #697 (closed #642), #401 (closed #642), #700 (closed #233), and #735 (closed #734) -- each incident required manual reopen and downstream cleanup. The lint's three-state exit (0 clean / 1 hits found / 2 config error) MUST be treated as a hard refusal: rewrite the PR body / commit messages until clean, OR pass `--allow-known-false-positives` ONLY for legitimately-quoted occurrences (test fixtures, documentation that discusses the trigger token literally). See `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1 for the corresponding Layer 3 (recovery) `pr:check-protected-issues` rule (#701)\n- ⊗ Invent remote PR/SHA/CI/review claims in handoff evidence without same-turn probe binding — invented-done (#3120)\n- ⊗ Fill remote ship/gate fields from memory when only local work completed; legal partial omits PR fields (#3120)\n- ⊗ Clear a failing gate by editing the gate (definition, verifier, reward, required check, coverage floor, policy, eval fixture) instead of the work under test — gate integrity (#3156); see [docs/gate-integrity.md](../../docs/gate-integrity.md)\n- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)\n- ⊗ Under a hard turn/cost budget, gold-plate pre-PR polish past the stated bar until the budget expires (#3266)\n- ⊗ Exit pre-PR after skipping deepen-for-budget without naming the skip in the summary (#3266 / #1006)\n",
+      "body": "# Deft Directive Pre-PR -- Read, Write, Lint, Diff, Loop\n\nStructured self-review loop agents run before submitting a PR. Catches inconsistencies, missing enforcement markers, incomplete acceptance criteria, scope creep, and unintended changes before they reach the reviewer.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) | [deft-directive-build](../deft-directive-build/SKILL.md) | [RWLDL tool](../../tools/RWLDL.md)\n\n> **Formerly `deft-rwldl`** -- renamed and scoped to PR readiness. For the broader iterative quality improvement loop (micro/macro review), see [tools/RWLDL.md](../../tools/RWLDL.md).\n\n## Branch-Protection Policy Guard\n\n! Before entering Phase 1 (Read), run the skill-level branch-policy guard documented in `task policy:show` / dual-invoke `deft verify:branch` (#746 / #747). Halt before any state mutation (the Phase 2 Write phase, the Phase 3 Lint phase that may touch files) when the policy is unresolvable AND no env-var bypass is active:\n\n```\ndeft verify:branch\n```\n\nor `task deft:verify:branch` when the consumer Taskfile include is present. Do not add a consumer `verify:branch` task. Pre-PR is the last gate before push, so a stale / unresolvable policy here is the highest-leverage place to catch the bug before it reaches the bot reviewer.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (per-finding decision menus in Phase 4 Diff, the Phase 5 Loop restart-vs-exit gate) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. The Discuss-pause semantic is documented verbatim there -- implicit resumption is forbidden.\n\n\n## Ordered-plan target gate (#2402)\n\n! Before opening or pushing a PR, when an ordered-plan sequence may be active, verify the work unit matches the current authorized entry:\n\n1. Resolve the current entry kind and id:\n\n```\ntask plan-sequence:current\n```\n\n   Use `task plan-sequence:current -- --json` when you need machine-readable `kind` / `id` fields from the current entry.\n\n2. Verify with the **entry kind** (not hardcoded `pr` — `story` / `issue` entries are common):\n\n```\ntask verify:plan-sequence -- --target-kind <entry-kind> --target <entry-id>\n```\n\n- ! Exit non-zero → fail closed; do not open an unauthorized PR.\n- ! Exit 0 with \"skipped (no active ordered-plan sequence)\" → proceed under normal pre-PR rules.\n- ⊗ Hardcode `--target-kind pr` when the current entry is `kind=story` or `kind=issue` — the verifier matches entry kind exactly (#2662).\n- ! After the PR's review cycle completes successfully, run `task plan-sequence:advance` so \"next\" resolves to the following entry (or exhausted).\n- ⊗ Treat skill-chaining or \"what's next?\" as permission to open a PR outside the current sequence entry.\n\n## Three-axis candidate validation (#4888)\n\nGitHub `mergeable_state` is **textual only**. Post-open behavioral/policy gates stay invisible until the merge-chokepoint `task check` / `deft check` runs against the current base (#4888).\n\n- ! On **conflict-resolve** and **behind-rebase** (PR open; local HEAD matches live remote PR head), MUST treat the merge-chokepoint full gate as candidate validation against current base — not optional polish. Prefer `deft check`; else tree-correct `task check` / `task deft:check`. Then MUST call `evaluateNonCascadeCandidateGreen` with an attestation from `buildCandidateValidationAttestationFromProbe` (allowlisted probe exit 0; blessed producer) keyed to `(pr_head_sha, target_head_sha)`. Fail closed names the probe.\n- ! On **pre-push**, MUST run that same merge-chokepoint full gate locally against current base before pushing. Do **not** require `evaluateNonCascadeCandidateGreen` until after push when a PR exists and local HEAD matches the live remote PR head — then obtain the SHA-pair attestation. First push (no PR yet) and tip-ahead-of-remote pushes use the local gate only (#4888).\n- ! Frame `#4883` CLEAN / forge `mergeable_state=clean` as axis-1 necessity only — never three-axis sufficiency.\n- ⊗ Skip the merge-chokepoint `task check` after conflict-resolve or behind-rebase because GitHub shows mergeable/clean (#4888).\n- ⊗ Call `evaluateNonCascadeCandidateGreen` as a pre-push blocker when no PR exists or local HEAD does not yet match the remote PR head (#4888).\n- ⊗ Satisfy semantic-drift visibility with a withdrawn Python semantic-drift script SoT (TS evaluateSemanticGreen owns the probe).\n- Depth: `scm/github.md` § Cascade / Three-axis (#4888); forge supersession `#633`/`#1517`.\n\n## Gate throughput — iteration fast lane vs merge chokepoint (#1704)\n\n> **Invariant:** every change MUST pass the full gate at least once before merge. Pre-PR is the merge chokepoint — NOT every iteration commit.\n\n- ! **Iteration lane (Phases 2–3 loop):** use affected/static gates on changed paths — `vitest run --coverage <paths>`, relevant `verify:*` on touched files, `task coverage:hotspots` — instead of full `task check` on every pre-PR iteration. Phase 3 sits inside this loop, so it uses the iteration lane, not a full suite.\n- ! **Merge chokepoint (once after the loop, before push/PR):** prefer `deft check` once before push/PR. If the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` in framework source). These are one gate, not two sequential runs. Do not add a fourth probe (#2893 / #4379). A bare `task check` miss on an include-only consumer is not \"gate unavailable\". This is a #1704 revision of the prior Phase 3 Lint exit + final confirm (two runs, one inside every iteration). The escape-rate guard below still applies; do not invent a separate surface.\n- ! **Escape-rate safety (#1703 Tier-1):** before recommending fleet-wide fast-lane tightening, cite `#1703` Tier-1 telemetry (`helped/crud-metrics.jsonl`) and `task eval:health` — do NOT invent a separate escape-rate surface.\n- ~ **In-engine incrementality (#1713):** content-hash cache + runner-delegated affected selection are sibling work (#1713).\n- ⊗ Treat Phase 3c targeted coverage alone as PR-ready without full `task check` at the merge chokepoint.\n- ⊗ Run full `task check` inside every pre-PR Phase 3 iteration — Phase 3 is inside the loop; the chokepoint is once after exit.\n\n## When to Use\n\n- ! Before pushing a branch for PR creation\n- ! After completing implementation but before the final merge-chokepoint `deft check` (#1704 / #4379)\n- ~ After addressing bot reviewer findings (run one pre-PR pass before pushing the fix batch)\n- ? During mid-implementation checkpoints on large changes\n\n## Controller invocation (#4912)\n\n! Start the prescribed pre-PR workflow through `deft pre-pr:run`. Opening this skill file is not completion. A generic mark-complete cannot mint a pass.\n\n- ! `deft pre-pr:run` starts a controller run. The run id is a lookup hint; the private store is authoritative.\n- ⊗ Treat reading this SKILL.md as pre-PR completion.\n- ⊗ Mint a passing record from an author-supplied run id, checkbox, gitignored marker, or generic mark-complete.\n- ⊗ Reuse a one-PR-unit verdict as pre-PR success.\n\nLive skip detection on deftai/directive additionally requires Limb 5 enrollment (#4976).\n\n## Hard local refuse before push (#5804)\n\n! On enrolled tip OVPR, feature-branch git push of product/test changes fails closed unless a private-store deft pre-pr:run pass bound to HEAD covers outgoing paths (outgoing ⊆ reviewed pushBinding). Empty pre-push stdin denies.\n\n- ! Recovery when refuse fires: deft pre-pr:run then retry push.\n- ⊗ Treat reading this SKILL.md or narrating pre-PR as a push pass.\n- ⊗ Inherit evaluatePrePush empty-stdin allow for the enrolled arm.\n\n\n## Loop Phases\n\nEach iteration proceeds through all phases in order. Do NOT skip phases or reorder them.\n\n### Phase 1 -- Read\n\n! Re-read each changed file end-to-end (`git diff master --name-only` to get the list).\n\n- ! Read every changed file in full -- do not skim or skip sections\n- ! Compare each file against its scope xBRIEF acceptance criteria in `xbrief/active/`\n- ~ If changed files include `xbrief/PROJECT-DEFINITION.xbrief.json`, a configured `codebase-map` provider artifact, or `.planning/codebase/MAP.md`, read the MAP and canonical metadata together. The MAP is orientation; `plan.architecture.codeStructure` and provider artifacts remain authoritative.\n- ! When adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing\n- ! When strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains\n- ! When adding a weaker rule (`~`, `≉`, or prose that recommends or permits a command/pattern) beside an existing `!` or `⊗` for the same command/pattern in the same file, resolve the contradiction in the same commit — weaken-beside-a-MUST is the same-commit reconcile as adding or strengthening a MUST (#4135 / #4324)\n- ~ Note any inconsistencies, missing RFC2119 markers, stale cross-references, or incomplete sections\n- ~ Check that CHANGELOG.md entries match the actual changes made\n- ! If the change alters **user-visible behavior**, apply [coding/docs.md](../../coding/docs.md) (#447): update the matching user-facing surface (CHANGELOG when user/operator-visible, CLI help / commands.md for new or changed verbs/flags, README/getting-started for install/first-run, skill/strategy triggers when entry points change) in this PR\n- ⊗ Claim documentation was updated without those files in the diff\n- ~ Pure internal refactors with no user-visible behavior change do not require user-facing doc updates\n\n### Phase 2 -- Write\n\n! Fix any issues found in the Read phase.\n\n- ! Fix inconsistencies, add missing RFC2119 enforcement markers (`!`, `~`, `⊗`)\n- ! Complete any incomplete acceptance criteria or missing content\n- ! Update stale cross-references\n- ~ Improve clarity where intent is ambiguous\n- ⊗ Make changes beyond the scope of the current task -- if you notice unrelated issues, file them as ideas or future work, do not fix them now\n\n### Phase 3 -- Lint\n\n! Run the iteration-lane gates and fix any failures (#1704). Full `task check` is the post-loop merge chokepoint, not this per-iteration phase.\n\n- ! Run affected/static gates on changed paths (`vitest run --coverage <paths>`, relevant `verify:*`, `task coverage:hotspots`) — not full `task check` inside the loop\n- ! Fix all failures before proceeding to Phase 3b\n- ~ If a lint fix requires changing a file, that counts as a change for the Loop phase\n\n~ **Windows + Grok Build (#1353):** Avoid `|`, `>`, or `2>&1` in `run_terminal_command` strings -- use Python `pathlib`/`subprocess` or plain task commands instead.\n\n### Phase 3c -- Coverage headroom (#2683 / #5421)\n\n! Before the full `task check` coverage gate, decide coverage applicability for the complete reviewed diff, then either measure headroom or record authorized not-applicable.\n\n- ! Run the shared applicability path (`deft coverage:hotspots` classifies before requiring Istanbul when the reviewed base/head/tree binding is available): **applicable** → measured path; **not-applicable** → inert skip channel; **coverageMode posture** (`initial`|`disabled`, exit 5) → mode skip channel (paths may still be coverable; authority is plan.policy.coverageMode); **refuse** → fail closed (or waived exit 4 when granted).\n- ! When applicable: run targeted coverage first: `vitest run --coverage <changed-paths>` (or language equivalent) — not only full `task check`. Then run `task coverage:hotspots` / `deft coverage:hotspots` for uncovered branches / headroom. Exercise both sides of new branches (ternary / early-return / catch / default switch / `||` / `??`). 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%). Complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573).\n- ! When coverageMode is `initial` or `disabled` and no `coverage/coverage-final.json` is present: record `coverage_headroom` via **exit 5 + exact skip reason** `coverageMode posture skip (initial|disabled)` (`COVERAGE_HEADROOM_MODE_SKIP`). This is posture N/A — distinct from inert N/A and from forbidden report-missing-alone. The controller re-reads effective coverageMode at observe and commandSatisfied; hotspots exit 5 self-instructs the token and carries it on the mode artifact. When a coverage report exists, keep the measured path (report-present guard).\n- ! When not-applicable (every changed path proven inert): record `coverage_headroom` via **non-zero exit + exact skip reason** `reviewed diff has no coverable paths` (`ALLOWED_SKIP_REASONS.coverage_headroom`). The controller re-derives applicability from the run's PrePrInputBinding before honoring that skip. Hotspots exit 3 emits the machine-readable N/A artifact for this channel.\n- ! When coverageMode is `initial` or `disabled` and no `coverage/coverage-final.json` is present: record `lint_iteration` via **exit 5 + exact skip reason** `lint_iteration coverageMode posture skip (initial|disabled)` (`LINT_ITERATION_MODE_SKIP`). This discharges the Vitest-shaped observation only — keep applicable static / `verify:*` gates in Phase 3 and the merge_chokepoint phase. Do **not** invent `vitest --coverage`. The controller re-reads coverageMode at observe and commandSatisfied; refuse the mode skip when a coverage report exists (shared report-present guard with #5791). Never exit 0 and never bare any-nonzero for this channel.\n- ⊗ Satisfy `coverage_headroom` with an unbound exit-0 changed-file audit or any free-form exit-0 command that is not the authorized `deft coverage:hotspots` measured pass.\n- ⊗ Invent an Istanbul report, ask the operator to waive an irrelevant metric, or treat report-missing alone as not-applicable (mode posture skip requires coverageMode initial|disabled + exit 5 token — not a free-form missing-report claim).\n- ⊗ Soften `coverage_headroom` to optional, lower the coverage floor, or claim a general docs-only CI bypass.\n- ! Toolchain-only N/A for executable changes on non-Istanbul projects (Coverlet adapters) remains open — do not paper over executable .NET with inert-classifier N/A.\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## First-PR-open closed-PR path-intersection (#1178)\n\n! Own the **first-PR-open** closed-PR path-intersection pass here (and any implement-leaf `gh pr create` bypass MUST call this same contract). Swarm Phase 6 stays merge / protected-issue / finalize and MUST point at this pre-pr owner — ⊗ treat Phase 6 as the first-open closed-PR search owner.\n\nShared retrieval tokens match article-review pre-filing (#1178): closed-PR walk uses named default `PREFILING_CLOSED_PR_WINDOW` = **100**, outcome tokens `window-exhausted` | `list-exhausted` | `cap` | `error`, and file-list pagination must complete before path-intersection.\n\n- ! Before opening a product PR, walk closed/merged PRs inside `PREFILING_CLOSED_PR_WINDOW` (`GET .../pulls?state=closed&sort=updated&direction=desc`).\n- ! For each candidate, paginate `GET .../pulls/<n>/files` to completion. If file enumeration truncates or errors, record `error` / incomplete — ⊗ path-intersect on a truncated file list as a verified clear.\n- ! Mechanical trigger: any closed/merged PR inside the window whose files intersect the candidate changed-path set → MUST cite that PR and state what differs (disposition may still be `partial` / `unresolved`; overlap alone is not duplicate-scope proof).\n- ! Record the walk outcome token. Bounded no-match requires `window-exhausted` or `list-exhausted` with complete file lists for inspected PRs.\n- ⊗ Open a product PR with no closed-PR path-intersection pass.\n- ⊗ Import #5099 feedback:file closed-walk constants for this pass unless separately exported (cite-only).\n\n## Exit Condition\n\n! Exit when a complete Read-Write-Lint-Diff cycle produces **zero changes** -- no file edits in Write, no lint fixes in Lint, and no scope issues in Diff.\n\nAfter exiting:\n- ! Run the merge chokepoint once: prefer `deft check`; if the CLI is missing, use the tree-correct task form (`task deft:check` on include-only consumers; `task check` in framework source). These are one gate, not two sequential runs. Do not add a fourth probe (#2893 / #4379). Phase 3 used the iteration lane, so this is the first full suite in the loop, not a second run.\n- ! If that post-loop full gate is red and the fix changes files, restart from Phase 1 (Read). Do not only re-run the gate — those edits must pass Read and Diff (#4324).\n- ! After that restart exits with zero changes, run the same tree-correct full gate once again (recovery after a red merge chokepoint).\n- ! Re-run the full gate only after a red merge chokepoint or a new commit.\n- ~ The branch is now ready for push and PR creation\n\n\n## Significant decision log (#1396)\n\n! Before push, if this PR encodes a **significant** choice not already recorded, run `task decision:write` (significance filter: architecture, product behavior, security, boundaries, data model, topology, hard-to-reverse process).\n\n~ Check `task decision:list` for related process policy so the PR does not silently reverse a dogfood decision.\n\n⊗ Invent revisit-free rationale in the PR body as a substitute for a decision record when the choice is significant.\n⊗ Noise the log with trivial scope completions.\n\nDocs: `docs/decision-log.md`.\n\n## Anti-Patterns\n\n- ⊗ Open a product PR with no closed-PR path-intersection pass inside `PREFILING_CLOSED_PR_WINDOW` (#1178)\n- ⊗ Submit a PR without running this pre-PR loop (Read-Write-Lint-Diff) -- every PR branch should pass at least one full cycle\n- ⊗ Exit the loop after the Lint phase without completing the Diff phase -- Diff catches scope creep and unintended changes that Lint cannot detect\n- ⊗ Skip the Read phase and jump directly to Lint -- Read catches semantic issues (missing content, wrong RFC2119 markers, incomplete acceptance criteria) that linters do not check\n- ⊗ Make out-of-scope fixes during Write -- this introduces scope creep that Diff will flag, forcing another iteration\n- ⊗ Ignore the iteration count -- more than 3 iterations usually indicates oscillating fixes or an unclear spec task\n- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term\n- ⊗ Add a weaker rule (`~` / `≉`) beside an existing `!` / `⊗` for the same command/pattern without reconciling in the same commit\n- ⊗ After a red post-loop `task check`, fix files and re-run only the gate without restarting Read-Write-Lint-Diff\n- ⊗ Skip `task pr:check-closing-keywords` (#737) before pushing a PR. Intent mode (#3015) also refuses bare/conditional real `Closes #N` without `--allow-close`. The negation-context substring match is the Layer 0 (prevention) gate that prevents the recurring auto-close of umbrella / staying-OPEN issues observed in #697 (closed #642), #401 (closed #642), #700 (closed #233), and #735 (closed #734) -- each incident required manual reopen and downstream cleanup. The lint's three-state exit (0 clean / 1 hits found / 2 config error) MUST be treated as a hard refusal: rewrite the PR body / commit messages until clean, OR pass `--allow-known-false-positives` ONLY for legitimately-quoted occurrences (test fixtures, documentation that discusses the trigger token literally). See `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1 for the corresponding Layer 3 (recovery) `pr:check-protected-issues` rule (#701)\n- ⊗ Invent remote PR/SHA/CI/review claims in handoff evidence without same-turn probe binding — invented-done (#3120)\n- ⊗ Fill remote ship/gate fields from memory when only local work completed; legal partial omits PR fields (#3120)\n- ⊗ Clear a failing gate by editing the gate (definition, verifier, reward, required check, coverage floor, policy, eval fixture) instead of the work under test — gate integrity (#3156); see [docs/gate-integrity.md](../../docs/gate-integrity.md)\n- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)\n- ⊗ Under a hard turn/cost budget, gold-plate pre-PR polish past the stated bar until the budget expires (#3266)\n- ⊗ Exit pre-PR after skipping deepen-for-budget without naming the skip in the summary (#3266 / #1006)\n",
       "frontmatter_extra": null
     },
     {

package/skills/deft-directive-pre-pr/SKILL.md

@@ -101,6 +101,15 @@ GitHub `mergeable_state` is **textual only**. Post-open behavioral/policy gates
 
 Live skip detection on deftai/directive additionally requires Limb 5 enrollment (#4976).
 
+## Hard local refuse before push (#5804)
+
+! On enrolled tip OVPR, feature-branch git push of product/test changes fails closed unless a private-store deft pre-pr:run pass bound to HEAD covers outgoing paths (outgoing ⊆ reviewed pushBinding). Empty pre-push stdin denies.
+
+- ! Recovery when refuse fires: deft pre-pr:run then retry push.
+- ⊗ Treat reading this SKILL.md or narrating pre-PR as a push pass.
+- ⊗ Inherit evaluatePrePush empty-stdin allow for the enrolled arm.
+
+
 ## Loop Phases
 
 Each iteration proceeds through all phases in order. Do NOT skip phases or reorder them.
@@ -145,12 +154,13 @@ Each iteration proceeds through all phases in order. Do NOT skip phases or reord
 
 ! Before the full `task check` coverage gate, decide coverage applicability for the complete reviewed diff, then either measure headroom or record authorized not-applicable.
 
-- ! Run the shared applicability path (`deft coverage:hotspots` classifies before requiring Istanbul when the reviewed base/head/tree binding is available): **applicable** → measured path; **not-applicable** → skip channel; **refuse** → fail closed.
+- ! Run the shared applicability path (`deft coverage:hotspots` classifies before requiring Istanbul when the reviewed base/head/tree binding is available): **applicable** → measured path; **not-applicable** → inert skip channel; **coverageMode posture** (`initial`|`disabled`, exit 5) → mode skip channel (paths may still be coverable; authority is plan.policy.coverageMode); **refuse** → fail closed (or waived exit 4 when granted).
 - ! When applicable: run targeted coverage first: `vitest run --coverage <changed-paths>` (or language equivalent) — not only full `task check`. Then run `task coverage:hotspots` / `deft coverage:hotspots` for uncovered branches / headroom. Exercise both sides of new branches (ternary / early-return / catch / default switch / `||` / `??`). 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%). Complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573).
+- ! When coverageMode is `initial` or `disabled` and no `coverage/coverage-final.json` is present: record `coverage_headroom` via **exit 5 + exact skip reason** `coverageMode posture skip (initial|disabled)` (`COVERAGE_HEADROOM_MODE_SKIP`). This is posture N/A — distinct from inert N/A and from forbidden report-missing-alone. The controller re-reads effective coverageMode at observe and commandSatisfied; hotspots exit 5 self-instructs the token and carries it on the mode artifact. When a coverage report exists, keep the measured path (report-present guard).
 - ! When not-applicable (every changed path proven inert): record `coverage_headroom` via **non-zero exit + exact skip reason** `reviewed diff has no coverable paths` (`ALLOWED_SKIP_REASONS.coverage_headroom`). The controller re-derives applicability from the run's PrePrInputBinding before honoring that skip. Hotspots exit 3 emits the machine-readable N/A artifact for this channel.
-- ! When coverage is N/A: do **not** invent `vitest --coverage`; keep applicable static / `verify:*` gates in Phase 3. Do not treat "no coverable code" as "no lint obligations." A closed `lint_iteration` skip remains deferred.
+- ! When coverageMode is `initial` or `disabled` and no `coverage/coverage-final.json` is present: record `lint_iteration` via **exit 5 + exact skip reason** `lint_iteration coverageMode posture skip (initial|disabled)` (`LINT_ITERATION_MODE_SKIP`). This discharges the Vitest-shaped observation only — keep applicable static / `verify:*` gates in Phase 3 and the merge_chokepoint phase. Do **not** invent `vitest --coverage`. The controller re-reads coverageMode at observe and commandSatisfied; refuse the mode skip when a coverage report exists (shared report-present guard with #5791). Never exit 0 and never bare any-nonzero for this channel.
 - ⊗ Satisfy `coverage_headroom` with an unbound exit-0 changed-file audit or any free-form exit-0 command that is not the authorized `deft coverage:hotspots` measured pass.
-- ⊗ Invent an Istanbul report, ask the operator to waive an irrelevant metric, or treat report-missing alone as not-applicable.
+- ⊗ Invent an Istanbul report, ask the operator to waive an irrelevant metric, or treat report-missing alone as not-applicable (mode posture skip requires coverageMode initial|disabled + exit 5 token — not a free-form missing-report claim).
 - ⊗ Soften `coverage_headroom` to optional, lower the coverage floor, or claim a general docs-only CI bypass.
 - ! Toolchain-only N/A for executable changes on non-Istanbul projects (Coverlet adapters) remains open — do not paper over executable .NET with inert-classifier N/A.
 

package/tasks/agent.yml

@@ -7,8 +7,6 @@ tasks:
   monitor:
     desc: "Sub-agent heartbeat sweep (#1365 / #2824). Three-state exit (0 ok / 1 stale-or-malformed / 2 config). Alias for the raw subagent-monitor engine."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/cache.yml

@@ -31,8 +31,6 @@ tasks:
   put:
     desc: "Cache an entry -- task cache:put -- <source> <key> --raw-file PATH [--ttl-seconds N]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -41,8 +39,6 @@ tasks:
   get:
     desc: "Read an entry -- task cache:get -- <source> <key> [--allow-stale | --no-stale]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -51,8 +47,6 @@ tasks:
   invalidate:
     desc: "Drop an entry -- task cache:invalidate -- <source> <key> [--reason TEXT]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -61,8 +55,6 @@ tasks:
   fetch-all:
     desc: "Bulk populate -- task cache:fetch-all -- --source github-issue --repo OWNER/NAME [--batch-size N] [--delay-ms N] [--ttl-seconds N] [--no-refresh-closed to skip open→closed reconcile]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -71,8 +63,6 @@ tasks:
   prune:
     desc: "Drop expired or LRU-evict -- task cache:prune -- [--older-than-days 30] [--source github-issue] [--dry-run] [--to-cap]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -82,8 +72,6 @@ tasks:
   archive-closed:
     desc: "Reversible archive of closed github-issue cache entries (#1137). -- task triage:cache-archive -- [--dry-run] [--older-than-days 30] [--repo OWNER/NAME] [--json]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -92,8 +80,6 @@ tasks:
   archive-list:
     desc: "List archived github-issue cache entries (#1137). -- task triage:archive-list -- [--repo OWNER/NAME] [--format=json] [--since ISO] [--limit N]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -102,8 +88,6 @@ tasks:
   restore-from-archive:
     desc: "Restore archived github-issue entry to live cache (#1137). -- task triage:restore-from-archive -- --issue N [--repo OWNER/NAME] [--force]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/capacity.yml

@@ -24,8 +24,6 @@ tasks:
   show:
     desc: "Capacity allocation target-vs-actual mix (advisory, offline). task capacity:show [-- --project-root <path>]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -34,8 +32,6 @@ tasks:
   backfill:
     desc: "One-time capacity-bucket backfill for completed vBRIEFs (#1606): infer capacityBucket from origin-issue labels + stamp completedAt from git. Dry-run by default; idempotent; never touches cost. -- task capacity:backfill [-- --apply] [--window-only] [--cache-dir <path>] [--json]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/change.yml

@@ -11,8 +11,6 @@ tasks:
   changelog:check:
     desc: Verify CHANGELOG.md has an [Unreleased] section with at least one entry
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -21,8 +19,6 @@ tasks:
   change:init:
     desc: Create a new change proposal directory structure in history/changes/<name>/
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/codebase.yml

@@ -9,8 +9,6 @@ tasks:
     dir: '{{.USER_WORKING_DIR}}'
     # Per conventions/task-caching.md: no sources/generates because this task
     # forwards user-supplied paths and project-root flags via CLI_ARGS.
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -19,8 +17,6 @@ tasks:
   extract-default:
     desc: "Emit the dependency-free default codebase-map artifact to stdout (#1595 PR3)."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -29,8 +25,6 @@ tasks:
   provider-map:
     desc: "Select an external codebase-map provider or fall back to the default artifact (#1595 PR3)."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -39,8 +33,6 @@ tasks:
   map:
     desc: "Generate .planning/codebase/MAP.md from the selected codebase-map artifact (#1595 PR4)."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -49,8 +41,6 @@ tasks:
   projection-registry:
     desc: "Inspect registered codebase projection kinds (#1595 PR3)."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/commit.yml

@@ -11,8 +11,6 @@ tasks:
   commit:lint:
     desc: Validate HEAD commit message against conventional commit format
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/coverage.yml

@@ -7,8 +7,6 @@ tasks:
   hotspots:
     desc: "Coverage hotspots + branch headroom gate (#2683): read coverage/coverage-final.json, compare global metrics to project vitest thresholds, fail closed below floor or below configured headroom (default 0.3pp), and list lowest modules plus uncovered branch samples for git-diff paths (override with --path). Supports --json for agents."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/decision.yml

@@ -12,8 +12,6 @@ tasks:
   write:
     desc: "Write a lightweight structured decision record (#1396). -- task decision:write -- [--decision TEXT] [--governing-rule ...] [--alternative ...] [--why-winner ...] [--confidence low|medium|high] [--revisit-trigger ...] [--scope PATH] [--body-file PATH] [--json] [--dry-run]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -22,8 +20,6 @@ tasks:
   list:
     desc: "List structured decision records under xbrief/decisions/ (#1396). -- task decision:list -- [--query TEXT] [--scope PATH] [--issue N] [--limit N] [--json]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/directive.yml

@@ -14,7 +14,6 @@ vars:
 tasks:
   finish-loop:
     desc: "Outer walk-away cascade: finish-loop grant gate + queue scan + progress JSONL + optional pr:finish-loop; agent owns implement steps (#871)"
-    deps: [":engine:_ts-build"]
     dir: '{{.USER_WORKING_DIR}}'
     cmds:
       - task: :engine:invoke

package/tasks/docs.yml

@@ -22,8 +22,6 @@ tasks:
   rule-map:
     desc: "Build the maintainer Rule Map (docs/RULE-MAP.md + gitignored docs/rule-map/index.html)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -32,8 +30,6 @@ tasks:
   rule-map:check:
     desc: "Fail if committed docs/RULE-MAP.md is out of date (for CI / pre-commit gating)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -42,15 +38,15 @@ tasks:
   capability-map:
     desc: "Generate content/docs/capabilities.md from the capability overlay (#4099)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/core/dist/docs/capability-map.js" --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'capability-map --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   capability-map:check:
     desc: "Fail if committed content/docs/capabilities.md is stale or the overlay disagrees with registries (#4099)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/core/dist/docs/capability-map.js" --project-root "{{.USER_WORKING_DIR}}" --check
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'capability-map --project-root "{{.USER_WORKING_DIR}}" --check'

package/tasks/engine-invoke.cjs

@@ -23,6 +23,11 @@ const CONTENT_PACKAGE_NAME = "@deftai/directive-content";
 /** Single remediation when a deposit has no global CLI (#3324 / #3265). */
 const DEPOSIT_REMEDIATION = "npm i -g @deftai/directive";
 const SOURCE_BUILD_REMEDIATION = "task build";
+/** Missing checkout pin remediation (#5805 Prefer-A Bound P1). */
+const PIN_INSTALL_REMEDIATION =
+  "npm i -g @deftai/directive, then directive install --repair (or package-manager install of @deftai/directive-runtime)";
+const PIN_MATERIALIZE_REMEDIATION = "task materialize:runtime";
+const PIN_BIN_REL = path.join("node_modules", "@deftai", "directive-runtime", "dist", "bin.js");
 
 /**
  * cmd.exe command separators / metacharacters. Free-text DEFT_ENGINE_CMD_JSON
@@ -156,6 +161,63 @@ function hasConsumerDepositMarker(root, opts = {}) {
  * @param {string} root
  * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
  */
+
+/**
+ * Absolute path of the checkout-local pin binary (AC9.9 / #5805).
+ * @param {string} projectRoot
+ * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
+ */
+function resolveFrameworkPinBin(projectRoot, opts = {}) {
+  const pathMod = opts.path || path;
+  if (!projectRoot) return "";
+  return pathMod.join(projectRoot, "node_modules", "@deftai", "directive-runtime", "dist", "bin.js");
+}
+
+/**
+ * True when the checkout-local pin binary exists.
+ * @param {string} projectRoot
+ * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
+ */
+function hasFrameworkPinBin(projectRoot, opts = {}) {
+  const io = opts.fs || fs;
+  const pin = resolveFrameworkPinBin(projectRoot, opts);
+  if (!pin) return false;
+  try {
+    return io.existsSync(pin);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Framework-source ordinary invoke: pin exclusive, fail closed when missing (#5805).
+ * Deposit / non-buildable keep prior hasBin → vendored / global behavior.
+ * @param {{
+ *   hasBin: boolean,
+ *   isBuildableSource: boolean,
+ *   hasPinBin: boolean,
+ *   isRuntimeVerb?: boolean,
+ *   hasGlobalCli?: boolean,
+ * }} input
+ */
+function resolveFrameworkSourceInvoke(input) {
+  if (!input.isBuildableSource) {
+    return resolveInvokeDispatch({
+      hasBin: input.hasBin,
+      isBuildableSource: false,
+      isRuntimeVerb: Boolean(input.isRuntimeVerb),
+      hasGlobalCli: Boolean(input.hasGlobalCli),
+    });
+  }
+  if (input.hasPinBin) {
+    return { action: "vendored", binKind: "pin" };
+  }
+  return {
+    action: "fail-closed",
+    remediations: [PIN_INSTALL_REMEDIATION, PIN_MATERIALIZE_REMEDIATION],
+    exitCode: 2,
+  };
+}
 function isBuildableSource(root, opts = {}) {
   if (hasConsumerDepositMarker(root, opts)) {
     return false;
@@ -337,6 +399,18 @@ if (require.main === module) {
   if (mode === "is-buildable-source") {
     process.exit(isBuildableSource(process.argv[3] || "") ? 0 : 1);
   }
+  if (mode === "pin-bin") {
+    const root = process.argv[3] || "";
+    const pin = resolveFrameworkPinBin(root);
+    if (hasFrameworkPinBin(root)) {
+      process.stdout.write(pin);
+      process.exit(0);
+    }
+    console.error("deft: missing checkout pin " + pin);
+    console.error("  Recovery: " + PIN_INSTALL_REMEDIATION);
+    console.error("  Or tip dogfood: " + PIN_MATERIALIZE_REMEDIATION);
+    process.exit(2);
+  }
   main();
 }
 
@@ -349,9 +423,14 @@ module.exports = {
   isVendoredCoreRoot,
   isBuildableSource,
   resolveInvokeDispatch,
+  resolveFrameworkPinBin,
+  hasFrameworkPinBin,
+  resolveFrameworkSourceInvoke,
   CONSUMER_DEPOSIT_FIELD,
   CONSUMER_DEPOSIT_MARKER_FILE,
   CONTENT_PACKAGE_NAME,
   DEPOSIT_REMEDIATION,
   SOURCE_BUILD_REMEDIATION,
+  PIN_INSTALL_REMEDIATION,
+  PIN_MATERIALIZE_REMEDIATION,
 };