@sabaiway/agent-workflow-kit 14.4.0 → 14.4.1

package/CHANGELOG.md

@@ -4,6 +4,25 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 14.4.1 — `review-state.mjs` becomes a facade over five tested leaves; nothing the tool decides, prints or records changes (AD-149)
+
+**The review-receipt checker is now five small modules behind its old entry point.** `tools/review-state.mjs` was one
+918-line file. 14.4.1 moves its bodies into five library modules and keeps a 218-line facade that parses the command
+line, composes them and keeps its 28 exported names, so no import site outside the leaf suites moves. Exit codes, reasons, the `--json`
+output and the tool header are the same as in 14.4.0. Story S1 of the epic `REVIEW-STATE-AND-CORE-EVIDENCE-ARE-MONOLITHS`;
+contract `docs/ai/specs/kit/review-state.md` (revision 1).
+
+- **The leaves.** `review-state-judge.mjs` (receipt status, the degrade escape, the held-session arm, the check
+  decision), `review-state-build.mjs` (the read-only git queries and the state build; the only one that imports
+  `node:child_process`), `review-state-flow.mjs` (plan-adoption coverage and the armed-flow arms), `review-state-render.mjs` (the
+  human report and the mask advisory line) and `review-state-await.mjs` (the `--await` timeout grammar and poll loop).
+  No leaf imports the facade or runs as a script; each is under the 400-line cap, and the facade's size record is gone.
+- **Tests.** Nine unit cases move from `review-state.test.mjs` (116 stay) into four new leaf suites, which add five
+  written cases; `review-state-await.test.mjs` imports its leaf; `review-state-harness.test.mjs` holds the shared
+  fixtures. `test/review-state-layout.test.mjs` (new) pins each exported name to its home module, the header's digest,
+  the import directions and the `--json` key order. `test/package-content.test.mjs` names the five leaves and pins 318
+  packed files.
+
 ## 14.4.0 — a delegated task engages the held session: `review-state --check` reads a configured `task.execute`, the fold lane follows a resolved one, and `task-brief check` admits a lone suite (AD-148)
 
 **A task set to `delegated` is now gated and advised on its own.** In 14.3.0 the held-session gate and the fold lane

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '14.4.0'
+  version: '14.4.1'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.4.0",
+  "version": "14.4.1",
   "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/tools/review-state-await.mjs

@@ -0,0 +1,77 @@
+// review-state-await.mjs — the --timeout grammar and the poll loop.
+
+import { detectBackends } from './detect-backends.mjs';
+import { fail } from './orchestration-config.mjs';
+import { decideCheck } from './review-state-judge.mjs';
+import { buildState } from './review-state-build.mjs';
+
+// --await (BUGFREE-3 / AD-049, item (d)) bounds + poll cadence. The default timeout is generous —
+// a real grounded bridge review can take minutes — and every value is overridable (--timeout / the
+// injectable clock) so hermetic tests never spend wall-clock.
+export const DEFAULT_AWAIT_TIMEOUT_S = 900;
+export const AWAIT_POLL_MS = 5000;
+
+// ── --await: block until the configured review obligations are SATISFIED ───────────────
+// It waits until `--check` would pass: under `reviewed`, a ship-class attestation from any
+// review-capable backend; under `council`, every configured backend ship-class OR carrying a
+// current-tree degrade RECORD in the core-evidence store (never all backends) — once such a
+// record lands, --await stops waiting for that backend and returns READY (before, it waited
+// forever for a receipt that never comes). It inherits everything for FREE — it polls the SAME
+// decideCheck(buildState()) `--check` computes. The completion signal is the RECEIPT/RECORD
+// (i.e. `--check` would PASS), NEVER a process event — a harness "completed" notification fires
+// early and a bridge's output late-flushes, so polling state is the durable mechanization of
+// receipts-not-pgrep. Stays read-only (it only re-reads state — now the evidence store too, a
+// few KB per tick); the clock is injectable (ctx.now / ctx.sleep / ctx.pollMs) so hermetic tests
+// never spend wall-clock.
+
+const AWAIT_ALLOWED_ARGS = new Set(['--await', '--timeout']);
+
+const parseAwaitTimeoutS = (argv) => {
+  const i = argv.indexOf('--timeout');
+  if (i === -1) return DEFAULT_AWAIT_TIMEOUT_S;
+  const raw = argv[i + 1];
+  if (!raw || !/^\d+$/.test(raw) || Number(raw) < 1) throw fail(2, '--timeout requires a positive integer number of seconds');
+  return Number(raw);
+};
+
+export const mainAwait = async (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  const detect = ctx.detect ?? detectBackends;
+  const now = ctx.now ?? (() => Date.now());
+  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const pollMs = ctx.pollMs ?? AWAIT_POLL_MS;
+  const build = ctx.buildState ?? buildState;
+  try {
+    for (let i = 0; i < argv.length; i += 1) {
+      const a = argv[i];
+      if (a === '--timeout') { i += 1; continue; } // its value is consumed by parseAwaitTimeoutS
+      if (!AWAIT_ALLOWED_ARGS.has(a)) throw fail(2, `--await accepts only --timeout <s> (got ${a})`);
+    }
+    const timeoutS = parseAwaitTimeoutS(argv);
+    const timeoutMs = timeoutS * 1000;
+    const start = now();
+    // Poll the SAME normative decision --check computes: ready == `--check` would pass (solo / no
+    // plan / a clean tree / not-a-git-tree all resolve instantly — nothing to await). Re-read state
+    // every poll so a landed receipt (or a tree edit that re-staled one) is seen fresh. The DEADLINE
+    // is checked BEFORE readiness (codex council R2): once elapsed reaches the timeout the await is
+    // over, so a receipt that only lands AT/after the deadline never flips it to READY; and each
+    // sleep is BOUNDED to the remaining time so a full poll interval can never overshoot the timeout.
+    let lastReason = 'no poll completed before the deadline';
+    for (;;) {
+      const elapsed = now() - start;
+      if (elapsed >= timeoutMs) return { code: 1, stdout: '', stderr: `review-state --await: TIMEOUT after ${timeoutS}s — ${lastReason}` };
+      const check = decideCheck(build({ cwd, env, detect }));
+      lastReason = check.reason;
+      if (check.code === 0) return { code: 0, stdout: `review-state --await: READY — ${check.reason}`, stderr: '' };
+      if (check.heldSession === true) return { code: 1, stdout: '', stderr: `review-state --await: HELD SESSION — ${check.reason}` };
+      // Decision 4 (#50): an AUTHORITATIVE veto ends the wait loudly BEFORE the deadline — the
+      // dispatched review answered with a landed negative; classifying that as a timeout was the
+      // misclassification this amendment closes. Only a fresh review can move it, never waiting.
+      if (check.veto === true) return { code: 1, stdout: '', stderr: `review-state --await: VETO — ${check.reason}` };
+      await sleep(Math.min(pollMs, timeoutMs - elapsed));
+    }
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `review-state: ${err.message}` };
+  }
+};

package/tools/review-state-build.mjs

@@ -0,0 +1,163 @@
+// review-state-build.mjs - read-only git plumbing and buildState.
+
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { detectBackends } from './detect-backends.mjs';
+import { resolveActivityRecipe, DISPLAY_ALIASES, requiredBackendsForConfiguredRecipe, composeReadiness } from './recipes.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { plansInFlight } from './plan-files.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, stripGitLocationEnv, withGitPath } from './git-env.mjs';
+import {
+  computeTreeFingerprint,
+  isTreeClean,
+  isNeverCommittableStat,
+  resolveReceiptsPath,
+  readReceipts,
+  resolveBase,
+} from './core-evidence.mjs';
+import {
+  ACTIVITY, SLOT, backendReceiptStatus, buildHeldSessionState, degradeRecordSet, selectHeldSessionDegrades,
+} from './review-state-judge.mjs';
+import {
+  attestedPlanIdsFor, computePlanAdoptionCoverage, consumeVetoOverride, liftStaleRow, readFlowArming,
+} from './review-state-flow.mjs';
+
+// ── git plumbing (read-only queries; injectable for tests) ─────────────────────────
+
+const gitRaw = (args, cwd, env) =>
+  spawnSync('git', args, { cwd, env: withGitPath(env ?? process.env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+
+// stdout Buffer of a git query, or null when git fails (not a repo / git absent).
+const gitBuf = (args, cwd, env) => {
+  const r = gitRaw(args, cwd, env);
+  if (r.error || r.status !== 0) return null;
+  return r.stdout;
+};
+
+const gitLine = (args, cwd, env) => {
+  const buf = gitBuf(args, cwd, env);
+  return buf == null ? null : buf.toString('utf8').replace(/\r?\n$/, '');
+};
+
+// ── the sandbox-masks advisory (D lane, AD-044 Plan 4 Phase 1.5) ────────────────────
+
+// Count the never-committable untracked paths the STANDARD walk still shows. The review domain
+// ignores them by construction; this count only feeds ONE non-failing advisory line naming the
+// cosmetic sandbox-masks apply — an applied managed block hides the paths from --exclude-standard,
+// so the advisory disappears exactly when the status noise does (no standing detector).
+export const countNeverCommittableUntracked = (cwd, { lstat = lstatSync, env } = {}) => {
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd, env);
+  if (top == null) return 0;
+  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top, env);
+  if (untrackedZ == null) return 0;
+  return untrackedZ
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean)
+    .filter((rel) => {
+      try {
+        return isNeverCommittableStat(lstat(join(top, rel)));
+      } catch {
+        return false;
+      }
+    }).length;
+};
+
+// buildState({ cwd, env, detect }) → everything both renders need. Pure I/O at the edges.
+// EVERY project-relative read (orchestration config, docs/plans, receipts) anchors at the git
+// work-tree ROOT when one exists — the fingerprint is root-anchored, so a subdirectory invocation
+// must read the same config/plans or a dirty unreceipted tree could false-PASS as "no plan in
+// flight". Outside a git tree the cwd is the only anchor (and --check exits 0).
+export const buildState = ({ cwd, env = process.env, detect = detectBackends, surveyVehicle, lstat = lstatSync, readFile = readFileSync } = {}) => {
+  // WHICH repository, first; the config/plan anchor is the stripped discovery's top (from a subdirectory the bare cwd would miss docs/plans — decideCheck refuses on an unanchored root).
+  const location = resolveGitLocation(cwd, { env });
+  const anchoredTop = location.top ?? gitLine(['rev-parse', '--show-toplevel'], cwd, stripGitLocationEnv(env));
+  const root = anchoredTop ?? cwd;
+  const { config, source: configSource } = loadConfig(root);
+  // A bridge-detector throw reaches the hook, never a catch that would also lose the surveyed
+  // executor vehicle: bridge readiness goes unknown (fail closed below), the carrier stays known.
+  let detectionWarning = null;
+  const onDetectError = (err) => {
+    detectionWarning = `backend detection failed (${(err && err.message) || err}) — bridge readiness unknown.`;
+  };
+  const detection = composeReadiness(root, { detect, surveyVehicle, onDetectError });
+  // The resolver stays for DISPLAY only; the OBLIGATIONS come from the configured recipe (never the readiness-degraded effective one — no silent solo).
+  const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity: ACTIVITY, slot: SLOT });
+  const obligations = requiredBackendsForConfiguredRecipe({ config: config ?? {}, readiness: detection, detectionFailed: detectionWarning != null });
+  const requiredBackends = obligations.backends;
+  const plans = plansInFlight(root);
+  // The injected lstat threads through EVERY stat-dependent computation (fingerprint, clean, the
+  // mask count) — a partial injection would let a test observe an inconsistent state.
+  const fingerprint = location.state === 'work-tree' ? computeTreeFingerprint(cwd, { lstat, env }) : null;
+  const clean = fingerprint == null ? null : isTreeClean(cwd, { lstat, env });
+  const receiptsPath = resolveReceiptsPath(cwd, env);
+  const receiptsRead = receiptsPath ? readReceipts(receiptsPath) : { receipts: [], malformed: 0 };
+  const { receipts, malformed } = receiptsRead;
+  const receiptsReadError = receiptsRead.readError ?? null;
+  const backends = requiredBackends.map((b) => ({ backend: b, ...backendReceiptStatus(receipts, b, fingerprint) }));
+  // The D3(b) degrade escape: read the core-evidence store ONLY here, ONLY for the exemption —
+  // the gate never otherwise depends on it (an unavailable store denies the exemption CLOSED,
+  // never fails a tree whose receipts independently satisfy the gate).
+  const base = resolveBase(cwd);
+  const degrade = degradeRecordSet({ cwd, env, fingerprint });
+  const degradedExempt = requiredBackends.filter((b) => degrade.set.has(b));
+  const heldSession = buildHeldSessionState({
+    cwd,
+    env,
+    configuredExecute: [config?.[ACTIVITY]?.execute, config?.task?.execute].find((recipe) => recipe === 'delegated'),
+    plans,
+    fingerprint,
+    clean,
+    degrades: selectHeldSessionDegrades(degrade.records),
+  });
+  // ── the Phase-2 flow arms' state (two-tier activation, P3) ──
+  const flow = readFlowArming({ cwd, env, lstat });
+  const planCoverage = flow.flowArmed
+    ? computePlanAdoptionCoverage({ root, plans, records: flow.records, owner: flow.flowOwner, readFile })
+    : [];
+  const { attestedPlanIds, lensRefusedAttestations } = flow.flowArmed
+    ? attestedPlanIdsFor({ records: flow.records, base, fingerprint })
+    : { attestedPlanIds: [], lensRefusedAttestations: [] };
+  const arms = { flowArmed: flow.flowArmed, receipts, records: flow.records, base, fingerprint, flowConfig: config?.flow ?? null };
+  const armedBackends = backends.map((b) => consumeVetoOverride(liftStaleRow(b, arms), arms));
+  // The solo-class veto probe (#48): under an armed solo recipe every review-capable backend's
+  // CURRENT-tree receipt is still consulted, so a recipe flip to solo never buries a standing veto.
+  const soloVetoRows = flow.flowArmed && obligations.recipe === 'solo'
+    ? Object.values(DISPLAY_ALIASES).map((b) => consumeVetoOverride(liftStaleRow({ backend: b, ...backendReceiptStatus(receipts, b, fingerprint) }, arms), arms))
+    : [];
+  return {
+    resolved,
+    configSource,
+    obligations,
+    requiredBackends,
+    backends: armedBackends,
+    plans,
+    root,
+    rootAnchored: anchoredTop !== null,
+    location,
+    fingerprint,
+    clean,
+    receiptsPath,
+    receiptCount: receipts.length,
+    malformed,
+    receiptsReadError,
+    base,
+    evidenceStorePath: degrade.storePath,
+    evidenceMalformed: degrade.malformed,
+    evidenceReadError: degrade.readError,
+    evidenceUnavailable: degrade.unavailable,
+    degradedExempt,
+    heldSession,
+    maskedUntracked: countNeverCommittableUntracked(cwd, { lstat, env }),
+    detectionWarning,
+    flowPresent: flow.flowPresent,
+    flowArmed: flow.flowArmed,
+    flowBrokenReason: flow.flowBrokenReason,
+    flowOwner: flow.flowOwner,
+    planCoverage,
+    attestedPlanIds,
+    lensRefusedAttestations,
+    soloVetoRows,
+  };
+};

