mindforge-cc 11.9.1 → 11.9.3

package/bin/engine/verification-runner.js

@@ -7,28 +7,114 @@ const fs = require('fs');
 const MAX_OUTPUT_LENGTH = 2000;
 
 /**
- * Stage definitions — each maps a stage name to its command and optional skip condition.
- * The tests stage guards against recursion: if NODE_ENV=test (set by run-all.js) or
- * MINDFORGE_VERIFICATION_ACTIVE=1 (set by this runner), we skip to prevent infinite nesting.
+ * Detect an ESLint configuration. Flat config (eslint 9+) and the legacy .eslintrc family both
+ * count, as does an `eslintConfig` key in package.json, because `npx eslint .` succeeds with any
+ * of them and fails with none.
+ */
+function hasEslintConfig(cwd) {
+  const named = [
+    'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs',
+    'eslint.config.ts', 'eslint.config.mts', 'eslint.config.cts',
+    '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json',
+    '.eslintrc.yml', '.eslintrc.yaml',
+  ];
+  if (named.some((f) => fs.existsSync(path.join(cwd, f)))) return true;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    return Boolean(pkg.eslintConfig);
+  } catch { return false; }
+}
+
+/**
+ * Stage definitions — each maps a stage name to its command and an optional availability check.
+ *
+ * `skipIf(cwd)` returns a REASON STRING to skip, or false to run. A bare `true` still skips, for
+ * compatibility, but a reason is strongly preferred: an unexplained skip in the report is nearly as
+ * unhelpful as an unexplained failure.
+ *
+ * WHY EVERY STAGE NEEDS ONE. Only `typecheck` had an availability check, so `mindforge verify` on a
+ * freshly installed, entirely healthy consumer project reported:
+ *
+ *     | tests     | ❌ fail |
+ *     | lint      | ❌ fail |
+ *     | audit     | ❌ fail |
+ *     | typecheck | ⏭️ skip |
+ *     **Summary:** 0 passed, 3 failed, 1 skipped        exit 1
+ *
+ * Measured on `node bin/install.js --claude --local` into an empty project: 1,836 files installed,
+ * and no `tests/`, no ESLint config and no `bin/verify-audit.js` — because the installer ships none
+ * of them, which is correct. So all three stages were reporting the ABSENCE of a tool as the
+ * FAILURE of the thing it would have checked. The audit stage's "result" was a raw Node module
+ * loader stack trace.
+ *
+ * "I cannot check this here" and "this is broken" are opposite statements, and a verifier that
+ * conflates them is worse than one that runs nothing: it trains its user to ignore red.
+ *
+ * The recursion guard on `tests` is unchanged and separate — NODE_ENV=test is set by run-all.js and
+ * MINDFORGE_VERIFICATION_ACTIVE=1 by this runner, and skipping prevents infinite nesting.
  */
 const STAGE_DEFS = {
   tests: {
     command: 'node tests/run-all.js',
-    skipIf: () =>
-      process.env.MINDFORGE_VERIFICATION_ACTIVE === '1' ||
-      process.env.NODE_ENV === 'test',
+    skipIf: (cwd) => {
+      if (process.env.MINDFORGE_VERIFICATION_ACTIVE === '1' || process.env.NODE_ENV === 'test') {
+        return 'already inside a verification run (recursion guard)';
+      }
+      if (!fs.existsSync(path.join(cwd, 'tests', 'run-all.js'))) {
+        return 'no tests/run-all.js here — the package does not install a test suite';
+      }
+      return false;
+    },
   },
   lint: {
-    command: 'npx eslint . --max-warnings=0',
-    skipIf: null,
+    // `--max-warnings=0` used to be here, which made this stage IMPOSSIBLE to pass in the repo it
+    // ships from: measured, `npx eslint .` reports 199 problems / 0 errors / 199 warnings. So
+    // `mindforge verify` reported a lint FAILURE on a tree whose lint is green by the project's own
+    // definition — a confidently wrong answer, which is worse than no answer.
+    //
+    // Aligned with the project's own contract rather than a stricter threshold invented here:
+    //   package.json  "lint": "eslint ."                      (warnings tolerated)
+    //   CI            eslint . --max-warnings=9999            (warnings tolerated)
+    //   sdk CI        eslint src/ --max-warnings 0            (strict, but only over sdk/src)
+    // Two of the three tolerate warnings and the third is scoped to a different tree, so a
+    // repo-wide zero-warning gate was this file's opinion alone. Errors still fail the stage,
+    // because eslint exits non-zero on an error regardless of the warning threshold.
+    command: 'npx eslint .',
+    skipIf: (cwd) => (hasEslintConfig(cwd)
+      ? false
+      : 'no ESLint configuration here — nothing defines what lint means for this project'),
   },
   audit: {
     command: 'node bin/verify-audit.js',
-    skipIf: null,
+    // BOTH the verifier AND the log — and the comment that used to sit here asserted the opposite of
+    // measured behaviour, which is how the remaining gap survived review.
+    //
+    // It claimed "an absent AUDIT.jsonl is a legitimate empty chain that verify-audit.js reports on
+    // correctly". Measured in an empty project: `node bin/verify-audit.js` prints
+    // "❌ audit chain BROKEN at entry 0: unreadable: ENOENT: no such file or directory" and exits 1.
+    // It does not report an empty chain, it reports corruption. So wherever the script IS present and
+    // the log is not — a --with-utils install, a fresh checkout — this stage still produced a red for
+    // a project that has simply never written an audit entry. That is the same
+    // absence-reported-as-failure defect the rest of this change exists to remove.
+    //
+    // The script being missing is the state of every ordinary consumer install (the installer does not
+    // copy bin/verify-audit.js), and there the stage died in Node's module loader and printed the
+    // stack trace as its verification result.
+    skipIf: (cwd) => {
+      if (!fs.existsSync(path.join(cwd, 'bin', 'verify-audit.js'))) {
+        return 'bin/verify-audit.js is not installed here, so the audit chain cannot be verified';
+      }
+      if (!fs.existsSync(path.join(cwd, '.planning', 'AUDIT.jsonl'))) {
+        return 'no .planning/AUDIT.jsonl yet — nothing has been audited, which is not a broken chain';
+      }
+      return false;
+    },
   },
   typecheck: {
     command: 'npx tsc --noEmit',
-    skipIf: (cwd) => !fs.existsSync(path.join(cwd, 'tsconfig.json')),
+    skipIf: (cwd) => (fs.existsSync(path.join(cwd, 'tsconfig.json'))
+      ? false
+      : 'no tsconfig.json here — nothing to typecheck'),
   },
 };
 
