@gr8ful/spf 0.4.0 → 0.5.1

package/dist/core/paths.d.ts

@@ -67,6 +67,9 @@ export interface DataPaths {
  * alwaysWritable()` matches `cfg.defaults.data_dir` against repo-relative git
  * output, so that field stays exactly as configured. This produces a
  * parallel, absolute set of paths for filesystem use instead of mutating it.
+ *
+ * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
+ * caller needs run before its own first `mkdirSync` against `data_dir`.
  */
 export declare function resolveDataPaths(anchor: RepoAnchor, rawDataDir: string, rawDbPath: string): DataPaths;
 /**

package/dist/core/paths.js

@@ -16,7 +16,7 @@
  * levels below the package root, so the same relative path resolves either
  * way), with `assets/` a direct child of it.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, lstatSync, realpathSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { findRepoRoot } from "./git_helper.js";
 export const PACKAGE_ROOT = path.resolve(import.meta.dirname, "..", "..");
@@ -67,6 +67,49 @@ export function resolveConfigPaths(anchor, explicit) {
     }
     return { paths: [BUILTIN_CONFIG_PATH], source: "built-in-only" };
 }
+/**
+ * Self-heals one specific, previously-observed failure mode: `data_dir`
+ * existing as a broken symlink — self-referential (points at itself) or
+ * dangling (points at something that no longer exists) — instead of a real
+ * directory. `spf watch`'s `linkDataDir` guards against ever CREATING one of
+ * these now (see its comment in `cli/commands/watch.ts`), but a prior,
+ * unguarded build already left one behind on at least one real checkout, and
+ * that state persists across every later `spf` invocation until something
+ * removes it: `mkdirSync(data_dir, {recursive: true})` — the very first
+ * filesystem touch nearly every command makes, whether via `ensureDir`'s
+ * session dirs or `acquireLock`'s lockfile dir — throws `ELOOP` before
+ * anything else runs, with no recovery path of its own.
+ *
+ * This has to run HERE, in the one function every one of those call sites
+ * resolves `data_dir` through, rather than as a guard inside each of them
+ * individually — a fix duplicated at every call site is a fix that's one new
+ * call site away from being missed again.
+ *
+ * `lstatSync` (never follows the link itself) distinguishes "nothing here
+ * yet" (the ordinary first-run case — silently returns, nothing to heal)
+ * from "a symlink sits here." Only for the symlink case does `realpathSync`
+ * (which fully resolves it) get a chance to throw — `ELOOP` for a circular
+ * link, `ENOENT` for a dangling target — and only then is anything removed.
+ * A real directory never reaches the `realpathSync` call at all.
+ */
+function healBrokenDataDir(data_dir) {
+    let entry;
+    try {
+        entry = lstatSync(data_dir);
+    }
+    catch {
+        return; // nothing at this path at all — ordinary first run
+    }
+    if (!entry.isSymbolicLink())
+        return; // a real directory (or file) — not this bug
+    try {
+        realpathSync(data_dir);
+    }
+    catch {
+        rmSync(data_dir);
+        console.error(`spf: removed a broken data_dir symlink at ${data_dir} (self-referential or dangling) — a fresh directory will be created in its place`);
+    }
+}
 /**
  * Anchor a config's own `data_dir`/`observability.db` (as loaded — relative
  * or absolute, whichever the YAML says) to `repo_root`.
@@ -75,9 +118,13 @@ export function resolveConfigPaths(anchor, explicit) {
  * alwaysWritable()` matches `cfg.defaults.data_dir` against repo-relative git
  * output, so that field stays exactly as configured. This produces a
  * parallel, absolute set of paths for filesystem use instead of mutating it.
+ *
+ * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
+ * caller needs run before its own first `mkdirSync` against `data_dir`.
  */
 export function resolveDataPaths(anchor, rawDataDir, rawDbPath) {
     const data_dir = path.resolve(anchor.repo_root, rawDataDir);
+    healBrokenDataDir(data_dir);
     const data_dir_rel = path.relative(anchor.repo_root, data_dir).split(path.sep).join("/");
     const db_path = path.resolve(anchor.repo_root, rawDbPath);
     const sessions_dir = path.resolve(path.dirname(db_path), "sessions");

package/dist/core/providers.js

@@ -21,4 +21,8 @@ export const PROVIDER_ENV_KEYS = {
     deepseek: ["DEEPSEEK_API_KEY"],
     together: ["TOGETHER_API_KEY"],
     cerebras: ["CEREBRAS_API_KEY"],
+    // Keyless: a local server, not a hosted API — nothing to check for or
+    // prompt for. An empty array here means "known provider, needs no key",
+    // never "unknown provider" (that's a missing table entry, not `[]`).
+    ollama: [],
 };

package/dist/core/refine.js

@@ -27,14 +27,22 @@ export function resolveAuthoringProvider(cfg) {
         throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — ` +
             `the refine lane needs "github" (see jira_provider.ts's module comment on why Jira isn't wired up yet)`);
     }
-    if (!cfg.watch.repo.trim()) {
-        throw new Error(`watch.repo is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+    // Issue authoring always targets the ISSUE tracker's repo — `issue_repo`
+    // if set, falling back to plain `repo` (the common case: issue_provider
+    // and code_host are both github, so they're the same repo). Reading
+    // `repo` alone would be wrong for a github-issues + bitbucket-code setup,
+    // where `repo` names the BITBUCKET repo (see WatchConfigSchema's doc
+    // comment) — this would try to create GitHub issues against a Bitbucket
+    // identifier.
+    const repo = cfg.watch.issue_repo.trim() || cfg.watch.repo.trim();
+    if (!repo) {
+        throw new Error(`watch.repo (or watch.issue_repo, if code_host names a different repo) is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
     }
     const token = process.env["GITHUB_TOKEN"];
     if (!token) {
         throw new Error('GITHUB_TOKEN is not set — the refine lane needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo)');
     }
-    return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+    return new GitHubProvider(repo, cfg.watch.label_prefix, token);
 }
 function typeLabel(labelPrefix, kind) {
     return `${labelPrefix}:type:${kind}`;

package/dist/core/session.js

@@ -11,6 +11,15 @@ import { Run } from "./runner.js";
 import { Tracer } from "./tracer.js";
 import { engineerName, newId } from "./utils.js";
 import { resolveNotifier } from "./notify/notifier.js";
+import * as otel from "./otel.js";
+/**
+ * How long a signalled run may spend pushing spans before it exits anyway.
+ * Short on purpose: someone who just pressed ^C is waiting, and an
+ * observability projection is never worth making a kill feel broken. The
+ * budget is enforced inside `otel.flushAll()` (a raced, unref'd deadline), so
+ * an unreachable collector costs exactly this and not one tick more.
+ */
+const SIGNAL_DRAIN_MS = 750;
 /**
  * A killed run still closes its own trace.
  *
@@ -20,11 +29,31 @@ import { resolveNotifier } from "./notify/notifier.js";
  * flight that is already dead. Handling the signal both finalizes here and
  * lets the phase's try/catch record the phase as failed on the way out
  * (best-effort: a signal can still land mid-write).
+ *
+ * SQLite is written FIRST and synchronously, exactly as before — the otel
+ * drain is appended after it and can only ever cost time, never correctness.
+ * (`notify` has no equivalent drain on this path: its in-flight webhooks are
+ * dropped on a signal today. Fixing that means touching the notifier's
+ * lifecycle, which is outside this change; only the otel path is drained here.)
+ * A second signal during the drain exits immediately — someone pressing ^C
+ * twice means "now", and a shutdown path that ignores that is a hang.
  */
 function finalizeWhenKilled(run) {
+    let draining = false;
     const handler = (signal) => {
+        const code = 128 + (signal === "SIGINT" ? 2 : 15);
+        if (draining)
+            process.exit(code);
+        draining = true;
         run.tracer.sessionFinish(run.adw_id, false); // also closes process rows
-        process.exit(128 + (signal === "SIGINT" ? 2 : 15));
+        // Unconfigured (the default) exits SYNCHRONOUSLY, exactly as it did before
+        // otel existed — no extra tick between the signal and the exit for the
+        // repos that never opted in.
+        if (!run.tracer.otel)
+            process.exit(code);
+        // Bounded and never-throwing: flushAll() swallows its own failures and
+        // resolves on its own deadline, so this always reaches process.exit().
+        void otel.flushAll(SIGNAL_DRAIN_MS).then(() => process.exit(code), () => process.exit(code));
     };
     process.on("SIGTERM", handler);
     process.on("SIGINT", handler);
@@ -44,7 +73,15 @@ export function ensure(cfg, adwId, cwd, chainName) {
     const id = adwId || newId(8);
     const anchor = paths.resolveAnchor(cwd);
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
-    const tracer = new Tracer(dataPaths.db_path, path.join(dataPaths.sessions_dir, id, "events.jsonl"));
+    // `null` unless `observability.otel` is configured — no environment variable
+    // can turn this on (see core/otel.ts's EXPLICIT CONFIG ONLY). Constructed
+    // BEFORE the Tracer because the Tracer's write methods are the fan-out
+    // seams: SQLite stays the source of truth, otel is a projection off it, and
+    // registering here (module-level LIVE, exactly like resolveNotifier) is what
+    // lets the CLI's finally block and the signal handler above drain it without
+    // threading a handle through every call site.
+    const otelExporter = otel.resolveOtelExporter(cfg, { adwId: id, chainName: chainName || "adw" });
+    const tracer = new Tracer(dataPaths.db_path, path.join(dataPaths.sessions_dir, id, "events.jsonl"), otelExporter);
     const run = new Run({
         cfg,
         adwId: id,

package/dist/core/tracer.d.ts

@@ -2,18 +2,47 @@
  * Tracer: every event lands in JSONL and SQLite AS IT HAPPENS.
  *
  * Files are the raw record; spf.db is the queryable mirror the UI polls.
- * No push transport — the flow is always: agents -> sqlite -> web ui.
  * WAL mode so the UI can read while ADW processes write.
+ *
+ * No push transport in the CONTROL flow — that is always, still, and only:
+ * agents -> sqlite -> web ui. SQLite is the source of truth; nothing
+ * downstream of it can affect a phase, a gate, or a run outcome.
+ *
+ * The one amendment: when (and only when) `observability.otel` is configured,
+ * each write method below ends with a single fan-out line to an optional
+ * OtelExporter — a lossy, allowlisted PROJECTION of what was just written,
+ * pushed to an OTLP endpoint fire-and-forget. It is deliberately NOT a second
+ * record: it never blocks, never throws into a caller (see `fanOut`), drops
+ * spans under backpressure, and carries only the allowlisted subset of fields
+ * (never `EventRecord.payload`, never the request text, never envelope
+ * contents — `core/otel.ts`'s header has the full list and the reasons).
+ * Methods whose data is entirely outside that allowlist —
+ * `sessionRequest` (the operator's prompt), `envelopeRow` (agent output),
+ * `processStart`/`processEnd` (pids) — have NO fan-out line on purpose. Do not
+ * add one.
  */
 import { Database } from "./sqlite.ts";
 import type { AgentConfig, EventRecord, GateReport, Phase } from "./data_types.ts";
+import type { OtelExporter } from "./otel.ts";
 export declare class Tracer {
     db: Database;
     dbPath: string;
     eventsJsonl: string;
-    constructor(dbPath: string, eventsJsonl: string);
+    /** `null` unless `observability.otel` is configured — see the header. */
+    otel: OtelExporter | null;
+    constructor(dbPath: string, eventsJsonl: string, otel?: OtelExporter | null);
     /** Additive column migrations, so a db from an older SPF still opens. */
     private migrate;
+    /**
+     * The ONE door to the optional otel projection, and the only reason a fan-out
+     * line is safe to put at the end of a synchronous write method: it is a
+     * no-op when unconfigured, and it swallows everything. An exporter bug, a
+     * malformed span, an exhausted queue — none of it may ever surface as a
+     * failed phase, because export is not allowed to dispose of anything. The
+     * exporter's own methods are synchronous enqueues; the network happens later,
+     * on an unref'd timer.
+     */
+    private fanOut;
     event(record: EventRecord): string;
     sessionStart(adwId: string, engineer: string, adwName?: string | null): void;
     sessionRequest(adwId: string, request: string): void;

package/dist/core/tracer.js

@@ -2,8 +2,24 @@
  * Tracer: every event lands in JSONL and SQLite AS IT HAPPENS.
  *
  * Files are the raw record; spf.db is the queryable mirror the UI polls.
- * No push transport — the flow is always: agents -> sqlite -> web ui.
  * WAL mode so the UI can read while ADW processes write.
+ *
+ * No push transport in the CONTROL flow — that is always, still, and only:
+ * agents -> sqlite -> web ui. SQLite is the source of truth; nothing
+ * downstream of it can affect a phase, a gate, or a run outcome.
+ *
+ * The one amendment: when (and only when) `observability.otel` is configured,
+ * each write method below ends with a single fan-out line to an optional
+ * OtelExporter — a lossy, allowlisted PROJECTION of what was just written,
+ * pushed to an OTLP endpoint fire-and-forget. It is deliberately NOT a second
+ * record: it never blocks, never throws into a caller (see `fanOut`), drops
+ * spans under backpressure, and carries only the allowlisted subset of fields
+ * (never `EventRecord.payload`, never the request text, never envelope
+ * contents — `core/otel.ts`'s header has the full list and the reasons).
+ * Methods whose data is entirely outside that allowlist —
+ * `sessionRequest` (the operator's prompt), `envelopeRow` (agent output),
+ * `processStart`/`processEnd` (pids) — have NO fan-out line on purpose. Do not
+ * add one.
  */
 import { Database } from "./sqlite.js";
 import { appendFileSync, mkdirSync } from "node:fs";
@@ -97,7 +113,10 @@ export class Tracer {
     db;
     dbPath;
     eventsJsonl;
-    constructor(dbPath, eventsJsonl) {
+    /** `null` unless `observability.otel` is configured — see the header. */
+    otel;
+    constructor(dbPath, eventsJsonl, otel) {
+        this.otel = otel ?? null;
         mkdirSync(path.dirname(dbPath), { recursive: true });
         this.dbPath = dbPath;
         this.eventsJsonl = eventsJsonl;
@@ -118,6 +137,27 @@ export class Tracer {
             }
         }
     }
+    /**
+     * The ONE door to the optional otel projection, and the only reason a fan-out
+     * line is safe to put at the end of a synchronous write method: it is a
+     * no-op when unconfigured, and it swallows everything. An exporter bug, a
+     * malformed span, an exhausted queue — none of it may ever surface as a
+     * failed phase, because export is not allowed to dispose of anything. The
+     * exporter's own methods are synchronous enqueues; the network happens later,
+     * on an unref'd timer.
+     */
+    fanOut(action) {
+        if (!this.otel)
+            return;
+        try {
+            action(this.otel);
+        }
+        catch {
+            // Deliberately silent: a logged line per event on a hot path would be
+            // its own failure mode, and otel.ts already logs its own send failures
+            // exactly once.
+        }
+    }
     // ── events ──────────────────────────────────────────────────────────────
     event(record) {
         const eventId = `evt_${newId(12)}`;
@@ -128,23 +168,28 @@ export class Tracer {
             .query(`INSERT INTO events (event_id, adw_id, phase_id, parent_id, type, name,
          payload_json, tokens, started_at, ended_at) VALUES (?,?,?,?,?,?,?,?,?,?)`)
             .run(eventId, record.adw_id, record.phase_id, record.parent_id, record.type, record.name, JSON.stringify(record.payload), record.tokens ?? null, record.started_at || ts, record.ended_at ?? null);
+        this.fanOut((otel) => otel.recordEvent(record, eventId, ts)); // otel projection — see fanOut
         return eventId;
     }
     // ── sessions ────────────────────────────────────────────────────────────
     sessionStart(adwId, engineer, adwName) {
+        const startedAt = nowIso();
         this.db
             .query(`INSERT INTO sessions (adw_id, status, engineer, started_at) VALUES (?,?,?,?)
          ON CONFLICT(adw_id) DO UPDATE SET status='running'`)
-            .run(adwId, "running", engineer, nowIso());
-        if (!adwName)
-            return;
-        // A joined session chains ADWs — record each distinct one, in run order.
-        const row = this.db.query("SELECT adw_name FROM sessions WHERE adw_id=?").get(adwId);
-        const names = row?.adw_name ? row.adw_name.split(" + ") : [];
-        if (!names.includes(adwName)) {
-            names.push(adwName);
-            this.db.query("UPDATE sessions SET adw_name=? WHERE adw_id=?").run(names.join(" + "), adwId);
+            .run(adwId, "running", engineer, startedAt);
+        if (adwName) {
+            // A joined session chains ADWs — record each distinct one, in run order.
+            const row = this.db.query("SELECT adw_name FROM sessions WHERE adw_id=?").get(adwId);
+            const names = row?.adw_name ? row.adw_name.split(" + ") : [];
+            if (!names.includes(adwName)) {
+                names.push(adwName);
+                this.db.query("UPDATE sessions SET adw_name=? WHERE adw_id=?").run(names.join(" + "), adwId);
+            }
         }
+        // otel projection: the run's clock only. `engineer` is a person's name —
+        // outside the allowlist, and not a measure of anything.
+        this.fanOut((otel) => otel.recordSessionStart(startedAt));
     }
     sessionRequest(adwId, request) {
         this.db.query("UPDATE sessions SET request=? WHERE adw_id=?").run(request.slice(0, 500), adwId);
@@ -154,6 +199,7 @@ export class Tracer {
             .query("UPDATE sessions SET status=?, ended_at=? WHERE adw_id=?")
             .run(ok ? "success" : "fail", nowIso(), adwId);
         this.processesEndAll(adwId); // nothing of this run is alive any more
+        this.fanOut((otel) => otel.recordSessionFinish(ok)); // otel projection: emits the root run span, once
     }
     sessionAddUsage(adwId, tokens, cost) {
         this.db
@@ -208,6 +254,9 @@ export class Tracer {
          ON CONFLICT(phase_id) DO UPDATE SET status=excluded.status,
          attempt=excluded.attempt, error=excluded.error, ended_at=excluded.ended_at`)
             .run(phase.phase_id, phase.adw_id, phase.seq, p.name, p.kind, p.owner, p.description, phase.status, phase.attempt, p.retries, phase.error ?? null, phase.started_at ?? null, phase.ended_at ?? null);
+        // otel projection: a no-op on the start-of-phase upsert (no ended_at yet) —
+        // phase spans are emitted at phase END only. `phase.error` never crosses.
+        this.fanOut((otel) => otel.recordPhase(phase));
     }
     // ── envelopes / gates / agent sessions ──────────────────────────────────
     envelopeRow(phase, agent, outputType, payloadJson, valid, attempt) {
@@ -222,6 +271,10 @@ export class Tracer {
             .query(`INSERT INTO gate_results (adw_id, phase_id, attempt, gate, passed,
          violations_json, checks_json, created_at) VALUES (?,?,?,?,?,?,?,?)`)
             .run(phase.adw_id, phase.phase_id, attempt, gate, report.passed ? 1 : 0, JSON.stringify(report.violations), JSON.stringify(report.checks), nowIso());
+        // otel projection: gate name + verdict + violation COUNT as a span event on
+        // the phase span. The violation and check TEXT stays here in SQLite — it
+        // quotes the agent's claim and the repo's files.
+        this.fanOut((otel) => otel.recordGate(phase, gate, report, attempt));
     }
     /**
      * The agent's config row is the source of truth for its label and color.
@@ -242,5 +295,10 @@ export class Tracer {
          context_window=excluded.context_window,
          last_used_at=excluded.last_used_at`)
             .run(adwId, agent.name, agent.coding_agent, agent.model, agent.color, sessionId, contextTokens, contextWindow, ts, ts);
+        // otel projection: the TYPED source of an agent's model + backend for its
+        // span (agents.ts writes this row before the agent_end event, which is what
+        // lets otel.ts avoid reading the agent_start payload at all). `sessionId`
+        // is not exported — it is a coding-agent handle, not a measure.
+        this.fanOut((otel) => otel.recordAgentSession(agent));
     }
 }

package/dist/core/watch.d.ts

@@ -6,6 +6,17 @@ export interface ChainRunResult {
     adwId: string;
     /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
     detail: string;
+    /**
+     * A short, already-sanitized/truncated digest of the reviewer's verdict
+     * (approved/blocking/findings), read back best-effort from the sessions DB
+     * — see `cli/commands/watch.ts`'s `runChain`. `undefined` when the chain
+     * that ran has no reviewer step, or the DB read/parse failed; `runIssue`
+     * below falls back to `reviewRequired` to tell those two apart in the PR
+     * body and `pr_opened` notification.
+     */
+    reviewSummary?: string;
+    /** Whether the chain that ran declares a "reviewer" in its `requiredAgents` — distinguishes "reviewer approved" from "nothing reviewed this change" when `reviewSummary` is absent. */
+    reviewRequired?: boolean;
 }
 /** One issue the refine lane created — enough for `finishSpec`'s summary comment and the marker's idempotency record. */
 export interface RefinedIssueRef {

package/dist/core/watch.js

@@ -284,6 +284,15 @@ async function runIssue(deps, issue) {
             return;
         }
         wtGit.push("origin", branch);
+        // The human merging this PR sees whatever the reviewer found — or, if
+        // nothing reviewed this change at all, is told that plainly rather than
+        // left to assume a silent approval. `reviewSummary` is already
+        // sanitized/truncated by the caller (see runChain's own doc comment).
+        const reviewLine = result.reviewSummary
+            ? result.reviewSummary
+            : result.reviewRequired
+                ? "Reviewer ran, but no verdict could be read back from the session data."
+                : `Nothing reviewed this change — chain \`${deps.chain}\` has no reviewer step.`;
         // No cross-linking magic keyword here on purpose (a code host paired
         // with a different tracker has no "Closes #n" convention to hook into
         // — see provider.ts) — the issue id in the title/body is plain text
@@ -292,7 +301,7 @@ async function runIssue(deps, issue) {
         const pr = await deps.codeHost.openPr({
             branch,
             title: `${issue.title} (${issue.id})`,
-            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`, issue ${issue.id}.`,
+            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`, issue ${issue.id}.\n\n${reviewLine}`,
             base: deps.baseBranch,
         });
         await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, pr: pr.number, attempt: 0 });
@@ -302,7 +311,13 @@ async function runIssue(deps, issue) {
             kind: "pr_opened",
             level: "info",
             title: `PR #${pr.number} opened`,
-            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain]],
+            detail: reviewLine,
+            fields: [
+                ["issue", issue.id],
+                ["title", issue.title],
+                ["chain", deps.chain],
+                ["review", result.reviewSummary ? "reviewed" : result.reviewRequired ? "reviewer ran, no verdict" : "not reviewed"],
+            ],
             url: pr.url || undefined,
         });
     }

