@gr8ful/spf 0.4.0 → 0.5.0

package/assets/skill/references/config.md

@@ -12,7 +12,7 @@ always shows the resolved, merged result for the repo you're in.
 1. The packaged built-in default (`assets/defaults/spf.config.yaml` inside
    the installed CLI).
 2. `.spf/spf.config.yaml` in the target repo, if present — merged on top,
-   field by field (`defaults`/`observability`/`quality`/`watch`/`notifications`
+   field by field (`defaults`/`observability`/`quality`/`watch`/`notifications`/`review`
    merge key-by-key — `notifications.channels` replaces wholesale, same as
    `quality.checks`; `agents` merges by `name`: a matching name patches that
    entry, a new name appends).
@@ -72,6 +72,8 @@ agents:
 | `color` | hex string | Lane color fallback for agents that don't set their own. |
 | `harness_engineering` | string[] | **Must stay `[]`** — no analogue on any current backend; a non-empty entry fails validate(). |
 | `tools` | string[] \| null | Roster-wide allowlist. Unset/null = every built-in tool usable. |
+| `writes` | string[] \| null | Roster-wide write allowlist, back-filled onto any agent that doesn't set its own — see `writes` under `agents[]` below for the three-state semantics. |
+| `env_allowlist` | string[] \| null | Roster-wide env allowlist, back-filled the same way as `writes`. Unset/null = every agent gets the full operator environment (see `env_allowlist` under `agents[]`). |
 | `protected_files` | string[] | Paths no agent may touch unless named in its own `writes`. Default `[".spf/", "spf.config.yaml"]`. |
 | `data_dir` | path | Runtime home, repo-relative. Default `.spf/data`. |
 
@@ -81,6 +83,11 @@ agents:
 |---|---|---|
 | `db` | path | The trace sqlite db. Default `.spf/data/spf.db`. |
 | `poll_ms` | int | UI live-poll cadence. Default `500`. |
+| `otel.endpoint` | string | OTLP/HTTP collector endpoint (e.g., `https://your-host/v1/traces`). Omit to disable OTel export. |
+| `otel.headers` | object | Optional HTTP headers (e.g., auth tokens). Each value is a string. |
+| `otel.service_name` | string | Optional service name in exported spans. Default `spf`. |
+
+**No ambient env activation**: OTEL export requires explicit `observability.otel` config — the `OTEL_EXPORTER_OTLP_ENDPOINT` shell variable is never consulted. An unrelated shell env variable must not become a data-egress switch.
 
 ### `quality`
 
@@ -116,7 +123,8 @@ Full mechanism: the main README's "`spf watch`" section. Field reference:
 |---|---|---|
 | `issue_provider` | `"github"` \| `"jira"` | The tracker `spf watch` polls. Default `github`. |
 | `code_host` | `"github"` \| `"bitbucket"` | Where PRs open — independent of `issue_provider` (Jira issues against a Bitbucket repo is a real setup). Default `github`. |
-| `repo` | string | Required once watch is actually run (not schema-validated — fails loudly at `spf watch` startup instead). `"owner/name"` for `code_host: github`, `"workspace/repo_slug"` for `code_host: bitbucket`. |
+| `repo` | string | The **code host's** repo — required once watch is actually run (not schema-validated — fails loudly at `spf watch` startup instead). `"owner/name"` for `code_host: github`, `"workspace/repo_slug"` for `code_host: bitbucket`. |
+| `issue_repo` | string | Overrides `repo` for the **issue tracker** side, only meaningful (and only needed) for `issue_provider: github` + `code_host: bitbucket` — the one combination where the tracker and the code host are genuinely different repos in different systems. Unset (the default) falls back to `repo`, which is exactly right for `github`+`github` (one repo) and for `issue_provider: jira` (which never reads `repo` at all). |
 | `label_prefix` | string | State-machine label prefix — polls/writes `<prefix>:ready`, `<prefix>:working`, etc. Default `spf`. |
 | `chain` | string | Which registered chain runs per claimed `<prefix>:ready` issue. Default `plan-build-test`. |
 | `base_branch` | string | Branch worktrees fork from and PRs target. Default `main`. |
@@ -146,7 +154,9 @@ additionally gets `<prefix>:refined`, so a human can review and promote it to
 `<prefix>:ready` when it's worth building — the refine lane never
 auto-promotes anything.
 
+### `notifications`
 
+Optional outbound push for unattended work — `spf watch`'s daemon lifecycle,
 and every chain run (`spf <chain>` / `spf run`, including watch's own
 per-issue runs). Interactive commands (`doctor`, `list`, `sessions`,
 `phases`, `events`, `init`, `ui`, `migrate`, `eject`, `abort`, `version`)
@@ -187,6 +197,33 @@ run's exit code. See the main README's "Notifications" section for how to
 get each channel's webhook URL, and `spf init`'s interview, which asks for
 this section and collects the URL straight into `.env`.
 
+### `review`
+
+The human sign-off gate in front of `simple-sdlc`'s `commit_build` phase —
+the one place in this codebase an AI reviewer's `approved` flag alone would
+otherwise gate a commit (`build-review` has no commit step, and no other
+chain runs a reviewer at all). See the main README's "Isolation" section for
+the full behavior; this is just the two knobs.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `require_human_signoff` | bool | `false` (default, this release): an unattended run (`spf watch`, CI, no TTY) proceeds on the reviewer's verdict alone, with a loud warning printed and traced every time. `true`: an unattended run instead fails the phase closed — rerun attended, or route the work through `spf watch`, whose own human gate is the PR merge. Never affects an attended run's prompt, which is always shown either way. |
+| `signoff_timeout_seconds` | number ≥1 | Bounds the attended confirm prompt. Default `300`. Not required to be an integer — `1.5` parses and becomes a 1500ms timer. Expiry resolves to the prompt's own default — **not accepted**, same as if the answer had been "no" — never an unbounded `stdin` read inside `run.phase()`. |
+
+```yaml
+review:
+  require_human_signoff: false   # this release's default — see above
+  signoff_timeout_seconds: 300
+```
+
+The confirm prompt's own default is always `false` — never `review.approved`,
+so an AI's own verdict can never auto-approve itself by way of an unanswered
+default. A `Signed-off-by:` trailer is appended to the commit only on a
+recorded explicit "yes," built from `git config user.name`/`user.email` at
+the repo (never `ENGINEER_NAME`/`$USER`, which are spoofable and fall back to
+the literal string `"engineer"`) — an unattended run's AI-only commit never
+carries one, because nobody said yes to attest to.
+
 ### `agents[]`
 
 | Field | Required | Meaning |
@@ -197,6 +234,7 @@ this section and collects the URL straight into `.env`.
 | `coding_agent`, `model`, `thinking`, `color`, `harness_engineering` | no | Override the matching `defaults` key. |
 | `tools` | no | Allowlist. Omitting it means all tools usable. A capability list, not a boundary — see `writes`. |
 | `writes` | no | What this agent may modify **in the repo**, enforced after every call. `undefined`/`null` = unrestricted (still barred from `protected_files`); `[]` = no repo writes; a list = only those paths (trailing `/` = directory prefix, `*` = one path segment, `**` = crosses segments, anything else = exact path). |
+| `env_allowlist` | no | Opt-in filter on the environment handed to this agent's subprocess/sandbox. `undefined` (default) = the full operator environment, unchanged. A list = only those keys, plus the baseline (`PATH`, `HOME`, `USER`, `LANG`, `TERM`, `TMPDIR`) either backend keeps regardless. |
 
 Output types are deliberately absent from config: an entry defines who an
 agent *is*; the call site defines how it's *used*.
@@ -210,7 +248,15 @@ no public model-registry API) — `agents.ts` checks only the static shape at
 first real dispatch instead. Provider credentials come from the
 environment, matching the provider you named (`GEMINI_API_KEY`/
 `GOOGLE_API_KEY` for `google/...`, `ANTHROPIC_API_KEY` for `anthropic/...`,
-etc.) — `spf doctor` checks the common ones are set.
+etc.) — `spf doctor` checks the common ones are set. `ollama/...` is the one
+keyless provider (`PROVIDER_ENV_KEYS.ollama` is `[]`) — instead of a key, set
+`OLLAMA_BASE_URL` (default `http://localhost:11434/v1` if unset) to point at
+your server; the `spf init` interview asks for this instead of a secret when
+you pick `ollama`, and `spf doctor` probes it (informational — a down server
+is reported, never a hard failure). See README.md's "flue + local Ollama"
+section for the full walkthrough and
+[`assets/templates/ts-flue-ollama.spf.config.yaml`](../../templates/ts-flue-ollama.spf.config.yaml)
+for a ready-to-run starting config.
 
 **For `coding_agent: claude_code`:** write `model` in Claude Code's own
 vocabulary — a bare alias (`sonnet`, `opus`) or a full model name — never
