@sabaiway/agent-workflow-kit 1.42.0 → 1.44.0

package/CHANGELOG.md

@@ -4,6 +4,88 @@ 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.
 
+## 1.44.0 — Autonomy provisioner: the consent-gated sandbox doctor (AD-044 Plan 2)
+
+A **feature** release (kit-only; memory/engine/bridges unchanged, lineage head stays `2.0.0`). New
+routable GUARDED mode **`autonomy-doctor`** — the cross-platform system provisioner that makes the
+AD-044 sandbox actually initializable on consumer hosts: detect → consent-gated install → verify →
+loud degrade, over the locked matrix (macOS Seatbelt built-in / Linux + WSL2 `bwrap` + `socat` /
+native Windows → WSL2 redirect). This is the kit's FIRST tool that can run a privileged command,
+so the consent and honesty contract is the release:
+
+- **Three explicit lanes.** Flagless = FS-only preview (ZERO subprocesses): the diagnosis, the
+  exact install command it WOULD run, and the exact `--apply <pm>:<pkg,…>` consent line — never a
+  "ready" claim (Linux flagless is `present-unverified`, exit 3, by design). `--verify` = the only
+  source of a Linux "ready (verified)": a pinned bwrap user-namespace smoke + `socat -V`.
+  `--apply <pm>:<pkgs>` = consent bound to the previewed tuple — any mismatch vs the re-derived
+  plan refuses (exit 2) and runs nothing; a successful install auto-verifies.
+- **Privileged execution, closed world.** Every executed token — package manager, sudo, and the
+  binary `env` execs — resolves to an ABSOLUTE path inside the fixed trusted-dir allowlist
+  `/usr/bin:/bin:/usr/sbin:/sbin` (`/usr/local/bin` deliberately excluded); a PATH-shadowed
+  binary triggers a loud advisory, never execution. Frozen 4-family map: apt via the
+  env-trampoline (`sudo /usr/bin/env DEBIAN_FRONTEND=noninteractive apt-get install -y …`, so
+  non-interactivity survives sudo `env_reset`) · dnf `-y` · pacman `--needed --noconfirm` ·
+  apk `add`; package names come from a frozen internal map — no repo/config/user input ever
+  enters the command line. Unknown PM or untrusted location → stated degrade (exit 6), never a
+  guess.
+- **Sudo boundary, honestly.** `sudo -n true` preflight; passwordless success is LOUDLY stated;
+  no TTY + a password required → the ENFORCED print-handoff (the doctor runs NOTHING and prints
+  the exact command to run in your own terminal) — the designed primary path under an agent
+  harness. Root callers (`euid 0` / `SUDO_UID`) are refused a "verified" claim — a green smoke
+  under root can't prove unprivileged user namespaces (`root-unproven`, exit 5).
+- **Frozen output contract.** Exported EXIT/status table (Linux exit 0 ONLY via the verify
+  oracle) + a machine-parseable summary LAST line in every diagnosis outcome (`--help` prints the
+  help text alone); `doc-parity` bindings pin the contract to the mode doc. The docs/ai
+  deployment gate runs after arg parsing, ahead of every diagnosis/verify/apply lane; the
+  `.workflow-version` stamp gate is a stated EXEMPTION (the doctor mutates the OS, never
+  lineage-bound repo content).
+- **Host-proven where it counts.** The bwrap smoke fixture and the apt env-trampoline descriptor
+  are host-proven (the trampoline crossed a real sudo boundary with zero apt prompts); a fresh
+  Claude Code session on the newly-ready host shows the series payoff — an ad-hoc command's
+  prompt-delta drops 1 → 0 while the commit/push/publish red-lines still ask (content-scoped
+  `ask` rules pierce `autoAllowBashIfSandboxed`; the render's exact rule form is load-bearing)
+  and network egress still prompts. The sandbox is picked up at session START — the doctor's
+  success output always states the restart step.
+- **Registration + guards.** The GUARDED legend now reads "consent-gated destructive/privileged
+  actions (dry-run-first)"; the velocity render's sandbox-unavailable degrade message points at
+  the doctor; the doctor stays OUTSIDE every velocity auto-approve tier; tarball sentinel
+  143 → 145 (`tools/autonomy-doctor.mjs` + `references/modes/autonomy-doctor.md`).
+
+## 1.43.0 — Closed-world gate seeding: lifecycle hooks die by construction (AD-052)
+
+A **feature** release (kit-only; memory/engine/bridges unchanged, lineage head stays `2.0.0`). The
+consent-gated `gates.json` seeder (`seed-gates.mjs`) moves from BLOCKLIST screening to a
+**closed-world** offer derivation — the structural fix for **Issue-011**, whose three residuals the
+AD-042 council could only ever push one gap further, never close. Since a declared gate is
+hook-auto-approvable, the offer is now conservative BY CONSTRUCTION: the worst case is a legit
+command not offered (add it by hand), never a dangerous one offered.
+
+- **Uniform hook-free exec form.** The seeded cmd is
+  `COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>` for the detected package manager.
+  `exec` runs a command, not a named script, so no `pre<name>`/`post<name>` lifecycle hook can fire
+  — structurally and uniformly across **npm, pnpm, and yarn** (classic + berry). Never `<pm> run
+  <name>`, which would re-expose hooks and let a later `package.json` edit change what a byte-exact
+  approved gate runs.
+- **Body allowlist, not blocklist.** The script body must be a string member of a 9-entry literal
+  runner allowlist (`node --test`, `vitest run`, `jest`, `jest --ci`, `eslint .`,
+  `prettier --check .`, `tsc --noEmit`, `tsc -p . --noEmit`, `vite build`) after a pinned
+  ASCII-only normalization; anything else — an injected `curl … | sh`, a `release:npm` alias, an
+  env/path body — is not offered, by non-membership. Editing the allowlist ADDS a test-guarded
+  entry; it can never weaken a filter.
+- **Per-PM fail-closed floor.** npm is pinned `--offline --script-shell /bin/sh` (no registry fetch
+  of a missing runner; a hostile `.npmrc script-shell` loses); the `COREPACK_ENABLE_NETWORK=0`
+  prefix blocks a Corepack-shimmed PM from fetching a hostile `packageManager` pin before exec;
+  pnpm/yarn fail closed natively; a package manager whose exec contract cannot be verified is
+  WITHHELD with a loud note. Screened-out gate-class scripts are counted and named — never silently
+  absent (preview and apply alike).
+- **Preflight parent-chain guard.** `assertDocsAiDeployment` (`atomic-write.mjs`) now walks the
+  `docs` parent chain (refusing a symlinked `docs` parent or cwd root) before any read, closing the
+  seeder's preview-path escape; all four write consumers inherit it. ENOENT-safe — a brand-new
+  project still gets the normal no-deployment stop.
+- **Scoped safety claim.** Safe-by-construction is the OFFER DERIVATION, not a runtime sandbox: a
+  script gate runs the project's own tooling (project-controlled code), the disclosed residual
+  bounded by the two-consent trust chain. The preview discloses it.
+
 ## 1.42.0 — Opt-in ADR-store migration mode + old-layout detection (AD-051)
 
 A **feature** release, co-released with **memory 2.0.0 (MAJOR)** — the one-file-per-ADR store that

package/README.md

@@ -239,12 +239,13 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. `--ledger-summary` (AD-049) appends a COMPUTED review-ledger digest for the single in-flight segment (rounds · origins · classifications · verdicts · overrides — unrelated loops excluded), so the reviewer sees the loop's own history without hand-copying. Prints to stdout; `--out` writes **one scratch file only** (gitignored / outside the repo — a tracked or not-ignored in-repo path is refused). Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit review-ledger` | any time | **review-round ledger** — turns the review-loop stop rule into a **computed** signal: record each plan-execution review round, its triage, and any recorded **overrides** (`oracle-change` lifts named tampered test files; `red-proof` waives the observed-red proof for exactly one `testId`; v4 adds **`size-cap`** — the exact sanctioned magnitude for a surface over the diff cap, segment-scoped — all loud, durable, auditable waivers, never silent) into a JSONL ledger inside the git dir (never committable), and read the stop decision (`converged > resolved-residual > triage-required > continue`) from the records — never from a remembered rule. **Since v4 every record carries `base` = the HEAD commit and the whole loop is SEGMENT-scoped (AD-048):** round numbering, the caps, and every tooth reset ONLY at a gated commit — a multiphase plan records fully while round 4 within one segment stays refused; `gate-run` records (minted by `gates --record`) make gates-before-review a computed precondition; the triage class **`refuted`** is the honest phantom-finding lane (grounds mandatory); `--telemetry` renders counts-only gate-efficacy data across all loops and both ledgers. `--status` replaces the hand-composed per-round tally; `record --from-receipts` (AD-049) DRAFTS the `backends[]` from the current-fingerprint receipts (verdict per backend, counts from the supplied findings) instead of hand-composing them — a recipe-named backend with no receipt is a loud stop; `--check` is a fail-closed gate exit code for `docs/ai/gates.json` (by hand or via the consent-gated seeder). A `fixable-bug` triage **requires its red→green `testId`** (v1..v3 records stay valid on read — old records never enter a segment). The writer refuses a round (past the hard-max, while a triage is pending, or lacking a grounded review receipt) and refuses an override outside its single in-flight loop. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit fold-completeness` | any time | **fold-completeness gate** — attests the review loop's folded fixes were proven the HONEST way (no fix theater): the runner executes your suite ONCE under `NODE_V8_COVERAGE`, checks every changed executable line is **executed**, probes every bound `testId` N times (`AW_FOLD_RERUNS`), records content hashes, and scans the test surface for tamper; the `--red` verb observes a test FAILING on the pre-fold tree — **BEFORE the fix** — and mints an **observed-red receipt**. The read-only checker (`--status` / `--check`) then requires, per bound test: the receipt, receipt-precedes-run order, N/N-green probes, and content **custody** (the green test is byte-identical to the one seen failing) — the receipt+custody half waivable for exactly one `testId` by a recorded `red-proof` override; mixed/timed-out probes are QUARANTINE (never converted, no override); **v3 records carry `base` and the proof is segment-scoped (AD-048)** — a committed phase's custody obligations close with its commit, and a receipt never crosses a commit boundary; tampered pre-existing test files fail closed unless covered by a recorded `oracle-change` override. Honest residuals: coverage proves **execution, not assertion**, and records are forgeable — self-discipline, not a security boundary. v1 scope is JS/V8 (pluggable via `AW_FOLD_BOUND_CMD`): changed TS/JSX fails closed, docs/config changes are listed but never block, and **no mutation testing ships**. Wire the gate by hand — the consent-gated seeder deliberately does not offer it yet (JS-only hold). 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, and the ledger's own class/scope vocabulary) 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 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 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. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
 | `/agent-workflow-kit hook` | Claude Code · opt-in | **gate-approval hook** — places a self-contained PreToolUse hook (`.claude/hooks/`) and wires it into `.claude/settings.json`: a Bash command **byte-identical** to a gate you declared in `docs/ai/gates.json` (run from the project root) is auto-approved — no prompt, no idle; a seeded read-only command carrying a runtime residual (output redirection, command substitution, `--output` writes) now **asks** even where an allow rule would have silently passed it (proven live — hook `ask` overrides an allow rule). Exact matches only, never patterns; never `deny`; a broken `gates.json` only disables auto-approval, never the guard. Preview by default; never writes `settings.local.json`; never commits. |
 | `/agent-workflow-kit bridge-settings` | opt-in, any time | **host-level bridge settings** — read or change the bridges' `KEY=VALUE` config file (`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf`), the **one place a knob survives kit upgrades** (it lives outside every kit tree; a refresh never touches it, and now states loudly if it ever overwrote a local edit). First knobs: the **codex Fast tier** (`CODEX_SERVICE_TIER=priority` — ~1.5× speed at a **2.5× credit rate**, quality-neutral, default off — a consented spend), the codex/agy hard timeouts, the review byte cap, the oversized-review add-dir toggle. Allowed keys + value rules come from the bundled bridge manifests; **model/effort are never settable** (the quality guard is untouched). **Previews by default**; refuses an unknown key, an out-of-range value, or a duplicate-carrying file; writes atomically (symlink/TOCTOU-safe). Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit autonomy-doctor` | opt-in, any time | **guarded sandbox provisioner "doctor"** — can this machine run the Claude sandbox, and (only with your consent) fix it: macOS Seatbelt built-in / Linux+WSL2 needs `bwrap`+`socat` / native Windows → WSL2. Flagless = **FS-only preview** (the diagnosis, the exact absolute-path command it WOULD run, the exact `--apply <pm>:<pkgs>` consent tuple — runs nothing, never claims ready); `--verify` runs the unprivileged proof (a `bwrap` user-namespace smoke + `socat -V`) — the **only** source of a Linux "ready (verified)" claim; `--apply <pm>:<pkgs>` is the consent-gated privileged install (the tuple must equal the previewed plan; everything executed resolves to absolute paths inside `/usr/bin:/bin:/usr/sbin:/sbin`; the exact command is re-printed immediately before execution), then verifies. Honest loud degrades (unknown PM, untrusted location, nested-sandbox INDETERMINATE, root-unproven) and a stated restart step. Sits **outside every velocity auto-approve tier**; never auto-runs, never writes repo files, never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 

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: '1.42.0'
+  version: '1.44.0'
 ---
 
 # agent-workflow-kit
