@gr8ful/spf 0.1.0

package/dist/chains/adw_plan.js

@@ -0,0 +1,27 @@
+/**
+ * ADW Plan — one-shot planning workflow.
+ *
+ * Usage:
+ *   spf plan "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> planner
+ */
+import * as agents from "../core/agents.js";
+import * as gates from "../core/gates.js";
+import * as session from "../core/session.js";
+import { PlanOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["planner"];
+export const REQUIRED_SUITES = [];
+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);
+    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
+        ph.log({ input: prompt });
+    });
+    await run.phase(makePhaseParams({ name: "plan", kind: "agent", owner: "planner", description: "Turn the request into an implementable plan" }), async (ph) => {
+        await ph.call(makeAgentCall({ output_type: PlanOutput, prompt, gates: [gates.artifactsExist, gates.filesNonEmpty] }));
+    });
+    return run.finish();
+}

package/dist/chains/adw_plan_build.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ADW Plan Build — two-agent chain: planner -> envelope -> builder.
+ *
+ * Usage:
+ *   spf plan-build "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> planner -> builder -> git(commit)
+ */
+import type { ChainContext } from "./context.ts";
+export declare const REQUIRED_AGENTS: string[];
+export declare const REQUIRED_SUITES: string[];
+export declare function main(ctx: ChainContext): Promise<number>;

package/dist/chains/adw_plan_build.js

@@ -0,0 +1,30 @@
+/**
+ * ADW Plan Build — two-agent chain: planner -> envelope -> builder.
+ *
+ * Usage:
+ *   spf plan-build "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> planner -> builder -> git(commit)
+ */
+import * as agents from "../core/agents.js";
+import * as gates from "../core/gates.js";
+import * as session from "../core/session.js";
+import { BuildOutput, PlanOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["planner", "builder"];
+export const REQUIRED_SUITES = [];
+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);
+    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
+        ph.log({ input: prompt });
+    });
+    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] })));
+    const 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] })));
+    await run.phase(makePhaseParams({ name: "commit", kind: "code", owner: "git", description: "Land the builder's changes, using the message it wrote" }), async (ph) => {
+        const message = build.commit_message || `spf(${run.adw_id}): ${build.summary}`;
+        ph.log({ sha: run.git.commitAll(message), message });
+    });
+    return run.finish();
+}

package/dist/chains/adw_plan_build_test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ADW Plan Build Test — the full starter chain.
+ *
+ * Usage:
+ *   spf plan-build-test "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> planner -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded] -> git(commit)
+ *
+ * Testing is CODE: the suite's command lives in core/quality.ts, so no
+ * agent spends a context window rediscovering it. Failures flow back to the
+ * builder as an envelope, and only an exhausted fix loop fails the run.
+ */
+import type { ChainContext } from "./context.ts";
+export declare const REQUIRED_AGENTS: string[];
+export declare const REQUIRED_SUITES: string[];
+export declare function main(ctx: ChainContext): Promise<number>;

package/dist/chains/adw_plan_build_test.js

@@ -0,0 +1,65 @@
+/**
+ * ADW Plan Build Test — the full starter chain.
+ *
+ * Usage:
+ *   spf plan-build-test "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> planner -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded] -> git(commit)
+ *
+ * Testing is CODE: the suite's command lives in core/quality.ts, so no
+ * agent spends a context window rediscovering it. Failures flow back to the
+ * builder as an envelope, and only an exhausted fix loop fails the run.
+ */
+import * as agents from "../core/agents.js";
+import * as gates from "../core/gates.js";
+import * as quality from "../core/quality.js";
+import * as session from "../core/session.js";
+import { BuildOutput, PlanOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["planner", "builder"];
+export const REQUIRED_SUITES = ["test"];
+const MAX_FIX_LOOPS = 3;
+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);
+    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
+        ph.log({ input: prompt });
+    });
+    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] })));
+    let previous = 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.artifactsExist] })));
+    let test = null;
+    for (let i = 1; i <= MAX_FIX_LOOPS; i++) {
+        test = await run.phase(makePhaseParams({
+            name: `test_${i}`,
+            kind: "code",
+            owner: "quality",
+            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);
+            return result;
+        });
+        if (test.passed)
+            break;
+        previous = await run.phase(makePhaseParams({
+            name: `fix_${i}`,
+            kind: "agent",
+            owner: "builder",
+            retries: 1,
+            description: "Repair what the suite reported, from its verbatim output",
+        }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: quality.asEnvelope(test, "tests"), gates: [gates.artifactsExist] })));
+    }
+    // Only tested work gets committed — a red suite leaves the tree uncommitted.
+    if (test !== null && test.passed) {
+        await run.phase(makePhaseParams({ name: "commit", kind: "code", owner: "git", description: "Land the code only after the suite came back green" }), async (ph) => {
+            const message = previous.commit_message || `spf(${run.adw_id}): ${previous.summary}`;
+            ph.log({ sha: run.git.commitAll(message), message });
+        });
+    }
+    return run.finish(test !== null && test.passed, `the suite still failed after ${MAX_FIX_LOOPS} fix attempt(s)`);
+}

