@gr8ful/spf 0.1.7 → 0.3.0

package/dist/chains/index.js

@@ -1,111 +1,68 @@
-import * as adwPrompt from "./adw_prompt.js";
-import * as adwScout from "./adw_scout.js";
-import * as adwPlan from "./adw_plan.js";
-import * as adwBuild from "./adw_build.js";
-import * as adwPlanBuild from "./adw_plan_build.js";
-import * as adwBuildTest from "./adw_build_test.js";
-import * as adwPlanBuildTest from "./adw_plan_build_test.js";
-import * as adwPlanBuildTestQuality from "./adw_plan_build_test_quality.js";
-import * as adwBuildReview from "./adw_build_review.js";
-import * as adwQuality from "./adw_quality.js";
-import * as adwDocument from "./adw_document.js";
-import * as adwSimpleSdlc from "./adw_simple_sdlc.js";
+import * as steps from "./steps.js";
+import * as simpleSdlc from "./simple_sdlc.js";
+/** Build a step-based ChainDefinition, deriving phases/requiredAgents/requiredSuites from its steps. */
+function stepChain(name, describe, list) {
+    return {
+        name,
+        describe,
+        phases: steps.derivePhases(list),
+        requiredAgents: steps.deriveRequiredAgents(list),
+        requiredSuites: steps.deriveRequiredSuites(list),
+        steps: list,
+    };
+}
 export const CHAINS = [
-    {
-        name: "prompt",
-        describe: "one agent, one prompt, traced end to end — --agent <name> picks who (default: builder)",
-        phases: "engineer(request) -> <agent>",
-        requiredAgents: (options) => [options["agent"] ?? "builder"],
-        requiredSuites: [],
-        run: adwPrompt.main,
-    },
-    {
-        name: "scout",
-        describe: "read-only recon; nothing changes",
-        phases: "engineer(request) -> scout",
-        requiredAgents: adwScout.REQUIRED_AGENTS,
-        requiredSuites: adwScout.REQUIRED_SUITES,
-        run: adwScout.main,
-    },
-    {
-        name: "plan",
-        describe: "turn a request into an implementable plan",
-        phases: "engineer(request) -> planner",
-        requiredAgents: adwPlan.REQUIRED_AGENTS,
-        requiredSuites: adwPlan.REQUIRED_SUITES,
-        run: adwPlan.main,
-    },
-    {
-        name: "build",
-        describe: "implement an existing plan",
-        phases: "engineer(request) -> builder",
-        requiredAgents: adwBuild.REQUIRED_AGENTS,
-        requiredSuites: adwBuild.REQUIRED_SUITES,
-        run: adwBuild.main,
-    },
-    {
-        name: "plan-build",
-        describe: "small, well-understood work — plan, build, commit",
-        phases: "engineer(request) -> planner -> builder -> git(commit)",
-        requiredAgents: adwPlanBuild.REQUIRED_AGENTS,
-        requiredSuites: adwPlanBuild.REQUIRED_SUITES,
-        run: adwPlanBuild.main,
-    },
-    {
-        name: "build-test",
-        describe: "there is a suite to satisfy — build, test, bounded fix loop",
-        phases: "engineer(request) -> builder -> code(test) [-> builder(fix) -> code(test) ...]",
-        requiredAgents: adwBuildTest.REQUIRED_AGENTS,
-        requiredSuites: adwBuildTest.REQUIRED_SUITES,
-        run: adwBuildTest.main,
-    },
-    {
-        name: "plan-build-test",
-        describe: "the standard chain — plan, build, test, commit",
-        phases: "engineer(request) -> planner -> builder -> code(test) [-> fix loop] -> git(commit)",
-        requiredAgents: adwPlanBuildTest.REQUIRED_AGENTS,
-        requiredSuites: adwPlanBuildTest.REQUIRED_SUITES,
-        run: adwPlanBuildTest.main,
-    },
-    {
-        name: "plan-build-test-quality",
-        describe: "the repo has quality commands worth enforcing beyond tests — same, plus lint/typecheck/build gates",
-        phases: "engineer(request) -> planner -> builder -> code(quality:all) [-> fix loop] -> git(commit)",
-        requiredAgents: adwPlanBuildTestQuality.REQUIRED_AGENTS,
-        requiredSuites: adwPlanBuildTestQuality.REQUIRED_SUITES,
-        run: adwPlanBuildTestQuality.main,
-    },
-    {
-        name: "build-review",
-        describe: "\"is this what was asked for\" matters more than \"does it run\"",
-        phases: "engineer(request) -> builder -> reviewer [-> revise loop]",
-        requiredAgents: adwBuildReview.REQUIRED_AGENTS,
-        requiredSuites: adwBuildReview.REQUIRED_SUITES,
-        run: adwBuildReview.main,
-    },
-    {
-        name: "quality",
-        describe: "lint, typecheck, build — no agents at all",
-        phases: "engineer(request) -> code(quality:all)",
-        requiredAgents: adwQuality.REQUIRED_AGENTS,
-        requiredSuites: adwQuality.REQUIRED_SUITES,
-        run: adwQuality.main,
-    },
-    {
-        name: "document",
-        describe: "write up the work that was just done, from the diff",
-        phases: "engineer(request) -> code(changes) -> documenter",
-        requiredAgents: adwDocument.REQUIRED_AGENTS,
-        requiredSuites: adwDocument.REQUIRED_SUITES,
-        run: adwDocument.main,
-    },
+    stepChain("prompt", "one agent, one prompt, traced end to end — --agent <name> picks who (default: builder)", [
+        steps.request(),
+        steps.promptOnly(),
+    ]),
+    stepChain("scout", "read-only recon; nothing changes", [steps.request(), steps.scout()]),
+    stepChain("plan", "turn a request into an implementable plan", [steps.request(), steps.plan()]),
+    stepChain("build", "implement an existing plan", [steps.request(), steps.build({ fromPlan: false, retries: 1 })]),
+    stepChain("plan-build", "small, well-understood work — plan, build, commit", [
+        steps.request(),
+        steps.plan(),
+        steps.build(),
+        steps.commit(),
+    ]),
+    stepChain("build-test", "there is a suite to satisfy — build, test, bounded fix loop", [
+        steps.request(),
+        steps.build({ fromPlan: false }),
+        steps.fixLoop({ suite: "test" }),
+    ]),
+    stepChain("plan-build-test", "the standard chain — plan, build, test, commit", [
+        steps.request(),
+        steps.plan(),
+        steps.build(),
+        steps.fixLoop({ suite: "test" }),
+        steps.commit({ onlyIfAccepted: true }),
+    ]),
+    stepChain("plan-build-test-quality", "the repo has quality commands worth enforcing beyond tests — same, plus lint/typecheck/build gates", [
+        steps.request(),
+        steps.plan(),
+        steps.build(),
+        steps.fixLoop({ suite: "all" }),
+        steps.commit({ onlyIfAccepted: true }),
+    ]),
+    stepChain("build-review", '"is this what was asked for" matters more than "does it run"', [
+        steps.request(),
+        steps.build({ fromPlan: false }),
+        steps.reviseLoop(),
+    ]),
+    stepChain("quality", "lint, typecheck, build — no agents at all", [
+        steps.request({ description: "Capture why quality verification was requested" }),
+        steps.qualityCheck({ suite: "all" }),
+    ]),
+    stepChain("document", "write up the work that was just done, from the diff", [steps.request(), steps.changes(), steps.document()]),
     {
         name: "simple-sdlc",
         describe: "the work is real and its shape is not obvious — plan, build, test, review, document; 3 commits",
-        phases: "engineer(request) -> planner -> builder -> code(test) -> reviewer -> code(changes) -> documenter",
-        requiredAgents: adwSimpleSdlc.REQUIRED_AGENTS,
-        requiredSuites: adwSimpleSdlc.REQUIRED_SUITES,
-        run: adwSimpleSdlc.main,
+        phases: "engineer(request) -> planner -> git(commit_plan) -> builder -> code(test) [-> builder(fix) -> code(test) ...] " +
+            "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> git(commit_build) " +
+            "-> code(changes) -> documenter -> git(commit_docs)",
+        requiredAgents: simpleSdlc.REQUIRED_AGENTS,
+        requiredSuites: simpleSdlc.REQUIRED_SUITES,
+        run: simpleSdlc.main,
     },
 ];
 export function findChain(name) {
@@ -114,3 +71,15 @@ export function findChain(name) {
 export function resolveRequiredAgents(chain, options) {
     return typeof chain.requiredAgents === "function" ? chain.requiredAgents(options) : chain.requiredAgents;
 }
+/**
+ * Run a chain, whichever path it defines: `run` (the imperative escape
+ * hatch) if it has one, otherwise `steps` through the shared driver. Both
+ * CLI dispatch sites (`spf <chain>` and `spf watch`) go through this, never
+ * `chain.run(...)` directly — the whole reason to route through here is that
+ * a `steps`-only chain has no `run` to call.
+ */
+export async function runChain(chain, ctx, options = {}) {
+    if (chain.run)
+        return chain.run(ctx, options);
+    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), chain.requiredSuites, chain.steps, options);
+}

package/dist/chains/{adw_simple_sdlc.d.ts → simple_sdlc.d.ts}

@@ -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,6 +36,12 @@
  * 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 type { ChainContext } from "./context.ts";
 export declare const REQUIRED_AGENTS: string[];

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>;