@@ -20,8 +20,7 @@ This kit is the **composition root** of the `agent-workflow` family. The memory
 (`docs/ai/`, the entry-point doc, caps / archive / index, the setup contracts) is owned by
 **`agent-workflow-memory`**. The kit **prefers to delegate** substrate deployment to that skill
 when it is present and healthy, and otherwise uses its **own bundled copy** (`references/`,
-`migrations/`) — so the existing one-command install keeps working with **no new dependency on the
-memory substrate**. (The methodology slot is a separate axis: its fragment is read **live from the
+`migrations/`) — the one-command install stays **dependency-free**. (The methodology slot is a separate axis: its fragment is read **live from the
 installed `agent-workflow-engine`**, which `npx @sabaiway/agent-workflow-kit@latest init` installs;
 see `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md`.)
 `init` also **refreshes the installed memory substrate** (best-effort — a miss is a loud DEGRADED
@@ -50,7 +49,7 @@ made: a partial/broken memory install discovered mid-flow must not disable the w
 > [`tools/delegation.mjs`](${CLAUDE_SKILL_DIR}/tools/delegation.mjs): `detectMemory(<memory-dir>)` runs the validator +
 > the required-asset check and returns `delegate` / fallback with a reason; `handoffPlan(delegate)`
 > returns who writes what, which stamps end up present, and that the commit gate is kit-only. Both
-> are unit-tested, so the contract below is pinned by code, not agent interpretation.
+> are unit-tested — the contract below is pinned by code.
 
 **Hand-off contract & bounded pointer reconciliation** — `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md` (read at the bootstrap/upgrade point of use).
 
@@ -63,25 +62,26 @@ ever deleted.
 
 ## Modes
 
-Pick the mode from the user's invocation — the mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested; safe-routing rule below). An existing `docs/ai/` guards against bootstrapping over a live system — the user makes the final call.
+Pick the mode from the user's invocation — the mapping is pinned by `tools/commands.mjs` `routeInvocation` (safe-routing rule below). An existing `docs/ai/` guards against bootstrapping over a live system.
 
 ### Version status & the two axes — the internal routing check
 
-**Safe-routing rule (which mode did the user invoke?).** Map the invocation token with `tools/commands.mjs` `routeInvocation`: a **known** subcommand → its mode; the **bare/empty** invocation → `bootstrap` — the one writer reachable without a token, and only on an undeployed project (if `docs/ai/` already exists, **ask upgrade-vs-bootstrap**, never overwrite); **any unrecognized/ambiguous** token → `help`, which is **read-only**. The invariant: **no unrecognized/garbage invocation ever triggers a write** (only an explicit known token or the acknowledged bare-bootstrap exception can). The mapping is unit-tested, so it is not left to interpretation.
+**Safe-routing rule (which mode did the user invoke?).** Map the invocation token with `tools/commands.mjs` `routeInvocation`: a **known** subcommand → its mode; the **bare/empty** invocation → `bootstrap` — the one writer reachable without a token, and only on an undeployed project (if `docs/ai/` already exists, **ask upgrade-vs-bootstrap**, never overwrite); **any unrecognized/ambiguous** token → `help`, which is **read-only**. The invariant: **no unrecognized/garbage invocation ever triggers a write** (only an explicit known token or the acknowledged bare-bootstrap exception can).
 
-Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide the route — this is an **internal** routing decision, **not** a line you print to the user (the number itself is shown only per *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Route:
+Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide the route — an **internal** routing decision, **not** a line you print (version display: *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Route:
 
 - **absent** → bootstrap (a fresh deployment).
 - **stamp < `2.0.0`** (the deployment-lineage head) → `upgrade`.
 - **stamp == `2.0.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3; run step 3 (never enumerate the reconciles from memory).
 - **stamp > head / unparseable** → STOP — never-downgrade gate (see `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 2).
+- **Exempt:** `autonomy-doctor` provisions the OS, not the deployment — stamp-independent (stated in its mode file).
 
 **Two independent version axes — never conflate them:**
 
 1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`2.0.0`). This is the **only** axis this skill compares.
 2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version is **not** the lineage head.
 
-**Refreshed the kit but nothing changed?** After `npx @sabaiway/agent-workflow-kit@latest init` updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files.
+**Refreshed the kit but nothing changed?** After the npx installer updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files.
 
 ### Mode: help
 
@@ -127,6 +127,10 @@ writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md` before acti
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-autonomy.md` before acting.
 
+### Mode: autonomy-doctor
+
+guarded — read `${CLAUDE_SKILL_DIR}/references/modes/autonomy-doctor.md` before acting.
+
 ### Mode: uninstall
 
 guarded — read `${CLAUDE_SKILL_DIR}/references/modes/uninstall.md` before acting.

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.42.0",
+  "version": "1.44.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/modes/autonomy-doctor.md

@@ -0,0 +1,21 @@
+### Mode: autonomy-doctor
+
+The **sandbox provisioner "doctor"** — the answer to *"can this machine run the Claude sandbox, and can you fix it?"* (AD-044: macOS Seatbelt built-in / Linux+WSL2 `bwrap`+`socat` / native Windows → WSL2). **Division of labor:** YOU narrate the diagnosis and relay the consent question; the KIT does the deterministic detect → consent-gated install → verify. It is **guarded**: the privileged lane runs ONLY with the per-run consent tuple, always faces the harness permission prompt (the mode sits outside every velocity auto-approve tier), **never auto-runs, never writes repo files, and never commits**.
+
+Run **`node ${CLAUDE_SKILL_DIR}/tools/autonomy-doctor.mjs [--verify | --apply <pm>:<pkg[,pkg...]>]`**:
+
+1. **Flagless = FS-only preview** (the default; runs NO subprocesses): the diagnosis, the exact absolute-path command the doctor WOULD run, and the exact `--apply <pm>:<pkgs>` consent line. It **never claims "ready"** — binaries present without proof render `present-unverified`, never exit `0`.
+2. **`--verify`** — the unprivileged diagnostic: a `bwrap` user-namespace smoke plus `socat -V` (captured stdio). This is the ONLY source of a Linux **ready-verified** claim. Honesty split: a green verify proves the **OS primitives, not Claude-init** — the output always states the restart step. Under root/`SUDO_UID` the verified claim is REFUSED (`root-unproven`); a namespace-denied smoke with present binaries reports a loud `indeterminate` (nested sandboxing / already inside a container — re-run from an unsandboxed shell).
+3. **`--apply <pm>:<pkgs>`** — the consent-gated privileged install: the tuple must EQUAL the re-derived plan (consent binds to the previewed plan; a mismatch or a bare `--apply` refuses with `2` usage and runs NOTHING), the exact resolved command is re-printed immediately before execution, then the verify lane runs automatically. Sudo boundary: root drops sudo; a passwordless sudo proceeds with a LOUD note; a password-needing sudo without a controlling terminal runs NOTHING and prints the exact command to run in the USER's terminal (`handoff-required`).
+
+**Trust gate:** everything executed resolves to an ABSOLUTE path inside the fixed trusted dirs `/usr/bin:/bin:/usr/sbin:/sbin` (`/usr/local/bin` deliberately excluded); a binary or package manager found only outside is a loud `untrusted-path` / `unknown-pm` degrade, never executed. The privileged child gets a minimal scrubbed env (trusted-dir PATH + LANG), an argv array, no shell. Package names come from a frozen internal map (`bubblewrap`, `socat`); apt runs through the env trampoline (`env DEBIAN_FRONTEND=noninteractive …`) so non-interactivity survives sudo's `env_reset`.
+
+**Exit codes (frozen):** `0` ready (`ready-verified` / `ready-assumed`; Linux only via the verify oracle) · `1` precondition STOP (`no-deployment`) · `2` usage (bare `--apply`, tuple mismatch, unknown flag) · `3` not-ready diagnosis (`missing-binaries` offer / `present-unverified` / `handoff-required`) · `4` install failed (`install-failed`) · `5` verify failed (`verify-failed` / `indeterminate` / `root-unproven`) · `6` unsupported / untrusted (`unsupported-platform` win32 / `unknown-pm` / `untrusted-path`). The machine summary line prints LAST in every diagnosis outcome (`--help` prints the help text alone): `[autonomy-doctor] status=<token> platform=<p> missing=<csv> pm=<name|none>`.
+
+**Stamp EXEMPTION (stated, deliberate):** the doctor runs behind the docs/ai presence gate ahead of every lane (`--help` and parse-time usage errors return earlier) but has **NO `.workflow-version` stamp gate** — it provisions the OS, never lineage-bound repo content, so the global stale-deployment→upgrade routing does not apply to this mode.
+
+**Residuals (disclosed in the preview):** a root-owned hostile binary inside the trusted dirs is out of the threat model; Claude itself resolves `bwrap`/`socat` via PATH at session init (the doctor warns on a PATH shadow, never fixes PATH); the harness permission prompt shows the `--apply` tuple, not the absolute-path command — bridged by the apply-time re-print.
+
+Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
+
+**Invariants:** guarded (the MUTATING lane only via `--apply` with the matching tuple, exactly once) · preview-first · never auto-runs · outside every velocity auto-approve tier · never writes repo files · never commits · loud degrades, never silent.

package/references/modes/doc-parity.md

@@ -9,7 +9,8 @@ The DOC-PARITY lint (BUGFREE-3 / AD-049, session-economics item (b)) — the det
 
 **What it checks (the closed registry).** The numeric/version tokens are IMPORTED live from the tools — never re-typed in the lint — so the registry itself can never go stale:
 - `references/modes/review-ledger.md` carries `SCHEMA_VERSION` (schema v4), `HARD_MAX` (the hard-max ceiling of 3), `DEFAULT_DIFF_CAP` (the default 400 diff cap), `REVIEW_CAP` (cap ≤2), and the ledger vocabulary sourced from the schema's own `V4_CLASSES` / `V4_OVERRIDE_SCOPES` Sets plus the `gate-run` kind (`size-cap`, `refuted`, `gate-run`, `red-proof`, `oracle-change`, `fixable-bug`, `inherent-layer-residual`, `escalate`);
-- `references/modes/fold-completeness.md` carries `RESULT_SCHEMA_VERSION` (fold RESULT schema v4).
+- `references/modes/fold-completeness.md` carries `RESULT_SCHEMA_VERSION` (fold RESULT schema v4);
+- `references/modes/autonomy-doctor.md` carries the doctor's frozen D7 contract (AD-044 Plan 2): every live EXIT-table phrase (`` `0` ready `` … `` `6` unsupported / untrusted ``), every status token (sourced from the exported `STATUS`), and the trusted-dir allowlist (`TRUSTED_DIRS`).
 
 **Why the modes/*.md docs and NOT the tool HELP strings.** Every tool's HELP INTERPOLATES the same constant (`the ${DEFAULT_DIFF_CAP}-line diff cap`), so it can never drift from the code — there is nothing to check there. The hand-authored contract prose in `references/modes/*.md` is the surface that DOES drift, so that is exactly what this lint pins. Change a constant and the current-value token stops appearing in the lagging doc → the gate fails, forcing the doc update **in the same edit as the code** (the §2.6 "contract docs change in the same edit as code" rule, mechanized).
 

package/references/modes/gates.md

@@ -16,6 +16,6 @@ Declared gates can also be **auto-approved** (no permission prompt on a byte-exa
 
 **Candidate line — the review-receipt gate (opt-in, never auto-seeded; AD-021).** Projects that configure a reviewed/council `plan-execution.review` recipe can declare the AD-038 review-state check as one more gate — the exact candidate `{ id, title, cmd }` line and its contract live under `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` (step 3). The template `gates.json` stays EMPTY; adding the line is the maintainer's explicit consent — by hand, or through the consent-gated seeder below (AD-042).
 
-**Consent-gated seeding — a separate WRITER CLI, not part of the runner (AD-042).** Bootstrap recon already records the project's own daily commands; the seeder turns them into a preview of `{ id, title, cmd }` entries. Protocol: run `node ${CLAUDE_SKILL_DIR}/tools/seed-gates.mjs --cwd <project>` (dry-run by default — prints the derived entries and **writes NOTHING**; declining leaves the file byte-identical), show the user the EXACT entries (`AskUserQuestion` preview where supported, prose otherwise), and only on an explicit yes run it again with `--apply [--only <id>]…` — it **appends exactly the consented entries** (append-only: existing entries are never modified or removed; an id collision is refused loudly; a malformed declaration is never written over). Only terminating verification commands are offered (test / lint / type-check / build — never dev/watch/serve, never a formatter write-mode, never a release/publish/deploy script), commands are package-manager-aware, and the review-state candidate above is included automatically when the project's orchestration config declares reviewed/council on `plan-execution.review`. **Disclose before the yes** (the preview prints it): once the approval hook is wired, it auto-approves byte-exact declared gate commands — seeding and hook wiring are two separate consents.
+**Consent-gated seeding — a separate WRITER CLI, not part of the runner (AD-042).** Bootstrap recon already records the project's own daily commands; the seeder turns them into a preview of `{ id, title, cmd }` entries. Protocol: run `node ${CLAUDE_SKILL_DIR}/tools/seed-gates.mjs --cwd <project>` (dry-run by default — prints the derived entries and **writes NOTHING**; declining leaves the file byte-identical), show the user the EXACT entries (`AskUserQuestion` preview where supported, prose otherwise), and only on an explicit yes run it again with `--apply [--only <id>]…` — it **appends exactly the consented entries** (append-only: existing entries are never modified or removed; an id collision is refused loudly; a malformed declaration is never written over). The offer is **closed-world** (AD-052): only a terminating-class script NAME (test / lint / type-check / build — never dev/watch/serve, never a write-mode or release/publish/deploy variant) whose BODY is a member of the seeder's literal runner allowlist is offered — membership, never blocklist screening: the worst case is a legit command not offered, never a dangerous one offered. The seeded cmd is the uniform hook-free **`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>`** — `exec` runs a command, not a named script, so no pre/post hook can fire (npm/pnpm/yarn alike; never `<pm> run <name>`, which re-exposes hooks), and the Corepack env prefix blocks a hostile `packageManager` pin from fetching the PM binary before exec. npm is pinned `--offline --script-shell /bin/sh` (no fetch of a missing runner; a hostile `.npmrc script-shell` loses); pnpm/yarn refuse an absent runner without network (a user-installed cache/global/PATH runner executing is user machine state — part of the disclosed residual); a family without a verified fail-closed exec contract is WITHHELD loudly. A gate-class script screened out on its BODY is counted and named in a note (add it by hand if you trust it); the review-state candidate above joins automatically on a reviewed/council `plan-execution.review`. **Disclose before the yes** (the preview prints it): the wired hook auto-approves byte-exact declared commands — two separate consents — and a script gate runs project-controlled tooling the seeder does not sandbox (safe-by-construction = the OFFER DERIVATION).
 
 **Invariants:** the runner writes nothing by default (`--record` delegates its ONE ledger write to the review-ledger sole writer, `recordGateRun` — the runner itself never opens the ledger) · never commits · never runs a subscription CLI · executes only the project's OWN declared commands (never a kit-invented one) · the bash contract fails loud, never reinterprets · the seeder is a separate consent-per-run CLI — preview-first, append-only, never pre-approved by any velocity tier.

package/tools/atomic-write.mjs

@@ -53,6 +53,19 @@ export const assertDocsAiDeployment = (cwd, deps = {}, opts = {}) => {
   const noun = opts.noun ?? 'a file';
   const rel = opts.rel ?? 'under docs/ai';
   const docsAi = join(cwd, 'docs', 'ai');
+  // Parent-chain preflight (AD-052, Issue-011 residual 3): refuse a symlinked cwd ROOT or a
+  // symlinked `docs` PARENT before any read — the walk the write path already enforces
+  // (writeContainedFileAtomic), aligned onto the gate every consumer runs first. The walk covers
+  // the PARENT chain only (the linkManaged precedent, fs-safe.mjs): the docs/ai LEAF keeps the
+  // dedicated checks below, whose exact STOP messages each consumer's tests pin. ENOENT-safe —
+  // an absent component is a no-op walk, so a brand-new project still reaches the normal
+  // "no deployment" STOP below. The walk throws a plain Error; re-throw as the CALLER's typed
+  // stop so every consumer's `.code` contract holds.
+  try {
+    assertContainedRealPath(cwd, join(cwd, 'docs'), { lstat });
+  } catch (err) {
+    throw stop(String(err?.message ?? err).replace(/^\[agent-workflow-kit\] /, ''));
+  }
   const docsAiStat = lstatNoFollow(docsAi, lstat);
   if (docsAiStat === null) {
     throw stop(`no agent-workflow deployment here (docs/ai is absent) — run init/bootstrap before writing ${rel}`);

package/tools/autonomy-doctor.mjs

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+// autonomy-doctor.mjs — the cross-platform sandbox provisioner "doctor" (AD-044 Plan 2; mode:
+// autonomy-doctor, GUARDED). Detect → consent-gated install → verify → loud degrade, for the
+// AD-044 sandbox matrix: macOS Seatbelt built-in / Linux+WSL2 bwrap+socat / native Windows → WSL2.
+//
+// THREE lanes:
+//   (flagless)          FS-only preview: diagnosis + the exact command it WOULD run + the exact
+//                       --apply consent tuple. ZERO subprocesses. Never claims "ready".
+//   --verify            unprivileged diagnostic: bwrap userns smoke + `socat -V` (captured stdio,
+//                       DIAGNOSTIC runner). The ONLY source of a Linux "ready (verified)" claim.
+//   --apply <pm>:<pkgs> consent-gated privileged install. The tuple must EQUAL the re-derived
+//                       plan (consent binds to the previewed plan; mismatch → refuse, runs
+//                       NOTHING), then the verify lane runs automatically.
+//
+// Trust gate (D2/D3): everything the doctor EXECUTES resolves to an ABSOLUTE path inside the
+// FIXED trusted dirs /usr/bin:/bin:/usr/sbin:/sbin (isExecutableFile — statSync follows an
+// in-dir symlink; /usr/local/bin deliberately excluded). A binary found only outside → loud
+// degrade naming its location, never executed. The privileged child gets a minimal SCRUBBED env
+// (trusted-dir PATH + LANG), argv array, no shell, stdio ['ignore','inherit','inherit'].
+//
+// Gating (D8): docs/ai deployment presence on EVERY run. NO .workflow-version stamp gate — the
+// doctor mutates the OS, never lineage-bound repo content (the stated stamp EXEMPTION).
+//
+// Exit codes (D7, frozen): 0 ready (ready-verified / ready-assumed; Linux only via the verify
+// oracle) · 1 precondition STOP (no-deployment) · 2 usage (bare --apply, tuple mismatch, unknown
+// flag) · 3 not-ready diagnosis (missing-binaries offer / present-unverified / handoff-required)
+// · 4 install failed · 5 verify failed / indeterminate / root-unproven · 6 unsupported/untrusted
+// (win32 / unknown PM / found-only-outside-trusted-dirs). The machine summary line prints LAST in
+// every diagnosis outcome (--help prints the help text alone):
+// [autonomy-doctor] status=<token> platform=<p> missing=<csv> pm=<name|none>.
+//
+// Residual disclosure (D9, shipped in the preview): (i) a root-owned hostile binary inside the
+// trusted dirs = the host is already lost (out of threat model); (ii) Claude itself resolves
+// bwrap/socat via PATH at session init — the doctor verifies the trusted-dir copies and WARNS on
+// a PATH shadow, never fixes it; (iii) the harness permission prompt shows the --apply tuple, not
+// the absolute-path command — bridged by the apply-time re-print of the exact resolved command.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { spawnSync } from 'node:child_process';
+import { closeSync, lstatSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isExecutableFile, probeSandboxAvailability } from './velocity-profile.mjs';
+import { assertDocsAiDeployment } from './atomic-write.mjs';
+
+// ── the frozen contract tables (fixtures the tests copy) ────────────────────────────
+
+export const TRUSTED_DIRS = Object.freeze(['/usr/bin', '/bin', '/usr/sbin', '/sbin']);
+const TRUSTED_PATH = TRUSTED_DIRS.join(':');
+
+// The closed world of sandbox binaries → package names. Keys double as the binary list (the
+// probe's SANDBOX_LINUX_BINARIES mirror); no repo/config/user input ever enters a command line.
+export const PACKAGE_FOR = Object.freeze({ bwrap: 'bubblewrap', socat: 'socat' });
+
+export const EXIT = Object.freeze({
+  ready: 0,
+  stop: 1,
+  usage: 2,
+  notReady: 3,
+  installFailed: 4,
+  verifyFailed: 5,
+  unsupported: 6,
+});
+
+export const STATUS = Object.freeze({
+  readyVerified: 'ready-verified',
+  readyAssumed: 'ready-assumed',
+  noDeployment: 'no-deployment',
+  usage: 'usage',
+  missingBinaries: 'missing-binaries',
+  presentUnverified: 'present-unverified',
+  handoffRequired: 'handoff-required',
+  installFailed: 'install-failed',
+  verifyFailed: 'verify-failed',
+  indeterminate: 'indeterminate',
+  rootUnproven: 'root-unproven',
+  unsupportedPlatform: 'unsupported-platform',
+  unknownPm: 'unknown-pm',
+  untrustedPath: 'untrusted-path',
+});
+
+export const EXIT_FOR_STATUS = Object.freeze({
+  [STATUS.readyVerified]: EXIT.ready,
+  [STATUS.readyAssumed]: EXIT.ready,
+  [STATUS.noDeployment]: EXIT.stop,
+  [STATUS.usage]: EXIT.usage,
+  [STATUS.missingBinaries]: EXIT.notReady,
+  [STATUS.presentUnverified]: EXIT.notReady,
+  [STATUS.handoffRequired]: EXIT.notReady,
+  [STATUS.installFailed]: EXIT.installFailed,
+  [STATUS.verifyFailed]: EXIT.verifyFailed,
+  [STATUS.indeterminate]: EXIT.verifyFailed,
+  [STATUS.rootUnproven]: EXIT.verifyFailed,
+  [STATUS.unsupportedPlatform]: EXIT.unsupported,
+  [STATUS.unknownPm]: EXIT.unsupported,
+  [STATUS.untrustedPath]: EXIT.unsupported,
+});
+
+// The MUTATING stdio contract: sudo prompts on /dev/tty (never stdin), no PM can block on stdin.
+export const MUTATING_STDIO = Object.freeze(['ignore', 'inherit', 'inherit']);
+
+// The frozen 4-family install map (D3, closed world). First-present in the trusted dirs wins.
+// Every executable token in the built argv is a D2-resolved ABSOLUTE trusted-dir path — apt's
+// non-interactivity rides the env TRAMPOLINE (env is the command sudo runs, so sudo env_reset
+// cannot strip DEBIAN_FRONTEND; a bare `apt-get` after env would hand resolution back to PATH).
+const PM_FAMILIES = Object.freeze([
+  Object.freeze({ name: 'apt-get', needsEnvTrampoline: true }),
+  Object.freeze({ name: 'dnf', needsEnvTrampoline: false }),
+  Object.freeze({ name: 'pacman', needsEnvTrampoline: false }),
+  Object.freeze({ name: 'apk', needsEnvTrampoline: false }),
+]);
+
+const buildFamilyArgv = (family, pmPath, envPath, packages) => {
+  if (family.name === 'apt-get') return [envPath, 'DEBIAN_FRONTEND=noninteractive', pmPath, 'install', '-y', ...packages];
+  if (family.name === 'dnf') return [pmPath, 'install', '-y', ...packages];
+  if (family.name === 'pacman') return [pmPath, '-S', '--needed', '--noconfirm', ...packages];
+  return [pmPath, 'add', ...packages];
+};
+
+// The bwrap userns smoke (D5) — HOST-PROVEN fixture 2026-07-10 (WSL2, bwrap 0.9.0): the payload is
+// process.execPath (injectable; `--ro-bind / /` makes it reachable — no /bin/true assumption).
+export const buildSmokeArgv = (bwrapPath, execPath) =>
+  Object.freeze([bwrapPath, '--unshare-all', '--die-with-parent', '--ro-bind', '/', '/', execPath, '--version']);
+
+// A smoke stderr that matches this WITH present binaries is the namespace-denied signature —
+// LOUD INDETERMINATE (nested sandboxing / already inside a container), never an install offer.
+const NAMESPACE_DENIED_RE = /operation not permitted|permission denied|no permissions to creat/i;
+
+const D9_DISCLOSURE = [
+  'Residual disclosure (D9):',
+  '  (i)  a root-owned hostile binary inside the trusted dirs means the host is already lost — out of this doctor\'s threat model.',
+  `  (ii) Claude itself resolves bwrap/socat via PATH at session init — the doctor verifies the trusted-dir copies (${TRUSTED_PATH}) and WARNS on a PATH shadow; it never fixes PATH.`,
+  '  (iii) the harness permission prompt shows the --apply <pm>:<pkgs> tuple, not the absolute-path command — bridged by the apply-time re-print of the exact resolved command.',
+];
+
+const RESTART_NOTE =
+  'Restart Claude Code now — the sandbox is detected only at session start; a fresh session is the behavioral proof.';
+const VERIFY_HONESTY =
+  'Honesty: a green verify proves the OS sandbox primitives (bwrap user namespaces + socat), NOT that Claude initialized its sandbox.';
+const WSL2_REDIRECT =
+  'native Windows is unsupported — run Claude Code inside WSL2 (Ubuntu) and re-run the doctor there.';
+const SEATBELT_NOTE = 'macOS: Seatbelt assumed built-in — not smoke-tested by this doctor.';
+
+const USAGE_HINT =
+  'usage: autonomy-doctor.mjs [--verify | --apply <pm>:<pkg[,pkg...]>]  (flagless = FS-only preview)';
+
+const HELP = `autonomy-doctor — sandbox provisioner doctor (detect → consent-gated install → verify).
+
+Usage:
+  node autonomy-doctor.mjs                      FS-only preview (diagnosis + the exact plan; runs NOTHING)
+  node autonomy-doctor.mjs --verify             unprivileged diagnostic: bwrap userns smoke + socat -V
+  node autonomy-doctor.mjs --apply <pm>:<pkgs>  consent-gated install (tuple must equal the previewed plan),
+                                                then the verify lane runs automatically
+  --help, -h                                    this help
+
+Consent contract: --apply REQUIRES the <pm>:<pkg,...> tuple the preview printed — a mismatch vs the
+re-derived plan refuses (exit 2) and runs NOTHING. Everything executed resolves to an absolute path
+inside the trusted dirs ${TRUSTED_PATH}; the exact resolved command is re-printed immediately
+before execution. The doctor never writes repo files and never commits.
+
+Exit codes: 0 ready (ready-verified / ready-assumed) · 1 precondition STOP (no docs/ai deployment) ·
+2 usage · 3 not-ready diagnosis · 4 install failed · 5 verify failed/indeterminate/root-unproven ·
+6 unsupported/untrusted. The last line of every diagnosis outcome is the machine summary:
+[autonomy-doctor] status=<token> platform=<p> missing=<csv> pm=<name|none>
+(--help prints this help text alone — no summary line.)`;
+
+// ── small pure helpers ───────────────────────────────────────────────────────────────
+
+const NO_MISSING = '-';
+export const composeSummaryLine = ({ status, platform, missing = [], pm = null }) =>
+  `[autonomy-doctor] status=${status} platform=${platform} missing=${missing.length > 0 ? missing.join(',') : NO_MISSING} pm=${pm ?? 'none'}`;
+
+const resolveTrusted = (name, isExec) => TRUSTED_DIRS.map((dir) => join(dir, name)).find((p) => isExec(p)) ?? null;
+
+const findFirstPathHit = (name, env, isExec) =>
+  ((env && env.PATH) || '').split(':').filter(Boolean).map((dir) => join(dir, name)).find((p) => isExec(p)) ?? null;
+
+export const hasControllingTerminal = () => {
+  try {
+    closeSync(openSync('/dev/tty', 'r'));
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// ── the pure planner core (diagnosis + plan + tuple as DATA; no subprocesses) ─────────
+
+export const deriveDoctorPlan = ({ probeResult, env, isExec }) => {
+  const missing = probeResult.missing ?? [];
+  const packages = missing.map((binary) => PACKAGE_FOR[binary]);
+  const resolutions = Object.keys(PACKAGE_FOR).map((name) => {
+    const trusted = resolveTrusted(name, isExec);
+    const pathHit = findFirstPathHit(name, env, isExec);
+    return { name, trusted, pathHit, missing: missing.includes(name) };
+  });
+  const shadows = resolutions.filter((r) => !r.missing && r.trusted !== null && r.pathHit !== null && r.pathHit !== r.trusted);
+  const untrusted = resolutions.filter((r) => !r.missing && r.trusted === null);
+  const family = PM_FAMILIES.map((f) => ({ family: f, path: resolveTrusted(f.name, isExec) })).find((f) => f.path !== null) ?? null;
+  const envPath = resolveTrusted('env', isExec);
+  const pm = family === null ? null : { name: family.family.name, path: family.path };
+  const envMissing = family !== null && family.family.needsEnvTrampoline && envPath === null;
+  const tuple = pm !== null && missing.length > 0 ? `${pm.name}:${packages.join(',')}` : null;
+  const rootArgv = pm === null || missing.length === 0 || envMissing
+    ? null
+    : buildFamilyArgv(family.family, pm.path, envPath, packages);
+  return { missing, packages, resolutions, shadows, untrusted, pm, envMissing, tuple, rootArgv };
+};
+
+// ── argv parsing (usage errors carry exitCode 2 via the shared idiom) ─────────────────
+
+const usageFail = (message) => Object.assign(new Error(message), { exitCode: EXIT.usage });
+
+export const parseDoctorArgs = (argv) => {
+  let lane = 'preview';
+  let tuple = null;
+  const setLane = (next) => {
+    if (lane !== 'preview') throw usageFail('pass at most ONE of --verify / --apply');
+    lane = next;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { lane: 'help', tuple: null };
+    if (arg === '--verify') setLane('verify');
+    else if (arg === '--apply' || arg.startsWith('--apply=')) {
+      const raw = arg === '--apply' ? argv[(i += 1)] : arg.slice('--apply='.length);
+      if (raw === undefined || raw === '' || raw.startsWith('--')) {
+        throw usageFail('--apply requires the consent tuple <pm>:<pkg[,pkg...]> the preview printed (a bare --apply is refused)');
+      }
+      if (!/^[^:\s]+:[^:\s]+$/.test(raw)) throw usageFail(`--apply tuple "${raw}" is not <pm>:<pkg[,pkg...]>`);
+      setLane('apply');
+      tuple = raw;
+    } else throw usageFail(`unknown flag: ${arg}`);
+  }
+  return { lane, tuple };
+};
+
+// ── rendering ─────────────────────────────────────────────────────────────────────────
+
+const renderDiagnosis = ({ plan, probeResult, log }) => {
+  log('autonomy-doctor — Linux sandbox diagnosis (bwrap + socat)');
+  log(`  probe: ${probeResult.reason}`);
+  for (const r of plan.resolutions) {
+    if (r.missing && r.trusted !== null) {
+      log(`  ${r.name}: NOT on PATH (the probe follows Claude's own PATH resolution) but present at ${r.trusted} — fix your PATH rather than re-installing.`);
+    } else if (r.missing) log(`  ${r.name}: MISSING`);
+    else if (r.trusted === null) {
+      log(`  ${r.name}: found ONLY at ${r.pathHit} — NOT in the trusted dirs (${TRUSTED_PATH}); the doctor will never execute it`);
+    } else log(`  ${r.name}: ${r.trusted}`);
+  }
+  for (const s of plan.shadows) {
+    log(`  PATH-SHADOW WARNING: ${s.name} first resolves on PATH at ${s.pathHit}, not the trusted ${s.trusted} — Claude will resolve the PATH one at session init (the D9 residual); the doctor verifies only the trusted copy.`);
+  }
+};
+
+// The untrusted degrade every lane runs FIRST (codex R1): while any sandbox binary resolves only
+// outside the trusted dirs, no offer, no consent invitation, and no privileged path may proceed —
+// an install cannot make such a host verify-ready.
+const refuseUntrusted = ({ plan, log }) => {
+  for (const r of plan.untrusted) {
+    log(`${r.name} found ONLY at ${r.pathHit} — NOT in the trusted dirs (${TRUSTED_PATH}); refusing every install/verify path until a trusted copy exists (loud degrade, D2).`);
+  }
+  return STATUS.untrustedPath;
+};
+
+// The install offer (flagless + --verify share it). Returns the status token for the missing case.
+const renderOffer = ({ plan, euid, isExec, env, log }) => {
+  if (plan.untrusted.length > 0) return refuseUntrusted({ plan, log });
+  if (plan.pm === null) {
+    const packages = plan.packages.join(' + ');
+    const outside = PM_FAMILIES
+      .map((f) => ({ name: f.name, hit: findFirstPathHit(f.name, env, isExec) }))
+      .filter((f) => f.hit !== null);
+    if (outside.length > 0) {
+      log(`package manager found ONLY outside the trusted dirs (${outside.map((f) => `${f.name} at ${f.hit}`).join('; ')}) — refusing to execute it (loud degrade, D3); install ${packages} manually, then re-run --verify.`);
+      return STATUS.untrustedPath;
+    }
+    log(`no supported package manager found in the trusted dirs (supported: ${PM_FAMILIES.map((f) => f.name).join(', ')}) — install ${packages} manually with your PM, then re-run --verify. (zypper et al. are deliberate omissions — a stated degrade, never a guess.)`);
+    return STATUS.unknownPm;
+  }
+  if (plan.envMissing) {
+    log(`env not found in the trusted dirs (${TRUSTED_PATH}) — the apt non-interactivity trampoline cannot be built; install ${plan.packages.join(' + ')} manually, then re-run --verify.`);
+    return STATUS.untrustedPath;
+  }
+  log(`  missing: ${plan.missing.join(', ')} → package(s): ${plan.packages.join(', ')} (via ${plan.pm.name})`);
+  const sudoTrusted = resolveTrusted('sudo', isExec);
+  const printedArgv = euid === 0 || sudoTrusted === null ? plan.rootArgv : [sudoTrusted, ...plan.rootArgv];
+  log('  with your consent the doctor WOULD run exactly:');
+  log(`    ${printedArgv.join(' ')}`);
+  if (euid !== 0 && sudoTrusted === null) {
+    const sudoOnPath = findFirstPathHit('sudo', env, isExec);
+    log(sudoOnPath === null
+      ? '  (no sudo in the trusted dirs — the command above is the ROOT form; run it as root)'
+      : `  (sudo found only at ${sudoOnPath} — NOT in the trusted dirs; the command above is the ROOT form)`);
+  }
+  log(`  consent: re-run with  --apply ${plan.tuple}   (the tuple binds consent to exactly this plan)`);
+  return STATUS.missingBinaries;
+};
+
+// ── the verify lane (D5 — the ONE ready predicate; shared by --verify and post-apply) ──
+
+const runVerifyLane = ({ plan, ctx }) => {
+  const { log, isExec, env, euid, execPath, diagnosticRunner, scrubbedEnv } = ctx;
+  if (plan.untrusted.length > 0) return refuseUntrusted({ plan, log });
+  if (plan.missing.length > 0) return renderOffer({ plan, euid, isExec, env, log });
+  if (euid === 0 || (env && env.SUDO_UID)) {
+    log('refusing the "verified" claim: running as root (euid 0 / SUDO_UID set) — a green smoke under root does NOT prove UNPRIVILEGED user namespaces. Re-run --verify as your normal user.');
+    return STATUS.rootUnproven;
+  }
+  const bwrapPath = plan.resolutions.find((r) => r.name === 'bwrap').trusted;
+  const socatPath = plan.resolutions.find((r) => r.name === 'socat').trusted;
+  const smoke = diagnosticRunner({ argv: [...buildSmokeArgv(bwrapPath, execPath)], env: scrubbedEnv, stdio: 'pipe' });
+  if (smoke.error) {
+    log(`bwrap smoke could not SPAWN (${smoke.error.code ?? smoke.error.message}) — the binary resolved but did not execute.`);
+    return STATUS.verifyFailed;
+  }
+  if (smoke.status !== 0) {
+    const stderr = smoke.stderr ?? '';
+    if (stderr) log(stderr.replace(/\n$/, ''));
+    if (NAMESPACE_DENIED_RE.test(stderr)) {
+      log('verify INDETERMINATE: the userns smoke was DENIED while the binaries are present — likely cause: nested sandboxing / already inside a container (a green probe cannot distinguish this). Re-run --verify from an unsandboxed shell.');
+      return STATUS.indeterminate;
+    }
+    log(`bwrap userns smoke FAILED (exit ${smoke.status}). The binaries are PRESENT — this is NOT an install problem, so re-installing will not fix it: check unprivileged user namespaces (userns sysctl / AppArmor restrictions) and that this host is WSL2, not WSL1.`);
+    return STATUS.verifyFailed;
+  }
+  const socat = diagnosticRunner({ argv: [socatPath, '-V'], env: scrubbedEnv, stdio: 'pipe' });
+  if (socat.error || socat.status !== 0) {
+    if (socat.stderr) log(socat.stderr.replace(/\n$/, ''));
+    log(socat.error
+      ? `socat -V could not SPAWN (${socat.error.code ?? socat.error.message}).`
+      : `socat -V FAILED (exit ${socat.status}) — the binary is present but not functional; not an install-missing problem.`);
+    return STATUS.verifyFailed;
+  }
+  log('ready (verified): probe green + bwrap userns smoke green + socat -V green — nothing to install.');
+  log(VERIFY_HONESTY);
+  log(RESTART_NOTE);
+  return STATUS.readyVerified;
+};
+
+// ── the apply lane (the ONE place the MUTATING runner may be invoked, exactly once) ───
+
+const runApplyLane = ({ plan, tuple, ctx }) => {
+  const { log, isExec, env, euid, diagnosticRunner, mutatingRunner, scrubbedEnv, isTTYOf } = ctx;
+  if (plan.untrusted.length > 0) return { status: refuseUntrusted({ plan, log }), finalPlan: plan };
+  if (plan.missing.length === 0) {
+    log(`consent REFUSED: the re-derived plan is EMPTY (nothing missing) — the tuple "${tuple}" matches no plan. Nothing was run or installed; run --verify for the ready proof.`);
+    return { status: STATUS.usage, finalPlan: plan };
+  }
+  if (plan.pm === null || plan.envMissing) return { status: renderOffer({ plan, euid, isExec, env, log }), finalPlan: plan };
+  if (tuple !== plan.tuple) {
+    log(`consent REFUSED: tuple mismatch — given "${tuple}", the current diagnosis derives "${plan.tuple}". Nothing was run; re-run flagless to preview, then --apply with the derived tuple.`);
+    return { status: STATUS.usage, finalPlan: plan };
+  }
+  let execArgv = plan.rootArgv;
+  if (euid !== 0) {
+    const sudoTrusted = resolveTrusted('sudo', isExec);
+    if (sudoTrusted === null) {
+      const sudoOnPath = findFirstPathHit('sudo', env, isExec);
+      if (sudoOnPath !== null) {
+        log(`sudo found ONLY at ${sudoOnPath} — NOT in the trusted dirs (${TRUSTED_PATH}); refusing to execute it.`);
+        return { status: STATUS.untrustedPath, finalPlan: plan };
+      }
+      log('sudo is not available — run this as ROOT in your terminal, then re-run --verify:');
+      log(`  ${plan.rootArgv.join(' ')}`);
+      return { status: STATUS.handoffRequired, finalPlan: plan };
+    }
+    const preflight = diagnosticRunner({ argv: [sudoTrusted, '-n', 'true'], env: scrubbedEnv, stdio: 'pipe' });
+    const preflightGreen = !preflight.error && preflight.status === 0;
+    if (preflightGreen) {
+      log('sudo will run WITHOUT a password prompt (cached credentials or NOPASSWD) — the install proceeds non-interactively.');
+    } else if (!isTTYOf()) {
+      log('sudo needs a password and there is NO controlling terminal — running NOTHING. Run this in YOUR terminal, then re-run --verify:');
+      log(`  ${[sudoTrusted, ...plan.rootArgv].join(' ')}`);
+      return { status: STATUS.handoffRequired, finalPlan: plan };
+    } else {
+      log('sudo will prompt for your password on your terminal.');
+    }
+    execArgv = [sudoTrusted, ...plan.rootArgv];
+  }
+  log('executing EXACTLY (every token trusted-dir absolute):');
+  log(`  ${execArgv.join(' ')}`);
+  const res = mutatingRunner({ argv: execArgv, env: scrubbedEnv, stdio: [...MUTATING_STDIO] });
+  if (res.error || res.status !== 0) {
+    log(res.error
+      ? `install could not SPAWN (${res.error.code ?? res.error.message}).`
+      : `install FAILED (exit ${res.status}) — see the package manager output above (stderr was inherited). A stale package index is one possible cause (the doctor never refreshes indexes — run your PM's update by hand if so).`);
+    return { status: STATUS.installFailed, finalPlan: plan };
+  }
+  log('install completed — running the verify lane...');
+  const freshProbe = ctx.probe();
+  const freshPlan = deriveDoctorPlan({ probeResult: freshProbe, env, isExec });
+  return { status: runVerifyLane({ plan: freshPlan, ctx }), finalPlan: freshPlan };
+};
+
+// ── default runners (the ONE real-process boundary; injectable for hermetic tests) ────
+
+export const runDiagnosticSpawn = (descriptor) =>
+  spawnSync(descriptor.argv[0], descriptor.argv.slice(1), { env: descriptor.env, encoding: 'utf8', stdio: 'pipe' });
+export const runMutatingSpawn = (descriptor) =>
+  spawnSync(descriptor.argv[0], descriptor.argv.slice(1), { env: descriptor.env, stdio: descriptor.stdio });
+
+// ── main(argv, deps) → exit code ──────────────────────────────────────────────────────
+
+export const main = (argv, deps = {}) => {
+  const log = deps.log ?? console.log;
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const cwd = deps.cwd ?? process.cwd();
+  const lstat = deps.lstat ?? lstatSync;
+  const isExec = deps.isExecutable ?? isExecutableFile;
+  const execPath = deps.execPath ?? process.execPath;
+  const diagnosticRunner = deps.diagnosticRunner ?? runDiagnosticSpawn;
+  const mutatingRunner = deps.mutatingRunner ?? runMutatingSpawn;
+  const probe = deps.probe ?? (() => probeSandboxAvailability({ platform, env, isExecutable: isExec }));
+  const euidOf = deps.euid ?? (() => process.geteuid?.());
+  const isTTYOf = () => deps.isTTY ?? hasControllingTerminal();
+
+  const finish = (status, plan = null) => {
+    log(composeSummaryLine({ status, platform, missing: plan?.missing ?? [], pm: plan?.pm?.name ?? null }));
+    return EXIT_FOR_STATUS[status];
+  };
+
+  let parsed;
+  try {
+    parsed = parseDoctorArgs(argv);
+  } catch (err) {
+    log(`autonomy-doctor: ${err.message}`);
+    log(USAGE_HINT);
+    return finish(STATUS.usage);
+  }
+  if (parsed.lane === 'help') {
+    log(HELP);
+    return 0;
+  }
+
+  try {
+    assertDocsAiDeployment(cwd, { lstat }, { noun: 'anything', rel: 'anything here' });
+  } catch (err) {
+    log(`precondition STOP — ${err.message}`);
+    return finish(STATUS.noDeployment);
+  }
+
+  if (platform === 'win32') {
+    log(WSL2_REDIRECT);
+    return finish(STATUS.unsupportedPlatform);
+  }
+  if (platform === 'darwin') {
+    if (parsed.lane === 'apply') {
+      log(`consent REFUSED: nothing to install on macOS (Seatbelt is built-in) — the tuple "${parsed.tuple}" matches no plan. Nothing was run.`);
+      return finish(STATUS.usage);
+    }
+    log(SEATBELT_NOTE);
+    return finish(STATUS.readyAssumed);
+  }
+  if (platform !== 'linux') {
+    log(`native ${platform} sandbox unsupported — use WSL2 on Windows.`);
+    return finish(STATUS.unsupportedPlatform);
+  }
+
+  // Linux from here; euid resolves LAZILY after the platform gate (process.geteuid is win32-absent).
+  const euid = euidOf();
+  const probeResult = probe();
+  const plan = deriveDoctorPlan({ probeResult, env, isExec });
+  const scrubbedEnv = { PATH: TRUSTED_PATH, ...(env && env.LANG ? { LANG: env.LANG } : {}) };
+  const ctx = { log, isExec, env, euid, execPath, diagnosticRunner, mutatingRunner, scrubbedEnv, isTTYOf, probe };
+
+  renderDiagnosis({ plan, probeResult, log });
+
+  if (parsed.lane === 'preview') {
+    let status;
+    if (plan.untrusted.length > 0) status = refuseUntrusted({ plan, log });
+    else if (plan.missing.length > 0) status = renderOffer({ plan, euid, isExec, env, log });
+    else {
+      log('  state: binaries present but UNVERIFIED — the flagless preview never claims ready; run --verify for the ready proof.');
+      status = STATUS.presentUnverified;
+    }
+    for (const line of D9_DISCLOSURE) log(line);
+    return finish(status, plan);
+  }
+  if (parsed.lane === 'verify') return finish(runVerifyLane({ plan, ctx }), plan);
+  const applied = runApplyLane({ plan, tuple: parsed.tuple, ctx });
+  return finish(applied.status, applied.finalPlan);
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exit(main(process.argv.slice(2)));

package/tools/commands.mjs

@@ -28,7 +28,7 @@ const invocationOf = (token) => `${BARE_INVOCATION}${token ? ` ${token}` : ''}`;
 // ── kinds ────────────────────────────────────────────────────────────────────────
 // read-only    — never writes, never commits, never runs a subscription CLI.
 // writer       — writes files (a project deployment or a settings/skill placement).
-// guarded      — a destructive teardown gated behind a mandatory dry-run-first + explicit consent.
+// guarded      — consent-gated destructive/privileged actions (dry-run-first + explicit consent).
 // project-exec — the kit itself writes nothing, but the mode RUNS the project's own declared
 //                commands with the caller's privileges (the `gates` runner) — honest-tagged so a
 //                user never reads "read-only" on a surface that executes their gate matrix.
@@ -140,6 +140,13 @@ const CATALOG = [
     kind: GUARDED,
     oneLine: 'Read or change the host-level bridge settings (e.g. the codex Fast tier) — a KEY=VALUE file that survives kit upgrades; previews first, and the Fast tier carries its extra-cost caveat.',
   },
+  {
+    key: 'autonomy-doctor',
+    invocation: invocationOf('autonomy-doctor'),
+    group: 'Configure',
+    kind: GUARDED,
+    oneLine: 'Check whether this machine can run the Claude sandbox and, only with your explicit consent, install what is missing — privileged, preview-first, consent-per-run; it never auto-runs and never commits.',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),
@@ -274,7 +281,7 @@ export const formatHelp = () => {
   const lines = [
     `${SKILL_NAME} — command index (this list is read-only)`,
     '',
-    'Each command is tagged read-only · writer (makes changes) · guarded (destructive, previews first) · runs project cmds (executes your own declared commands).',
+    'Each command is tagged read-only · writer (makes changes) · guarded (consent-gated destructive/privileged actions, previews first) · runs project cmds (executes your own declared commands).',
   ];
   for (const group of GROUP_ORDER) {
     const inGroup = COMMANDS.filter((c) => c.group === group);

package/tools/doc-parity.mjs

@@ -26,11 +26,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SCHEMA_VERSION, REVIEW_CAP, V4_CLASSES, V4_OVERRIDE_SCOPES } from './review-ledger.mjs';
 import { HARD_MAX, DEFAULT_DIFF_CAP } from './review-ledger-write.mjs';
 import { RESULT_SCHEMA_VERSION } from './fold-completeness.mjs';
+import { EXIT as DOCTOR_EXIT, STATUS as DOCTOR_STATUS, TRUSTED_DIRS as DOCTOR_TRUSTED_DIRS } from './autonomy-doctor.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 const REVIEW_LEDGER_DOC = 'references/modes/review-ledger.md';
 const FOLD_DOC = 'references/modes/fold-completeness.md';
+const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -45,6 +47,19 @@ const valueBinding = (constant, value, phrase, files) => ({ constant, value, tok
 // so the closed set can never disagree with the code. Every word must appear in the ledger contract.
 const LEDGER_VOCAB = [...V4_CLASSES, ...V4_OVERRIDE_SCOPES, 'gate-run'];
 
+// The autonomy-doctor D7 contract (AD-044 Plan 2): the live EXIT table + every status token must
+// render into the mode's contract doc. `usage` is skipped as a bare-word token (trivially present
+// everywhere) — its exit-code phrase below pins that outcome instead.
+const DOCTOR_EXIT_PHRASES = [
+  ['ready', `\`${DOCTOR_EXIT.ready}\` ready`],
+  ['stop', `\`${DOCTOR_EXIT.stop}\` precondition STOP`],
+  ['usage', `\`${DOCTOR_EXIT.usage}\` usage`],
+  ['notReady', `\`${DOCTOR_EXIT.notReady}\` not-ready diagnosis`],
+  ['installFailed', `\`${DOCTOR_EXIT.installFailed}\` install failed`],
+  ['verifyFailed', `\`${DOCTOR_EXIT.verifyFailed}\` verify failed`],
+  ['unsupported', `\`${DOCTOR_EXIT.unsupported}\` unsupported / untrusted`],
+];
+
 export const BINDINGS = Object.freeze([
   valueBinding('SCHEMA_VERSION', SCHEMA_VERSION, `schema v${SCHEMA_VERSION}`, [REVIEW_LEDGER_DOC]),
   valueBinding('HARD_MAX', HARD_MAX, `hard-max ceiling of ${HARD_MAX}`, [REVIEW_LEDGER_DOC]),
@@ -52,6 +67,11 @@ export const BINDINGS = Object.freeze([
   valueBinding('REVIEW_CAP', REVIEW_CAP, `cap ≤${REVIEW_CAP}`, [REVIEW_LEDGER_DOC]),
   valueBinding('RESULT_SCHEMA_VERSION', RESULT_SCHEMA_VERSION, `schema v${RESULT_SCHEMA_VERSION}`, [FOLD_DOC]),
   ...LEDGER_VOCAB.map((word) => valueBinding(`vocab:${word}`, word, word, [REVIEW_LEDGER_DOC])),
+  ...DOCTOR_EXIT_PHRASES.map(([key, phrase]) => valueBinding(`doctor-exit:${key}`, DOCTOR_EXIT[key], phrase, [AUTONOMY_DOCTOR_DOC])),
+  ...Object.values(DOCTOR_STATUS)
+    .filter((token) => token !== DOCTOR_STATUS.usage)
+    .map((token) => valueBinding(`doctor-status:${token}`, token, token, [AUTONOMY_DOCTOR_DOC])),
+  valueBinding('doctor-trusted-dirs', DOCTOR_TRUSTED_DIRS.join(':'), DOCTOR_TRUSTED_DIRS.join(':'), [AUTONOMY_DOCTOR_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -96,8 +116,9 @@ Usage:
   node doc-parity.mjs [--check | --json]
 
 A CLOSED, exported registry binds each live code constant (review-ledger SCHEMA_VERSION / REVIEW_CAP,
-review-ledger-write HARD_MAX / DEFAULT_DIFF_CAP, fold-completeness RESULT_SCHEMA_VERSION) and the
-ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run) to the exact token its
+review-ledger-write HARD_MAX / DEFAULT_DIFF_CAP, fold-completeness RESULT_SCHEMA_VERSION), the
+ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run), and the autonomy-doctor contract
+(the EXIT table, the status tokens, the trusted-dir allowlist) 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 bound file, or an absent token FAILS CLOSED.
 

package/tools/seed-gates.mjs

@@ -6,14 +6,28 @@
 // EMPTY (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through
 // this preview, never auto-seeding.
 //
-// What it offers (the derivation invariants, test-pinned):
+// What it offers (the derivation invariants, test-pinned) — CLOSED-WORLD since AD-052: an entry
+// is offered only when every axis is proven safe by MEMBERSHIP in a finite, test-guarded set,
+// never by absence from a blocklist (Issue-011 killed the blocklist model — one more gap per
+// review round, unprovable):
 //   • sources: discoverGateCandidates over package.json scripts (velocity-profile.mjs stays
 //     read-only; THIS module owns the offer mapping) + the conditional review-state candidate;
-//   • warn-flagged candidates (release/publish/deploy/push/version/commit/tag, pre*/post*) NEVER
-//     enter the offer — excluded, not offered-with-a-warning;
-//   • only TERMINATING verification classes are offered (test / lint / type-check / build) —
-//     never dev/start/watch/serve/preview, never a formatter write-mode;
-//   • commands are package-manager-aware (packageManager field, else lockfile probe, else npm);
+//   • NAME screens shape WHICH entries are offered: warn-flagged candidates (release/publish/
+//     deploy/push/version/commit/tag, pre*/post*) never enter; only terminating verification
+//     class NAMES (test / lint / type-check / build) pass, never dev/start/watch/serve/preview,
+//     never a mutating-variant name; a shell-unsafe name is screened first;
+//   • the BODY must be a string member of the literal BODY_ALLOWLIST after a pinned ASCII-only
+//     normalization — anything else is screened out with a LOUD note (never silently absent);
+//   • the cmd is the per-PM HOOK-FREE form `COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>`
+//     (packageManager field, else lockfile probe, else npm): `exec` runs a command, not a named
+//     script, so the pre/post lifecycle-hook class dies structurally on npm/pnpm/yarn alike, and
+//     the Corepack env prefix blocks a hostile packageManager pin from fetching the PM binary; a
+//     family with no verified fail-closed exec contract is WITHHELD with a loud note. NEVER
+//     `<pm> run <name>` — that re-exposes hooks and lets a later package.json edit change a
+//     byte-exact-approved gate;
+//   • the safety claim is scoped to the OFFER DERIVATION, not a runtime sandbox: a gate still
+//     executes project-controlled tooling (a node_modules/.bin PATH shim intercepts under every
+//     form) — the documented residual, disclosed in the preview, bounded by the two consents;
 //   • ids derive kebab-case from script names (build:prod → build-prod) and every offered entry
 //     passes the runner's validateDeclaration (the seeder imports the validator — NEVER the
 //     reverse: run-gates.mjs stays a runner that writes nothing);