package/dist/chains/adw_plan_build_test_quality.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ADW Plan Build Test Quality — full agent chain plus deterministic quality.
+ *
+ * Usage:
+ *   spf plan-build-test-quality "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> planner -> builder -> [code(verify) -> code(test) -> builder(fix)] bounded -> git(commit)
+ *
+ * Verify and test are CODE, not agents. Their commands are known, so running them
+ * needs no judgement — only repairing them does. A failing block does not fail its
+ * phase: the runner did its job, the code is what failed. The failure becomes an
+ * envelope and flows back into the builder, and only an exhausted repair loop
+ * fails the run.
+ */
+import type { ChainContext } from "./context.ts";
+export declare const REQUIRED_AGENTS: string[];
+export declare const REQUIRED_SUITES: string[];
+export declare function main(ctx: ChainContext): Promise<number>;

package/dist/chains/adw_plan_build_test_quality.js

@@ -0,0 +1,66 @@
+/**
+ * ADW Plan Build Test Quality — full agent chain plus deterministic quality.
+ *
+ * Usage:
+ *   spf plan-build-test-quality "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> planner -> builder -> [code(verify) -> code(test) -> builder(fix)] bounded -> git(commit)
+ *
+ * Verify and test are CODE, not agents. Their commands are known, so running them
+ * needs no judgement — only repairing them does. A failing block does not fail its
+ * phase: the runner did its job, the code is what failed. The failure becomes an
+ * envelope and flows back into the builder, and only an exhausted repair loop
+ * fails the run.
+ */
+import * as agents from "../core/agents.js";
+import * as gates from "../core/gates.js";
+import * as quality from "../core/quality.js";
+import * as session from "../core/session.js";
+import { BuildOutput, PlanOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["planner", "builder"];
+export const REQUIRED_SUITES = ["all"];
+const MAX_FIX_LOOPS = 3;
+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);
+    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
+        ph.log({ input: prompt });
+    });
+    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] })));
+    let previous = 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 testResult = null;
+    let qualityResult = null;
+    for (let i = 1; i <= MAX_FIX_LOOPS; i++) {
+        qualityResult = await run.phase(makePhaseParams({ name: `verify_${i}`, kind: "code", owner: "quality", description: "Lint, typecheck, and build before testing" }), async (ph) => {
+            const result = quality.runQuality(run);
+            record(ph, result);
+            return result;
+        });
+        // runQuality() already includes the test block; a repo that wants tests
+        // in their own phase can split them out the way this comment does.
+        testResult = qualityResult;
+        if (qualityResult.passed && testResult.passed)
+            break;
+        if (i === MAX_FIX_LOOPS)
+            break;
+        // Whichever block failed becomes the builder's spec — verbatim command
+        // output, no parser standing between the failure and the fix.
+        const broken = !qualityResult.passed ? qualityResult : testResult;
+        const what = !qualityResult.passed ? "verification" : "tests";
+        previous = await run.phase(makePhaseParams({ name: `fix_${i}`, kind: "agent", owner: "builder", retries: 1, description: `Resolve the reported ${what} failures` }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: quality.asEnvelope(broken, what), gates: [gates.diffMatchesClaims] })));
+    }
+    const verified = qualityResult !== null && qualityResult.passed && testResult !== null && testResult.passed;
+    if (verified) {
+        await run.phase(makePhaseParams({ name: "commit", kind: "code", owner: "git", description: "Commit the tested and quality-verified working tree" }), async (ph) => {
+            const message = previous.commit_message || `spf(${run.adw_id}): ${previous.summary}`;
+            ph.log({ sha: run.git.commitAll(message), message });
+        });
+    }
+    return run.finish(verified, `verify/test never came back clean after ${MAX_FIX_LOOPS} fix attempt(s)`);
+}

