@sabaiway/agent-workflow-kit 2.1.0 → 3.1.0

package/references/scripts/migrate-gates.test.mjs

@@ -0,0 +1,284 @@
+// migrate-gates.test.mjs — spec for the consented legacy gates.json migration (strip-the-kit D8).
+// The migration is ATOMIC and COMPLETE: canonical legacy entries removed + the unit-tests cmd
+// extended with the lcov reporters + the coverage-check gate added LAST; customized entries are
+// NEVER auto-touched (loud report + recovery); preview writes NOTHING; apply is tmp+rename.
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  LEGACY_FORMS,
+  UNIT_TESTS_COVERAGE_FLAGS,
+  RETIRED_STORE_BASENAMES,
+  findRetiredStores,
+  buildMigrationPlan,
+  resultingGates,
+  formatPreview,
+  main,
+} from './migrate-gates.mjs';
+
+const KIT_TOOLS = mkdtempSync(join(tmpdir(), 'migrate-gates-kit-'));
+writeFileSync(join(KIT_TOOLS, 'coverage-check.mjs'), '// the installed checker the migration points at\n');
+
+const mkProject = (gates) => {
+  const root = mkdtempSync(join(tmpdir(), 'migrate-gates-'));
+  mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+  writeFileSync(join(root, 'docs', 'ai', 'gates.json'), `${JSON.stringify({ _README: 'mine', gates }, null, 2)}\n`);
+  return root;
+};
+const gatesOf = (root) => JSON.parse(readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8')).gates;
+const quiet = () => {
+  const out = [];
+  const err = [];
+  return { log: (l) => out.push(String(l)), error: (l) => err.push(String(l)), out, err };
+};
+
+const LEGACY_LEDGER = { id: 'review-ledger', title: 'L', cmd: 'node "/kit/tools/review-ledger.mjs" --check' };
+const LEGACY_FOLD = { id: 'fold-completeness', title: 'F', cmd: 'node /kit/tools/fold-completeness.mjs --check' };
+const UNIT = { id: 'unit-tests', title: 'U', cmd: 'node --test tools/*.test.mjs' };
+const CUSTOM = { id: 'my-ledger-wrap', title: 'C', cmd: 'node scripts/wrap.mjs && node /kit/tools/review-ledger.mjs --check' };
+
+describe('migrate-gates — the pure migration plan', () => {
+  it('matches BOTH documented legacy forms (quoted and bare paths) and removes them', () => {
+    for (const form of LEGACY_FORMS) assert.ok(form.re instanceof RegExp);
+    const { plan } = buildMigrationPlan([LEGACY_LEDGER, LEGACY_FOLD], KIT_TOOLS);
+    assert.deepEqual(plan.filter((r) => r.action === 'remove').map((r) => r.entry.id), ['review-ledger', 'fold-completeness']);
+  });
+
+  it('extends the canonical unit-tests cmd with the lcov reporters (flags inserted after `node --test`)', () => {
+    const { plan, unitTestsExtended } = buildMigrationPlan([UNIT], KIT_TOOLS);
+    assert.ok(unitTestsExtended);
+    const extended = plan.find((r) => r.action === 'extend').entry;
+    assert.equal(extended.cmd, `node --test ${UNIT_TESTS_COVERAGE_FLAGS} tools/*.test.mjs`);
+  });
+
+  it('an already-extended unit-tests cmd is left alone (idempotent)', () => {
+    const done = { id: 'unit-tests', title: 'U', cmd: `node --test ${UNIT_TESTS_COVERAGE_FLAGS} tools/*.test.mjs` };
+    const { plan } = buildMigrationPlan([done], KIT_TOOLS);
+    assert.equal(plan.find((r) => r.entry.id === 'unit-tests').action, 'keep');
+  });
+
+  it('adds the coverage-check gate LAST with the RESOLVED quoted path; never a second one', () => {
+    const { plan } = buildMigrationPlan([UNIT], KIT_TOOLS);
+    const result = resultingGates(plan);
+    const last = result[result.length - 1];
+    assert.equal(last.id, 'coverage-check');
+    assert.equal(last.cmd, `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check`);
+    const again = buildMigrationPlan(result, KIT_TOOLS);
+    assert.ok(!again.plan.some((r) => r.action === 'add'), 'a declaration already carrying the checker gains no duplicate');
+  });
+
+  it('a CUSTOMIZED dead-tool reference (compound form) is kept untouched and reported', () => {
+    const analysis = buildMigrationPlan([CUSTOM], KIT_TOOLS);
+    assert.equal(analysis.plan.find((r) => r.entry.id === 'my-ledger-wrap').action, 'keep');
+    assert.deepEqual(analysis.customized.map((g) => g.id), ['my-ledger-wrap']);
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /CUSTOMIZED \(untouched\): my-ledger-wrap/);
+    assert.match(preview, /do NOT install the commit guard/);
+  });
+});
+
+describe('migrate-gates — the canonical anchor + final-capability validation (round-1 folds)', () => {
+  it('a canonical checker NOT in the last position is MOVED last (never left mid-list)', () => {
+    const canonical = { id: 'coverage-check', title: 'CC', cmd: `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check` };
+    const { plan } = buildMigrationPlan([canonical, UNIT], KIT_TOOLS);
+    const result = resultingGates(plan);
+    assert.equal(result[result.length - 1].id, 'coverage-check', 'the canonical checker ends up LAST');
+    assert.ok(plan.some((r) => r.action === 'move' && r.entry.id === 'coverage-check'), 'the reorder is an explicit move action');
+    assert.ok(!plan.some((r) => r.action === 'add'), 'no duplicate checker is added');
+  });
+
+  it('a LOOKALIKE checker cmd is CUSTOMIZED (never counted canonical) and the canonical one is still added', () => {
+    const lookalike = { id: 'cov', title: 'C', cmd: 'node scripts/coverage-check.mjs --check' };
+    const analysis = buildMigrationPlan([lookalike, UNIT], KIT_TOOLS);
+    assert.ok(analysis.customized.some((g) => g.id === 'cov'), 'the lookalike is reported customized');
+    const result = resultingGates(analysis.plan);
+    assert.equal(result[result.length - 1].id, 'coverage-check', 'the REAL canonical checker is added last');
+  });
+
+  it('the result is judged final-capable ONLY with a canonical review-state present; missing → a LOUD warning with the candidate line, never "final-run-capable"', () => {
+    const analysis = buildMigrationPlan([UNIT], KIT_TOOLS);
+    assert.equal(analysis.finalCapable, false, 'no review-state → not final-capable');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /review-state/, 'the warning names the missing core check');
+    assert.match(preview, /"id": "review-state"|review-state\.mjs/, 'the paste-ready candidate is carried');
+    assert.doesNotMatch(preview, /already final-run-capable/);
+    const withRs = buildMigrationPlan(
+      [UNIT, { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'review-state.mjs')}" --check` }],
+      KIT_TOOLS,
+    );
+    assert.equal(withRs.finalCapable, true);
+  });
+
+  it('a NON-canonical unit-tests cmd (npm test / wrapper) is CUSTOMIZED with the full flag set as the recovery', () => {
+    const npmTest = { id: 'unit-tests', title: 'U', cmd: 'npm test' };
+    const analysis = buildMigrationPlan([npmTest], KIT_TOOLS);
+    assert.equal(analysis.plan.find((r) => r.entry.id === 'unit-tests').action, 'keep');
+    assert.ok(analysis.customized.some((g) => g.id === 'unit-tests'), 'a non-canonical suite cmd is customized');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /--experimental-test-coverage/, 'the recovery carries the full flag set');
+  });
+
+  it('a PARTIALLY-flagged unit-tests cmd is CUSTOMIZED (a lone coverage flag never reads as configured)', () => {
+    const partial = { id: 'unit-tests', title: 'U', cmd: 'node --test --experimental-test-coverage tools/*.test.mjs' };
+    const analysis = buildMigrationPlan([partial], KIT_TOOLS);
+    assert.equal(analysis.plan.find((r) => r.entry.id === 'unit-tests').action, 'keep');
+    assert.ok(analysis.customized.some((g) => g.id === 'unit-tests'), 'the half-wired cmd is customized, never silently left');
+  });
+
+  it('a kitTools path with DQ-unsafe characters is a loud STOP before any write', () => {
+    const root = mkProject([UNIT]);
+    const evil = mkdtempSync(join(tmpdir(), 'migrate-gates-$evil-'));
+    writeFileSync(join(evil, 'coverage-check.mjs'), '// lookalike\n');
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', evil, '--apply'], io), 1);
+    assert.match(io.err.join('\n'), /double-quot|shell metacharacter/i);
+    rmSync(evil, { recursive: true, force: true });
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('CUSTOMIZED warnings + the guard warning print even when apply has nothing else to do', () => {
+    const root = mkProject([CUSTOM]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 0);
+    const text = io.out.join('\n');
+    assert.match(text, /CUSTOMIZED \(untouched\): my-ledger-wrap/, 'the customized row survives the no-op path');
+    assert.match(text, /do NOT install the commit guard/i, 'the guard warning survives the no-op path');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a SYMLINKED docs (or docs/ai) PARENT is a STOP on preview AND apply (never written through)', () => {
+    const outside = mkdtempSync(join(tmpdir(), 'migrate-gates-target-'));
+    mkdirSync(join(outside, 'ai'), { recursive: true });
+    writeFileSync(join(outside, 'ai', 'gates.json'), `${JSON.stringify({ gates: [UNIT] })}\n`);
+    const root = mkdtempSync(join(tmpdir(), 'migrate-gates-symparent-'));
+    symlinkSync(outside, join(root, 'docs'));
+    for (const argv of [['--cwd', root, '--kit-tools', KIT_TOOLS], ['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply']]) {
+      const io = quiet();
+      assert.equal(main(argv, io), 1, `must STOP: ${argv.join(' ')}`);
+      assert.match(io.err.join('\n'), /symlink/i);
+    }
+    rmSync(root, { recursive: true, force: true });
+    rmSync(outside, { recursive: true, force: true });
+  });
+});
+
+describe('migrate-gates — preview writes NOTHING; apply is atomic and complete', () => {
+  it('the dry-run default leaves gates.json byte-identical and prints the plan + the apply hint', () => {
+    const root = mkProject([LEGACY_LEDGER, UNIT]);
+    const before = readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8');
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0);
+    assert.equal(readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8'), before, 'dry-run must write nothing');
+    const text = io.out.join('\n');
+    assert.match(text, /REMOVE review-ledger/);
+    assert.match(text, /EXTEND unit-tests/);
+    assert.match(text, /ADD coverage-check/);
+    assert.match(text, /apply exactly this migration: node "\/[^"]*migrate-gates\.mjs" --kit-tools/, 'the apply hint is a REAL runnable path (never a file: URL)');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('--apply lands the full migration: legacy gone, unit-tests extended, coverage-check LAST', () => {
+    const root = mkProject([UNIT, LEGACY_LEDGER, LEGACY_FOLD]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 0);
+    const gates = gatesOf(root);
+    assert.deepEqual(gates.map((g) => g.id), ['unit-tests', 'coverage-check']);
+    assert.match(gates[0].cmd, /--experimental-test-coverage/);
+    assert.equal(gates[gates.length - 1].id, 'coverage-check');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('an ALREADY-migrated declaration is a stated no-op on apply', () => {
+    const root = mkProject([UNIT, LEGACY_LEDGER]);
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], quiet()), 0);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 0);
+    assert.match(io.out.join('\n'), /nothing to migrate/);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a MISSING gates.json is a stated no-op; a MALFORMED one is a loud STOP (never written over)', () => {
+    const empty = mkdtempSync(join(tmpdir(), 'migrate-gates-none-'));
+    const io = quiet();
+    assert.equal(main(['--cwd', empty, '--kit-tools', KIT_TOOLS], io), 0);
+    assert.match(io.out.join('\n'), /nothing to migrate/);
+    rmSync(empty, { recursive: true, force: true });
+
+    const root = mkProject([]);
+    writeFileSync(join(root, 'docs', 'ai', 'gates.json'), '{ not json');
+    const io2 = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io2), 1);
+    assert.match(io2.err.join('\n'), /malformed JSON/);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a SYMLINKED gates.json is a STOP on preview AND apply', () => {
+    const root = mkdtempSync(join(tmpdir(), 'migrate-gates-link-'));
+    mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+    writeFileSync(join(root, 'real.json'), '{"gates":[]}\n');
+    symlinkSync(join(root, 'real.json'), join(root, 'docs', 'ai', 'gates.json'));
+    for (const argv of [['--cwd', root, '--kit-tools', KIT_TOOLS], ['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply']]) {
+      const io = quiet();
+      assert.equal(main(argv, io), 1);
+      assert.match(io.err.join('\n'), /symlink/);
+    }
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('retired git-dir stores: previewed as CLEAN rows (nothing deleted), unlinked on apply, ENOENT a no-op', () => {
+    const root = mkProject([LEGACY_LEDGER]);
+    const g = (...a) => spawnSync('git', a, { cwd: root, encoding: 'utf8' });
+    g('init', '-q');
+    for (const name of RETIRED_STORE_BASENAMES) writeFileSync(join(root, '.git', name), '{"dead":1}\n');
+    assert.equal(findRetiredStores(root).length, RETIRED_STORE_BASENAMES.length, 'all three retired basenames are found');
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0);
+    assert.match(io.out.join('\n'), /CLEAN .*agent-workflow-review-ledger\.v5-orphans\.jsonl/, 'the v5-orphans archive is previewed too');
+    assert.equal(findRetiredStores(root).length, RETIRED_STORE_BASENAMES.length, 'the dry-run deleted NOTHING');
+    const io2 = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io2), 0);
+    assert.deepEqual(findRetiredStores(root), [], 'apply unlinked every retired store');
+    assert.match(io2.out.join('\n'), /cleaned .*agent-workflow-fold-completeness\.jsonl/);
+    // A second apply: stores gone, declaration migrated — a stated no-op (ENOENT never errors).
+    const io3 = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io3), 0);
+    assert.match(io3.out.join('\n'), /nothing to migrate/);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('stores alone (an already-migrated declaration) still get cleaned on apply', () => {
+    const root = mkProject([UNIT]);
+    const g = (...a) => spawnSync('git', a, { cwd: root, encoding: 'utf8' });
+    g('init', '-q');
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], quiet()), 0); // migrate first
+    writeFileSync(join(root, '.git', RETIRED_STORE_BASENAMES[0]), '{"dead":1}\n');
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 0);
+    assert.match(io.out.join('\n'), /cleaned .*agent-workflow-review-ledger\.jsonl/);
+    assert.deepEqual(findRetiredStores(root), []);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('outside a git tree the store cleanup is a silent no-op (no crash, gates.json still migrates)', () => {
+    const root = mkProject([LEGACY_LEDGER, UNIT]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 0);
+    assert.deepEqual(gatesOf(root).map((g2) => g2.id), ['unit-tests', 'coverage-check']);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('--kit-tools is REQUIRED and must contain the checker (no runtime guessing)', () => {
+    const root = mkProject([UNIT]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root], io), 2);
+    assert.match(io.err.join('\n'), /--kit-tools/);
+    const io2 = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', root], io2), 1);
+    assert.match(io2.err.join('\n'), /coverage-check\.mjs/);
+    rmSync(root, { recursive: true, force: true });
+  });
+});