@@ -62,33 +76,35 @@ const usageFail = (message) =>
 export const TRUST_CHAIN_DISCLOSURE =
   'Disclosure: once the optional approval hook is wired (/agent-workflow-kit hook), it ' +
   'auto-approves byte-exact declared gate commands from the project root — seeding (this consent) ' +
-  'and hook wiring (its own consent) are two separate yeses.';
+  'and hook wiring (its own consent) are two separate yeses. A script gate runs the project\'s ' +
+  'own tooling, which executes project-controlled code (the seeder does not sandbox it; the two ' +
+  'consents bound it).';
 
 const USAGE = `usage: seed-gates [--dry-run | --apply] [--only <id>]... [--cwd <dir>] [--help]
 
 Consent-gated seeder for the project's own docs/ai/gates.json. Default is --dry-run: prints the
 derived { id, title, cmd } entries and writes NOTHING. --apply APPENDS exactly the consented
 entries (--only <id> selects a subset; append-only — existing entries are never modified or
-removed, an id collision is refused). Only terminating verification commands are offered
-(test / lint / type-check / build); release/publish/deploy scripts and watch/serve modes never
-enter the offer. ${TRUST_CHAIN_DISCLOSURE}`;
+removed, an id collision is refused). The offer is CLOSED-WORLD: only a terminating-class script
+name (test / lint / type-check / build — never release/publish/deploy, never watch/serve, never a
+write-mode variant) whose BODY is a member of the literal runner allowlist is offered, as the
+hook-free \`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <body>\` form for the detected package manager. A gate-class script whose
+body is NOT in the allowlist is screened out with a note naming it (a command you trust can still
+be declared by hand); non-gate-class names are excluded silently, as always.
+${TRUST_CHAIN_DISCLOSURE}`;
 