@@ -41,9 +127,18 @@ function executeStage(name, cwd) {
     return { name, status: 'skip', durationMs: 0, output: `Unknown stage: ${name}` };
   }
 
-  // Check skip condition
-  if (def.skipIf && def.skipIf(cwd)) {
-    return { name, status: 'skip', durationMs: 0, output: '' };
+  // Check availability / skip condition. A reason string is carried through to the report, because
+  // an unexplained skip leaves the reader unable to tell "not applicable here" from "silently
+  // broken" — the same ambiguity that conflating absence with failure created.
+  const skip = def.skipIf && def.skipIf(cwd);
+  if (skip) {
+    return {
+      name,
+      status: 'skip',
+      durationMs: 0,
+      output: typeof skip === 'string' ? skip : '',
+      reason: typeof skip === 'string' ? skip : undefined,
+    };
   }
 
   const start = Date.now();
@@ -112,20 +207,42 @@ function formatReport(result) {
   lines.push('');
   lines.push(`**Timestamp:** ${result.timestamp}`);
   lines.push('');
-  lines.push('| Stage | Status | Duration |');
-  lines.push('|-------|--------|----------|');
+  lines.push('| Stage | Status | Duration | Note |');
+  lines.push('|-------|--------|----------|------|');
 
   for (const stage of result.stages) {
     const emoji = statusEmoji[stage.status] || '?';
     const duration = stage.durationMs > 0 ? `${stage.durationMs}ms` : '-';
-    lines.push(`| ${stage.name} | ${emoji} ${stage.status} | ${duration} |`);
+    // A skip without its reason is unreadable: this table used to show a bare `⏭️ skip` and left the
+    // reader to guess whether the stage was inapplicable or quietly broken. Pipes are escaped so a
+    // reason can never break the markdown table.
+    const note = stage.status === 'skip' && stage.reason
+      ? String(stage.reason).replace(/\|/g, '\\|')
+      : '';
+    lines.push(`| ${stage.name} | ${emoji} ${stage.status} | ${duration} | ${note} |`);
   }
 
   lines.push('');
   lines.push(`**Summary:** ${result.summary.passed} passed, ${result.summary.failed} failed, ${result.summary.skipped} skipped (${result.summary.totalDurationMs}ms total)`);
+
+  // Say it outright when NOTHING ran. Adding availability checks fixed the false failures, but it
+  // moved a consumer install from "3 failed, exit 1" to "0 failed, exit 0" — and bin/engine/
+  // verify-cli.js exits on `failed > 0`, so a script reading $? now sees success for a run that
+  // verified nothing. Whether an all-skipped run should exit non-zero is an open maintainer
+  // decision and is deliberately NOT pre-empted here; what is not optional is that the report
+  // refuses to look like a pass.
+  if (result.summary.passed === 0 && result.summary.failed === 0 && result.summary.skipped > 0) {
+    lines.push('');
+    lines.push('> **NOTHING WAS VERIFIED.** Every stage was skipped, so this report is not '
+      + 'evidence that anything works — see the Note column for what was unavailable. A verifier '
+      + 'that ran no checks must not be read as a passing verifier.');
+  }
   lines.push('');
 
   return lines.join('\n');
 }
 
-module.exports = { runVerification, formatReport };
+// STAGE_DEFS is exported so a test can compare the lint stage's threshold against the project's own
+// lint script rather than hardcoding what it expects to find. Read-only by contract: mutating it
+// would change every subsequent run in the same process.
+module.exports = { runVerification, formatReport, STAGE_DEFS };

package/bin/engine/verify-cli.js

@@ -3,8 +3,19 @@
 
 /**
  * verify-cli.js — Entrypoint for the `verify` CLI command.
- * Calls the unified verification runner across all stages and writes
- * the formatted report to .planning/VERIFICATION.md.
+ * Calls the unified verification runner across all stages, prints the formatted report, and writes it
+ * to .planning/VERIFICATION.md only when asked with --write.
+ *
+ * WHY --write RATHER THAN ALWAYS. `.planning/VERIFICATION.md` is TRACKED (`git ls-files` returns it),
+ * and this file used to overwrite it on every run — so a contributor who ran the project's own
+ * verification dirtied a tracked file and had to remember to discard it. Nothing reads the root
+ * report: the only other reference is tests/e2e.test.js:399, and that reads
+ * `.planning/phases/1/VERIFICATION-1.md`, a per-phase fixture in a generated project, not this file.
+ * The report was already printed to stdout, so gating the file loses no information.
+ *
+ * Untracking the file is the other half and belongs to the operator (`git rm --cached` plus a
+ * .gitignore entry). This change is correct either way: with the file untracked, --write becomes a
+ * convenience; while it stays tracked, --write is what stops the dirtying.
  */
 
 const path = require('path');
@@ -13,17 +24,24 @@ const { runVerification, formatReport } = require('./verification-runner');
 
 const STAGES = ['tests', 'lint', 'audit', 'typecheck'];
 const CWD = process.env.MINDFORGE_ROOT || path.resolve(__dirname, '../..');
+const REPORT_NAME = 'VERIFICATION.md';
 
 async function main() {
-  const planningDir = path.join(CWD, '.planning');
-  if (!fs.existsSync(planningDir)) {
-    fs.mkdirSync(planningDir, { recursive: true });
-  }
+  const shouldWrite = process.argv.slice(2).includes('--write');
 
   const result = await runVerification({ cwd: CWD, stages: STAGES });
   const report = formatReport(result);
 
-  fs.writeFileSync(path.join(planningDir, 'VERIFICATION.md'), report);
+  if (shouldWrite) {
+    const planningDir = path.join(CWD, '.planning');
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+    const reportPath = path.join(planningDir, REPORT_NAME);
+    fs.writeFileSync(reportPath, report);
+    process.stdout.write(`Report written to ${reportPath}\n`);
+  }
+
   process.stdout.write(report + '\n');
   process.exit(result.summary.failed > 0 ? 1 : 0);
 }

package/bin/eval/eval-harness.js

@@ -1,5 +1,16 @@
 'use strict';
 
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Repo root derived from THIS file's location, never from cwd.
+// bin/utils/paths.js resolves PROJECT_ROOT by walking up from process.cwd(),
+// which on a consumer install lands inside node_modules — the wrong root for a
+// corpus scan, and it would silently yield an empty corpus. __dirname is always
+// <root>/bin/eval.
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
 /**
  * Recall@K — fraction of relevant items found in the top-k retrieved results.
  * @param {string[]} retrieved - IDs in ranked order
@@ -79,4 +90,204 @@ async function runEval({ goldenSet, retriever, k }) {
   return { meanRecallAtK, meanNDCG, perQuery };
 }
 
-module.exports = { recallAtK, ndcg, runEval };
+// ── Corpus + runnable golden-set gate (FTS-01) ───────────────────────────────
+// Before this block the file had NO require.main guard, so the documented
+// command `node bin/eval/eval-harness.js --set golden-set-retrieval.json`
+// printed nothing and exited 0 — a gate that could not fail, and therefore not
+// a gate. golden-set-retrieval.json and this harness had zero callers.
+//
+// The shipped golden set names documents by BASENAME (`audit-hash`,
+// `model-router`, `stuck-detector`, …). Those ids exist nowhere in
+// .mindforge/celestial.db, so recall measured against the live trace DB is 0.00
+// by construction whatever the query builder does. The corpus the golden set
+// actually describes is the repo's own module/skill documentation — so build it,
+// index it into a THROWAWAY database under os.tmpdir(), and measure that.
+
+const CORPUS_ROOTS = [
+  { dir: 'bin', exts: ['.js'] },
+  { dir: '.mindforge/skills', exts: ['.md'] },
+  { dir: '.mindforge/engine', exts: ['.md'] },
+  { dir: '.agent/hooks', exts: ['.js'] },
+];
+const CORPUS_MAX_BYTES = 20000;
+const CORPUS_SKIP_DIRS = new Set(['node_modules', 'dist', 'coverage']);
+
+function _walk(dir, exts, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // a missing corpus root is reported via corpusSize, not a throw
+  }
+  for (const entry of entries) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!CORPUS_SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+        _walk(p, exts, out);
+      }
+    } else if (exts.includes(path.extname(entry.name))) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Doc id for a corpus file: its basename, except SKILL.md, which is keyed by its
+ * containing skill directory (that is the name the golden set uses).
+ * @param {string} file - absolute or relative file path
+ * @returns {string} document id
+ */
+function docIdForFile(file) {
+  const base = path.basename(file, path.extname(file));
+  return base === 'SKILL' ? path.basename(path.dirname(file)) : base;
+}
+
+/**
+ * Enumerate the document corpus the golden set's `relevant` ids refer to.
+ * @param {string} [root] - project root; defaults to REPO_ROOT
+ * @returns {Map<string, {id: string, file: string, content: string}>}
+ */
+function buildDocCorpus(root = REPO_ROOT) {
+  const corpus = new Map();
+  for (const { dir, exts } of CORPUS_ROOTS) {
+    for (const file of _walk(path.join(root, dir), exts, [])) {
+      const id = docIdForFile(file);
+      if (corpus.has(id)) continue; // first wins; basename collisions are rare
+      let text = '';
+      try {
+        text = fs.readFileSync(file, 'utf8').slice(0, CORPUS_MAX_BYTES);
+      } catch {
+        continue;
+      }
+      const rel = path.relative(root, file);
+      corpus.set(id, { id, file: rel, content: `${id} ${rel}\n${text}` });
+    }
+  }
+  return corpus;
+}
+
+/**
+ * Index the doc corpus into a throwaway VectorHub and score the golden set.
+ * NEVER touches .mindforge/celestial.db — the database lives in os.tmpdir() and
+ * is deleted again before this resolves.
+ * @param {Object} [opts]
+ * @param {string} [opts.goldenSetPath] - defaults to ./golden-set-retrieval.json
+ * @param {string} [opts.root] - corpus root; defaults to REPO_ROOT
+ * @param {number} [opts.k] - cutoff; defaults to 10
+ * @returns {Promise<Object>} runEval metrics plus corpus/coverage diagnostics
+ */
+async function runGoldenSetEval(opts = {}) {
+  const goldenSetPath = opts.goldenSetPath || path.join(__dirname, 'golden-set-retrieval.json');
+  const root = opts.root || REPO_ROOT;
+  const k = opts.k || 10;
+
+  const golden = JSON.parse(fs.readFileSync(goldenSetPath, 'utf8'));
+  const goldenSet = golden.queries || [];
+  const corpus = buildDocCorpus(root);
+
+  const relevantIds = [...new Set(goldenSet.flatMap(q => q.relevant || []))];
+  const unresolved = relevantIds.filter(id => !corpus.has(id));
+
+  const { VectorHub } = require('../memory/vector-hub');
+  const dbDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mindforge-eval-'));
+  const hub = new VectorHub(path.join(dbDir, 'eval-corpus.db'));
+  await hub.init();
+  try {
+    // The hub is throwaway, so raise the autosave batch size: the default of 10
+    // exports the whole growing database to disk every 10 documents, which turns
+    // a 0.5 s index build into a quadratic one for no durability benefit here.
+    hub._batchSize = Number.MAX_SAFE_INTEGER;
+    for (const doc of corpus.values()) {
+      await hub.saveKnowledge({ id: doc.id, type: 'doc', content: doc.content, source: doc.file });
+    }
+    const retriever = async (query) =>
+      (await hub.searchKnowledge(query, { limit: k })).map(r => r.id);
+    const metrics = await runEval({ goldenSet, retriever, k });
+    return {
+      ...metrics,
+      k,
+      corpusSize: corpus.size,
+      relevantIdCount: relevantIds.length,
+      unresolvedRelevantIds: unresolved,
+      baseline: golden.baseline || null,
+    };
+  } finally {
+    await hub.close();
+    fs.rmSync(dbDir, { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  recallAtK,
+  ndcg,
+  runEval,
+  buildDocCorpus,
+  docIdForFile,
+  runGoldenSetEval,
+};
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+// node bin/eval/eval-harness.js [--set golden-set-retrieval.json] [--k 10]
+//                               [--min-recall 0.55] [--json]
+// Exits 1 when mean recall@k is below --min-recall, or when any golden
+// `relevant` id no longer resolves to a real document (golden-set drift).
+// `npm run eval:retrieval` runs this with the committed baseline floor.
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const flag = (name, fallback) => {
+    const i = argv.indexOf(name);
+    return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : fallback;
+  };
+  const setArg = flag('--set', 'golden-set-retrieval.json');
+  const goldenSetPath = path.isAbsolute(setArg)
+    ? setArg
+    : path.join(__dirname, path.basename(setArg));
+  const num = (name, fallback) => {
+    const raw = flag(name, String(fallback));
+    const n = Number(raw);
+    // Fail closed: an unparseable threshold must never silently become 0.
+    if (!Number.isFinite(n) || n < 0) {
+      console.error(`[eval] ERROR: ${name} must be a non-negative number, got ${JSON.stringify(raw)}`);
+      process.exit(1);
+    }
+    return n;
+  };
+  const k = Math.max(1, Math.trunc(num('--k', 10)));
+  const minRecall = num('--min-recall', 0);
+
+  runGoldenSetEval({ goldenSetPath, k })
+    .then((res) => {
+      if (argv.includes('--json')) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`[eval] corpus: ${res.corpusSize} docs · golden queries: ${res.perQuery.length} · k=${res.k}`);
+        for (const q of res.perQuery) {
+          console.log(`  recall=${q.recall.toFixed(3)} nDCG=${q.ndcg.toFixed(3)} hits=${q.retrieved.length}  ${q.query}`);
+        }
+        console.log(`[eval] mean recall@${res.k} = ${res.meanRecallAtK.toFixed(4)}`);
+        console.log(`[eval] mean nDCG@${res.k}   = ${res.meanNDCG.toFixed(4)}`);
+        if (res.baseline && typeof res.baseline.meanRecallAtK === 'number') {
+          // Round BEFORE choosing the sign, so a difference smaller than the
+          // printed precision reads as +0.0000 rather than a bogus -0.0000.
+          const delta = Number((res.meanRecallAtK - res.baseline.meanRecallAtK).toFixed(4));
+          console.log(`[eval] committed baseline recall@${res.baseline.k || res.k} = ${res.baseline.meanRecallAtK.toFixed(4)} (delta ${delta >= 0 ? '+' : ''}${delta.toFixed(4)})`);
+        }
+      }
+      if (res.unresolvedRelevantIds.length > 0) {
+        console.error(`[eval] FAIL: ${res.unresolvedRelevantIds.length} golden id(s) no longer resolve to a document: ${res.unresolvedRelevantIds.join(', ')}`);
+        process.exit(1);
+      }
+      if (res.meanRecallAtK < minRecall) {
+        console.error(`[eval] FAIL: mean recall@${res.k} ${res.meanRecallAtK.toFixed(4)} < --min-recall ${minRecall}`);
+        process.exit(1);
+      }
+    })
+    .catch((err) => {
+      // sql.js throws bare strings for some binding errors, so an Error-shaped
+      // formatter alone would print "undefined" and hide the real failure.
+      const detail = (err && (err.stack || err.message)) || String(err);
+      console.error(`[eval] ERROR: ${detail}`);
+      process.exit(1);
+    });
+}

package/bin/eval/golden-set-retrieval.json

@@ -1,6 +1,15 @@
 {
   "description": "Golden set for retrieval quality evaluation. Each entry has a natural-language query and the IDs of documents that SHOULD be retrieved.",
   "version": "1.0.0",
+  "baseline": {
+    "note": "Committed measurement so a retrieval regression is detectable. Reproduce with `npm run eval:retrieval`. Corpus = repo docs enumerated by buildDocCorpus() in bin/eval/eval-harness.js; retriever = VectorHub.searchKnowledge (OR-joined terms, ranked by tf-idf over FTS4 matchinfo('pcnx')). Before FTS-01 both figures were 0.0000 because the whole query was one FTS phrase.",
+    "k": 10,
+    "meanRecallAtK": 0.6417,
+    "meanNDCG": 0.5698,
+    "corpusSize": 517,
+    "gateMinRecall": 0.55,
+    "measuredOn": "v11.9.2 (fix/v11.9.2-ship-blockers), sql.js 1.14.1 / SQLite 3.49.1"
+  },
   "queries": [
     {
       "query": "how does the audit hash chain work",

package/bin/governance/approval-record.js

@@ -0,0 +1,147 @@
+'use strict';
+/**
+ * Canonical approval-record integrity, shared by the writer and every verifier.
+ *
+ * WHY THIS EXISTS — what the old record actually proved: nothing.
+ *
+ * bin/governance/approve.js stamped
+ *     signature = sha256(`${id}:${reason}:${timestamp}:${os.hostname()}`)
+ * and called it a signature. Three problems, all measured:
+ *
+ *   1. It is NOT a signature. Nothing signs it; there is no key and no asymmetry. Anyone who
+ *      can write the file can compute the value.
+ *   2. It is UNVERIFIABLE by design. `os.hostname()` is part of the preimage but is NOT a field
+ *      of the record, so a verifier holding the record cannot reproduce the digest. CI never
+ *      could have checked it.
+ *   3. Nothing checked it anyway. control-plane.yml asserted `!rec.signature` — presence only.
+ *
+ * So the field was simultaneously misnamed, uncheckable and unchecked. It is replaced by
+ * `record_checksum`: a plain SHA-256 over the record's OWN canonical fields, which any holder
+ * can recompute. That makes it a real tamper-check on the record's contents — and nothing more,
+ * which is why it is not called a signature.
+ *
+ * WHAT THIS DOES NOT PROVIDE. A checksum over a git-tracked file is an INTEGRITY control, never
+ * an AUTHORIZATION one: anyone with push access can mint a fresh record with a valid checksum.
+ * Authorization on this repo comes from branch protection (a required PR plus required status
+ * checks on main and develop), not from a file. Verified live before this was written:
+ * `branches/{main,develop}/protection` returned 404 and `rulesets` was empty, so for the whole
+ * period this record format existed there was no enforcement layer of any kind behind it.
+ *
+ * The construction deliberately mirrors bin/governance/audit-hash.js — twelve lines, one
+ * function, used by writer and verifier alike. That module's discipline ("MUST be the single
+ * source of truth for both") is exactly what kept the audit chain honest while this record rotted,
+ * so it is copied rather than reinvented.
+ */
+
+const crypto = require('crypto');
+
+/** Field written last and excluded from its own digest. */
+const CHECKSUM_FIELD = 'record_checksum';
+
+/** Current record schema. A record without it is a pre-v2 record and is not accepted. */
+const SCHEMA = 'mindforge.approval/v2';
+
+/** How long a recorded acknowledgement stays current. */
+const TTL_HOURS = 72;
+
+/**
+ * SHA-256 over the record's own fields, with the checksum field removed.
+ *
+ * Determinism note: like audit-hash.js this relies on JSON.stringify emitting keys in insertion
+ * order, which is why writer and verifier MUST both go through this function. A verifier that
+ * rebuilt the object literal in a different order would compute a different digest and reject
+ * every valid record — so do not inline this construction anywhere, including in YAML.
+ *
+ * @param {object} record
+ * @returns {string} `sha256:<hex>`
+ */
+function checksumRecord(record) {
+  const material = { ...record };
+  delete material[CHECKSUM_FIELD];
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(material)).digest('hex')}`;
+}
+
+/** ISO timestamp `hours` after `fromIso`. */
+function expiryFrom(fromIso, hours = TTL_HOURS) {
+  return new Date(new Date(fromIso).getTime() + hours * 3600 * 1000).toISOString();
+}
+
+const REQUIRED_FIELDS = ['schema', 'id', 'project', 'version', 'tier', 'approved_by', 'timestamp', 'expires_at', 'reason', 'identity_verification'];
+
+/**
+ * Check one approval record's integrity and currency.
+ *
+ * This answers "is this record intact, and is it about the release being built?" It does NOT
+ * answer "was this change authorized" — see the header.
+ *
+ * The currency checks are the ones that matter in practice. A record with no expiry and no
+ * version binding satisfied the old gate in perpetuity: the committed approval was minted
+ * 2026-06-11 for version 11.5.1 and was still accepted 67 days and 286 commits later, against
+ * 11.9.2, because the gate read only the directory's contents.
+ *
+ * @param {object} record
+ * @param {{currentVersion:string, now?:Date}} ctx
+ * @returns {{ok:boolean, problems:string[], stale:boolean}}
+ */
+function verifyRecord(record, ctx) {
+  const problems = [];
+  let stale = false;
+
+  if (!record || typeof record !== 'object') {
+    return { ok: false, problems: ['record is not a JSON object'], stale: false };
+  }
+
+  if (record.schema !== SCHEMA) {
+    problems.push(
+      record.signature && !record.schema
+        ? 'pre-v2 record (has the removed `signature` field, no `schema`). Its digest included ' +
+          'os.hostname(), which is not a field of the record, so it can never be verified. Re-mint it.'
+        : `unknown schema ${JSON.stringify(record.schema)} — expected ${SCHEMA}`);
+  }
+
+  for (const f of REQUIRED_FIELDS) {
+    if (record[f] === undefined || record[f] === null || record[f] === '') {
+      problems.push(`missing required field \`${f}\``);
+    }
+  }
+
+  if (record[CHECKSUM_FIELD]) {
+    const expected = checksumRecord(record);
+    if (record[CHECKSUM_FIELD] !== expected) {
+      problems.push(`${CHECKSUM_FIELD} does not match the record contents — it has been edited since minting`);
+    }
+  } else {
+    problems.push(`missing \`${CHECKSUM_FIELD}\``);
+  }
+
+  const iv = record.identity_verification;
+  const isVerified = iv && iv.verified === true;
+  const isAckedUnverified = iv && iv.verified === false
+    && iv.method === 'git_identity_unverified' && iv.unverified_ack === true;
+  if (!isVerified && !isAckedUnverified) {
+    problems.push('identity is neither GPG-verified nor an explicitly acknowledged unverified ' +
+      'approval (verified:false + method git_identity_unverified + unverified_ack:true)');
+  }
+
+  // Currency. Reported separately from malformedness because a stale record is a correctly-made
+  // record that has simply stopped applying — a different thing from a corrupt one.
+  if (record.version && ctx.currentVersion && record.version !== ctx.currentVersion) {
+    stale = true;
+    problems.push(`records version ${record.version} but the build is ${ctx.currentVersion} — ` +
+      'an approval does not carry forward to a later release');
+  }
+  const now = ctx.now || new Date();
+  if (record.expires_at) {
+    const exp = new Date(record.expires_at);
+    if (Number.isNaN(exp.getTime())) problems.push(`expires_at is not a valid date: ${record.expires_at}`);
+    else if (exp <= now) {
+      stale = true;
+      const ageH = Math.round((now - exp) / 3600000);
+      problems.push(`expired ${ageH}h ago (expires_at ${record.expires_at})`);
+    }
+  }
+
+  return { ok: problems.length === 0, problems, stale };
+}
+
+module.exports = { checksumRecord, verifyRecord, expiryFrom, CHECKSUM_FIELD, SCHEMA, TTL_HOURS, REQUIRED_FIELDS };