package/references/templates/agent_rules.md

@@ -76,7 +76,7 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
 - **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
-- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch into ONE invocation — the review-ledger triad rides one batched write, other stage writers combine via one launcher per stage; never one writer call at a time (each write is its own prompt).
+- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).
 
 ---
 
@@ -93,7 +93,7 @@ Split a complex task across sessions for **focus and review hygiene**, not becau
 ## 4. User Interaction
 
 1. **Don't rush to commit.** Prepare changes, run local quality checks, report progress with test outcomes.
-2. **Get explicit approval** before staging/committing or moving to the next phase.
+2. **Get explicit approval** before COMMITTING or moving to the next phase — staging is reversible loop-work (the final-run ordering stages first, reviews the staged tree, then asks ONCE at the commit; a separate staging ask is a useless approval).
 
 ---
 

package/tools/ack-write.mjs

@@ -16,7 +16,7 @@
 //   • atomic — exclusive-create *.tmp + rename (no partial-write state); last-writer-wins;
 //   • never commits.
 //
-// Dependency-free beyond the kit's own atomic-write core + the shared ack constants, Node >= 18. No
+// Dependency-free beyond the kit's own atomic-write core + the shared ack constants, Node >= 22. No
 // side effects on import (the isDirectRun idiom).
 
 import { lstatSync, readFileSync } from 'node:fs';

