@gr8ful/spf 0.1.6 → 0.2.1

package/dist/chains/{adw_simple_sdlc.js → simple_sdlc.js}

@@ -1,5 +1,5 @@
 /**
- * ADW Simple SDLC — plan, build, test, review, document, committing as it goes.
+ * Simple SDLC — plan, build, test, review, document, committing as it goes.
  *
  * Usage:
  *   spf simple-sdlc "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
@@ -36,39 +36,32 @@
  * The documenter measures against the commit this run STARTED from, not against
  * `main`, because by then the run has moved `main` itself. That baseline is
  * pinned before the first commit phase and printed in the request phase.
+ *
+ * This is the one chain still shaped by hand rather than by a `steps` list —
+ * three commits, a pinned baseline, and a conditional retest don't collapse
+ * cleanly into the flat, loop-free vocabulary `./steps.ts` provides for every
+ * other chain. It still reuses that module's shared helpers (`startRun`,
+ * `commitEnvelope`, `logChangeset`) rather than keeping its own copies.
  */
-import * as agents from "../core/agents.js";
 import * as changes from "../core/changes.js";
 import * as gates from "../core/gates.js";
 import * as quality from "../core/quality.js";
-import * as session from "../core/session.js";
+import { DOCUMENT_NOTES } from "../core/prompts.js";
+import { commitEnvelope, logChangeset, startRun } from "./steps.js";
 import { BuildOutput, DocumentOutput, PlanOutput, ReviewOutput, makeAgentCall, makeChangeCapture, makePhaseParams, } from "../core/data_types.js";
 export const REQUIRED_AGENTS = ["planner", "builder", "reviewer", "documenter"];
 export const REQUIRED_SUITES = ["test"];
 const MAX_FIX_LOOPS = 3;
 const MAX_REVISION_LOOPS = 2;
-const DOCUMENT_NOTES = "Read diff_path in full before writing. Document only what the diff shows, then copy the write-up into app_docs/ as your task describes.";
-/** Commit what the preceding phase produced, in that agent's own words. */
-function commit(run, ph, envelope) {
-    const message = envelope.commit_message || `spf(${run.adw_id}): ${envelope.summary}`;
-    ph.log({ sha: run.git.commitAll(message), message });
-}
-/** Log a deterministic block's verdict — the same shape every ADW uses. */
-function record(ph, result) {
-    const passed = result.checks.filter((c) => c.passed).length;
-    ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
-}
 export async function main(ctx) {
-    const { prompt, config_paths, adw_id, cwd } = ctx;
-    const cfg = agents.loadConfig(config_paths);
-    agents.validate(cfg, REQUIRED_AGENTS, REQUIRED_SUITES, cwd);
-    const run = session.ensure(cfg, adw_id, cwd);
+    const { prompt } = ctx;
+    const run = startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
     const baseline = run.git.rev("HEAD"); // pinned before this run commits anything
     await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
         ph.log({ input: prompt, baseline: run.git.shortSha(baseline) });
     });
     const plan = await run.phase(makePhaseParams({ name: "plan", kind: "agent", owner: "planner", description: "Turn the request into an implementable plan" }), (ph) => ph.call(makeAgentCall({ output_type: PlanOutput, prompt, gates: [gates.artifactsExist, gates.filesNonEmpty] })));
-    await run.phase(makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "Put the spec on record before any code exists to blur it" }), async (ph) => commit(run, ph, plan));
+    await run.phase(makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "Put the spec on record before any code exists to blur it" }), async (ph) => commitEnvelope(run, ph, plan));
     let build = await run.phase(makePhaseParams({ name: "build", kind: "agent", owner: "builder", description: "Implement the plan exactly" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: plan, gates: [gates.diffMatchesClaims] })));
     let test = null;
     for (let i = 1; i <= MAX_FIX_LOOPS; i++) {
@@ -79,11 +72,13 @@ export async function main(ctx) {
             description: "Run the suite — a known command, so code runs it and no agent has to rediscover it",
         }), async (ph) => {
             const result = quality.runTests(run);
-            record(ph, result);
+            quality.record(ph, result);
             return result;
         });
         if (test.passed)
             break;