package/dist/chains/adw_prompt.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ADW Prompt — the smallest ADW: one agent, one prompt, traced end-to-end.
+ *
+ * Usage:
+ *   spf prompt "<prompt or path/to/prompt.md>" [--agent builder] [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> <agent>
+ */
+import type { ChainContext } from "./context.ts";
+export declare function main(ctx: ChainContext, options?: {
+    agent?: string;
+}): Promise<number>;

package/dist/chains/adw_prompt.js

@@ -0,0 +1,25 @@
+/**
+ * ADW Prompt — the smallest ADW: one agent, one prompt, traced end-to-end.
+ *
+ * Usage:
+ *   spf prompt "<prompt or path/to/prompt.md>" [--agent builder] [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> <agent>
+ */
+import * as agents from "../core/agents.js";
+import * as session from "../core/session.js";
+import { GenericOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export async function main(ctx, options = {}) {
+    const { prompt, config_paths, adw_id, cwd } = ctx;
+    const agent = options.agent ?? "builder";
+    const cfg = agents.loadConfig(config_paths);
+    agents.validate(cfg, [agent], [], cwd);
+    const run = session.ensure(cfg, adw_id, cwd);
+    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
+        ph.log({ input: prompt });
+    });
+    await run.phase(makePhaseParams({ name: "prompt", kind: "agent", owner: agent, description: `Send the request straight to ${agent} and parse its envelope` }), async (ph) => {
+        await ph.call(makeAgentCall({ output_type: GenericOutput, prompt }));
+    });
+    return run.finish();
+}

package/dist/chains/adw_quality.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ADW Quality — lint, typecheck, and build the project.
+ *
+ * Usage:
+ *   spf quality "<reason for the quality run>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> code(quality)
+ */
+import type { ChainContext } from "./context.ts";
+export declare const REQUIRED_AGENTS: string[];
+export declare const REQUIRED_SUITES: string[];
+export declare function main(ctx: ChainContext): Promise<number>;

package/dist/chains/adw_quality.js

@@ -0,0 +1,32 @@
+/**
+ * ADW Quality — lint, typecheck, and build the project.
+ *
+ * Usage:
+ *   spf quality "<reason for the quality run>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> code(quality)
+ */
+import * as agents from "../core/agents.js";
+import * as quality from "../core/quality.js";
+import * as session from "../core/session.js";
+import { makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = [];
+export const REQUIRED_SUITES = ["all"];
+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);
+    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture why quality verification was requested" }), async (ph) => {
+        ph.log({ input: prompt });
+    });
+    await run.phase(makePhaseParams({ name: "quality", kind: "code", owner: "quality", description: "Run the deterministic quality blocks" }), async (ph) => {
+        const result = quality.runQuality(run);
+        const passed = result.checks.filter((c) => c.passed).length;
+        ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
+        if (!result.passed) {
+            throw new Error("quality failed: " + result.failures.join("; "));
+        }
+    });
+    return run.finish();
+}

package/dist/chains/adw_scout.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ADW Scout — read-only recon workflow. Just looking for stuff.
+ *
+ * Usage:
+ *   spf scout "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> scout
+ */
+import type { ChainContext } from "./context.ts";
+export declare const REQUIRED_AGENTS: string[];
+export declare const REQUIRED_SUITES: string[];
+export declare function main(ctx: ChainContext): Promise<number>;

package/dist/chains/adw_scout.js