-// ── candidate classification (the LOCKED derivation invariants) ────────────────────────
-// The derived cmd (`<pm> run <name>`) is bash-interpolated by the gate runner and can become
+// ── candidate classification: the NAME screens (the LOCKED derivation invariants) ──────
+// NAME screens shape WHICH safe entries are offered; the danger axis (the BODY) is closed-world
+// below (AD-052). The derived cmd is bash-interpolated by the gate runner and can become
 // hook-auto-approvable, so only shell-SAFE script names ever enter the offer: a name carrying
 // whitespace or any shell metacharacter (`test:ci && echo pwn`) is screened out entirely.
 const SAFE_SCRIPT_NAME_PATTERN = /^[A-Za-z0-9:_.-]+$/;
 const TERMINATING_CLASS_PATTERN = /^(test|lint|type-?check|types|tsc|build)([:._-]|$)/i;
-// Non-terminating screening is TOKEN-set based, position-independent (never an anchored regex —
-// the anchored form missed `build:preview` and a bare `vite preview` body): a non-terminating
-// token in ANY name segment, or as ANY bare/dashed body word, disqualifies; `watch` disqualifies
-// as a substring anywhere (watchAll, --watchAll). Conservative on purpose — a screened-out script
-// can still be declared by hand; a wrongly-included one would become hook-auto-approvable.
+// Non-terminating NAME screening is TOKEN-set based, position-independent (never an anchored
+// regex — the anchored form missed `build:preview`): a non-terminating token in ANY name segment
+// disqualifies; `watch` disqualifies as a substring anywhere (watchAll). Conservative on purpose —
+// a screened-out script can still be declared by hand.
 const NON_TERMINATING_TOKENS = new Set(['dev', 'start', 'serve', 'watch', 'preview']);
