cadet-agent 0.56.0 → 0.60.0

package/src/harness/state.mjs

@@ -15,6 +15,7 @@ import {
   REACHABILITY_GATE, REACHABILITY_TRANSITION_FROM,
   DESIGN_REVIEW_GATE, DESIGN_REVIEW_TRANSITION_FROM,
   HUMAN_ACCEPTANCE_GATE, HUMAN_ACCEPTANCE_TRANSITION_FROM,
+  USER_PLAY_GATE, USER_PLAY_TRANSITION_FROM,
   ARCHITECTURE_GATE, ARCHITECTURE_TRANSITION_FROM, ARCHITECTURE_TRANSITION_TO,
   architectureFitnessActive,
 } from './policy.mjs';
@@ -435,11 +436,50 @@ export function validateState(state, context = {}) {
         const scope = Array.isArray(entry.scope) ? entry.scope : (entry.scope ? [entry.scope] : []);
         for (const s of scope) excepted.add(String(s));
       }
+      // The same ambiguity, seen from the other side: a story the session moved on
+      // FROM, with evidence behind it, that still reads `planned` — which makes a
+      // finished story indistinguishable from one that was never started.
+      //
+      // The data already tells the two apart. `storyCompletions` records the
+      // boundary and how much the item left behind, and its comment says why the
+      // count is there: so "a completion with nothing behind it is visible rather
+      // than implied". A row with nothing behind it is a hollow completion — an
+      // item begun and then abandoned — and is left alone here. A row with records
+      // in it is a story that was carried to a verdict, and `planned` is then a
+      // false statement about it.
+      //
+      // It is an ERROR, not a warning, for the reason the rule below gives, and its
+      // remedy has the same shape: say what happened. A story that was superseded
+      // rather than delivered is not `planned` either.
+      //
+      // `in-progress` is deliberately NOT checked: `state begin` on an item that
+      // still carries its old completion row leaves it active, so active-plus-row
+      // is a legitimate combination and refusing it would be a false accusation.
+      const completedWith = new Map();
+      if (Array.isArray(state.storyCompletions)) {
+        for (const row of state.storyCompletions) {
+          if (!isPlainObject(row)) continue;
+          if (typeof row.workItemId !== 'string' || row.workItemId.length === 0) continue;
+          const records = Number(row.evidenceRecords);
+          if (!(records > 0)) continue;
+          completedWith.set(row.workItemId, records);
+        }
+      }
       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 (status === 'planned' && completedWith.has(workItemId)) {
+            errors.push({
+              path: `epics.${epicId}.stories.${storyId}`,
+              message: `story "${storyId}" reads "planned" but the completion row for its work item `
+                + `"${workItemId}" records ${completedWith.get(workItemId)} evidence record(s). A story the `
+                + 'session moved on from, with evidence behind it, is not planned: it is done, or it is '
+                + 'superseded. Leaving it planned makes a finished story indistinguishable from one that '
+                + 'was never started.',
+            });
+          }
+          if (status !== 'done') continue;
           if (evidenced.has(workItemId)) continue;
           if (excepted.has(workItemId)) continue;
           errors.push({
@@ -1336,7 +1376,7 @@ export function conditionalEdgeGates(fromPhase, toPhase, policy = null) {
   return policy?.designReview?.enabled === true ? [DESIGN_REVIEW_GATE] : [];
 }
 
-export function requiredGates(toPhase, { reachability = false, humanAcceptance = false, architectureFitness = false } = {}) {
+export function requiredGates(toPhase, { reachability = false, humanAcceptance = false, architectureFitness = false, userPlay = false } = {}) {
   for (const [from, spec] of Object.entries(TRANSITIONS)) {
     if (spec.to === toPhase) {
       const gates = [...spec.gates];
@@ -1359,6 +1399,16 @@ export function requiredGates(toPhase, { reachability = false, humanAcceptance =
       // revalidated gate is judged without its phase stamp — which for this one would
       // mean accepting a record written in any phase at all.
       if (humanAcceptance && from === HUMAN_ACCEPTANCE_TRANSITION_FROM) gates.push(HUMAN_ACCEPTANCE_GATE);
+      // User play joins the STORY boundary (`review -> validation`) and nothing else, and
+      // only when the repository has asked for it. Placement: a playthrough is a claim
+      // about a delivered, reviewed story, and this is the edge a story crosses before the
+      // next one starts — `validation -> implementation` is the next-story loop and stays
+      // unblocked, which is why the requirement cannot live there. It is deliberately NOT
+      // in `revalidate`: at `validation -> closed` the epic's own
+      // `humanAcceptanceConfirmed` covers the whole epic, and demanding every story's play
+      // again at closure would multiply the person's work at the exact moment they are
+      // being asked to accept the finished thing.
+      if (userPlay && from === USER_PLAY_TRANSITION_FROM) gates.push(USER_PLAY_GATE);
       // Architecture fitness joins `implementation -> review`, and only when the project
       // has declared checks. It is appended at evaluation time rather than written into
       // the transition table, so a project that declares nothing keeps the frozen lists
@@ -1579,6 +1629,7 @@ export function evaluateTransition(state, toPhase, context = {}) {
     reachability: context.policy?.reachability?.enabled === true,
     humanAcceptance: context.policy?.humanAcceptance?.enabled === true,
     architectureFitness: architectureFitnessActive(context.policy),
+    userPlay: context.policy?.userPlay?.enabled === true,
   });
   // An edge with no `TRANSITIONS` entry can still carry a gate. It is resolved HERE,
   // before the ungated-edge shortcut below, because that shortcut is what would