cadet-agent 0.35.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadet-agent",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {

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);
@@ -57,10 +58,15 @@ function showHelp() {
     --gate         Gate name (harness verify|confirm)
     --command      Command override (harness verify)
     --files        Comma-separated relevant files to bind evidence to (harness verify|confirm)
+    --commit       Revision the gate attests, as a hex SHA (harness verify|confirm)
     --reason       Why automation was unavailable (harness confirm)
     --expires-at   ISO-8601 expiry bounding the confirmation (harness confirm)
     --environment  key=value,... describing what was verified (harness confirm)
     --scope        Comma-separated scope of the confirmation (harness confirm)
+    --story        Story markdown declaring the acceptance criteria (harness verify-acs)
+    --report       Test report to derive the inventory from (harness verify-acs|matrix-check)
+    --matrix       TDD matrix markdown to check (harness matrix-check)
+    --inventory    Newline-separated test names, when no report is available (harness matrix-check)
     --agents-md    keep|overwrite|merge for an existing AGENTS.md (init/sync)
     --yes, -y      Never prompt; keep existing files (non-interactive installs)
     --help, -h    Show this help
@@ -96,6 +102,11 @@ function parseArgs(argv) {
       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;
@@ -361,6 +372,7 @@ async function cmdHarness(opts) {
       relevantFiles,
       rootDir: opts.targetDir,
       approvedBy: opts.approvedBy || 'user',
+      commit: opts.commit || null,
       at,
     });
 
@@ -526,6 +538,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'),
@@ -764,6 +777,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,
@@ -772,7 +874,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/policy.mjs

@@ -162,6 +162,7 @@ export const EXCEPTION_CATEGORIES = Object.freeze([
   'unscoped-freshness',
   'documentation-only',
   'tooling-gap',
+  'pre-harness-story',
 ]);
 
 /** Default expiry (in days) per category. `null` means "no default bound". */
@@ -172,6 +173,11 @@ export const EXCEPTION_EXPIRY_DAYS = Object.freeze({
   'unscoped-freshness': 1,
   'documentation-only': null,   // scoped to the work item
   'tooling-gap': 14,
+  // No default bound: this records a PERMANENT historical fact (a story closed
+  // before the harness existed, whose gates were never recorded as evidence).
+  // The gap will never close on its own, so a time-bounded exception would only
+  // re-raise the same finding every N days without anything having changed.
+  'pre-harness-story': null,
 });
 
 /** Categories whose exception must carry a closure review note. */

package/src/harness/state.mjs

@@ -212,6 +212,65 @@ 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 resolve it with a scoped `pre-harness-story`
+    // exception naming the story's work item; 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),
+      );
+      // A scoped exception is the FIRST-CLASS escape for a permanent historical
+      // gap. `activeExceptions` is keyed on the ACTIVE work item, which is the
+      // current story — the wrong scope here, where we walk every completed story
+      // — so the scope match is done explicitly against each story's work-item id.
+      // Only a valid, categorised exception counts: an unknown category is not a
+      // loophole, it is a typo, and `validateGateException` rejects it separately.
+      const excepted = new Set();
+      if (Array.isArray(state.changeHistory)) {
+        for (const entry of state.changeHistory) {
+          if (!isPlainObject(entry) || entry.type !== 'gate-exception') continue;
+          if (!EXCEPTION_CATEGORIES.includes(entry.category)) continue;
+          const scope = Array.isArray(entry.scope) ? entry.scope : (entry.scope ? [entry.scope] : []);
+          for (const s of scope) excepted.add(String(s));
+        }
+      }
+      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;
+          const workItemId = `${epicId}::${storyId}`;
+          if (evidenced.has(workItemId)) continue;
+          if (excepted.has(workItemId)) 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 +334,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 +620,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 +661,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 +690,7 @@ export function createEvidence({
     criteriaHash: criteriaHash || hashCriteria([]),
     relevantFiles,
     toolVersion,
+    commit: normalizedCommit,
     createdAt: timestamp(createdAt),
     expiresAt: expiresAt ? timestamp(expiresAt) : null,
     freshnessPolicy,

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