@@ -269,4 +315,23 @@ No config section for this — it's an environment-variable recipe, since
 `claude` subprocess, exactly like every other env var. Set
 `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` (local or cloud Ollama) before
 running `spf`; see `roster.md`'s "Coding agent backends" section for the
-exact commands.
+exact commands. `spf doctor` probes `ANTHROPIC_BASE_URL` (informational — a
+down endpoint or wrong path is reported, never a hard failure) and flags a
+base URL that already ends in `/v1` as a likely double-path mistake, since
+the `claude` CLI appends `/v1/messages` itself.
+
+Routing through `SPF_CLAUDE_CMD="ollama launch claude --model granite4.1:8b"`
+instead needs an explicit `--` before `claude`'s own flags (cobra flag
+parsing otherwise consumes them as `ollama launch`'s own) — `agent_cc.ts`
+detects this exact `ollama launch ...` token shape and inserts that
+separator automatically, so you never add it by hand. The `--model` before
+that separator is NOT optional, though: it's `ollama launch`'s own flag, and
+it's mandatory in headless mode (SPF always pipes stdio, so the interactive
+model picker `ollama launch` falls back to without it can never run) — a
+`--model` typed after the `--` belongs to `claude`, not to `ollama launch`,
+and doesn't help. `spf doctor` hard-fails a `SPF_CLAUDE_CMD` missing it. See
+README.md's "Proxy or wrapper launchers" section for the full explanation.
+
+For `flue` (the default backend) pointed at Ollama instead of `claude_code`
+— i.e. `model: ollama/<tag>` — see "Model resolution" above and README.md's
+"flue + local Ollama" section.