-// A terminating-looking NAME can still hide release work in its BODY (`"test": "npm publish"`):
-// the same token classes the warn-name screen rejects are rejected as bare body words too — an
-// offered cmd is hook-auto-approvable, so a dangerous body must never ride a clean name.
-const DANGEROUS_BODY_TOKENS = new Set(['release', 'publish', 'deploy', 'push', 'version', 'commit', 'tag']);
 const WATCH_ANYWHERE_PATTERN = /watch/i;
 const wordOf = (raw) => raw.toLowerCase().replace(/^-+/, '').split('=')[0];
 const hasTokenIn = (text, splitter, tokens) =>
@@ -97,16 +113,82 @@ const hasTokenIn = (text, splitter, tokens) =>
     .some((part) => tokens.has(wordOf(part)));
 const isNonTerminatingName = (name) =>
   hasTokenIn(name, /[:._-]/, NON_TERMINATING_TOKENS) || WATCH_ANYWHERE_PATTERN.test(name);
-const isNonTerminatingBody = (body) =>
-  hasTokenIn(body, /\s+/, NON_TERMINATING_TOKENS) || WATCH_ANYWHERE_PATTERN.test(body);
-const isDangerousBody = (body) => hasTokenIn(body, /\s+/, DANGEROUS_BODY_TOKENS);
-// A MUTATING VARIANT of a terminating class never enters the offer — a hook-auto-approvable gate
-// must never be a writer. Screened on BOTH axes: the script NAME (lint:fix, test:update,
-// build:write, test:snapshot) and the script BODY's write-mode flags (eslint --fix,
-// prettier --write / -w, jest -u / --updateSnapshot, tsc -w). Conservative by design: an excluded
-// candidate can still be declared by hand — a wrongly-included one would be silently auto-approved.
+// A MUTATING VARIANT NAME of a terminating class never enters the offer (lint:fix, test:update,
+// build:write, test:snapshot) — a hook-auto-approvable gate must never be a writer. Write-mode
+// BODIES need no screen: the closed-world allowlist simply has no write-mode member.
 const MUTATING_VARIANT_NAME_PATTERN = /(^|[:._-])(fix|write|update|snapshot)([:._-]|$)/i;
