@deftai/directive-content 0.107.0 → 0.109.0

package/docs/consumer-check-contract.md

@@ -39,6 +39,41 @@ A **partial local** root check aggregate still fails closed — the include must
 
 Root cause of red `greenfield-python-free-smoke` after #3145: the gate only inspected the root Taskfile, treated include-only greenfield as “no check composition,” and hard-failed (`exit 201` via #3188). That was a **gate false positive** for the intentional deposit shape, not a missing deposit wiring bug.
 
+## Merge-chokepoint gate scoping (#3893)
+
+Some gates are repo-wide by default and must be **narrowed** when composed on a
+merge chokepoint. `verify:orphan-active` is the first: composed unscoped it
+fails a candidate for lifecycle residue another merge stranded, and N stranded
+briefs make N single-brief lifecycle PRs mutually unmergeable.
+
+The contract therefore records a required argument per gate
+(`MERGE_CHOKEPOINT_SCOPED_GATE_ARGS`) and reports a check aggregate that lists
+the gate without it:
+
+```yaml
+  check:consumer:
+    deps:
+      - task: verify:orphan-active
+        vars:
+          CLI_ARGS: "--changed-only"
+```
+
+The check reads the dependency's effective `CLI_ARGS` value, not the raw entry
+text, so the flag appearing in a comment, a sibling variable, or a descriptive
+value does not satisfy it.
+
+- **`--framework-source`: fail closed.** This repo owns its own composition, so
+  a regression to the unscoped form is a hard failure here.
+- **Consumer deposits: warn.** `deft update` re-deposits the Taskfile; the
+  warning names the exact one-line repair in the meantime.
+- **Aggregates that do not list the gate are silent.** Include-only greenfield
+  roots and orchestrator-body `check` tasks are unaffected.
+
+This is a strengthening, not a relaxation: nothing about the detector, the
+required-gate set, or any exit code is weakened. Repo-wide residue truth still
+runs on the bare verb, at the delivery tip, and on the after-merge
+`verify:orphan-active -- --issue N` DONE gate (#3429).
+
 ## Repair path
 
 1. Restore deposit Taskfiles: `deft update` (includes `tasks/verify.yml` under `.deft/core/`)

package/docs/delivery-attempt.md

@@ -34,6 +34,8 @@ MUST evaluate this gate before automatic retry or re-dispatch.
 | `BLOCK_ELAPSED_BUDGET` | Wall-clock budget exhausted |
 | `BLOCK_TOOL_OR_TOKEN_BUDGET` | Tool-call (or host-token when telemetried) budget exhausted |
 
+evaluateInFlight(ledger, input) applies the same elapsed budget to a run that is already queued or running. Pre-dispatch never sees that case: an active attempt is DENY_DUPLICATE_ACTIVE. In-flight elapsed is totalElapsedSeconds plus wall-clock since startedAt. Under budget returns ALLOW_RESUME. Exhausted returns BLOCK_ELAPSED_BUDGET. No second budget store.
+
 Once a **block** decision is emitted, automatic re-dispatch MUST stop until a
 declared resume condition is satisfied or an audited operator override is
 recorded. Persist the terminal handoff (`buildTerminalHandoff` /
@@ -102,7 +104,8 @@ task swarm:pre-dispatch -- --scope-id <story|issue|xbrief-id> --target-id <workt
 Default unit key: `scopeId` + `targetId` + `workflowId=drive-to:merge-ready`.
 Actions: `begin` (default), `complete` (`--status succeeded|failed|cancelled|blocked`), `cancel` (takeover step 1).
 Monitors MUST run begin before any peer implement spawn; spawn only on exit 0.
-Takeover: cancel prior attempt, then begin again — never concurrent dual active.
+Takeover after REDISPATCH_OK: cancel prior attempt, then begin again — never concurrent dual active.
+A killed worker stays `queued`/`running` until cancel; REDISPATCH_OK does not lift `DENY_DUPLICATE_ACTIVE` (#3730).
 Implementation: `packages/core/src/swarm/pre-dispatch.ts` + `task swarm:pre-dispatch`.
 
 ## Skill routing

package/docs/freshness-contract.md

@@ -35,10 +35,15 @@ When a mutation `session:start` (cold or re-arm) loads payload surfaces into
 runtime context, it binds the live generation:
 
 ```text
-.deft/session-binds/<safe-session-id>.json   # multi-agent isolation (preferred)
+.deft/session-binds/<sha256-slice>.json      # multi-agent isolation (preferred)
 .deft/session-bind.json                      # default / last-bind convenience
 ```
 
+The per-session record is named by a 24-hex SHA-256 slice of the session id, so
+a directory listing carries no fragment of the id (#3768). Records written
+before that rename also carried a 32-character id prefix; they are read-accepted
+until the next bind supersedes them.
+
 Multi-agent hosts **must** pin session identity so one session cannot certify
 another as current:
 

package/docs/gate-integrity.md

@@ -1,3 +1,4 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/docs/gate-integrity.md" -->
 # Gate integrity — a failing gate must not be fixed by editing the gate (#3156)
 
 General product and process rule for Directive fix loops, refine loops, and quality-gate repair: **when a gate is red, clear red by fixing the work under test — not by mutating the gate.**
@@ -80,7 +81,7 @@ Field notes and parent framing: issue [#3156](https://github.com/deftai/directiv
 ## Discoverability
 
 - Pre-PR Diff phase checklist: [deft-directive-pre-pr](../skills/deft-directive-pre-pr/SKILL.md) (gate-integrity bullet).
-- Stance / propose-not-apply: [main.md § Self-Improving, Not Self-Editing (#3164)](../../main.md#self-improving-not-self-editing-3164), [philosophy.md](../meta/philosophy.md).
+- Stance / propose-not-apply: [main.md § Self-Improving, Not Self-Editing (#3164)](../main.md#self-improving-not-self-editing-3164), [philosophy.md](../meta/philosophy.md).
 - Verification outcomes: [verification.md](../verification/verification.md).
 - Goal/gate rigidity: [goal-gate-determinism.md](../patterns/goal-gate-determinism.md) (#852).
 - Scope self-auth instance: [scope-provenance.md](./scope-provenance.md) (#3145).
@@ -94,13 +95,27 @@ Full CI automation that blocks “diff touches a gate that just failed” withou
 | Topic | Where |
 |-------|--------|
 | Parent epic | [#3179](https://github.com/deftai/directive/issues/3179) |
-| Stance (propose-not-apply) | [#3164](https://github.com/deftai/directive/issues/3164), [main.md](../../main.md#self-improving-not-self-editing-3164) |
+| Stance (propose-not-apply) | [#3164](https://github.com/deftai/directive/issues/3164), [main.md](../main.md#self-improving-not-self-editing-3164) |
 | Refine-internal SkillOpt | [#2436](https://github.com/deftai/directive/issues/2436) |
 | Fixed evaluator / agent-loop | [#782](https://github.com/deftai/directive/issues/782) |
 | Verification independence | [#1499](https://github.com/deftai/directive/issues/1499) |
 | Scope self-authorization | [#3145](https://github.com/deftai/directive/issues/3145), [scope-provenance.md](./scope-provenance.md) |
 | Host self-mutate honesty | [#3162](https://github.com/deftai/directive/issues/3162), [host-surface-assumptions.md](./host-surface-assumptions.md) |
 | Safety via formal gates | [#1200](https://github.com/deftai/directive/issues/1200) |
+| Poisoned product-oracle history from a safety refusal | [#3615](https://github.com/deftai/directive/issues/3615), this page § Product-oracle history poisoned by a safety refusal |
+
+---
+
+## Product-oracle history poisoned by a safety refusal (#3615)
+
+A safety-refused acceptance command is not a product measurement. `verify:ac` keeps the acceptance gate red, and it does not write `verification.outcome=fail` for an all-refused walk. A mixed walk that still has a refusal does not write a product-oracle pass.
+
+Records already written still pair on `session_id` + `check_id`. A correct classifier going forward does not unwrite a `fail` already on disk. Recovery is an operator workaround, not independent re-derivation:
+
+1. Start a new Deft session (new `DEFT_SESSION_ID`) so the integrity layer does not pair against the poisoned fail, or
+2. Truncate or delete the run-summary JSONL (default `.deft-run-summary.json`, typically gitignored).
+
+⊗ Set `independent_rederivation=true` to clear this class. That flag asserts both sides were rebuilt from scratch. The refused side never executed.
 
 ---
 

package/docs/getting-started.md

@@ -16,21 +16,18 @@ Before the mechanics below, it helps to see the whole loop. Directive is two con
 
 ## Prerequisites
 
-- **Node 20+** and **pnpm** for live gates and the npm distribution channel (see `.nvmrc` in the framework payload).
+- **Node 20+** and the package manager declared by the project (`npm` or `pnpm`) for live consumer gates and the npm distribution channel (see `.nvmrc` in the framework payload). npm is bundled with Node; a pnpm-pinned project enables pnpm through Corepack.
+- **Git** and **GitHub CLI (`gh`)** are also checked by the consumer toolchain gate.
 - **Go 1.22+** only if you use the bootstrap Go installer or build from source.
-- **Python 3.11+**, **uv**, **task**, **git**, and **gh** for full framework workflows — run `directive toolchain:check` (or `deft toolchain:check`) after install.
+- **Python 3.11+**, **uv**, and **task** for the framework-maintainer and session workflows that name them. The consumer toolchain probe itself does not check those tools. Run `directive toolchain:check --consumer --project-root .` after install.
 
 ---
 
 ## Installation
 
-### npm (coming soon — not yet published)
+### npm (canonical)
 
-> ⚠️ **The `@deftai/directive` npm package is not yet published** to the registry (provisioning tracked by [#1909](https://github.com/deftai/directive/issues/1909)). **Until it goes live, install via the [Go installer](#go-installer-bootstrap) below.** The commands shown here are what the install will become once the package is published.
-
-<!-- TODO(#1909): flip to npm-canonical and remove this "coming soon" notice when @deftai/directive is published -->
-
-Once published, when Node is already available you will install Directive globally:
+With Node already available, install Directive globally from npm:
 
 ```bash
 npm i -g @deftai/directive
@@ -38,16 +35,18 @@ directive --version    # primary command
 deft --version         # alias — same binary
 ```
 
-One-shot without a global install (also once published):
+One-shot without a global install:
 
 ```bash
 npx @deftai/directive doctor
 npx @deftai/directive session:start
 ```
 
-This npm path is the emerging primary distribution channel under `@deftai/directive` ([#11](https://github.com/deftai/directive/issues/11)); the Go installer below remains the install/bootstrap option today and during the staged retire window.
+This npm path has been the canonical distribution channel since v0.55.1. A pnpm-managed repository can install the same package with `pnpm add -g @deftai/directive` or project-locally with `pnpm add -D @deftai/directive`.
+
+### Go installer (legacy bridge)
 
-### Go installer (bootstrap)
+The Go installer is a frozen legacy bridge for older installs and source-oriented recovery. New consumer installs should use npm above; see [UPGRADING.md](../UPGRADING.md#one-time-migration-from-the-go-installer-legacy--npm) when migrating an existing Go-installer layout.
 
 Download a platform installer from the [Directive release page](https://github.com/deftai/directive/releases) and run it from the project you want to adopt:
 

package/docs/hook-runtime-unavailable.md

@@ -0,0 +1,54 @@
+# Hook runtime unavailable: `deft-hook` is not on PATH
+
+On a host that cannot execute `deft-hook`, the Cursor `preToolUse` registration is `failClosed: true`, so **every mutation is denied** — and because the binary never runs, no Directive code is left to say why. The visible symptom is an opaque non-zero exit, typically **127** (command not found).
+
+Tracker: [#3785](https://github.com/deftai/directive/issues/3785). Related: [#3736](https://github.com/deftai/directive/issues/3736) (timeout), [#3571](https://github.com/deftai/directive/issues/3571) (unused-host recovery), [#2752](https://github.com/deftai/directive/issues/2752) (per-host toggles).
+
+## Who hits this
+
+The registration travels via git; the runtime does not. `.cursor/hooks.json` is trackable by design and the `.deft/core/` deposit is born-ignored, so any environment that gets the repo without a Node install of the CLI inherits the fence without the implementation:
+
+- cloud agent VMs whose image has no Node and no global install
+- CI runners and containers that never run `npm i -g @deftai/directive`
+- a fresh clone on a new workstation
+
+## Recovery is out of band
+
+There is no in-session escape. Run this from a shell where Node and the CLI **are** available — your workstation, or the repo before you push it:
+
+```bash
+deft policy:disable-host-hooks --host cursor --confirm
+```
+
+That sets `plan.policy.hostHooks.cursor = false` in `xbrief/PROJECT-DEFINITION.xbrief.json`, and the next `deft update` strips the Cursor registration. Commit and push; the locked-out environment clears on its next pull or fresh clone.
+
+⚠ Capability cost: disabling `hostHooks` for a host removes `deft-hook` pre-execution guardrails for anyone who later opens this repo in that host. The change is tracked and recorded to `meta/policy-changes.log`. Inspect with `deft policy:show --field=hostHooks`; reverse by setting the host back to `true` and running `deft update`.
+
+## Preferred fix: make the runtime travel with the registration
+
+If Cursor is a host you rely on, restore the runtime rather than removing the fence. Either:
+
+- commit a `package.json` dependency on `@deftai/directive` — a published version or another spec a clone can fetch, since a location spec (`file:`, `link:`, `../directive`, an absolute path) resolves only on the machine that wrote it — and run `npm install` in the image or clone, which puts `deft-hook` in `node_modules/.bin`; or
+- add `npm i -g @deftai/directive` to the image build.
+
+`deft init` and `deft update` warn when a hook registration travels with the repository — already committed, or merely untracked and not ignored, so the next `git add` carries it — while neither anchor is present. The warning names the affected file and this document.
+
+## ⊗ Do not hand-edit `failClosed` in the deposited hook file
+
+Setting `failClosed: false` in `.cursor/hooks.json` clears the block exactly once. That file is a managed deposit: the next `deft update` rewrites the entries with `failClosed: true` and **silently re-arms the lockout**, usually long after anyone remembers editing it. Use the policy verb above, which is durable and tracked.
+
+## Why the flags do not help
+
+| Escape hatch | Why it does not reach this failure |
+|---|---|
+| `.deft-directive-disable` | Evaluated *inside* `deft-hook`. When the binary is missing, nothing reads the flag. |
+| `.no-deft-directive` | Consulted at `session.start` only; it never reaches `preToolUse`. |
+| Host-side "skip hook" | A host concept. Directive has no such bypass. |
+
+## Absent, crashed, and timed out are one class
+
+The hook exit contract already decouples the exit code from the verdict: exit `0` means a decision was **rendered** — allow *or* deny — so every non-zero exit is by construction a *non-decision*. Absence, a crash, and a host timeout kill are the same state, and all three stay fail-closed.
+
+They stay fail-closed because fail-open-on-absence is a bypass primitive, not a lenience: removing the binary is an ordinary shell call, so treating absence as allow would convert a self-inflicted denial into a bypass of the write fence, the intent ceiling, the session ritual, and the occupancy lease ([#3156](https://github.com/deftai/directive/issues/3156)). What these cases need is legibility and an out-of-band escape — this page — not a relaxed fence.
+
+For a timeout specifically, retry the gated ritual first when machine load is the likely cause; the Cursor `tool.before` budget is sized for a gated ritual plus live readiness, so a repeated timeout is a real signal rather than noise.

package/docs/host-surface-assumptions.md

@@ -1,3 +1,4 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/docs/host-surface-assumptions.md" -->
 # Host-surface assumptions: file gates vs REPL / self-mutating hosts (#3162)
 
 Directive control surfaces assume two host behaviors that **some** modern agent hosts break by design.
@@ -131,7 +132,7 @@ Named hook home for managed-path deny: **Tier-1 host hooks** (`packages/core/src
 
 | Topic | Where |
 |-------|--------|
-| Self-improving, not self-editing stance | [main.md § Self-Improving, Not Self-Editing (#3164)](../../main.md#self-improving-not-self-editing-3164), [philosophy.md](../meta/philosophy.md) |
+| Self-improving, not self-editing stance | [main.md § Self-Improving, Not Self-Editing (#3164)](../main.md#self-improving-not-self-editing-3164), [philosophy.md](../meta/philosophy.md) |
 | Gate integrity (do not clear red by editing the gate) | [gate-integrity.md](./gate-integrity.md) (#3156); refine-internal #2436 separate |
 | Skill pin tiers (process pins, not full #830) | [skill-pin-policy.md](./skill-pin-policy.md) |
 | Host lifecycle duty list | [host-lifecycle-duties.md](../contracts/host-lifecycle-duties.md) |

package/docs/orphan-active-verdict-basis.md

@@ -0,0 +1,199 @@
+# `verify:orphan-active`: verdict basis and freshness (#3767)
+
+`verify:orphan-active` decides whether an `xbrief/active/` brief with
+`plan.status == running` is really still live work. Until #3767 it answered
+that question from a triage-cache hit returned **unconditionally** — no age
+bound, no re-validation. A cached `open` written twelve hours earlier beat
+reality and suppressed the live read that would have corrected it, so the gate
+exited 0 while scanning the very brief whose issue had already closed.
+
+This document records what the gate now does, why, and what it still cannot
+promise.
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `⊗`=MUST NOT, `?`=MAY.
+
+---
+
+## Two modes, split by query shape
+
+The gate has two callers with different obligations, so it has two mechanisms.
+
+| | Scoped `--issue N` | Unscoped aggregate |
+|---|---|---|
+| Caller | after-merge DONE proof (#3429 / #3476) | `task check`, pre-commit, pre-push sweep |
+| Mechanism | authoritative per-issue REST read | one complete open-issue inventory |
+| N | 1 | one call regardless of brief count |
+| Unknown state | **fail closed** (exit 1, `unresolved`) | **fail open** (exit 0, reported `unverified`) |
+| Latency budget | 5 s | 15 s |
+
+The unknown asymmetry is deliberate and predates this change. Scoped is a proof
+obligation before a worker claims DONE about one named origin. The aggregate
+sweep must not make offline work network-authorized — hard-failing every
+aggregate unknown would break `--skip-gh`, offline runs, and fresh clones.
+
+⊗ Do not flatten the two unknown policies into one rule.
+
+---
+
+## What each run is allowed to look at (#3893)
+
+Mode decides *how* a verdict is reached. Scope decides *which briefs* are in
+the question at all.
+
+| | Bare / `--issue N` | `--changed-only` |
+|---|---|---|
+| Caller | doctor, manual runs, swarm finalize, after-merge DONE proof | `check:framework-source` / `check:consumer` merge chokepoint |
+| Briefs evaluated | every running brief under `active/` | only briefs in the candidate's own diff against `origin/<deliveryBranch>` |
+| On the delivery line | n/a | falls back to the full sweep -- this run *is* the delivery-tip check |
+| Unresolvable git or base ref | n/a | falls back to the full sweep, never to a narrower scan |
+
+The merge chokepoint was unscoped until #3893. Measured 2026-08-28: four
+unrelated PRs failed the same two lanes on one stranded brief, one of them
+passed an unchanged re-run once the strandings landed, and two single-brief
+lifecycle PRs could not pass alone because each left the other orphan.
+
+The pre-merge run was never preventive for its own candidate either: the gate
+reads REST `merged_at`, and the candidate's linked PR still reads null while
+that candidate's gate runs. The pre-merge signal for closeout residue is
+`verify:pr-closeout-attestable` (#3781), which keys on the PR's structured
+closing references rather than the branch diff.
+
+The detector is unchanged. The linked-PR/open-issue signature still fails a
+candidate whose own diff carries it.
+
+⊗ Do not read a `--changed-only` pass as repo-wide truth. Every run prints its
+scope; `EvaluateResult.scope` carries the same thing structurally.
+
+---
+
+## The freshness choice
+
+**Age bound plus re-validation, applied per mode.** Both options offered by
+#3767 are used, because each mode needs a different one.
+
+- A cache hit is honoured only when it is at most **15 minutes** old
+  (`ISSUE_CACHE_MAX_AGE_MS`). Older entries are not evidence.
+- Scoped `--issue N` re-validates first: it takes the authoritative read and
+  falls back to the cache only inside the age bound, when the live read is
+  unavailable. Unknown after that is `unresolved`.
+- The aggregate sweep resolves from the open-issue inventory when the network
+  is allowed, and uses an in-bound cache hit only under `--skip-gh` or when the
+  inventory itself is unavailable.
+
+15 minutes keeps a warm-cache offline run working while making an overnight
+entry non-authoritative — the measured entry was roughly twelve hours old.
+
+---
+
+## The aggregate inventory
+
+The sweep reuses `restIssueListOpenInventory` (#3752): one
+`gh api --paginate --slurp repos/<owner>/<repo>/issues?state=open&per_page=100`
+subprocess. It excludes pull-request rows and **fails closed** on command
+failure, non-JSON output, a non-array payload, a malformed row, buffer
+exhaustion, and the pagination cap.
+
+! The inventory MUST be complete. `probeCacheDrift`'s helper defaults to a
+1,000-item limit; reusing that capped set as a closed-state oracle would
+misclassify open issue 1001+ in a larger repository.
+
+Membership in a successful inventory means open. **Absence means "not open"**,
+which is the direction that tells an operator to run `scope:complete` on what
+may be live work — so absence is confirmed by one authoritative per-issue read
+before the gate acts on it. That confirming result is reused for the rest of
+the run when several briefs name the same issue. In the ordinary case
+(everything open) that costs zero extra calls.
+
+When the inventory is unavailable the gate reports `unverified` rather than
+inferring closed. Fail-closed here means never manufacturing a false "closed",
+not turning the sweep into a connectivity check.
+
+### Why not a live read per brief
+
+Per-brief live reads are the mechanism #3752 removed. Measured: the inventory
+is **4.2 s constant**, against **14.2 s** and **76.6 s** for sequential
+per-brief reads at the WIP cap of 20 on two different hosts. Crossover is about
+5 briefs on `gh` and about 1 on `ghx`. `verify:orphan-active` sits in the
+fast-preflight tier, where wall clock rather than REST quota is the constraint.
+
+---
+
+## Reported basis
+
+Every run now says how it decided, so a verified pass is distinguishable from
+an unverified one:
+
+```text
+verify:orphan-active: no orphaned active/running xBRIEFs (scanned 3 running briefs in active/).
+  Basis: inventory 2, cache 1 (max age 4m).
+```
+
+```text
+verify:orphan-active: no orphaned active/running xBRIEFs (scanned 1 running brief in active/).
+  Basis: unverified 1.
+  UNVERIFIED: state could not be established for the references below, so this run is
+  not evidence that they are unshipped:
+    - #8001 (open-issue inventory unavailable: gh api failed: ...)
+```
+
+`EvaluateResult.basis` carries the same counts structurally
+(`inventory`, `live`, `cache`, `unverified`, `maxCacheAgeMs`, `proxied`,
+`elapsedMs`, `budgetMs`).
+
+⊗ Do not cite an exit 0 with `unverified > 0` as evidence that a tree is clean.
+
+---
+
+## The `ghx` caveat
+
+"Live" is itself a cache. `defaultRunGh` resolves through `resolveBinary()`,
+which prefers **`ghx`**, a cached read-only GET proxy whose age nothing in this
+gate can inspect.
+
+This gate therefore **pins plain `gh`** for its authoritative reads when `gh` is
+on PATH. When only `ghx` is available the gate still runs, sets
+`basis.proxied`, and prints:
+
+```text
+  Note: reads resolved through `ghx`, a cached GET proxy; freshness is bounded by that
+  proxy, which this gate cannot inspect (#3737).
+```
+
+⊗ Do not claim the gate detects a closed origin "regardless of cache age" while
+`ghx` is in the path. Whether `resolveBinary` should prefer `ghx` at all is
+[#3737](https://github.com/deftai/directive/issues/3737).
+
+---
+
+## Latency budgets
+
+There were none before #3767, which is why "affordable" was unfalsifiable.
+
+| Mode | Budget | Basis |
+|---|---|---|
+| Scoped `--issue N` | 5 s | one issue read plus at most one linked-PR read, measured ~0.75 s each |
+| Unscoped aggregate | 15 s | one 4.2 s inventory plus confirming reads for apparent closes |
+
+Exceeding a budget prints an advisory line and does **not** change the exit
+code. Budget drift is a signal to re-measure the mechanism, not a new failure
+mode for callers.
+
+---
+
+## Out of scope
+
+- The offline crash when neither `gh` nor `ghx` is on PATH
+  ([#3774](https://github.com/deftai/directive/issues/3774)).
+- Whether `resolveBinary` should prefer `ghx`
+  ([#3737](https://github.com/deftai/directive/issues/3737)).
+- The `cache_fresh` forge-error fail-open decided on
+  [#3738](https://github.com/deftai/directive/issues/3738).
+
+## Related
+
+- [#3429](https://github.com/deftai/directive/issues/3429) — the gate's contract
+- [#3476](https://github.com/deftai/directive/issues/3476) — `verify:completed-tracked`
+- [#3752](https://github.com/deftai/directive/issues/3752) — the open-inventory mechanism reused here
+- [#3156](https://github.com/deftai/directive/issues/3156) — gate integrity; this was a deliberate gate-definition change
+- [#3893](https://github.com/deftai/directive/issues/3893) — merge-chokepoint scoping; the named check-composition change
+- [#3781](https://github.com/deftai/directive/issues/3781) — `verify:pr-closeout-attestable`, the pre-merge closeout signal

package/docs/skill-pin-policy.md

@@ -13,7 +13,7 @@ Pins are for **false-negative-sensitive process gates**, not for copying entire
 | Tier | Meaning | How the agent discovers it |
 |---|---|---|
 | **always-pin** | Named in AGENTS.md (managed or consumer unmanaged header) as a required `SKILL.md` load when a matching work type starts | Always-loaded AGENTS.md |
-| **on-demand** | Routed via Skills Index triggers in `REFERENCES.md` — scan Level-0, read Level-1 on match | Skills Index → `SKILL.md` |
+| **on-demand** | Routed via Skills Index triggers (consumer: `npx deft packs:slice skills list`; maintainer: `REFERENCES.md`) — scan Level-0, read Level-1 on match | Skills Index → `SKILL.md` |
 | **reference-only** | External, rare, or maintainer-only corpora; no standing trigger routing | Explicit doc pointer only |
 
 ### Criteria for always-pin

package/events/README.md

@@ -27,11 +27,11 @@ data-file-convention check ([#710](https://github.com/deftai/directive/issues/71
 
 - **`detection-bound`** — detectable from filesystem state alone (e.g. dirty
   tree, vBRIEF schema invalidity, version drift). Emitted via
-  `scripts/_event_detect.py`. Detector lives at the call site documented in
+  `task lifecycle:event`. Detector lives at the call site documented in
   the entry's `trigger` field.
 - **`behavioral`** — requires runtime instrumentation (paired
   `session:interrupted` / `session:resumed`, `plan:approved`,
-  `legacy:detected`). Emitted via `scripts/_events.py`, which manages 1:1
+  `legacy:detected`). Emitted via `task lifecycle:event`, which manages 1:1
   session-pair invariants and a JSONL append-only log at
   `<project_root>/.deft-cache/events.jsonl`.
 
@@ -48,29 +48,28 @@ conforming to `event-record.schema.json`:
 }
 ```
 
-`scripts/_event_detect.py::emit(name, payload)` validates against the full
+`task lifecycle:event -- emit <name> ...` validates against the full
 registry (any registered name is accepted) and is silent by default; when the
 `DEFT_EVENT_LOG` environment variable points to a writable path, each
 emission is appended as a single JSON line.
 
-`scripts/_events.py::emit(name, payload)` validates against the
-`category="behavioral"` subset of the registry, generates a sortable event id
-for pairing semantics, enforces required-payload contracts, and persists to
-`<project_root>/.deft-cache/events.jsonl` (or a path injected via `log_path` /
+Behavioral emits validate against the `category="behavioral"` subset of the
+registry, generate a sortable event id for pairing semantics, enforce
+required-payload contracts, and persist to
+`<project_root>/.deft-cache/events.jsonl` (or a path injected via `--log` /
 `DEFT_EVENT_LOG`). The log lives under the already-gitignored `.deft-cache/`
 rather than `.deft/`, because `.deft/` is not blanket-gitignored on hybrid
 installs (`.deft/core/` is gitignored and reconstituted by `directive init`,
-per #1942 / #1465). Use this helper when emitting behavioral events from
-skills (`python -m scripts._events emit ...`).
+per #1942 / #1465). Skills emit behavioral events with
+`task lifecycle:event -- emit <name> ...`.
 
 ## Adding an event
 
 1. Append the entry to `registry.json` with the appropriate `category`,
    payload contract, trigger pointer, and consumer pointers (validate via
-   `tests/cli/test_events.py` and `tests/cli/test_behavioral_events.py`).
-2. Add the detection / emission call site in `scripts/` or the relevant
-   surface (use `scripts/_event_detect.py` for detection-bound,
-   `scripts/_events.py` for behavioral).
+   `packages/core/src/lifecycle/events.ts` tests).
+2. Add the detection / emission call site in the TypeScript lifecycle surface
+   (use `task lifecycle:event` for both detection-bound and behavioral events).
 3. Reference the event by name from at least one consumer (skill, task,
    script) so the surface stays usable -- the schema requires `consumers`
    to be a non-empty array.

package/glossary.md

@@ -1,3 +1,4 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/glossary.md" -->
 # Glossary
 
 The authoritative vocabulary for the Deft framework.
@@ -120,7 +121,7 @@ Canonical vocabulary for the xBRIEF lifecycle. **xBRIEF** / `xbrief/` is the sol
 
 - **Cross-scope dependency** -- Dependency between two scope xBRIEFs at `plan.metadata.dependencies` (array of dependency IDs). See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Exit Commands** -- The seven deterministic `task scope:*` commands that transition a scope xBRIEF between lifecycle folders: `scope:promote`, `scope:activate`, `scope:complete`, `scope:cancel`, `scope:restore`, `scope:block`, `scope:unblock` (see [tasks/scope.yml](../tasks/scope.yml)).
+- **Exit Commands** -- The seven deterministic `task scope:*` commands that transition a scope xBRIEF between lifecycle folders: `scope:promote`, `scope:activate`, `scope:complete`, `scope:cancel`, `scope:restore`, `scope:block`, `scope:unblock` (see [tasks/scope.yml](tasks/scope.yml)).
 
 - **Origin provenance** -- A `references` entry linking a scope xBRIEF to its origin issue / ticket / user-request. Required for ingestion dedup. See [vbrief/vbrief.md](./vbrief/vbrief.md).
 

package/incidents/README.md

@@ -1,3 +1,4 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/incidents/README.md" -->
 # Incidents Library
 
 This directory captures real-world incidents that motivated specific Deft
@@ -53,7 +54,7 @@ Examples:
 - `2026-04-15-some-other-incident.md`
 
 Filenames use hyphens, not underscores -- this mirrors the project-wide
-filename convention in [`main.md`](../../main.md).
+filename convention in [`main.md`](../main.md).
 
 ## When to add an entry
 

package/interfaces/cli.md

@@ -1,3 +1,4 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/interfaces/cli.md" -->
 # CLI Best Practices
 
 Opinionated patterns for command-line interfaces with AI agents.
@@ -110,4 +111,4 @@ else:
 
 ---
 
-**See also**: [python.md](../languages/python.md) | [typescript.md](../languages/typescript.md) | [tui.md](../interfaces/tui.md)
+**See also**: [python.md](../languages/python.md) | [typescript.md](../languages/typescript.md) | [tui.md](tui.md)

package/languages/6502-DASM.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/6502-DASM.md" -->
 # 6502 + DASM Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md)
 
 ## Scope
 - This guide covers:

package/languages/c.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/c.md" -->
 # C Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
 
 **Stack**: C17/C23, CMake 3.25+, clang/GCC; Testing: Unity/cmocka; Analysis: clang-tidy, cppcheck, AddressSanitizer
 

package/languages/cpp.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/cpp.md" -->
 # C++ Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
 
 **Stack**: C++20/23, CMake 3.25+, Catch2/GoogleTest, GSL (Guidelines Support Library); CLI: CLI11; TUI: FTXUI; Async: Asio/libcoro
 

package/languages/csharp.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/csharp.md" -->
 # C# Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
 
 **Stack**: C# 12+/.NET 8+ (LTS), SDK-style projects; Web: ASP.NET Core/Minimal APIs; Testing: xUnit + NSubstitute + FluentAssertions; Analysis: Roslyn Analyzers, StyleCop.Analyzers
 

package/languages/dart.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/dart.md" -->
 # Dart Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md)
 
 **Stack**: Dart 3.x+; Framework: Flutter (mobile/web) or standalone; Testing: `package:test` / `flutter_test`; Lint: `analysis_options.yaml` + custom_lint; Format: `dart format`; Docs: dartdoc
 

package/languages/delphi.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/delphi.md" -->
 # Delphi / Object Pascal Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
 
 **Stack**: Delphi 12+/Object Pascal, RAD Studio; GUI: VCL (Windows), FMX (cross-platform); DB: FireDAC; Testing: DUnitX
 

package/languages/elixir.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/elixir.md" -->
 # Elixir Standards
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+**⚠️ See also**: [main.md](../main.md) | [PROJECT.md](../../PROJECT.md)
 
 **Stack**: Elixir 1.16+ / OTP 26+; Build: Mix; Testing: ExUnit; Lint: Credo; Format: `mix format`; Docs: ExDoc; Types: Dialyxir