package/assets/skill/references/observability.md

@@ -31,8 +31,17 @@ Location comes from `observability.db` in `spf.config.yaml`, default
 | `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.
+`parent_id` is reserved and structurally empty today — SPF's phases are flat
+siblings, and nothing writes nesting into it. The UI reconstructs phase/
+tool-call nesting from `phase_id` plus agent-call bracketing instead of
+reading `parent_id`.
+
+**Optional OTel export.** When `observability.otel.endpoint` is set in
+`spf.config.yaml`, a lossy, allowlisted projection of phase/agent/tool spans
+(status, model, token/cost counts, gate results — never prompts, envelopes,
+tool arguments, or source code) is also pushed to an OTLP/HTTP collector,
+fire-and-forget. SQLite remains the source of truth regardless; see
+`config.md`'s `observability.otel.*` rows for the field reference.
 
 **Spend is itemized per phase.** `agent_end.usage` carries tokens *and*
 dollars for each component Flue reports (matching pi-ai's field names

package/assets/templates/ts-flue-ollama.spf.config.yaml

@@ -0,0 +1,67 @@
+# .spf/spf.config.yaml — Flue backend (the default), routed at a local
+# Ollama server instead of a hosted provider. `spf init --template
+# ts-flue-ollama` writes this file as-is.
+#
+# model: is ALWAYS provider/model-id for Flue — "ollama/<tag>", where <tag>
+# is whatever `ollama list` shows on the machine actually running the model
+# (agent_flue.ts registers each distinct "ollama/<tag>" it sees with Flue's
+# own provider registry the first time it's dispatched — no separate model
+# catalog to keep in sync here). agents.validate() only checks the STRING
+# SHAPE (provider/id, via agent_flue.ts's resolveModel()) — never that the
+# tag actually exists on the server. A wrong or not-yet-pulled tag only
+# surfaces at the first real dispatch, as an "Unknown model" error from
+# Ollama itself, not at validate() time.
+#
+# The two model ids below (qwen3.8:27b-mlx, granite4.1:8b) are EXAMPLES from
+# one spike machine's own `ollama list` output, not a stable public catalog —
+# replace both with whatever `ollama list` shows on YOUR machine before
+# running spf. Nothing here pins a specific model family; the split is
+# purely "heavier reasoning agent" vs. "lighter/faster agent", same as any
+# other template's planner-vs-builder split.
+#
+# ollama is a KEYLESS provider (providers.ts's PROVIDER_ENV_KEYS.ollama is
+# `[]`) — no API key to export. What IS required:
+#   export OLLAMA_BASE_URL=http://localhost:11434/v1   # default if unset
+# `spf doctor` probes OLLAMA_BASE_URL/models (informational, never a hard
+# failure) so a server that isn't running shows up before your first real
+# run does, not during it.
+#
+# Context-window occupancy reporting is disabled for every ollama/* model:
+# agent_flue.ts registers these models with contextWindow: 0 (spike-verified
+# safe — the same convention agent_flue.ts already uses for
+# context_window: 0 elsewhere), which turns off threshold-based compaction
+# rather than reporting a fabricated number Ollama's OpenAI-compatible API
+# doesn't actually provide per-model.
+quality:
+  checks:
+    - { name: typecheck, operation: typecheck, argv: ["npm", "run", "typecheck"], timeout_seconds: 60 }
+    - { name: lint, operation: lint, argv: ["npm", "run", "lint"], timeout_seconds: 60 }
+    - { name: build, operation: build, argv: ["npm", "run", "build"], timeout_seconds: 300 }
+    - { name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 300 }
+  suites:
+    test: [test]
+    all: [typecheck, lint, build, test]
+
+defaults:
+  coding_agent: flue
+  # EXAMPLE tag — replace with a heavier model from your own `ollama list`.
+  model: ollama/qwen3.8:27b-mlx
+
+# Overridden here (unlike the OpenRouter template's rationale, which applies
+# equally): the packaged roster's planner/reviewer/documenter pin their own
+# Flue-style provider/model-id strings (fireworks/openai models), unrelated
+# to a local Ollama server — left alone, those three would still resolve and
+# run fine, just against a hosted provider's key this template never asks
+# for. Overridden so every agent actually demonstrates local-only routing.
+agents:
+  - name: planner
+    model: ollama/qwen3.8:27b-mlx
+  - name: reviewer
+    model: ollama/qwen3.8:27b-mlx
+  - name: documenter
+    # EXAMPLE tag — replace with a lighter/faster model from your own
+    # `ollama list`. Tool-calling (the injected sf_report contract every
+    # agent's structured output rides on) was spike-verified to work down to
+    # a 3B model — a lighter tag here is a real, not merely theoretical,
+    # option.
+    model: ollama/granite4.1:8b

