@sabaiway/agent-workflow-kit 1.35.0 → 1.36.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.36.0 — Review-round ledger: the prose crossover-stop becomes a computed signal (AD-045)
+
+A **feature** release (deployment-lineage head stays `1.3.0` — no migration). The review-loop
+crossover-stop that `planning.md` §9 and `procedures.md` describe in prose — "cap ≤2 rounds", the
+crossover, "fold-at-altitude vs residual", "{round N · finding-origin tally · per-backend verdict} …
+a computed signal, not a remembered rule" — was **prose with no checker** and broke under load. This
+ships it as a **mechanism** (DEBT-REVIEW-CAP): a review-round **LEDGER** that protects every consumer
+project's `plan-execution` review loop.
+
+- **`tools/review-ledger.mjs`** (read-only) — the record schema (two kinds, `round` / `triage`,
+  internally-consistency-validated), a tolerant reader (malformed lines counted + surfaced, never
+  dropped), the pure **`decideStop`** truth table returning exactly one state under a fixed precedence
+  (**converged > resolved-residual > triage-required > continue**) from machine fields only, the
+  integrity receipt cross-check, and the **`--check`** gate — **fail-CLOSED** on every unknown state
+  (detector failure · unreadable / malformed ledger · a corrupt round sequence · more than one plan
+  in flight).
+- **`tools/review-ledger-write.mjs`** (the sole writer, over the hardened `atomic-write` core) —
+  `record` / `classify` with **the teeth**: it refuses a round while triage is required, beyond the
+  hard-max ceiling of 3, or without a grounded review receipt, and enforces round-sequence integrity +
+  round-bound classifications. The read/write split is pinned by an import-split test; the ledger lives
+  in the git dir (uncommittable by construction, mirroring the receipts precedent).
+- **Command surface** — a `review-ledger` catalog entry + `### Mode: review-ledger` + its mode
+  reference; the conditional `seed-gates` candidate (offered only when `plan-execution.review` is
+  reviewed / council).
+- **Honest residual** (stated in the tool header, like `review-state`'s): the ledger attests a review
+  occurred and its ship-class is consistent; it does not prove the recorded counts are truthful nor
+  that a self-reported `degraded` is real — a self-discipline mechanism, not a security boundary.
+
+Self-arming dogfood: this release's own review loop was recorded through the ledger it builds
+(`--check` exits 0 via the `converged` branch). The optional per-fold `testId` slot exists but stays
+**unenforced** — enforcement + a fold-completeness signal + the canon-pointer mechanization are the
+next plan (DEBT-TEST-COMPLETENESS).
+
 ## 1.35.0 — Host-level bridge settings surface + Codex Fast tier as configuration (AD-043)
 
 A **feature** release (deployment-lineage head stays `1.3.0` — no migration). Bridge knobs like the

package/SKILL.md

@@ -3,12 +3,12 @@ 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.35.0'
+  version: '1.36.0'
 ---
 
 # agent-workflow-kit
 
-Deploys a **portable AI-agent memory-and-workflow system** into a project, and upgrades it as the kernel evolves — so any future agent can reconstruct project context in ~60 seconds and avoid repeating past mistakes.
+Deploys a **portable AI-agent memory-and-workflow system** into a project, and upgrades it as the kernel evolves — so any future agent can reconstruct project context fast and avoid repeating past mistakes.
 
 **Posture:** never leak kit internals — translate tool outcomes to plain language; Gotchas: `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`.
 
@@ -23,14 +23,13 @@ when it is present and healthy, and otherwise uses its **own bundled copy** (`re
 `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
 installed `agent-workflow-engine`**, which `npx @sabaiway/agent-workflow-kit@latest init` installs — a
-runtime dependency placed by `init` and read live; see `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md`.)
+runtime dependency read live; see `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md`.)
 `init` also **refreshes the installed memory substrate** (best-effort — a miss is a loud DEGRADED
-success: a warning with the exact recovery command + exit 0, never silent, never the engine's hard
-STOP; `--no-memory` skips it), so a returning `init` leaves **no stale core member**. The
+success: warn + the exact recovery command + exit 0, never silent, never the engine's hard STOP;
+`--no-memory` skips it), so a returning `init` leaves **no stale core member**. The
 execution-backend bridges are still never **placed** by `init` (placed on demand by `setup`, opt-in);
