cadet-agent 0.32.1 → 0.33.1

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,6 +1,6 @@
 {
   "name": "cadet-agent",
-  "version": "0.32.1",
+  "version": "0.33.1",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -39,6 +39,7 @@ function showHelp() {
     cadet-agent state validate      Validate .cadet/state.json against the v2 schema
     cadet-agent state migrate       Atomically migrate v1 state to v2 (backup on write)
     cadet-agent state transition --to <phase>   Enforce the transition matrix + evidence
+    cadet-agent state transition --to <phase> --dry-run   Check only; writes nothing
 
     cadet-agent harness record      Append a sanitized span/evidence/decision event
     cadet-agent harness confirm     Record manual-confirmation evidence (writes ledger + state)
@@ -93,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 '--dry-run': opts.dryRun = true; break;
       case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
       case '--agents-md': opts.agentsMd = argv[++i]; break;
       case '--yes': case '-y': opts.yes = true; break;
@@ -204,16 +206,23 @@ async function cmdState(opts) {
     if (!exists) fail(opts, 'No .cadet/state.json found. Initialise state before transitioning.', () => 2);
     // Freshness is enforced against the current working tree: evaluateTransition
     // recomputes each gate's input-tree hash from the evidence's relevant files.
+    //
+    // `--dry-run` reports the SAME verdict and stops. It is the only safe way to
+    // ask "would this transition be allowed?" — running the command without the
+    // flag applies the transition. A check that is documented as a dry run must
+    // not have side effects, so the write below is gated on `!opts.dryRun`.
     const evaluation = evaluateTransition(state, opts.to, { rootDir: opts.targetDir });
     if (!evaluation.allowed) {
       const detail = {
         ok: false,
         allowed: false,
+        dryRun: opts.dryRun === true,
+        applied: false,
         missingGates: evaluation.missingGates,
         staleEvidence: evaluation.staleEvidence,
         errors: evaluation.errors,
       };
-      const lines = ['❌ Transition rejected:'];
+      const lines = [`❌ Transition rejected${opts.dryRun ? ' (dry run — nothing was written)' : ''}:`];
       for (const e of evaluation.errors) lines.push(`   ${e}`);
       if (evaluation.missingGates.length) lines.push(`   missing gates/evidence: ${evaluation.missingGates.join(', ')}`);
       for (const s of evaluation.staleEvidence) lines.push(`   stale: ${s.gate} — ${s.reason || (s.reasons || []).join('; ')}`);
@@ -221,9 +230,17 @@ async function cmdState(opts) {
       else console.error(lines.join('\n'));
       process.exit(1);
     }
+    if (opts.dryRun) {
+      emit(
+        opts,
+        `✅ Transition ${state.session?.currentPhase} → ${opts.to} would be allowed (dry run — nothing was written).`,
+        { ok: true, allowed: true, dryRun: true, applied: false, to: opts.to, from: state.session?.currentPhase },
+      );
+      return;
+    }
     const next = applyTransition(state, opts.to, { rootDir: opts.targetDir });
     writeState(opts.targetDir, next);
-    emit(opts, `✅ Transitioned to ${opts.to}.`, { ok: true, allowed: true, to: opts.to });
+    emit(opts, `✅ Transitioned to ${opts.to}.`, { ok: true, allowed: true, dryRun: false, applied: true, to: opts.to });
     return;
   }
 

package/src/harness/index.mjs

@@ -25,7 +25,7 @@ export {
 export {
   STATE_VERSION, READABLE_STATE_VERSIONS, validateState, migrateStateV1toV2, migrateStateFile,
   createEvidence, computeInputTreeHash, workItemIdOf, evidenceFreshness,
-  latestEvidenceForGate, activeExceptions, requiredGates, evaluateTransition, resolveStrict,
+  latestEvidenceForGate, activeExceptions, requiredGates, isUngatedForwardEdge, evaluateTransition, resolveStrict,
   applyTransition, resetGatesForNewWorkItem, statePathFor, readState, writeState, writeJsonAtomic, StateError,
 } from './state.mjs';
 

package/src/harness/state.mjs

@@ -685,6 +685,55 @@ export function requiredGates(toPhase) {
   return null;
 }
 
+/**
+ * Ungated forward edges — transitions that carry no gate requirement but are
+ * still legal. These are the bootstrap and planning-progression edges from the
+ * workflow (README mermaid + Workflow.md): classification can drop straight to
+ * implementation, and the planning phases advance without gates.
+ *
+ * This list exists because `requiredGates` returns null for any phase that is
+ * never a *target* of a gated transition (implementation, requirements,
+ * architecture, …). Treating null as "ungated, therefore legal" allowed a
+ * transition into those phases from ANYWHERE — including out of the terminal
+ * `closed` phase. The set below is the closed enumeration of the intended
+ * forward edges; anything not in it (or in TRANSITIONS) is rejected.
+ */
+const UNGATED_FORWARD_EDGES = Object.freeze([
+  // Classification (context-resolution) routes to planning or straight to work.
+  ['context-resolution', 'requirements'],
+  ['context-resolution', 'architecture'],
+  ['context-resolution', 'implementation'],
+  // Planning progression.
+  ['requirements', 'architecture'],
+  ['requirements', 'requirementsComplete'],
+  ['requirementsComplete', 'architecture'],
+  ['requirementsComplete', 'architectureComplete'],
+  ['architecture', 'architectureComplete'],
+  ['architecture', 'spikes'],
+  ['requirements', 'spikes'],
+  ['requirementsComplete', 'spikes'],
+  ['architectureComplete', 'spikes'],
+  ['spikes', 'architecture'],
+  ['spikes', 'architectureComplete'],
+  ['architectureComplete', 'story-breakdown'],
+  ['spikes', 'story-breakdown'],
+  ['story-breakdown', 'implementation'],
+  // 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? */
+export function isUngatedForwardEdge(fromPhase, toPhase) {
+  return UNGATED_FORWARD_EDGES.some(([from, to]) => from === fromPhase && to === toPhase);
+}
+
 /**
  * Check one gate for a transition. Shared by the primary `gates` set and the
  * strict-closure `revalidate` set so the two can never drift apart.
@@ -770,8 +819,15 @@ export function evaluateTransition(state, toPhase, context = {}) {
 
   const spec = requiredGates(toPhase);
   if (!spec) {
-    // Ungated transitions (e.g. context-resolution → requirements) are legal.
-    return { allowed: true, fromPhase, toPhase, missingGates, staleEvidence, errors, revalidated: [] };
+    // Ungated transitions are legal ONLY along the declared forward edges
+    // (bootstrap + planning progression). A target that is neither gated nor a
+    // declared forward edge is rejected — most importantly, this makes `closed`
+    // terminal instead of an any-to-any escape hatch.
+    if (isUngatedForwardEdge(fromPhase, toPhase)) {
+      return { allowed: true, fromPhase, toPhase, missingGates, staleEvidence, errors, revalidated: [] };
+    }
+    errors.push(`illegal transition "${fromPhase}" → "${toPhase}" (not a gated transition, and not a declared forward edge)`);
+    return { allowed: false, fromPhase, toPhase, missingGates, staleEvidence, errors, revalidated: [] };
   }
   if (spec.from !== fromPhase) {
     errors.push(`illegal transition "${fromPhase}" → "${toPhase}" (expected from "${spec.from}")`);