package/assets/templates/ts.spf.config.yaml

@@ -61,6 +61,11 @@ agents:
 # Needs a GITHUB_TOKEN env var (classic PAT, repo scope) for the defaults below.
 # watch:
 #   repo: owner/name
+#   # issue_repo: owner/name   # ONLY for issue_provider: github + code_host: bitbucket,
+#   #                          # where the issue tracker and code host are genuinely
+#   #                          # different repos — repo above is then the BITBUCKET
+#   #                          # repo, and issue_repo is the GitHub one. Unused/unset
+#   #                          # for every other combination.
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main

package/dist/chains/context.d.ts

@@ -27,4 +27,34 @@ export interface ChainContext {
      * ignores this field.
      */
     issue_id?: string | null;
+    /**
+     * True when no human is at the keyboard for this run — `spf watch`'s
+     * daemon lane, a cron/CI invocation — false for an interactive
+     * `spf <chain> "..."`.
+     *
+     * REQUIRED, deliberately: it is not a flag a call site may forget. Every
+     * ChainContext construction site has to state which lane it is, because
+     * "unattended" is what makes several safety rules non-negotiable rather
+     * than merely advisable — most concretely, a repo-local chain
+     * (`.spf/chains/*.yaml`) may only ADD gates, never drop a built-in one
+     * (see `steps.ts`'s GATE_ALLOWLIST comment): there is nobody watching the
+     * console to notice that `diffMatchesClaims` was quietly turned off. A
+     * boolean that defaults to `false` would make the dangerous lane the one
+     * you get by accident.
+     */
+    unattended: boolean;
+    /**
+     * Absolute path of the YAML file this chain was loaded from, when it is a
+     * repo-local chain (`.spf/chains/<name>.yaml` — see
+     * `chains/repo_chains.ts`). `undefined` for a built-in chain, which has no
+     * file: it IS spf's own code.
+     *
+     * `steps.startRun()` writes this into the trace as a single
+     * `chain_source` log event, so a session in the UI or in `spf trace` can
+     * always answer "whose chain definition ran this?" — the answer stops
+     * being obvious the moment a target repo can ship its own chains, and the
+     * trace is the only durable record (the YAML file itself may have been
+     * edited by the time anyone reads the run back).
+     */
+    chain_source?: string;
 }

package/dist/chains/index.d.ts