-**once placed**, `init` **refreshes** them from the kit's own bundled copies (refresh-only, local
-files, never a downgrade; `--no-bridges` skips it) — so a returning `init` leaves no stale placed
-bridge either.
+**once placed**, `init` **refreshes** them from the kit's own bundled copies (refresh-only, never a
+downgrade; `--no-bridges` skips it) — so a returning `init` leaves no stale placed bridge either.
 
 **Detection (kit-owned, decided BEFORE any project write).** Run the kit's **own shipped**
 validator — `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs <memory-skill-dir>` — never a
@@ -38,9 +37,8 @@ validator shipped by the candidate (which could itself be broken). Delegate only
 hold:
 - result is **valid** and `kind` is `memory-substrate`;
 - **every required asset is present** in the candidate, at its real path:
-  `references/templates/`, **`references/templates/orchestration.json`** (the orchestration-config
-  template — a memory too old to ship it, pre-`1.2.0`, can't seed `docs/ai/orchestration.json`, so it
-  falls back to the kit's own bundled substrate, which does), `references/contracts.md`,
+  `references/templates/`, **`references/templates/orchestration.json`** (a pre-`1.2.0` memory can't
+  ship it, so it falls back to the kit's bundled substrate), `references/contracts.md`,
   `references/scripts/`, `scripts/stamp-takeover.mjs`, `migrations/`, `capability.json`. A partial
   install (manifest + `SKILL.md` only) is treated as **invalid**.
 
@@ -81,7 +79,7 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide
 **Two independent version axes — never conflate them:**
 
 1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`1.3.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 (e.g. `1.x`) is **not** the lineage head.
+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?** The skill you are running is whatever was on disk when the session started. 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 (the slash command + this `SKILL.md`).
 
@@ -125,6 +123,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/procedures.md` before a
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md` before acting.
 
+### Mode: set-autonomy
+
+writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-autonomy.md` before acting.
+
 ### Mode: uninstall
 
 guarded — read `${CLAUDE_SKILL_DIR}/references/modes/uninstall.md` before acting.
@@ -153,6 +155,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` before
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/grounding.md` before acting.
 
+### Mode: review-ledger
+
+writer — read `${CLAUDE_SKILL_DIR}/references/modes/review-ledger.md` before acting.
+
 ---
 
 ## References

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.35.0",
+  "version": "1.36.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/review-ledger.md

@@ -0,0 +1,28 @@
+### Mode: review-ledger
+
+The review-round **LEDGER** (DEBT-REVIEW-CAP / AD-045) — it turns the prose review-loop crossover-stop (`planning.md` §9 "cap ≤2 / crossover-stop / fold-at-altitude"; `procedures.md` "{round N · finding-origin tally · per-backend verdict} … computed signal, not a remembered rule") into a **COMPUTED** signal. The orchestrator records **one round per review round** to a JSONL ledger **inside the git dir** (`<git dir>/agent-workflow-review-ledger.jsonl` — never committable by construction; `AW_REVIEW_LEDGER` overrides), and a read-only checker computes the stop decision from the recorded rounds + triage classifications, never from a remembered rule. It is the read-only sibling of `review-state` (presence vs convergence are distinct axes) — the read module **never imports the writer** (an import-split test pins it).
+
+**Two tools — the read/write split (Decision 3):**
+
+1. **Read-only checker** — `node ${CLAUDE_SKILL_DIR}/tools/review-ledger.mjs [--check | --status | --json]`:
+   - `--status` (default) → the human report: resolved `plan-execution.review` recipe, plan-in-flight, per-round tally with `findings[]`, per-backend counts + verdict, the `decideStop` verdict. **This printed render REPLACES the remembered per-round `{round N · finding-origin tally · per-backend verdict}` emission** — run it each round instead of composing the tally by hand.
+   - **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it). It enforces the **plan-execution (code) loop** (the loop that produces the committable artifact), filtered to `activity==="plan-execution"` AND the in-flight plan's filename stem: exit 0 for solo / no plan in flight / a clean tree / a non-git cwd / a `converged` or `resolved-residual` loop; exit 1 for a dirty non-converged loop (`triage-required`, `continue`, or **no round/receipt recorded at all** — a dirty active plan with an empty/stale ledger is a FAILURE, not a fail-open pass), more than one plan in flight (ambiguous loop id), a recorded 0/0 coexisting with a non-ship receipt verdict, or a non-degraded recorded backend missing its receipt. **Fail-CLOSED** on a detector failure — the only detector-independent green is an EXPLICIT configured solo.
+   - `--json` → the structured state + decision.
+
+2. **Writer** — `node ${CLAUDE_SKILL_DIR}/tools/review-ledger-write.mjs record|classify --json '<payload>'` (the SOLE writer, over the shared `atomic-write` core):
+   - `record` appends one round — `{ loop, round, origins, backends, findings }` (activity defaults to `plan-execution`). **The teeth (Decision 5):** it REFUSES (typed STOP) to append a round WHILE `decideStop` on the existing records is `triage-required` (an UNCLASSIFIED surviving blocking finding at/after the cap), and refuses ANY round beyond the **hard-max ceiling of 3** unconditionally. **Integrity binding (Decision 7):** each NON-degraded backend needs a grounded **code** receipt (from `codex-review code` / `agy-review code --facts @f`) for the current tree — a round cannot be recorded for a tree no bridge reviewed.
+   - `classify` appends one triage — each surviving blocking finding classified `fixable-bug` / `inherent-layer-residual` / `escalate`. **This is what BREAKS the deadlock:** once every surviving blocking finding is classified, `record` permits the next round (a `fixable-bug` classification lets the fix round run — no deadlock).
+
+**The computed stop (`decideStop`, precedence `converged > resolved-residual > triage-required > continue`).** Machine fields only (counts, `class`, `accepted`, `fingerprint`), never free-text:
+- **converged** — every recipe-named backend present, **non-degraded, at 0 blockers + 0 majors** in the latest round, at the current tree fingerprint. **"Surviving blocking finding" = a blocker OR a major** (a minor never forces triage).
+- **resolved-residual** — at/after the cap (or a recurrence auto-trip), every surviving blocking finding classified `inherent-layer-residual` (document + raise to an acceptance criterion → NEVER folded again) OR `escalate` with `accepted:true`, and the triage's own fingerprint equals the current tree (a doc edit after the triage → a fresh round).
+- **triage-required** (the writer HARD STOP) — a surviving blocking finding is UNCLASSIFIED at/after the cap, or a blocking finding recurred in ≥2 rounds still unclassified (even under the cap). `fixable-bug` → fold ONCE, re-review; `escalate` needs an accepted maintainer outcome.
+- **continue** — the catch-all: under the cap, or a classified-but-not-resolved loop (fold the `fixable-bug` / obtain the `escalate` outcome, then a fresh round).
+
+**"Every named backend" = "every NON-degraded named backend" (Decision 4).** A backend recorded `degraded:true` (agy is Issue-001-degraded on large diffs) is EXCLUDED from the 0/0 convergence requirement AND from the receipt cross-check (it ran no real review, mints no receipt), but is RECORDED (verdict `degraded`, a required `reason`) — it can never FAKE convergence. A recipe-named backend with NO entry is `missing` (≠ degraded) and BLOCKS convergence. Because the `degraded` mark is self-reported, `--check` surfaces every degraded backend loudly.
+
+**Wire `--check` as a gate by hand OR via the explicit-consent seeder — never without consent.** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-ledger", "title": "Review-round ledger: the in-flight loop is converged or accepted-residual", "cmd": "node <path-to-this-skill>/tools/review-ledger.mjs --check" }` — the path your project reaches the kit by, QUOTED. The consent-gated seeder offers exactly this entry ONLY when `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review`.
+
+**Human residual (stated, accepted — like `review-state`'s):** the ledger attests a review occurred and its ship-class is consistent; it does NOT prove the recorded COUNTS are truthful, nor that a self-reported `degraded:true` is real (`git commit --no-verify`, ledger-file editing, and forged counts remain possible). The ledger lives in the git dir (never committable) — a self-discipline mechanism against silent process drift, not a security boundary.
+
+**Invariants:** the read module is read-only · never commits · never runs a subscription CLI · spawns read-only `git` queries only · the SOLE writer is `review-ledger-write.mjs`, which the read module NEVER imports (structural read/write split, import-split test) · `hardMax` is a writer-only ceiling, never a `decideStop` input.

package/references/modes/set-autonomy.md

@@ -0,0 +1,29 @@
+### Mode: set-autonomy
+
+The **policy writer** for `docs/ai/autonomy.json` — the answer to *"set my autonomy policy without hand-editing JSON."* **Division of labor:** YOU turn the user's plain language into explicit ops; the KIT does the deterministic validate → merge → preview → write. It **previews by default** (writes nothing); `--write` applies. It **never renders enforcement** (that is the separate velocity autonomy mode — this writer touches only the policy file), **never runs a backend, and never commits**. Hand-editing `docs/ai/autonomy.json` stays fully supported — an offered convenience, never a lock.
+
+**The policy** has two parts: **red-lines** (always hold, segment-independent) + a **per-activity autonomy level**.
+
+- **red-lines** (`redlines.<key>` = `ask` | `deny`): the outward/irreversible actions. `commit` / `push` / `publish` (default **ask** — commit stays the human checkpoint); `network` / `credentials` / `fs_outside_repo` (default **deny** — the conservative floor).
+- **autonomy** (`<activity>.autonomy` = `sandbox` | `prompt`) per activity (`plan-authoring`, `plan-execution`): `sandbox` ⇒ auto-allow confined commands + accept edits; `prompt` ⇒ conservative prompting (the sandbox still confines). An absent activity floors at `prompt`.
+
+**Map the user's plain language → explicit ops** (the kit ships no NL parser; it performs no `all`-magic, so you expand scope explicitly, asking when unclear — localize the interpretation to the user's language at narration time, but keep the ops exact):
+
+| user intent | op |
+|---|---|
+| more autonomous when executing | `--set plan-execution.autonomy=sandbox` |
+| prompt while planning | `--set plan-authoring.autonomy=prompt` |
+| always ask before commit | `--set redlines.commit=ask` |
+| block the network | `--set redlines.network=deny` |
+| revert / do it as before | `--unset <section>.<key>` (→ its computed default) |
+
+Run **`node ${CLAUDE_SKILL_DIR}/tools/set-autonomy.mjs [--set <section>.<key>=<value>]… [--unset <section>.<key>]… [--write] [--json]`**:
+
+1. **Grammar — always fully-qualified `<section>.<key>`** (the kit never guesses the section; a bare `commit=ask` is rejected). Sections/keys: `redlines.{commit,push,publish,network,credentials,fs_outside_repo}` (each `ask|deny`); `plan-authoring.autonomy`, `plan-execution.autonomy` (each `sandbox|prompt`).
+2. **Preview by default** — prints `current → proposed` for the **changed** keys only, plus each key's **effective value** (an `--unset` shows its computed default). It writes **nothing**. Re-run with **`--write`** to apply. A no-op `--set` (value already equals) writes nothing and never re-seeds the onboarding note.
+3. **`--write`** applies via a hardened, atomic write (deployment-gated — refuses to scatter a policy into a repo with no `docs/ai`; exclusive-create temp + rename; symlink/TOCTOU-safe; last-writer-wins). It preserves the onboarding note + every untouched key, normalizing to canonical 2-space JSON. After a write it points at the **velocity autonomy render** as the next step (rendering the policy into `.claude/settings.json` is a separate, previewed step — this writer never touches settings).
+4. **Exit codes:** `0` success; `2` usage (a bare/duplicate op, or `--write` with no ops); `1` config error (malformed/unreadable policy — the file is left **untouched**, never clobbered) or a write STOP (no deployment / a symlinked policy). A `1`/`2` failure is loud; on a malformed policy, offer to show the parse error so you can help the user fix the JSON.
+
+Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
+
+**Invariants:** writer (writes only `docs/ai/autonomy.json`) · never renders enforcement · never runs a backend · never commits · previews by default · hand-edit stays first-class.

package/references/modes/velocity.md

@@ -31,3 +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.
 
 **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.
+
+---
+
+## The `--autonomy` render (separate mode — AD-044)
+
+`--autonomy` is a **separate mode** from the allowlist seeding above: it renders the per-project autonomy policy (`docs/ai/autonomy.json`, written by `set-autonomy` — `${CLAUDE_SKILL_DIR}/references/modes/set-autonomy.md`) into the `.claude/settings.json` blocks it **owns** — the `sandbox` block, `permissions.ask`/`permissions.deny` red-lines, and `permissions.defaultMode`. It is **policy-only**: it never seeds the read-only allowlist and leaves `permissions.allow` untouched as a value. Run **`node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs --autonomy [--apply] [--cwd <dir>]`**:
+
+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.
+
+**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/tools/autonomy-config.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// autonomy-config.mjs — the schema / read / pure-transform core for the per-project autonomy policy
+// (docs/ai/autonomy.json). It is the SINGLE source of the policy contract, mirroring
+// orchestration-config.mjs structurally (AD-044):
+//
+//   loadAutonomy / validateAutonomy / AUTONOMY_REL — the strict-JSON reader the read-only surfaces
+//                                                    share (the Claude render imports loadAutonomy).
+//   parseAutonomyOp / assertAutonomyAssignment      — the TYPED op parser + the ONE section/key/value
+//                                                    validity table the set-autonomy writer reuses
+//                                                    (drift-guarded: one accept/reject grammar).
+//   applyAutonomyOps / serializeAutonomy            — the PURE merge + the canonical (2-space,
+//                                                    _README-first) serializer the writer commits.
+//   resolveAutonomy                                 — the pure computed-defaults resolver (sparse →
+//                                                    effective policy); the render + any future read
+//                                                    surface share this ONE resolver.
+//
+// This module performs NO filesystem WRITES — only reads (loadAutonomy). The single fs-writer lives in
+// autonomy-write.mjs, which no read-only module imports, so the read surface stays fs-write-free.
+// Pure-where-possible (fs injectable), dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { ACTIVITIES } from './recipes.mjs';
+
+// The hand-editable / agent-writable, per-project policy (strict JSON). cwd-relative — the error prefix
+// uses this rel path so a user sees a path they can open, never an absolute temp/host path.
+export const AUTONOMY_REL = 'docs/ai/autonomy.json';
+
+// A tagged failure: a plain Error carrying the intended process exit code (2 usage / 1 config). Avoids
+// a class (project rule) while letting a CLI main() map a throw to the right code in one place. Shared
+// so set-autonomy.mjs raises identically-typed errors (mirrors orchestration-config.mjs `fail`).
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+// ── the grammar tables (Decision 5) — the ONE shared accept/reject data ──────────────
+// Both validateAutonomy and parseAutonomyOp read THESE tables (never a second hand-copy), so the
+// accept/reject decision can never drift between config-validation and the writer's op parser (pinned
+// by the full-matrix drift test, the orchestration recipeValidForSlot precedent).
+
+// The six red-lines split into command red-lines (commit/push/publish) and non-command red-lines
+// (network/credentials/fs_outside_repo). Both take `ask` or `deny`; only the Decision-4 DEFAULT differs.
+export const COMMAND_REDLINES = Object.freeze(['commit', 'push', 'publish']);
+export const NONCOMMAND_REDLINES = Object.freeze(['network', 'credentials', 'fs_outside_repo']);
+export const REDLINE_KEYS = Object.freeze([...COMMAND_REDLINES, ...NONCOMMAND_REDLINES]);
+export const REDLINE_VALUES = Object.freeze(['ask', 'deny']);
+// Decision 4 defaults: command red-lines default to `ask` (commit stays the human checkpoint), the
+// non-command red-lines default to `deny` (network/credentials/fs escape are the conservative floor).
+export const REDLINE_DEFAULTS = Object.freeze({
+  commit: 'ask', push: 'ask', publish: 'ask',
+  network: 'deny', credentials: 'deny', fs_outside_repo: 'deny',
+});
+
+// Per-activity autonomy level (Decision 2): `sandbox` ⇒ auto-allow + acceptEdits; `prompt` ⇒
+// conservative prompting (sandbox still confines). An absent activity floors at `prompt` (Decision 5).
+export const AUTONOMY_LEVELS = Object.freeze(['sandbox', 'prompt']);
+export const DEFAULT_ACTIVITY_AUTONOMY = 'prompt';
+export const ACTIVITY_KEY = 'autonomy';
+export const REDLINES_SECTION = 'redlines';
+
+const KNOWN_ACTIVITIES = () => Object.keys(ACTIVITIES).join(', ');
+const KNOWN_SECTIONS = () => `${REDLINES_SECTION}, ${KNOWN_ACTIVITIES()}`;
+const isJsonObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// ── the ONE section/key/value validity grammar (shared accept/reject) ────────────────
+// assignmentValid is the PURE predicate (mirror recipeValidForSlot) the full-matrix drift test pins;
+// assertAutonomySlot / assertAutonomyAssignment are the LOUD assertions the op parser uses. All read
+// the same tables above, so parseAutonomyOp and validateAutonomy can never disagree.
+
+// True iff (section, key) is a known slot of the policy (redlines.<redline> | <activity>.autonomy).
+export const slotValid = (section, key) => {
+  if (section === REDLINES_SECTION) return REDLINE_KEYS.includes(key);
+  if (ACTIVITIES[section]) return key === ACTIVITY_KEY;
+  return false;
+};
+
+// Accepted values for a KNOWN slot: red-lines take ask|deny; an activity's autonomy takes sandbox|prompt.
+export const acceptedValuesFor = (section) => (section === REDLINES_SECTION ? REDLINE_VALUES : AUTONOMY_LEVELS);
+
+// True iff (section, key, value) is a fully-valid assignment. Pure predicate; throws nothing.
+export const assignmentValid = (section, key, value) =>
+  slotValid(section, key) && acceptedValuesFor(section).includes(value);
+
+// Assert (section, key) is a known slot; return its kind ('redline' | 'activity'). Loud (exit 2 by
+// default) with the shared "unknown section" / "unknown slot" message the op parser emits.
+export const assertAutonomySlot = (section, key, exitCode = 2) => {
+  if (section === REDLINES_SECTION) {
+    if (!REDLINE_KEYS.includes(key)) {
+      throw fail(exitCode, `unknown red-line "${key}" (known: ${REDLINE_KEYS.join(', ')})`);
+    }
+    return 'redline';
+  }
+  if (ACTIVITIES[section]) {
+    if (key !== ACTIVITY_KEY) {
+      throw fail(exitCode, `unknown key "${key}" for activity "${section}" (only: ${ACTIVITY_KEY})`);
+    }
+    return 'activity';
+  }
+  throw fail(exitCode, `unknown section "${section}" (known: ${KNOWN_SECTIONS()})`);
+};
+
+// Assert (section, key, value) is a fully-valid assignment — unknown section/key OR bad value → loud.
+// Used by the set-autonomy op parser AND (with exitCode 1) by validateAutonomy, so they accept/reject
+// in lockstep on ONE grammar. Returns the slot kind.
+export const assertAutonomyAssignment = (section, key, value, exitCode = 2) => {
+  const kind = assertAutonomySlot(section, key, exitCode);
+  const accepted = acceptedValuesFor(section);
+  if (typeof value !== 'string' || !accepted.includes(value)) {
+    throw fail(exitCode, `invalid value "${value}" for ${section}.${key} (accepts: ${accepted.join(', ')})`);
+  }
+  return kind;
+};
+
+// ── the typed op parser (usage errors → exit 2) ─────────────────────────────────────
+// The grammar is ALWAYS fully-qualified `<section>.<key>` — the writer never guesses a section. A bare
+// `commit=ask` is rejected (name the section). No `all`-magic; the agent expands plain language into
+// explicit per-key ops (asking if scope is unclear) — the set-recipe division of labor.
+
+const parseQualified = (lhs, flag) => {
+  const dot = lhs.indexOf('.');
+  if (dot <= 0 || dot === lhs.length - 1) {
+    throw fail(
+      2,
+      `${flag} must be fully-qualified <section>.<key> (got "${lhs}") — name the section, e.g. redlines.commit / plan-execution.autonomy`,
+    );
+  }
+  return { section: lhs.slice(0, dot), key: lhs.slice(dot + 1) };
+};
+
+// parseAutonomyOp(kind, token) → a typed record:
+//   kind 'set'   + token `<section>.<key>=<value>` → { kind:'set', section, key, value }
+//   kind 'unset' + token `<section>.<key>`         → { kind:'unset', section, key }
+// Every malformed token is a USAGE error (exit 2): a bare key (no section), an unknown section/key, a
+// bad value, a missing value on --set, or a stray value on --unset.
+export const parseAutonomyOp = (kind, token) => {
+  if (kind === 'set') {
+    const eq = token.indexOf('=');
+    if (eq <= 0) throw fail(2, `--set must be <section>.<key>=<value> (got "${token}")`);
+    const value = token.slice(eq + 1);
+    if (!value) throw fail(2, `--set must be <section>.<key>=<value> (got "${token}")`);
+    const { section, key } = parseQualified(token.slice(0, eq), '--set');
+    assertAutonomyAssignment(section, key, value);
+    return { kind: 'set', section, key, value };
+  }
+  if (token.includes('=')) throw fail(2, `--unset takes <section>.<key> without a value (got "${token}")`);
+  const { section, key } = parseQualified(token, '--unset');
+  assertAutonomySlot(section, key);
+  return { kind: 'unset', section, key };
+};
+
+// ── policy validation (config errors → exit 1) ──────────────────────────────────────
+
+// Validate a parsed autonomy.json object against the Decision-5 grammar. Strict: an unknown top-level
+// key, an unknown red-line, an unknown activity/key, or a bad value is an error. All keys optional
+// (sparse). An optional "_README" string key is allowed + ignored. Never a silent fallback — every
+// rejection is a loud `path: reason` (exit 1). Returns the config on success.
+export const validateAutonomy = (config) => {
+  if (!isJsonObject(config)) {
+    throw fail(1, `${AUTONOMY_REL}: must be a JSON object (red-lines + per-activity autonomy)`);
+  }
+  for (const [key, val] of Object.entries(config)) {
+    if (key === '_README') {
+      if (typeof val !== 'string') throw fail(1, `${AUTONOMY_REL}: "_README" must be a string`);
+      continue;
+    }
+    if (key === REDLINES_SECTION) {
+      if (!isJsonObject(val)) throw fail(1, `${AUTONOMY_REL}: "${REDLINES_SECTION}" must be a JSON object of red-line → ask|deny`);
+      for (const [rk, rv] of Object.entries(val)) {
+        try {
+          assertAutonomyAssignment(REDLINES_SECTION, rk, rv, 1);
+        } catch (err) {
+          throw fail(1, `${AUTONOMY_REL}: ${err.message}`);
+        }
+      }
+      continue;
+    }
+    if (ACTIVITIES[key]) {
+      if (!isJsonObject(val)) throw fail(1, `${AUTONOMY_REL}: activity "${key}" must be a JSON object of { ${ACTIVITY_KEY}: sandbox|prompt }`);
+      for (const [ak, av] of Object.entries(val)) {
+        try {
+          assertAutonomyAssignment(key, ak, av, 1);
+        } catch (err) {
+          throw fail(1, `${AUTONOMY_REL}: ${err.message}`);
+        }
+      }
+      continue;
+    }
+    throw fail(1, `${AUTONOMY_REL}: unknown top-level key "${key}" (known: _README, ${KNOWN_SECTIONS()})`);
+  }
+  return config;
+};
+
+// ── policy IO (config errors → exit 1) ──────────────────────────────────────────────
+
+// Load + validate the policy from <cwd>/docs/ai/autonomy.json. Absent FILE → computed defaults (NOT an
+// error): { config: null, source: 'none' }. Malformed JSON / schema-invalid / unreadable → loud
+// `path: reason` (exit 1). lstat (NOT existsSync) so a DANGLING SYMLINK reads as present and its later
+// read failure surfaces loudly — never silently treated as absent (no-silent-failures Hard Constraint).
+export const loadAutonomy = (cwd, readFile = readFileSync, lstat = lstatSync) => {
+  const full = join(cwd, AUTONOMY_REL);
+  try {
+    lstat(full);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { config: null, source: 'none' };
+    throw fail(1, `${AUTONOMY_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let raw;
+  try {
+    raw = readFile(full, 'utf8');
+  } catch (err) {
+    throw fail(1, `${AUTONOMY_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw fail(1, `${AUTONOMY_REL}: malformed JSON (${err.message})`);
+  }
+  return { config: validateAutonomy(parsed), source: AUTONOMY_REL };
+};
+
+// ── the pure computed-defaults resolver ─────────────────────────────────────────────
+
+// resolveAutonomy(config) → the effective policy: every red-line resolved to its config value or its
+// Decision-4 default; every ACTIVITIES entry resolved to its config autonomy or `prompt`. The render +
+// any future read surface share THIS resolver, so a sparse policy always yields one full effective
+// policy (no key ever undefined). Pure; accepts null (absent file → all defaults).
+export const resolveAutonomy = (config) => {
+  const cfg = isJsonObject(config) ? config : {};
+  const rl = isJsonObject(cfg[REDLINES_SECTION]) ? cfg[REDLINES_SECTION] : {};
+  const redlines = {};
+  for (const k of REDLINE_KEYS) redlines[k] = rl[k] ?? REDLINE_DEFAULTS[k];
+  const activities = {};
+  for (const a of Object.keys(ACTIVITIES)) {
+    const entry = isJsonObject(cfg[a]) ? cfg[a] : {};
+    activities[a] = { [ACTIVITY_KEY]: entry[ACTIVITY_KEY] ?? DEFAULT_ACTIVITY_AUTONOMY };
+  }
+  return { redlines, activities };
+};
+
+// ── pure merge + canonical serialization ────────────────────────────────────────────
+
+// A pure deep-equal over the JSON-ish policy shape (plain objects + string values). Used only for the
+// "did anything actually change?" decision (no-op detection + seed-on-change), never for output.
+const deepEqual = (a, b) => {
+  if (a === b) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  return ak.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+};
+
+// applyAutonomyOps(current, ops, { seedReadme }) → the merged policy. PURE: deep-clones `current` (or
+// {}), applies each set/unset, preserves `_README` + every untouched section/key, drops a section that
+// an unset empties (sparse), then re-runs validateAutonomy (loud on invalid — defensive; the op parser
+// pre-validates). When (and ONLY when) the merge CHANGES the policy, `_README` is absent, and
+// `seedReadme` is supplied, the canonical note is seeded — so a no-op set never spuriously seeds it.
+export const applyAutonomyOps = (current, ops, { seedReadme = null } = {}) => {
+  const base = current == null ? {} : structuredClone(current);
+  const next = structuredClone(base);
+  for (const op of ops) {
+    if (op.kind === 'set') {
+      next[op.section] = { ...(next[op.section] ?? {}) };
+      next[op.section][op.key] = op.value;
+    } else if (next[op.section] && op.key in next[op.section]) {
+      const rest = { ...next[op.section] };
+      delete rest[op.key];
+      if (Object.keys(rest).length === 0) delete next[op.section];
+      else next[op.section] = rest;
+    }
+  }
+  validateAutonomy(next);
+  const changed = !deepEqual(next, base);
+  if (changed && seedReadme != null && next._README === undefined) next._README = seedReadme;
+  return next;
+};
+
+// serializeAutonomy(config) → strict JSON, 2-space, trailing newline, `_README` FIRST (explicitly, so
+// the onboarding note never sinks below the policy). This is the canonical on-disk form: a touched
+// write normalizes to it (content-preserving, NOT byte-preserving of arbitrary hand-formatting).
+export const serializeAutonomy = (config) => {
+  const ordered = {};
+  if (config._README !== undefined) ordered._README = config._README;
+  for (const [k, v] of Object.entries(config)) {
+    if (k !== '_README') ordered[k] = v;
+  }
+  return `${JSON.stringify(ordered, null, 2)}\n`;
+};
+
+// ── 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.
+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.';
+
+export const SEED_AUTONOMY = {
+  _README: AUTONOMY_README,
+  redlines: {
+    commit: 'ask', push: 'ask', publish: 'ask',
+    network: 'deny', credentials: 'deny', fs_outside_repo: 'deny',
+  },
+  'plan-authoring': { autonomy: 'sandbox' },
+  'plan-execution': { autonomy: 'sandbox' },
+};

package/tools/autonomy-write.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// autonomy-write.mjs — the ONLY filesystem WRITER for docs/ai/autonomy.json. It is imported by the
+// set-autonomy writer alone; no read-only module (autonomy-config.mjs, velocity-profile.mjs's read
+// path) imports it, so "a read-only surface can never reach a writer" is a STRUCTURAL invariant (an
+// import-split test pins it), not just an assertion. Splitting the writer out of the schema/read module
+// keeps the read surface fs-write-free — the orchestration-write.mjs precedent (AD-044).
+//
+// The hardened write flow (deployment gate → symlink STOPs → containment guard → exclusive-create tmp
+// + rename with a TOCTOU re-check → tmp cleanup; LAST-WRITER-WINS) lives in the shared atomic-write
+// core (tools/atomic-write.mjs, AD-042) and is consumed here with this module's own STOP identity, so
+// the public API + error contract are its own (this file's tests pin them).
+//
+// Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are unit-testable.
+
+import { AUTONOMY_REL, serializeAutonomy } from './autonomy-config.mjs';
+import { writeDocsAiFileAtomic } from './atomic-write.mjs';
+
+// A typed STOP — a deliberate refusal we surface (deployment gate / symlinked leaf), distinct from a
+// native fs error. `Object.assign(new Error(), { code })`, the codebase's typed-error idiom (no classes).
+export const AUTONOMY_WRITE_STOP = 'AUTONOMY_WRITE_STOP';
+const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'AutonomyWriteStop', code: AUTONOMY_WRITE_STOP });
+
+// writeAutonomy(cwd, config, deps) → { writtenPath } on success; THROWS a typed STOP (no deployment /
+// symlinked leaf) or a native fs error otherwise. The tmp is cleaned up on any failure after its
+// creation. config is serialized canonically (serializeAutonomy: 2-space, _README-first, trailing NL).
+export const writeAutonomy = (cwd, config, deps = {}) =>
+  writeDocsAiFileAtomic(cwd, AUTONOMY_REL, serializeAutonomy(config), deps, { stop, noun: 'a policy' });

package/tools/commands.mjs

@@ -154,6 +154,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Set the orchestration recipe for an activity from plain language — previews the change, then writes the config when you confirm.',
   },
+  {
+    key: 'set-autonomy',
+    invocation: invocationOf('set-autonomy'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Set the per-project autonomy policy from plain language — which actions always ask (commit/push/publish/network) and how autonomously each activity runs; previews the change, then writes the policy when you confirm.',
+  },
   {
     key: 'review-state',
     invocation: invocationOf('review-state'),
@@ -168,6 +175,13 @@ const CATALOG = [
     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.',
   },
+  {
+    key: 'review-ledger',
+    invocation: invocationOf('review-ledger'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Record each review round and read the computed crossover-stop for the plan-execution loop (converged / accepted-residual / triage-required); --check turns it into a gate exit code and forces a triage before over-running the review.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime