@sabaiway/agent-workflow-kit 14.4.1 → 14.4.3

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.3 — cleanup after the two splits: one false doc pointer, a test title, a list order, comments and whitespace; nothing the kit decides, prints or records changes
+
+**Six small review findings from the review-state and core-evidence splits are fixed.** The only shipped doc change is in
+`references/modes/commit-guard.md`: it now says the fingerprint argv lives in `core-evidence-tree.mjs` and that the
+`core-evidence.mjs` facade re-exports it. The earlier text named the facade as its home. Everything else is one
+test title, one list order, comments and whitespace.
+
+- **Tests.** In `tools/review-state.test.mjs`, the block that runs `--check` and proves a later ungrounded receipt
+  outranks an earlier grounded SHIP no longer carries the name `backendReceiptStatus`. In
+  `test/package-content.test.mjs`, `tools/grounding.mjs` sits under the AD-038 pair comment again, and two comments
+  use a real em dash instead of the literal `\u2014` escape. The `cleanState` helper in `tools/review-state-judge.test.mjs`
+  loses a stray indent, and a blank line before a closing brace in `tools/core-evidence-tree.test.mjs` is gone.
+- **Sources.** The first-line comments of `review-state-build.mjs`, `review-state-flow.mjs` and `review-state-render.mjs`
+  use the em dash the other modules use, and `core-evidence-store-read.mjs` loses a doubled blank line.
+
+## 14.4.2 — `core-evidence.mjs` becomes a facade over six leaves; nothing the tool decides, prints or records changes (AD-150)
+
+**The core-evidence writer is now six small modules behind its old entry point.** `tools/core-evidence.mjs` was one
+1251-line file. 14.4.2 moves its code into six library modules and keeps a 143-line facade with the unchanged header,
+the command line and the same 49 exported names, so no import site outside the core-evidence suites moves. Exit codes,
+messages, records and the tree fingerprint are the same as in 14.4.1. Story S2 of the epic
+`REVIEW-STATE-AND-CORE-EVIDENCE-ARE-MONOLITHS`; contract `docs/ai/specs/kit/core-evidence.md` (revision 1).
+
+- **The leaves.** `core-evidence-tree.mjs` (git queries, base, tree fingerprint, working state),
+  `core-evidence-receipts.mjs` (receipt path and reader, verdict vocabulary, receipt classes),
+  `core-evidence-store-read.mjs` (testId format, store path, record schema, reader, keys), `core-evidence-store.mjs`
+  (the one append and the `red-proof` and `degrade` verbs), `core-evidence-red-proof.mjs` (the test-file safeguards
+  and the repeated test runs) and `core-evidence-summary.mjs` (the `summary` state and render). The summary module does not
+  import the append module. None of the six imports the facade or runs as a script; each is under the 400-line cap, and
+  the size records of the old module and its suite are gone.
+- **Tests.** The 96 cases of `core-evidence.test.mjs` move unchanged: 75 into five module suites, 21 stay in the
+  facade suite, with shared fixtures in `core-evidence-harness.test.mjs`; no case is added or removed. `core-evidence-hostile.test.mjs` imports the
+  modules it calls. `test/kit-readonly-tools.test.mjs` now looks for the `--absolute-git-dir` query in the receipts
+  module, and `test/package-content.test.mjs` names the six modules and pins 324 packed files. A comment in `tools/exec-producer.mjs`
+  that pointed at a line range of the old module now names `flaggedIndexLag` in the tree module.
+
 ## 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

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.1'
+  version: '14.4.3'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.4.1",
+  "version": "14.4.3",
   "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/commit-guard.md