@@ -0,0 +1,27 @@
+/**
+ * ADW Scout — read-only recon workflow. Just looking for stuff.
+ *
+ * Usage:
+ *   spf scout "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> scout
+ */
+import * as agents from "../core/agents.js";
+import * as gates from "../core/gates.js";
+import * as session from "../core/session.js";
+import { makeAgentCall, makePhaseParams, ScoutOutput } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["scout"];
+export const REQUIRED_SUITES = [];
+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);
+    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
+        ph.log({ input: prompt });
+    });
+    await run.phase(makePhaseParams({ name: "scout", kind: "agent", owner: "scout", description: "Find and report where things live — change nothing" }), async (ph) => {
+        await ph.call(makeAgentCall({ output_type: ScoutOutput, prompt, gates: [gates.artifactsExist] }));
+    });
+    return run.finish();
+}

package/dist/chains/adw_simple_sdlc.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ADW 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]
+ *
+ * Phases: engineer(request) -> planner -> git(commit_plan)
+ *         -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
+ *         -> reviewer [-> builder(revise) -> reviewer ... bounded]
+ *         -> code(retest, only if a revision changed code)
+ *         -> git(commit_build) -> code(changes) -> documenter -> git(commit_docs)
+ *
+ * Three commits, three work products, three authors. The plan, the code, and the
+ * write-up each land in their own commit, and each commit message is the words of
+ * the agent that produced it — `commit_message` on PlanOutput describes the spec,
+ * on BuildOutput the code, on DocumentOutput the write-up. No agent's sentence is
+ * ever reused for another agent's diff.
+ *
+ * Testing is CODE, not an agent. `bun test` is a command, not a judgement call:
+ * an agent rediscovering it every run costs a million tokens to learn what a
+ * subprocess already knows. Failures travel back to the builder as an envelope,
+ * so the repair loop is unchanged — only the runner became free and repeatable.
+ *
+ * Two different questions still get asked, in order. The suite asks "does it
+ * run"; the reviewer asks "is this what was asked for", against `plan.md` — and
+ * neither can answer the other's. A revision that closes a review finding
+ * re-enters the suite, so the tree that gets committed is the tree that was both
+ * tested and approved.
+ *
+ * The code commit lands after verification, not straight after the build: fixes
+ * and revisions are part of the same work product, and red code has no business
+ * on the branch. A run that fails verification therefore leaves the plan
+ * committed and the working tree dirty — the spec is a real artifact either way,
+ * and the unfinished code stays where the engineer can see it.
+ *
+ * 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.
+ */
+import type { ChainContext } from "./context.ts";
+export declare const REQUIRED_AGENTS: string[];
+export declare const REQUIRED_SUITES: string[];
+export declare function main(ctx: ChainContext): Promise<number>;

package/dist/chains/adw_simple_sdlc.js