+        if (i === MAX_FIX_LOOPS)
+            break; // never leave an unverified fix on the table
         build = await run.phase(makePhaseParams({
             name: `fix_${i}`,
             kind: "agent",
@@ -111,7 +106,7 @@ export async function main(ctx) {
             description: "Re-run the suite — the revision changed code after the last green result",
         }), async (ph) => {
             const result = quality.runTests(run);
-            record(ph, result);
+            quality.record(ph, result);
             return result;
         });
     }
@@ -120,16 +115,10 @@ export async function main(ctx) {
     // describing yet. The plan commit stands — it is a record of what was asked.
     const verified = test !== null && test.passed && review !== null && review.approved;
     if (verified) {
-        await run.phase(makePhaseParams({ name: "commit_build", kind: "code", owner: "git", description: "Land the code only now: green suite, approved review" }), async (ph) => commit(run, ph, build));
+        await run.phase(makePhaseParams({ name: "commit_build", kind: "code", owner: "git", description: "Land the code only now: green suite, approved review" }), async (ph) => commitEnvelope(run, ph, build));
         const changeset = await run.phase(makePhaseParams({ name: "changes", kind: "code", owner: "git", description: "Diff the whole run against its pinned baseline, for the documenter" }), async (ph) => {
             const result = changes.capture(run, makeChangeCapture({ base: baseline }));
-            ph.log({
-                base: `${result.base.label} @ ${result.base.commit.slice(0, 7)}`,
-                reason: result.base.reason,
-                files: result.files.length + result.untracked.length,
-                lines: `+${result.insertions} -${result.deletions}`,
-                diff: result.diff_path,
-            });
+            logChangeset(ph, result);
             if (result.empty) {
                 throw new Error(`nothing changed since ${result.base.label} (${result.base.reason}) — there is nothing to document.`);
             }
@@ -141,7 +130,7 @@ export async function main(ctx) {
             previous: changes.asEnvelope(changeset, DOCUMENT_NOTES),
             gates: [gates.artifactsExist, gates.filesNonEmpty],
         })));
-        await run.phase(makePhaseParams({ name: "commit_docs", kind: "code", owner: "git", description: "Ship the write-up in its own commit, beside the code it describes" }), async (ph) => commit(run, ph, document));
+        await run.phase(makePhaseParams({ name: "commit_docs", kind: "code", owner: "git", description: "Ship the write-up in its own commit, beside the code it describes" }), async (ph) => commitEnvelope(run, ph, document));
     }
     return run.finish(verified, "the suite or the review never came back clean");
 }

