@sabaiway/agent-workflow-kit 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 3.7.0 — the worktrees-dir advisor item can finally converge (AD-068)
+
+The `recommendations` advisor's `worktrees-dir` item used to fire forever: its only convergence
+signal was a host write-capability callback that production never supplies, so the item kept
+re-rendering even once its own advice had been applied. It now converges on either of two
+maintainer-visible signals — while a genuinely supplied host signal still overrides both, in
+EITHER direction (a trusted no keeps the item firing however the project is configured):
+
+- **a declared grant** — a `sandbox.filesystem.allowWrite` entry covering the probed worktrees
+  parent dir, in either settings scope; `~`/`~/…` resolve against home, and coverage is
+  path-segment-aware (a grant on a sibling or on a child never counts). A declaration is proof the
+  maintainer applied THIS item's advice, never proof of write capability — the provision
+  preflight's real create+delete probe stays the runtime truth. The declaration read is guarded
+  no-follow end to end (an out-of-project store reached through a symlink cannot silence the item;
+  a non-regular target is a stated skip), and the `allowWrite` shape check is fail-closed over the
+  whole array — one malformed entry invalidates the list rather than hiding beside a good one;
+- **a dir-bound ack** — for hosts that ignore the settings key: the item's consent-gated APPLY
+  one-liner is `ack-write --lane worktrees-dir` (a dry-run preview that prints the exact `--apply`
+  which records the ack), while the HAND-APPLY grant advice rides the `recipe:` line as the
+  labeled first step — the consent flow waits for the grant (or the terminal-fallback choice)
+  before the ack runs, because the ack RECORDS a choice, never makes one. The recorded
+  `worktreesDirAck` fingerprint lives in the family-owned `docs/ai/acks.json` and binds to the
+  RESOLVED probe dir, so the item re-fires exactly when that resolved dir changes — never on a
+  no-op re-render, never a security key. Against a trusted host NO the apply stays the HAND-APPLY
+  grant advice and no ack surfaces (it could never converge there).
+
+`ack-write` accordingly grows a closed-world `--lane` registry (`sandbox-lane` — the default, so
+every existing invocation and rendered one-liner stays byte-identical — and `worktrees-dir`); one
+lane sets exactly ONE store key, merge-preserving the rest, and an unknown lane is a usage refusal
+at the writer, never an invented key in the shared store.
+
+Honesty fix riding along: every shipped surface that promised the read-lane hook «fires on
+subagent Bash too» now says «where the host fires hooks on subagent Bash» — that behavior has
+never been measured, and a shipped surface must not assert it.
+
 ## 3.6.0 — the dependency-free install posture: a proof, never a default (AD-067)
 
 On a provably dependency-free project the provision record and the default-lane report no longer

package/README.md

