cadet-agent 0.36.0 → 0.37.0

package/package.json

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

@@ -58,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

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

@@ -231,19 +231,37 @@ export function validateState(state, context = {}) {
     // 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.
+    // 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;
-          if (evidenced.has(`${epicId}::${storyId}`)) 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 `