@deftai/directive-content 0.108.0 → 0.109.1

package/docs/hook-root-admission.md

@@ -0,0 +1,150 @@
+# Hook root admission — which tree a gated write is judged against (#3794 / #4013)
+
+Every PreToolUse mutation carries **two** roots, and they are not interchangeable:
+
+- **payload root** — the project root the host hook payload names.
+- **effective root** — the working tree the write target actually lands in, chosen by
+  `admitEffectiveHookRoot` from the target path.
+
+Deny messages name both: `payloadRoot=<path> effectiveRoot=<path>`.
+
+This page publishes what root admission decides, which gate reads which root, and why the
+no-toplevel case behaves the way it does. It describes shipped behaviour; it changes none of it.
+
+## The outcomes of root admission
+
+| Target's nearest existing ancestor resolves to | Outcome | Effective root |
+| --- | --- | --- |
+| The payload root itself | admit | payload root |
+| Another working tree sharing `--git-common-dir` with the payload root | admit | that worktree |
+| Another Git toplevel, while the payload root is not a Git repository | admit — no containment question exists | payload root |
+| Another Git toplevel whose `--git-common-dir` cannot be read | refuse `unproven-identity` | — (deny) |
+| A proven different repository | refuse `foreign-repository` | — (deny) |
+| **No Git toplevel at all** | **admit** | **payload root** |
+
+Set level: `admitMutationTargetSet` admits every member of one mutation (the declared ApplyPatch
+path plus every path in the patch body), short-circuits on the first refused member, and then
+requires **one unique** effective root across the members. Two admitted roots is a
+`worktree-span` refusal, so occupancy and ritual cannot follow only the declared path.
+
+The last row is the subject of #4013. It fires for any destination whose nearest existing ancestor
+directory is not inside a Git working tree — a path under the OS temp directory, a file in the home
+directory, a scratch directory outside every checkout.
+
+## The no-toplevel case is deliberate
+
+**A write target with no Git toplevel is gated against the payload root. That is intended, not a
+gap.** #3794's acceptance text required falling back to the payload root when a target worktree
+could not be admitted, and commit `bcd9d34e` deliberately split the two situations that fallback
+used to hold: a target that resolves to *some other* toplevel whose identity cannot be read now
+fails closed as `unproven-identity`, while a target with *no* toplevel keeps the payload-root
+behaviour. "A question asked and left unanswered" is the rationale for the fail-closed branch. It
+is not the rationale for this one — no containment question was ever posed.
+
+Three measured reasons the fallback is not a lease bug (#4013, accepted successor lean
+[5481139589](https://github.com/deftai/directive/issues/4013#issuecomment-5481139589)):
+
+1. **The effective root selects more than a lease.** It is the input to occupancy, the session
+   ritual, active scope, the story write fence and assist-scratch classification. "No root, no
+   gating" would drop all of those for an out-of-tree write, so an unritualed session — or an agent
+   acting on an absolute path it read in an issue — could write a home, config or temp file with no
+   ritual and no scope basis. It would also buy nothing on active scope, which already exempts
+   outside-root writes (#2885).
+2. **Occupancy and ritual are cross-checked, and the allow path re-stamps the lease.** The admitted
+   owner is compared against the session the verified ritual is bound to. Relaxing only the
+   foreign-lease refusal either leaves the writer blocked by that comparison, or suppresses it and
+   lets one session ride another's ceremony. The same path re-stamps `heartbeat_at` immediately
+   before an allowed write, so an unrelated out-of-tree write would renew the very lease a
+   narrowing meant to decouple.
+3. **A nullable root has no defined behaviour for a multi-target patch.** Target-set admission
+   demands one unique root. If an outside member contributed nothing, a patch mixing a
+   linked-worktree edit with an injected absolute path could collapse to the linked root and evade
+   the `worktree-span` refusal; if absence dominated instead, one outside member would suppress the
+   gates for the in-tree edit beside it. Either way an untrusted patch path becomes an
+   authority-selection input — the containment risk #3794 closed.
+
+The friction is real: a foreign lease holder should not block an unrelated note under the OS temp
+directory. Relieving it costs a change to the authority contract, not a bug fix. See
+[What a narrowing would have to define](#what-a-narrowing-would-have-to-define).
+
+## What still runs for a no-toplevel target, gate by gate
+
+| Gate | Root it reads | Disposition |
+| --- | --- | --- |
+| Occupancy lease | effective root (= payload root here) | **Runs.** A live foreign lease on the payload root denies `occupancy-occupied`; the owner or a granted member is admitted. |
+| Session ritual, gated tier | effective root (= payload root here) | **Runs**, including the occupancy↔ritual owner cross-check and the pre-allow re-check. |
+| Authz / UAT grant scoping | payload root | **Payload-root authoritative**, unchanged by admission. |
+| Authz audit trail | payload root | **Payload-root authoritative.** |
+| Kill-switch (`.deft-directive-disable`) | payload root | **Payload-root authoritative.** A flag beside the target does not disable the gate. |
+| `deny().projectRoot` | payload root | **Payload-root authoritative**, so a deny is reported against the tree the host named. |
+| Mutation intent ceiling (#1193) | neither | **Runs independently** of both roots. |
+| Read-only posture | neither | **Runs.** |
+| Runtime authority / path write fence | project policy from the payload root; story `file_scope` and the path it matches from the effective root | **Runs** when enabled. |
+| Active scope | effective root | **Inspected, deny skipped.** The not-ready deny is skipped by the #2885 outside-root carve-out, measured from the payload root. Spawn tools have no write target and still require scope. |
+| Assist-scratch allowlist | effective root | **No match.** An out-of-tree target is not under `.deft-scratch/` or `temp/` relative to the effective root, so the low-ceremony path does not apply. |
+
+Read that table as the answer to "what does the lease actually protect here". The case is not a
+lease question with one disposition; it is a root-selection question with a disposition per gate.
+
+## Three surfaces, three behaviours
+
+The fallback is a **direct-write** behaviour. It does not generalise across transports.
+
+| Surface | Example tool name | Reaches root admission? | Out-of-tree destination |
+| --- | --- | --- | --- |
+| Direct write, bare host name | `Write`, `Edit`, `search_replace`, `ApplyPatch` | **Yes** | Judged against the payload root — the fallback above. |
+| Generic server-prefixed MCP | `tasks__search_replace` | **No** | Routed only through push/merge runtime classification; unrecognized there, so `shell-op-unclassifiable` (fail open). |
+| Recognized Shell file-write | `Set-Content -Path <os-temp>/note.md …` | **No** | `isInRepoShellWritePath` rejects destinations resolving outside the project root, so the #3987 reissue path skips them (fail open). |
+
+Catalogued MCP push/merge names (`git_push`, `merge_pull_request`, …) *are* gated — by runtime
+authority scopes, which is a different gate and does not consult root admission either.
+
+⊗ Do not state that the payload-root fallback fires "on the direct-write and MCP surfaces". #4013's
+issue body said that and it is wrong for generic MCP. Three surfaces, three behaviours.
+
+## Known limitation — relative targets have no declared base (#4023)
+
+`existingAncestorDir` resolves the write target with `resolve(targetPath)` and no base argument, so
+a **relative** target is canonicalized against the hook **process** working directory rather than
+the payload root or a host-supplied cwd. The same lexical target can therefore land in different
+rows of the first table depending only on where the hook runs. Symlink and Windows-junction targets
+shift the class the same way: a junction into a linked worktree admits that worktree, a junction
+into a non-repository directory falls back to the payload root.
+
+Recorded, not fixed by #4013. Canonicalization changes admission classification, so it needs its own
+arc: **#4023**.
+
+## What a narrowing would have to define
+
+A narrowing is refused *as filed*, not forever. A viable successor design would:
+
+1. Name a target-class lattice: same admitted worktree, same-repository other worktree, foreign
+   repository, unproven identity, proven no-toplevel.
+2. State the combining rule for every mixed target set, so `admitMutationTargetSet` still yields one
+   answer.
+3. Keep the `foreign-repository`, `unproven-identity` and `worktree-span` refusals ahead of any
+   exemption.
+4. State, per gate in the table above, whether the exemption changes that gate — including whether a
+   no-toplevel write may refresh any worktree lease, and whose ritual satisfies it.
+5. Canonicalize targets first (#4023).
+
+None of that would make #4013's filed premise — that the fallback is a defect — true.
+
+## Scope of this guarantee
+
+Root admission is **cooperative host-session routing**, the same posture as the occupancy lease it
+selects: hook payloads and local session ids are forgeable by a same-user process. It bounds
+careless cross-tree writes; it is not an authentication boundary against an adversarial agent. See
+[`contracts/path-write-fence.md`](../contracts/path-write-fence.md) for the same limit stated for
+the write fence.
+
+## Code
+
+| Concern | Where |
+| --- | --- |
+| Root admission, single target and target set | `packages/core/src/hooks/dispatcher.ts` — `admitEffectiveHookRoot`, `admitMutationTargetSet` |
+| Which gate reads which root | `packages/core/src/hooks/dispatcher.ts` — `inspectMutationGates` header comment |
+| Nearest existing ancestor, toplevel and common-dir lookups | `packages/core/src/session/git.ts` — `existingAncestorDir`, `worktreePathOrNull`, `gitCommonDir` |
+| Shell write-dest classification and the in-repo predicate | `packages/core/src/hooks/shell-write-targets.ts` — `isInRepoShellWritePath` |
+| Tool-name surfaces | `packages/core/src/hooks/tools.ts` — `isDirectWriteTool`, `isShellTool`, `isMcpTool` |
+| Behaviour lock | `packages/core/src/hooks/dispatcher-effective-root.test.ts` |

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.
@@ -115,6 +116,8 @@ Where the host supports hooks, **deny writes to directive-managed paths** withou
 | **Tier-1 host hooks** | PreToolUse / equivalent intercept Write/Edit/Shell that target managed paths (AGENTS managed section, deposit, pin skill paths the host exposes) |
 | **Path write fence** | Project + story `file_scope` evaluation — [`path-write-fence.md`](../contracts/path-write-fence.md) |
 | **Agent hook readiness** | `deft verify:hooks-installed --scope=agent --live` — [`agent-hook-readiness.md`](../contracts/agent-hook-readiness.md) |
+| **Host tool-surface coverage** | Which tool names each host's matcher actually selects, and which are recorded out of scope — [`host-tool-surface-audit.md`](./host-tool-surface-audit.md) (#3987) |
+| **Root admission** | Which working tree a gated write is judged against, gate by gate, and which surfaces consult it — [`hook-root-admission.md`](./hook-root-admission.md) (#3794 / #4013) |
 | **Policy** | `plan.policy.hostHooks.<host>` — inspect with `deft policy:show --field=hostHooks` |
 
 ! When hooks are available, treat managed-path deny as the enforcement home for constitution bytes — not agent good behavior alone.
@@ -131,7 +134,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/host-tool-surface-audit.md

@@ -0,0 +1,163 @@
+# Host tool-surface audit (#3987)
+
+The PreToolUse write gate only runs on tool names the host's deposited matcher
+selects. A name nobody listed is not a permissive policy — it is a gate that
+never executes. #3987 was exactly that: Grok Build's shell tool
+`run_terminal_command` was in no matcher, so a write the gate refused could be
+reissued through the shell and land unobserved.
+
+This file is the recorded answer to acceptance item 2: **for every tool name a
+supported host emits, either the deposited matcher covers it, or there is a
+written reason it stays out of scope.** The machine-readable form is
+`HOST_TOOL_SURFACE_AUDIT` in `packages/core/src/hooks/tools.ts`, and
+`deft verify:hooks-installed --scope=agent` fails closed on any silence in it.
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `⊗`=MUST NOT.
+
+---
+
+## Two layers that can disagree
+
+| Layer | Form | Where |
+|-------|------|-------|
+| Deposited matcher | literal `a\|b\|c` alternation the host matches against | `.claude/settings.json`, `.grok/hooks/deft.json`, `.cursor/hooks.json`, `.codex/hooks.json` |
+| Runtime classifier | lowercases and strips non-alphanumerics, then set-membership | `isDirectWriteTool` / `isShellTool` / `isSpawnTool` |
+
+Both read the same constants, so they normally agree — but a name can be
+present in one and useless in the other. A matcher entry the classifier does not
+recognize invokes the hook and then falls through to `not-direct-write`; a
+classifier entry the deposit omits is never reached at all. The coverage check
+asserts **both** for every catalogued name, so a fix has to say which layer it
+changed.
+
+---
+
+## Grok Build — fully observed
+
+Source: this host's published tool list, plus the 5,354-call session census
+recorded on [#3987](https://github.com/deftai/directive/issues/3987).
+
+| Tool | Disposition |
+|------|-------------|
+| `write` | covered — direct write |
+| `search_replace` | covered — direct write |
+| `run_terminal_command` | covered — shell (#3990) |
+| `monitor` | covered — shell; it runs an arbitrary background shell command, so omitting it reproduces the #3987 gap one tool over |
+| `spawn_subagent` | covered — spawn |
+| `read_file`, `grep`, `list_dir`, `search_tool`, `web_search`, `web_fetch` | out of scope — read |
+| `todo_write` | out of scope — session-local non-product scratch |
+| `get_command_or_subagent_output`, `wait_commands_or_subagents` | out of scope — poll over already-dispatched work |
+| `kill_command_or_subagent` | out of scope — process control |
+| `scheduler_delete`, `scheduler_list` | out of scope — scheduler control and read; mutate no product path |
+| `enter_plan_mode`, `exit_plan_mode` | out of scope — session posture |
+| `image_gen`, `image_edit`, `image_to_video`, `reference_to_video` | out of scope — generated media lands in session scratch, never a tracked product path |
+| `scheduler_create` | **known gap, not covered** — see below |
+| `use_tool` | **known gap, not covered** — see below |
+
+### `scheduler_create` — spawn-class, needs a policy decision
+
+It dispatches a background subagent on an interval, which is spawn-class by the
+same reading that puts `spawn_subagent` in the matcher. Covering it routes a
+scheduling primitive through the full spawn stack (session ritual plus an active
+xBRIEF), which denies a shape that works today — a new deny class, not a
+coverage repair. That is a deliberate policy call and belongs in its own change,
+not in a matcher edit.
+
+### `use_tool` — mcp-class, needs a classifier change
+
+`use_tool` is a proxy: the MCP tool actually invoked is nested in
+`tool_input.tool_name`, and the dispatcher classifies on the outer name only. A
+matcher entry alone would buy a hook invocation and no enforcement, because
+`isMcpTool("use_tool")` is false and `classifyMcpTool` returns null. Reading the
+inner name is a classifier change with its own untrusted-input surface.
+
+---
+
+## Claude, Codex, Cursor — partly or wholly unobserved
+
+The deposit asserting a spelling is **not** evidence that the host emits it. All
+four deposits carry the identical shell matcher, which is a matcher-string fact,
+not a coverage fact ([#3987 comment 5471374558](https://github.com/deftai/directive/issues/3987#issuecomment-5471374558) F8).
+
+| Host | Established | Unobserved |
+|------|-------------|------------|
+| Claude Code | shell `Bash` | direct-write and spawn spellings |
+| Codex | shell `shell`; `apply_patch` write form (#3614) | everything else |
+| Cursor | nothing | the whole surface |
+
+Cursor is the one that matters: nothing in this tree observes which tool names
+it emits on `preToolUse`. The fixture corpus asserts the framework's own
+assumption, and `agent-hooks.test.ts` asserts the deposit contains a string.
+Neither observes the host. Cursor could be a second zero-coverage host by the
+exact mechanism that produced #3987, and the evidence available here would not
+distinguish that from working coverage.
+
+! Closing these requires an **observed** PreToolUse payload per host, not a
+re-reading of the deposit.
+
+⊗ Fill a host's catalog from the deposit, the matcher constants, or the fixture
+corpus. That makes the check assert its own input and hides the gap it exists
+to find.
+
+---
+
+## The check
+
+`deft verify:hooks-installed --scope=agent` (also run by `deft doctor`) fails
+closed on four silences:
+
+| Finding | Meaning |
+|---------|---------|
+| `missing-audit` | a supported host has no entry here at all — the "new host drops out of coverage" case |
+| `uncovered-tool` | a catalogued mutation name is absent from every **deposited** matcher — the "renamed tool" case, read from the file rather than regenerated |
+| `unclassified-tool` | a catalogued name the runtime classifier does not place in the same group |
+| `unexplained-entry` | an out-of-scope entry with no reason, a host claiming full observation while naming no mutation tool, or a non-mutation entry the classifier actually gates |
+
+A hand-edited deposit reads as **stale** first, and `deft update` is the remedy
+for that; the coverage message is for gaps a current deposit still leaves.
+
+Implementation: `packages/core/src/init-deposit/host-tool-coverage.ts`.
+Catalog: `packages/core/src/hooks/tools.ts`.
+
+---
+
+## Why coverage alone did not close #3987
+
+Matcher coverage is necessary and not sufficient — all three seats of the #3987
+panel agreed. Coverage closes the reissue bypass. It does not keep the occupancy
+lease alive, because the lease renews on a **gated write**, and eligibility
+keeps almost all real shell traffic off that path: five recognized write verbs,
+no dest carrying `$` / `*` / `?`, nothing out of root or in OS temp, and any
+compound command refused before the gate. `cd <root>; <command>` is compound,
+and the mandated Windows body-file flow (#2646 / #2744) fails all three
+conditions at once.
+
+The renewal half is `restampOwnerLivenessOnHookEvent`
+(`packages/core/src/hooks/owner-liveness.ts`): the hook already resolves the
+owner from the host payload, so a matched tool call renews the lease even when
+it writes nothing. It is bounded to a host-authoritative owner, keeps
+`markWrite` false, and never touches `claimed_at`, so `OCCUPANCY_MAX_LEASE_MS`
+still ends the lease at 12 hours. It renews the tree the mutation gates
+authorized against — a linked worktree under `.deft-scratch/`, not the payload
+root — so a worktree write does not keep the primary checkout's lease alive
+while the tree actually in use expires.
+
+! A call with **no write target** proves only the tree the host named.
+`projectRootFromHookPayload` takes that from the payload's own `cwd`-class
+fields, so a session working inside a worktree names the worktree and renews
+it. When the host reports a root that is not the tree the work is in, and no
+write target says otherwise, nothing is renewed. That is deliberate: renewing a
+guessed tree would keep a lease alive for a tree nobody occupies, and reclaiming
+an unused tree is what the TTL is for. `deft occupancy:heartbeat --session-id
+<owner>` remains the explicit path for a long, quiet session.
+
+---
+
+## Cross-links
+
+| Topic | Where |
+|-------|-------|
+| Gate integrity (do not clear red by editing the gate) | [`gate-integrity.md`](./gate-integrity.md) |
+| Host honesty limits | [`host-surface-assumptions.md`](./host-surface-assumptions.md) |
+| Agent hook readiness | [`agent-hook-readiness.md`](../contracts/agent-hook-readiness.md) |
+| Occupancy lease and its bounds | `packages/core/src/session/occupancy.ts` |

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

@@ -35,6 +35,37 @@ aggregate unknown would break `--skip-gh`, offline runs, and fresh clones.
 
 ---
 
+## 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
@@ -164,3 +195,5 @@ mode for callers.
 - [#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
 

package/languages/go.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/go.md" -->
 # Go 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)
 
 ## Standards
 

package/languages/java.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/java.md" -->
 # Java 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**: Java 21+ (LTS), Maven/Gradle; Web: Spring Boot 3+; Testing: JUnit 5 + Mockito + AssertJ; Analysis: Checkstyle, SpotBugs, Error Prone
 

package/languages/javascript.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/javascript.md" -->
 # JavaScript 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**: ES2022+, Node 20+; Build: Vite/esbuild; Testing: Vitest/Jest; Lint: ESLint + Prettier; Web: React/Next.js
 

package/languages/julia.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/julia.md" -->
 # Julia 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**: Julia 1.10+; Packages: Pkg.jl; Testing: `Test` stdlib + Aqua.jl; Docs: Documenter.jl; Format: JuliaFormatter.jl; Lint: JET.jl / Aqua.jl
 

package/languages/kotlin.md

@@ -1,8 +1,9 @@
+<!-- deft:deposit-link-rewrite v=1 source="content/languages/kotlin.md" -->
 # Kotlin 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**: Kotlin 2.0+; Build: Gradle (Kotlin DSL); Testing: JUnit 5 + kotest; Lint: detekt; Format: ktfmt/ktlint; Docs: KDoc