cadet-agent 0.34.0 → 0.36.0

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "cadet-agent",
-  "version": "0.34.0",
-  "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
-  "type": "module",
-  "bin": {
-    "cadet-agent": "bin/cli.mjs"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "lint": "lychee --offline --include-fragments \"**/*.md\"",
-    "verify": "npm test && npm run lint"
-  },
-  "files": [
-    "bin/",
-    "src/"
-  ],
-  "keywords": [
-    "cadet",
-    "cadet-agent",
-    "unity",
-    "game-development",
-    "ai-agent",
-    "copilot",
-    "cursor",
-    "claude-code"
-  ],
-  "license": "CC-BY-4.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/naishtech/cadet-agent.git"
-  },
-  "homepage": "https://github.com/naishtech/cadet-agent#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "cadet-agent",
+  "version": "0.36.0",
+  "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
+  "type": "module",
+  "bin": {
+    "cadet-agent": "bin/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "lint": "lychee --offline --include-fragments \"**/*.md\"",
+    "verify": "npm test && npm run lint"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "cadet",
+    "cadet-agent",
+    "unity",
+    "game-development",
+    "ai-agent",
+    "copilot",
+    "cursor",
+    "claude-code"
+  ],
+  "license": "CC-BY-4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naishtech/cadet-agent.git"
+  },
+  "homepage": "https://github.com/naishtech/cadet-agent#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { install, sync } from './install.mjs';
 import {
   validateState, migrateStateFile, readState, writeState, evaluateTransition, applyTransition,
@@ -9,6 +9,7 @@ import {
   detectRepoRole, describeRepoRole, GATES, manualConfirmation,
   parseTestInventory, parseStoryCriteria, compareCoverage, describeCoverageGaps,
   createEvidence, newId, computeInputTreeHash, hashCriteria,
+  collectDeclaredTestNames, reconcileTestNames,
 } from './harness/index.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -90,9 +91,17 @@ function parseArgs(argv) {
       case '--environment': opts.environment = argv[++i]; break;
       case '--scope': opts.scope = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
       case '--evidence-status': opts.evidenceStatus = argv[++i]; break;
-      case '--files': opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
+      // Track that the flag was supplied even when its value is empty, so an
+      // empty `--files ""` is rejected rather than silently falling back to the
+      // working-tree scan (which could bind evidence to Cadet's own files).
+      case '--files': opts.filesGiven = true; opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
       case '--story': opts.story = argv[++i]; break;
       case '--report': opts.report = argv[++i]; break;
+      // AR-1: the revision a gate record attests, so a gate-related fix claim
+      // can be traced to the commit that contains it.
+      case '--commit': opts.commitGiven = true; opts.commit = argv[++i]; break;
+      case '--matrix': opts.matrix = argv[++i]; break;
+      case '--inventory': opts.inventory = argv[++i]; break;
       case '--write-coverage': opts.writeCoverage = true; break;
       case '--strict-orphans': opts.strictOrphans = true; break;
       case '--dry-run': opts.dryRun = true; break;
@@ -320,6 +329,9 @@ async function cmdHarness(opts) {
     // Freshness binding mirrors `harness verify`: never record a gate against an
     // unknown input tree unless the repository explicitly opted out.
     const allowEmpty = policy?.allowEmptyFreshness === true;
+    if (opts.filesGiven && (!opts.files || opts.files.length === 0)) {
+      fail(opts, '--files was given with no paths. Pass a comma-separated list of the files this gate covers (e.g. --files src/Foo.cs,test/FooTests.cs), or omit --files to auto-detect changed files.', () => 1, { ok: false, gate, code: 'empty-files' });
+    }
     let relevantFiles;
     if (opts.files && opts.files.length) {
       relevantFiles = opts.files.map((f) => f.replace(/\\/g, '/'));
@@ -355,6 +367,7 @@ async function cmdHarness(opts) {
       relevantFiles,
       rootDir: opts.targetDir,
       approvedBy: opts.approvedBy || 'user',
+      commit: opts.commit || null,
       at,
     });
 
@@ -459,6 +472,9 @@ async function cmdHarness(opts) {
     const allowEmpty = policy?.allowEmptyFreshness === true;
     let relevantFiles;
     let filesSource;
+    if (opts.filesGiven && (!opts.files || opts.files.length === 0)) {
+      fail(opts, '--files was given with no paths. Pass a comma-separated list of the files this gate covers (e.g. --files src/Foo.cs,test/FooTests.cs), or omit --files to auto-detect changed files.', () => 1, { ok: false, gate, code: 'empty-files' });
+    }
     if (opts.files && opts.files.length) {
       relevantFiles = opts.files.map((f) => f.replace(/\\/g, '/'));
       filesSource = 'explicit';
@@ -517,6 +533,7 @@ async function cmdHarness(opts) {
       phase: ledger.phase || 'implementation',
       relevantFiles,
       rootDir: opts.targetDir,
+      commit: opts.commit || null,
       policy,
       budgets: ledger.tracker,
       artifactDir: join(runsDir(opts.targetDir), 'artifacts'),
@@ -755,6 +772,95 @@ async function cmdHarness(opts) {
     return;
   }
 
+  // AR-5. Reconcile a TDD matrix's DELIVERED test-name claims against a compiled
+  // inventory. Read-only: it reports, and never writes state, so it can be run at
+  // authoring time (before anything has been implemented) as well as in a gate.
+  if (sub === 'matrix-check') {
+    if (!opts.matrix) fail(opts, 'harness matrix-check requires --matrix <path-to-matrix.md>');
+    const matrixPath = resolve(opts.targetDir, opts.matrix);
+    let matrixText;
+    try {
+      matrixText = readFileSync(matrixPath, 'utf-8');
+    } catch (err) {
+      fail(opts, `cannot read matrix ${opts.matrix}: ${err.message}`, () => 2);
+    }
+
+    // The inventory may come from a run report (strongest: it proves the test
+    // RAN) or from C# sources (a name inventory only). Prefer a report.
+    let inventory = null;
+    let inventorySource = null;
+    if (opts.report) {
+      const reportPath = resolve(opts.targetDir, opts.report);
+      let reportText;
+      try {
+        reportText = readFileSync(reportPath, 'utf-8');
+      } catch (err) {
+        fail(opts, `cannot read report ${opts.report}: ${err.message}`, () => 2);
+      }
+      const parsed = parseTestInventory(reportText);
+      if (parsed && parsed.format !== 'unknown' && parsed.names.length > 0) {
+        inventory = new Set(parsed.names);
+        inventorySource = `${opts.report} (${parsed.format})`;
+      }
+    }
+    if (!inventory && opts.inventory) {
+      const invPath = resolve(opts.targetDir, opts.inventory);
+      let raw;
+      try {
+        raw = readFileSync(invPath, 'utf-8');
+      } catch (err) {
+        fail(opts, `cannot read inventory ${opts.inventory}: ${err.message}`, () => 2);
+      }
+      inventory = new Set(String(raw).split(/\r?\n/).map((s) => s.trim()).filter(Boolean));
+      inventorySource = opts.inventory;
+    }
+
+    const collected = collectDeclaredTestNames(matrixText);
+    if (!inventory) {
+      // Without an inventory this cannot prove anything, so it must not report
+      // success. Returning the collected names is still useful at authoring time:
+      // it shows what the matrix claims, and the caller can spot a name they know
+      // they never wrote.
+      const detail = {
+        ok: false,
+        code: 'inventory-unavailable',
+        matrix: opts.matrix,
+        claims: collected.claims,
+        intents: collected.intents,
+      };
+      if (opts.format === 'json') emit(opts, '', detail);
+      else {
+        console.error('❌ No inventory supplied, so no claim can be checked. Pass --report <test-results> (preferred, proves the test ran) or --inventory <names.txt>.');
+        console.error(`   The matrix declares ${collected.claims.length} delivered claim(s) across ${collected.intents.length} undelivered intention(s).`);
+      }
+      process.exit(1);
+    }
+
+    const result = reconcileTestNames(collected, inventory);
+    const ok = result.missingFromInventory.length === 0;
+    const detail = {
+      ok,
+      matrix: opts.matrix,
+      inventory: inventorySource,
+      checked: result.checked,
+      intents: collected.intents.length,
+      missingFromInventory: result.missingFromInventory,
+      unmatchedIntents: result.unmatchedIntents,
+    };
+    if (opts.format === 'json') emit(opts, '', detail);
+    else if (ok) {
+      console.log(`✅ Every delivered test-name claim exists in the inventory (${result.checked} checked from ${inventorySource}).`);
+      if (result.unmatchedIntents.length > 0) {
+        console.log(`   ℹ️  ${result.unmatchedIntents.length} undelivered intention(s) now exist and the row may be stale — consider marking it DELIVERED.`);
+      }
+    } else {
+      console.error(`❌ ${result.missingFromInventory.length} delivered test-name claim(s) do not exist in the inventory (${inventorySource}):`);
+      for (const n of result.missingFromInventory) console.error(`   "${n}" — declared as delivered but absent. Attach it to the criterion it proves, or correct the name.`);
+    }
+    if (!ok) process.exit(1);
+    return;
+  }
+
   if (sub === 'cleanup') {
     const { deleted, kept } = cleanupRuns(opts.targetDir, policy, {
       olderThanMs: Number.isFinite(opts.olderThanMs) ? opts.olderThanMs : null,
@@ -763,7 +869,7 @@ async function cmdHarness(opts) {
     return;
   }
 
-  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|report|cleanup|capabilities.`);
+  fail(opts, `Unknown harness subcommand: ${sub || '(none)'}. Use record|confirm|verify|verify-acs|matrix-check|report|cleanup|capabilities.`);
 }
 
 export async function run(argv) {

package/src/harness/index.mjs

@@ -69,3 +69,7 @@ export {
   normalizeTestName, parseTestInventory, parseStoryCriteria, parseStoryCriteriaText,
   compareCoverage, describeCoverageGaps,
 } from './verify-acs.mjs';
+
+export {
+  collectDeclaredTestNames, reconcileTestNames, inventoryFromCSharpSources,
+} from './matrix-check.mjs';

package/src/harness/matrix-check.mjs

@@ -0,0 +1,122 @@
+// AR-5 — mechanical reconciliation of a TDD matrix's test-name claims against a
+// compiled test inventory.
+//
+// THE DEFECT THIS EXISTS TO REMOVE. A TDD matrix row names the tests that prove
+// an acceptance criterion. Those rows are authored during architecture, BEFORE
+// implementation, so a name can be an intention that changes (or never happens)
+// while nothing re-checks the row. In one real project this produced the SAME
+// phantom-test-name defect three times, and all three were found late — by the
+// validation gate, two stories after the claim was written. A name that does not
+// exist reads as proof and is not.
+//
+// THE TWO DIRECTIONS, AND WHY THE DISTINCTION MATTERS.
+//
+//   DELIVERED rows   carry a claim: "these tests exist and prove this criterion".
+//                    A name here that is absent from the inventory is a DEFECT.
+//   undelivered rows carry an intention for planned work. A name here that is
+//                    absent is EXPECTED and must NOT be reported.
+//
+// Collapsing the two produces false failures, and a false failure is how a real
+// check gets switched off. This module keeps them separate and makes the
+// separation the caller's explicit choice.
+//
+// Deliberately dependency-free and side-effect-free: it returns findings and
+// never throws on content, so it can run at authoring time as well as in a gate.
+
+/** Marker that separates a row's claims from its explanatory prose. */
+const DELIVERED_MARKER = 'DELIVERED';
+
+/**
+ * A test name is `Identifier_LikeThis` — at least one underscore, both sides
+ * identifier-shaped. This deliberately rejects prose symbols that appear in
+ * backticks (type names such as `ViewExtent`, single letters such as `u`), which
+ * is the specific false-positive class that made an earlier checker unusable.
+ */
+const TEST_NAME = /^[A-Za-z][A-Za-z0-9]*_[A-Za-z0-9_]+$/;
+
+/** Extract every backticked token that looks like a test name. */
+function backtickedTestNames(text) {
+  const out = [];
+  for (const m of String(text).matchAll(/`([^`]+)`/g)) {
+    const name = m[1].trim();
+    if (TEST_NAME.test(name)) out.push(name);
+  }
+  return out;
+}
+
+/** Split a markdown table row into its cells (leading/trailing pipes dropped). */
+function cellsOf(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('|')) return null;
+  const parts = trimmed.split('|');
+  // A row looks like `| a | b | c |`; the split yields ['', ' a ', ' b ', ' c ', ''].
+  return parts.slice(1, -1).map((c) => c.trim());
+}
+
+/**
+ * Collect test names from a TDD-matrix-style markdown document.
+ *
+ * Only the "declared tests" cell — the SECOND column — is read, and within a
+ * DELIVERED row only the text BEFORE the marker. Both restrictions exist because
+ * a matrix row's later columns discuss the design in prose and legitimately name
+ * types, symbols and fractions in backticks; treating those as claims is exactly
+ * the false-failure class this module was written to avoid.
+ *
+ * @returns {{claims: string[], intents: string[]}} deduplicated, source-ordered
+ */
+export function collectDeclaredTestNames(markdown) {
+  const claims = [];
+  const intents = [];
+  for (const line of String(markdown).split(/\r?\n/)) {
+    const cells = cellsOf(line);
+    if (!cells || cells.length < 2) continue;
+    const declaredCell = cells[1];
+    if (!declaredCell) continue;
+    // A separator row (`| --- | --- |`) has no test names and no marker.
+    const markerAt = declaredCell.indexOf(DELIVERED_MARKER);
+    const isDelivered = markerAt !== -1;
+    const scope = isDelivered ? declaredCell.slice(0, markerAt) : declaredCell;
+    const names = backtickedTestNames(scope);
+    (isDelivered ? claims : intents).push(...names);
+  }
+  return { claims: [...new Set(claims)], intents: [...new Set(intents)] };
+}
+
+/**
+ * Compare collected names against a compiled inventory.
+ *
+ * @param {{claims: string[], intents: string[]}} collected
+ * @param {Set<string>|string[]} inventory compiled test method names
+ * @returns {{missingFromInventory: string[], unmatchedIntents: string[], checked: number}}
+ */
+export function reconcileTestNames(collected, inventory) {
+  const have = inventory instanceof Set ? inventory : new Set(inventory || []);
+  const claims = Array.isArray(collected?.claims) ? collected.claims : [];
+  const intents = Array.isArray(collected?.intents) ? collected.intents : [];
+  return {
+    // Only DELIVERED claims can be defects. An intention is allowed to be absent.
+    missingFromInventory: claims.filter((n) => !have.has(n)),
+    // Reported separately and informationally: an intention that HAS landed is
+    // not a defect, but it usually means the row is stale and should be marked
+    // DELIVERED. Surfaced so the drift is visible rather than silent.
+    unmatchedIntents: intents.filter((n) => have.has(n)),
+    checked: claims.length,
+  };
+}
+
+/**
+ * Extract public test-method names from C# test sources.
+ *
+ * Used to build an inventory when no test report is available — for example at
+ * authoring time, before anything has run. This is a NAME inventory, not a
+ * pass/fail one: it proves a name exists, never that the test passes. Callers
+ * that need the stronger claim must use a run report.
+ */
+export function inventoryFromCSharpSources(sources) {
+  const names = new Set();
+  const pattern = /public\s+(?:async\s+)?(?:void|Task)\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+  for (const text of sources) {
+    for (const m of String(text).matchAll(pattern)) names.add(m[1]);
+  }
+  return names;
+}

package/src/harness/state.mjs

@@ -212,6 +212,47 @@ export function validateState(state, context = {}) {
         if (lt.to !== undefined && !PHASES.includes(lt.to)) errors.push({ path: 'lastTransition.to', message: `unknown phase "${lt.to}"` });
       }
     }
+
+    // AR-2. A story marked `done` must have SOME evidence record of its own.
+    //
+    // WHY THIS IS NEEDED. Every gate rule in this file is scoped to the ACTIVE
+    // work item, so `state validate` could report a document as fully valid while
+    // an already-completed story had no evidence whatsoever. In one real project
+    // eight `done` stories had zero records and validation said "valid, 0 errors,
+    // 0 warnings" — the gaps were invisible until they were looked for by hand.
+    //
+    // SCOPE, DELIBERATELY NARROW. This asserts COVERAGE, not gate completeness:
+    // it asks only "is there any evidence for this story at all?". Whether every
+    // required gate was satisfied for the right phase is already enforced at
+    // transition time, against the active work item, where the phase is known.
+    // Re-deciding that here would duplicate the transition matrix and risk the
+    // two disagreeing.
+    //
+    // It is an ERROR, not a warning, because a `done` story with no evidence is
+    // indistinguishable from a story that was never verified — which is the
+    // condition the framework exists to prevent. Projects that closed stories
+    // before the harness existed can resolve it with a scoped gate exception or
+    // by re-recording; silently tolerating it is what let the gap grow.
+    if (isPlainObject(state.epics) && Array.isArray(state.gateEvidence)) {
+      const evidenced = new Set(
+        state.gateEvidence
+          .map((e) => (isPlainObject(e) ? e.workItemId : null))
+          .filter((id) => typeof id === 'string' && id.length > 0),
+      );
+      for (const [epicId, epic] of Object.entries(state.epics)) {
+        if (!isPlainObject(epic) || !isPlainObject(epic.stories)) continue;
+        for (const [storyId, status] of Object.entries(epic.stories)) {
+          if (status !== 'done') continue;
+          if (evidenced.has(`${epicId}::${storyId}`)) continue;
+          errors.push({
+            path: `epics.${epicId}.stories.${storyId}`,
+            message: `story "${storyId}" is marked done but has no evidence record for its work item `
+              + `"${epicId}::${storyId}". A completed story must be backed by at least one evidence `
+              + 'record; otherwise it is indistinguishable from one that was never verified.',
+          });
+        }
+      }
+    }
   } else if (state.gateEvidence !== undefined) {
     warnings.push({ path: 'gateEvidence', message: 'gateEvidence on a v1 state is ignored until migration' });
   }
@@ -275,6 +316,15 @@ function validateEvidenceShape(ev, strict = null) {
   if (ev.result !== undefined && ev.result !== null && typeof ev.result !== 'string') {
     errors.push({ path: 'result', message: 'result must be a string or null' });
   }
+  // AR-1. `commit` is optional (a v2-shaped record omits it) but must be a real
+  // revision identifier when present — a branch or tag name would read as a
+  // citation while being uncheckable later, which is worse than none.
+  if (ev.commit !== undefined && ev.commit !== null && !/^[0-9a-fA-F]{4,40}$/.test(String(ev.commit))) {
+    errors.push({
+      path: 'commit',
+      message: 'commit must be a 4-40 character hex revision identifier, or null',
+    });
+  }
   if (ev.createdAt !== undefined && ev.createdAt !== null && Number.isNaN(Date.parse(ev.createdAt))) {
     errors.push({ path: 'createdAt', message: 'createdAt must be an ISO-8601 date-time' });
   }
@@ -552,6 +602,30 @@ export function migrateStateFile(statePath, { backup = true } = {}) {
 
 // ── Evidence ────────────────────────────────────────────────────────────────
 
+/**
+ * AR-1. Normalize and validate a commit citation.
+ *
+ * Accepts a full SHA or an abbreviated one (git's default short form is 7, but
+ * 4–40 hex characters are all unambiguous enough to store). A symbolic name such
+ * as a branch or tag is REJECTED: those move, so a record naming one cannot be
+ * checked later, which defeats the purpose of citing a revision at all.
+ *
+ * Returns null for an absent value so a v2-shaped record is unchanged.
+ */
+export function normalizeCommit(commit) {
+  if (commit === null || commit === undefined) return null;
+  const value = String(commit).trim();
+  if (value === '') return null;
+  if (!/^[0-9a-fA-F]{4,40}$/.test(value)) {
+    throw new StateError(
+      `commit must be a 4-40 character hex revision identifier, but was "${value}". `
+      + 'A branch or tag name is not accepted: it moves, so the citation could not be '
+      + 'checked later. Pass an abbreviated or full SHA.',
+    );
+  }
+  return value.toLowerCase();
+}
+
 /** Build an evidence record. `id` defaults to a fresh UUIDv4. */
 export function createEvidence({
   evidenceId,
@@ -569,12 +643,19 @@ export function createEvidence({
   criteriaHash = null,
   relevantFiles = [],
   toolVersion = null,
+  commit = null,
   createdAt = new Date(),
   expiresAt = null,
   freshnessPolicy = null,
   source = 'automated',
   id,
 }) {
+  // AR-1. A gate record must be able to name the revision it attests, or a
+  // "gate-related fix claim" cannot be traced to the code it claims to cover.
+  // Validated rather than trusted: this value is persisted into state.json and
+  // read back by the Reviewer, so a malformed one would make a claim look
+  // verified while naming nothing.
+  const normalizedCommit = normalizeCommit(commit);
   return {
     evidenceId: evidenceId || id || undefined,
     workItemId,
@@ -591,6 +672,7 @@ export function createEvidence({
     criteriaHash: criteriaHash || hashCriteria([]),
     relevantFiles,
     toolVersion,
+    commit: normalizedCommit,
     createdAt: timestamp(createdAt),
     expiresAt: expiresAt ? timestamp(expiresAt) : null,
     freshnessPolicy,

package/src/harness/util.mjs

@@ -1,149 +1,172 @@
-/**
- * Shared harness primitives: UUIDv4, SHA-256 over UTF-8 bytes, tree hashing,
- * deterministic JSON serialization, and UTC timestamps.
- *
- * Contract: docs/core/HarnessContract.md §2 (identifiers, hashes).
- */
-
-import { createHash, randomUUID } from 'node:crypto';
-import { readFileSync, existsSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-
-/** UUIDv4 identifier. */
-export function newId() {
-  return randomUUID();
-}
-
-export function isUuid(value) {
-  return typeof value === 'string'
-    && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
-}
-
-/** SHA-256 hex digest over UTF-8 bytes. */
-export function sha256(value) {
-  return createHash('sha256').update(value, 'utf-8').digest('hex');
-}
-
-/** SHA-256 hex digest over raw bytes (Buffers are hashed as-is). */
-export function sha256Bytes(buf) {
-  return createHash('sha256').update(buf).digest('hex');
-}
-
-/** Hash of a file's exact bytes, or null when the file is missing. */
-export function hashFile(path) {
-  if (!existsSync(path)) return null;
-  try {
-    return sha256Bytes(readFileSync(path));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Deterministic hash of a set of `(relativePath, fileHash)` pairs.
- * Pairs are sorted by path so the hash is order-independent and stable across
- * platforms. Files without a resolvable hash are recorded as `missing`.
- */
-export function hashTree(pairs) {
-  const normalized = [...pairs]
-    .map(({ path, hash }) => ({
-      path: String(path).replace(/\\/g, '/'),
-      hash: hash || 'missing',
-    }))
-    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-  return sha256(JSON.stringify(normalized));
-}
-
-/**
- * Hash an acceptance-criteria document or list. `criteria` may be a string or an
- * array of strings; a stable serialization is used either way.
- */
-export function hashCriteria(criteria) {
-  if (criteria === null || criteria === undefined) return sha256('[]');
-  const arr = Array.isArray(criteria) ? criteria.map(String) : [String(criteria)];
-  return sha256(JSON.stringify(arr));
-}
-
-/** ISO-8601 UTC timestamp for a Date or "now". */
-export function timestamp(at = new Date()) {
-  return (at instanceof Date ? at : new Date(at)).toISOString();
-}
-
-/** Current time provider; injectable for deterministic tests. */
-export function nowMs() {
-  return Date.now();
-}
-
-/**
- * Canonical JSON with sorted keys. Used for stable hashes and for comparing
- * evidence records without key-order noise.
- */
-export function canonicalJson(value) {
-  return JSON.stringify(sortKeys(value));
-}
-
-function sortKeys(value) {
-  if (Array.isArray(value)) return value.map(sortKeys);
-  if (value && typeof value === 'object') {
-    const out = {};
-    for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[key]);
-    return out;
-  }
-  return value;
-}
-
-export { canonicalJson as stableStringify };
-
-/**
- * List the files changed in the working tree relative to HEAD, using git.
- * Returns forward-slash relative paths. Returns an empty array when git is
- * unavailable or the directory is not a repository — callers must not assume
- * freshness coverage in that case; use `gitChangedFiles` when the distinction
- * between "no changes" and "no git" matters.
- */
-export function changedFiles(cwd, { runner = defaultGitRunner } = {}) {
-  return gitChangedFiles(cwd, { runner }).files;
-}
-
-/**
- * List changed files and report whether git was actually queryable.
- * Returns `{ available, files, reason }`. `available: false` means freshness
- * coverage could not be established and callers must fail safe.
- */
-export function gitChangedFiles(cwd, { runner = defaultGitRunner } = {}) {
-  let res;
-  try {
-    res = runner('git', ['-C', cwd, 'status', '--porcelain', '--untracked-files=all']);
-  } catch (err) {
-    return { available: false, files: [], reason: `git invocation failed: ${err.message}` };
-  }
-  if (!res) {
-    return { available: false, files: [], reason: 'git is not available' };
-  }
-  if (res.error || res.status === null) {
-    return { available: false, files: [], reason: 'git is not installed or could not be executed' };
-  }
-  if (res.status !== 0) {
-    // Not a repository, or git refused the query.
-    return { available: false, files: [], reason: String(res.stderr || '').trim() || `git exited ${res.status}` };
-  }
-  const files = new Set();
-  for (const line of String(res.stdout || '').split(/\r?\n/)) {
-    if (!line.trim()) continue;
-    // Porcelain v1: XY<space>path (rename: "old -> new").
-    let path = line.slice(3).trim();
-    if (path.includes(' -> ')) path = path.split(' -> ').pop().trim();
-    path = path.replace(/^"|"$/g, '');
-    if (path) files.add(path.replace(/\\/g, '/'));
-  }
-  return { available: true, files: [...files].sort(), reason: null };
-}
-
-function defaultGitRunner(cmd, args) {
-  try {
-    return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true });
-  } catch {
-    return null;
-  }
-}
-
+/**
+ * Shared harness primitives: UUIDv4, SHA-256 over UTF-8 bytes, tree hashing,
+ * deterministic JSON serialization, and UTC timestamps.
+ *
+ * Contract: docs/core/HarnessContract.md §2 (identifiers, hashes).
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+/** UUIDv4 identifier. */
+export function newId() {
+  return randomUUID();
+}
+
+export function isUuid(value) {
+  return typeof value === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
+}
+
+/** SHA-256 hex digest over UTF-8 bytes. */
+export function sha256(value) {
+  return createHash('sha256').update(value, 'utf-8').digest('hex');
+}
+
+/** SHA-256 hex digest over raw bytes (Buffers are hashed as-is). */
+export function sha256Bytes(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/** Hash of a file's exact bytes, or null when the file is missing. */
+export function hashFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return sha256Bytes(readFileSync(path));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deterministic hash of a set of `(relativePath, fileHash)` pairs.
+ * Pairs are sorted by path so the hash is order-independent and stable across
+ * platforms. Files without a resolvable hash are recorded as `missing`.
+ */
+export function hashTree(pairs) {
+  const normalized = [...pairs]
+    .map(({ path, hash }) => ({
+      path: String(path).replace(/\\/g, '/'),
+      hash: hash || 'missing',
+    }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return sha256(JSON.stringify(normalized));
+}
+
+/**
+ * Hash an acceptance-criteria document or list. `criteria` may be a string or an
+ * array of strings; a stable serialization is used either way.
+ */
+export function hashCriteria(criteria) {
+  if (criteria === null || criteria === undefined) return sha256('[]');
+  const arr = Array.isArray(criteria) ? criteria.map(String) : [String(criteria)];
+  return sha256(JSON.stringify(arr));
+}
+
+/** ISO-8601 UTC timestamp for a Date or "now". */
+export function timestamp(at = new Date()) {
+  return (at instanceof Date ? at : new Date(at)).toISOString();
+}
+
+/** Current time provider; injectable for deterministic tests. */
+export function nowMs() {
+  return Date.now();
+}
+
+/**
+ * Canonical JSON with sorted keys. Used for stable hashes and for comparing
+ * evidence records without key-order noise.
+ */
+export function canonicalJson(value) {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[key]);
+    return out;
+  }
+  return value;
+}
+
+export { canonicalJson as stableStringify };
+
+/**
+ * List the files changed in the working tree relative to HEAD, using git.
+ * Returns forward-slash relative paths. Returns an empty array when git is
+ * unavailable or the directory is not a repository — callers must not assume
+ * freshness coverage in that case; use `gitChangedFiles` when the distinction
+ * between "no changes" and "no git" matters.
+ */
+export function changedFiles(cwd, { runner = defaultGitRunner } = {}) {
+  return gitChangedFiles(cwd, { runner }).files;
+}
+
+/**
+ * Cadet's own bookkeeping — never a meaningful verification input.
+ *
+ * `state.json` is rewritten by the very command that records a gate, and
+ * `runs/*.json` gains a new ledger on every harness invocation. If either were
+ * auto-detected as a relevant file, the evidence hash would describe a file the
+ * recording itself mutates: the gate would be stale the moment it was written,
+ * and the resulting record would certify no story code. Excluded here, at the
+ * single scan used by both `harness verify` and `harness confirm`.
+ */
+const CADET_MACHINERY = ['.cadet/state.json', '.cadet/runs/'];
+
+/** True when a repository-relative path is Cadet's own bookkeeping. */
+function isCadetMachinery(relPath) {
+  return CADET_MACHINERY.some((p) => (p.endsWith('/') ? relPath.startsWith(p) : relPath === p));
+}
+
+/**
+ * List changed files and report whether git was actually queryable.
+ * Returns `{ available, files, reason }`. `available: false` means freshness
+ * coverage could not be established and callers must fail safe.
+ *
+ * Cadet's own machinery (`.cadet/state.json`, `.cadet/runs/**`) is filtered out
+ * of `files`; see `CADET_MACHINERY`.
+ */
+export function gitChangedFiles(cwd, { runner = defaultGitRunner } = {}) {
+  let res;
+  try {
+    res = runner('git', ['-C', cwd, 'status', '--porcelain', '--untracked-files=all']);
+  } catch (err) {
+    return { available: false, files: [], reason: `git invocation failed: ${err.message}` };
+  }
+  if (!res) {
+    return { available: false, files: [], reason: 'git is not available' };
+  }
+  if (res.error || res.status === null) {
+    return { available: false, files: [], reason: 'git is not installed or could not be executed' };
+  }
+  if (res.status !== 0) {
+    // Not a repository, or git refused the query.
+    return { available: false, files: [], reason: String(res.stderr || '').trim() || `git exited ${res.status}` };
+  }
+  const files = new Set();
+  for (const line of String(res.stdout || '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    // Porcelain v1: XY<space>path (rename: "old -> new").
+    let path = line.slice(3).trim();
+    if (path.includes(' -> ')) path = path.split(' -> ').pop().trim();
+    path = path.replace(/^"|"$/g, '');
+    if (!path) continue;
+    const rel = path.replace(/\\/g, '/');
+    if (isCadetMachinery(rel)) continue;
+    files.add(rel);
+  }
+  return { available: true, files: [...files].sort(), reason: null };
+}
+
+function defaultGitRunner(cmd, args) {
+  try {
+    return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true });
+  } catch {
+    return null;
+  }
+}
+

package/src/harness/verification.mjs

@@ -252,6 +252,7 @@ export async function runVerificationLoop({
   relevantFiles = [],
   criteria = [],
   rootDir = process.cwd(),
+  commit = null,
   policy,
   budgets,
   runCommandImpl = runCommand,
@@ -327,6 +328,7 @@ export async function runVerificationLoop({
       inputTreeHash,
       criteriaHash,
       relevantFiles,
+      commit,
       createdAt: startedAt,
       source: 'automated',
     });
@@ -461,7 +463,7 @@ function finalize({ status, attempts, tracker, inputTreeHash, criteriaHash, stop
 export function manualConfirmation({
   gate, workItemId, phase, projectPath, editorVersion, scope, acceptanceCriterionId = null,
   relevantFiles = [], criteria = [], rootDir = process.cwd(), approvedBy = 'user', at = new Date(),
-  reason = null, expiresAt = null, environment = null, expiresInMs = null,
+  reason = null, expiresAt = null, environment = null, expiresInMs = null, commit = null,
 } = {}) {
   const inputTreeHash = computeInputTreeHash(rootDir, relevantFiles);
   // v3 quality fields. `scope` is declared both as the free-text `result` line
@@ -504,6 +506,7 @@ export function manualConfirmation({
       relevantFiles,
       createdAt: at,
       expiresAt: expiry,
+      commit,
       source: 'manual-confirmation',
     }),
     // Present only when supplied, so a v2-shaped record is unchanged when the