package/dist/chains/steps.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Step primitives: named, reusable pieces of chain composition.
+ *
+ * Every chain used to be a hand-written module repeating the same prologue,
+ * the same `request` phase, and — where chains overlapped — byte-identical
+ * `plan`/`build`/test-fix/review-revise/commit phases. This file is that
+ * code, extracted once: a `Step` is one `run.phase(...)` call (or a small
+ * bounded group of them) lifted out verbatim and parameterized only where
+ * the chains genuinely differed.
+ *
+ * A Step reads and writes a shared `ChainState` — the local variables a
+ * hand-written chain would otherwise thread from one `run.phase` call to the
+ * next (the last envelope, the last quality result, whether the run is
+ * accepted). Composing a chain is then an ordered array of Steps.
+ *
+ * The loops (`fixLoop`, `reviseLoop`) own their bounded iteration and dynamic
+ * phase naming (`test_1`, `fix_1`, ...) INTERNALLY — a chain's step list is
+ * therefore always flat, with no loop or conditional syntax at the
+ * composition layer. That is what would make a future declarative (YAML)
+ * chain tractable: it would only ever need to name steps and pass them
+ * tuning params, never express control flow.
+ */
+import { type EnvelopeBase, type QualityResult, type ReviewOutputT } from "../core/data_types.ts";
+import type { ChangeSet } from "../core/data_types.ts";
+import { Run, type PhaseHandle } from "../core/runner.ts";
+import type { ChainContext } from "./context.ts";
+/** What one step hands the next — the parts of a hand-written chain's local variables. */
+export interface ChainState {
+    prompt: string;
+    options: Record<string, string>;
+    /** The last agent envelope produced — what the next agent step feeds forward as `previous`. */
+    previous: EnvelopeBase | null;
+    quality: QualityResult | null;
+    review: ReviewOutputT | null;
+    changeset: ChangeSet | null;
+    /** HEAD, pinned by request({logBaseline: true}) before the run commits anything. */
+    baseline: string;
+    /** The run's own acceptance criterion — distinct from "every phase succeeded"; see Run.finish(). */
+    accepted: boolean;
+    /** Why not, when accepted is false — passed straight to run.finish(). */
+    reason: string;
+}
+/**
+ * One phase (or a small bounded group of them). Callable like a plain
+ * function; the optional properties are how a step declares what it needs
+ * so `deriveRequiredAgents`/`deriveRequiredSuites`/`derivePhases` can build
+ * `ChainDefinition.requiredAgents`/`requiredSuites`/`phases` from a step list
+ * instead of those being a second, separately maintained set of exports.
+ */
+export interface Step {
+    (run: Run, state: ChainState): Promise<void>;
+    requiredAgents?: string[] | ((options: Record<string, string>) => string[]);
+    requiredSuites?: string[];
+    /** Display fragment for derivePhases() — e.g. "planner", "git(commit)". */
+    label?: string;
+}
+/** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
+export declare function startRun(ctx: ChainContext, requiredAgents: string[], requiredSuites: string[]): Run;
+/** Commit an envelope in its own author's words — the message-fallback four chains repeated. */
+export declare function commitEnvelope(run: Run, ph: PhaseHandle, envelope: EnvelopeBase & {
+    commit_message?: string;
+}): void;
+/** Log a change-capture result the same way every chain that captures one did. */
+export declare function logChangeset(ph: PhaseHandle, result: ChangeSet): void;
+/** The engineer(request) phase every chain opens with. */
+export declare function request(opts?: {
+    description?: string;
+    logBaseline?: boolean;
+}): Step;
+export declare function plan(): Step;
+/**
+ * `fromPlan` only changes the description — whether a plan() step precedes
+ * this one already decides whether `state.previous` is a plan or null, so
+ * there is nothing else for this flag to gate.
+ */
+export declare function build(opts?: {
+    fromPlan?: boolean;
+    retries?: number;
+}): Step;
+export declare function scout(): Step;
+/** The `prompt` chain's one step: --agent picks who, at run time and at requiredAgents-derivation time alike. */
+export declare function promptOnly(): Step;
+/** One deterministic quality block, standalone — never throws; sets state.accepted for run.finish() to check. */
+export declare function qualityCheck(opts?: {
+    suite: "test" | "all";
+    description?: string;
+}): Step;
+/**
+ * Bounded check -> fix loop: a known command finds the failure, the builder
+ * repairs it. Always guards the last iteration — a fix on the final attempt
+ * is never re-verified, so it is never spawned. Sets state.accepted/reason.
+ */
+export declare function fixLoop(opts?: {
+    suite: "test" | "all";
+    max?: number;
+    owner?: string;
+}): Step;
+/** Bounded review -> revise loop. Sets state.accepted/reason from the final verdict. */
+export declare function reviseLoop(opts?: {
+    max?: number;
+}): Step;
+/** Commit the last agent step's envelope. `onlyIfAccepted` gates it on state.accepted (a preceding fixLoop/reviseLoop). */
+export declare function commit(opts?: {
+    onlyIfAccepted?: boolean;
+}): Step;
+/** Diff the working tree against a base ref — code, not judgement. `--base` (default "main") if opts.base is unset. */
+export declare function changes(opts?: {
+    base?: string;
+}): Step;
+/** Write up the captured change. Requires a preceding changes() step. */
+export declare function document(): Step;
+export declare function deriveRequiredAgents(steps: Step[]): string[] | ((options: Record<string, string>) => string[]);
+export declare function deriveRequiredSuites(steps: Step[]): string[];
+/** A display string for `spf list` — derived so it can no longer drift from what actually runs. */
+export declare function derivePhases(steps: Step[]): string;
+/** Run a chain's step list start to finish: prologue, every step in order, then run.finish(). */
+export declare function runSteps(ctx: ChainContext, requiredAgents: string[], requiredSuites: string[], steps: Step[], options?: Record<string, string>): Promise<number>;

