@sabaiway/agent-workflow-kit 1.44.0 → 1.45.1

package/references/modes/velocity.md

@@ -4,7 +4,7 @@ The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-
 
 **Version-status routing (like the other writer modes):** read `docs/ai/.workflow-version` first — not-deployed → bootstrap; stamp < `2.0.0` → `upgrade`; stamp > head / unparseable → STOP. The tool enforces this in code too (`--apply` STOPs unless the stamp is the lineage head).
 
-Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [--kit-tools] [--accept-edits] [--cwd <dir>]`:
+Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [--kit-tools] [--bridge-tier] [--accept-edits] [--cwd <dir>]`:
 
 1. **`--dry-run` first, always** (the default — changes nothing). It prints: the fixed read-only core it would add; a **read-only advisory** that lists your `package.json` `scripts` as **unaudited candidates you may add BY HAND** (inspect each first) to `.claude/settings.json` / `settings.local.json` — the tool **never** writes them and flags obviously-mutating names as "do not add"; any **pre-existing non-read-only `Bash(...)` entries** to consider removing by hand; and the honest residual notice (below). It STOPs (zero writes) on a symlinked `.claude` / non-regular `settings.json`, malformed settings JSON, or an unsafe `permissions.defaultMode` — `bypassPermissions` or anything outside `default`/`acceptEdits`/`plan`, present in **either** `settings.json` or `settings.local.json`.
 2. **Ask the opt-ins** via **`AskUserQuestion` where supported** — two separate choices, the safe option FIRST in each. First the **`--kit-tools` tier** (separate from `acceptEdits`; **"core only" remains the default answer** — seed the tier only on an explicit yes, then add `--kit-tools` to the `--apply` re-run). Then the `acceptEdits` opt-in:
@@ -21,6 +21,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 - `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs` (wildcard)
 - `node ${CLAUDE_SKILL_DIR}/tools/commands.mjs` (wildcard)
 - `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs --check` (wildcard)