package/dist/test/chains.test.js

@@ -11,7 +11,7 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { CHAINS, findChain, resolveRequiredAgents } from "../chains/index.js";
+import { CHAINS, findChain, resolveRequiredAgents, resolveRequiredSuites } from "../chains/index.js";
 // name -> [phases, requiredAgents (with no options), requiredSuites]
 const EXPECTED = {
     prompt: { phases: "engineer(request) -> <agent>", agents: ["builder"], suites: [] },
@@ -44,7 +44,7 @@ const EXPECTED = {
     refine: { phases: "engineer(request) -> refiner -> code(publish)", agents: ["refiner"], suites: [] },
     "simple-sdlc": {
         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) " +
+            "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> engineer(signoff) -> git(commit_build) " +
             "-> code(changes) -> documenter -> git(commit_docs)",
         agents: ["planner", "builder", "reviewer", "documenter"],
         suites: ["test"],
@@ -59,7 +59,7 @@ for (const chain of CHAINS) {
     test(`${chain.name}: derived phases/requiredAgents/requiredSuites match what was hand-verified against \`spf list\``, () => {
         assert.equal(chain.phases, expected.phases);
         assert.deepEqual(resolveRequiredAgents(chain, {}), expected.agents);
-        assert.deepEqual(chain.requiredSuites, expected.suites);
+        assert.deepEqual(resolveRequiredSuites(chain, {}), expected.suites);
     });
 }
 test("prompt: requiredAgents depends on --agent, not a fixed list — the one dynamic case", () => {
@@ -67,6 +67,11 @@ test("prompt: requiredAgents depends on --agent, not a fixed list — the one dy
     assert.deepEqual(resolveRequiredAgents(chain, {}), ["builder"], "no --agent -> falls back to builder");
     assert.deepEqual(resolveRequiredAgents(chain, { agent: "planner" }), ["planner"], "--agent overrides the default");
 });
+test("plan-build-test: requiredSuites depends on --suite, the same way prompt's agent does", () => {
+    const chain = findChain("plan-build-test");
+    assert.deepEqual(resolveRequiredSuites(chain, {}), ["test"], "no --suite -> falls back to the compiled-in default");
+    assert.deepEqual(resolveRequiredSuites(chain, { suite: "custom" }), ["custom"], "--suite overrides the default");
+});
 test("every chain but simple-sdlc is a steps list; simple-sdlc alone uses the imperative run() escape hatch", () => {
     for (const chain of CHAINS) {
         if (chain.name === "simple-sdlc") {

package/dist/test/data_types.test.js

@@ -14,8 +14,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as v from "valibot";
 import { toJsonSchema } from "@valibot/to-json-schema";
-import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, GenericOutput, NotificationsConfigSchema, PhaseParamsSchema, PlanOutput, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
-import { loadConfig } from "../core/agents.js";
+import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, EventRecordTypeSchema, GenericOutput, NotificationsConfigSchema, PhaseParamsSchema, PlanOutput, ReviewConfigSchema, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
+import { agentEnv, loadConfig } from "../core/agents.js";
 test("writes: three-state semantics — absent, null, and [] all mean something different", () => {
     const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
     const unrestricted = v.parse(AgentConfigSchema, base);
@@ -80,3 +80,141 @@ test("notifications survives loadConfig's merge — key-by-key like observabilit
         rmSync(dir, { recursive: true, force: true });
     }
 });
+test("ReviewConfigSchema: defaults to require_human_signoff=false, signoff_timeout_seconds=300", () => {
+    const parsed = v.parse(ReviewConfigSchema, {});
+    assert.equal(parsed.require_human_signoff, false, "this release fails OPEN by default — see the schema's own doc comment");
+    assert.equal(parsed.signoff_timeout_seconds, 300);
+});
+// The silent-drop trap: mergeRawConfig (core/agents.ts) is a FIXED-SHAPE
+// object literal, so a `review:` key in a real config file that isn't named
+// on both sides of that literal is dropped before SFConfigSchema ever sees
+// it — parsing would then succeed anyway, quietly, on the schema default.
+// This is adversarial history on this branch, not a hypothetical: it is
+// exactly the bug `observability`/`notifications` already guard against, and
+// `review` gets the same guard the day it is added.
+test("review survives loadConfig's merge — the silent-drop trap mergeRawConfig's fixed-shape literal sets, for a single config file", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-review-merge-test-"));
+    try {
+        const configPath = join(dir, "spf.config.yaml");
+        writeFileSync(configPath, "review:\n  require_human_signoff: true\n  signoff_timeout_seconds: 45\n");
+        const cfg = loadConfig([configPath]);
+        assert.equal(cfg.review.require_human_signoff, true, "a review: value from a real config file must reach SFConfig, not be dropped by mergeRawConfig's object literal");
+        assert.equal(cfg.review.signoff_timeout_seconds, 45);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("review merges key-by-key across two layered config files, like observability/notifications", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-review-merge-layered-test-"));
+    try {
+        const base = join(dir, "base.yaml");
+        const override = join(dir, "override.yaml");
+        writeFileSync(base, "review:\n  require_human_signoff: false\n  signoff_timeout_seconds: 120\n");
+        writeFileSync(override, "review:\n  require_human_signoff: true\n");
+        const cfg = loadConfig([base, override]);
+        assert.equal(cfg.review.require_human_signoff, true, "override wins for the key it names");
+        assert.equal(cfg.review.signoff_timeout_seconds, 120, "unset in the override -> the base's value survives, key-by-key, not a whole-block replace");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+// observability.otel is the one nested OBJECT under a top-level key that
+// mergeRawConfig spreads field-by-field, so its merge semantics differ from its
+// siblings' and are worth pinning: `otel:` is replaced as a WHOLE OBJECT by an
+// override that names it (you never want a half-merged endpoint/headers pair —
+// that is how an auth token gets POSTed to the wrong collector), while
+// `observability`'s other keys still merge key-by-key around it. Also the
+// activation contract: absent by default, so no repo starts exporting because
+// it upgraded.
+test("observability.otel survives loadConfig's merge — absent by default, whole-object replace on override", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-otel-merge-test-"));
+    try {
+        const bare = join(dir, "bare.yaml");
+        writeFileSync(bare, "observability:\n  poll_ms: 250\n");
+        assert.equal(loadConfig([bare]).observability.otel, undefined, "no otel: block -> export stays off, the default for every repo");
+        const base = join(dir, "base.yaml");
+        const override = join(dir, "override.yaml");
+        writeFileSync(base, "observability:\n  poll_ms: 250\n  otel:\n    endpoint: http://base-collector:4318/v1/traces\n    headers: {authorization: base-token}\n    service_name: base\n");
+        writeFileSync(override, "observability:\n  otel:\n    endpoint: http://override-collector:4318/v1/traces\n");
+        const cfg = loadConfig([base, override]);
+        assert.equal(cfg.observability.poll_ms, 250, "observability's other keys still merge key-by-key around otel");
+        assert.equal(cfg.observability.otel?.endpoint, "http://override-collector:4318/v1/traces");
+        assert.equal(cfg.observability.otel?.headers, undefined, "whole-object replace: the base's auth header does NOT follow the override's endpoint");
+        assert.equal(cfg.observability.otel?.service_name, "spf", "and the base's service_name doesn't either — the schema default applies");
+        // A single config file must reach SFConfig at all — the silent-drop trap
+        // mergeRawConfig's fixed-shape object literal sets for any new key.
+        const single = join(dir, "single.yaml");
+        writeFileSync(single, "observability:\n  otel:\n    endpoint: https://collector.example.com/v1/traces\n");
+        assert.equal(loadConfig([single]).observability.otel?.endpoint, "https://collector.example.com/v1/traces");
+        // A typo fails at config load, not as a silent per-run export failure.
+        const bad = join(dir, "bad.yaml");
+        writeFileSync(bad, "observability:\n  otel:\n    endpoint: not-a-url\n");
+        assert.throws(() => loadConfig([bad]), /invalid config/, "endpoint is URL-validated");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("EventRecordTypeSchema accepts every observed event type and rejects an unknown one", () => {
+    for (const type of ["phase_start", "agent_start", "tool_call", "handoff", "gate_pass", "gate_fail", "log", "agent_end", "phase_end", "error"]) {
+        assert.equal(v.parse(EventRecordTypeSchema, type), type);
+    }
+    assert.throws(() => v.parse(EventRecordTypeSchema, "bogus_type"), "an event type outside the observed set must be rejected, not silently stored");
+});
+test("AgentConfigSchema: env_allowlist is optional and defaults to undefined (byte-identical to before this field existed)", () => {
+    const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
+    const unset = v.parse(AgentConfigSchema, base);
+    assert.equal(unset.env_allowlist, undefined);
+    const allowlisted = v.parse(AgentConfigSchema, { ...base, env_allowlist: ["MY_API_KEY"] });
+    assert.deepEqual(allowlisted.env_allowlist, ["MY_API_KEY"]);
+    const nulled = v.parse(AgentConfigSchema, { ...base, env_allowlist: null });
+    assert.equal(nulled.env_allowlist, null, "null must parse (the 'unrestricted' spelling config.md teaches for writes)");
+});
+// This is the load-bearing half of the field: the schema merely declares
+// the shape, agentEnv() is what actually filters the operator's own
+// environment down to the allowlist. A test that only exercised the schema
+// (as the previous version of this test did) would never notice agentEnv
+// silently failing to filter anything.
+test("agentEnv: filters the operator environment down to the allowlist plus the baseline keys", () => {
+    const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
+    const savedApiKey = process.env["MY_API_KEY"];
+    const savedSecret = process.env["SECRET_TOKEN"];
+    try {
+        process.env["MY_API_KEY"] = "abc123";
+        process.env["SECRET_TOKEN"] = "should-never-appear";
+        // unset -> undefined: both backends fall back to `request.env ?? operatorEnv()`,
+        // so this is byte-identical to the unfiltered behavior that predates the field.
+        const unset = v.parse(AgentConfigSchema, base);
+        assert.equal(agentEnv(unset), undefined);
+        // [] -> baseline-only: every ENV_BASELINE_KEYS entry actually present in
+        // process.env, and nothing else — SECRET_TOKEN must not leak through.
+        const empty = v.parse(AgentConfigSchema, { ...base, env_allowlist: [] });
+        const baselineOnly = agentEnv(empty);
+        const baselineKeys = ["PATH", "HOME", "USER", "LANG", "TERM", "TMPDIR"];
+        for (const key of Object.keys(baselineOnly)) {
+            assert.ok(baselineKeys.includes(key), `${key} is not a baseline key — [] must yield baseline-only`);
+        }
+        assert.equal(baselineOnly["SECRET_TOKEN"], undefined);
+        assert.equal(baselineOnly["MY_API_KEY"], undefined);
+        // ["MY_API_KEY"] -> baseline + MY_API_KEY, with SECRET_TOKEN provably absent.
+        const allowlisted = v.parse(AgentConfigSchema, { ...base, env_allowlist: ["MY_API_KEY"] });
+        const filtered = agentEnv(allowlisted);
+        assert.equal(filtered["MY_API_KEY"], "abc123");
+        assert.equal(filtered["SECRET_TOKEN"], undefined, "an unrelated secret must not survive the filter");
+        for (const key of Object.keys(filtered)) {
+            assert.ok(baselineKeys.includes(key) || key === "MY_API_KEY", `${key} leaked through the allowlist unexpectedly`);
+        }
+    }
+    finally {
+        if (savedApiKey === undefined)
+            delete process.env["MY_API_KEY"];
+        else
+            process.env["MY_API_KEY"] = savedApiKey;
+        if (savedSecret === undefined)
+            delete process.env["SECRET_TOKEN"];
+        else
+            process.env["SECRET_TOKEN"] = savedSecret;
+    }
+});

package/dist/test/git_helper.test.d.ts

@@ -0,0 +1 @@
+import "./hermetic_git.ts";