package/dist/chains/steps.js

@@ -0,0 +1,299 @@
+/**
+ * Step primitives: named, reusable pieces of chain composition.
+ *
+ * Every chain used to be a hand-written module repeating the same prologue,
+ * the same `request` phase, and — where chains overlapped — byte-identical
+ * `plan`/`build`/test-fix/review-revise/commit phases. This file is that
+ * code, extracted once: a `Step` is one `run.phase(...)` call (or a small
+ * bounded group of them) lifted out verbatim and parameterized only where
+ * the chains genuinely differed.
+ *
+ * A Step reads and writes a shared `ChainState` — the local variables a
+ * hand-written chain would otherwise thread from one `run.phase` call to the
+ * next (the last envelope, the last quality result, whether the run is
+ * accepted). Composing a chain is then an ordered array of Steps.
+ *
+ * The loops (`fixLoop`, `reviseLoop`) own their bounded iteration and dynamic
+ * phase naming (`test_1`, `fix_1`, ...) INTERNALLY — a chain's step list is
+ * therefore always flat, with no loop or conditional syntax at the
+ * composition layer. That is what would make a future declarative (YAML)
+ * chain tractable: it would only ever need to name steps and pass them
+ * tuning params, never express control flow.
+ */
+import * as changesLib from "../core/changes.js";
+import * as gates from "../core/gates.js";
+import * as quality from "../core/quality.js";
+import * as agentsCfg from "../core/agents.js";
+import * as session from "../core/session.js";
+import { DOCUMENT_NOTES } from "../core/prompts.js";
+import { BuildOutput, DocumentOutput, GenericOutput, PlanOutput, ReviewOutput, ScoutOutput, makeAgentCall, makeChangeCapture, makePhaseParams, } from "../core/data_types.js";
+import { Run } from "../core/runner.js";
+function makeState(prompt, options) {
+    return { prompt, options, previous: null, quality: null, review: null, changeset: null, baseline: "", accepted: true, reason: "" };
+}
+function makeStep(fn, meta = {}) {
+    const step = fn;
+    step.requiredAgents = meta.requiredAgents;
+    step.requiredSuites = meta.requiredSuites;
+    step.label = meta.label;
+    return step;
+}
+// ── layer 1: the shared prologue ────────────────────────────────────────
+/** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
+export function startRun(ctx, requiredAgents, requiredSuites) {
+    const cfg = agentsCfg.loadConfig(ctx.config_paths);
+    agentsCfg.validate(cfg, requiredAgents, requiredSuites, ctx.cwd);
+    return session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name);
+}
+/** Commit an envelope in its own author's words — the message-fallback four chains repeated. */
+export function commitEnvelope(run, ph, envelope) {
+    const message = envelope.commit_message || `spf(${run.adw_id}): ${envelope.summary}`;
+    ph.log({ sha: run.git.commitAll(message), message });
+}
+/** Log a change-capture result the same way every chain that captures one did. */
+export function logChangeset(ph, result) {
+    ph.log({
+        base: `${result.base.label} @ ${result.base.commit.slice(0, 7)}`,
+        reason: result.base.reason,
+        files: result.files.length + result.untracked.length,
+        lines: `+${result.insertions} -${result.deletions}`,
+        diff: result.diff_path,
+    });
+}
+// ── layer 2: step factories ──────────────────────────────────────────────
+/** The engineer(request) phase every chain opens with. */
+export function request(opts = {}) {
+    const fn = async (run, state) => {
+        if (opts.logBaseline)
+            state.baseline = run.git.rev("HEAD");
+        await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: opts.description ?? "Capture the incoming ask" }), async (ph) => {
+            const payload = { input: state.prompt };
+            if (opts.logBaseline)
+                payload.baseline = run.git.shortSha(state.baseline);
+            ph.log(payload);
+        });
+    };
+    return makeStep(fn, { label: "engineer(request)" });
+}
+/** One agent phase: prompt in, typed envelope out, `previous` is whatever the prior step left in state. */
+function agentStep(opts) {
+    const fn = async (run, state) => {
+        const envelope = await run.phase(makePhaseParams({ name: opts.name, kind: "agent", owner: opts.owner, description: opts.description, retries: opts.retries ?? 0 }), (ph) => ph.call(makeAgentCall({ output_type: opts.output_type, prompt: state.prompt, previous: state.previous, gates: opts.gates ?? [] })));
+        state.previous = envelope;
+    };
+    return makeStep(fn, { requiredAgents: [opts.owner], label: opts.label ?? opts.owner });
+}
+export function plan() {
+    return agentStep({
+        name: "plan",
+        owner: "planner",
+        output_type: PlanOutput,
+        description: "Turn the request into an implementable plan",
+        gates: [gates.artifactsExist, gates.filesNonEmpty],
+    });
+}
+/**
+ * `fromPlan` only changes the description — whether a plan() step precedes
+ * this one already decides whether `state.previous` is a plan or null, so
+ * there is nothing else for this flag to gate.
+ */
+export function build(opts = {}) {
+    const fromPlan = opts.fromPlan ?? true;
+    return agentStep({
+        name: "build",
+        owner: "builder",
+        output_type: BuildOutput,
+        description: fromPlan ? "Implement the plan exactly" : "Implement the request",
+        gates: [gates.diffMatchesClaims],
+        retries: opts.retries ?? 0,
+    });
+}
+export function scout() {
+    return agentStep({
+        name: "scout",
+        owner: "scout",
+        output_type: ScoutOutput,
+        description: "Find and report where things live — change nothing",
+        gates: [gates.artifactsExist],
+    });
+}
+/** The `prompt` chain's one step: --agent picks who, at run time and at requiredAgents-derivation time alike. */
+export function promptOnly() {
+    const fn = async (run, state) => {
+        const owner = state.options["agent"] ?? "builder";
+        const envelope = await run.phase(makePhaseParams({ name: "prompt", kind: "agent", owner, description: `Send the request straight to ${owner} and parse its envelope` }), (ph) => ph.call(makeAgentCall({ output_type: GenericOutput, prompt: state.prompt, previous: state.previous })));
+        state.previous = envelope;
+    };
+    return makeStep(fn, { requiredAgents: (options) => [options["agent"] ?? "builder"], label: "<agent>" });
+}
+/** One deterministic quality block, standalone — never throws; sets state.accepted for run.finish() to check. */
+export function qualityCheck(opts = { suite: "all" }) {
+    const fn = async (run, state) => {
+        await run.phase(makePhaseParams({
+            name: opts.suite === "all" ? "quality" : "test",
+            kind: "code",
+            owner: "quality",
+            description: opts.description ??
+                (opts.suite === "all" ? "Run the deterministic quality blocks" : "Run the suite — a known command, so code runs it and no agent has to rediscover it"),
+        }), async (ph) => {
+            const result = opts.suite === "all" ? quality.runQuality(run) : quality.runTests(run);
+            quality.record(ph, result);
+            state.quality = result;
+            state.accepted = result.passed;
+            state.reason = result.passed ? "" : `quality failed: ${result.failures.join("; ")}`;
+        });
+    };
+    return makeStep(fn, { requiredSuites: [opts.suite], label: opts.suite === "all" ? "code(quality)" : "code(test)" });
+}
+/**
+ * Bounded check -> fix loop: a known command finds the failure, the builder
+ * repairs it. Always guards the last iteration — a fix on the final attempt
+ * is never re-verified, so it is never spawned. Sets state.accepted/reason.
+ */
+export function fixLoop(opts = { suite: "test" }) {
+    const max = opts.max ?? 3;
+    const owner = opts.owner ?? "builder";
+    const stepName = opts.suite === "all" ? "verify" : "test";
+    const what = opts.suite === "all" ? "verification" : "tests";
+    const fn = async (run, state) => {
+        let result = null;
+        for (let i = 1; i <= max; i++) {
+            result = await run.phase(makePhaseParams({
+                name: `${stepName}_${i}`,
+                kind: "code",
+                owner: "quality",
+                description: opts.suite === "all"
+                    ? "Lint, typecheck, and build before testing"
+                    : "Run the suite — a known command, so code runs it and no agent has to rediscover it",
+            }), async (ph) => {
+                const r = opts.suite === "all" ? quality.runQuality(run) : quality.runTests(run);
+                quality.record(ph, r);
+                return r;
+            });
+            if (result.passed)
+                break;
+            if (i === max)
+                break; // never leave an unverified fix on the table
+            state.previous = await run.phase(makePhaseParams({ name: `fix_${i}`, kind: "agent", owner, retries: 1, description: "Repair what the suite reported, from its verbatim output" }), (ph) => ph.call(makeAgentCall({
+                output_type: BuildOutput,
+                prompt: state.prompt,
+                previous: quality.asEnvelope(result, what),
+                gates: [gates.diffMatchesClaims],
+            })));
+        }
+        state.quality = result;
+        state.accepted = result !== null && result.passed;
+        state.reason = state.accepted ? "" : `the suite still failed after ${max} fix attempt(s)`;
+    };
+    return makeStep(fn, {
+        requiredAgents: [owner],
+        requiredSuites: [opts.suite],
+        label: `code(${stepName}) [-> ${owner}(fix) -> code(${stepName}) ...] bounded`,
+    });
+}
+/** Bounded review -> revise loop. Sets state.accepted/reason from the final verdict. */
+export function reviseLoop(opts = {}) {
+    const max = opts.max ?? 3;
+    const fn = async (run, state) => {
+        let review = null;
+        for (let i = 1; i <= max; i++) {
+            review = await run.phase(makePhaseParams({ name: `review_${i}`, kind: "agent", owner: "reviewer", description: "Rule on every requirement in the spec, against the code on disk" }), (ph) => ph.call(makeAgentCall({ output_type: ReviewOutput, prompt: state.prompt, previous: state.previous, gates: [gates.artifactsExist, gates.verdictConsistent] })));
+            if (review.approved || i === max)
+                break;
+            state.previous = await run.phase(makePhaseParams({ name: `revise_${i}`, kind: "agent", owner: "builder", retries: 1, description: "Close every blocking finding the reviewer named" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt: state.prompt, previous: review, gates: [gates.diffMatchesClaims] })));
+        }
+        state.review = review;
+        state.accepted = review !== null && review.approved;
+        state.reason = state.accepted ? "" : `the reviewer never approved after ${max} revision(s)`;
+    };
+    return makeStep(fn, { requiredAgents: ["reviewer", "builder"], label: "reviewer [-> builder(revise) -> reviewer ...] bounded" });
+}
+/** Commit the last agent step's envelope. `onlyIfAccepted` gates it on state.accepted (a preceding fixLoop/reviseLoop). */
+export function commit(opts = {}) {
+    const fn = async (run, state) => {
+        if (opts.onlyIfAccepted && !state.accepted)
+            return;
+        if (!state.previous)
+            throw new Error("commit() has nothing to commit — no preceding agent step produced an envelope");
+        await run.phase(makePhaseParams({
+            name: "commit",
+            kind: "code",
+            owner: "git",
+            description: opts.onlyIfAccepted
+                ? "Land the code only after the suite came back green"
+                : "Land the builder's changes, using the message it wrote",
+        }), async (ph) => commitEnvelope(run, ph, state.previous));
+    };
+    return makeStep(fn, { label: "git(commit)" });
+}
+/** Diff the working tree against a base ref — code, not judgement. `--base` (default "main") if opts.base is unset. */
+export function changes(opts = {}) {
+    const fn = async (run, state) => {
+        const base = opts.base ?? state.options["base"] ?? "main";
+        const changeset = await run.phase(makePhaseParams({ name: "changes", kind: "code", owner: "git", description: `Diff the working tree against ${base} — the change to be written up` }), async (ph) => {
+            const result = changesLib.capture(run, makeChangeCapture({ base }));
+            logChangeset(ph, result);
+            if (result.empty) {
+                throw new Error(`nothing changed since ${result.base.label} (${result.base.reason}) — documenting runs after a build. ` +
+                    `Build something first, or point --base at the ref the work should be measured from.`);
+            }
+            return result;
+        });
+        state.changeset = changeset;
+    };
+    return makeStep(fn, { label: "code(changes)" });
+}
+/** Write up the captured change. Requires a preceding changes() step. */
+export function document() {
+    const fn = async (run, state) => {
+        if (!state.changeset)
+            throw new Error("document() requires a preceding changes() step in the chain's step list");
+        const envelope = await run.phase(makePhaseParams({ name: "document", kind: "agent", owner: "documenter", retries: 1, description: "Turn the captured diff into a write-up an engineer can read" }), (ph) => ph.call(makeAgentCall({
+            output_type: DocumentOutput,
+            prompt: state.prompt,
+            previous: changesLib.asEnvelope(state.changeset, DOCUMENT_NOTES),
+            gates: [gates.artifactsExist, gates.filesNonEmpty],
+        })));
+        state.previous = envelope;
+    };
+    return makeStep(fn, { requiredAgents: ["documenter"], label: "documenter" });
+}
+// ── layer 3: derive ChainDefinition fields from a step list ─────────────
+export function deriveRequiredAgents(steps) {
+    const dynamicSteps = steps.filter((s) => typeof s.requiredAgents === "function");
+    const staticSteps = steps.filter((s) => Array.isArray(s.requiredAgents));
+    if (dynamicSteps.length === 0) {
+        return [...new Set(staticSteps.flatMap((s) => s.requiredAgents))];
+    }
+    return (options) => {
+        const set = new Set();
+        for (const s of staticSteps)
+            for (const a of s.requiredAgents)
+                set.add(a);
+        for (const s of dynamicSteps)
+            for (const a of s.requiredAgents(options))
+                set.add(a);
+        return [...set];
+    };
+}
+export function deriveRequiredSuites(steps) {
+    const set = new Set();
+    for (const s of steps)
+        for (const suite of s.requiredSuites ?? [])
+            set.add(suite);
+    return [...set];
+}
+/** A display string for `spf list` — derived so it can no longer drift from what actually runs. */
+export function derivePhases(steps) {
+    return steps.map((s) => s.label ?? "?").join(" -> ");
+}
+// ── the driver ────────────────────────────────────────────────────────────
+/** Run a chain's step list start to finish: prologue, every step in order, then run.finish(). */
+export async function runSteps(ctx, requiredAgents, requiredSuites, steps, options = {}) {
+    const run = startRun(ctx, requiredAgents, requiredSuites);
+    const state = makeState(ctx.prompt, options);
+    for (const step of steps) {
+        await step(run, state);
+    }
+    return run.finish(state.accepted, state.reason);
+}