-const MUTATING_BODY_FLAG_PATTERN = /(^|\s)(--fix|--write|--update(?:-snapshot)?|--updateSnapshot|-w|-u)(=|\s|$)/;
+
+// ── the CLOSED-WORLD body contract (AD-052 — the Issue-011 structural fix) ─────────────
+// The body axis is ALLOWLIST MEMBERSHIP, never blocklist screening. The failure direction flips
+// by construction: worst case = a legit command not offered (mild, add-by-hand) — never a
+// dangerous one offered. Extension contract (edit-safety): adding an entry = adding the literal
+// here + classifying its stem in the partition below + its own test case; the self-safety test
+// pins every entry against shell metacharacters, write-mode flags, and unrecognized runner stems.
+// Deliberately EXCLUDED: `tsc -p .` without --noEmit — it EMITS compiled .js into the tree by
+// default, a write side-effect a verification gate must not have.
+export const BODY_ALLOWLIST = Object.freeze([
+  'node --test',
+  'vitest run',
+  'jest',
+  'jest --ci',
+  'eslint .',
+  'prettier --check .',
+  'tsc --noEmit',
+  'tsc -p . --noEmit',
+  'vite build',
+]);
+// The FIXED executable-source partition of the allowlist stems (test-pinned, never a runtime
+// probe): a host-runtime stem (`node`) is always on PATH and never a node_modules package — no
+// local-bin resolution applies to it; a package-runner stem resolves from the project's own
+// node_modules (or Berry .pnp.cjs) via `<pm> exec`, under the per-PM no-network-fetch rule below.
+export const HOST_RUNTIME_STEMS = Object.freeze(['node']);
+export const PACKAGE_RUNNER_STEMS = Object.freeze(['vitest', 'jest', 'eslint', 'prettier', 'tsc', 'vite']);
+
+// Decision-3 order, test-pinned: (1) string-typed, else not offered; (2) reject ANY char outside
+// printable ASCII + space/tab BEFORE trimming — String.trim() strips \n/NBSP/BOM at the EDGES and
+// would mask a leading/trailing forbidden char; (3) trim + collapse ASCII space/tab runs to one
+// space; (4) literal membership. No case folding, no arg reordering, no separate env/path reject
+// axis — `FOO=bar node --test` and `./scripts/x.sh` are already rejected by NON-MEMBERSHIP.
+const PRINTABLE_ASCII_BODY_PATTERN = /^[\x20-\x7E\t]*$/;
+const allowlistedBodyOf = (body) => {
+  if (typeof body !== 'string') return null;
+  if (!PRINTABLE_ASCII_BODY_PATTERN.test(body)) return null;
+  const normalized = body.replace(/^[ \t]+|[ \t]+$/g, '').replace(/[ \t]+/g, ' ');
+  return BODY_ALLOWLIST.includes(normalized) ? normalized : null;
+};
+
+// The per-PM HOOK-FREE exec form (Decision 1, host-proven npm 12 / pnpm 10 / yarn 1 + berry 4):
+// `exec` runs a COMMAND, not a named script — no pre/post lifecycle exists to fire, uniformly.
+// The `--` keeps a body flag (`jest --ci`) from being absorbed by the PM. Per-PM hardening — the
+// pinned invariant is NO NETWORK FETCH of an absent runner, not "no user-machine fallback":
+//   npm  — `--script-shell /bin/sh` beats a hostile per-project `.npmrc script-shell` (proven the
+//          flag wins) and `--offline` refuses an absent runner as a cache miss, never a registry
+//          fetch; a hit on a previously-installed real package (the npm cache OR the host's
+//          global tree — both user machine state, not project content) is the documented runtime
+//          residual (Decision 2 ii / 6), not a separate guard.
+//   pnpm — no network fetch; an absent runner fails closed when no project-local or
+//          PATH-resolvable runner exists (a user-installed one executing is the same
+//          user-machine-state residual). Reads no npm `.npmrc script-shell`.
+//   yarn — same contract, uniform for classic + berry (berry resolves via .pnp.cjs; proven).
+// The `COREPACK_ENABLE_NETWORK=0` prefix closes ONE more attacker-reachable fetch axis: when the
+// PM binary is a Corepack shim, a hostile `packageManager: "<pm>@<uncached-version>"` field makes
+// Corepack DOWNLOAD that PM release from the registry BEFORE exec even resolves the runner. The env
+// var disables that provisioning (proven: it fails closed "Network access disabled" on an uncached
+// pin, and is inert when the PM is a real install or already provisioned) — so the no-network
+// contract holds for the PM-provision step too, not just the runner. Applies to all three (Corepack
+// can shim npm/pnpm/yarn alike). An UNKNOWN family has no verified fail-closed exec contract → cmd
+// null (withheld, loud note) — the mild worst case, never a hole. detectPackageManager can only
+// yield npm/pnpm/yarn today (bun collapses to npm — characterized), so this is the builder floor.
+const COREPACK_NO_NETWORK = 'COREPACK_ENABLE_NETWORK=0';
+export const execCmdFor = (pm, body) => {
+  if (pm === 'npm') return { cmd: `${COREPACK_NO_NETWORK} npm exec --offline --script-shell /bin/sh -- ${body}`, note: null };
+  if (pm === 'pnpm') return { cmd: `${COREPACK_NO_NETWORK} pnpm exec -- ${body}`, note: null };
+  if (pm === 'yarn') return { cmd: `${COREPACK_NO_NETWORK} yarn exec -- ${body}`, note: null };
+  return {
+    cmd: null,
+    note: `no fail-closed exec form is verified for this package manager (${pm}) — add the gate by hand`,
+  };
+};
 
 export const kebabIdOf = (name) =>
   String(name)
