@gr8ful/spf 0.1.0

package/assets/skill/references/handoff.md

@@ -0,0 +1,162 @@
+# Handoff Reference
+
+The envelope schema, the two-channel output contract, and the session
+directory layout — how context transfers in code, not in conversation.
+
+## Two output channels, exactly
+
+An agent may produce output in two ways and no others:
+
+1. **Reference files** written into `context_handoff/` — plans, notes,
+   artifacts for the agents that follow.
+2. **A final valid-JSON response** — the envelope, its direct response and
+   nothing else, validated by Flue's injected `sf_report` tool against the
+   call's declared Valibot schema before the tool's handler ever fires.
+
+Code does the rest: capture the validated data, persist it as
+`envelope.json`, inject it into the next agent's user prompt.
+
+## Envelope schema
+
+Every output type is built with `envelopeType()` over the base shape
+(`src/core/data_types.ts`):
+
+```ts
+const EnvelopeBaseEntries = {
+  status: v.picklist(["success", "fail"]),        // the only required field
+  summary: v.optional(v.string(), ""),              // one sentence: what happened
+  artifacts: v.optional(v.array(v.string()), () => []),   // paths written, usually in context_handoff/
+  notes_for_next_agent: v.optional(v.string(), ""), // what the next agent must know
+};
+```
+
+`status` is load-bearing: an envelope that parses but reports `status:
+"fail"` throws, failing the phase. An agent declaring its own failure is not
+a successful phase.
+
+The built-in types:
+
+- `GenericOutput` — fallback for an agent with no sharper contract yet.
+- `PlanOutput` — `commit_message` (the plan file's own commit subject).
+- `BuildOutput` — `changed_files`, `commit_message`.
+- `ScoutOutput` — `findings: [{file, note}]`.
+- `ReviewOutput` — `approved`, `findings: [{requirement, met, evidence}]`, `blocking: string[]`.
+- `DocumentOutput` — `document_path`, `documented_files`, `commit_message`.
+
+**Each `commit_message` describes its own agent's work product, never the
+next one's.** A chain that commits once uses whichever fits; one that
+commits per step needs all three, and reusing one agent's sentence for
+another's diff is how a commit log starts lying.
+
+Two types are code-shaped-as-envelope adapters, not agent reports: `VerifyOutput`
+(a quality-suite result, from `quality.asEnvelope`) and `ChangesOutput` (a
+captured `git diff`, from `changes.asEnvelope`). The consuming agent can't
+tell the difference, which is the point.
+
+The envelope is a **manifest of claims**. Gates verify those claims after
+the fact — declared artifacts exist and are non-empty, declared changed
+files appear in the diff, a review's verdict agrees with its own findings.
+See `authoring_chains.md` for adding a gate or an output type.
+
+## The typed-output rule — the synced triad
+
+**Every agent call passes a concrete output type**, and the model's final
+JSON is validated against exactly that type by the injected `sf_report`
+tool.
+
+```ts
+const plan = await run.phase(
+  makePhaseParams({ name: "plan", kind: "agent", owner: "planner", description: "..." }),
+  (ph) => ph.call(makeAgentCall({ output_type: PlanOutput, prompt, gates: [gates.artifactsExist] })),
+);
+```
+
+Three things are one fact: the envelope schema in `data_types.ts`, the exact
+JSON shown in that agent's `user.md` `## Report` section, and the
+`output_type:` named at the call site. Edit them together, or the agent's
+next response silently stops matching what code expects.
+
+**Parse failure is not a restart.** If the model never calls `sf_report`
+(or calls it with data that fails validation), the harness falls back to
+extracting JSON from the response text, and if that still fails, re-prompts
+the **same session** with a correction — bounded by `JSON_FIX_ATTEMPTS` in
+`agents.ts`. Gate violations use the identical mechanism, bounded instead by
+the phase's `retries`. A cold restart would throw away the context that
+produced the near-miss.
+
+## Injecting the previous envelope
+
+`prompts.render()` substitutes into a `user.md`:
+
+| Placeholder | Value |
+|---|---|
+| `{{prompt}}` | the engineer's ask (or the chain's per-call prompt) |
+| `{{previous_envelope}}` | the upstream envelope JSON, from `AgentCall.previous` |
+| `{{context_handoff_dir}}` | absolute path to this session's `context_handoff/` |
+
+A `user.md` declares one h3 per incoming datum, then the task, then the
+output contract:
+
+````markdown
+## Task
+
+Find what `prompt` asks about. Write findings into `context_handoff_dir`,
+then emit your `Report` JSON.
+
+## Report
+
+Respond with ONLY valid JSON matching `ScoutOutput` — no prose before or after:
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence on what you found>",
+  "findings": [{ "file": "src/server.ts", "note": "<why this file matters>" }],
+  "artifacts": ["<context_handoff_dir>/scout_findings.md"]
+}
+```
+````
+
+The `## Report` section shows the exact JSON shape of the declared output
+type — the agent's output contract lives in `user.md` because the shape
+belongs to the *use*, not the identity. The matching `system.md` stays
+static: Purpose + Instructions only.
+
+## Session directory layout
+
+```
+.spf/data/sessions/{adw_id}/
+├── agent_map.json          agent name -> Flue conversation id + model
+├── context_handoff/        the ONE place agents write files for the agents that follow
+└── {agent_name}/
+    ├── prompts/            exact prompts sent (system.md + user.md), saved before execution
+    └── envelope.json       the final valid-JSON response — captured, validated, persisted by code
+```
+
+`session.ensure(cfg, adwId, cwd)` mints or joins the id and creates these
+dirs. One `context_handoff/` per session, shared by every agent.
+
+## agent_map.json and resuming
+
+```json
+{
+  "planner": {"session_id": "a1b2c3d4-planner", "model": "google/gemini-3.6-flash", "coding_agent": "flue"},
+  "builder": {"session_id": "a1b2c3d4-builder", "model": "google/gemini-3.6-flash", "coding_agent": "flue"}
+}
+```
+
+This map is what lets a later run rejoin each agent's **existing Flue
+conversation**. Run a `build` chain with `--adw-id a1b2c3d4` after a `plan`
+chain used the same id, and the builder resumes its own conversation rather
+than starting cold.
+
+The map records the model each session was created with. If config drift
+changes an agent's model, that agent starts a **fresh** conversation and the
+map is updated — never a bad resume. `agent_sessions` in `spf.db` is the
+queryable mirror of this file. Flue's own durable conversation state lives
+separately, in `.spf/data/flue.db` — a sibling with a different lifetime
+(resumed, not archived) from `spf.db`.
+
+**Files are the raw record; the db is the queryable mirror.** Losing
+`spf.db` loses nothing that can't be rebuilt from `envelope.json` and
+`agent_map.json` (plus Flue's own `flue.db` for conversation replay).

package/assets/skill/references/observability.md

@@ -0,0 +1,184 @@
+# Observability Reference
+
+The event schema, the tables, and the polling contract — one data path,
+always: **agents → sqlite → CLI / web UI.**
+
+## Two stores, one truth
+
+**Files are the raw record** (`envelope.json`, `agent_map.json`, Flue's own
+`.spf/data/flue.db` conversation store); **SQLite (`.spf/data/spf.db`, via
+`node:sqlite`) is the queryable mirror** the CLI and UI read. `tracer.ts`
+writes both. Losing the db loses nothing that can't be rebuilt from files.
+
+Location comes from `observability.db` in `spf.config.yaml`, default
+`.spf/data/spf.db` — inside the target repo, always gitignored.
+
+## Event schema
+
+`tracer.ts` emits these types, every one logged against its `adw_id` **and**
+`phase_id`:
+
+| Type | Emitted when |
+|---|---|
+| `phase_start` | a `run.phase(...)` block is entered |
+| `agent_start` | an agent's Flue conversation is created or continued for `ph.call(...)` |
+| `tool_call` | a tool call completes — **one event per real call**, named `bash: ls -la src`, payload `{tool, tool_call_id, args, result_snippet, ok, duration_ms}` |
+| `handoff` | an envelope crosses from one agent to the next |
+| `gate_pass` | a gate found no failed checks — payload carries `attempt`, `checks` (the evidence), and an empty `violations` |
+| `gate_fail` | a gate found at least one failed check — payload carries `attempt`, `checks`, and `violations` |
+| `log` | an explicit `ph.log(...)` from the chain script |
+| `agent_end` | the agent's turn completes; envelope parsed or not — payload carries `cost`, `usage` (the per-component breakdown), `context_tokens`, `context_window` |
+| `phase_end` | the block exits; carries the resolved status |
+| `error` | a throw inside a phase block |
+
+`parent_id` nests spans, so an agent phase expands into its tool-call spans
+in the UI.
+
+**Spend is itemized per phase.** `agent_end.usage` carries tokens *and*
+dollars for each component Flue reports (matching pi-ai's field names
+one-for-one) — `input`, `output`, `cache_read`, `cache_write` — summed
+across every send the phase made, so a phase that retried on a bad envelope
+or a failed gate shows what all its attempts cost, not just the last one.
+
+`reasoning_tokens` is the thinking share and is **inside** `output_tokens`,
+not a fifth component. It bills at the output rate, so the panel nests it
+under output rather than adding it. Runs predating the breakdown have no
+`usage` key at all; the lump `cost` and the event's own `tokens` still
+stand.
+
+**Context is occupancy, not spend.** `events.tokens` and
+`sessions.total_tokens` bill every turn, so they only grow. `context_tokens`
+is how full the window actually was when the agent's last turn settled —
+computed the same way as pi's own auto-compaction trigger: the last *valid*
+turn's `usage.totalTokens`, falling back to `input + output + cacheRead +
+cacheWrite`, skipping aborted/errored turns. `context_window` — the model's
+ceiling — is backend-dependent: a Flue-backed agent always reports **0**
+(Flue exposes no model-registry lookup the way pi's
+`~/.pi/agent/models.json` did), while a `claude_code`-backed agent reports
+a real ceiling straight from the CLI's own result message. Either way, `0`
+means "unknown," not "no context used" — the lane draws no ceiling bar
+rather than a wrong one.
+
+**Gates record evidence, not just a verdict.** A gate returns one
+`{item, ok, note}` check per thing it looked at; `violations` are derived
+from the failed ones. Both land in `gate_results` (`checks_json` +
+`violations_json`) and in the `gate_pass`/`gate_fail` payload.
+
+**A `tool_call` is the one event that spans time**, so it fills both
+`started_at` and `ended_at` on the row. Every other type is a point in
+time. Lay tool calls out on a time axis from those columns, never by
+parsing `payload_json`.
+
+**Streaming is solved by construction.** `agent_flue.ts`'s `run()` forwards
+Flue's `ConversationStreamChunk`s to the tracer as they arrive — never
+batched at phase end. This is why the whole call chain from `agent_flue.run()`
+up through `agents.execute`, `run.phase`, and every chain's `main()` is
+`async`.
+
+## Tables
+
+```sql
+sessions (
+  adw_id TEXT PRIMARY KEY, adw_name TEXT, request TEXT, status TEXT, engineer TEXT,
+  started_at TEXT, ended_at TEXT, total_tokens INTEGER DEFAULT 0, total_cost REAL DEFAULT 0,
+  archived INTEGER DEFAULT 0            -- review triage, set by the UI; never by a run
+);
+phases (
+  phase_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, seq INTEGER,
+  name TEXT, kind TEXT, owner TEXT, description TEXT,
+  status TEXT DEFAULT 'fail',           -- success must be earned
+  attempt INTEGER DEFAULT 0, retries INTEGER DEFAULT 0, error TEXT,
+  started_at TEXT, ended_at TEXT
+);
+events (
+  event_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  parent_id TEXT, type TEXT, name TEXT, payload_json TEXT, tokens INTEGER,
+  started_at TEXT, ended_at TEXT        -- ended_at set only on events that span time
+);
+envelopes (
+  envelope_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  agent TEXT, output_type TEXT, payload_json TEXT, valid INTEGER, attempt INTEGER, created_at TEXT
+);
+gate_results (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  attempt INTEGER, gate TEXT, passed INTEGER,
+  violations_json TEXT,                 -- derived: the failed checks, as "item: note"
+  checks_json TEXT,                     -- [{item, ok, note}] — everything the gate looked at
+  created_at TEXT
+);
+processes (                             -- adw_id -> pid, so a stuck run can be stopped
+  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT REFERENCES sessions,
+  kind TEXT,                            -- 'adw' (the chain process) | 'agent' (a real child pid for claude_code; same as the chain's own pid for Flue, which is in-process)
+  name TEXT, pid INTEGER,
+  command TEXT,                         -- what the pid WAS; pids get recycled, verify before killing
+  started_at TEXT, ended_at TEXT        -- ended_at NULL = believed alive
+);
+agent_sessions (                        -- the queryable mirror of agent_map.json
+  adw_id TEXT REFERENCES sessions, agent TEXT,
+  coding_agent TEXT, model TEXT, color TEXT, session_id TEXT,
+  context_tokens INTEGER,               -- window occupancy after the agent's last turn
+  context_window INTEGER,               -- backend-dependent; 0 = unknown — see "Context is occupancy" above
+  created_at TEXT, last_used_at TEXT,
+  PRIMARY KEY (adw_id, agent)
+);
+```
+
+`processes.kind = 'agent'` rows carry the actual `claude` subprocess pid for
+a `claude_code`-backed agent — genuinely killable independently of the
+chain that spawned it. For a Flue-backed agent (in-process, no child) the
+same row carries the chain's own pid, since there's no separate process to
+record. `spf abort <adw_id>` signals every live row it finds either way.
+
+**Derived, never stored:** phase durations (`ended_at − started_at`),
+session phase-progress (query `phases` by `adw_id`), lane layout (`kind` +
+`owner`).
+
+Phase status invariants: `queued` only for manifest-declared phases not yet
+entered; `running` on enter; only a clean exit writes `success` — agent
+phases additionally need the envelope validated and gates green; everything
+else resolves to `fail`.
+
+## WAL pragmas
+
+Every connection — writer and reader — opens with:
+
+```sql
+PRAGMA journal_mode=WAL;
+PRAGMA synchronous=NORMAL;
+PRAGMA busy_timeout=5000;
+```
+
+WAL allows readers during writes. `src/core/sqlite.ts`'s `node:sqlite` shim
+sets these explicitly and also disables `enableForeignKeyConstraints`
+(`node:sqlite` defaults it **on**, unlike `bun:sqlite`/plain SQLite — left
+on, a session's first `events` row inserting before its `sessions` row
+commits throws). `spf ui` opens its connection with `{readOnly: true}` —
+verified the shim translates that correctly; `readonly` (lowercase) is a
+silent no-op in `node:sqlite` itself, which is exactly the footgun the shim
+exists to close.
+
+## Polling contract
+
+**Nothing pushes.** No ingest endpoint, no WebSocket. Live view polls a
+rowid cursor:
+
+```sql
+SELECT ... FROM events WHERE adw_id = ? AND rowid > ? ORDER BY rowid LIMIT 500;
+```
+
+`spf events <adw_id> --follow` and `spf ui` both do this at
+`observability.poll_ms` (default 500). History is the same queries with
+filters, lazy-paged — one mechanism serves both live and past runs.
+
+## Finding and stopping a stuck run
+
+```bash
+spf phases <adw_id>     # which phase is still "running"
+spf abort <adw_id>      # SIGTERM the chain's process
+```
+
+A hung agent produces no events at all — the trace goes quiet rather than
+red, which is exactly when `processes` (not `events`) is the table that
+answers "is this run doing anything." A killed run finalizes its own trace:
+SIGTERM/SIGINT are handled to close out the session as `fail` with its
+process rows closed, rather than leaving it reading `running` forever.

package/dist/chains/adw_build.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ADW Build — one-shot implementation workflow.
+ *
+ * Usage:
+ *   spf build "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> builder
+ */
+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_build.js

@@ -0,0 +1,27 @@
+/**
+ * ADW Build — one-shot implementation workflow.
+ *
+ * Usage:
+ *   spf build "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> builder
+ */
+import * as agents from "../core/agents.js";
+import * as gates from "../core/gates.js";
+import * as session from "../core/session.js";
+import { BuildOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["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 });
+    });
+    await run.phase(makePhaseParams({ name: "build", kind: "agent", owner: "builder", retries: 1, description: "Implement the request" }), async (ph) => {
+        await ph.call(makeAgentCall({ output_type: BuildOutput, prompt, gates: [gates.diffMatchesClaims] }));
+    });
+    return run.finish();
+}

package/dist/chains/adw_build_review.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ADW Build Review — implement, then confirm it is what was asked for.
+ *
+ * Usage:
+ *   spf build-review "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> builder -> reviewer [-> builder(revise) -> reviewer ... bounded]
+ *
+ * Review is not testing. Tests answer "does it run"; the reviewer answers "is this
+ * the thing that was asked for" — it reads the spec (`plan.md` from a prior plan
+ * phase if the session has one, else the prompt verbatim), reads the code that was
+ * written, and rules on each requirement.
+ *
+ * Like the tester, the reviewer's phase succeeds when it RUNS and REPORTS. A
+ * rejection does not fail the phase; it fails the run, checked at the end, after
+ * the bounded revise loop has had its chances.
+ */
+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_build_review.js

@@ -0,0 +1,55 @@
+/**
+ * ADW Build Review — implement, then confirm it is what was asked for.
+ *
+ * Usage:
+ *   spf build-review "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> builder -> reviewer [-> builder(revise) -> reviewer ... bounded]
+ *
+ * Review is not testing. Tests answer "does it run"; the reviewer answers "is this
+ * the thing that was asked for" — it reads the spec (`plan.md` from a prior plan
+ * phase if the session has one, else the prompt verbatim), reads the code that was
+ * written, and rules on each requirement.
+ *
+ * Like the tester, the reviewer's phase succeeds when it RUNS and REPORTS. A
+ * rejection does not fail the phase; it fails the run, checked at the end, after
+ * the bounded revise loop has had its chances.
+ */
+import * as agents from "../core/agents.js";
+import * as gates from "../core/gates.js";
+import * as session from "../core/session.js";
+import { BuildOutput, ReviewOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["builder", "reviewer"];
+export const REQUIRED_SUITES = [];
+const MAX_REVISION_LOOPS = 3;
+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 });
+    });
+    let previous = await run.phase(makePhaseParams({ name: "build", kind: "agent", owner: "builder", description: "Implement the request" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, gates: [gates.diffMatchesClaims] })));
+    let review = null;
+    for (let i = 1; i <= MAX_REVISION_LOOPS; 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, previous, gates: [gates.artifactsExist, gates.verdictConsistent] })));
+        if (review.approved)
+            break;
+        if (i === MAX_REVISION_LOOPS)
+            break;
+        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, previous: review, gates: [gates.diffMatchesClaims] })));
+    }
+    return run.finish(review !== null && review.approved, `the reviewer never approved after ${MAX_REVISION_LOOPS} revision(s)`);
+}

package/dist/chains/adw_build_test.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ADW Build Test — implement, then verify; failures flow back into the builder.
+ *
+ * Usage:
+ *   spf build-test "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
+ *
+ * Testing is CODE. The suite's command is written down in core/quality.ts,
+ * so running it needs no judgement — only repairing it does. Failures reach the
+ * builder as an envelope through `quality.asEnvelope`, which is the same door an
+ * agent's report came through, so the repair loop is unchanged.
+ *
+ * A failing suite does NOT fail its phase: the runner did its job, the code is
+ * what failed. It fails the run, checked at the end, after the bounded fix loop
+ * has had its chances.
+ */
+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_build_test.js

@@ -0,0 +1,67 @@
+/**
+ * ADW Build Test — implement, then verify; failures flow back into the builder.
+ *
+ * Usage:
+ *   spf build-test "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
+ *
+ * Testing is CODE. The suite's command is written down in core/quality.ts,
+ * so running it needs no judgement — only repairing it does. Failures reach the
+ * builder as an envelope through `quality.asEnvelope`, which is the same door an
+ * agent's report came through, so the repair loop is unchanged.
+ *
+ * A failing suite does NOT fail its phase: the runner did its job, the code is
+ * what failed. It fails the run, checked at the end, after the bounded fix loop
+ * has had its chances.
+ */
+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, makeAgentCall, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["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 });
+    });
+    await run.phase(makePhaseParams({ name: "build", kind: "agent", owner: "builder", description: "Implement the request" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, 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;
+        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],
+        })));
+    }
+    return run.finish(test !== null && test.passed, `the suite still failed after ${MAX_FIX_LOOPS} fix attempt(s)`);
+}

package/dist/chains/adw_document.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ADW Document — write up the work that was just done, from the diff.
+ *
+ * Usage:
+ *   spf document "<prompt or path/to/prompt.md>" [--base main] [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> code(changes) -> documenter
+ *
+ * This runs AFTER a build, and the guard is structural rather than advisory: the
+ * change capture is a code phase, and an empty diff raises there — before the
+ * documenter is ever spawned. There is nothing to document until something was
+ * built, and the phase says so instead of paying an agent to discover it.
+ *
+ * `git diff` against `--base` (main by default) is what "the latest changes"
+ * means here; see core/changes.ts for how the base commit is resolved on a
+ * branch, on main, and on a clean tree right after a chain committed.
+ */
+import type { ChainContext } from "./context.ts";
+export declare const REQUIRED_AGENTS: string[];
+export declare const REQUIRED_SUITES: string[];
+export declare function main(ctx: ChainContext, options?: {
+    base?: string;
+}): Promise<number>;

package/dist/chains/adw_document.js

@@ -0,0 +1,59 @@
+/**
+ * ADW Document — write up the work that was just done, from the diff.
+ *
+ * Usage:
+ *   spf document "<prompt or path/to/prompt.md>" [--base main] [--config <path>] [--adw-id a1b2c3d4]
+ *
+ * Phases: engineer(request) -> code(changes) -> documenter
+ *
+ * This runs AFTER a build, and the guard is structural rather than advisory: the
+ * change capture is a code phase, and an empty diff raises there — before the
+ * documenter is ever spawned. There is nothing to document until something was
+ * built, and the phase says so instead of paying an agent to discover it.
+ *
+ * `git diff` against `--base` (main by default) is what "the latest changes"
+ * means here; see core/changes.ts for how the base commit is resolved on a
+ * branch, on main, and on a clean tree right after a chain committed.
+ */
+import * as agents from "../core/agents.js";
+import * as changes from "../core/changes.js";
+import * as gates from "../core/gates.js";
+import * as session from "../core/session.js";
+import { DocumentOutput, makeAgentCall, makeChangeCapture, makePhaseParams } from "../core/data_types.js";
+export const REQUIRED_AGENTS = ["documenter"];
+export const REQUIRED_SUITES = [];
+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.";
+export async function main(ctx, options = {}) {
+    const { prompt, config_paths, adw_id, cwd } = ctx;
+    const base = options.base ?? "main";
+    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 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 = changes.capture(run, makeChangeCapture({ base }));
+        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}) — documenting runs after a build. ` +
+                `Build something first, or point --base at the ref the work should be measured from.`);
+        }
+        return result;
+    });
+    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" }), async (ph) => {
+        await ph.call(makeAgentCall({
+            output_type: DocumentOutput,
+            prompt,
+            previous: changes.asEnvelope(changeset, DOCUMENT_NOTES),
+            gates: [gates.artifactsExist, gates.filesNonEmpty],
+        }));
+    });
+    return run.finish();
+}

package/dist/chains/adw_plan.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 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>;