package/tools/review-state-flow.mjs

@@ -0,0 +1,110 @@
+// review-state-flow.mjs - plan-adoption coverage and the armed-flow arms.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { DISPLAY_ALIASES } from './recipes.mjs';
+import { resolveFlowStorePath, readFlowStore, deriveFlowOwner, readPlanFrontmatterId } from './flow-store.mjs';
+import { CHAIN_KIND, authoritativeFlowRecords } from './flow-record.mjs';
+import { selectReliedOnReceipt, evaluateVetoOverride, evaluateInternalAttestationLenses } from './flow-check.mjs';
+import { PLANS_REL } from './plan-files.mjs';
+import { summarizeReviewReceiptsForTree, isShipVerdict } from './core-evidence.mjs';
+
+// The in-flight-plan → adopted-chain coverage map (P13/P19): ONE bounded read + ONE hash per plan
+// file; coverage requires the frontmatter planId, the FULL content digest, and the owner to match
+// the adoption record — a mismatch on any axis refuses internal-only arming by name.
+export const computePlanAdoptionCoverage = ({ root, plans, records, owner, readFile = readFileSync }) =>
+  plans.map((plan) => {
+    let bytes;
+    try {
+      bytes = readFile(join(root, PLANS_REL, plan));
+    } catch (err) {
+      return { plan, planId: null, covered: false, reason: `the plan file is unreadable (${(err && err.code) || (err && err.message) || err})` };
+    }
+    const buf = typeof bytes === 'string' ? Buffer.from(bytes) : bytes;
+    const planId = readPlanFrontmatterId(buf.toString('utf8'));
+    if (planId == null) return { plan, planId: null, covered: false, reason: 'no frontmatter planId — plan filenames are never chain identity (#58); adopt the plan through the flow writer' };
+    const adoptionRecord = records.find((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption' && r.planId === planId);
+    if (adoptionRecord === undefined) return { plan, planId, covered: false, reason: `no adoption record for planId "${planId}"` };
+    if (adoptionRecord.planDigest !== createHash('sha256').update(buf).digest('hex')) {
+      return { plan, planId, covered: false, reason: 'the plan content no longer matches its adoption record (edited after adoption)' };
+    }
+    if (adoptionRecord.owner !== owner) {
+      return { plan, planId, covered: false, reason: `the adoption is owned by "${adoptionRecord.owner}", not this worktree ("${owner}") — a foreign-owner adoption never arms internal-only here` };
+    }
+    return { plan, planId, covered: true };
+  });
+
+// Tier 1 is store-file PRESENCE: no file ⇒ every field below stays inert and the decision is
+// byte-identical to the pre-flow checker (the unarmed fast path also reads NO plan file).
+export const readFlowArming = ({ cwd, env, lstat }) => {
+  const flowPath = resolveFlowStorePath(cwd, env);
+  const flowStat = (() => {
+    if (flowPath == null) return null;
+    try {
+      return lstat(flowPath);
+    } catch (err) {
+      return err && err.code === 'ENOENT' ? null : 'unstatable';
+    }
+  })();
+  const flowPresent = flowStat !== null;
+  const flowRead = flowPresent && flowStat !== 'unstatable' ? readFlowStore(flowPath) : null;
+  const flowBrokenReason = !flowPresent ? null
+    : flowStat === 'unstatable' ? 'the store leaf cannot be stat-ed (fail closed)'
+    : flowRead.readError != null ? `read error: ${flowRead.readError}`
+    : flowRead.malformed > 0 ? `${flowRead.malformed} malformed line(s) (${flowRead.malformedReasons[0]})`
+    : null;
+  const flowArmed = flowPresent && flowBrokenReason == null
+    && flowRead.records.some((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption');
+  const flowOwner = flowArmed ? deriveFlowOwner(cwd) : null;
+  return { flowPresent, flowArmed, flowBrokenReason, flowOwner, records: flowArmed ? flowRead.records : [] };
+};
+
+// The lens-substitution rung (#15/#3): an attestation whose lens set claims a review provider's
+// slot without a then-active down-mark never counts — and its refusal is NAMED, never silent
+// (lensRefusedAttestations feeds the internal-only floor's failure reason).
+export const attestedPlanIdsFor = ({ records, base, fingerprint }) => {
+  const lensRefusedAttestations = [];
+  const attestedPlanIds = [...new Set(authoritativeFlowRecords(records)
+    .filter((r) => r.kind === 'internal-attestation' && r.base === base && r.fingerprint === fingerprint)
+    .filter((r) => {
+      const lensCheck = evaluateInternalAttestationLenses({ record: r, records, providerBackends: Object.values(DISPLAY_ALIASES) });
+      if (!lensCheck.ok) {
+        lensRefusedAttestations.push({ planId: r.planId, reason: lensCheck.reason });
+        return false;
+      }
+      return true;
+    })
+    .map((r) => r.planId))];
+  return { attestedPlanIds, lensRefusedAttestations };
+};
+
+// #61: the SHARED relied-on selector (one home with the flow-check coverage rung) — an unbroken
+// declared-path bookkeeping-delta chain lifts the backend's last receipt; any break, fork, or
+// cap exhaustion stays stale.
+export const liftStaleRow = (row, { flowArmed, receipts, records, base, fingerprint, flowConfig }) => {
+  if (!flowArmed || row.state !== 'stale') return row;
+  const selected = selectReliedOnReceipt({
+    receipts, backend: row.backend, tree: { base, fingerprint },
+    records,
+    declaredPaths: [flowConfig?.debtQueue, flowConfig?.convergenceSummary].filter((p) => typeof p === 'string'),
+    refreshCap: flowConfig?.councilRounds,
+  });
+  if (selected.receipt == null || selected.lifted === 0) return row;
+  return {
+    ...row, state: 'current', verdict: selected.receipt.verdict ?? 'unknown',
+    shipClass: isShipVerdict(selected.receipt.verdict), grounded: true,
+    timestamp: selected.receipt.timestamp ?? null, deltaLift: selected.lifted,
+  };
+};
+
+// #56/#38: a standing CURRENT-tree veto consults its override instance; a delta-lifted veto has
+// no override lane here (the bound set pins the veto receipt's own tree).
+export const consumeVetoOverride = (row, { flowArmed, receipts, records, base, fingerprint }) => {
+  if (!flowArmed || !(row.state === 'current' && !row.shipClass) || row.deltaLift != null) return row;
+  const own = receipts.filter((r) => r.backend === row.backend);
+  const summary = summarizeReviewReceiptsForTree(own, fingerprint);
+  if (summary.state !== 'current') return row;
+  const lift = evaluateVetoOverride({ records, vetoReceipt: summary.receipt, tree: { base, fingerprint } });
+  return lift.lifted ? { ...row, overrideLabel: lift.label } : row;
+};