cadet-agent 0.33.0 → 0.34.0

package/README.md

@@ -168,6 +168,10 @@ Hard gates are enforced at every phase transition. The agent reads `.cadet/state
 | review → validation | `codeReviewCompleted`, `securityReviewPassed`, `acceptanceCriteriaValidated` |
 | validation → closed | `designArtifactSyncConfirmed` |
 
+**`closed` is end-of-epic, not per-story.** `validation → closed` is taken only when no stories remain (`NEXT_STORY → no → CLOSED` above). When an epic still has stories, the next story re-enters from `validation → implementation` (`NEXT_STORY → yes → IMPL`). Do not close a story individually: `closed` is terminal, and there is no transition out of it.
+
+The full set of legal transitions is the three gated rows above **plus** the ungated forward edges (classification, planning progression, `story-breakdown → implementation`, and the `validation → implementation` next-story loop). Any transition outside that set is rejected with a named reason.
+
 ### Harness
 
 Gates are backed by **evidence**, not assertion. Each claimed gate must have a fresh, non-superseded evidence record bound to the current work item, input tree hash, and acceptance criteria. The harness also bounds context, tokens, tool calls, retries, wall-clock time, cost, and archive sizes — and those bounds are enforced, not advisory.

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "cadet-agent",
-  "version": "0.33.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.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"
+  }
+}

package/src/cli.mjs

@@ -94,6 +94,7 @@ function parseArgs(argv) {
       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;
@@ -618,39 +619,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/state.mjs

@@ -718,8 +718,15 @@ const UNGATED_FORWARD_EDGES = Object.freeze([
   ['architectureComplete', 'story-breakdown'],
   ['spikes', 'story-breakdown'],
   ['story-breakdown', 'implementation'],
-  // Re-entering work for a new story/epic from a review/vallidation outcome.
-  ['story-breakdown', 'story-breakdown'],
+  // Next-story loop. The workflow is
+  //   VALIDATE -->|"gate: designArtifactSyncConfirmed"| NEXT_STORY
+  //   NEXT_STORY -->|"yes"| IMPL
+  //   NEXT_STORY -->|"no"| CLOSED
+  // so the next story in an epic re-enters implementation from `validation`.
+  // `closed` stays terminal — it means the epic/plan is finished
+  // (Resume: "All work is complete for the current epic(s)") — and is
+  // deliberately NOT an escape hatch for starting the next story.
+  ['validation', 'implementation'],
 ]);
 
 /** Is `from → to` one of the declared ungated forward edges? */

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;
 }