@@ -0,0 +1,147 @@
+/**
+ * ADW 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]
+ *
+ * Phases: engineer(request) -> planner -> git(commit_plan)
+ *         -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
+ *         -> reviewer [-> builder(revise) -> reviewer ... bounded]
+ *         -> code(retest, only if a revision changed code)
+ *         -> git(commit_build) -> code(changes) -> documenter -> git(commit_docs)
+ *
+ * Three commits, three work products, three authors. The plan, the code, and the
+ * write-up each land in their own commit, and each commit message is the words of
+ * the agent that produced it — `commit_message` on PlanOutput describes the spec,
+ * on BuildOutput the code, on DocumentOutput the write-up. No agent's sentence is
+ * ever reused for another agent's diff.
+ *
+ * Testing is CODE, not an agent. `bun test` is a command, not a judgement call:
+ * an agent rediscovering it every run costs a million tokens to learn what a
+ * subprocess already knows. Failures travel back to the builder as an envelope,
+ * so the repair loop is unchanged — only the runner became free and repeatable.
+ *
+ * Two different questions still get asked, in order. The suite asks "does it
+ * run"; the reviewer asks "is this what was asked for", against `plan.md` — and
+ * neither can answer the other's. A revision that closes a review finding
+ * re-enters the suite, so the tree that gets committed is the tree that was both
+ * tested and approved.
+ *
+ * The code commit lands after verification, not straight after the build: fixes
+ * and revisions are part of the same work product, and red code has no business
+ * on the branch. A run that fails verification therefore leaves the plan
+ * committed and the working tree dirty — the spec is a real artifact either way,
+ * and the unfinished code stays where the engineer can see it.
+ *
+ * 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.
+ */
+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 { 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 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));
+    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++) {
+        test = await run.phase(makePhaseParams({
+            name: `test_${i}`,
+            kind: "code",
+            owner: "quality",
+            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);
+            return result;
+        });
+        if (test.passed)
+            break;
+        build = await run.phase(makePhaseParams({
+            name: `fix_${i}`,
+            kind: "agent",
+            owner: "builder",
+            retries: 1,
+            description: "Repair what the suite reported, from its verbatim output",
+        }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: quality.asEnvelope(test, "tests"), gates: [gates.diffMatchesClaims] })));
+    }
+    let review = null;
+    let revised = false;
+    for (let i = 1; i <= MAX_REVISION_LOOPS; i++) {
+        review = await run.phase(makePhaseParams({ name: `review_${i}`, kind: "agent", owner: "reviewer", description: "Confirm the build matches the plan" }), (ph) => ph.call(makeAgentCall({ output_type: ReviewOutput, prompt, previous: build, gates: [gates.artifactsExist, gates.verdictConsistent] })));
+        if (review.approved || i === MAX_REVISION_LOOPS)
+            break;
+        build = await run.phase(makePhaseParams({ name: `revise_${i}`, kind: "agent", owner: "builder", retries: 1, description: "Close the reviewer's blocking findings" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: review, gates: [gates.diffMatchesClaims] })));
+        revised = true;
+    }
+    // A revision edited code after the suite last ran, so the green light is
+    // stale. Re-run it rather than commit on a result that predates the change.
+    if (revised && review !== null && review.approved) {
+        test = await run.phase(makePhaseParams({
+            name: "retest",
+            kind: "code",
+            owner: "quality",
+            description: "Re-run the suite — the revision changed code after the last green result",
+        }), async (ph) => {
+            const result = quality.runTests(run);
+            record(ph, result);
+            return result;
+        });
+    }
+    // Red tests or a rejected review stop the chain here: the code stays
+    // uncommitted and nothing is documented, because there is nothing worth
+    // 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));
+        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,
+            });
+            if (result.empty) {
+                throw new Error(`nothing changed since ${result.base.label} (${result.base.reason}) — there is nothing to document.`);
+            }
+            return result;
+        });
+        const document = await run.phase(makePhaseParams({ name: "document", kind: "agent", owner: "documenter", retries: 1, description: "Write up the completed change" }), (ph) => ph.call(makeAgentCall({
+            output_type: DocumentOutput,
+            prompt,
+            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));
+    }
+    return run.finish(verified, "the suite or the review never came back clean");
+}

package/dist/chains/context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What every chain's `main()` receives. The CLI (or, later, the chain
+ * registry) resolves every path here — a chain never has its own opinion
+ * about where the config file or the working directory are, and none of the
+ * historical per-chain hardcoded config-path defaults survive this.
+ */
+export interface ChainContext {
+    prompt: string;
+    /**
+     * Absolute paths, in load order (agents.loadConfig merges them: later
+     * overrides earlier). The built-in packaged default, then an optional
+     * discovered `.spf/spf.config.yaml` — or just the one explicit `--config`
+     * path, standalone, with no built-in underneath it.
+     */
+    config_paths: string[];
+    adw_id: string | null;
+    /** Absolute. The anchor session.ensure() resolves repo_root and data_dir from. */
+    cwd: string;
+}

package/dist/chains/context.js

@@ -0,0 +1 @@
+export {};

package/dist/chains/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The chain registry — the one place a CLI-facing short name maps to a
+ * chain module. `spf list` reads this; `spf <name>`/`spf run <name>` dispatch
+ * through it. Replaces guessing a module filename from the CLI argument.
+ */
+import type { ChainContext } from "./context.ts";
+export interface ChainDefinition {
+    /** The name typed on the CLI: `spf <name> "..."`. */
+    name: string;
+    describe: string;
+    phases: string;
+    /** Static for most chains; adw_prompt's depends on --agent, so it's a function there. */
+    requiredAgents: string[] | ((options: Record<string, string>) => string[]);
+    requiredSuites: string[];
+    run: (ctx: ChainContext, options?: Record<string, string>) => Promise<number>;
+}
+export declare const CHAINS: ChainDefinition[];
+export declare function findChain(name: string): ChainDefinition | undefined;
+export declare function resolveRequiredAgents(chain: ChainDefinition, options: Record<string, string>): string[];