cadet-agent 0.33.1 → 0.35.0

package/package.json

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

package/src/cli.mjs

@@ -90,10 +90,14 @@ 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;
       case '--write-coverage': opts.writeCoverage = true; break;
+      case '--strict-orphans': opts.strictOrphans = true; break;
       case '--dry-run': opts.dryRun = true; break;
       case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
       case '--agents-md': opts.agentsMd = argv[++i]; break;
@@ -319,6 +323,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, '/'));
@@ -458,6 +465,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';
@@ -618,39 +628,60 @@ async function cmdHarness(opts) {
     const inventory = parseTestInventory(reportText);
     const coverage = compareCoverage(criteria, inventory);
     const gaps = describeCoverageGaps(coverage);
+    // The inverse direction: tests that ran but are declared on no AC. Always
+    // reported; only fatal when explicitly requested, because a consumer may
+    // legitimately carry helper tests that belong to no single criterion.
+    const orphanGaps = describeCoverageGaps(coverage, { includeOrphans: true }).slice(gaps.length);
+    const orphans = coverage.orphaned || [];
 
     // Under strict closure an unknown/empty inventory can never prove coverage,
     // even if every AC declared no tests in a way that looked consistent.
     const unknownInventory = inventory.format === 'unknown' || inventory.names.length === 0;
-    const effectiveOk = coverage.ok && !unknownInventory;
+    const orphanBlocking = opts.strictOrphans === true && orphans.length > 0;
+    const effectiveOk = coverage.ok && !unknownInventory && !orphanBlocking;
 
     if (!strict) {
       // v2/v3 parity: report, write nothing, exit 0.
       if (opts.format === 'json') {
-        emit(opts, '', { ok: effectiveOk, story: opts.story, ac: coverage.ac, inventorySize: coverage.inventorySize, format: inventory.format, gateSet: false, reportPath });
+        emit(opts, '', { ok: effectiveOk, story: opts.story, ac: coverage.ac, orphaned: orphans, inventorySize: coverage.inventorySize, format: inventory.format, gateSet: false, reportPath });
       } else if (effectiveOk) {
         console.log(`✅ AC coverage verified for ${opts.story} (${coverage.ac.length} criteria, ${coverage.inventorySize} tests in inventory).`);
         console.log('   strictClosure is off — reported only, state.json unchanged.');
+        if (orphans.length > 0) {
+          // A warning goes to stderr even on the success path, so it is not lost
+          // in stdout piping and matches how every other warning is emitted.
+          console.error(`   ⚠️  ${orphans.length} test(s) declared on no acceptance criterion (reported only):`);
+          for (const g of orphanGaps) console.error(g);
+        }
       } else {
         console.error(`⚠️  AC coverage gaps in ${opts.story} (strictClosure off — reported only):`);
         if (unknownInventory) console.error(`   no test inventory could be derived from ${reportPath || 'the report'} (format: ${inventory.format}).`);
         for (const g of gaps) console.error(g);
+        for (const g of orphanGaps) console.error(g);
       }
       if (!effectiveOk) process.exit(1);
       return;
     }
 
     if (!effectiveOk) {
-      const detail = { ok: false, story: opts.story, ac: coverage.ac, inventorySize: coverage.inventorySize, format: inventory.format, gateSet: false, code: unknownInventory ? 'inventory-unknown' : 'coverage-gap' };
+      const detail = { ok: false, story: opts.story, ac: coverage.ac, orphaned: orphans, inventorySize: coverage.inventorySize, format: inventory.format, gateSet: false, code: unknownInventory ? 'inventory-unknown' : (orphanBlocking ? 'orphaned-tests' : 'coverage-gap') };
       if (opts.format === 'json') emit(opts, '', detail);
       else {
         console.error(`❌ Cannot set acceptanceCriteriaValidated for ${opts.story}:`);
         if (unknownInventory) console.error(`   no test inventory could be derived from ${reportPath || 'the report'} (format: ${inventory.format}). An unparseable report proves nothing.`);
         for (const g of gaps) console.error(g);
+        if (orphanBlocking) for (const g of orphanGaps) console.error(g);
       }
       process.exit(1);
     }
 
+    if (orphans.length > 0) {
+      // Passing, but the inverse-direction drift is visible rather than silent.
+      const notice = `⚠️  ${orphans.length} test(s) ran but are declared on no acceptance criterion (not fatal; pass --strict-orphans to enforce).`;
+      if (opts.format === 'json') console.error(notice);
+      else for (const g of [notice, ...orphanGaps]) console.error(g);
+    }
+
     const at = new Date();
     const criteriaStrings = coverage.ac.flatMap((a) => [a.id, ...a.declared]);
     const nowIso = at.toISOString();

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/verify-acs.mjs

@@ -240,10 +240,21 @@ function splitTestList(text) {
 /**
  * Compare a story's declared tests against a run's inventory.
  *
- * Returns `{ ok, ac: [{ id, declared, found, status }], inventorySize, format }`.
+ * Returns `{ ok, ac: [{ id, declared, found, status }], orphaned, inventorySize, format }`.
  * `status` is `covered` (all declared found), `missing` (some declared absent),
  * or `undeclared` (the AC declares no test at all).
  *
+ * `orphaned` is the INVERSE direction: tests that ran but are declared on no AC.
+ * This module previously checked only declared→delivered, so a delivered test
+ * attached to no criterion was invisible — the drift that recurred three times
+ * before this was added. Note the status name `undeclared` does NOT cover this
+ * case: it means "this AC declares no tests", not "this test is on no AC".
+ *
+ * `orphaned` deliberately does NOT affect `ok`. Consumers legitimately have
+ * helper tests and parameterised fixtures that belong to no single criterion, so
+ * making orphans fatal would break every existing story. Callers that want
+ * enforcement pass `--strict-orphans` (see describeCoverageGaps and cli.mjs).
+ *
  * Every gap is reported together; the caller renders all of them, never just the
  * first.
  */
@@ -252,8 +263,13 @@ export function compareCoverage(criteria, inventory) {
   const ac = [];
   let ok = true;
 
+  // Union of everything declared anywhere, so a test declared on any AC is not
+  // an orphan just because it is not on the AC being examined.
+  const declaredAnywhere = new Set();
+
   for (const c of criteria) {
     const declared = (c.tests || []).map((t) => String(t));
+    for (const t of declared) declaredAnywhere.add(normalizeTestName(t));
     if (declared.length === 0) {
       ok = false;
       ac.push({ id: c.id, declared: [], found: [], status: 'undeclared' });
@@ -265,16 +281,34 @@ export function compareCoverage(criteria, inventory) {
     ac.push({ id: c.id, declared, found: present, status });
   }
 
+  // Preserve report order and the report's own spelling, deduped by normalized
+  // name so an inventory that repeats a test does not repeat the warning.
+  const orphaned = [];
+  const seenOrphan = new Set();
+  for (const raw of inventory?.names || []) {
+    const key = normalizeTestName(raw);
+    if (!key || declaredAnywhere.has(key) || seenOrphan.has(key)) continue;
+    seenOrphan.add(key);
+    orphaned.push(key);
+  }
+
   return {
     ok,
     ac,
+    orphaned,
     inventorySize: (inventory?.names || []).length,
     format: inventory?.format || 'unknown',
   };
 }
 
-/** Format the gaps as concrete, actionable lines (spec §5.1 step 4). */
-export function describeCoverageGaps(coverage) {
+/**
+ * Format the gaps as concrete, actionable lines (spec §5.1 step 4).
+ *
+ * `includeOrphans` appends the inverse-direction gaps. It is opt-in so the
+ * default call site keeps its previous output shape, and so a caller can report
+ * orphans without treating them as failures.
+ */
+export function describeCoverageGaps(coverage, { includeOrphans = false } = {}) {
   const lines = [];
   for (const entry of coverage.ac) {
     if (entry.status === 'undeclared') {
@@ -287,5 +321,10 @@ export function describeCoverageGaps(coverage) {
       }
     }
   }
+  if (includeOrphans) {
+    for (const t of coverage.orphaned || []) {
+      lines.push(`   "${t}" ran but is declared on no acceptance criterion — attach it to the criterion it proves, or remove it.`);
+    }
+  }
   return lines;
 }