package/tools/atomic-write.mjs

@@ -3,7 +3,7 @@
 // by (containment ROOT, absolute target, body, stop identity) so every consumer runs the same guarded
 // flow with zero drift:
 //   • writeDocsAiFileAtomic  — a file under a project's docs/ai/ (deployment-gated to cwd):
-//       orchestration-write.mjs → docs/ai/orchestration.json; seed-gates.mjs → docs/ai/gates.json.
+//       orchestration-write.mjs → docs/ai/orchestration.json; gates-init.mjs → docs/ai/gates.json.
 //   • writeHostConfigFileAtomic — a file under a host config dir OUTSIDE any project tree
 //       (bridges 2.3.0, D6): ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf. The
 //       host dir is CREATED if absent (a host config SHOULD materialize), unlike the docs/ai gate
@@ -19,7 +19,7 @@
 //   - tmp cleaned up on any failure after its creation.
 //   - LAST-WRITER-WINS: local, single-user; no cross-process lock (documented, not silently assumed).
 //
-// Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are
+// Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*) so the guards are
 // unit-testable. NEVER imported by a read-only module (procedures.mjs — pinned by an import guard).
 
 import { lstatSync, writeFileSync, renameSync, rmSync, mkdirSync } from 'node:fs';

package/tools/autonomy-config.mjs

