@sabaiway/agent-workflow-kit 1.48.0 → 2.0.0

package/bridges/codex-cli-bridge/bin/codex-review.test.mjs

@@ -618,6 +618,32 @@ const extractArgCaseArms = (source) => {
 };
 const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
 
+// The source lines that really EXECUTE: a heredoc body (the --help text) and a comment both carry
+// names without carrying logic, so a bare name-grep over the whole source stays green after the
+// logic is deleted. Reuses the same heredoc discipline as extractArgCaseArms.
+const executableLines = (source) => {
+  const out = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    if (raw.trimStart().startsWith('#')) continue;
+    out.push(raw);
+  }
+  return out;
+};
+// An env var is really CONSULTED when an executable test compares it: [[ "${NAME:-}" == … ]].
+const consultsEnv = (source, name) =>
+  executableLines(source).some((l) => new RegExp(`\\[\\[[^\\]]*\\$\\{?${name}\\b[^\\]]*(==|!=)`).test(l));
+// The operand slots a rendered invocation form really carries: <angle> and [bracket] placeholders.
+// The optional `@` prefix rides WITH the slot (`@<facts-file>` is one operand, not a bare
+// `<facts-file>` behind a stray character) — the catalog declares the whole token a user types.
+const SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+
 describe('codex-review.sh — --help contract (manifest-pinned)', () => {
   it('--help and -h exit 0 pre-preflight (no codex, no git, no AGENTS.md)', () => {
     for (const arg of ['--help', '-h']) {
@@ -679,11 +705,114 @@ describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manife
   });
 });
 
+// ── mode catalog ⟷ wrapper reality (BRIDGE-MODES-CATALOG) ─────────────────────────
+// The kit validator owns the catalog's INTERNAL shape; these arms pin what only the wrapper source
+// can settle — the catalog documents THIS wrapper's real modes and real escape hatches, and every
+// contract invocation the wrapper honours is cataloged (adding a mode without one fails here).
+describe('codex-review.sh — mode catalog ⟷ wrapper reality (manifest-pinned)', () => {
+  const source = readFileSync(WRAPPER, 'utf8');
+  const arms = extractArgCaseArms(source);
+  const catalog = MANIFEST.modeCatalog ?? [];
+  const reviewEntries = catalog.filter((e) => e.role === 'review');
+  const reviewPrimaries = reviewEntries.filter((e) => e.kind === 'primary');
+
+  it('the catalog submodes ARE the wrapper\'s real parser mode arms (both directions)', () => {
+    const modes = splitArms(arms.get('"$mode"')).filter((a) => a !== '*');
+    assert.ok(reviewPrimaries.length > 0, 'the manifest must catalog its review modes');
+    setEq(reviewPrimaries.map((e) => e.submode), modes, 'catalog submodes ⟷ real parser mode arms');
+  });
+
+  it('every review entry composes BY REFERENCE and every reference resolves', () => {
+    for (const entry of reviewEntries) {
+      assert.ok(
+        Array.isArray(entry.invocationRefs) && entry.invocationRefs.length > 0,
+        `${entry.key}: a contract-backed entry references at least one contract descriptor`,
+      );
+      assert.ok(!Object.hasOwn(entry, 'descriptor'), `${entry.key}: a contract-backed entry never restates a literal descriptor`);
+      for (const ref of entry.invocationRefs) {
+        assert.equal(
+          typeof REVIEW_CONTRACT[ref.contractField]?.[ref.index], 'string',
+          `${entry.key}: ref ${ref.contractField}[${ref.index}] does not resolve into the manifest contract`,
+        );
+      }
+    }
+  });
+
+  it('every review contract invocation is claimed by exactly ONE catalog entry (no uncataloged mode)', () => {
+    const claims = reviewEntries.flatMap((e) => e.invocationRefs.map((r) => `${r.contractField}[${r.index}]`));
+    assert.equal(new Set(claims).size, claims.length, 'a contract invocation is claimed at most once');
+    const declared = [
+      ...REVIEW_CONTRACT.invocations.map((_, i) => `invocations[${i}]`),
+      ...(REVIEW_CONTRACT.continue ?? []).map((_, i) => `continue[${i}]`),
+    ];
+    setEq(new Set(claims), declared, 'catalog claims ⟷ declared contract invocations');
+  });
+
+  it('every env-hook the catalog aims at a review mode is a real EXECUTABLE guard, not a mention', () => {
+    const hooks = catalog.filter((e) => e.kind === 'env-hook' && e.parents.some((p) => reviewPrimaries.some((r) => r.key === p)));
+    assert.ok(hooks.length > 0, 'CODEX_PROBE must be cataloged as an env-hook over the review modes');
+    for (const hook of hooks) {
+      assert.ok(
+        consultsEnv(source, hook.key),
+        `env-hook ${hook.key} is named in the source but never TESTED in an executable condition — a help/comment mention would keep a name-grep green after the logic is deleted`,
+      );
+    }
+  });
+
+  it('the catalog operand slots set-EQUAL the slots its rendered forms really carry (both directions)', () => {
+    for (const entry of reviewEntries) {
+      const forms = entry.invocationRefs.map((r) => REVIEW_CONTRACT[r.contractField][r.index]);
+      // The DEDUPLICATED UNION over every resolved form: a plural-ref entry legitimately spreads its
+      // slots across forms, so per-form equality would false-fail a correct catalog.
+      const realSlots = new Set(forms.flatMap((f) => f.match(SLOT_RE) ?? []));
+      setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, `${entry.key}: catalog operands ⟷ the slots its forms really carry`);
+    }
+  });
+
+  it('an entry rendering a LITERAL descriptor is slot-checked too (env-hooks have no role to filter on)', () => {
+    // The contract-backed arm above filters by role — and an env-hook HAS no role, so its descriptor
+    // would never be slot-checked. That is exactly how a hardcoded dead path can reach the discovery
+    // surface looking ready-to-run. Every literal-descriptor kind is covered here: env-hooks and
+    // contract-free primaries.
+    const literalEntries = catalog.filter((e) => typeof e.descriptor === 'string');
+    assert.ok(literalEntries.length > 0, 'CODEX_PROBE must be cataloged with a literal descriptor');
+    for (const entry of literalEntries) {
+      const realSlots = new Set(entry.descriptor.match(SLOT_RE) ?? []);
+      setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, `${entry.key}: catalog operands ⟷ the slots its descriptor really carries`);
+    }
+  });
+
+  it('CODEX_PROBE really relaxes the guard on EVERY review parent the catalog claims (behavioural)', () => {
+    // The catalog CLAIMS these modes are modified by the hook; prove it per parent rather than
+    // trusting a source scan: an off-pin model is exit 2 normally, exit 0 under probe.
+    const hook = catalog.find((e) => e.key === 'CODEX_PROBE');
+    const drive = { 'review.plan': ['plan', 'plan.md'], 'review.code': ['code'] };
+    const reviewParents = hook.parents.filter((p) => reviewPrimaries.some((r) => r.key === p));
+    assert.ok(reviewParents.length > 0, 'CODEX_PROBE must claim at least one review parent');
+    for (const parent of reviewParents) {
+      assert.ok(drive[parent], `no behavioural drive for claimed parent "${parent}" — add one`);
+      // The exit code alone is weak evidence: pin the real DISPATCH too (capStdin is non-empty only
+      // when codex was actually invoked), so a run that dies early can never pass the probe-on branch.
+      const guarded = makeSandbox();
+      const off = run(guarded, { args: drive[parent], env: { CODEX_MODEL: 'not-the-pinned-model' } });
+      rmSync(guarded.root, { recursive: true, force: true });
+      assert.equal(off.status, 2, `${parent}: the quality guard must refuse an off-pin model without the hook`);
+      assert.equal(off.capStdin, '', `${parent}: the guard must refuse BEFORE spending a run`);
+
+      const probed = makeSandbox();
+      const on = run(probed, { args: drive[parent], env: { CODEX_MODEL: 'not-the-pinned-model', CODEX_PROBE: '1' } });
+      rmSync(probed.root, { recursive: true, force: true });
+      assert.equal(on.status, 0, `${parent}: CODEX_PROBE=1 must really relax the guard — the catalog claims it does`);
+      assert.notEqual(on.capStdin, '', `${parent}: CODEX_PROBE=1 must really reach codex, not merely exit 0`);
+    }
+  });
+});
+
 // ── review receipts (AD-038) ─────────────────────────────────────────────────────