@@ -241,7 +241,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit core-evidence` | any time | **the ONE loop-evidence writer** (strip-the-kit) — every core evidence record lands in a single append-only JSONL store inside the git dir (never committable; versioned schema, latest-per-key supersession, byte-identical duplicates refused, malformed lines fail every reader closed). `red-proof "<file>#<pattern>"` declares an observed-red **BEFORE a bugfix** (N/N red runs + content custody + base + the pre-fix fingerprint; green/mixed/timeout are DISTINGUISHED refusals — nothing written); `degrade --backend --reason` is the ONLY escape for an unavailable review backend (per-tree, never all backends); `summary` renders the whole loop state statelessly (gate result · per-backend verdicts · red-proofs · degrades) — no ledger, no rounds, nothing remembered. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit coverage-check` | any time | **the final-run checker** (D3(c)+(d)) — reads the lcov the declared `unit-tests` gate produced at the FIXED git-dir path and fails on any uncovered CHANGED executable Node line (listed `file:line`; a changed file absent from the map is a file-level red; out-of-domain/unsupported files are LISTED — the claim narrowed honestly); VERIFIES every current-base red-proof declaration (bound test exists · custody hash unchanged · green N/N now · pre-fix fingerprint differs); prints `lcov-sha256=<hex|none>` of the exact bytes it consumed — the sha the `--final` receipt binds and re-hashes. An absent lcov is a LOUD `skipped-no-lcov`; a symlinked path is a refusal. `--check` is the gate exit code — declare it as the LAST gate (`run-gates --final` refuses otherwise). Read-only. |
 | `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |
-| `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (sandbox-lane only) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (the sandbox-lane live recipe, or the worktrees-dir hand-apply-first grant advice) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit worktrees` | any time | **parallel feature worktrees** — run several features in DIFFERENT agent sessions on one repo, zero interference on working-tree files (the ONE exception is the dependency cache, below): `provision <slug> --plan <file>` creates a sibling git worktree on branch `aw/<slug>` and populates it (registry-derived footprint copy-if-missing — a tracked file is never overwritten; EXACTLY ONE seeded feature plan; the `handoff-<slug>.md` record from minute zero; `node_modules` symlinked where the link stays ignored — a shared MUTABLE dependency cache: writes through it hit MAIN's node_modules; for isolation run the printed isolated-install command (`--install` only PRINTS it; on `--resume` run the printed unlink-first recovery first); absolute root-pinned gate commands rebased on untracked copies only, and only while their bytes equal the MAIN source or its rebased form — user-modified copies stay untouched); `list` is read-only (slug, branch, base, dirty, handoff); `land <slug> --prepare` locks the common git dir, fail-closes on divergence or incomplete satellite state, transfers the complete accepted satellite diff onto a CLEAN main, runs sync plus the declared gates, and reports HEAD/TRANSFER/PREPARED OIDs — the commit ALWAYS stays a dialogue ask; `cleanup <slug>` takes the same lock and removes a LANDED worktree only after live landed-verification against main HEAD, while `--abandon` is the ONE destructive arm (destroys unlanded work; **no preview step** on any writer). The parent dir is the `docs/ai/worktrees.json` `parentDir` setting (default: the repo's sibling parent); an unwritable parent degrades to printed maintainer-pasted commands, and the one-time host consent that makes it promptless surfaces via `recommendations`. Never commits, never pushes, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '3.6.0'
+  version: '3.7.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/agents/changelog-skeleton.md

@@ -21,4 +21,4 @@ Rules:
 - Mark anything uncertain as `VERIFY:` rather than asserting it.
 - No superlatives, no persuasion, no summary paragraph — that is the frontier's red-line work.
 - Read-only: you never modify files.
-- Tooling note: this vehicle grants `Read`/`Grep`/`Glob` only — **no `Bash`**. If a harness omits `Grep`/`Glob`, fall back to the `Read` tool (whole-file reads), never a shelled-out command. Should a harness nonetheless route your reads through `Bash`, keep each one a **plain single read-only command** (`grep …`, `ls …`, `cat …`) — never a `;`/`&&`/`|` chain, never `node -e`; where the maintainer enabled the opt-in **read-lane** (`docs/ai/lanes.json`), the gate hook keeps those seeded-read-only Bash reads promptless (it fires on subagent Bash too).
+- Tooling note: this vehicle grants `Read`/`Grep`/`Glob` only — **no `Bash`**. If a harness omits `Grep`/`Glob`, fall back to the `Read` tool (whole-file reads), never a shelled-out command. Should a harness nonetheless route your reads through `Bash`, keep each one a **plain single read-only command** (`grep …`, `ls …`, `cat …`) — never a `;`/`&&`/`|` chain, never `node -e`; where the maintainer enabled the opt-in **read-lane** (`docs/ai/lanes.json`), the gate hook keeps those seeded-read-only Bash reads promptless (subagent Bash included, where the host fires hooks on subagent Bash).

package/references/agents/gate-triage.md

@@ -21,4 +21,4 @@ Rules:
 - Output: one section per failing gate, ordered as the run reported them. No fix suggestions,
   no root-cause speculation beyond the failure class, no code.
 - Read-only: you never modify files, never re-run commands.
-- Tooling note: this vehicle grants `Read`/`Grep`/`Glob` only — **no `Bash`**. If a harness omits `Grep`/`Glob`, fall back to the `Read` tool (whole-file reads), never a shelled-out command. Should a harness nonetheless route your reads through `Bash`, keep each one a **plain single read-only command** (`grep …`, `ls …`, `cat …`) — never a `;`/`&&`/`|` chain, never `node -e`; where the maintainer enabled the opt-in **read-lane** (`docs/ai/lanes.json`), the gate hook keeps those seeded-read-only Bash reads promptless (it fires on subagent Bash too).
+- Tooling note: this vehicle grants `Read`/`Grep`/`Glob` only — **no `Bash`**. If a harness omits `Grep`/`Glob`, fall back to the `Read` tool (whole-file reads), never a shelled-out command. Should a harness nonetheless route your reads through `Bash`, keep each one a **plain single read-only command** (`grep …`, `ls …`, `cat …`) — never a `;`/`&&`/`|` chain, never `node -e`; where the maintainer enabled the opt-in **read-lane** (`docs/ai/lanes.json`), the gate hook keeps those seeded-read-only Bash reads promptless (subagent Bash included, where the host fires hooks on subagent Bash).

package/references/agents/mechanical-sweep.md

@@ -18,4 +18,4 @@ Rules:
 - Output format: the structure the prompt asks for (list / table / JSON). No preamble, no
   commentary, no recommendations — the orchestrator applies judgment, you supply facts.
 - Read-only: you never modify files, never run commands, never propose edits.
-- Tooling note: this vehicle grants `Read`/`Grep`/`Glob` only — **no `Bash`**. If a harness omits `Grep`/`Glob`, fall back to the `Read` tool (whole-file reads), never a shelled-out command. Should a harness nonetheless route your reads through `Bash`, keep each one a **plain single read-only command** (`grep …`, `ls …`, `cat …`) — never a `;`/`&&`/`|` chain, never `node -e`; where the maintainer enabled the opt-in **read-lane** (`docs/ai/lanes.json`), the gate hook keeps those seeded-read-only Bash reads promptless (it fires on subagent Bash too).
+- Tooling note: this vehicle grants `Read`/`Grep`/`Glob` only — **no `Bash`**. If a harness omits `Grep`/`Glob`, fall back to the `Read` tool (whole-file reads), never a shelled-out command. Should a harness nonetheless route your reads through `Bash`, keep each one a **plain single read-only command** (`grep …`, `ls …`, `cat …`) — never a `;`/`&&`/`|` chain, never `node -e`; where the maintainer enabled the opt-in **read-lane** (`docs/ai/lanes.json`), the gate hook keeps those seeded-read-only Bash reads promptless (subagent Bash included, where the host fires hooks on subagent Bash).

package/references/modes/recommendations.md

@@ -2,7 +2,7 @@
 
 Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md
 
-The **read-only deployment advisor** — the deterministic section every `upgrade` run ends with, also invocable on its own. It computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line, then each item as **{severity · what is sub-optimal · the benefit in ONE plain line · an optional `recipe:` line (the `sandbox-lane` live recipe — egress hosts + resolved writable dirs — only) · the exact consent-gated apply one-liner}**. The tool computes deterministic English DATA; **you PRESENT the section in the user's conversational language** — every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings stay **byte-exact**; show the raw tool block on request (the AD-032 report-contract lane — the tool cannot know the dialogue language, so the language rendering is your presentation layer).
+The **read-only deployment advisor** — the deterministic section every `upgrade` run ends with, also invocable on its own. It computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line, then each item as **{severity · what is sub-optimal · the benefit in ONE plain line · an optional `recipe:` line (the `sandbox-lane` live recipe — egress hosts + resolved writable dirs — or the `worktrees-dir` hand-apply-first grant advice) · the exact consent-gated apply one-liner}**. The tool computes deterministic English DATA; **you PRESENT the section in the user's conversational language** — every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings stay **byte-exact**; show the raw tool block on request (the AD-032 report-contract lane — the tool cannot know the dialogue language, so the language rendering is your presentation layer).
 
 **Live host/session facts are tool-composed only.** Every fact this section states about the current
 host or session — prompts fired, sandbox scope, whether a bypass was needed, network reachability,
@@ -15,7 +15,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 
 1. **`--cwd` is REQUIRED** — the target project is explicit, never inferred from the shell's current directory (a subdirectory invocation still advises on the named root).
 2. **Verdict first (present-even-when-empty, opening at the `## Recommendations (agent-workflow)` header).** With everything optimal the body is exactly `no recommendations — flow optimal.` — the empty-state line ALONE is the verdict, zero added lines. Every other state opens the body with ONE verdict line composed from the frozen templates: `{K} item(s) need attention` leads when any item's severity is `attention` (a CONFIGURED declaration that is broken, drifted, degrading or invalid — the deployment needs review); `{N} optional recommendation(s), apply any you want` covers the `optional` class (offers to enable an unconfigured capability), led by `nothing is broken` ONLY when no item needs attention AND no probe check was skipped (a skipped probe could hide an attention-class problem — the claim never overreaches); `optimality NOT attested — {M} probe check(s) skipped` is appended last whenever probe checks were skipped. (The `(s)` invariant form IS the pinned pluralization — no singular/plural branching.) Items render attention-first, each tagged `needs attention:` / `optional:`. A failed probe renders as a stated `⚠ skipped item …` line — never a crash, never a fabricated item.
