feature-factory 0.8.7 → 0.8.8

package/bin/factory.js

@@ -10,7 +10,7 @@ import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { readFileSync } from "node:fs";
-import { nextAction, readRun, readRunUnchecked } from "../state/index.js";
+import { nextAction, nextActionRecord, readRun, readRunUnchecked } from "../state/index.js";
 import { transition } from "../state/transition.js";
 import { buildEvidence, deriveReviewReady, EVIDENCE_KEYS, evidenceRef, git, observeAncestry, observeCleanliness, observeTrackedCleanliness, observeWorktree, privilegedPaths, proveInitContainment, resolveWorktree, runBootstrap, unownedPaths } from "../observe/index.js";
 import { assertPublicationReady, assertReviewBinding, observeMergeProof, readEvidence, readReview, readValidatorReview } from "../observe/review.js";
@@ -972,12 +972,31 @@ const HANDLERS = {
       pr_draft: run.pr_draft ?? true,
       lock: lock.state, dead_lock: run.status === "running" && lock.state === "stale",
       lock_session: lock.owner?.session ?? null,
-      gates: Object.fromEntries(GATE_NAMES.filter((name) => run.gates[name]).map((name) => [name, run.gates[name].status])),
-      steps: run.steps.map((step) => `${step.agent}:${step.status}(${step.attempts})`),
-      slices: run.slices.map((slice) => `${slice.id}:${slice.status}(${slice.attempts})`),
-      validator: run.validator?.verdict ?? null,
+      // The whole gate record, not just its status. `at` and `artifact` were dropped here while sitting
+      // intact in `run.json` -- and `at` is what tells a controller whether "approved" happened a minute
+      // ago or three hours ago, which is most of what "is this run stuck" means.
+      gates: Object.fromEntries(GATE_NAMES.filter((name) => run.gates[name])
+        .map((name) => [name, { status: run.gates[name].status, at: run.gates[name].at ?? null, artifact: run.gates[name].artifact ?? null }])),
+      // Structured, not `${agent}:${status}(${attempts})`. Attempts are the field a controller reads to
+      // decide whether an attempt was consumed, and reaching them meant regexing a display string out of
+      // a JSON contract. Nothing in the suite asserted the string form, so it was a public shape with no
+      // coverage -- which is how a rendering artifact survived in a machine-readable payload. The content
+      // is unchanged; only the shape is. Breaking for anyone parsing the strings, which is safe here
+      // because an exact-match `FACTORY_VERSION` pin already forces consumers to move deliberately.
+      steps: run.steps.map((step) => ({ agent: step.agent, status: step.status, attempts: step.attempts })),
+      slices: run.slices.map((slice) => ({ id: slice.id, status: slice.status, attempts: slice.attempts })),
+      // Same narrowing: the record carries `report`, `reviewed_head` and `loops`, and only the verdict
+      // came out. `loops` says whether validation is converging; `reviewed_head` says what it judged.
+      validator: run.validator
+        ? { verdict: run.validator.verdict, report: run.validator.report ?? null,
+            reviewed_head: run.validator.reviewed_head ?? null, loops: run.validator.loops ?? null }
+        : null,
       pr_url: run.pr_url,
       terminal_result: run.terminal_result,
+      // Both, deliberately. `next_action` is the machine answer; `next` is its rendering, derived from the
+      // same record by one formatter so they cannot drift, and kept because the driver contract, the
+      // sidebar and a lot of prose name `next: gate:story`.
+      next_action: nextActionRecord(run),
       next: nextAction(run),
     });
   },
@@ -1172,7 +1191,8 @@ const HANDLERS = {
     });
     if (outcome?.refusal) throw new CliError(`${outcome.refusal}; run remains needs-human and its historical terminal result is preserved`);
     return emit(flags, {
-      run_id: runId, status: next.status, terminal_result: next.terminal_result, next: nextAction(next),
+      run_id: runId, status: next.status, terminal_result: next.terminal_result,
+      next_action: nextActionRecord(next), next: nextAction(next),
     });
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-factory",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",