package/dist/cli/ask.d.ts

@@ -0,0 +1,27 @@
+export interface SelectChoice<T extends string> {
+    value: T;
+    label?: string;
+    hint?: string;
+}
+export interface Asker {
+    text(label: string, opts?: {
+        default?: string;
+        validate?: (value: string) => string | null;
+    }): Promise<string>;
+    select<T extends string>(label: string, choices: SelectChoice<T>[], dflt: T): Promise<T>;
+    confirm(label: string, dflt: boolean): Promise<boolean>;
+    /** Echo-suppressed. `current` (if any) is shown masked; an empty answer keeps it and resolves to `""`. */
+    secret(label: string, opts?: {
+        current?: string;
+    }): Promise<string>;
+    note(text: string): void;
+    heading(text: string): void;
+    close(): void;
+}
+/** `stdin.isTTY` is what actually matters (the interview reads it) — `stdout.isTTY` alone, this repo's only prior TTY check (`src/ui/server/serve.ts:88`), would let a piped-in `spf init` hang waiting on input that will never arrive. */
+export declare function isInteractive(): boolean;
+/** Thrown when the user interrupts (Ctrl-C) or stdin closes (EOF) mid-interview. `initCommand` catches this and exits 130, writing nothing. */
+export declare class InterviewAborted extends Error {
+    constructor();
+}
+export declare function createAsker(): Asker;