@@ -133,8 +215,11 @@ export const detectPackageManager = (cwd, deps = {}) => {
   return 'npm';
 };
 
-// The script-derived offer entries. Order = package.json scripts order (the offer the user reads).
-export const deriveScriptEntries = (cwd, deps = {}) => {
+// The script-derived offer: entries + loud honesty notes (a gate-class script screened out on its
+// body, or a whole family withheld, is COUNTED and NAMED — never silently absent). Order =
+// package.json scripts order (the offer the user reads). `deps.packageManager` injects a family
+// token past the detector for the builder-boundary fail-closed proof (T4b).
+const deriveScripts = (cwd, deps = {}) => {
   const read = deps.readFile ?? readFileSync;
   const pkg = (() => {
     try {
@@ -143,29 +228,48 @@ export const deriveScriptEntries = (cwd, deps = {}) => {
       return null; // no/unreadable package.json → no script candidates (an honest empty offer)
     }
   })();
-  const pm = detectPackageManager(cwd, deps);
-  const seen = new Set();
-  const bodyOf = (name) => String(pkg?.scripts?.[name] ?? '');
-  return discoverGateCandidates(pkg ?? {})
+  const pm = deps.packageManager ?? detectPackageManager(cwd, deps);
+  const named = discoverGateCandidates(pkg ?? {})
     .filter((c) => !c.warn) // warn-flagged NEVER enter the offer
     .filter((c) => SAFE_SCRIPT_NAME_PATTERN.test(c.scriptName)) // shell-safe names only, FIRST
     .filter((c) => TERMINATING_CLASS_PATTERN.test(c.scriptName))
     .filter((c) => !isNonTerminatingName(c.scriptName))
-    .filter((c) => !MUTATING_VARIANT_NAME_PATTERN.test(c.scriptName) && !MUTATING_BODY_FLAG_PATTERN.test(bodyOf(c.scriptName)))
-    .filter((c) => !isNonTerminatingBody(bodyOf(c.scriptName)))
-    .filter((c) => !isDangerousBody(bodyOf(c.scriptName)))
-    .map((c) => ({
-      id: kebabIdOf(c.scriptName),
-      title: `Project script: ${pm} run ${c.scriptName}`,
-      cmd: `${pm} run ${c.scriptName}`,
-    }))
-    .filter((e) => {
-      if (!e.id || seen.has(e.id)) return false; // an empty or duplicate derived id never enters the offer
-      seen.add(e.id);
-      return true;
-    });
+    .filter((c) => !MUTATING_VARIANT_NAME_PATTERN.test(c.scriptName));
+  const seen = new Set(); // first occurrence of a derived id wins, whatever its outcome (conservative)
+  const entries = [];
+  const screenedIds = [];
+  const withheld = [];
+  for (const c of named) {
+    const id = kebabIdOf(c.scriptName);
+    if (!id || seen.has(id)) continue; // an empty or duplicate derived id never enters the offer
+    seen.add(id);
+    const body = allowlistedBodyOf(pkg?.scripts?.[c.scriptName]);
+    if (body === null) {
+      screenedIds.push(id);
+      continue;
+    }
+    const { cmd, note } = execCmdFor(pm, body);
+    if (cmd === null) {
+      withheld.push({ id, note });
+      continue;
+    }
+    entries.push({ id, title: `Project script ${c.scriptName}: ${body}`, cmd });
+  }
+  const notes = [];
+  if (screenedIds.length) {
+    notes.push(
+      `${screenedIds.length} gate-class script(s) screened out — body not in the closed-world ` +
+        `allowlist: ${screenedIds.join(', ')} — a command you trust can still be declared by hand in ${GATES_REL}`,
+    );
+  }
+  if (withheld.length) {
+    notes.push(`${withheld.length} script gate(s) withheld: ${withheld.map((w) => w.id).join(', ')} — ${withheld[0].note}`);
+  }
+  return { entries, notes };
 };
 
+export const deriveScriptEntries = (cwd, deps = {}) => deriveScripts(cwd, deps).entries;
+
 // The conditional review-state candidate — keyed on the SLOT the checker enforces
 // (plan-execution.review, tools/review-state.mjs), read via the shared config reader. Offered only
 // when the config DECLARES reviewed/council there; solo configs and a council-on-plan-authoring-only
@@ -256,14 +360,13 @@ const assertOnlyIdsOffered = (offer, onlyIds = []) => {
 // plus loud notes. Both review candidates key on the same slot (plan-execution.review reviewed/council)
 // but gate distinct axes (receipt presence vs review-round convergence) — offered together.
 export const buildOffer = (cwd, deps = {}) => {
-  const entries = deriveScriptEntries(cwd, deps);
+  const scripts = deriveScripts(cwd, deps);
   const rs = reviewStateCandidate(cwd, deps);
   const rl = reviewLedgerCandidate(cwd, deps);
   const candidates = [rs.candidate, rl.candidate].filter(Boolean);
-  const notes = [rs.note, rl.note].filter(Boolean);
   return {
-    entries: [...entries, ...candidates],
-    notes,
+    entries: [...scripts.entries, ...candidates],
+    notes: [...scripts.notes, rs.note, rl.note].filter(Boolean),
   };
 };
 
@@ -361,7 +464,7 @@ export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
   }
   const offer = buildOffer(cwd, deps);
   assertOnlyIdsOffered(offer, onlyIds); // BEFORE the empty-offer return — a typo is never masked
-  if (!offer.entries.length) return { outcome: 'nothing' };
+  if (!offer.entries.length) return { outcome: 'nothing', notes: offer.notes };
   const selected = onlyIds.length ? offer.entries.filter((e) => onlyIds.includes(e.id)) : offer.entries;
 
   const existing = loadExistingDeclaration(cwd, deps);
@@ -382,7 +485,7 @@ export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
   validateDeclaration(merged); // every written declaration passes the runner's validator, always
   const body = `${JSON.stringify(merged, null, 2)}\n`;
   const { writtenPath } = writeDocsAiFileAtomic(cwd, GATES_REL, body, deps, { stop, noun: 'a gate declaration' });
-  return { outcome: 'written', writtenPath, appended: selected.map((e) => e.id) };
+  return { outcome: 'written', writtenPath, appended: selected.map((e) => e.id), notes: offer.notes };
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────────────
@@ -439,9 +542,11 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     const result = applySeed({ cwd, onlyIds: args.only }, deps);
     if (result.outcome === 'nothing') {
       log('[agent-workflow-kit] nothing to offer — no seedable terminating verification scripts were found; wrote nothing.');
+      for (const note of result.notes) log(`  note: ${note}`); // the user learns WHY (same note as the preview)
       return EXIT_OK;
     }
     log(`[agent-workflow-kit] appended ${result.appended.length} consented gate(s) to ${GATES_REL}: ${result.appended.join(', ')}`);
+    for (const note of result.notes) log(`  note: ${note}`); // a mixed offer never silently omits what was screened
     log(`[agent-workflow-kit] ${TRUST_CHAIN_DISCLOSURE}`);
     return EXIT_OK;
   } catch (err) {

package/tools/velocity-profile.mjs

@@ -838,7 +838,8 @@ const AUTONOMY_RESIDUAL_NOTICE =
 // isExecutableFile — true iff `p` is a REGULAR file with an execute bit (statSync FOLLOWS a symlink, so
 // a symlinked binary resolves to its target). A directory or a non-executable file NAMED bwrap/socat
 // must NOT count as the binary (else the loud sandbox-unavailable degrade would be wrongly suppressed).
-const isExecutableFile = (p) => {
+// Exported (AD-044 Plan 2): autonomy-doctor.mjs promotes this to its trusted-dir execution gate.
+export const isExecutableFile = (p) => {
   try {
     const st = statSync(p);
     return st.isFile() && (st.mode & 0o111) !== 0;
@@ -929,7 +930,7 @@ export const renderAutonomySettings = (resolved, probe) => {
   // sandbox availability (Step 3.3 probe) — a LOUD degrade where the OS can't sandbox; the red-lines +
   // defaultMode still land (they are permission rules, sandbox-independent).
   if (!probe.available) {
-    degrades.push(`sandbox UNAVAILABLE on this host (${probe.reason}) — claude renders the sandbox block but WARNS and runs UNSANDBOXED: ad-hoc scripts will still PROMPT and network/fs confinement is NOT enforced until it is available (Plan 2 offers to install the missing dependency). The red-lines + defaultMode still apply. failIfUnavailable is left UNSET so the session is never bricked.`);
+    degrades.push(`sandbox UNAVAILABLE on this host (${probe.reason}) — claude renders the sandbox block but WARNS and runs UNSANDBOXED: ad-hoc scripts will still PROMPT and network/fs confinement is NOT enforced until it is available (run /agent-workflow-kit autonomy-doctor to diagnose and, with your consent, install the missing dependency). The red-lines + defaultMode still apply. failIfUnavailable is left UNSET so the session is never bricked.`);
   }
   return { level, activities: resolved.activities, sandbox, defaultMode, ask, deny, notes, degrades };
 };