package/state/index.js

@@ -28,11 +28,11 @@ export function readRunUnchecked(runDir) {
 
 function nextSliceAction(slices) {
   const blockedSlice = slices.find((slice) => slice.status === "blocked");
-  if (blockedSlice) return `blocked-slice:${blockedSlice.id}`;
+  if (blockedSlice) return { kind: "blocked-slice", subject: blockedSlice.id };
   const activeSlice = slices.find((slice) => ["running", "review"].includes(slice.status));
-  if (activeSlice) return `observe-slice:${activeSlice.id}`;
+  if (activeSlice) return { kind: "observe-slice", subject: activeSlice.id };
   const pendingSlice = slices.find((slice) => slice.status === "pending");
-  return pendingSlice ? `dispatch-slice:${pendingSlice.id}` : undefined;
+  return pendingSlice ? { kind: "dispatch-slice", subject: pendingSlice.id } : undefined;
 }
 
 // The single answer to "what happens next". Both `factory status` and the opencode
@@ -42,23 +42,35 @@ function nextSliceAction(slices) {
 // Resume: the first thing a returning session needs to know. Preserves the inherited
 // rules: a pending gate re-presents, a running slice re-observes, an
 // unaccepted step re-runs.
-export function nextAction(run) {
-  if (["completed", "partial", "blocked"].includes(run.status)) return `terminal:${run.status}`;
+// `{kind, subject}`, because the answer is two facts and a consumer that must split a string on `:` to
+// recover them is parsing a rendering. `subject` is null for the kinds that name no target.
+export function nextActionRecord(run) {
+  if (["completed", "partial", "blocked"].includes(run.status)) return { kind: "terminal", subject: run.status };
   const openStep = run.steps.find((step) => step.status !== "accepted");
+  const stepAction = openStep ? { kind: "step", subject: openStep.agent } : null;
   const sliceAction = nextSliceAction(run.slices);
   for (const name of GATE_NAMES) {
     const gate = run.gates[name];
     // `pending` waits on a human; absent means the phase has not been reached, which is
     // still not "done". But naming an absent gate while an agent is mid-round reads as
     // "waiting on you" — so existing slice or step work is named instead.
-    if (gate === undefined) return sliceAction ?? (openStep ? `step:${openStep.agent}` : `gate:${name}`);
-    if (gate.status === "pending") return `gate:${name}`;
-    if (gate.status === "stop") return `stopped-at-gate:${name}`;
-    if (gate.status === "changes") return `changes-at-gate:${name}`;
-    if (name === "brief" && gate.status === "approved" && run.slices.length === 0) return "seed-slices";
+    if (gate === undefined) return sliceAction ?? stepAction ?? { kind: "gate", subject: name };
+    if (gate.status === "pending") return { kind: "gate", subject: name };
+    if (gate.status === "stop") return { kind: "stopped-at-gate", subject: name };
+    if (gate.status === "changes") return { kind: "changes-at-gate", subject: name };
+    if (name === "brief" && gate.status === "approved" && run.slices.length === 0) return { kind: "seed-slices", subject: null };
   }
   if (sliceAction) return sliceAction;
-  if (openStep) return `step:${openStep.agent}`;
-  if (!run.pr_url) return "pr";
-  return "complete";
+  if (stepAction) return stepAction;
+  if (!run.pr_url) return { kind: "pr", subject: null };
+  return { kind: "complete", subject: null };
+}
+
+// The string form is DERIVED from the record rather than computed beside it, so the two cannot disagree.
+// Retained because the driver contract, the sidebar and a great deal of prose all name `next: gate:story`,
+// and because a human-facing label is a fair thing for a CLI to keep -- as long as it is a projection of
+// the structured answer and not a second implementation of it.
+export function nextAction(run) {
+  const { kind, subject } = nextActionRecord(run);
+  return subject === null ? kind : `${kind}:${subject}`;
 }