cadet-agent 0.56.0 → 0.63.1

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({
@@ -500,15 +540,25 @@ function validateEvidenceShape(ev, strict = null) {
   if (ev.evidenceId !== undefined && !isUuid(ev.evidenceId)) errors.push({ path: 'evidenceId', message: 'evidenceId must be a UUIDv4' });
   if (ev.phase !== undefined && !PHASES.includes(ev.phase)) errors.push({ path: 'phase', message: `unknown phase "${ev.phase}"` });
   if (ev.gate !== undefined && !GATES.includes(ev.gate)) errors.push({ path: 'gate', message: `unknown gate "${ev.gate}"` });
-  // A human acceptance with no witness, or with no statement of its limitations, is
-  // a signature on nothing. Checked at validation as well as at creation, because a
-  // hand-edited state.json is exactly what this gate must not be satisfiable by.
-  if (ev.gate === HUMAN_ACCEPTANCE_GATE) {
-    for (const field of ['witness', 'limitations']) {
-      const value = ev[field];
-      if (typeof value !== 'string' || value.trim() === '') {
-        errors.push({ path: field, message: `a ${HUMAN_ACCEPTANCE_GATE} record must carry a non-empty "${field}"` });
-      }
+  // A human-owned gate's record IS a person's answer, so the record must carry one. Checked at
+  // validation as well as at creation, because a hand-edited state.json is exactly what this gate
+  // must not be satisfiable by.
+  //
+  // Both gates carried `witness` and `limitations` here until 2026-10-03, when the form that
+  // produced them was removed; the substance moved into `reason`, which now holds what the person
+  // said. Two fields on two gates existed only to mirror that form.
+  if (ev.gate === HUMAN_ACCEPTANCE_GATE || ev.gate === USER_PLAY_GATE) {
+    const hasReason = typeof ev.reason === 'string' && ev.reason.trim() !== '';
+    // `witness` + `limitations` are the shape the removed form wrote: two fields that existed only
+    // to mirror it. A record already written under that shape keeps validating, because the
+    // framework never invalidates evidence it once accepted.
+    const hasLegacyPair = ['witness', 'limitations']
+      .every((field) => typeof ev[field] === 'string' && ev[field].trim() !== '');
+    if (!hasReason && !hasLegacyPair) {
+      errors.push({
+        path: 'reason',
+        message: `a ${ev.gate} record must carry the person's own answer in a non-empty "reason"`,
+      });
     }
   }
   // The architecture record is a claim about checks, so it must say which checks. One
@@ -1093,6 +1143,8 @@ export function createEvidence({
   command = null,
   result = null,
   exitCode = null,
+  durationMs = null,
+  outputBytes = null,
   artifactPath = null,
   artifactHash = null,
   inputTreeHash,
@@ -1122,6 +1174,13 @@ export function createEvidence({
     command,
     result,
     exitCode,
+    // WHAT THE RUN COST. Both are measured for the attempt span already, and neither was written where
+    // an operator reads a gate: `state.json -> gateEvidence` carried the command, the exit code and the
+    // verdict, but not how long the command took or whether it said anything. The wall clock is the
+    // cheapest way to tell a real red from a process that never launched, and this repository's own
+    // policy tells a reader to do exactly that. Null when nothing ran.
+    durationMs,
+    outputBytes,
     artifactPath,
     artifactHash,
     inputTreeHash,
@@ -1316,7 +1375,6 @@ export function activeExceptions(state, { workItemId, now = new Date() } = {}) {
 
 // ── Transitions ─────────────────────────────────────────────────────────────
 
-/** Required gates for a transition target, or null when the target is not gated. */
 /**
  * Gates required on an edge that carries no entry in `TRANSITIONS`.
  *
@@ -1336,7 +1394,17 @@ 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 } = {}) {
+/**
+ * The gates a transition to `toPhase` requires: `{ from, gates, revalidate }`, or `null` when the target
+ * is not the target of a gated transition.
+ *
+ * The shape is an OBJECT, not a bare list. The caller reads `.gates`, and `.revalidate` names the gates
+ * this edge re-examines under strict closure. Corrected here because the previous one-line comment said
+ * only "required gates for a transition target" and said nothing about the object, and a caller that read
+ * it as a list then got an object it treated as empty — which reported a gated edge as ungated. A comment
+ * a reader can act on wrongly is worse than no comment.
+ */
+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 +1427,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 +1657,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
@@ -2017,6 +2096,213 @@ export function writeJsonAtomic(path, value) {
   return path;
 }
 
+/**
+ * The legal edges out of a phase: what `state transition --to <phase>` would accept.
+ *
+ * WHY THIS EXISTS. Resuming asks "what happens next", and the tool that answers it —
+ * `state transition --to <phase> --dry-run` — takes a TARGET phase the reader has to guess
+ * before it will say anything. Both halves of the answer are already declared in this
+ * framework: `TRANSITIONS` for the gated story loop, and `UNGATED_FORWARD_EDGES` for the
+ * planning progression and the next-story loop. The gate list comes from `requiredGates`,
+ * the same function the transition itself calls, so an opt-in gate (reachability, the
+ * playthrough, human acceptance, architecture fitness) is reported exactly when the resolved
+ * policy would require it — and a repository that enables none of them sees the frozen lists
+ * the contract declares, unchanged.
+ *
+ * Pure: a function of (phase, policy). It runs no transition and reads no file, so a brief
+ * cannot claim an edge the machinery would refuse.
+ */
+export function legalEdgesFrom(phase, policy = null) {
+  if (!phase) return [];
+  const edges = [];
+  const spec = TRANSITIONS[phase];
+  if (spec) {
+    // `requiredGates` returns `{ from, gates, revalidate }` — an OBJECT, not a bare list. Read `.gates`;
+    // a caller that treats the return value as an array gets an empty list and reports a gated edge as
+    // ungated. The `revalidate` half is deliberately not carried: on this edge it repeats these gates,
+    // and the transition dry run is what reports revalidation.
+    const required = requiredGates(spec.to, {
+      reachability: policy?.reachability?.enabled === true,
+      humanAcceptance: policy?.humanAcceptance?.enabled === true,
+      architectureFitness: architectureFitnessActive(policy),
+      userPlay: policy?.userPlay?.enabled === true,
+    });
+    edges.push({ to: spec.to, gates: required?.gates || [] });
+  }
+  for (const [from, to] of UNGATED_FORWARD_EDGES) {
+    if (from !== phase) continue;
+    const gates = conditionalEdgeGates(from, to, policy);
+    edges.push({ to, gates, ungated: gates.length === 0 });
+  }
+  return edges;
+}
+
+/**
+ * The state brief: a derived summary of the state document, small enough to load
+ * every turn.
+ *
+ * WHY THIS EXISTS AND WHAT IT REPLACES. The context plan named `.cadet/state.json`
+ * itself as a tier-0 always-load reference, and that document is not the current
+ * story: it is the current story's live evidence plus append-only lists of every
+ * work item ever closed and every change checkpoint ever recorded. Measured in a
+ * real consumer, it reached 94,547 B — about 31,500 tokens — of which the current
+ * story was 31%, and it is re-sent on every turn. A host that loads it pays for the
+ * project's whole history to answer "what phase am I in".
+ *
+ * WHAT IT CARRIES. Only what the phase reads: the phase and the session settings,
+ * the active work item and its story and epic status, what is left in that epic, the legal
+ * edge out of the current phase with the gates it carries, every gate in the policy with the
+ * newest evidence record for each, the last transition, and how much of the document
+ * compaction would archive. Nothing here is decided twice: every field is read
+ * from the document, and `latestEvidenceForGate` is the same reader a gate check
+ * uses, so the brief cannot disagree with the machinery about which record is live.
+ *
+ * WHAT IT DELIBERATELY OMITS. Evidence record bodies, the coverage index, the
+ * archive and the change log. A reader who needs those opens `.cadet/state.json`;
+ * the brief says so in its own first line. It is a summary, not a second record.
+ *
+ * Pure: no I/O, so a test drives it from a document and a caller decides where it
+ * is written. The resolved work-item paths come IN through `docs`, because finding
+ * them needs the filesystem: the caller resolves them, and this stays a function of
+ * its arguments.
+ */
+export function buildStateBrief(state, policy = null, docs = null) {
+  const s = isPlainObject(state) ? state : {};
+  const session = isPlainObject(s.session) ? s.session : {};
+  const work = isPlainObject(s.activeWorkItem) ? s.activeWorkItem : null;
+  const claimed = isPlainObject(s.gates) ? s.gates : {};
+  const epics = isPlainObject(s.epics) ? s.epics : {};
+
+  const gates = GATES.map((gate) => {
+    const latest = latestEvidenceForGate(s, gate);
+    return {
+      gate,
+      claimed: claimed[gate] === true,
+      status: latest ? latest.status : null,
+      evidenceId: latest ? latest.evidenceId : null,
+      at: latest ? latest.createdAt : null,
+      // WHAT THE RUN COST, so a reader can tell a real red from a command that never launched without
+      // opening the run ledger. Absent on every record written before the fields existed.
+      durationMs: latest && typeof latest.durationMs === 'number' ? latest.durationMs : null,
+      outputBytes: latest && typeof latest.outputBytes === 'number' ? latest.outputBytes : null,
+    };
+  });
+
+  const epic = work?.epicId && isPlainObject(epics[work.epicId]) ? epics[work.epicId] : null;
+  const stories = isPlainObject(epic?.stories) ? epic.stories : {};
+  const storyStatuses = Object.values(stories);
+
+  // WHAT IS LEFT IN THE ACTIVE EPIC, named rather than counted. `Resume` compares state against the
+  // epic markdown story by story, and a count cannot be compared with anything, so the brief names
+  // each story still not `done` with its status. Derived from the same map the counts come from.
+  const remaining = Object.entries(stories)
+    .filter(([, status]) => status !== 'done')
+    .map(([id, status]) => ({ id, status }));
+
+  // The legal edge out of the current phase, and the gates it carries. See `legalEdgesFrom`.
+  const next = legalEdgesFrom(session.currentPhase, policy);
+
+  // What `state compact --keep active` would move, counted by the same two pure
+  // functions compaction itself uses. Reported rather than implied, because the
+  // number growing without bound is the thing nobody notices.
+  const inline = Array.isArray(s.gateEvidence) ? s.gateEvidence.length : 0;
+  const { archived: archivableEvidence } = splitEvidence(s, { keep: 'active' });
+  const historyInline = Array.isArray(s.changeHistory) ? s.changeHistory.length : 0;
+  const { archived: archivableHistory } = compactHistory(
+    (Array.isArray(s.changeHistory) ? s.changeHistory : []).filter((e) => e?.type !== 'gate-exception'),
+  );
+
+  return {
+    workItemId: work ? `${work.epicId}::${work.storyId}` : null,
+    phase: session.currentPhase || null,
+    workflowPath: session.workflowPath || null,
+    trackingMode: session.trackingMode || null,
+    learnerTier: session.learnerTier || null,
+    operatingMode: session.operatingMode || null,
+    story: work?.storyId
+      ? { id: work.storyId, status: stories[work.storyId] || null, at: docs?.story || null }
+      : null,
+    epic: epic
+      ? {
+        id: work.epicId,
+        status: epic.status || null,
+        storiesDone: storyStatuses.filter((v) => v === 'done').length,
+        storiesTotal: storyStatuses.length,
+        remaining,
+        at: docs?.epic || null,
+      }
+      : null,
+    next,
+    gates,
+    evidence: { inline, archivable: archivableEvidence.length, superseded: (Array.isArray(s.gateEvidence) ? s.gateEvidence : []).filter((r) => r?.status === 'superseded').length },
+    history: { inline: historyInline, archivable: archivableHistory.length, entryLimit: HISTORY_ENTRIES_KEPT, charLimit: MAX_HISTORY_ENTRY_CHARS },
+    lastTransition: isPlainObject(s.lastTransition)
+      ? { from: s.lastTransition.from || null, to: s.lastTransition.to || null, at: s.lastTransition.at || null }
+      : null,
+    activeRunId: s.activeRunId || null,
+  };
+}
+
+/** Render a state brief as the text a host loads. */
+export function renderStateBrief(brief) {
+  const b = isPlainObject(brief) ? brief : {};
+  const lines = [];
+
+  lines.push(`state brief — ${b.workItemId || '(no active work item)'}`);
+  lines.push('The tier-0 summary of .cadet/state.json. Open that document for evidence records,');
+  lines.push('the coverage index and the archive; this file carries what the phase reads.');
+  lines.push('');
+  lines.push(`phase: ${b.phase || '(unset)'} · workflow: ${b.workflowPath || '(unset)'} · tracking: ${b.trackingMode || '(unset)'}`);
+  if (b.story) {
+    lines.push(`story: ${b.story.status || '(unset)'}`);
+    // WHERE THE STORY IS. A resume needs the file, and the path is not derivable from the document:
+    // a real project nests its plans, so the host either resolves them (as `harness context plan` does)
+    // or goes looking. The caller resolves and passes it in, which keeps this builder pure.
+    if (b.story.at) lines.push(`  at: ${b.story.at}`);
+  }
+  if (b.epic) {
+    lines.push(`epic: ${b.epic.status || '(unset)'} — ${b.epic.storiesDone} of ${b.epic.storiesTotal} stories done`);
+    if (b.epic.at) lines.push(`  at: ${b.epic.at}`);
+    const remaining = Array.isArray(b.epic.remaining) ? b.epic.remaining : [];
+    if (remaining.length) {
+      lines.push(`  remaining: ${remaining.map((r) => `${r.id} (${r.status || 'unset'})`).join(', ')}`);
+    }
+  }
+  // The edge out of this phase, so the transition dry run confirms a known edge instead of being the
+  // thing that discovers one. A phase with no legal edge (`closed`) prints nothing, which is the fact.
+  for (const edge of (Array.isArray(b.next) ? b.next : [])) {
+    const needs = Array.isArray(edge.gates) && edge.gates.length ? `needs ${edge.gates.join(', ')}` : 'ungated';
+    lines.push(`next: ${b.phase} -> ${edge.to} (${needs})`);
+  }
+  lines.push('');
+  lines.push('gates (the newest evidence record for each)');
+  for (const row of Array.isArray(b.gates) ? b.gates : []) {
+    const state = row.claimed ? 'claimed' : 'UNMET';
+    // The wall clock beside the verdict. This repository's false reds took 182 ms and its genuine Unity
+    // pass takes tens of seconds, so the number is the difference between a test result and a command
+    // that never ran. Omitted when the record does not carry one, rather than shown as zero.
+    const took = typeof row.durationMs === 'number' ? `${Math.round(row.durationMs)} ms  ` : '';
+    const record = row.status
+      ? `${row.status}  ${took}${row.evidenceId || '(no id)'}  ${row.at || ''}`.trimEnd()
+      : '(no evidence)';
+    lines.push(`  ${row.gate.padEnd(27)} ${state.padEnd(9)} ${record}`);
+  }
+  lines.push('');
+  const ev = b.evidence || {};
+  lines.push(`evidence inline: ${ev.inline} record(s), ${ev.superseded} superseded, ${ev.archivable} archivable`);
+  const hist = b.history || {};
+  lines.push(`change log: ${hist.inline} entr(ies), ${hist.archivable} archivable (keeps the most recent ${hist.entryLimit}, or ${hist.charLimit} characters per entry)`);
+  if (ev.archivable || hist.archivable) {
+    lines.push('  archive them with: cadet-agent state compact --keep active');
+  }
+  if (b.lastTransition) {
+    lines.push(`last transition: ${b.lastTransition.from} -> ${b.lastTransition.to} at ${b.lastTransition.at}`);
+  }
+  if (b.activeRunId) lines.push(`active run: ${b.activeRunId}`);
+
+  return `${lines.join('\n')}\n`;
+}
+
 /** Atomically write state.json. */
 export function writeState(targetDir, state) {
   return writeJsonAtomic(statePathFor(targetDir), state);

package/src/harness/verification.mjs

@@ -531,6 +531,11 @@ export async function runVerificationLoop({
           ? `budget-blocked: ${hardStop.reason}`
           : (launch.launchFailed ? `launch-failed: ${launch.reason}` : describeResult(result))),
       exitCode: result.exitCode,
+      // Carried onto the record, not only onto the attempt below it. An operator reading
+      // `gateEvidence` sees how long the command took and how much it wrote, which is how a real red is
+      // told from a command that never launched.
+      durationMs: result.durationMs ?? null,
+      outputBytes: result.outputBytes ?? null,
       artifactPath: result.artifactPath,
       artifactHash: result.artifactHash,
       inputTreeHash,
@@ -687,7 +692,6 @@ export function manualConfirmation({
   gate, workItemId, phase, projectPath, editorVersion, scope, acceptanceCriterionId = null,
   relevantFiles = [], criteria = [], rootDir = process.cwd(), approvedBy = 'user', at = new Date(),
   reason = null, expiresAt = null, environment = null, expiresInMs = null, commit = null,
-  witness = null, limitations = null,
 } = {}) {
   const inputTreeHash = computeInputTreeHash(rootDir, relevantFiles);
   // v3 quality fields. `scope` is declared both as the free-text `result` line
@@ -699,8 +703,6 @@ export function manualConfirmation({
   // Redaction has no bypass (contract §8).
   const scopeList = (Array.isArray(scope) ? scope : (scope ? [scope] : [])).map(redactString);
   const safeReason = reason === null || reason === undefined ? null : redactString(String(reason));
-  const safeWitness = witness === null || witness === undefined ? null : redactString(String(witness));
-  const safeLimitations = limitations === null || limitations === undefined ? null : redactString(String(limitations));
   const env = Object.fromEntries(
     Object.entries(environment || (projectPath || editorVersion
       ? { projectPath: projectPath || null, editorVersion: editorVersion || null }
@@ -740,18 +742,10 @@ export function manualConfirmation({
     ...(safeReason !== null ? { reason: safeReason } : {}),
     ...(hasEnv ? { environment: env } : {}),
     ...(scopeList.length ? { scope: scopeList } : {}),
-    // A human acceptance states what was witnessed and what was accepted as missing.
-    // Both are free prose from a person, so both are redacted like every other field
-    // that reaches state.json. `state` validation requires them for
-    // `humanAcceptanceConfirmed`, which is why they are recorded rather than folded
-    // into `reason`: `reason` says why automation could not answer, these say what the
-    // person actually accepted.
-    ...(safeWitness !== null ? { witness: safeWitness } : {}),
-    ...(safeLimitations !== null ? { limitations: safeLimitations } : {}),
   };
   return {
     evidence, approvedBy, projectPath, editorVersion, scope: scopeList, reason: safeReason,
-    environment: env, witness: safeWitness, limitations: safeLimitations, recordedAt: timestamp(at),
+    environment: env, recordedAt: timestamp(at),
   };
 }