@@ -1,14 +1,34 @@
 /**
- * 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.
+ * The chain registry — the one place a CLI-facing short name resolves to a
+ * chain. `spf list` reads it; `spf <name>`/`spf run <name>` dispatch through
+ * it. Replaces guessing a module filename from the CLI argument.
  *
- * Every chain but `simple-sdlc` is a flat `steps` list composed from
- * `./steps.ts`'s primitives — no module of its own, and no hand-written
- * `phases`/`requiredAgents`/`requiredSuites` to keep in sync with what
- * actually runs; those are derived from the step list itself.
- * `simple-sdlc`'s three-commit, pinned-baseline shape is still imperative —
- * see `./simple_sdlc.ts` — via the `run` escape hatch below.
+ * TWO TIERS, and the distinction is load-bearing:
+ *
+ *  1. BUILT-INS — `CHAINS`, below. Compiled in, always present, the same in
+ *     every repo spf is ever run against. Every one but `simple-sdlc` is a
+ *     flat `steps` list composed from `./steps.ts`'s primitives — no module
+ *     of its own, and no hand-written `phases`/`requiredAgents`/
+ *     `requiredSuites` to keep in sync with what actually runs; those are
+ *     derived from the step list itself. `simple-sdlc`'s three-commit,
+ *     pinned-baseline shape is still imperative — see `./simple_sdlc.ts` —
+ *     via the `run` escape hatch below.
+ *  2. REPO-LOCAL CHAINS — registered at CLI startup from
+ *     `<repo>/.spf/chains/*.yaml` by `registerRepoChains()`, having been
+ *     read by `./repo_chains.ts`. These are DATA: a yaml file names built-in
+ *     step factories and passes them params. It cannot introduce code, and
+ *     it runs on the same `steps.runSteps()` driver as a built-in, because
+ *     "agent proposes, code disposes" only means anything if the code that
+ *     disposes is SPF's code — not the target repo's.
+ *
+ * `CHAINS` stays a built-in-only const: nothing ever pushes into it, and
+ * `src/test/chains.test.ts` pins its exact name set. Repo chains live in a
+ * separate module-level list that `registerRepoChains()` REPLACES (never
+ * appends to), so a second registration — a long-lived process, `spf watch`
+ * re-reading after an edit, a test — cannot double-register a name. Read
+ * both tiers through `allChains()`; built-ins always come first, and
+ * `findChain()` resolves them first, so a built-in name can never be
+ * shadowed by a file on disk.
  */
 import type { ChainContext } from "./context.ts";
 import * as steps from "./steps.ts";
@@ -19,15 +39,79 @@ export interface ChainDefinition {
     phases: string;
     /** Static for most chains; prompt's depends on --agent, so it's a function there. */
     requiredAgents: string[] | ((options: Record<string, string>) => string[]);
-    requiredSuites: string[];
+    /** Static unless a step's suite can be overridden by --suite (qualityCheck/fixLoop), in which case it's a function — see steps.deriveRequiredSuites. */
+    requiredSuites: string[] | ((options: Record<string, string>) => string[]);
     /** The declarative path — a flat step list, run by runChain() via steps.runSteps(). */
     steps?: steps.Step[];
     /** The imperative escape hatch for a chain too shaped by its own logic to be a flat list (simple-sdlc). */
     run?: (ctx: ChainContext, options?: Record<string, string>) => Promise<number>;
+    /**
+     * Absolute path of the `.spf/chains/*.yaml` this chain was loaded from —
+     * set only for a repo-local chain, `undefined` for a built-in (a built-in
+     * has no source file: it IS spf). The CLI copies it into
+     * `ChainContext.chain_source` so the run's trace records whose definition
+     * ran, and `spf list`/`spf doctor` use its presence to mark which chains
+     * came from the repo.
+     */
+    source?: string;
 }
+/**
+ * Build a step-based ChainDefinition, deriving phases/requiredAgents/
+ * requiredSuites from its steps.
+ *
+ * Exported so `./repo_chains.ts` builds a yaml-defined chain through the
+ * EXACT same function as a built-in. That is deliberate and should not be
+ * "simplified" into a second, parallel constructor: a repo chain must be
+ * indistinguishable downstream — same derivation of phases/agents/suites,
+ * same `steps` array, same `runSteps` driver, one run path — or the
+ * guarantees the built-ins are tested for stop applying to it.
+ */
+export declare function stepChain(name: string, describe: string, list: steps.Step[]): ChainDefinition;
 export declare const CHAINS: ChainDefinition[];