@@ -24,7 +24,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/commit-guard.mjs --check [--cwd <dir>]` —
 
 **Boundary — what «the commit captures the tree» means for submodules.** The guard proves the SUPERPROJECT commit captures the SUPERPROJECT working tree. A superproject commit stores a submodule as a gitlink OID and never captures its file content — that content is the submodule's own commit boundary. The dirty-submodule refusal is therefore a best-effort COURTESY beyond the guard's boundary, and its completeness is bounded by what the submodule itself reports: a file held behind a `skip-worktree` / `assume-unchanged` bit in the SUBMODULE's own index is invisible to the submodule's status and so to this refusal. Deepening the nested probe was tried and abandoned — three consecutive review rounds each produced a new way for it to answer wrongly — so the honest contract is the boundary, not a completeness claim. Tracked as its own class.
 
-**Stated residual — the payload flags close the config-blind class.** The fingerprint argv in the ONE node home, `core-evidence.mjs`, carries `--no-textconv --ignore-submodules=none` beside `--no-ext-diff`; both bash twins are parity-pinned to that set for their fingerprint and review-payload diffs, so host textconv and submodule-ignore configuration cannot hide staged bytes. Refusal 2 remains the fail-closed backstop for any DIRTY index whose staged content the payload still cannot see: it names making the change visible to `git diff --cached` and re-running the final gate, without guessing a flag or configuration key.
+**Stated residual — the payload flags close the config-blind class.** The fingerprint argv in the ONE node home, `core-evidence-tree.mjs` (re-exported by the `core-evidence.mjs` facade), carries `--no-textconv --ignore-submodules=none` beside `--no-ext-diff`; both bash twins are parity-pinned to that set for their fingerprint and review-payload diffs, so host textconv and submodule-ignore configuration cannot hide staged bytes. Refusal 2 remains the fail-closed backstop for any DIRTY index whose staged content the payload still cannot see: it names making the change visible to `git diff --cached` and re-running the final gate, without guessing a flag or configuration key.
 
 **Human residual (stated, accepted):** `git commit --no-verify` bypasses any pre-commit hook — a self-discipline mechanism, not a security boundary.
 

package/tools/core-evidence-receipts.mjs

@@ -0,0 +1,191 @@
+// core-evidence-receipts.mjs — the review-receipt read path, the verdict vocabulary and the receipt classes; the contract is the header of core-evidence.mjs.
+
+import { join } from 'node:path';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { gitLine } from './core-evidence-tree.mjs';
+
+export const RECEIPTS_BASENAME = 'agent-workflow-review-receipts.jsonl';
+
+export const resolveReceiptsPath = (cwd, env = process.env) => {
+  if (env.AW_REVIEW_RECEIPTS) return env.AW_REVIEW_RECEIPTS;
+  const gitDir = gitLine(['rev-parse', '--absolute-git-dir'], cwd);
+  return gitDir == null ? null : join(gitDir, RECEIPTS_BASENAME);
+};
+
+// Parse the receipt file → { receipts, malformed, readError? }. Absent file → empty (not an
+// error: no review ever ran). The read rides the fs-read-nofollow leaf (RECEIPTS-READER-NOFOLLOW):
+// a symlinked/FIFO/directory receipts path surfaces as readError — never content, never an empty
+// success — and any NON-ENOENT failure surfaces as readError too; an unreadable store must never
+// silently read as "no receipts" (the summary withholds its verdicts section on it). A malformed
+// line is counted + reported, never silently dropped. `io` is the injectable-read test seam
+// (readRegularFileNoFollow's descriptor-level io).
+export const readReceipts = (path, io = {}) => {
+  const read = readRegularFileNoFollow(path, io);
+  if (read.outcome === 'absent') return { receipts: [], malformed: 0 };
+  if (read.outcome === 'foreign') {
+    return { receipts: [], malformed: 0, readError: `the receipts store is a ${read.className}, not a regular file — refusing to read it (fail closed)` };
+  }
+  if (read.outcome === 'error') return { receipts: [], malformed: 0, readError: read.code };
+  const raw = read.content;
+  const receipts = [];
+  let malformed = 0;
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === 'object' && typeof parsed.backend === 'string') receipts.push(parsed);
+      else malformed += 1;
+    } catch {
+      malformed += 1;
+    }
+  }
+  return { receipts, malformed };
+};
+
+// The closed review-verdict vocabulary (the union of both wrappers' closed grammars). Any
+// RECOGNIZED verdict is review EVIDENCE (a recognized negative is an authoritative veto); ONLY
+// ship-class SATISFIES the review-state gate.
+const SHIP_VERDICTS = new Set(['ship', 'ship with nits']);
+const NEGATIVE_VERDICTS = new Set(['revise', 'rethink', 'rework']);
+// Type-strict: only a STRING can enter the closed grammar — String() coercion would admit an
+// array like ["ship"] as ship-class.
+const normalizeVerdict = (verdict) => (typeof verdict === 'string' ? verdict.trim().toLowerCase() : null);
+export const isShipVerdict = (verdict) => {
+  const v = normalizeVerdict(verdict);
+  return v !== null && SHIP_VERDICTS.has(v);
+};
+export const isRecognizedVerdict = (verdict) => {
+  const v = normalizeVerdict(verdict);
+  return v !== null && (SHIP_VERDICTS.has(v) || NEGATIVE_VERDICTS.has(v));
+};
+
+export const REVIEW_RECEIPT_CLASS = Object.freeze({
+  NOT_CURRENT: 'not-current',
+  ATTESTING: 'attesting',
+  UNGROUNDED: 'ungrounded',
+  UNRECOGNIZED_VERDICT: 'unrecognized-verdict',
+  PROBE: 'probe',
+  UNMARKED: 'unmarked',
+  MALFORMED_MARKER: 'malformed-marker',
+  POSTURE_UNMARKED: 'posture-unmarked',
+  MALFORMED_POSTURE: 'malformed-posture',
+  DELIVERY_UNMARKED: 'delivery-unmarked',
+  MALFORMED_DELIVERY: 'malformed-delivery',
+});
+
+// Backends whose `code` receipts must SELF-DECLARE how the change set reached the model (D8b).
+// Scoped, not universal: agy's oversized lane was the one observed returning a confident
+// fabrication, and codex's receipt semantics are deliberately untouched.
+const DELIVERY_DECLARING_BACKENDS = new Set(['agy']);
+
+// A delivery declaration is a lowercase token naming HOW delivery was established (`inline` when
+// the whole change set rode one prompt, `fed` when a chunked feed proved it by echo). The gate
+// requires PRESENT and WELL-FORMED, never a PARTICULAR value — which lane was used is the
+// wrapper's business; that the receipt declares one at all is the gate's.
+const isValidReceiptDelivery = (delivery) =>
+  typeof delivery === 'string' && delivery.length > 0 && delivery.length <= 32 && /^[a-z][a-z0-9-]*$/.test(delivery);
+
+// The D5 posture declaration (strip Phase 4): an object whose `model` is a NON-EMPTY string;
+// `effort` (when present) a non-empty string; `tier` (when present) a non-empty string or null.
+// Backend-agnostic — the wrapper is the writer authority on WHICH keys it declares.
+const isValidReceiptPosture = (posture) => {
+  if (posture === null || typeof posture !== 'object' || Array.isArray(posture)) return false;
+  if (typeof posture.model !== 'string' || posture.model.length === 0) return false;
+  if (Object.hasOwn(posture, 'effort') && (typeof posture.effort !== 'string' || posture.effort.length === 0)) return false;
+  if (Object.hasOwn(posture, 'tier') && posture.tier !== null && (typeof posture.tier !== 'string' || posture.tier.length === 0)) return false;
+  return true;
+};
+
+// Classify ONE receipt against a tree fingerprint. Order is load-bearing: identity first (is this
+// even about the current tree?), then the probe marker (may it attest at all?), then the D5
+// posture marker (same self-declaration doctrine — an absent/invalid posture is non-attesting,
+// fail closed; pre-D5 receipts stop satisfying, the recovery is re-running the review), then the
+// verdict-in-recognized-vocabulary arm BEFORE grounding — an unrecognized verdict is an
+// unconditional refusal that grounding must never reclassify (an ungrounded `unknown` receipt
+// otherwise reads UNGROUNDED and can be masked by another backend's SHIP), then grounding.
+export const classifyReviewReceiptForTree = (receipt, fingerprint) => {
+  if (!(receipt !== null && typeof receipt === 'object' && !Array.isArray(receipt)) || receipt.fresh !== true || receipt.artifact !== 'code' || receipt.fingerprint !== fingerprint) {
+    return REVIEW_RECEIPT_CLASS.NOT_CURRENT;
+  }
+  if (!Object.hasOwn(receipt, 'probe')) return REVIEW_RECEIPT_CLASS.UNMARKED;
+  if (typeof receipt.probe !== 'boolean') return REVIEW_RECEIPT_CLASS.MALFORMED_MARKER;
+  if (receipt.probe === true) return REVIEW_RECEIPT_CLASS.PROBE;
+  if (!Object.hasOwn(receipt, 'posture')) return REVIEW_RECEIPT_CLASS.POSTURE_UNMARKED;
+  if (!isValidReceiptPosture(receipt.posture)) return REVIEW_RECEIPT_CLASS.MALFORMED_POSTURE;
+  if (!isRecognizedVerdict(receipt.verdict)) return REVIEW_RECEIPT_CLASS.UNRECOGNIZED_VERDICT;
+  if (receipt.grounded !== true) return REVIEW_RECEIPT_CLASS.UNGROUNDED;
+  // LAST on purpose. The delivery arm may only intercept a receipt that would otherwise ATTEST:
+  // placing it earlier pulled delivery-less `unrecognized-verdict` / `ungrounded` agy receipts out
+  // of summarize's latest-NORMAL selection, so an EARLIER ship survived a LATER bad receipt — the
+  // selection-first doctrine, broken silently. Those two classes stay byte-identical to before;
+  // the ONE class this arm changes is the previously-attesting one, which is the point.
+  if (DELIVERY_DECLARING_BACKENDS.has(receipt.backend)) {
+    if (!Object.hasOwn(receipt, 'delivery')) return REVIEW_RECEIPT_CLASS.DELIVERY_UNMARKED;
+    if (!isValidReceiptDelivery(receipt.delivery)) return REVIEW_RECEIPT_CLASS.MALFORMED_DELIVERY;
+  }
+  return REVIEW_RECEIPT_CLASS.ATTESTING;
+};
+
+// Summarize one backend's receipts for a tree → { state, receipt, counts… }. The LATEST NORMAL
+// (probe-free, marker-valid, current-fingerprint) receipt is selected FIRST and THEN judged — a
+// later unknown-verdict or ungrounded receipt never lets an earlier SHIP survive, and a probe (or
+// forged marker) written after a real review never becomes the authoritative verdict.
+export const summarizeReviewReceiptsForTree = (receipts, fingerprint) => {
+  const classified = receipts
+    .map((receipt) => ({ receipt, classification: classifyReviewReceiptForTree(receipt, fingerprint) }))
+    .filter(({ classification }) => classification !== REVIEW_RECEIPT_CLASS.NOT_CURRENT);
+  const rowsFor = (classification) => classified.filter((row) => row.classification === classification);
+  const normal = classified.filter(({ classification }) =>
+    classification === REVIEW_RECEIPT_CLASS.ATTESTING ||
+    classification === REVIEW_RECEIPT_CLASS.UNGROUNDED ||
+    classification === REVIEW_RECEIPT_CLASS.UNRECOGNIZED_VERDICT);
+  const probe = rowsFor(REVIEW_RECEIPT_CLASS.PROBE);
+  const unmarked = rowsFor(REVIEW_RECEIPT_CLASS.UNMARKED);
+  const malformedMarker = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_MARKER);
+  const postureUnmarked = rowsFor(REVIEW_RECEIPT_CLASS.POSTURE_UNMARKED);
+  const malformedPosture = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_POSTURE);
+  const deliveryUnmarked = rowsFor(REVIEW_RECEIPT_CLASS.DELIVERY_UNMARKED);
+  const malformedDelivery = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_DELIVERY);
+  const counts = {
+    currentCount: classified.length,
+    ungroundedCount: rowsFor(REVIEW_RECEIPT_CLASS.UNGROUNDED).length,
+    unrecognizedVerdictCount: rowsFor(REVIEW_RECEIPT_CLASS.UNRECOGNIZED_VERDICT).length,
+    probeExcluded: probe.length,
+    markerRejected: malformedMarker.length,
+    unmarkedRejected: unmarked.length,
+    postureRejected: postureUnmarked.length + malformedPosture.length,
+    deliveryRejected: deliveryUnmarked.length + malformedDelivery.length,
+  };
+  if (normal.length > 0) {
+    const latest = normal[normal.length - 1];
+    if (latest.classification === REVIEW_RECEIPT_CLASS.ATTESTING) return { state: 'current', receipt: latest.receipt, ...counts };
+    if (latest.classification === REVIEW_RECEIPT_CLASS.UNGROUNDED) return { state: 'ungrounded', receipt: latest.receipt, ...counts };
+    return { state: 'unrecognized-verdict', receipt: latest.receipt, ...counts };
+  }
+  if (classified.length > 0) {
+    return {
+      state: malformedMarker.length > 0 || unmarked.length > 0 || counts.postureRejected > 0 || counts.deliveryRejected > 0 ? 'rejected' : 'probe',
+      receipt: null,
+      ...counts,
+    };
+  }
+  return { state: 'none', receipt: null, ...counts };
+};
+
+// Why this backend has no attestation — one stated sentence per distinct recovery.
+export const describeMissingReviewAttestation = (summary) => {
+  if (summary.state === 'current') return null;
+  const exclusions = [
+    summary.probeExcluded > 0 ? `${summary.probeExcluded} probe receipt(s)` : null,
+    summary.markerRejected > 0 ? `${summary.markerRejected} receipt(s) with a malformed probe marker` : null,
+    summary.unmarkedRejected > 0 ? `${summary.unmarkedRejected} receipt(s) with no probe marker` : null,
+    (summary.postureRejected ?? 0) > 0 ? `${summary.postureRejected} receipt(s) with an absent/invalid run posture (a pre-D5 wrapper — re-run the review on the current bridge)` : null,
+    (summary.deliveryRejected ?? 0) > 0 ? `${summary.deliveryRejected} agy receipt(s) with an absent/invalid delivery declaration (minted before the change set was PROVEN delivered — re-run the review on the current bridge)` : null,
+  ].filter(Boolean);
+  const exclusionSuffix = exclusions.length > 0 ? `; excluded ${exclusions.join(', ')}` : '';
+  if (summary.state === 'ungrounded') return `the latest normal receipt for the current tree is ungrounded${exclusionSuffix}`;
+  if (summary.state === 'unrecognized-verdict') return `the latest normal receipt carries an unrecognized verdict (${JSON.stringify(summary.receipt?.verdict ?? null)}) — an unknown verdict never attests${exclusionSuffix}`;
+  if (summary.state === 'probe') return 'only probe receipts exist for the current tree — a probe review never attests';
+  if (summary.state === 'rejected') return `current-tree receipts have an untrustworthy probe marker, run posture or delivery declaration${exclusionSuffix}`;
+  return 'no fresh code receipt exists for the current tree';
+};

package/tools/core-evidence-red-proof.mjs

@@ -0,0 +1,125 @@
+// core-evidence-red-proof.mjs — the red-proof probe: the test-file safeguards and the N-rerun observation; the contract is the header of core-evidence.mjs.
+
+import { readFileSync, lstatSync, realpathSync } from 'node:fs';
+import { join, normalize, sep, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lexicalRepoRelative } from './repo-lex.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
+import { splitTestId } from './core-evidence-store-read.mjs';
+
+// ── the probe safeguards (moved verbatim from the retired fold runner) ────────────────────────────
+
+// Node sets NODE_TEST_CONTEXT for any process running UNDER `node --test`; a fresh `node --test`
+// that inherits it silently SKIPS running its files. The probe spawns `node --test`, so it strips
+// that var (a no-op in normal invocation).
+export const childTestEnv = (env, extra = {}) => {
+  const out = { ...env, ...extra };
+  delete out.NODE_TEST_CONTEXT;
+  return out;
+};
+
+const PROBE_RESULT_RE = /^(ok|not ok) \d+ - (.*)$/;
+const PROBE_FAIL_RE = /^# fail (\d+)$/;
+const PROBE_DIRECTIVE_RE = /#\s*(?:skip|todo)\b/i; // a TAP SKIP/TODO directive — the test did NOT run
+
+// parseProbeOutput({ stdout, code, fileArg }) → { resolvable, executed, baselineGreen }. The file
+// wrapper is matched by BASENAME (node normalizes the echoed path); a directive-carrying result
+// line never counts (some Node lines emit pattern-filtered tests as SKIP — the guard is
+// version-agnostic on purpose).
+export const parseProbeOutput = ({ stdout, code, fileArg }) => {
+  let matched = 0;
+  let notOk = 0;
+  let failCount = null;
+  const wanted = basename(String(fileArg).trim());
+  for (const line of String(stdout).split('\n')) {
+    const m = PROBE_RESULT_RE.exec(line);
+    if (m && !PROBE_DIRECTIVE_RE.test(m[2]) && basename(m[2].trim()) !== wanted) {
+      matched += 1;
+      if (m[1] === 'not ok') notOk += 1;
+    }
+    const f = PROBE_FAIL_RE.exec(line.trim());
+    if (f) failCount = Number(f[1]);
+  }
+  const resolvable = matched > 0;
+  const fails = (failCount ?? 0) + notOk;
+  return { resolvable, executed: matched, baselineGreen: resolvable && code === 0 && fails === 0 };
+};
+
+// The shell-free node:test argv. The pattern rides `=`-joined: as a separate token a pattern
+// beginning with "-" would parse as an OPTION and silently select no test.
+export const defaultBoundArgv = (file, pattern) => ['node', '--test', '--test-reporter', 'tap', `--test-name-pattern=${pattern}`, file];
+
+// containsPath(realRoot, realAbs) → strictly INSIDE. Segment-safe ('/a' never contains '/ab') and
+// correct for a repo at the filesystem root.
+export const containsPath = (realRoot, realAbs) => realAbs.startsWith(realRoot.endsWith(sep) ? realRoot : realRoot + sep);
+
+// resolveTestFile(rootTop, rel, deps?) → { ok: true, abs } | { ok: false, reason } (never throws).
+// Repo-relative only; a REGULAR file under no-follow lstat; the RESOLVED real path contained under
+// the REAL repo root (a leaf check alone would let a symlinked PARENT directory escape).
+export const resolveTestFile = (rootTop, rel, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const realpath = deps.realpath ?? realpathSync;
+  const lex = lexicalRepoRelative(rel);
+  if (!lex.ok) return { ok: false, reason: lex.reason };
+  const abs = join(rootTop, normalize(rel));
+  let st;
+  try {
+    st = lstat(abs);
+  } catch {
+    return { ok: false, reason: `file "${rel}" does not exist` };
+  }
+  if (!st.isFile()) return { ok: false, reason: `"${rel}" is not a regular file (a symlink/directory/device is never followed — fail closed)` };
+  let realAbs;
+  let realRoot;
+  try {
+    realAbs = realpath(abs);
+    realRoot = realpath(rootTop);
+  } catch {
+    return { ok: false, reason: `cannot resolve the real path of "${rel}"` };
+  }
+  if (!containsPath(realRoot, realAbs)) return { ok: false, reason: `"${rel}" resolves outside the repo root (a symlinked parent directory) — fail closed` };
+  return { ok: true, abs: realAbs };
+};
+
+// sha-256 over the file's BYTES; null on a read failure (the caller reads that as unresolvable).
+export const hashFileBytes = (abs) => {
+  try {
+    return createHash('sha256').update(readFileSync(abs)).digest('hex');
+  } catch {
+    return null;
+  }
+};
+
+// The N-rerun probe. The custody hash is taken BEFORE the runs (the content the observation
+// attests); the spawn ALWAYS uses the resolver's canonical absolute path — the executed file must
+// be the hashed file independent of runner path semantics. A timed-out or signal-killed run is
+// neither red nor green — it lands in `timeouts` (quarantine fuel).
+export const probeBound = ({ testId, rootTop, env, reruns, timeoutS }) => {
+  const { file, pattern } = splitTestId(testId);
+  const resolved = resolveTestFile(rootTop, file);
+  const fileHash = resolved.ok ? hashFileBytes(resolved.abs) : null;
+  let executed = 0;
+  let greens = 0;
+  let reds = 0;
+  let timeouts = 0;
+  if (resolved.ok && fileHash != null) {
+    for (let i = 0; i < reruns; i += 1) {
+      const argv = defaultBoundArgv(resolved.abs, pattern);
+      const res = spawnSync(argv[0], argv.slice(1), {
+        cwd: rootTop, env: childTestEnv(env), encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER, timeout: timeoutS * 1000,
+      });
+      if ((res.error && res.error.code === 'ETIMEDOUT') || res.signal != null) {
+        timeouts += 1;
+        continue;
+      }
+      const p = parseProbeOutput({ stdout: res.stdout ?? '', code: res.error ? 1 : res.status ?? 1, fileArg: file });
+      executed = Math.max(executed, p.executed);
+      if (!p.resolvable) continue;
+      if (p.baselineGreen) greens += 1;
+      else reds += 1;
+    }
+  }
+  const entry = { executed, runs: reruns, greens, reds, timeouts, fileHash };
+  return { entry, file, resolveReason: resolved.ok ? (fileHash == null ? `cannot read "${file}"` : null) : resolved.reason };
+};

package/tools/core-evidence-store-read.mjs

@@ -0,0 +1,207 @@
+// core-evidence-store-read.mjs — the read half of the evidence store: testId format, path, schema, reader and keys; the contract is the header of core-evidence.mjs.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { lexicalRepoRelative } from './repo-lex.mjs';
+// The coverage vocabulary leaf: run-gates RECORDS the token this validator checks, and run-gates
+// imports core-evidence (the sole-writer boundary), so their shared home sits below both.
+import { COVERAGE, FINAL_COVERAGE_STATES } from './coverage-state.mjs';
+import { gitLine } from './core-evidence-tree.mjs';
+
+// testId FORMAT: "<repo-relative test file>#<test-name-pattern>" — a "#" separator with BOTH halves
+// non-empty. Format-only (no suffix rule); resolvability is the probe's job.
+const TESTID_SEPARATOR = '#';
+export const isWellFormedTestId = (v) => {
+  if (typeof v !== 'string') return false;
+  const at = v.indexOf(TESTID_SEPARATOR);
+  return at > 0 && at < v.length - 1;
+};
+export const splitTestId = (v) => {
+  const at = v.indexOf(TESTID_SEPARATOR);
+  return { file: v.slice(0, at), pattern: v.slice(at + 1) };
+};
+
+// ── the store: ONE git-dir JSONL file (D7) ────────────────────────────────────────────────────────
+
+export const EVIDENCE_BASENAME = 'agent-workflow-core-evidence.jsonl';
+export const EVIDENCE_SCHEMA_VERSION = 1;
+
+// AW_CORE_EVIDENCE overrides (the AW_REVIEW_RECEIPTS idiom); else <git dir>/basename; null outside
+// a git work tree.
+export const resolveEvidencePath = (cwd, env = process.env) => {
+  if (env.AW_CORE_EVIDENCE) return env.AW_CORE_EVIDENCE;
+  const gitDir = gitLine(['rev-parse', '--absolute-git-dir'], cwd);
+  return gitDir == null ? null : join(gitDir, EVIDENCE_BASENAME);
+};
+
+// ── schema validation (closed kinds, per-kind arms; unknown schema/kind fail CLOSED) ──────────────
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const HEX40_RE = /^[0-9a-f]{40}$/;
+
+export const validateEvidenceRecord = (record) => {
+  if (!isPlainObject(record)) return { ok: false, reason: 'record is not an object' };
+  if (record.schema !== EVIDENCE_SCHEMA_VERSION) {
+    return { ok: false, reason: `unknown schema ${JSON.stringify(record.schema)} — this reader accepts schema ${EVIDENCE_SCHEMA_VERSION} only (fail closed)` };
+  }
+  if (record.kind === 'red-proof') {
+    if (!isWellFormedTestId(record.testId)) return { ok: false, reason: 'red-proof: testId must be "<test-file>#<test-name-pattern>" (a "#" separator, both halves non-empty)' };
+    if (!isNonEmptyString(record.file)) return { ok: false, reason: 'red-proof: file must be the non-empty repo-relative test-file path' };
+    const lex = lexicalRepoRelative(record.file);
+    if (!lex.ok) return { ok: false, reason: `red-proof: file must be lexically repo-relative — ${lex.reason}` };
+    if (record.file !== splitTestId(record.testId).file) return { ok: false, reason: 'red-proof: file must equal the testId file half — one path source of truth (a mismatched declaration is refused)' };
+    if (typeof record.fileHash !== 'string' || !HEX64_RE.test(record.fileHash)) return { ok: false, reason: 'red-proof: fileHash must be a 64-hex sha256 of the test-file bytes' };
+    if (!Number.isInteger(record.runs) || record.runs < 1) return { ok: false, reason: 'red-proof: runs must be a positive integer' };
+    if (record.reds !== record.runs) return { ok: false, reason: 'red-proof: reds must equal runs — an observed-red declaration is N/N by construction' };
+    if (record.base !== null && (typeof record.base !== 'string' || !(HEX40_RE.test(record.base) || HEX64_RE.test(record.base)))) return { ok: false, reason: 'red-proof: base must be the 40- or 64-hex HEAD sha (git sha1/sha256 object formats), or null on an unborn branch' };
+    if (typeof record.fingerprint !== 'string' || !HEX64_RE.test(record.fingerprint)) return { ok: false, reason: 'red-proof: fingerprint must be the 64-hex PRE-FIX tree fingerprint' };
+    if (!isNonEmptyString(record.timestamp)) return { ok: false, reason: 'red-proof: timestamp must be a non-empty string' };
+    return { ok: true };
+  }
+  if (record.kind === 'degrade') {
+    if (typeof record.backend !== 'string' || record.backend.trim() === '') return { ok: false, reason: 'degrade: backend must be a non-empty string (whitespace-only is refused)' };
+    if (typeof record.reason !== 'string' || record.reason.trim() === '') return { ok: false, reason: 'degrade: reason must be a non-empty string — a degrade without a stated reason is refused (fail closed)' };
+    if (typeof record.fingerprint !== 'string' || !HEX64_RE.test(record.fingerprint)) return { ok: false, reason: 'degrade: fingerprint must be the 64-hex tree fingerprint the degrade attests' };
+    if (!isNonEmptyString(record.timestamp)) return { ok: false, reason: 'degrade: timestamp must be a non-empty string' };
+    return { ok: true };
+  }
+  if (record.kind === 'final-start') {
+    if (typeof record.fingerprint !== 'string' || !HEX64_RE.test(record.fingerprint)) return { ok: false, reason: 'final-start: fingerprint must be the 64-hex tree fingerprint the attempt targets' };
+    if (!isNonEmptyString(record.attempt)) return { ok: false, reason: 'final-start: attempt must be a non-empty id — the completion closes exactly THIS start (linkage)' };
+    if (!isNonEmptyString(record.timestamp)) return { ok: false, reason: 'final-start: timestamp must be a non-empty string' };
+    return { ok: true };
+  }
+  if (record.kind === 'final') {
+    if (record.status !== 'green' && record.status !== 'red') return { ok: false, reason: `final: status must be "green" or "red" (got ${JSON.stringify(record.status)})` };
+    if (!isNonEmptyString(record.attempt)) return { ok: false, reason: 'final: attempt must be the non-empty id of the start this completion closes' };
+    for (const field of ['fingerprintBefore', 'fingerprintAfter']) {
+      if (typeof record[field] !== 'string' || !HEX64_RE.test(record[field])) return { ok: false, reason: `final: ${field} must be a 64-hex tree fingerprint` };
+    }
+    if (!Array.isArray(record.declared) || record.declared.length === 0 || !record.declared.every((d) => isPlainObject(d) && isNonEmptyString(d.id) && isNonEmptyString(d.cmd))) {
+      return { ok: false, reason: 'final: declared must be the non-empty ordered {id, cmd} array the run executed — an empty declaration never attests' };
+    }
+    if (!Array.isArray(record.results) || !record.results.every((r) => isPlainObject(r) && isNonEmptyString(r.id) && typeof r.ok === 'boolean' && (r.code === null || Number.isInteger(r.code)))) {
+      return { ok: false, reason: 'final: results must be the per-gate {id, ok, code} array (code integer, or null on a spawn failure)' };
+    }
+    if (record.results.length !== record.declared.length || !record.results.every((r, i) => r.id === record.declared[i].id)) {
+      return { ok: false, reason: 'final: results must mirror the declared gates 1:1 IN ORDER — a partial or shuffled attribution never attests' };
+    }
+    if (record.integrityFailure !== null && !isNonEmptyString(record.integrityFailure)) {
+      return { ok: false, reason: 'final: integrityFailure must be null or a non-empty reason (an artifact moved under the run)' };
+    }
+    const derived = record.results.every((r) => r.ok) && record.integrityFailure === null ? 'green' : 'red';
+    if (record.status !== derived) {
+      return { ok: false, reason: `final: status ${JSON.stringify(record.status)} contradicts the results/integrity content (derived ${JSON.stringify(derived)}) — status is DERIVED, never asserted` };
+    }
+    if (!isPlainObject(record.evidenceHashes)
+      || typeof record.evidenceHashes.redProof !== 'string' || !HEX64_RE.test(record.evidenceHashes.redProof)
+      || typeof record.evidenceHashes.degrade !== 'string' || !HEX64_RE.test(record.evidenceHashes.degrade)) {
+      return { ok: false, reason: 'final: evidenceHashes must carry 64-hex sha256 of the canonical red-proof and degrade serializations' };
+    }
+    // The D10 flow binding (Plan 4 Decision 2) is ADDITIVE: absent = a pre-flow-binding final
+    // (still valid); present must be the 64-hex owner-scoped projection hash.
+    if ('flow' in record.evidenceHashes && (typeof record.evidenceHashes.flow !== 'string' || !HEX64_RE.test(record.evidenceHashes.flow))) {
+      return { ok: false, reason: 'final: evidenceHashes.flow, when present, must be a 64-hex sha256 of the owner-scoped flow projection' };
+    }
+    if (record.lcovSha256 !== null && (typeof record.lcovSha256 !== 'string' || !HEX64_RE.test(record.lcovSha256))) {
+      return { ok: false, reason: 'final: lcovSha256 must be a 64-hex sha256 of the consumed lcov file, or null when none was produced' };
+    }
+    // The run's coverage token is ADDITIVE (absent = a pre-token receipt, still valid) and CLOSED.
+    // `certified` is cross-checked against the bound digest — a run that certified a verdict read
+    // bytes, so the two fields can never disagree in the store.
+    if ('coverage' in record) {
+      if (!FINAL_COVERAGE_STATES.includes(record.coverage)) {
+        return { ok: false, reason: `final: coverage, when present, must be one of ${FINAL_COVERAGE_STATES.join(' | ')} (got ${JSON.stringify(record.coverage)}; a final run always selects the canonical checker, so "none" never rides a final receipt)` };
+      }
+      if (record.coverage === COVERAGE.certified && record.lcovSha256 === null) {
+        return { ok: false, reason: 'final: coverage "certified" requires a bound lcovSha256 — a certified verdict was issued over lcov bytes that were read' };
+      }
+    }
+    if (!isNonEmptyString(record.timestamp)) return { ok: false, reason: 'final: timestamp must be a non-empty string' };
+    return { ok: true };
+  }
+  return { ok: false, reason: `unknown kind ${JSON.stringify(record.kind)} — closed set: red-proof | degrade | final-start | final (fail closed)` };
+};
+
+// ── the fail-closed reader ────────────────────────────────────────────────────────────────────────
+
+// parseEvidenceText(raw) → { records, malformed, malformedReasons } — the ONE per-line parse +
+// validation pass. readEvidence AND the append preflight consume it over the SAME captured bytes
+// (a second read between check and write would be a TOCTOU gap).
+export const parseEvidenceText = (raw) => {
+  const records = [];
+  const malformedReasons = [];
+  const lines = String(raw).split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i].trim() === '') continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(lines[i]);
+    } catch {
+      malformedReasons.push(`line ${i + 1}: invalid JSON`);
+      continue;
+    }
+    const v = validateEvidenceRecord(parsed);
+    if (v.ok) records.push(parsed);
+    else malformedReasons.push(`line ${i + 1}: ${v.reason}`);
+  }
+  return { records, malformed: malformedReasons.length, malformedReasons };
+};
+
+// readEvidence(path) → { records, malformed, malformedReasons, readError? }. Absent file → empty
+// (no evidence yet is not an error). Every non-parsing / non-validating line is COUNTED with its
+// reason — consumers fail closed on malformed > 0, never silently drop.
+export const readEvidence = (path, readFile = readFileSync) => {
+  let raw;
+  try {
+    raw = readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { records: [], malformed: 0, malformedReasons: [] };
+    return { records: [], malformed: 0, malformedReasons: [], readError: (err && err.code) || (err && err.message) || 'read failed' };
+  }
+  return parseEvidenceText(raw);
+};
+
+// ── D6a: per-kind keys, authoritative selection, canonical serialization ──────────────────────────
+
+// Space-joined with the CLOSED (validated hex-or-null) field in the MIDDLE, the free-form field
+// last — content can then never forge a separator collision (base/fingerprint carry no spaces by
+// validation; the last field absorbs anything).
+export const evidenceKey = (r) =>
+  r.kind === 'red-proof' ? `red-proof ${r.base} ${r.testId}`
+  : r.kind === 'degrade' ? `degrade ${r.fingerprint} ${r.backend}`
+  : r.kind === 'final' ? `final ${r.fingerprintBefore}`
+  : r.kind === 'final-start' ? `final-start ${r.fingerprint}`
+  : null;
+
+// The authoritative subset: the LATEST record per key, in file order of that latest appearance.
+export const authoritativeEvidence = (records) => {
+  const lastByKey = new Map();
+  records.forEach((r, i) => {
+    const k = evidenceKey(r);
+    if (k != null) lastByKey.set(k, i);
+  });
+  const keep = new Set(lastByKey.values());
+  return records.filter((_, i) => keep.has(i));
+};
+
+export const authoritativeOfKind = (records, kind) => authoritativeEvidence(records).filter((r) => r.kind === kind);
+
+// Canonical bytes: key-sorted JSON per record, one line each, newline-terminated ('' when empty) —
+// independent of the byte layout the record was originally written with. The D3(a) receipt hashes
+// EXACTLY these bytes per kind, so receipts (a different kind/file) are outside the domain by
+// construction.
+const stableStringify = (v) => {
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(',')}]`;
+  if (v !== null && typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(v);
+};
+
+export const canonicalKindSerialization = (records, kind) => {
+  const lines = authoritativeOfKind(records, kind).map(stableStringify);
+  return lines.length === 0 ? '' : `${lines.join('\n')}\n`;
+};