-3. **The apply-through-agent lane — an explicit informed-consent checkpoint:** after presenting, OFFER to apply; the user selects items in plain language; for each selected item you **surface its posture note inline** where one exists (the per-item notes below cover exactly the risk-marked keys; for `sandbox-lane` the note INCLUDES the sandbox-lanes ladder — present the whole ladder inline at the consent moment, never as a bare pointer). The user **explicitly confirms**, and **only then** — **no command runs before confirmation** — do you run the rendered command. Do NOT infer safety from the presence or absence of an `--apply` flag: most items' rendered command IS the mutation and completes on that one run, **including a no-`--apply` mutation** such as `family-freshness`'s `npx … init`. Some items instead render a **dry-run preview** that changes nothing and prints an explicit follow-up `--apply`/mutating command to run NEXT (e.g. `sandbox-lane`'s ack-write — a NEUTRAL recipe fingerprint into the family-owned `docs/ai/acks.json`, never a security key — and the `gates-declaration` seeder): after the SAME confirmation you run that printed follow-up command — no second ask, no improvisation (each writer keeps its own consent semantics: previews, `--apply` flags, refusals). An item marked **HAND-APPLY** (e.g. `agy-adddir`) is **never run by you and never written by the kit** — hand the user its rendered line together with its posture note.
+3. **The apply-through-agent lane — an explicit informed-consent checkpoint:** after presenting, OFFER to apply; the user selects items in plain language; for each selected item you **surface its posture note inline** where one exists (the per-item notes below cover exactly the risk-marked keys; for `sandbox-lane` the note INCLUDES the sandbox-lanes ladder — present the whole ladder inline at the consent moment, never as a bare pointer). The user **explicitly confirms**, and **only then** — **no command runs before confirmation** — do you run the rendered command. Do NOT infer safety from the presence or absence of an `--apply` flag: most items' rendered command IS the mutation and completes on that one run, **including a no-`--apply` mutation** such as `family-freshness`'s `npx … init`. Some items instead render a **dry-run preview** that changes nothing and prints an explicit follow-up `--apply`/mutating command to run NEXT (e.g. `sandbox-lane`'s ack-write — a NEUTRAL recipe fingerprint into the family-owned `docs/ai/acks.json`, never a security key — and the `gates-declaration` seeder): after the SAME confirmation you run that printed follow-up command — no second ask, no improvisation (each writer keeps its own consent semantics: previews, `--apply` flags, refusals). An item marked **HAND-APPLY** (e.g. `agy-adddir`) is **never run by you and never written by the kit** — hand the user its rendered line together with its posture note; HAND-APPLY is **maintainer territory wherever it renders** — the apply slot or the `recipe:` line. For `worktrees-dir` the two classes COMPOSE in one item and the ORDER is part of the contract: its `recipe:` line is the HAND-APPLY grant advice, its apply one-liner is the dry-run ack preview, and you **wait for the maintainer to confirm the grant is applied (or the terminal fallback chosen)** before running that preview and the exact `--apply` command it prints — the ack RECORDS a choice that must already have been made, and against a trusted host NO the item renders no ack at all.
 4. Registry strings (benefits + item texts) are frozen tool data, fact-true, ONE line under the pinned shape cap — posture/risk detail lives in the notes below at the consent moment, never inline in the overview. The dual velocity+security wording (`safer — blast radius bounded by the OS sandbox, not human attention`) rides ONLY the items with a real security delta (the autonomy render, the sandbox provisioning); the bridge-wrappers item claims **velocity only**.
 
 **Per-item posture notes (the consent moment — surface BEFORE running or handing over the apply):**
@@ -24,7 +24,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 - `sandbox-lane` — surface this note TOGETHER with the sandbox-lanes ladder below (the ladder IS the practical half of the note — inline, never a pointer). Pure DISCOVERABILITY: it surfaces the manifest-declared observed session-sandbox recipe (egress hosts ∪ resolved writable state dirs — `networkHosts` ∪ `writableDirs` of the wired bridges' `capability.json`, the single documentation source) and converges on a NEUTRAL fingerprint acknowledgement recorded by the consent-gated **ack writer** into the family-owned `docs/ai/acks.json` (`sandboxLaneAck`; a changed recipe re-fires the item). The store is family-owned so no host settings validator guards it (AD-055 relocated the ack off the Claude Code settings schema, which rejected the unknown key); the legacy `"agentWorkflow": { "sandboxLaneAck": … }` settings-scope key is still READ for one deprecation window (until the next kit MAJOR). It never claims the settings security keys take effect on any host class, never recommends writing them, and the kit never seeds `sandbox.network.allowedDomains` / `sandbox.filesystem.allowWrite` (bridge council 2026-07-11, both backends concur: a network pre-allow widens egress for EVERY sandboxed command; a write allowance on CLI state dirs would expose credential dirs). Posture history: an IDE-managed session sandbox was live-observed (2026-07-11/12) ignoring hand-applied settings security keys in BOTH scopes, and codex needs a writable HOME (EROFS `~/.codex` in-sandbox); whether a session's sandbox honors the settings keys is runtime-unknowable from the advisor (a denial-only signal) — which is exactly why the item states only detectable facts and no zero-prompt promise on any host class.
 
 - `read-lane` — enabling the opt-in read-only compound lane auto-approves *compounds* (and singles) of the seeded read-only core that carry ZERO shell metaprogramming: an UNATTENDED trust extension, bounded by the audited read-only core (never a command outside it; prompt-bypass only, never a sandbox bypass) and applied regardless of which of those core commands you seeded as individual settings rules. It is a PROJECT-PERSISTENT declaration in `docs/ai/lanes.json` — every future session, subagents' Bash too where the host fires hooks on subagent Bash, and (committed) every checkout. The apply depends on state: when the lane is OFF, it is the `gate-hook --read-lane` preview (whose own currency check refuses a stale hook — a pre-1.48 hook never reads `lanes.json`); when the placed hook is STALE (an enabled lane over an old hook) or MISSING, the item instead surfaces a **delete-to-reseed** / re-place recovery (a destructive `rm` + `--apply`, an attention item — never the safe preview). Risk profile: a bounded read-only trust-posture extension — no write/exec exposure beyond the audited core.
-- `worktrees-dir` — on a settings-native host that honors the key, the HAND-APPLY line widens the OS-sandbox WRITE surface to the whole worktrees parent dir: every sibling path under it (other repositories included) becomes agent-writable, and the widening persists for every later session. A harness-managed host may ignore that project setting; grant the narrow parent through host/session controls or use the provision terminal fallback instead. When that scope is wider than you want, narrow it FIRST: create a dedicated dir yourself (outside the agent's write surface), point `docs/ai/worktrees.json` `parentDir` at it, then re-run recommendations — the item re-renders with the narrowed dir. The kit never writes sandbox filesystem allowances itself; the line is always yours to paste. Risk profile: a real write-surface widening where honored — scope it deliberately.
+- `worktrees-dir` — on a settings-native host that honors the key, the HAND-APPLY line widens the OS-sandbox WRITE surface to the whole worktrees parent dir: every sibling path under it (other repositories included) becomes agent-writable, and the widening persists for every later session. A harness-managed host may ignore that project setting; grant the narrow parent through host/session controls or use the provision terminal fallback instead. When that scope is wider than you want, narrow it FIRST: create a dedicated dir yourself (outside the agent's write surface), point `docs/ai/worktrees.json` `parentDir` at it, then re-run recommendations — the item re-renders with the narrowed dir. The kit never writes sandbox filesystem allowances itself; the line is always yours to paste. **Convergence** is two-path: a declared `sandbox.filesystem.allowWrite` entry covering the probed dir (either settings scope — `~` and `~/…` resolve against home, and coverage is path-segment-aware, so a grant on a sibling or on a child never counts), or — for a host that ignores that key — the neutral dir-bound acknowledgement recorded by this item's consent-gated apply one-liner (`ack-write --lane worktrees-dir` — a dry-run preview that prints the exact `--apply`; recorded as `worktreesDirAck` in the family-owned `docs/ai/acks.json`, never a security key), while the grant advice itself rides the `recipe:` line as the labeled FIRST step; against a trusted host NO the apply stays the HAND-APPLY grant advice and no ack is offered. Neither is proof of write CAPABILITY: the provision preflight's real create+delete probe stays the runtime truth, and the fingerprint is bound to the **resolved probe dir**, so the item re-fires only when that resolved dir changes (two absent `parentDir` values sharing an existing ancestor resolve to the same dir and keep the same ack). Risk profile: a real write-surface widening where honored — scope it deliberately.
 
 **Sandbox lanes (what to DO with the `sandbox-lane` recipe, per host class):**
 
@@ -32,6 +32,6 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 - **Harness-managed sandbox** (an IDE/session-imposed sandbox that ignores the settings keys) — a NARROWEST-SCOPE ladder: (1) prefer wrapper/command-SCOPED sandbox rules where the harness offers them (only the review wrappers gain the egress + state-dir writes); (2) a SESSION-scoped allowance (the manifest hosts + the resolved state dirs for the whole session) is an INFORMED WIDENING — it carries the same blast-radius class the settings security keys were rejected for (every sandboxed command in the session gains that egress and those writable credential dirs), acceptable only as the maintainer's deliberate choice for a review-heavy session. Its **paste-ready hand-apply shape** (the kit never writes these keys) is, in `.claude/settings.json`, `"sandbox": { "network": { "allowedDomains": ["<egress host>", …] }, "filesystem": { "allowWrite": ["<writable state dir>", …] } }` — fill `<egress host>` / `<writable state dir>` from THIS recipe (the wired bridges' `capability.json` `networkHosts` ∪ resolved `writableDirs`); one consent then lands durably in config. (3) Else the per-run consented bypass. Record the ack (the ack-write one-liner) once a lane is chosen — choosing the bypass, or consciously declining, also counts.
 - Either way the recipe is **observed-minimal, honestly incomplete** — a blocked host names itself at run time; extend by hand and re-ack (the fingerprint moves with the recipe, not with your extensions).
 
-**Invariants:** read-only (never writes, never commits, never runs a subscription CLI) · `--cwd` required · present-even-when-empty · verdict-first from frozen templates · probe failures degrade to stated skip lines · apply one-liners are cwd-independent (absolute tool paths + a pinned `--cwd`; the sandbox-provision item pins via a `cd <root> &&` prefix — the doctor reads its cwd; the ONE exception is the `set-autonomy` item, a conversational skill invocation explicitly labeled *run IN the target project*) · the kit never seeds `sandbox.network.allowedDomains` / `sandbox.filesystem.allowWrite` (hand-apply territory) · the sandbox-lane convergence is a neutral acknowledgement recorded into `docs/ai/acks.json` by the consent-gated ack writer (the legacy settings-scope key read for one deprecation window), never a security key.
+**Invariants:** read-only (never writes, never commits, never runs a subscription CLI) · `--cwd` required · present-even-when-empty · verdict-first from frozen templates · probe failures degrade to stated skip lines · apply one-liners are cwd-independent (absolute tool paths + a pinned `--cwd`; the sandbox-provision item pins via a `cd <root> &&` prefix — the doctor reads its cwd; the ONE exception is the `set-autonomy` item, a conversational skill invocation explicitly labeled *run IN the target project*) · the kit never seeds `sandbox.network.allowedDomains` / `sandbox.filesystem.allowWrite` (hand-apply territory) · the sandbox-lane convergence is a neutral acknowledgement recorded into `docs/ai/acks.json` by the consent-gated ack writer (the legacy settings-scope key read for one deprecation window), never a security key · the `worktrees-dir` item converges on a declared `allowWrite` entry covering its probed dir, or on its own `worktreesDirAck` lane in that same store (recorded by its apply one-liner, never by the `recipe:` line).
 
 **Exit codes:** `0` report rendered (items or the empty state); `1` error (e.g. `--cwd` is not a directory); `2` usage.

package/references/modes/worktrees.md

@@ -91,8 +91,13 @@ settings-native line (`sandbox.filesystem.allowWrite` in `.claude/settings.json`
 terminal command. On a settings-native host that honors the key, adding the parent can make later
 provision/cleanup promptless. On a harness-managed host that ignores project settings, grant the
 narrow parent through the host/session controls; if that is unavailable, use the printed terminal
-command for each operation. The `recommendations` mode surfaces this lane but treats write access
-as unverified without a trusted host-capability signal.
+command for each operation. The `recommendations` mode surfaces this lane and converges it two ways:
+a declared `sandbox.filesystem.allowWrite` entry covering the probed parent (either settings
+scope), or — on a host that ignores that key — the neutral dir-bound acknowledgement its
+consent-gated apply one-liner records into `docs/ai/acks.json` (`worktreesDirAck`; the dry-run
+preview prints the exact `--apply`). Neither is proof of write
+capability: the create+delete probe above stays the runtime truth, and the ack binds to the
+resolved probe dir, so the item re-fires only when that resolved dir changes.
 
 **Landing flow:** provision → work → handoff → land → re-attest → commit → cleanup. Satellite
 commits are outside v1: graph divergence stops land and prints cherry-pick/rebase recovery. A gate

package/tools/ack-write.mjs

@@ -9,8 +9,8 @@
 //   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
 //   • deployment-gated — REFUSES an absent docs/ai with a named recovery pointer (run init/bootstrap);
 //   • creates docs/ai/acks.json (and nothing else) if absent;
-//   • merge-preserve — every existing key (a hand-authored `_README`, future sibling acks) is kept;
-//     only the `sandboxLaneAck` key is set;
+//   • merge-preserve — every existing key (a hand-authored `_README`, the OTHER lanes' acks) is
+//     kept; only the selected lane's ONE key is set (--lane, closed-world over ACK_LANES);
 //   • symlink / non-regular target → STOP (never write through a link or clobber a device/dir);
 //   • fail-closed on malformed existing JSON (never overwrite an unparseable store);
 //   • atomic — exclusive-create *.tmp + rename (no partial-write state); last-writer-wins;
@@ -22,7 +22,7 @@
 import { lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { ACKS_FILE, ACKS_LANE_KEY } from './recommendations.mjs';
+import { ACKS_FILE, ACK_LANES } from './recommendations.mjs';
 import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 
@@ -37,6 +37,9 @@ const JSON_INDENT = 2;
 // The recipeFingerprint shape (recommendations.mjs: sha256 hex sliced to 16) — a fail-closed guard so
 // the store never records a malformed or injected value.
 export const FINGERPRINT_PATTERN = /^[0-9a-f]{16}$/u;
+// The lane this writer records when none is named — the original single-lane contract, so every
+// pre-existing sandbox-lane invocation and its rendered one-liner stay byte-identical.
+export const DEFAULT_ACK_LANE = 'sandbox-lane';
 
 export const ACK_WRITE_STOP = 'ACK_WRITE_STOP';
 export const stop = (message) =>
@@ -82,34 +85,41 @@ const preflightTarget = (absPath, deps) => {
 
 // Pure preflight (both dry-run and apply). Validates the fingerprint, refuses an absent deployment,
 // gates the target, and computes the merge — no writes.
-export const planAckWrite = ({ cwd, fingerprint }, deps = {}) => {
+export const planAckWrite = ({ cwd, fingerprint, lane = DEFAULT_ACK_LANE }, deps = {}) => {
   // typeof BEFORE RegExp.test — .test() coerces its arg to a string, so a number or a single-element
   // array of 16 hex chars would otherwise pass the guard and be written as a non-string ack the
   // reader then ignores.
   if (typeof fingerprint !== 'string' || !FINGERPRINT_PATTERN.test(fingerprint)) {
     throw usageFail(`--fingerprint must be a 16-char lowercase hex fingerprint (got ${JSON.stringify(fingerprint ?? null)})`);
   }
+  // hasOwn, never a bare lookup: an inherited name ("constructor", "toString") would otherwise
+  // resolve to a function and be written into the shared store as an invented key.
+  if (typeof lane !== 'string' || !Object.hasOwn(ACK_LANES, lane)) {
+    throw usageFail(`--lane must name a known ack lane (${Object.keys(ACK_LANES).join(', ')}); got ${JSON.stringify(lane ?? null)}`);
+  }
+  const ackKey = ACK_LANES[lane];
+  const noun = `the neutral ${lane} ack`;
   const root = resolve(cwd);
-  assertDocsAiDeployment(root, deps, { stop, noun: 'the neutral sandbox-lane ack', rel: ACKS_FILE });
+  assertDocsAiDeployment(root, deps, { stop, noun, rel: ACKS_FILE });
   const absPath = join(root, ACKS_FILE);
   const { existed, existing } = preflightTarget(absPath, deps);
-  const alreadyAcked = existing[ACKS_LANE_KEY] === fingerprint;
-  const merged = { ...existing, [ACKS_LANE_KEY]: fingerprint };
-  const otherKeys = Object.keys(existing).filter((k) => k !== ACKS_LANE_KEY);
-  return { root, absPath, fingerprint, existed, existing, merged, alreadyAcked, otherKeys };
+  const alreadyAcked = existing[ackKey] === fingerprint;
+  const merged = { ...existing, [ackKey]: fingerprint };
+  const otherKeys = Object.keys(existing).filter((k) => k !== ackKey);
+  return { root, absPath, fingerprint, lane, ackKey, noun, existed, existing, merged, alreadyAcked, otherKeys };
 };
 
-export const writeAck = ({ cwd, fingerprint, dryRun = true } = {}, deps = {}) => {
-  const plan = planAckWrite({ cwd, fingerprint }, deps);
+export const writeAck = ({ cwd, fingerprint, lane = DEFAULT_ACK_LANE, dryRun = true } = {}, deps = {}) => {
+  const plan = planAckWrite({ cwd, fingerprint, lane }, deps);
   if (dryRun) return { wrote: false, dryRun: true, ...plan };
   const body = `${JSON.stringify(plan.merged, null, JSON_INDENT)}\n`;
-  writeDocsAiFileAtomic(plan.root, ACKS_FILE, body, deps, { stop, noun: 'the neutral sandbox-lane ack' });
+  writeDocsAiFileAtomic(plan.root, ACKS_FILE, body, deps, { stop, noun: plan.noun });
   return { wrote: true, dryRun: false, ...plan };
 };
 
 // ── report ──────────────────────────────────────────────────────────────────────────────
-export const applyCommand = (root, fingerprint) =>
-  `node ${q(ACK_WRITE_TOOL)} --fingerprint ${fingerprint} --cwd ${q(root)} --apply`;
+export const applyCommand = (root, fingerprint, lane = DEFAULT_ACK_LANE) =>
+  `node ${q(ACK_WRITE_TOOL)}${lane === DEFAULT_ACK_LANE ? '' : ` --lane ${lane}`} --fingerprint ${fingerprint} --cwd ${q(root)} --apply`;
 
 export const formatResult = (result) => {
   const merge = result.otherKeys.length > 0 ? ` (merge-preserving ${result.otherKeys.length} existing key(s))` : '';
@@ -121,27 +131,29 @@ export const formatResult = (result) => {
     }
     return [
       `agent-workflow ack — DRY RUN (no changes; re-run with --apply)`,
-      `  - would ${result.existed ? 'set' : 'create'} ${ACKS_FILE} "${ACKS_LANE_KEY}" = "${result.fingerprint}"${merge}`,
+      `  - would ${result.existed ? 'set' : 'create'} ${ACKS_FILE} "${result.ackKey}" = "${result.fingerprint}"${merge}`,
       `  - this is a NEUTRAL recipe acknowledgement, never a security key.`,
-      `  to apply: ${applyCommand(result.root, result.fingerprint)}`,
+      `  to apply: ${applyCommand(result.root, result.fingerprint, result.lane)}`,
     ].join('\n');
   }
   return [
     `agent-workflow ack — APPLY`,
-    `  - ${ACKS_FILE}: "${ACKS_LANE_KEY}" = "${result.fingerprint}"${merge}`,
+    `  - ${ACKS_FILE}: "${result.ackKey}" = "${result.fingerprint}"${merge}`,
   ].join('\n');
 };
 
 // ── CLI ─────────────────────────────────────────────────────────────────────────────────
-const USAGE = `usage: ack-write --fingerprint <16-hex> [--dry-run | --apply] [--cwd <dir>] [--help]
+const USAGE = `usage: ack-write --fingerprint <16-hex> [--lane <${Object.keys(ACK_LANES).join('|')}>] [--dry-run | --apply] [--cwd <dir>] [--help]
 
-Records the NEUTRAL sandbox-lane recipe acknowledgement into ${ACKS_FILE} (the family-owned ack
-store — no host settings validator guards it). Default is --dry-run (a preview; writes nothing) and
-prints the exact --apply command. --apply merges "${ACKS_LANE_KEY}" into ${ACKS_FILE}, preserving
-every existing key. Refuses an absent docs/ai deployment; never a security key; never commits.`;
+Records a NEUTRAL recipe acknowledgement into ${ACKS_FILE} (the family-owned ack store — no host
+settings validator guards it). --lane names which advisor item is being acknowledged (default
+"${DEFAULT_ACK_LANE}"); each lane owns one top-level key. Default is --dry-run (a preview; writes
+nothing) and prints the exact --apply command. --apply merges that ONE key into ${ACKS_FILE},
+preserving every existing key. Refuses an absent docs/ai deployment; never a security key; never
+commits.`;
 
 export const parseArgs = (argv) => {
-  const opts = { fingerprint: undefined, dryRunFlag: false, apply: false, cwd: undefined, help: false };
+  const opts = { fingerprint: undefined, lane: DEFAULT_ACK_LANE, dryRunFlag: false, apply: false, cwd: undefined, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') opts.help = true;
@@ -151,6 +163,10 @@ export const parseArgs = (argv) => {
       i += 1;
       if (argv[i] === undefined || argv[i].startsWith('-')) throw usageFail('--fingerprint needs a value');
       opts.fingerprint = argv[i];
+    } else if (arg === '--lane') {
+      i += 1;
+      if (argv[i] === undefined || argv[i].startsWith('-')) throw usageFail('--lane needs a lane name');
+      opts.lane = argv[i];
     } else if (arg === '--cwd') {
       i += 1;
       if (argv[i] === undefined || argv[i].startsWith('-')) throw usageFail('--cwd needs a directory argument');
@@ -160,7 +176,7 @@ export const parseArgs = (argv) => {
     }
   }
   if (opts.dryRunFlag && opts.apply) throw usageFail('--dry-run and --apply cannot be used together');
-  return { help: opts.help, fingerprint: opts.fingerprint, dryRun: !opts.apply, cwd: opts.cwd };
+  return { help: opts.help, fingerprint: opts.fingerprint, lane: opts.lane, dryRun: !opts.apply, cwd: opts.cwd };
 };
 
 export const main = (argv = process.argv.slice(2), deps = {}) => {
@@ -172,7 +188,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(USAGE);
       return EXIT_OK;
     }
-    const result = writeAck({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), fingerprint: args.fingerprint, dryRun: args.dryRun }, deps);
+    const result = writeAck({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), fingerprint: args.fingerprint, lane: args.lane, dryRun: args.dryRun }, deps);
     log(formatResult(result));
     return EXIT_OK;
   } catch (err) {

package/tools/gate-hook.mjs

@@ -454,7 +454,7 @@ export const writeReadLane = ({ cwd, dryRun = true } = {}, deps = {}) => {
 };
 
 const READ_LANE_POSTURE =
-  "posture: an auto-allowed read chain runs UNATTENDED and can read any file you can — the SAME trust boundary as the AUDITED read-only core velocity seeds, extended to COMPOUNDS (and singles) of that core. The subset invariant holds against that AUDITED CORE (every segment is an audited-core read), so the lane is a standalone opt-in grant BOUNDED BY the audited core — never a command outside it; it auto-approves those core commands REGARDLESS of which you seeded as individual settings rules (not strictly a subset of your current settings). This consent is a PROJECT-PERSISTENT declaration in docs/ai/lanes.json — it applies to every future session and to subagents' Bash, and where docs/ai is committed, to every checkout. It bypasses the PROMPT only, never the OS sandbox; on engine builds where a hook allow supersedes an ask rule, the opt-in covers EXACTLY the audited read-only core — nothing else.";
+  "posture: an auto-allowed read chain runs UNATTENDED and can read any file you can — the SAME trust boundary as the AUDITED read-only core velocity seeds, extended to COMPOUNDS (and singles) of that core. The subset invariant holds against that AUDITED CORE (every segment is an audited-core read), so the lane is a standalone opt-in grant BOUNDED BY the audited core — never a command outside it; it auto-approves those core commands REGARDLESS of which you seeded as individual settings rules (not strictly a subset of your current settings). This consent is a PROJECT-PERSISTENT declaration in docs/ai/lanes.json — it applies to every future session, to subagents' Bash where the host fires hooks on subagent Bash, and where docs/ai is committed, to every checkout. It bypasses the PROMPT only, never the OS sandbox; on engine builds where a hook allow supersedes an ask rule, the opt-in covers EXACTLY the audited read-only core — nothing else.";
 
 export const formatReadLaneResult = (result) => {
   const merge = result.otherKeys.length > 0 ? ` (merge-preserving ${result.otherKeys.length} existing key(s))` : '';

package/tools/recommendations.mjs

@@ -33,7 +33,7 @@
 import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   preflightVelocityProfile,
@@ -597,6 +597,14 @@ export const recipeFingerprint = ({ hosts, dirs, home }) => {
 // consulted as an ack.
 export const ACKS_FILE = 'docs/ai/acks.json';
 export const ACKS_LANE_KEY = 'sandboxLaneAck';
+export const ACKS_WORKTREES_DIR_KEY = 'worktreesDirAck';
+// The CLOSED-WORLD ack-lane registry: the lane name an advisor item renders on the writer's
+// command line → the store key that writer sets. A lane the registry does not name is a usage
+// refusal at the writer, never a newly-invented key in the shared store.
+export const ACK_LANES = Object.freeze({
+  'sandbox-lane': ACKS_LANE_KEY,
+  'worktrees-dir': ACKS_WORKTREES_DIR_KEY,
+});
 
 // The opt-in read-lane toggle file (AD-055 Part II) — the SAME kit-owned docs/ai/lanes.json the
 // placed hook reads live. The read-lane item offers to enable it once the hook is placed+wired.
@@ -632,7 +640,7 @@ export const SANDBOX_LANE_ACK_KEY = 'sandboxLaneAck';
 // writer refuses such a deployment — the reader must too), a symlinked/dangling LEAF must not read as
 // not-yet-acked, and a non-regular target (FIFO/dir/device) is a fail-closed SKIP — never read it (a
 // FIFO would BLOCK the advisor). ENOENT-safe: an absent file/dir is the NORMAL not-yet-acked null.
-const readAcksLane = (root, deps) => {
+const readAckValue = (root, deps, ackKey) => {
   const readFile = deps.readFile ?? readFileSync;
   const lstat = deps.lstat ?? lstatSync;
   const absPath = join(root, ACKS_FILE);
@@ -651,7 +659,7 @@ const readAcksLane = (root, deps) => {
   if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new Error(`${ACKS_FILE}: expected a JSON object`);
   }
-  const value = parsed[ACKS_LANE_KEY];
+  const value = parsed[ackKey];
   return typeof value === 'string' ? value : null;
 };
 
@@ -719,7 +727,7 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
     // then the legacy settings scopes; a stale value in one store is ignored when another matches
     // (Decisions 2). A changed recipe (hosts, dirs, or an env override) re-fires the item (D4).
     const acks = [
-      readAcksLane(root, deps),
+      readAckValue(root, deps, ACKS_LANE_KEY),
       settings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY],
       localSettings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY],
     ];
@@ -742,9 +750,86 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
   }
 };
 
-// The worktrees-dir arming item (parallel feature worktrees): fires when the resolved worktrees
-// parent dir (docs/ai/worktrees.json parentDir, else the repo's own parent) is not confirmed
-// writable by a trusted host signal. The provision preflight remains the real create+delete test.
+// A declared `sandbox.filesystem.allowWrite` entry, resolved the way a host that honors the key
+// resolves it: `~` and `~/…` against the resolved home, every other form against the project root.
+const resolveDeclaredDir = (entry, { home, root }) => {
+  if (entry === '~') return resolve(home);
+  if (entry.startsWith('~/')) return resolve(home, entry.slice(2));
+  return resolve(root, entry);
+};
+
+// Ancestor-or-equal containment on PATH SEGMENTS, never a raw string prefix — a grant on
+// `<p>/farm` must never read as a grant on the sibling `<p>/farmhouse`. A grant on a DESCENDANT
+// never covers its parent: the parent dir is the one provision writes into.
+const dirCovers = (declaredDir, probeDir) => {
+  const base = declaredDir.endsWith(sep) ? declaredDir.slice(0, -sep.length) : declaredDir;
+  return probeDir === base || probeDir.startsWith(`${base}${sep}`);
+};
+
+// D7 lane 1 — the DECLARATION confirmation. A settings entry is not proof of writable CAPABILITY
+// (runtime truth stays with the provision preflight's real create+delete probe); it is proof the
+// maintainer applied this item's own advice, which is what the item may converge on. Both scopes
+// are consulted, as everywhere else here; a malformed store THROWS → the probe's stated skip.
+// readSettingsFile only filters ENOENT — it rejects neither a symlink nor a non-regular target, and
+// then reads THROUGH the link. A declaration is a CONVERGENCE signal here, so an unguarded read
+// would let a store outside the project silence the item (and a FIFO would block the advisor).
+// Guard the WHOLE path chain no-follow and require a regular file BEFORE the read; ENOENT stays the
+// normal not-declared fall-through, everything else becomes the probe's stated skip.
+const readDeclarationScope = (root, rel, deps) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const absPath = join(root, rel);
+  let st;
+  try {
+    assertContainedRealPath(root, absPath, { lstat });
+    st = lstat(absPath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw err;
+  }
+  if (!st.isFile()) throw new Error(`${rel} is not a regular file — refusing to read it`);
+  return readSettingsFile(absPath, { ...deps, cwd: root });
+};
+
+// Fail-closed shape check BEFORE any coverage test — UNIFORMLY, over the whole array: a declaration
+// that suppresses a recommendation is never PARTIALLY trusted, so one bad entry invalidates the
+// whole list rather than being filtered away beside a good one. An empty or whitespace-only entry is
+// invalid too: it is meaningless to a host, but would resolve to the project root here and silence
+// the item for any probe dir inside the repo. An ABSENT allowWrite is simply nothing declared.
+const declaredWritableDirs = (scope, rel) => {
+  const filesystem = scope?.data?.sandbox?.filesystem;
+  if (filesystem === null || typeof filesystem !== 'object' || Array.isArray(filesystem)) return [];
+  const { allowWrite } = filesystem;
+  if (allowWrite === undefined) return [];
+  if (!Array.isArray(allowWrite) || !allowWrite.every((entry) => typeof entry === 'string' && entry.trim() !== '')) {
+    throw new Error(`${rel}: sandbox.filesystem.allowWrite must be an array of non-empty strings`);
+  }
+  return allowWrite;
+};
+
+const declaresWritableDir = (root, probeDir, deps) => {
+  const home = deps.home ?? homedir();
+  // Both scopes are READ and SHAPE-CHECKED (never short-circuited) so the guards screen each one —
+  // a malformed second scope must not hide behind a converging first.
+  const declared = [SETTINGS_FILE, SETTINGS_LOCAL_FILE].map((rel) =>
+    declaredWritableDirs(readDeclarationScope(root, rel, deps), rel),
+  );
+  return declared.some((entries) =>
+    entries.some((entry) => dirCovers(resolveDeclaredDir(entry, { home, root }), probeDir)),
+  );
+};
+
+// D7 lane 2 — the ack fallback for a host that ignores the settings key, bound to the PROBED DIR
+// through the shared neutral fingerprint (the same home-symbolic canonicalization the sandbox-lane
+// ack uses, so a home-anchored dir acks portably). The binding is to the RESOLVED probe dir, so the
+// item re-fires only when that resolved dir changes — two ABSENT parentDir values sharing an
+// existing ancestor resolve to the same dir and keep the same ack.
+export const worktreesDirFingerprint = (probeDir, home) => recipeFingerprint({ hosts: [], dirs: [probeDir], home });
+
+// The worktrees-dir arming item (parallel feature worktrees): fires when write access to the
+// resolved worktrees parent dir (docs/ai/worktrees.json parentDir, else the repo's own parent) is
+// neither confirmed by a trusted host signal nor declared/acknowledged by the maintainer. Before
+// D7 the host signal was the ONLY convergence lane — injectable from tests but never supplied in
+// production, so the item fired forever even once its own advice had been applied.
 const probeWorktreesDir = ({ root, deps, add, skip }) => {
   try {
     const config = loadWorktreesConfig(root, deps);
@@ -752,13 +837,34 @@ const probeWorktreesDir = ({ root, deps, add, skip }) => {
     // the SAME canonical derivation the provision preflight probes (worktrees.mjs) — an absent
     // configured dir resolves to its nearest existing ancestor, never a false denial
     const probeDir = resolveProbeDir(parent, deps);
-    if (deps.canWriteDir?.(probeDir) === true) return;
+    // A supplied host signal is runtime truth and OVERRIDES both declaration lanes in EITHER
+    // direction: a trusted yes converges, a trusted no fires however the project is configured.
+    const hostSignal = deps.canWriteDir?.(probeDir);
+    if (hostSignal === true) return;
+    const home = deps.home ?? homedir();
+    const fingerprint = worktreesDirFingerprint(probeDir, home);
+    if (hostSignal !== false) {
+      if (declaresWritableDir(root, probeDir, deps)) return;
+      if (readAckValue(root, deps, ACKS_WORKTREES_DIR_KEY) === fingerprint) return;
+    }
     const dir = truncatedTo(oneLineOf(probeDir), templateBudget(WHATS['worktrees-dir']));
-    add(
-      'worktrees-dir',
-      fillTemplate(WHATS['worktrees-dir'], { dir }),
-      `HAND-APPLY: add ${JSON.stringify(probeDir)} to sandbox.filesystem.allowWrite in .claude/settings.json on settings-native hosts; on harness-managed hosts grant this dir for the session or use the provision terminal fallback`,
-    );
+    const grantAdvice = `add ${JSON.stringify(probeDir)} to sandbox.filesystem.allowWrite in .claude/settings.json on settings-native hosts; on harness-managed hosts grant this dir for the session or use the provision terminal fallback`;
+    // The consent-flow executes only the APPLY slot; a HAND-APPLY line is maintainer territory and
+    // a recipe: detail is informational. So when the ack lane is open, the runnable ack preview IS
+    // the apply (dry-run; it prints the exact --apply the flow then runs) and the grant advice
+    // rides the detail, labeled as the first step. Against a trusted NO the ack could never
+    // converge, so the grant advice is the apply and no ack surfaces.
+    if (hostSignal === false) {
+      add('worktrees-dir', fillTemplate(WHATS['worktrees-dir'], { dir }), `HAND-APPLY: ${grantAdvice}`);
+    } else {
+      add(
+        'worktrees-dir',
+        fillTemplate(WHATS['worktrees-dir'], { dir }),
+        `node ${q(toolPath('ack-write.mjs'))} --lane worktrees-dir --fingerprint ${fingerprint} --cwd ${q(root)}`,
+        'worktrees-dir',
+        `HAND-APPLY FIRST: ${grantAdvice}; THEN this item's apply one-liner previews the dir-bound ack and prints the exact --apply that records it`,
+      );
+    }
   } catch (err) {
     skip('worktrees-dir', err);
   }
@@ -852,7 +958,7 @@ Usage:
 Computes the deterministic Recommendations section every kit upgrade ends with — VERDICT-FIRST:
 one composed verdict line opens every non-optimal render, then per item {severity · what is
 sub-optimal · the benefit in one plain line · an optional \`recipe:\` line (the sandbox-lane live
-recipe only) · the exact consent-gated apply one-liner}. --cwd is
+recipe, or the worktrees-dir hand-apply-first grant advice) · the exact consent-gated apply one-liner}. --cwd is
 REQUIRED (the target project is explicit, never inferred from the shell's current directory). The
 section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a probe failure is a
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;