+/**
+ * Every built-in name, reserved. `repo_chains.ts` checks against this to
+ * refuse a repo chain that reuses one — a collision is reported as a
+ * problem, never resolved by shadowing either way round.
+ */
+export declare const BUILTIN_CHAIN_NAMES: ReadonlySet<string>;
+/**
+ * Install the repo-local chains (and the problems found reading them) for
+ * this process. Call once, early, from the CLI entry point.
+ *
+ * REPLACES rather than appends, so it is idempotent: calling it twice with
+ * the same input leaves exactly one copy of each chain. That matters because
+ * a long-running `spf watch` may re-read `.spf/chains/` after an edit, and
+ * because a partial second registration (say, one file fixed) must not leave
+ * the previous file's stale definition behind.
+ *
+ * The `problems` list is stored, not thrown and not printed: loading is
+ * never allowed to fail a command that has nothing to do with the broken
+ * file (`spf trace`, `spf sessions`, `spf --version` must all still work in
+ * a repo with one malformed yaml). `spf list` and `spf doctor` surface them;
+ * dispatch surfaces them when the name someone typed is missing.
+ */
+export declare function registerRepoChains(chains: ChainDefinition[], problems: {
+    file: string;
+    message: string;
+}[]): void;
+/** Built-ins first, then repo-local chains — the order `spf list` prints and `findChain` resolves in. */
+export declare function allChains(): ChainDefinition[];
+/** What went wrong reading `.spf/chains/*.yaml`, for `spf list`/`spf doctor` to report. */
+export declare function repoChainProblems(): {
+    file: string;
+    message: string;
+}[];
+/**
+ * Resolve a CLI-facing name. Built-ins are consulted FIRST and win
+ * unconditionally — a repo chain that reuses a built-in name is rejected at
+ * load time (see `repo_chains.ts`), so this ordering is a second line of
+ * defence rather than the policy itself, and it is what makes `spf build` in
+ * any repo mean what the docs say it means.
+ */
 export declare function findChain(name: string): ChainDefinition | undefined;
 export declare function resolveRequiredAgents(chain: ChainDefinition, options: Record<string, string>): string[];
