@deftai/directive-content 0.109.0 → 0.110.0

package/docs/grok-build-subscription-setup.md

@@ -0,0 +1,146 @@
+# Grok Build subscription-only setup
+
+Agent-facing playbook for a new maintainer. Paste this file (or issue [#4035](https://github.com/deftai/directive/issues/4035)) and say: follow this playbook. The human completes browser logins when the agent stops.
+
+This is **host auth**, not Directive `session:start` and not product work in `deftai/directive`.
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `⊗`=MUST NOT.
+
+---
+
+## Goal
+
+Grok Build is the parent on SuperGrok (`grok login` / grok.com). Claude Code and Codex run only through their CLIs on subscriptions. Console API keys may still exist at User scope for other tools. Grok must not use those keys.
+
+## Target shape
+
+Verified 2026-08-31 on win32 (Grok 4.6 parent). Org names differ per maintainer. The auth *methods* must match.
+
+| Surface | Required auth | Must not use |
+|---|---|---|
+| Grok Build parent | grok.com / `auth.x.ai` OIDC session (`grok login`) | `XAI_API_KEY`, `GROK_CODE_XAI_API_KEY`, Console BYOK `[model.*]` |
+| Claude Code CLI | `claude.ai` team subscription (`claude auth login --claudeai`) | `ANTHROPIC_API_KEY` / `apiKeySource=ANTHROPIC_API_KEY` |
+| Codex CLI | ChatGPT (`codex login status` → ChatGPT) | `OPENAI_API_KEY` |
+
+Grok catalog (`grok models`) is only `grok-4.6` / `grok-4.5`. Default is `grok-4.6`.
+
+User-scope `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` may remain for non-Grok tools. Leave them set.
+
+## Hard stops
+
+The agent MUST NOT:
+
+- implement product code while running this playbook
+- unset User-scope or Machine-scope `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `XAI_API_KEY`
+- run `claude logout`, `codex logout`, or `grok logout`
+- add or restore BYOK `[model.*]` blocks in `~/.grok/config.toml` (opus / sonnet / fable / gpt-5.6 Console ids)
+- print secret values (print only `set=$true` / `set=$false`)
+- invent `~/.config/deft` on Windows (#2544)
+
+Config is read at Grok session start. After any `config.toml` edit, start a **new** Grok session. Mid-session children will not pick up `shell_environment_policy`.
+
+Close stdin on CLI spawns: Windows `cmd /c "… <nul"`; Unix `… </dev/null`.
+
+## Playbook
+
+### 1. Grok Build
+
+Install the Grok CLI. Put it on PATH.
+
+Human (browser): `grok login` (grok.com / SpaceXAI OAuth at `auth.x.ai`).
+
+Confirm: `grok models` prints `You are logged in with grok.com.` and lists only `grok-4.6` / `grok-4.5`.
+
+### 2. `~/.grok/config.toml`
+
+Path: `~/.grok/config.toml` (Windows: `%USERPROFILE%\.grok\config.toml`).
+
+Set:
+
+```toml
+[models]
+default = "grok-4.6"
+default_reasoning_effort = "high"
+web_search = "grok-4.6"
+
+# Grok Build must not meter Anthropic/OpenAI/xAI Console API.
+# Claude/Codex go through their CLIs (subscription).
+# User/Machine env keys stay for other tools; Grok shells do not inherit them.
+[shell_environment_policy]
+exclude = [
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "XAI_API_KEY",
+  "GROK_CODE_XAI_API_KEY",
+]
+```
+
+Remove every `[model.<id>]` table that points at Anthropic or OpenAI Console (typical leftovers: `opus-5-high-fast`, `sonnet-5`, `fable-5`, `gpt-5.6-*`). Do not add new ones.
+
+Do not copy unrelated `[ui]` personal settings from another maintainer.
+
+Then start a **new** Grok session before the probes.
+
+### 3. Claude Code CLI
+
+Install current Claude Code. On Windows a working layout is `~\.local\bin\claude.exe` plus shims (`~\.local\bin` and `%AppData%\npm` on PATH).
+
+Human (browser): `claude auth login --claudeai`. Use the team org the operator names.
+
+Confirm: `claude auth status` shows `loggedIn=true`, `authMethod=claude.ai`, `subscriptionType=team`, and **no** `apiKeySource=ANTHROPIC_API_KEY`.
+
+### 4. Codex CLI
+
+Install Codex. On Windows the hashed binary may live under `%LOCALAPPDATA%\OpenAI\Codex\bin\`; keep a `codex` shim on PATH.
+
+Human (browser): `codex login` (ChatGPT).
+
+Confirm: `codex login status` prints `Logged in using ChatGPT`.
+
+### 5. PATH
+
+User PATH includes `~/.local/bin` (Windows: `%USERPROFILE%\.local\bin`) so Grok children find `claude` and `codex` without extra env surgery.
+
+## Verification (report pass/fail with evidence)
+
+Run from a **Grok** `run_terminal_command` child after the new session. Close stdin. Never print key values.
+
+1. **Catalog.** `grok models` → only `grok-4.6` / `grok-4.5`. Fail if opus / sonnet / fable / gpt-5.6 appear in *this* catalog (Codex may still say `gpt-5.6-*` as *its* ChatGPT model; that is not Grok BYOK).
+
+2. **Env policy.** This process may still have User keys. Print only `set=$true/$false` for User / Machine / Process scope of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`, `GROK_CODE_XAI_API_KEY`. The Grok child Process-scope for `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` MUST be `$false`. Fail if the child still has them — policy did not apply (old session, or config not loaded). Do not delete User keys.
+
+3. **Claude from Grok, no extra unset.** `claude auth status` as above. Then:
+
+   `claude -p "Do not use tools. Reply with the single word: pong" --output-format text`
+
+   Fail on an API-key warning or not-logged-in.
+
+4. **Codex from Grok.** `codex login status` → ChatGPT. Then:
+
+   `codex exec --ephemeral --skip-git-repo-check --sandbox read-only "Do not use tools. Reply with the single word: pong"`
+
+   Fail if it demands `OPENAI_API_KEY`.
+
+5. **Grok itself.** The session model is `grok-4.6` (or `grok-4.5`), not a Claude id. `XAI_API_KEY` unset. Auth is grok.com session (`grok models` / `~/.grok/auth.json` `auth_mode=oidc` at `auth.x.ai`). Do not dump tokens from `auth.json`.
+
+**Pass.** All five true. Grok Build is subscription-only: xAI login + Claude team + Codex ChatGPT. Keys may remain in User env for non-Grok tools.
+
+**Fail.** Child shells still inherit `ANTHROPIC_API_KEY` (old session / policy not loaded) or Claude reports `apiKeySource=ANTHROPIC_API_KEY`. Do not delete User keys. Report and stop.
+
+## Design-critique dispatch
+
+When a Grok Build parent runs an N≥3 design-critique panel, this playbook's CLIs are the other-family launchers. Probe `claude` / `codex` on PATH and CLI-spawn those seats. Paste-ready is the fallback when a CLI is absent, not the default recovery. Normative stop: [`contracts/design-critique.md`](../contracts/design-critique.md) Envelope and ceiling (#4067).
+
+## Out of scope
+
+- [#4027](https://github.com/deftai/directive/issues/4027) — N≥3 design-critique lean-timing. This playbook is host auth. Do not launch a 3-panel unless the operator asks.
+- [#2520](https://github.com/deftai/directive/issues/2520) — multi-engine least-privilege *pattern*. Related theme, different artifact.
+- Unsetting User keys that other tools still need.
+- Product code in `deftai/directive`.
+
+## Related Grok docs (local, after install)
+
+- `~/.grok/docs/user-guide/02-authentication.md` — grok.com session vs `XAI_API_KEY` fallback
+- `~/.grok/docs/user-guide/05-configuration.md` — `config.toml` precedence
+- `~/.grok/docs/user-guide/11-custom-models.md` — BYOK `[model.*]` (do not add these)
+- `~/.grok/docs/user-guide/18-sandbox.md` — `[shell_environment_policy]`

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

@@ -116,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.

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/scope-provenance.md

@@ -156,3 +156,29 @@ git add .deft/approved-scope/<plan-id>.json .deft/approved-scope/<plan-id>.inten
 ```
 
 Editing the xBRIEF alone does not authorize new implementation paths.
+
+
+## Cohort-created scope (operator mint at allocation) (#3874)
+
+If a swarm cohort brief should declare `file_scope`, the operator who approved
+the cohort mints the digest on a real TTY at allocation time and lands
+`.deft/approved-scope/<plan-id>.json` on the merge base before workers activate.
+
+- Allocation-context tokens (#1378) are **not** provenance.
+- Swarm briefs are **not** exempt from this gate.
+- `#3110` human-presence mint and merge-base layering are unchanged.
+
+If the operator does not mint, omit `file_scope` when authoring the cohort brief.
+Undeclared cohort briefs are then a deliberate outcome, not a post-failure
+workaround. Do not undeclare a declared `file_scope` to pass the gate.
+
+## Working-tree / untracked files
+
+`verify:scope-provenance` unions:
+
+1. `git diff --name-only <base>...HEAD`
+2. `git diff --name-only HEAD`
+3. `git ls-files --others --exclude-standard`
+
+and lists on-disk `xbrief/active/` files. Presence in the working tree is what
+matters. Committing or not committing the brief does not hide it from the gate.

package/docs/test-boundary.md

@@ -1,6 +1,8 @@
 # Test / source boundary (`verify:test-boundary`)
 
-Refs: #3145 · Related: #1310 forward-coverage, testing layout guidance
+Refs: #3145 · Related: #1310 / #4009 forward-coverage, testing layout guidance
+
+`verify:forward-coverage` reuses this policy for source-to-test correspondence. It does not add a second testRoots config.
 
 ## Problem
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.109.0",
+  "version": "0.110.0",
   "deftConsumerDeposit": true,
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "license": "MIT",