@@ -16,7 +16,7 @@
 //
 // 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.
+// Pure-where-possible (fs injectable), dependency-free, Node >= 22. No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';

package/tools/autonomy-doctor.mjs

@@ -35,7 +35,7 @@
 // a PATH shadow, never fixes it; (iii) the harness permission prompt shows the --apply tuple, not
 // the absolute-path command — bridged by the apply-time re-print of the exact resolved command.
 //
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { spawnSync } from 'node:child_process';
 import { closeSync, lstatSync, openSync } from 'node:fs';
@@ -254,7 +254,7 @@ const renderDiagnosis = ({ plan, probeResult, log }) => {
   }
 };
 
-// The untrusted degrade every lane runs FIRST (codex R1): while any sandbox binary resolves only
+// The untrusted degrade every lane runs FIRST: while any sandbox binary resolves only
 // outside the trusted dirs, no offer, no consent invitation, and no privileged path may proceed —
 // an install cannot make such a host verify-ready.
 const refuseUntrusted = ({ plan, log }) => {

package/tools/autonomy-write.mjs

@@ -10,7 +10,7 @@
 // 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.
+// Dependency-free, Node >= 22. 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';

package/tools/bridge-settings-read.mjs

@@ -6,7 +6,7 @@
 // lines, the manifest-as-source registry (the union of the bundled bridges' `settings` blocks), and
 // the effective value of each knob (env > file > built-in default). It NEVER writes.
 //
-// Dependency-free, Node >= 18. No side effects on import.
+// Dependency-free, Node >= 22. No side effects on import.
 
 import { readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';

package/tools/bridge-settings.mjs

@@ -21,7 +21,7 @@
 // bundle (cannot determine the allowlist). main(argv, ctx) → { code, stdout, stderr }; getenv / home /
 // bundleRoot / fs are injectable for host-independent tests.
 //
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { pathToFileURL } from 'node:url';
 import { settingValueValid } from './manifest/validate.mjs';

package/tools/changed-surface.mjs

@@ -1,20 +1,14 @@
 #!/usr/bin/env node
-// changed-surface.mjs — the NEUTRAL shared read-only core (BUGFREE-2 / AD-048, D4 + D8). One home
-// for the changed-surface computation that BOTH the fold-completeness runner (coverage domain) and
-// the review-ledger writer (the D4 diff-size cap) consume — one computation, so the cap and the
-// coverage gate can never drift (the probeVerdict single-home precedent, AD-047). The D8 telemetry
-// fold-ledger read path lives beside it: fold-completeness.mjs already imports review-ledger.mjs,
-// so the review-ledger telemetry must reach the fold ledger WITHOUT importing back the other
-// direction — it imports THIS module instead.
+// changed-surface.mjs — the NEUTRAL shared read-only core: ONE home for the changed-surface
+// computation the coverage checker consumes (the closed classification + new-side line numbering),
+// plus the shared fail-closed knob parser and the strict N/N probe-verdict algebra the
+// core-evidence red-proof observer reads.
 //
 // Import-graph invariant (pinned by import-split tests): this module imports NOTHING from the
-// family — node built-ins only. Everyone may import it; it imports no one:
-//   review-ledger.mjs → changed-surface.mjs ← fold-completeness.mjs ← fold-completeness-run.mjs
-//   review-ledger-write.mjs → changed-surface.mjs (the writer NEVER imports the runner — the
-//   sole-tree-toucher boundary, codex R2)
+// family — node built-ins only. Everyone may import it; it imports no one.
 //
 // Read-only: never writes, never commits. It DOES spawn read-only `git` queries (diff/ls-files/
-// rev-parse). Dependency-free, Node >= 18. No side effects on import.
+// rev-parse). Dependency-free. No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
@@ -43,7 +37,7 @@ export const classifyChangedPath = (rel) => {
 
 // Strip the quotes and decode escapes BYTE-wise (octal escapes are UTF-8 bytes) — an unparsed
 // quoted path compares unequal to its classifier/testId form and would silently escape the
-// coverage/cap surface (agy R5, AD-047).
+// coverage/cap surface (AD-047).
 const CQUOTE_SIMPLE = { n: 10, t: 9, r: 13, f: 12, v: 11, b: 8, a: 7, '"': 34, '\\': 92 };
 export const unquoteDiffPath = (p) => {
   if (!(p.length >= 2 && p.startsWith('"') && p.endsWith('"'))) return p;
@@ -53,7 +47,7 @@ export const unquoteDiffPath = (p) => {
     const c = inner[i];
     if (c !== '\\') {
       // Consume a full CODE POINT — 16-bit-unit iteration would split a surrogate pair (an
-      // unescaped non-BMP char, reachable under core.quotepath=false) into replacement bytes (agy R6).
+      // unescaped non-BMP char, reachable under core.quotepath=false) into replacement bytes.
       const ch = String.fromCodePoint(inner.codePointAt(i));
       for (const b of Buffer.from(ch, 'utf8')) bytes.push(b);
       i += ch.length - 1;
@@ -95,7 +89,7 @@ export const parseUnifiedDiff = (diffText) => {
     }
     if (inHeader && line.startsWith('--- ')) continue;
     if (inHeader && line.startsWith('+++ ')) {
-      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, '')); // TAB/CR are git artifacts, never filename bytes (agy R6)
+      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, '')); // TAB/CR are git artifacts, never filename bytes
       current = p === '/dev/null' ? null : p.startsWith('b/') ? p.slice(2) : p;
       inHeader = false;
       continue;
@@ -120,7 +114,7 @@ export const parseUnifiedDiff = (diffText) => {
 // ── the changed surface (git-driven; the ONE computation both consumers read) ─────────────────────
 
 // The one diff-invocation shape every surface pass uses. The a/ b/ prefixes are pinned EXPLICITLY
-// (agy R6): a user's global diff.noprefix=true would otherwise drop them and the parsers would eat
+// A user's global diff.noprefix=true would otherwise drop them and the parsers would eat
 // a real directory named "a" — user git config must never bend the parse.
 export const DIFF_FLAGS = ['--unified=0', '--no-color', '--no-ext-diff', '--no-renames', '--src-prefix=a/', '--dst-prefix=b/'];
 
@@ -129,11 +123,6 @@ const gitStdout = (args, cwd) => {
   const r = runGit(args, cwd);
   return r.error || r.status > 1 ? null : r.stdout;
 };
-const gitLine = (args, cwd) => {
-  const r = runGit(args, cwd);
-  if (r.error || r.status !== 0) return null;
-  return r.stdout.replace(/\r?\n$/, '');
-};
 // Both leaf guards are exported for the unit tests of exactly their fail-closed edges (the
 // hashFileBytes precedent, AD-047) — internal consumers stay this module's own passes.
 export const readFileSafe = (path) => {
@@ -145,7 +134,7 @@ export const readFileSafe = (path) => {
 };
 // A changed LEAF is read only if it is a REGULAR file. lstat (no-follow): a symlinked or non-regular
 // leaf must NEVER be read/followed — following it could read outside the work tree or HANG on a
-// FIFO/device (codex R2, AD-046). A non-regular leaf fails closed (routed to `unsupported`).
+// FIFO/device (AD-046). A non-regular leaf fails closed (routed to `unsupported`).
 export const isRegularLeaf = (abs) => {
   try {
     return lstatSync(abs).isFile();
@@ -161,13 +150,13 @@ export const isRegularLeaf = (abs) => {
 // pure deletions cost nothing, subtractive folds stay free); an untracked file is wholly new, so all
 // its lines are "changed". `unsupportedLines` is the D4 cap's view of the SAME pass: unsupported
 // SOURCE files carry their new-side lines too (excluding them would gift a large-TS-fold bypass,
-// codex R2 / BUGFREE-2 D4); an unreadable/non-regular leaf counts 0 lines but stays LISTED (the
+// BUGFREE-2 D4); an unreadable/non-regular leaf counts 0 lines but stays LISTED (the
 // coverage gate still fails closed on it). excluded-test and out-of-domain never carry lines.
 export const computeChangedSurface = (root) => {
   // Unborn branch (no HEAD yet): the plain diff alone misses files STAGED for the initial commit —
   // they sit in the index, so they are neither worktree-vs-index changes nor untracked. Merge the
   // --cached diff (index vs the empty tree) with the plain one; parseUnifiedDiff unions per-file
-  // lines across concatenated diffs (codex R1).
+  // lines across concatenated diffs.
   const trackedDiff = gitStdout(['diff', 'HEAD', ...DIFF_FLAGS], root)
     ?? `${gitStdout(['diff', '--cached', ...DIFF_FLAGS], root) ?? ''}\n${gitStdout(['diff', ...DIFF_FLAGS], root) ?? ''}`;
   const trackedLines = parseUnifiedDiff(trackedDiff);
@@ -215,22 +204,10 @@ export const computeChangedSurface = (root) => {
   return { assessable, unsupported: [...unsupportedLines.keys()].sort(), outOfDomain: outOfDomain.sort(), unsupportedLines };
 };
 
-// countCapLines(surface) → the D4 counted magnitude: new-side changed lines of assessable AND
-// unsupported SOURCE files (the two counted classes, pinned by named tests); excluded-test and
-// out-of-domain never count; pure deletions already cost nothing (new-side lines only). Stated
-// consequence, INTENTIONAL (agy R1): under --no-renames a rename of a large file costs its full
-// length — the single-home invariant outweighs a rename special case.
-export const countCapLines = ({ assessable, unsupportedLines }) => {
-  let counted = 0;
-  for (const lines of assessable.values()) counted += lines.length;
-  for (const lines of unsupportedLines.values()) counted += lines.length;
-  return counted;
-};
-
 // ── the shared fail-closed positive-integer knob parser (AD-047 precedent) ───────────────────────
 
 // Zero / negative / fractional / non-numeric values are refusals by name — the parseInt(...)||default
-// idiom would silently accept bad truthy values (codex R2, AD-046). Unset → the default; set → a
+// idiom would silently accept bad truthy values (AD-046). Unset → the default; set → a
 // positive integer, exactly. `makeError` lets each caller throw its OWN typed STOP.
 export const parsePositiveIntKnob = (env, name, fallback, makeError = (m) => new Error(m)) => {
   const raw = env[name];
@@ -241,8 +218,8 @@ export const parsePositiveIntKnob = (env, name, fallback, makeError = (m) => new
   return Number.parseInt(raw, 10);
 };
 
-// ── the D4 probe-verdict algebra (AD-047; the SINGLE home — moved here from fold-completeness.mjs,
-// which re-exports it, so the runner, the checker, AND the review-ledger telemetry read ONE algebra) ─
+// ── the probe-verdict algebra (AD-047; the SINGLE home — the core-evidence red-proof observer
+// consumes it) ────────────────────────────────────────────────────────────────────────────────────
 
 // probeVerdict(entry) → 'green' | 'red' | 'quarantine' | 'unresolvable'. RED/GREEN are strict N/N
 // verdicts; any timeout, mixed outcome, or partial resolution is QUARANTINE — it never converts and
@@ -254,41 +231,3 @@ export const probeVerdict = (t) => {
   if (t.timeouts > 0 || unresolved > 0 || (t.greens > 0 && t.reds > 0)) return 'quarantine';
   return t.greens === t.runs ? 'green' : 'red';
 };
-
-// ── the fold-result ledger locator + a tolerant row reader (the D8 telemetry read path) ──────────
-
-export const RESULTS_BASENAME = 'agent-workflow-fold-completeness.jsonl';
-
-// The result-ledger path: AW_FOLD_RESULTS overrides (mirrors AW_REVIEW_LEDGER); else <git dir>/basename.
-export const resolveResultsPath = (cwd, env = process.env) => {
-  if (env.AW_FOLD_RESULTS) return env.AW_FOLD_RESULTS;
-  const gitDir = gitLine(['rev-parse', '--absolute-git-dir'], cwd);
-  return gitDir == null ? null : join(gitDir, RESULTS_BASENAME);
-};
-
-// readJsonlRows(path) → { rows, badLines, readError? } — the TOLERANT parse the telemetry counts
-// ride on (counts only, no judgment — D8): a row is any parsed JSON object; a bad line is counted,
-// never dropped silently. Schema validation stays with each ledger's own reader — telemetry must
-// not fork a second validator (drift) nor import one across the cycle boundary.
-export const readJsonlRows = (path, readFile = readFileSync) => {
-  let raw;
-  try {
-    raw = readFile(path, 'utf8');
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return { rows: [], badLines: 0 };
-    return { rows: [], badLines: 0, readError: (err && err.code) || (err && err.message) || 'read failed' };
-  }
-  const rows = [];
-  let badLines = 0;
-  for (const line of raw.split('\n')) {
-    if (line.trim() === '') continue;
-    try {
-      const parsed = JSON.parse(line);
-      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) rows.push(parsed);
-      else badLines += 1;
-    } catch {
-      badLines += 1;
-    }
-  }
-  return { rows, badLines };
-};

package/tools/cheap-agents.mjs

@@ -23,7 +23,7 @@
 //
 // Exit codes: 0 done / dry-run (incl. preserved customizations — a user's file is a legitimate
 // state, not an error); 1 precondition STOP (stamp, symlink, missing bundle); 2 usage.
-// Dependency-free, Node >= 18. No side effects on import.
+// Dependency-free, Node >= 22. No side effects on import.
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
@@ -34,7 +34,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 export const AGENTS_DIR = '.claude/agents';
 export const CLAUDE_DIR = '.claude';
 export const WORKFLOW_STAMP = 'docs/ai/.workflow-version';
-export const EXPECTED_WORKFLOW_VERSION = '2.0.0';
+export const EXPECTED_WORKFLOW_VERSION = '3.0.0';
 export const BUNDLED_AGENTS_DIR = resolve(HERE, '..', 'references', 'agents');
 
 const EXIT_OK = 0;