+- `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd ${PROJECT_ROOT}` (wildcard — the read-only deployment advisor; its rendered apply one-liners are writers and still prompt)
 - `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs --strict <skill-dir>` (wildcard)
 - `node ${CLAUDE_SKILL_DIR}/tools/release-scan.mjs <path>` (wildcard)
 - `node ${CLAUDE_SKILL_DIR}/tools/run-gates.mjs --cwd ${PROJECT_ROOT}` — **EXACT byte-string only**, and honestly **project-exec, not read-only**: it runs YOUR declared `docs/ai/gates.json` commands — the same trust boundary the opt-in hook grants byte-exact per-cmd. A wildcard would be BROADER than that boundary (`--cwd <dir>` executes another project's declared gates), so the bare cwd-defaulting form, any other `--cwd`, `--only`, and **`--record`** forms all still prompt (`--record` WRITES a gate-run record into the review ledger — a recording run is never auto-approved, AD-048).
@@ -30,6 +31,16 @@ Honesty notes: tier entries get **NO PreToolUse-hook residual coverage** — the
 
 **Invariants:** creates `.claude/` if absent and writes **only** `.claude/settings.json` (no other file); **never** allowlists commit/push/publish; **never** writes `settings.local.json`; never commits; opt-in `acceptEdits`, never silent.
 
+**The `--bridge-tier` (own opt-in, AD-044).** Seeds what a promptless council review run needs — BOTH surfaces: `permissions.allow` prefix rules AND the wrapper names in `sandbox.excludedCommands` (the harness runs an excluded command OUTSIDE the sandbox — the wrappers need network — so a plain allowlisted invocation triggers no sandbox-bypass approval). Both land in the **project** `.claude/settings.json` — the file this writer owns; an exclusion placed only in `settings.local.json` was live-observed NOT to route the command outside the sandbox (2026-07-11: the wrapper then starts sandboxed and dies on a read-only HOME + a network prompt), so hand-wiring the local file is not a working substitute for this tier. **Honesty note:** a session whose sandbox is imposed by the harness runtime itself (e.g. an IDE-managed session sandbox) may ignore settings-level exclusions entirely — there the wrappers need the session-level sandbox config (or a per-run consented bypass); the tier's seeded posture is correct for the settings-native sandbox and simply prompts again elsewhere (fail-safe, never a silent widening). Each bridge's observed egress hosts are declared in its `capability.json` `networkHosts` — the single documentation source (observed-minimal — a blocked host names itself at run time; read the manifests, this doc deliberately retypes no host list). The kit **never seeds** `sandbox.network.allowedDomains` or `sandbox.filesystem.allowWrite` (bridge council 2026-07-11, both backends concur): a network pre-allow widens egress for EVERY sandboxed command, and a write allowance on CLI state dirs (`~/.codex`, `~/.gemini/…`) would make credential dirs writable to every sandboxed command. Per-bridge picture under a harness-managed sandbox (live-observed 2026-07-11/12): an IDE-managed session sandbox ignores hand-applied `sandbox.network.allowedDomains` / `sandbox.filesystem.allowWrite` in BOTH settings scopes — its own per-host network consents govern egress; the durable zero-prompt lanes there are the session/host sandbox config (hosts from `networkHosts` + the CLI state-dir writes) or the per-run consented bypass. codex additionally needs a writable HOME (EROFS `~/.codex`); note the apex-vs-wildcard nuance — an apex domain is NOT covered by its `*.`-wildcard form, so the manifests carry both forms where observed (the blocked host names itself at run time). The upgrade Recommendations advisor renders exactly this as a HAND-APPLY item with the risk stated (`${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). Membership is the FROZEN review-wrapper constant, **never** the execution/probe wrappers (`codex-exec`, `agy-run` keep their human prompt — delegated execution is not covered by this consent), and only the **`code` review mode** — a `plan`/`diff` invocation takes a file argument that can point OUTSIDE the repo, so those modes keep their prompt; each wrapper entry derives ONLY when its bridge is **placed on PATH** (an absent bridge is a stated skip). The seeded byte-forms (this list IS the documented-invocation source for the bridge tier):
+
+- `Bash(codex-review code:*)` — the code-mode prefix, args wildcard; plus `codex-review` in `sandbox.excludedCommands`
+- `Bash(agy-review code:*)` — the code-mode prefix, args wildcard; plus `agy-review` in `sandbox.excludedCommands`
+- `Bash(node "${CLAUDE_SKILL_DIR}/tools/grounding.mjs":*)` — the grounding pre-step, **double-quoted absolute path**: exactly the byte-form the `procedures` advisor renders, so the pasted pre-step matches the rule (seeded↔rendered byte-parity). It derives ONLY when `agy-review` is placed (the pre-step exists for agy's grounded reviews; codex grounds natively) — a codex-only install never auto-allows this writer. The quoted form is accepted for THIS one tool only — never a general quote allowance; an unseedable kit path (spaces/metacharacters) is a stated skip. Its writer surface is closed by the tool's own guard: `--out` accepts only system-temp scratch (rewritable) or a FRESH gitignored in-repo path (create-only, exclusive write) — tracked, in-repo-not-ignored, EXISTING in-repo (even gitignored), outside-repo non-temp, and symlink/non-regular destinations are all refused.
+
+**Consented posture (printed on every `--bridge-tier` run, stated not pretended away):** an auto-allowed review wrapper runs **UNATTENDED** — it reads any repo file it is pointed at and sends the assembled payload to its **subscription backend**; prefix rules cannot inspect arguments, so a code-mode argument that names a readable file (agy's `--facts`/`--decided`) rides the same consent. That is the tier's purpose (unattended council review runs) and its residual. Tier entries get no PreToolUse-hook coverage — the same documented residual class as the autonomy red-line rules. The grounding entry's writer surface is bounded by `grounding.mjs`'s own scratch-destination guard (a tracked or in-repo-not-ignored `--out` is refused by the tool itself).
+
+**Invocation shape (why a run still prompts):** a prefix allow rule matches only a **PLAIN invocation starting with the wrapper name** — `codex-review code`, `agy-review code --facts @f`. An env-var prefix (`AGY_PROBE=1 agy-review …`) or a compound chain (`agy-review … && …`; `;`-joined statements) can NEVER match a prefix rule (observed live); output redirects are fine. Drive the wrappers as plain single commands.
+
 **Exit codes:** `0` done / dry-run; `1` a precondition STOP (stamp not current, unsafe mode, malformed settings, symlinked `.claude` / non-regular target); `2` bad arguments.
 
 ---
@@ -41,6 +52,6 @@ Honesty notes: tier entries get **NO PreToolUse-hook residual coverage** — the
 1. **Preview by default** (writes nothing); **`--apply`** merges the render-owned blocks into `.claude/settings.json` (merge-don't-clobber — foreign top-level keys, existing `permissions.allow`, and foreign ask/deny entries preserved; a policy flip MOVES a red-line rule between ask/deny rather than duplicating it). It **refuses an absent policy** loudly (seed one first with `set-autonomy`). It **never writes `settings.local.json`**; a `settings.local.json` `defaultMode` that would mask the render is reported (local > project).
 2. **`--autonomy --check`** is a **read-only drift gate**: it recomputes the render and compares against the live render-owned blocks — exit `0` in sync, exit `1` on drift (naming the exact key). A hand-edit OUTSIDE those blocks never flags.
 3. **Version-sensitive (characterized against the real claude 2.1.185).** Sandbox keys are `sandbox.enabled` + `sandbox.autoAllowBashIfSandboxed`; `sandbox` level ⇒ auto-allow + `defaultMode: acceptEdits`, `prompt` level ⇒ auto-allow OFF + `defaultMode: default` (the sandbox stays enabled as a confine floor either way). Red-lines use the argument-matching `:*` wildcard (`Bash(git commit:*)` / `Bash(git push:*)` / `Bash(npm publish:*)`). Where 2.1.185 cannot express a red-line distinctly — a **network hard-block** (regular settings only prompt on egress), **credential denial** (`sandbox.credentials` is 2.1.187+ / mask 2.1.199+), or a **prompt-on-outside-write** — the render **DEGRADES LOUDLY** (never a silent allow, never pretend-security). A missing Linux dependency (`socat`/`bwrap`) or an unsupported platform degrades the WHOLE sandbox to unsandboxed — the render still lands the red-lines + `defaultMode` and caveats that ad-hoc scripts will still prompt.
-4. **`--autonomy` cannot combine** with `--accept-edits` or `--kit-tools` (allowlist-mode flags) — a loud usage error.
+4. **`--autonomy` cannot combine** with `--accept-edits`, `--kit-tools`, or `--bridge-tier` (allowlist-mode flags) — a loud usage error.
 
 **Autonomy invariants:** policy-only (never seeds the allowlist, leaves `permissions.allow` untouched) · writes only `.claude/settings.json` (never `settings.local.json`) · refuses an absent policy · merge-don't-clobber · degrades loudly where 2.1.185 can't enforce · previews by default · never commits.

package/references/shared/composition-handoff.md

@@ -3,40 +3,45 @@
 **Hand-off contract (explicit; tested independent of agent interpretation).**
 - **Delegated** (memory valid): the kit passes the **target project dir** + the **three setup
   answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
-  `docs/ai/` + `AGENTS.md` (carrying the **two empty pointer pairs** — `workflow:methodology` and
-  `workflow:orchestration`) + **`.memory-version`**. The kit then **reconciles both bounded pointers**
-  (below) and writes the kit-fallback **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
+  `docs/ai/` + `AGENTS.md` (carrying the **three empty pointer pairs** — `workflow:methodology`,
+  `workflow:orchestration` and `workflow:autonomy`) + **`.memory-version`**. The kit then **reconciles
+  the bounded pointers** (below) and writes the kit-fallback **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
   hide authority**: after the hand-off it runs `tools/hide-footprint.mjs` (bootstrap step 9 — `${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`), which **absorbs
   memory's project-local footprint lines** into the one canonical `.git/info/exclude` block and adds
   the external footprint — so there is **no machine-global write** at any step (a stale memory's
   residual global block is cleaned via the upgrade reconcile, below).
 - **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`) from its own
-  bundled assets — whose entry-point template now ships **two empty pointer pairs** (`workflow:methodology`
-  + `workflow:orchestration`) the kit reconciles + fills — and writes **`.workflow-version`** only.
+  bundled assets — whose entry-point template now ships **three empty pointer pairs** (`workflow:methodology`
+  + `workflow:orchestration` + `workflow:autonomy`) the kit reconciles + fills — and writes **`.workflow-version`** only.
   Softly suggest installing `agent-workflow-memory` — never a prerequisite.
 
 **Bounded pointer reconciliation (the kit is the ONLY writer of these slots).** After `AGENTS.md`
 exists, run ONE command — `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile
-<project>/AGENTS.md` — which reconciles **two** bounded pointers in a single atomic write: the
-**workflow-methodology** pointer (the plan → execute → review summary) **and**, right below it, the
+<project>/AGENTS.md` — which reconciles **three** bounded pointers in a single atomic write: the
+**workflow-methodology** pointer (the plan → execute → review summary), the
 **orchestration-recipes** pointer (the Solo / Reviewed / Council / Delegated vocabulary, routing to
-`/agent-workflow-kit recipes`). Each is **one atomic operation per slot**: **ensure the slot exists**
+`/agent-workflow-kit recipes`) right below it, and the **autonomy-policy** pointer (the
+`docs/ai/autonomy.json` read contract) below that. Each is **one atomic operation per slot**:
+**ensure the slot exists**
 (insert an empty marker pair at its anchor when a legacy entry point lacks one) → **inject the bounded
 fragment ONLY IF the slot is empty** (a filled / user-customized slot is preserved verbatim) →
-**cap-check** (the second pointer's check runs on the file *after* the first, so it guards the
-**combined** ≤100-line budget). Both fragments are short summary + pointer, read **live from the
-installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`,
+**cap-check** (each chained pointer's check runs on the file *after* the previous one, so it guards the
+**combined** ≤100-line budget). The fragments are short summary + pointer, read **live from the
+installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`
++ `references/autonomy-slot.md`,
 the family's one source of truth) — **not** a bundled mirror, and **not** the full references. The
 live read is **lazy + fail-loud**: the engine is consulted **only when a slot actually needs filling**,
-so a deployment whose pointers are already filled reconciles to a zero-diff no-op even on a host
-without the engine; but when a fill **is** needed and the engine is **absent/invalid**, reconcile
+so a deployment with **all three** pointers filled reconciles to a zero-diff no-op even on a host
+without the engine (one still missing the autonomy pair needs the engine to gain it); when a fill
+**is** needed and the engine is **absent/invalid**, reconcile
 **STOPs** — report it in plain language with the one-line install command
 `npx @sabaiway/agent-workflow-engine@latest init` (`npx @sabaiway/agent-workflow-kit@latest init`
 installs the engine for you; translate, never leak tool internals). Contract per slot: exactly one
 ordered `start → end` pair; a malformed slot (single, reversed, nested, duplicate) or a missing /
-duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged). The
-**orchestration pointer is soft-skipped** (reported, never silent) when — and only when — adding it
-would exceed the 100-line cap: the methodology pointer still lands and the upgrade continues.
+duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged). A
+**chained pointer is soft-skipped** (reported, never silent) when — and only when — adding it would
+exceed the 100-line cap, the engine is too old to ship its fragment, or (autonomy only) its anchor
+(the orchestration pair) is absent: every prior pointer still lands and the upgrade continues.
 
 **Agent-rules lens refresh (runs in BOTH paths).** Its precondition is its own target file — run it
 only after `<project>/docs/ai/agent_rules.md` exists: after the substrate deploy in the

package/references/shared/report-footer.md

@@ -9,7 +9,11 @@ The tool runs the backend detector and appends the recipe recommendation itself
 recipe clause of its own, ever.
 
 - **Placeholder template (structure only — never copy this example; paste the tool's line):**
-  `backends: <alias> <✓|✗> <readiness> · <alias> <✓|✗> <readiness> — run /agent-workflow-kit backends · recipes: <recommendation clause> — see /agent-workflow-kit recipes`
+  `backends: <alias> <✓|✗> <readiness> · <alias> <✓|✗> <readiness> — run /agent-workflow-kit backends · recipes: <recommendation clause> — see /agent-workflow-kit recipes · autonomy: <per-activity levels> (<policy state>)`
+- The **`autonomy:` segment is appended by the composer itself** (`composeAutonomyFacts`, AD-044) —
+  per-activity levels + the policy state (computed defaults / declared / MALFORMED, loud) — the
+  agent never types it; the composer resolves the policy from the project root, so the line is
+  correct from any working directory inside the project.
 - The **`recipes:` clause is appended after** the `— run /agent-workflow-kit backends` pointer (never
   replacing it) and routes to the read-only `recipes` mode (`see /agent-workflow-kit recipes`). It is
   **never blank**: both backends ready → *"Council available, Reviewed the everyday default"*; one

package/references/templates/AGENTS.md

@@ -57,6 +57,8 @@ Start-of-session, during-work, and task-completion procedures live in [`docs/ai/
 <!-- workflow:methodology:end -->
 <!-- workflow:orchestration:start -->
 <!-- workflow:orchestration:end -->
+<!-- workflow:autonomy:start -->
+<!-- workflow:autonomy:end -->
 
 ---
 
@@ -68,7 +70,6 @@ Start-of-session, during-work, and task-completion procedures live in [`docs/ai/
 | No `any` / no unsafe casts | Linter / type-checker |
 | Functional style (no mutation in app code) | Linter |
 | Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
-| No hardcoded colors — design tokens only | Code review |
 | No business logic in components → hooks/services | Architecture review |
 | No changes without tests (TDD) | Required |
 | Check page docs before changes; update them after | Process |

package/references/templates/autonomy.json

@@ -0,0 +1,3 @@
+{
+  "_README": "Per-project autonomy policy: red-lines (always) + per-activity autonomy level. Hand-editable; or use the set-autonomy writer (previews, then writes valid JSON). Strict JSON — no comments."
+}

package/tools/autonomy-config.mjs

@@ -236,6 +236,15 @@ export const resolveAutonomy = (config) => {
   return { redlines, activities };
 };
 
+// isSparseSeedConfig(config) → true when the policy file is STRUCTURALLY the deploy seed: meta keys
+// only (`_README` today) — no red-lines section, no activity entry. Seed detection must be
+// structural, never resolved-equality: an EXPLICIT policy that declares exactly the default values
+// is a real DECLARATION (its render — the red-line ask rules included — must not be suppressed as
+// "just the seed"), while the seed declares nothing (codex, Segment B closing). Shared by every
+// autonomy read surface (advisor / recipes / procedures / grounding) so the four can never diverge.
+export const isSparseSeedConfig = (config) =>
+  isJsonObject(config) && Object.keys(config).every((k) => k.startsWith('_'));
+
 // ── pure merge + canonical serialization ────────────────────────────────────────────
 
 // A pure deep-equal over the JSON-ish policy shape (plain objects + string values). Used only for the
@@ -288,9 +297,10 @@ export const serializeAutonomy = (config) => {
 
 // ── the canonical seed (Decision 5) ──────────────────────────────────────────────────
 // AUTONOMY_README is the onboarding note; SEED_AUTONOMY is the Decision-5 fixture the set-autonomy
-// writer seeds and the config tests copy/validate verbatim. Plan 1 ships NO references/templates/
-// autonomy.json and NO template-parity test (both Plan 4) — SEED_AUTONOMY's Plan-1 consumers are the
-// autonomy-config tests and the render's "seed one first" guidance.
+// WRITER seeds (opinionated sandbox levels) and the config tests copy/validate verbatim. DISTINCT
+// from the Plan-4 deploy template `references/templates/autonomy.json` (bootstrap/upgrade ensure):
+// that seed is SPARSE — `_README` only, defaults-equivalent by the template-parity pin
+// (resolveAutonomy(template) ≡ resolveAutonomy(null)) — so deploying it never changes behavior.
 export const AUTONOMY_README =
   'Per-project autonomy policy: red-lines (always) + per-activity autonomy level. Hand-editable; or ' +
   'use the set-autonomy writer (previews, then writes valid JSON). Strict JSON — no comments.';

package/tools/commands.mjs

@@ -98,6 +98,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'List every command, grouped, marking each as read-only or as one that makes changes.',
   },
+  {
+    key: 'recommendations',
+    invocation: invocationOf('recommendations'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'See what in this deployment is configured sub-optimally — each item with a one-line benefit and the exact consent-gated command that applies it; renders even when everything is optimal.',
+  },
   {
     key: 'gates',
     invocation: invocationOf('gates'),
@@ -147,6 +154,13 @@ const CATALOG = [
     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: 'sandbox-masks',
+    invocation: invocationOf('sandbox-masks'),
+    group: 'Configure',
+    kind: GUARDED,
+    oneLine: 'Hide the sandbox’s injected device masks from git status via one managed block in the repo’s local exclude file — probe-derived (never a frozen list), preview first, full-block replace on your yes; reviews already ignore the masks by construction.',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),
@@ -187,7 +201,7 @@ const CATALOG = [
     invocation: invocationOf('grounding'),
     group: 'Orchestrate',
     kind: WRITER,
-    oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
+    oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints, the effective autonomy policy, plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
   },
   {
     key: 'review-ledger',

package/tools/delegation.mjs

@@ -27,6 +27,10 @@ export const EXPECTED_MEMORY_NAME = 'agent-workflow-memory';
 // DOES seed orchestration.json (Mode: upgrade step 3). This closes the stale-memory trap that the
 // read-only family-registry note (MEMORY_ORCH_TEMPLATE_REL) only INFORMS about — the gate ACTS. The
 // two key on the same asset; a cross-tool parity test pins them in lockstep.
+// The autonomy seed (AD-044 Plan 4) is deliberately NOT here: the Plan-3 decision stands — no
+// detectMemory autonomy-marker gate. A memory too old to ship references/templates/autonomy.json
+// stays delegable; the kit-side upgrade ensure seeds the policy from the kit's own template twin,
+// and the family-registry caveat INFORMS about the stale memory (inform, never gate).
 export const REQUIRED_MEMORY_ASSETS = [
   { path: 'references/templates', type: 'dir' },
   { path: 'references/templates/orchestration.json', type: 'file' },
@@ -85,7 +89,7 @@ export const handoffPlan = (delegate) =>
         memoryWrites: ['docs/ai/', 'AGENTS.md', 'docs/ai/.memory-version'],
         // The lens region runs AFTER the substrate deploy (its own precondition: the file exists)
         // — it converges a stale-memory seed to the installed engine's canon (AD-041).
-        kitWrites: ['AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
+        kitWrites: ['AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.memory-version', '.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',
@@ -93,11 +97,11 @@ export const handoffPlan = (delegate) =>
     : {
         mode: 'fallback',
         memoryWrites: [],
-        // Fallback now ships the kit's OWN AGENTS.md carrying the EMPTY methodology slot (Plan 2);
-        // the kit reconciles it (ensure-slot + inject-because-empty) exactly like the delegate
-        // path — so both paths end with a FILLED slot, not inline methodology. The lens region
+        // Fallback now ships the kit's OWN AGENTS.md carrying the EMPTY pointer slots (Plan 2);
+        // the kit reconciles them (ensure-slot + inject-because-empty) exactly like the delegate
+        // path — so both paths end with FILLED slots, not inline methodology. The lens region
         // runs after the fallback-template copy of docs/ai (same reconcile, both paths — AD-041).
-        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
+        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',

package/tools/detect-backends.mjs

@@ -88,7 +88,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
-        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); a write failure warns, never fails the review',
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); a write failure warns, never fails the review',
       },
     },
     bin: 'codex',
@@ -121,7 +121,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
       },
     },
     bin: 'agy',

package/tools/doc-parity.mjs

@@ -27,12 +27,15 @@ import { SCHEMA_VERSION, REVIEW_CAP, V4_CLASSES, V4_OVERRIDE_SCOPES } from './re
 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';
+import { RECOMMENDATIONS_SECTION_HEADER, RECOMMENDATIONS_EMPTY_LINE } from './recommendations.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';
+const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
+const UPGRADE_DOC = 'references/modes/upgrade.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 });
@@ -72,6 +75,11 @@ export const BINDINGS = Object.freeze([
     .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]),
+  // The upgrade Recommendations section contract (AD-044 Plan 4): the section header and the
+  // exact empty-state line must render in BOTH the mode doc and upgrade.md (both exits reference
+  // them) — a reworded doc would silently break the paste-verbatim contract.
+  valueBinding('recommendations-header', RECOMMENDATIONS_SECTION_HEADER, RECOMMENDATIONS_SECTION_HEADER, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
+  valueBinding('recommendations-empty-line', RECOMMENDATIONS_EMPTY_LINE, RECOMMENDATIONS_EMPTY_LINE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────

package/tools/engine-source.mjs

@@ -31,6 +31,12 @@ export const ORCHESTRATION_FRAGMENT_REL = 'references/orchestration-slot.md';
 // CLI fail loudly on — an engine too old to ship it. readEngineFragment accepts an arbitrary `rel`
 // (no whitelist), so no further plumbing is needed beyond this constant.
 export const PROCEDURES_FRAGMENT_REL = 'references/procedures.md';
+// The autonomy-policy slot fragment — the THIRD bounded fragment the kit injects (AD-044 Plan 3),
+// the cross-agent read contract for docs/ai/autonomy.json. An engine released before it does not
+// ship it; detectEngine({ rel }) lets the chained reconcile soft-skip that too-old engine (and
+// `status` caveat it) instead of discarding the methodology/orchestration fills. readEngineFragment
+// accepts an arbitrary `rel`, so no further plumbing is needed beyond this constant.
+export const AUTONOMY_FRAGMENT_REL = 'references/autonomy-slot.md';
 // The agent-rules lens pair — the canonical lens block + its append-only prior store (engine
 // >= 1.13.0; an older engine ships neither). The kit's lens-region reconcile live-reads BOTH via
 // readEngineFragment({ rel }); detectEngine({ rel }) lets it soft-skip a too-old engine (and

package/tools/family-registry.mjs

@@ -26,7 +26,7 @@ import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
 import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
-import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
+import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, AUTONOMY_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
 import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
 // The config reader lives in orchestration-config.mjs (the single config contract). The read-only status
 // settings-survey reuses THIS reader (one strict-JSON + loud-on-malformed contract), not a second copy.
@@ -182,6 +182,7 @@ export const classifyMember = (member, deps = {}) => {
 // caveat keys on both — an engine missing only the prior store must never report healthy.
 const ENGINE_FRAGMENT_CAVEATS = [
   { rels: [ORCHESTRATION_FRAGMENT_REL], caveat: 'engine present but does not supply the recipes pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [AUTONOMY_FRAGMENT_REL], caveat: 'engine present but does not supply the autonomy pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
   { rels: [PROCEDURES_FRAGMENT_REL], caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
   { rels: [LENS_FRAGMENT_REL, LENS_PRIORS_REL], caveat: 'engine present but does not ship the agent-rules lens canon (the fragment + its prior store; too old / incomplete — engine >= 1.13.0) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
 ];
@@ -192,10 +193,16 @@ const ENGINE_FRAGMENT_CAVEATS = [
 // adds a parity drift-guard tying this path to that required-asset set, so the note and the gate can
 // never key on different files (until then they are kept in lockstep by review).
 export const MEMORY_ORCH_TEMPLATE_REL = 'references/templates/orchestration.json';
+// The autonomy-policy seed (AD-044 Plan 4) gets the SAME inform-never-gate treatment: the
+// delegation gate deliberately does NOT key on it (the Plan-3 decision), so this caveat is the
+// discovery mechanism — the recommendations advisor surfaces it via surveyFamily.
+export const MEMORY_AUTONOMY_TEMPLATE_REL = 'references/templates/autonomy.json';
 // Worded as an honest OBSERVATION, not a diagnosis (absence can mean old OR incomplete), and it makes
 // NO claim about an orchestration.json seeding outcome (that depends on delegate-vs-fallback).
 const MEMORY_BEHIND_NOTE =
   "the memory installed here doesn't include the current orchestration template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
+const MEMORY_AUTONOMY_BEHIND_NOTE =
+  "the memory installed here doesn't include the current autonomy-policy template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
 
 // ── the bridge freshness probe (deterministic-first — INV-A / INV-B) ─────────────
 // The bridges are not npm packages: their ONLY delivery channel is the copy bundled inside this kit
@@ -261,12 +268,19 @@ export const surveyFamily = (deps = {}) =>
     // Only attach when it is provably ABSENT (a non-ENOENT probe error → 'unknown' → skip, never a
     // false "missing" claim). Mirrors the engine-caveat SHAPE; keyed on the Step-2.4 required asset.
     if (row.kind === 'memory-substrate' && row.manifestState === OK && row.skillDir) {
-      const templateProbe = probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps);
-      if (templateProbe === 'absent') {
-        row.caveats = [...(row.caveats ?? []), MEMORY_BEHIND_NOTE];
-      } else if (templateProbe === 'unknown') {
-        // Could not verify → this row must not be counted "checked, current" by the verdict (INV-B).
-        row.freshness = FRESH_UNKNOWN;
+      // Two required-template probes, same shape: orchestration (Step 2.4) + autonomy (AD-044
+      // Plan 4 — inform, never gate). Each attaches its own caveat on provable absence only.
+      for (const [rel, note] of [
+        [MEMORY_ORCH_TEMPLATE_REL, MEMORY_BEHIND_NOTE],
+        [MEMORY_AUTONOMY_TEMPLATE_REL, MEMORY_AUTONOMY_BEHIND_NOTE],
+      ]) {
+        const templateProbe = probeMarker(join(row.skillDir, rel), deps);
+        if (templateProbe === 'absent') {
+          row.caveats = [...(row.caveats ?? []), note];
+        } else if (templateProbe === 'unknown') {
+          // Could not verify → this row must not be counted "checked, current" by the verdict (INV-B).
+          row.freshness = FRESH_UNKNOWN;
+        }
       }
     }
     // Bridge freshness probe (INV-A / INV-B): only for a provably-OURS placed bridge (manifestState

package/tools/fold-completeness-run.mjs

@@ -1029,6 +1029,11 @@ loud advisory failure) but leaves --check unaffected.
 
 The read-only gate is a SEPARATE tool: node fold-completeness.mjs --check / --status / --json.
 
+Sandbox-safe: the RUNNER itself needs no network and writes only repo-local state (the D4 sandbox
+lane). The spawned suite/bound commands are COMMAND-SHAPE dependent — --suite / AW_FOLD_SUITE_CMD /
+AW_FOLD_BOUND_CMD / the verification profile can name project-defined commands; the default
+(node --test on stdout TAP) is plain and no-network — keep overrides sandbox-safe by shape.
+
 Exit codes: 0 written / advisory printed; 1 a typed STOP (loop derivation / suite discovery / a --red
 or --reattest refusal / a malformed SARIF on --findings / malformed record / fs error); 2 usage.`;