+/** Same idea as resolveRequiredAgents(), for the suite(s) --suite can override before validate() ever runs. */
+export declare function resolveRequiredSuites(chain: ChainDefinition, options: Record<string, string>): string[];
 /**
  * Run a chain, whichever path it defines: `run` (the imperative escape
  * hatch) if it has one, otherwise `steps` through the shared driver. Both

package/dist/chains/index.js

@@ -1,7 +1,17 @@
 import * as steps from "./steps.js";
 import * as simpleSdlc from "./simple_sdlc.js";
-/** Build a step-based ChainDefinition, deriving phases/requiredAgents/requiredSuites from its steps. */
-function stepChain(name, describe, list) {
+/**
+ * Build a step-based ChainDefinition, deriving phases/requiredAgents/
+ * requiredSuites from its steps.
+ *
+ * Exported so `./repo_chains.ts` builds a yaml-defined chain through the
+ * EXACT same function as a built-in. That is deliberate and should not be
+ * "simplified" into a second, parallel constructor: a repo chain must be
+ * indistinguishable downstream — same derivation of phases/agents/suites,
+ * same `steps` array, same `runSteps` driver, one run path — or the
+ * guarantees the built-ins are tested for stop applying to it.
+ */
+export function stepChain(name, describe, list) {
     return {
         name,
         describe,
@@ -63,19 +73,74 @@ export const CHAINS = [
         name: "simple-sdlc",
         describe: "the work is real and its shape is not obvious — plan, build, test, review, document; 3 commits",
         phases: "engineer(request) -> planner -> 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)",
         requiredAgents: simpleSdlc.REQUIRED_AGENTS,
         requiredSuites: simpleSdlc.REQUIRED_SUITES,
         run: simpleSdlc.main,
     },
 ];
+/**
+ * Every built-in name, reserved. `repo_chains.ts` checks against this to
+ * refuse a repo chain that reuses one — a collision is reported as a
+ * problem, never resolved by shadowing either way round.
+ */
+export const BUILTIN_CHAIN_NAMES = new Set(CHAINS.map((c) => c.name));
+// ── tier 2: repo-local chains, registered at startup ────────────────────
+/**
+ * Module-level, not a parameter threaded through every call site: `spf list`,
+ * `spf <chain>`, `spf watch`, `spf doctor` and the interview all resolve
+ * chains by name from unrelated places, and passing a registry object to
+ * each would mean four more chances for one of them to be looking at the
+ * built-ins only. One process, one repo, one registration.
+ */
+let REPO_CHAINS = [];
+let REPO_CHAIN_PROBLEMS = [];
+/**
+ * Install the repo-local chains (and the problems found reading them) for
+ * this process. Call once, early, from the CLI entry point.
+ *
+ * REPLACES rather than appends, so it is idempotent: calling it twice with
+ * the same input leaves exactly one copy of each chain. That matters because
+ * a long-running `spf watch` may re-read `.spf/chains/` after an edit, and
+ * because a partial second registration (say, one file fixed) must not leave
+ * the previous file's stale definition behind.
+ *
+ * The `problems` list is stored, not thrown and not printed: loading is
+ * never allowed to fail a command that has nothing to do with the broken
+ * file (`spf trace`, `spf sessions`, `spf --version` must all still work in
+ * a repo with one malformed yaml). `spf list` and `spf doctor` surface them;
+ * dispatch surfaces them when the name someone typed is missing.
+ */
+export function registerRepoChains(chains, problems) {
+    REPO_CHAINS = [...chains];
+    REPO_CHAIN_PROBLEMS = [...problems];
+}
+/** Built-ins first, then repo-local chains — the order `spf list` prints and `findChain` resolves in. */
+export function allChains() {
+    return [...CHAINS, ...REPO_CHAINS];
+}
+/** What went wrong reading `.spf/chains/*.yaml`, for `spf list`/`spf doctor` to report. */
+export function repoChainProblems() {
+    return [...REPO_CHAIN_PROBLEMS];
+}
+/**
+ * Resolve a CLI-facing name. Built-ins are consulted FIRST and win
+ * unconditionally — a repo chain that reuses a built-in name is rejected at
+ * load time (see `repo_chains.ts`), so this ordering is a second line of
+ * defence rather than the policy itself, and it is what makes `spf build` in
+ * any repo mean what the docs say it means.
+ */
 export function findChain(name) {
-    return CHAINS.find((c) => c.name === name);
+    return CHAINS.find((c) => c.name === name) ?? REPO_CHAINS.find((c) => c.name === name);
 }
 export function resolveRequiredAgents(chain, options) {
     return typeof chain.requiredAgents === "function" ? chain.requiredAgents(options) : chain.requiredAgents;
 }
+/** Same idea as resolveRequiredAgents(), for the suite(s) --suite can override before validate() ever runs. */
+export function resolveRequiredSuites(chain, options) {
+    return typeof chain.requiredSuites === "function" ? chain.requiredSuites(options) : chain.requiredSuites;
+}
 /**
  * Run a chain, whichever path it defines: `run` (the imperative escape
  * hatch) if it has one, otherwise `steps` through the shared driver. Both
@@ -86,5 +151,5 @@ export function resolveRequiredAgents(chain, options) {
 export async function runChain(chain, ctx, options = {}) {
     if (chain.run)
         return chain.run(ctx, options);
-    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), chain.requiredSuites, chain.steps, options);
+    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), resolveRequiredSuites(chain, options), chain.steps, options);
 }

package/dist/chains/repo_chains.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Repo-local chains: `<repo>/.spf/chains/*.yaml` read as DATA.
+ *
+ * WHAT THIS IS. A target repo can compose its own chain out of the step
+ * factories `./steps.ts` already exports, by naming them in a yaml file and
+ * passing them params. One file, one chain:
+ *
+ *     # .spf/chains/ship-it.yaml
+ *     name: ship-it
+ *     describe: plan, build, test, land — with our own reviewer in the loop
+ *     steps:
+ *       - step: request
+ *       - step: plan
+ *         owner: architect
+ *       - step: build
+ *         retries: 2
+ *         extraGates: [jsonParses]
+ *       - step: fixLoop
+ *         suite: test
+ *       - step: commit
+ *         onlyIfAccepted: true
+ *
+ * WHY DATA, AND NOT CODE. SPF's contract is "agent proposes, code disposes",
+ * and the code that disposes is SPF'S code. A chain that could `import`
+ * something out of the target repo would move the disposer into the repo
+ * being worked on — the agent's own blast radius — and there would be
+ * nothing left holding the line. So a repo chain names existing factories
+ * and nothing else: no expressions, no shell, no module paths, no way to
+ * introduce behavior that isn't already compiled into spf and covered by
+ * spf's tests. It is also what keeps the promise that a target repo is
+ * zero-setup and language-agnostic: the only thing it ever gains is `.spf/`,
+ * with no build step, no dependency on this package, and nothing to compile.
+ *
+ * The counterpart rule lives in `steps.ts` (see GATE_ALLOWLIST): params may
+ * only ADD. A repo chain can demand more checking than a built-in does; it
+ * can never demand less.
+ *
+ * ONE RUN PATH. Every chain here is built with `index.ts`'s `stepChain()` —
+ * the very same function the built-ins use — so it is a plain
+ * `ChainDefinition` with a `steps` array, its `phases`/`requiredAgents`/
+ * `requiredSuites` derived by the same code, executed by the same
+ * `steps.runSteps()` driver. There is deliberately no second interpreter,
+ * no "yaml runtime", and no branch anywhere downstream on "is this a repo
+ * chain": the only difference a repo chain carries is `source`, the file it
+ * came from, which exists so a run can be traced back to a definition that
+ * may since have been edited.
+ *
+ * NEVER THROWS. `loadRepoChains()` returns `{ chains, problems }`. That is
+ * not politeness: this function runs at CLI startup for EVERY command (see
+ * `cli/index.ts`), so a single malformed yaml must not be able to break
+ * `spf sessions`, `spf trace`, `spf doctor` or `spf --version` in a repo
+ * that has one. Anything that goes wrong — unreadable directory, invalid
+ * yaml, unknown step, wrong param type, bad description, unknown gate,
+ * colliding name — becomes a `{ file, message }` problem carrying enough
+ * detail to fix the file, and the other files still load.
+ *
+ * THE VOCABULARY IS THE FACTORY SIGNATURE. A step's yaml name is its
+ * exported function name (`fixLoop`, `promptOnly`, `publishIssues`) and its
+ * params are that function's `opts` keys, camelCase and all (`extraGates`,
+ * `onlyIfAccepted`, `fromPlan`). No snake_case aliasing, no renaming layer:
+ * a second spelling of the same thing is a second thing to keep in sync, and
+ * a chain author reading `steps.ts` (or `spf list`) would be reading a
+ * vocabulary that isn't the one they type. The schemas below are the ONE
+ * place that mapping is written down; each mirrors exactly one factory's
+ * `opts`, and adding a param to a factory without adding it here simply
+ * means yaml cannot reach it yet (a safe, loud default: unknown params are
+ * rejected, never ignored).
+ */
+import * as v from "valibot";
+import type * as paths from "../core/paths.ts";
+import * as steps from "./steps.ts";
+import { type ChainDefinition } from "./index.ts";
+/** What went wrong in one file, and which file. */
+export interface RepoChainProblem {
+    /** Absolute path — the thing the operator has to open and edit. */
+    file: string;
+    message: string;
+}
+/**
+ * A step's yaml surface: the schema its params must satisfy, and how to
+ * build the actual `Step` from them.
+ *
+ * `params` is redundant with the schema's own entries, and kept anyway: it
+ * lets an unknown param be reported as `unknown param "ownr" — allowed:
+ * owner, description, ...`, which is what an author needs, instead of
+ * valibot's structural complaint about an unexpected key.
+ */
+export interface StepSpec {
+    schema: v.GenericSchema;
+    build: (params: any) => steps.Step;
+    params: readonly string[];
+}
+/**
+ * One entry per exported flat-step factory in `steps.ts`. The key is what a
+ * yaml `step:` names.
+ *
+ * `qualityCheck`/`fixLoop` default their `suite` HERE as well as in the
+ * factory signature: the factory's default lives on the whole `opts` object
+ * (`opts = { suite: "test" }`), which a yaml-supplied `{}` would satisfy
+ * without ever supplying `suite`. Defaulting in the schema is what makes
+ * `- step: fixLoop` with no params mean the same thing as `fixLoop()`.
+ */
+export declare const STEP_SPECS: Record<string, StepSpec>;
+/** Every step name a yaml file may use — for schema validation and for error messages. */
+export declare const STEP_NAMES: readonly string[];
+/**
+ * The whole file. One document, one chain — deliberately not a list: the
+ * filename then documents which chain lives where, and a problem can point
+ * at a file the operator can open, which is the only handle they have.
+ *
+ * `steps` is validated loosely here (each entry only has to be an object
+ * naming a `step`); the per-step params are validated against that step's
+ * own schema afterwards, because which schema applies depends on the value
+ * of `step`.
+ */
+export declare const RepoChainFileSchema: v.StrictObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<"name is required — it is what `spf <name>` types">, v.RegexAction<string, "name must be lowercase letters/digits/._- and start with a letter or digit (it is typed on the command line)">]>;
+    readonly describe: v.SchemaWithPipe<readonly [v.StringSchema<"describe is required — it is the line `spf list` prints">, v.MinLengthAction<string, 1, "describe must not be empty">]>;
+    readonly steps: v.SchemaWithPipe<readonly [v.ArraySchema<v.LooseObjectSchema<{
+        readonly step: v.StringSchema<"each step entry needs a `step:` naming a step factory">;
+    }, undefined>, "steps must be a list">, v.MinLengthAction<({
+        step: string;
+    } & {
+        [key: string]: unknown;
+    })[], 1, "steps must name at least one step — a chain with no steps would run nothing and report success">]>;
+}, undefined>;
+export type RepoChainFile = v.InferOutput<typeof RepoChainFileSchema>;
+/**
+ * Read every chain in `<anchor.spf_dir>/chains/`.
+ *
+ * Never throws (see the module header). Returns the chains that loaded and a
+ * problem per file that didn't; a file contributes at most one chain and, on
+ * failure, exactly one problem — the first thing wrong with it, because the
+ * second is usually a consequence of the first.
+ */
+export declare function loadRepoChains(anchor: paths.RepoAnchor): {
+    chains: ChainDefinition[];
+    problems: RepoChainProblem[];
+};