-// The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; field VALUES with
+// The normative fixture: the AD-038 shape + the D3 self-declaring probe marker (field VALUES with
 // dynamic content are asserted by shape):
 const RECEIPT_FIXTURE = JSON.parse(
-  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.3.0","timestamp":"2026-07-03T12:00:00Z"}',
+  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.3.0","timestamp":"2026-07-03T12:00:00Z","probe":false}',
 );
 const RECEIPTS_REL = join('.git', 'agent-workflow-review-receipts.jsonl');
 const readReceipts = (repo) => {
@@ -715,6 +844,40 @@ describe('codex-review.sh — review receipts (AD-038)', () => {
     assert.match(receipt.timestamp, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
   });
 
+  // The probe marker (BRIDGE-MODES-CATALOG, D3): a CODEX_PROBE=1 review runs with the
+  // frontier-model/max-effort guard OFF, so its receipt must be distinguishable — the kit's
+  // review-state gate rejects a probe-marked receipt. EVERY receipt carries the marker (true or
+  // false): it self-declares, so the gate reads the fact rather than inferring it from a version
+  // string that bumps in a different release phase. Silence is not a declaration.
+  it('CODEX_PROBE=1 stamps probe:true — a throwaway probe can never attest a tree (D3)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_PROBE: '1', CODEX_FAKE_FINAL: 'Verdict: ship' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].probe, true, 'a probe-relaxed run marks its own receipt');
+    assert.deepEqual(Object.keys(receipts[0]), Object.keys(RECEIPT_FIXTURE), 'fixture key set + order');
+  });
+
+  // Every receipt SELF-DECLARES: the kit's gate reads the marker, never the wrapper version — so
+  // the marker must not depend on a version bump landing in the same release phase.
+  it('a normal review self-declares probe:false — the receipt states the fact, not a version', () => {
+    const sb = makeSandbox();
+    run(sb, { env: { CODEX_FAKE_FINAL: 'Verdict: ship' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(receipts[0].probe, false, 'silence is not a declaration — the gate rejects an unmarked receipt');
+  });
+
+  it('the marker tracks the RELAXED GUARD, not the model — a probe on an off-pinned model still marks', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_PROBE: '1', CODEX_MODEL: 'gpt-5-mini', CODEX_EFFORT: 'low', CODEX_FAKE_FINAL: 'Verdict: ship' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].probe, true, 'exactly the runs the guard let through unpinned are marked');
+  });
+
   it('the code-mode fingerprint tracks the uncommitted state (same tree → same hash; edit → different)', () => {
     const sb = makeSandbox();
     // Route the fake-codex capture files to /dev/null so the runs themselves leave the repo
@@ -1020,8 +1183,9 @@ describe('codex-review.sh — settings surface ⟷ manifest (D6, manifest-pinned
       assert.ok(arm, `no validation arm for ${s.key}`);
       if (s.kind === 'enum') for (const v of s.values) assert.ok(arm[1].includes(`"${v}"`), `${s.key}: enum value '${v}' not pinned`);
       if (s.kind === 'integer') {
-        assert.match(arm[1], new RegExp(`>= ${s.min}\\b`), `${s.key}: min ${s.min} not pinned`);
-        assert.match(arm[1], new RegExp(`<= ${s.max}\\b`), `${s.key}: max ${s.max} not pinned`);
+        // Issue-012 refactor: min/max are pinned as the aw_int_in_range helper's positional bounds
+        // (`aw_int_in_range "$v" <min> <max>`) — the overflow-safe range check replaced raw arithmetic.
+        assert.match(arm[1], new RegExp(`aw_int_in_range "\\$v" ${s.min} ${s.max}\\b`), `${s.key}: min/max ${s.min}/${s.max} not pinned as the aw_int_in_range bounds`);
       }
       if (s.kind === 'boolean') assert.ok(arm[1].includes('"0"') && arm[1].includes('"1"'), `${s.key}: boolean 0/1 not pinned`);
       if (s.kind === 'duration') {

package/bridges/codex-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "provides": ["execute", "review"],
   "roles": {
     "execute": {
@@ -42,10 +42,126 @@
         ],
         "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; 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"
+        "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); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); a write failure warns, never fails the review"
       }
     }
   },
+  "modeCatalog": [
+    {
+      "key": "exec",
+      "kind": "primary",
+      "role": "execute",
+      "purpose": "Execute a bounded plan in a sandboxed workspace and hand back a diff to review.",
+      "whenToUse": [
+        "a bounded sub-task whose acceptance criteria are already pinned",
+        "work you will review and commit yourself — the backend never commits"
+      ],
+      "whenNotTo": [
+        "work whose design is still open — decide it first, then delegate",
+        "anything you cannot check: the diff is advisory until you review it"
+      ],
+      "invocationRefs": [
+        { "contractField": "invocations", "index": 0 },
+        { "contractField": "invocations", "index": 1 }
+      ],
+      "operands": [
+        { "slot": "<plan-file|->", "required": true, "description": "the plan or instruction file, or - to read it from stdin" },
+        { "slot": "<extra codex flags...>", "required": false, "description": "extra codex flags, filtered by the guarded passthrough tiers" }
+      ],
+      "guardrails": [
+        { "value": "runs under codex's OWN OS sandbox (workspace-write)", "enforcement": "enforced", "condition": "it cannot nest inside another sandbox — the FS turns read-only; route it outside on the OBSERVED failure", "source": "capability.json roles.execute.contract.notes" },
+        { "value": "the guarded passthrough blocks model / sandbox / approval overrides", "enforcement": "enforced", "source": "bin/codex-exec.sh" },
+        { "value": "hard wall-clock cap CODEX_HARD_TIMEOUT (built-in default 3600s)", "enforcement": "enforced", "condition": "only while timeout(1)/gtimeout is on PATH — otherwise the wrapper warns and runs uncapped", "source": "capability.json settings.CODEX_HARD_TIMEOUT" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "exec.resume-last",
+      "kind": "continuation",
+      "role": "execute",
+      "purpose": "Continue the most recent codex-exec session with a follow-up instruction.",
+      "whenToUse": ["a small delta on work the same session already holds in context"],
+      "whenNotTo": ["a fresh task — a stale session carries stale assumptions"],
+      "invocationRefs": [{ "contractField": "continue", "index": 0 }],
+      "operands": [
+        { "slot": "<plan-file|->", "required": true, "description": "the follow-up instruction file, or - to read it from stdin" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "exec.resume",
+      "kind": "continuation",
+      "role": "execute",
+      "purpose": "Continue a NAMED codex-exec session by the session id it printed.",
+      "whenToUse": ["resuming a specific earlier session after other runs happened in between"],
+      "invocationRefs": [{ "contractField": "continue", "index": 1 }],
+      "operands": [
+        { "slot": "<session-id>", "required": true, "description": "the session id the original run printed on stderr" },
+        { "slot": "<plan-file|->", "required": true, "description": "the follow-up instruction file, or - to read it from stdin" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "review.plan",
+      "kind": "primary",
+      "role": "review",
+      "submode": "plan",
+      "purpose": "Critique an implementation plan before any of its code exists.",
+      "whenToUse": [
+        "a plan draft heading into its review council",
+        "checking whether a cold executor could really run the plan"
+      ],
+      "whenNotTo": ["a working-tree change set — that is review.code"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 0 }],
+      "operands": [
+        { "slot": "<plan-file>", "required": true, "description": "the plan file under review" }
+      ],
+      "guardrails": [
+        { "value": "read-only sandbox — codex cannot edit, create or delete a file", "enforcement": "enforced", "source": "bin/codex-review.sh" },
+        { "value": "runs on the pinned frontier model at max effort", "enforcement": "enforced", "condition": "unless CODEX_PROBE=1 relaxes the guard for a throwaway probe", "source": "bin/codex-review.sh" },
+        { "value": "a successful review appends one receipt line the review-state gate reads", "enforcement": "enforced", "condition": "a receipt write failure warns and the review still succeeds — the tree then reads un-receipted", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "review.code",
+      "kind": "primary",
+      "role": "review",
+      "submode": "code",
+      "purpose": "Review the uncommitted working-tree change set, precomputed in full for codex.",
+      "whenToUse": [
+        "a finished segment heading into its review round",
+        "a second opinion on real code before the commit ask"
+      ],
+      "whenNotTo": ["a clean tree — the wrapper exits before spending a run"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 1 }],
+      "operands": [
+        { "slot": "[extra focus...]", "required": false, "description": "extra focus words appended to the review directive" }
+      ],
+      "guardrails": [
+        { "value": "read-only sandbox — codex cannot edit, create or delete a file", "enforcement": "enforced", "source": "bin/codex-review.sh" },
+        { "value": "an oversized change set rides via a git-dir temp file, never truncated", "enforcement": "enforced", "source": "bin/codex-review.sh" },
+        { "value": "a successful review appends one receipt line the review-state gate reads", "enforcement": "enforced", "condition": "a receipt write failure warns and the review still succeeds — the tree then reads un-receipted", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "CODEX_PROBE",
+      "kind": "env-hook",
+      "parents": ["exec", "exec.resume-last", "exec.resume", "review.plan", "review.code"],
+      "purpose": "Relax the quality guards for a THROWAWAY probe run.",
+      "whenToUse": [
+        "a probe whose answer cannot depend on model or effort",
+        "checking that the wrapper plumbing works at all"
+      ],
+      "whenNotTo": ["any run whose output informs what ships — a probe never attests"],
+      "descriptor": "CODEX_PROBE=1 codex-review code",
+      "guardrails": [
+        { "value": "a probe review mints a probe-marked receipt the review-state gate rejects", "enforcement": "enforced", "source": "agent-workflow-kit tools/review-state.mjs" },
+        { "value": "on codex-exec it also relaxes the passthrough to the probeRelaxed tier", "enforcement": "enforced", "source": "bin/codex-exec.sh" }
+      ]
+    }
+  ],
   "settings": [
     {
       "key": "CODEX_SERVICE_TIER",

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.48.0",
+  "version": "2.0.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

@@ -13,7 +13,7 @@ The review-round **LEDGER** (DEBT-REVIEW-CAP / AD-045) — it turns the prose re
    - **`--telemetry`** → read-only COUNTS across ALL loops and BOTH ledgers (never combined with the other flags — a mixed-mode gate cmd would silently pass): rounds/segments per loop, finding-origin totals, classification distribution (incl. `refuted`), per-backend verdict + divergence-round counts, override usage by scope, gate-run counts (quality-green / red results by gate id), fold runs, observed-red receipts, quarantined probes. Counts only — which gates earn their keep stays the maintainer's judgment.
 
 2. **Writer** — `node ${CLAUDE_SKILL_DIR}/tools/review-ledger-write.mjs record|classify|override|batch --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 + AD-048, all per SEGMENT):** it REFUSES (typed STOP) to append a round WHILE `decideStop` on the segment's records is `triage-required` (an UNCLASSIFIED surviving blocking finding at/after the cap); refuses ANY round beyond the **hard-max ceiling of 3 within one segment** unconditionally (the counter reopens only at the next gated commit); refuses while a blocking finding of the segment's previous round **VANISHED unclassified** (present means present-as-blocking — a downgrade to minor does not survive; a pending `escalate` never clears; `refuted` is the honest phantom lane); refuses while the changed source surface exceeds the **diff-size cap** (`AW_REVIEW_DIFF_CAP`, default 400 new-side lines of assessable + unsupported SOURCE — tests and out-of-domain never count, pure deletions are free) without a recorded segment `size-cap` override; and refuses without a **quality-green gate-run** at the current fingerprint (`run-gates --record` — gates-before-review is computed, not remembered; a `--only` subset or a tree-changed run never satisfies; red PROCESS gates — the kit's own `--check` loop gates — never block). **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. **`--from-receipts`** (BUGFREE-3 / AD-049) DRAFTS the `backends[]` from those receipts instead of hand-composing them: each recipe-named backend's verdict comes from its fresh grounded code receipt and its counts are computed from the supplied `findings` (`origins` / `findings` stay explicit input); a recipe-named backend with no receipt is a LOUD stop — the draft never invents one (supply it explicitly as a degraded backend if the bridge really is down).
+   - `record` appends one round — `{ loop, round, origins, backends, findings }` (activity defaults to `plan-execution`). **The teeth (Decision 5 + AD-048, all per SEGMENT):** it REFUSES (typed STOP) to append a round WHILE `decideStop` on the segment's records is `triage-required` (an UNCLASSIFIED surviving blocking finding at/after the cap); refuses ANY round beyond the **hard-max ceiling of 3 within one segment** unconditionally (the counter reopens only at the next gated commit); refuses while a blocking finding of the segment's previous round **VANISHED unclassified** (present means present-as-blocking — a downgrade to minor does not survive; a pending `escalate` never clears; `refuted` is the honest phantom lane); refuses while the changed source surface exceeds the **diff-size cap** (`AW_REVIEW_DIFF_CAP`, default 400 new-side lines of assessable + unsupported SOURCE — tests and out-of-domain never count, pure deletions are free) without a recorded segment `size-cap` override; and refuses without a **quality-green gate-run** at the current fingerprint (`run-gates --record` — gates-before-review is computed, not remembered; a `--only` subset or a tree-changed run never satisfies; red PROCESS gates — the kit's own `--check` loop gates — never block). **Integrity binding (Decision 7):** each NON-degraded backend needs an **attesting** code receipt for the current tree — a round cannot be recorded for a tree no bridge really reviewed. *Attesting* is the SHARED predicate (`review-ledger-core`) that `review-state` and the round cross-check read too, so the gates can never disagree about what counts: a fresh `code` receipt at the current fingerprint that is **grounded** AND carries an explicit **`probe:false`**. A `probe:true` receipt never attests (a probe review runs with the quality guards off), and a **malformed or ABSENT** marker is rejected fail-closed — silence is not a declaration, so a receipt from a pre-marker bridge no longer counts (refresh it: `npx @sabaiway/agent-workflow-kit@latest init`). Each exclusion states its own reason, because the recoveries differ. **`--from-receipts`** (BUGFREE-3 / AD-049) DRAFTS the `backends[]` from those receipts instead of hand-composing them: each recipe-named backend's verdict comes from its fresh grounded code receipt and its counts are computed from the supplied `findings` (`origins` / `findings` stay explicit input); a recipe-named backend with no receipt is a LOUD stop — the draft never invents one (supply it explicitly as a degraded backend if the bridge really is down).
    - `classify` appends one triage — each surviving blocking finding of a SEGMENT round classified `fixable-bug` / `inherent-layer-residual` / `escalate` / **`refuted`** (v4 — the honest lane for a phantom finding, refuted against code: a MANDATORY non-empty `note` cites the grounds; never silently dropped, never folded). **A `fixable-bug` REQUIRES a `testId`** (M2/AD-046, schema v2) — the red→green test that pins the fold, formatted `<test-file>#<test-name-pattern>` (a `#` separator, both halves non-empty; no file-suffix rule); `inherent-layer-residual` / `escalate` may omit it. The writer validates the FORMAT only. **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).
    - `override` appends one override record (schema v3, BUGFREE-1/AD-047) — the LOUD, durable waiver the **fold-completeness** gate consumes, `{ loop, round, scope, reason }` plus the per-scope payload (EXACT — a stray key is refused): scope **`oracle-change`** → `files[]`, the repo-relative pre-existing test files whose tamper flag it lifts (a fix diff that deliberately rewrote test expectations); scope **`red-proof`** → `testId`, the ONE bound test whose observed-red receipt + custody it waives (a red genuinely unestablishable pre-fold, or a custody file legitimately edited post-fix); scope **`size-cap`** (v4) → `sanctionedLines`, the EXACT changed-surface magnitude the waiver sanctions — **segment-scoped** (it dies at the next commit; a grown surface needs a fresh recorded sanction). Teeth: schema validation, fail-closed ledger read, round-sequence integrity, and the loop must be the SINGLE in-flight plan. QUARANTINE (a flaky/timed-out probe) has NO override lane. Overrides never enter `decideStop` — the two v3 scopes are fold-completeness inputs; `size-cap` is a writer-tooth input.
    - **`gate-run` records (v4, kind `gate-run`)** are minted by `run-gates --record` through the writer's `recordGateRun` API (the runner never opens the ledger itself) — the D5 green-baseline receipt: the FULL declaration + exactly what ran + the tree fingerprint BEFORE and AFTER the run, segment-framed with NO round number, minted only inside the single in-flight loop. A red run records honestly (telemetry fuel); **quality-green** (every declared NON-process gate green, tree unchanged under the run) is judged at read time. Revert-first beyond this is not mechanically observable at this layer — it ships as protocol + telemetry visibility (consecutive red gate-runs), stated plainly.

package/references/modes/review-state.md

@@ -4,8 +4,8 @@ Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shippe
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
-1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, per-backend receipt state (current / stale / ungrounded / missing) with verdict + grounding + timestamp.
-2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a solo-resolved recipe (configured, or degraded there — no ready reviewer), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend receipted **current + grounded** — **or degraded-exempt**: the current segment's latest **review-ledger** round records that backend `degraded:true` at the current tree fingerprint, with ≥1 non-degraded recipe-named backend present + grounded and the ledger reading clean (AD-050; a corrupt ledger DENIES the exemption fail-closed but never fails an otherwise-satisfied tree — the tool header is the single home). Exit 1 when a backend is missing, **stale** (ANY edit after its review moves the fingerprint), or grounded:false under reviewed/council, and is not degraded-exempt. **Presence, not unanimity:** verdict adjudication (ship/revise, the divergence crossover) stays orchestrator judgment — the gate only proves the configured backends really reviewed THIS tree (a recorded degrade counts as "reviewed", never as "converged" — that stays `review-ledger`'s job). Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green.
+1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, per-backend receipt state (current / stale / ungrounded / probe / rejected / missing) with verdict + grounding + timestamp.
+2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a solo-resolved recipe (configured, or degraded there — no ready reviewer), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend receipted **current + grounded** — **or degraded-exempt**: the current segment's latest **review-ledger** round records that backend `degraded:true` at the current tree fingerprint, with ≥1 non-degraded recipe-named backend present + grounded and the ledger reading clean (AD-050; a corrupt ledger DENIES the exemption fail-closed but never fails an otherwise-satisfied tree — the tool header is the single home). Exit 1 when a backend is missing, **stale** (ANY edit after its review moves the fingerprint), or grounded:false under reviewed/council, and is not degraded-exempt. **Presence, not unanimity:** verdict adjudication (ship/revise, the divergence crossover) stays orchestrator judgment — the gate only proves the configured backends really reviewed THIS tree (a recorded degrade counts as "reviewed", never as "converged" — that stays `review-ledger`'s job). Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — a backend whose only current receipts are probes fails with its own stated reason, distinct from stale. The filter is **per receipt**, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a marker-aware wrapper writes `probe` on **every** successful review — `true` or `false` — so the receipt states the fact itself, and a **malformed** *or* **absent** marker is rejected **fail-closed** and stated in the check line, never silently dropped. This is deliberately **not** keyed on the wrapper version: the version bumps in a different release phase than the marker lands, so a version floor would reject the very receipts the current wrappers write — and it could only ever proxy a fact the receipt already carries. Accepted cost: a pre-marker receipt stops satisfying — re-run the review with a marker-aware bridge. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
 3. **Wire it as a gate by hand OR via the explicit-consent seeder — never without consent (AD-021/AD-042).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated seeder (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`, consent-seed section) offers exactly this entry — path resolved and quoted — ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces); it writes nothing without your explicit yes. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate.
 4. **`--await [--timeout <s>]`** (BUGFREE-3 / AD-049) → BLOCK until every recipe-named backend is SATISFIED for the current tree (i.e. until `--check` would PASS), or the bounded timeout elapses (a loud exit 1; default 900s). Run it after dispatching the review bridges to WAIT for their receipts to land instead of hand-polling a pid: the durable completion signal is the **receipt**, never a process event (a harness "completed" notification fires early; a bridge's output late-flushes). It waits until each backend has a fresh grounded receipt **OR is degraded-exempt**: once a current-tree degrade is recorded in the review-ledger, `--await` stops waiting for that backend and returns READY (AD-050 — it inherits the `--check` exemption via the shared decision), so you no longer hand-`--await` around a known degrade. Still read-only (it only re-reads state, now the ledger too); solo / no-plan / clean-tree resolve instantly.
 

package/references/modes/setup.md

@@ -11,8 +11,13 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs [<backend>] [--bindir <pa
   runs as its fourth stamp-independent reconcile): refresh every bridge `setup` **already placed**
   from the kit's bundled copies + re-link its wrappers; an absent bridge is a stated skip (**never**
   placed), a placed bridge newer than the bundle is a stated skip naming the kit update (**never**
-  downgraded), and every outcome line is composed by the tool — paste verbatim. Does not combine
-  with `--dry-run`.
+  downgraded), and every outcome line is composed by the tool — paste verbatim. When the skills dir
+  is **read-only this session** and the placed bridge is already at the bundled version, the
+  equal-version re-sync it would run cannot write: that outcome is `skipped-readonly` — a **stated
+  skip** (exit 0, not a failure) naming the current version, the skipped/incomplete re-sync, and the
+  read-only cause; it never claims a re-sync ran, and any local drift persists until a writable rerun.
+  (A version-**behind** refresh blocked by the same read-only dir stays a loud `could not refresh`,
+  its recovery pointing at a writable rerun.) Does not combine with `--dry-run`.
 - `--help`, `-h` — usage.
 
 For each backend it:

package/references/modes/upgrade.md

@@ -31,14 +31,14 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    **Placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
    `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` and **paste its per-bridge
    output lines verbatim** — every outcome line is composed by the tool (*refreshed* / *already
-   current* / *skipped — not placed* / *could not refresh* + its recovery); you compose nothing
-   factual. It is **refresh-only**: it refreshes a bridge **`setup` already placed** from this kit's
-   bundled copies and re-links its wrappers; an **absent** bridge is a stated skip, **never a first
-   placement** (placement stays the opt-in `${CLAUDE_SKILL_DIR}/references/modes/setup.md` — AD-009/AD-011 honesty intact), and a
-   placed bridge **newer** than the bundled copy is a stated skip naming the kit update (**never a
-   downgrade**). Like the other stamp-independent reconciles it runs on **every** upgrade —
-   including an equal-head one — with no lineage-head bump. A *could not refresh* line is
-   non-fatal: relay it plainly with its recovery and continue the upgrade.
+   current* / *skipped — not placed* / `skipped-readonly` / *could not refresh* + its recovery). It
+   is **refresh-only**: it refreshes a bridge **`setup` already placed** from this kit's bundled copies
+   and re-links its wrappers; an **absent** bridge is a stated skip, **never a first placement**
+   (placement stays the opt-in `${CLAUDE_SKILL_DIR}/references/modes/setup.md` — AD-009/AD-011 honesty intact), a placed bridge
+   **newer** than the bundle is a stated skip naming the kit update (**never a downgrade**), and
+   `skipped-readonly` is an equal-version re-sync a **read-only** skills dir blocked this session (a
+   stated skip, exit 0 — not a failure). Runs on **every** upgrade (equal-head too), no lineage-head
+   bump; a *could not refresh* line is non-fatal — relay it plainly with its recovery.
 
    **Agent-rules lens refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.**
    Run `node ${CLAUDE_SKILL_DIR}/tools/lens-region.mjs reconcile <project>/docs/ai/agent_rules.md`
@@ -56,7 +56,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    **NEVER writes** it (the file lives outside every kit tree — D2), so an unknown/retired key is
    flagged + preserved, never edited. Runs on **every** upgrade; exit 0 covers every outcome.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the stamp-independent reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology, orchestration-recipes and autonomy-policy) whether it was *added*, was *already present* (nothing changed), or was *skipped* (the soft-skip from step 3, with its reason — over the line limit / engine too old / the autonomy pointer's anchor absent); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/verification-profile.json` profile was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/autonomy.json` declaration was *seeded* (the sparse defaults-equivalent note) or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/`, found it *already present*, or found an *old ADR layout — migration instructed*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); the **bridge-settings reconcile** outcome (paste the tool's line verbatim); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
+   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology, orchestration-recipes and autonomy-policy) whether it was *added*, was *already present* (nothing changed), or was *skipped* (the soft-skip from step 3, with its reason — over the line limit / engine too old / the autonomy pointer's anchor absent); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/verification-profile.json` profile was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/autonomy.json` declaration was *seeded* (the sparse defaults-equivalent note) or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/`, found it *already present*, or found an *old ADR layout — migration instructed*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / `skipped-readonly` / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); the **bridge-settings reconcile** outcome (paste the tool's line verbatim); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
    - **Render the mandatory Recommendations section — on this exit too, BEFORE the footer.** Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language: every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; show the raw tool block on request. The section is present-even-when-empty (with everything optimal the body is exactly `no recommendations — flow optimal.`) and VERDICT-FIRST — the composed verdict line renders from the frozen templates `{K} item(s) need attention` / `nothing is broken` / `{N} optional recommendation(s), apply any you want` / `optimality NOT attested — {M} probe check(s) skipped`. Then OFFER the consent-gated applies: the user picks items in plain language; surface each picked item's posture note, get the explicit confirm, then run EXACTLY the rendered one-liners (a HAND-APPLY item is never run by you) — the full lane in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. Pinned order on this exit: Recommendations block → optional applies → report footer → the commit ask (the advisor/apply lane never lands after the commit ask).
    - **Live host/session facts are tool-composed only.** Any claim this report makes about the current host or session state — prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts — must trace to **live tool output** from **this session** (the lines you just composed, or a probe you ran this run); a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection. Full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`.

package/tools/detect-backends.mjs

@@ -91,7 +91,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; 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',
+        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); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); a write failure warns, never fails the review',
       },
     },
     bin: 'codex',
@@ -124,7 +124,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; 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",
+        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); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); a write failure warns, never fails the review",
         notes: [
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
         ],

package/tools/doc-parity.mjs

@@ -36,6 +36,7 @@ import {
   VERDICT_SKIPS_TEMPLATE,
   ACKS_FILE,
 } from './recommendations.mjs';
+import { SKIPPED_READONLY } from './setup-backends.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -45,6 +46,7 @@ const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
 const UPGRADE_DOC = 'references/modes/upgrade.md';
 const VELOCITY_DOC = 'references/modes/velocity.md';
+const SETUP_DOC = 'references/modes/setup.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 });
@@ -99,6 +101,11 @@ export const BINDINGS = Object.freeze([
   // (the incident's "mode-doc apply text stays in lockstep" acceptance as a mechanism, not prose).
   // Bound in BOTH docs that name the path (recommendations.md + velocity.md).
   valueBinding('acks-file', ACKS_FILE, ACKS_FILE, [RECOMMENDATIONS_DOC, VELOCITY_DOC]),
+  // The refresh read-only degrade outcome (REFRESH-EROFS-HONESTY / AD-056): the new skipped-readonly
+  // token must render in BOTH mode contracts that enumerate the placed-bridge refresh outcomes
+  // (setup.md owns --refresh-placed; upgrade.md pastes its lines) — a reworded doc dropping the
+  // outcome fails this pin plus the gate. The token tracks the exported SETUP constant.
+  valueBinding('refresh-skipped-readonly', SKIPPED_READONLY, SKIPPED_READONLY, [SETUP_DOC, UPGRADE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────

package/tools/fs-safe.mjs

@@ -17,7 +17,7 @@
 
 import {
   lstatSync, existsSync, mkdirSync, readdirSync, copyFileSync, readlinkSync, symlinkSync,
-  rmSync, unlinkSync,
+  rmSync, unlinkSync, readFileSync,
 } from 'node:fs';
 import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 
@@ -68,6 +68,27 @@ export const assertContainedRealPath = (root, dest, deps = {}) => {
   rel.split(sep).filter(Boolean).reduce(walk, root);
 };
 
+// Read-only write-boundary tagging (REFRESH-EROFS-HONESTY / AD-056). A DESTINATION-side write failure
+// of the read-only class is TAGGED (err.readonlyWriteBoundary) so the refresh-only driver can classify
+// an equal-version repair-on-rerun that cannot write as a STATED skip — never a false red. The tag is
+// applied ONLY around the three write primitives, so a READ-side failure (bundle read / dir listing)
+// is never absorbed: the degrade classifies at the write boundary, not by a broad err.code sniff over
+// the whole copy. EROFS is destination-side by nature; mkdir/symlink write only the dest; an
+// EACCES/EPERM at copyFile (which also READS the source) is destination-provable ONLY when the source
+// is readable — else it is a source-side read failure that must stay loud.
+const READONLY_WRITE_ERRNOS = new Set(['EROFS', 'EACCES', 'EPERM']);
+export const isReadonlyWriteBoundary = (err) => Boolean(err && err.readonlyWriteBoundary);
+const throwTaggedReadonly = (err, primitive, src, readFile) => {
+  if (err && READONLY_WRITE_ERRNOS.has(err.code)) {
+    let destinationSide = err.code === 'EROFS' || primitive !== 'copyFile';
+    if (!destinationSide) {
+      try { readFile(src); destinationSide = true; } catch { destinationSide = false; }
+    }
+    if (destinationSide) err.readonlyWriteBoundary = true;
+  }
+  throw err;
+};
+
 // Recursive refresh copy. Guards every dest via assertContainedRealPath first, then:
 //   symlink src   → additive: skip if dest exists, else mirror the link target.
 //   directory src → mkdir -p dest, recurse.
@@ -80,20 +101,22 @@ export const copyTreeRefresh = (src, dest, root, deps = {}) => {
   const copyFile = deps.copyFile ?? copyFileSync;
   const readlink = deps.readlink ?? readlinkSync;
   const symlink = deps.symlink ?? symlinkSync;
+  const readFile = deps.readFile ?? readFileSync;
 
   assertContainedRealPath(root, dest, deps);
   const stat = lstat(src);
   if (stat.isSymbolicLink()) {
     if (exists(dest)) return;
-    symlink(readlink(src), dest);
+    const target = readlink(src); // read-side (a readlink failure is never tagged as a write boundary)
+    try { symlink(target, dest); } catch (err) { throwTaggedReadonly(err, 'symlink', src, readFile); }
   } else if (stat.isDirectory()) {
-    mkdir(dest);
+    try { mkdir(dest); } catch (err) { throwTaggedReadonly(err, 'mkdir', src, readFile); }
     for (const entry of readdir(src)) {
       copyTreeRefresh(join(src, entry), join(dest, entry), root, deps);
     }
   } else {
-    mkdir(dirname(dest));
-    copyFile(src, dest);
+    try { mkdir(dirname(dest)); } catch (err) { throwTaggedReadonly(err, 'mkdir', src, readFile); }
+    try { copyFile(src, dest); } catch (err) { throwTaggedReadonly(err, 'copyFile', src, readFile); }
   }
 };