@gr8ful/spf 0.5.0 → 0.6.0

package/README.md

@@ -383,9 +383,10 @@ A product spec isn't individually workable — it needs to become a feature,
 broken down into user stories and bugs, before the build lane above has
 anything to claim. `watch.refine` is a second lane over the same poll loop
 that does exactly that: it polls `<prefix>:spec-ready`, runs a decomposition
-chain (`refine` by default) against the spec in its own worktree, and
-publishes what it produces as real tracker issues — a feature/epic container
-plus story/bug/task leaves, linked via GitHub's native sub-issue hierarchy.
+chain (`refine` by default — `request → scout → refiner → publish`) against
+the spec in its own worktree, and publishes what it produces as real tracker
+issues — a feature/epic container plus story/bug/task leaves, linked via
+GitHub's native sub-issue hierarchy.
 
 ```yaml
 watch:
@@ -406,22 +407,62 @@ into twenty stories doesn't turn into twenty unattended chain runs and twenty
 PRs with nobody having looked at the breakdown first. Once you do promote a
 leaf, the existing build lane picks it up completely unchanged.
 
-The spec issue itself gets a `spec-ready → refining → done`/`blocked`
-lifecycle, same shape as the build lane, and a summary comment listing every
-issue it created. Try it by hand first, against a real spec, before turning
-on the daemon:
+Grounding the decomposition in real code is structural, not just prose: a
+`scout` phase maps the subsystems the spec touches before the refiner ever
+runs, and its findings flow straight into the refiner as context. This makes
+`scout` a required agent for the `refine` chain — a roster that pruned it
+fails `spf watch` startup by name, the same as any other missing required
+agent.
+
+#### Human-in-the-loop escalation
+
+The refiner is instructed not to guess on anything material (scope, data
+model, an external dependency choice, a UX contract, a breaking change, or
+anything that would contradict an existing ADR — see
+`assets/prompts/refiner/system.md`'s "Ask, don't decide"). When it hits real
+ambiguity it raises questions instead of publishing a partial tree, and the
+spec moves through an extra loop before it reaches `done`:
+
+```text
+spec-ready → refining ──┬─→ done / blocked            (published a tree)
+                         └─→ needs-feedback            (raised questions)
+                                  │  a human answers in the issue's comments,
+                                  │  then adds continue-refinement
+                                  ▼
+                            refining (again, same adw_id) → ...
+```
+
+Answer the refiner's questions as comments on the spec issue, then add the
+`<prefix>:continue-refinement` label. `spf watch` resumes the **same**
+`adw_id` — the refiner's own coding-agent session continues, with the
+comment thread folded into its prompt — so it never re-derives context it
+already had, and it can loop through as many rounds as it takes; there's no
+cap. If channels are configured (see "Notifications" below), a
+`spec_needs_feedback` event fires every round.
+
+The spec issue itself moves through a `spec-ready → refining →
+needs-feedback ⇄ refining → done`/`blocked` lifecycle (the `needs-feedback ⇄
+refining` loop only when the refiner actually escalates), and a summary
+comment lists every issue it created — noting how many rounds of feedback it
+took, if any. Once a spec reaches `done`, `spf watch` also closes the issue
+on the tracker (best-effort: a tracker or a failed close never turns a
+successfully refined spec back to `blocked`). Try it by hand first, against
+a real spec, before turning on the daemon:
 
 ```bash
 spf refine "<spec text or path/to/spec.md>" --issue 42   # --issue renders a "## Parent: #42" back-reference
 ```
 
-`spf watch init` seeds the type labels alongside the state ones. This lane's
-prompt (`assets/prompts/refiner/`) is adapted from a "tracer-bullet ticket"
-decomposition skill — vertical slices, a `blocked_by` dependency graph, and
-an expand/migrate/contract sequence for wide mechanical refactors — with a
-gate (`gates.refinementWellFormed`) added on top to enforce the
+`spf watch init` seeds the type labels alongside the state ones — **re-run
+it** after upgrading to this version, so it can create the new
+`<prefix>:needs-feedback` and `<prefix>:continue-refinement` labels. This
+lane's prompt (`assets/prompts/refiner/`) is adapted from a "tracer-bullet
+ticket" decomposition skill — vertical slices, a `blocked_by` dependency
+graph, and an expand/migrate/contract sequence for wide mechanical refactors
+— with a gate (`gates.refinementWellFormed`) added on top to enforce the
 container/leaf shape that skill left as prose convention rather than a
-checked rule.
+checked rule, now also enforcing that a refinement never publishes issues and
+raises questions in the same round.
 
 ### GitHub (`issue_provider: github` and/or `code_host: github`)
 
@@ -482,10 +523,13 @@ notifications:
 ```
 
 `events` is the whole filter: `errors` sends only failed runs/phases, blocked
-issues, and watch errors; `all` adds every milestone — run started/finished,
-issue claimed, PR opened, issue done. A channel's own `events` overrides the
-top-level scope for just that channel. `spf doctor` reports whether each
-configured channel's env var is set.
+issues, watch errors, and a spec needing feedback (`spec_needs_feedback` —
+see "Human-in-the-loop escalation" above; it's `error`-level on purpose, the
+same class of event as a blocked issue, so an `errors`-scope channel sees it
+too); `all` adds every milestone — run started/finished, issue claimed, PR
+opened, issue done. A channel's own `events` overrides the top-level scope
+for just that channel. `spf doctor` reports whether each configured
+channel's env var is set.
 
 The webhook URL is a secret and lives only in `.env` — `webhook_url_env`
 names the key, never the URL itself, matching `GITHUB_TOKEN`/

package/assets/defaults/spf.config.yaml

@@ -52,6 +52,74 @@ observability:
 #       test: [test]
 #       all: [test, lint]
 
+# OFF by default, and absence/false is a TOTAL no-op: every agent dispatches
+# at exactly the model its roster entry names, byte-identically to before
+# this key existed. Same discipline as max_run_cost/max_run_tokens
+# (data_types.ts:463-491): a repo that upgrades must not silently start
+# routing its phases to different models.
+#
+# Turning it on is a deliberate edit, or `spf init --template ts-flue-ollama`
+# (the one packaged template whose two rungs are MEASURED). `spf init`'s
+# interview does NOT write this block — see config.md's "tiering" section
+# for why.
+tiering:
+  enabled: false
+
+  # The ladder, WEAKEST FIRST. A SEQUENCE, not a mapping: order is the whole
+  # semantics here (a risk level shifts every routed role UP or DOWN this
+  # list), and a YAML sequence states order unambiguously where a mapping
+  # would make it depend on the parser preserving key order.
+  #
+  # `coding_agent` (default "flue", the same default an agent's own field
+  # uses) declares WHICH BACKEND'S VOCABULARY this rung's `model` speaks. It
+  # is not optional in spirit: a tier changes an agent's `model` and NOTHING
+  # else — `coding_agent` is a per-agent field and always stays the agent's
+  # own — so a rung can only route roles whose backend matches. See
+  # config.md's "tiering" section for rule T, and note that this is what
+  # makes "validated by the same backend branch agents.validate() uses" an
+  # answerable question: the branch is the TIER's declared backend.
+  #
+  # `model` then speaks EXACTLY the same vocabulary as an agent's own `model:`
+  # for that backend — provider/model-id for flue, Claude Code's bare alias for
+  # claude_code. There is deliberately no per-provider table: for flue the
+  # provider is already the first segment of the value.
+  #
+  # WHEN tiering.enabled, `spf doctor` runs the SAME provider-key and
+  # model-shape checks over these rungs that it already runs over
+  # cfg.agents[].model — a rung naming a provider whose key is unset is a
+  # green doctor and a first-dispatch failure otherwise. When tiering is
+  # DISABLED (which is this file's shipped state) doctor does not look at
+  # `tiers` at all, so shipping this populated ladder cannot fail `spf
+  # doctor` in a repo that never opted in.
+  tiers:
+    - { name: scout,   coding_agent: flue, model: google/gemini-3.6-flash }
+    - { name: builder, coding_agent: flue, model: fireworks/accounts/fireworks/models/kimi-k3 }
+    - { name: deep,    coding_agent: flue, model: openai/gpt-5.6-terra }
+
+  # Baseline tier per ROLE (an agent name). Naming an agent here IS the
+  # operator's statement "route this one by tier" — so the resolved tier wins
+  # over that agent's own `model:`. An agent NOT named here is never retiered:
+  # its `model:` stands, untouched. That is the whole precedence rule.
+  #
+  # A key naming an agent this repo's roster does not define is NOT a global
+  # error — it is only reported for a chain that actually requires that
+  # agent. A pruned or renamed roster must not fail every chain.
+  #
+  # NOTE for the two packaged templates that set `defaults.coding_agent:
+  # claude_code` (ts, ts-cc): this `roles` map and the flue-shaped `tiers`
+  # above survive into their effective config through key-by-key merge. That
+  # is harmless while `enabled: false`. Flip `enabled: true` there without
+  # also declaring your own ladder and validate() fails LOUDLY by name on the
+  # backend mismatch (rule T) rather than dispatching a `fireworks/...` id
+  # through Claude Code.
+  roles:
+    scout:      scout
+    documenter: scout
+    planner:    builder
+    builder:    builder
+    refiner:    builder
+    reviewer:   deep
+
 agents:
   - name: planner
     model: fireworks/accounts/fireworks/models/kimi-k3

package/assets/prompts/refiner/system.md

@@ -12,6 +12,38 @@ Decompose a product spec into a feature/story-or-bug tree of vertical slices the
 - Judge any command you run by its exit status, never by scanning its output for words. `error` or `not found` inside passing output is text, not a failure.
 - Write your working notes to `<context_handoff_dir>/refine_plan.md` before emitting your Report JSON.
 
+## Grounding: tie every slice to real code
+
+A scout has already mapped the subsystems this spec touches — its findings arrive as `previous_envelope`. Read them, then read the files they name yourself: a scout finding is a pointer, not a substitute for looking. Before writing a single slice, be able to name the concrete modules, functions, or types each slice will touch. Record what you read and what you concluded in `refine_plan.md`.
+
+A slice you cannot tie to code that actually exists is not a slice — it is a guess wearing a slice's shape. Turn it into a question instead (see below).
+
+## Ask, don't decide
+
+You will hit real ambiguity: places where the spec (or the codebase, or both) genuinely supports more than one answer, and picking wrong wastes real engineering time on the wrong tree. Escalate those to a human rather than deciding for them. You MUST escalate, rather than guess, anything touching:
+
+- **Scope boundaries** — is X in or out of this decomposition.
+- **Data model or schema shape** — a new field, table, or type whose shape isn't implied by what already exists.
+- **Choice of external service or dependency** — which library, API, or vendor.
+- **Auth or permission semantics** — who can do what.
+- **User-facing contract or UX behavior** — what the feature actually does from the outside, when the spec doesn't pin it down.
+- **Breaking changes and migration strategy** — whether existing behavior/data changes shape, and how the transition is sequenced.
+- **Non-functional targets** — performance, scale, availability numbers the spec doesn't state.
+- **Anything that would contradict an existing ADR.**
+
+You MAY decide these yourself, following whatever pattern the codebase already uses — that's ordinary judgment, not ambiguity: naming, file placement, test framework and layout, internal module structure, and the ordering of independent slices.
+
+When you escalate, ask **everything you need in one batch** — don't trickle questions across rounds when you could have asked them all up front. Emit **no `issues`** in a round where you're asking questions; the two are mutually exclusive and a gate enforces it. For each question, give a human enough to answer in a word or two:
+
+- `why_it_matters` — what goes wrong if this gets guessed instead of decided.
+- `options` — the plausible answers you found, if there's a short list.
+- `recommendation` — your own best guess, so "go with your recommendation" is a valid answer.
+- `evidence` — the files/symbols that framed the question.
+
+## Resuming after a human answers
+
+A resumed run's prompt includes the issue's comment thread, split into "answers to your open questions" and "earlier discussion." Treat the answers as **authoritative** — never re-ask a question that's been answered. If an answer is itself ambiguous or incomplete, ask one narrower follow-up rather than repeating the original question.
+
 ## The tree
 
 Every node you produce is either a **container** (`epic` or `feature` — exists only to group other nodes; never itself a unit of work) or a **leaf** (`story`, `bug`, or `task` — the independently workable unit). A node is a container exactly when some other node names it as `parent`; everything else is a leaf. At least one leaf is required — a decomposition that is all containers has produced nothing to build.
@@ -45,9 +77,3 @@ If even a batch can't stay green alone, keep the same three-stage sequence but l
 - Avoid specific file paths or code snippets; they go stale fast. Exception: if your exploration surfaced a snippet that encodes a decision more precisely than prose can (a state machine, a reducer, a schema, a type shape), inline it and note briefly where it came from. Trim to the decision-rich part, not a working demo.
 - Do **not** write a "Blocked by" or "Parent" section into `body` yourself — the harness renders both from `blocked_by`/the source issue automatically, with real issue numbers once everything is created. Writing your own would go stale or duplicate the real one.
 - `body` should read as `## What to build` followed by `## Acceptance criteria` (a checklist).
-
-## Subagents
-
-`subagent_create` / `_continue` / `_list` / `_remove` fan out exploration — one per subsystem or open question — when the spec spans more than you can read cheaply. Give each a self-contained task, hold it to read-only work, and omit `model`.
-
-They run in the background. **Wait for every one you spawned to report before writing `refine_plan.md` or your Report JSON.** Skip them when a few reads would do.

package/assets/prompts/refiner/user.md

@@ -6,25 +6,32 @@
 
 {{prompt}}
 
+`prompt` may include a `## Discussion on the spec issue` section — the spec issue's own comment thread, if it has one. On a first pass this is whatever discussion already existed before the spec was labeled ready; on a resumed pass (after you raised questions and a human answered) it's split into "Answers to your open questions (round N)" and "Earlier discussion." Treat the answers section as authoritative — see your system instructions on resuming.
+
 ### previous_envelope
 
 {{previous_envelope}}
 
+A scout's findings — the subsystems this spec touches, one entry per file with a note on what's there. Read them, then read the files yourself; a scout finding is a pointer, not a substitute for grounding your own decomposition in the actual code.
+
 ### context_handoff_dir
 
 {{context_handoff_dir}}
 
 ## Task
 
-Decompose the product spec in `prompt` into a feature/story-or-bug tree, following every rule in your system instructions (vertical slices, the `blocked_by` DAG, expand/migrate/contract for wide refactors, no "Blocked by"/"Parent" text of your own).
+Decompose the product spec in `prompt` into a feature/story-or-bug tree, following every rule in your system instructions (grounding, ask-don't-decide, vertical slices, the `blocked_by` DAG, expand/migrate/contract for wide refactors, no "Blocked by"/"Parent" text of your own).
 
-1. Explore the codebase only as far as you need to ground the decomposition in what actually exists.
-2. Write your working notes to `<context_handoff_dir>/refine_plan.md`.
-3. Emit your `Report` JSON, declaring that one file in `artifacts`.
+1. Read the scout's findings in `previous_envelope`, then explore the codebase yourself as far as you need to ground the decomposition in what actually exists.
+2. Decide whether you can decompose the whole spec now, or whether something in it is genuinely ambiguous (see "Ask, don't decide"). These are mutually exclusive outcomes for this round — see the two Report shapes below.
+3. Write your working notes to `<context_handoff_dir>/refine_plan.md`.
+4. Emit your `Report` JSON, declaring that one file in `artifacts`.
 
 ## Report
 
-Respond with ONLY valid JSON matching `RefineOutput` — no prose before or after:
+Respond with ONLY valid JSON matching `RefineOutput` — no prose before or after. Exactly one of `issues` / `questions` is non-empty; the gate rejects a Report that populates both.
+
+**Shape 1 — the decomposition is unambiguous: emit `issues`, leave `questions` empty.**
 
 ```json
 {
@@ -57,14 +64,39 @@ Respond with ONLY valid JSON matching `RefineOutput` — no prose before or afte
       "parent": "F1",
       "blocked_by": ["S1"]
     }
+  ],
+  "questions": []
+}
+```
+
+**Shape 2 — something material is ambiguous: emit `questions`, leave `issues` empty.**
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence: how many questions, and what they're about>",
+  "artifacts": ["<context_handoff_dir>/refine_plan.md"],
+  "notes_for_next_agent": "<anything a human answering these should know>",
+  "issues": [],
+  "questions": [
+    {
+      "id": "Q1",
+      "question": "<the question, precise enough to answer in a word or two>",
+      "why_it_matters": "<what goes wrong if this is guessed instead of decided>",
+      "options": ["<plausible answer>", "<another plausible answer>"],
+      "recommendation": "<your own best guess, if you have one>",
+      "evidence": ["<file or symbol that framed this question>"]
+    }
   ]
 }
 ```
 
 Rules on the shape (enforced by a gate — a violation sends this back to you as a correction, not a silent acceptance):
 
+- `issues` and `questions` are mutually exclusive: a non-empty `questions` requires an empty `issues`, and vice versa. Escalating means publishing nothing this round.
 - `key` is your own local id for this run, unique within `issues` — never a real tracker id.
 - A node is a **container** (`kind: "epic"` or `"feature"`) exactly when some other node names it in `parent`; every other node is a **leaf** (`kind: "story"`, `"bug"`, or `"task"`) and must not be a container. At least one leaf is required.
 - `parent` is another node's `key`, or `""` for a top-level feature/epic.
 - `blocked_by` is a list of other nodes' `key`s — real dependencies only, and no cycles (through `parent` or `blocked_by`, or both together).
 - `body` is `## What to build` then `## Acceptance criteria` only — no "Blocked by" or "Parent" section; those are rendered for you once every node has a real issue number.
+- `questions[].id` is your own local id for this round, unique within `questions` — stable enough that, on a resumed run, an answer in the thread can be matched back to the question it answers.

package/assets/skill/SKILL.md

@@ -46,6 +46,7 @@ phases`/`spf events` exist so nobody has to guess the schema again).
 | "add a chain / a phase / an output type / a gate" | `authoring_chains.md` |
 | "what is SPF" | `spf_overview.md` |
 | "fold a third-party review tool's findings into the reviewer" | `cookbooks/ocr_reviewer.md` |
+| "try N attempts and pick the best one / best-of-N" | `spf fanout` — see `references/config.md`'s `spf fanout` section |
 | envelope/gate/session contract | `references/handoff.md` |
 | trace schema, spend vs. context | `references/observability.md` |
 | config field reference | `references/config.md` |

package/assets/skill/references/config.md

@@ -12,10 +12,10 @@ 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`/`review`
+   field by field (`defaults`/`observability`/`quality`/`watch`/`notifications`/`review`/`tiering`
    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).
+   `quality.checks` and `tiering.tiers`/`tiering.roles`; `agents` merges by
+   `name`: a matching name patches that entry, a new name appends).
 3. An explicit `--config <path>` replaces both — standalone, no built-in
    underneath it.
 
@@ -76,6 +76,29 @@ agents:
 | `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`. |
+| `max_run_cost` | number > 0 (USD) | Stops the NEXT agent call once a run has already spent this much — checked before each call, never after. A single call is never capped (a run can overshoot by one whole call), and a chain with only one agent dispatch (`scout`, `prompt`, `build`) can never trip it at all. Absent (default) = unbounded. Throws `BudgetExceeded`, which fails the phase closed. |
+| `max_run_tokens` | integer > 0 | Same semantics as `max_run_cost`, on `sessions.total_tokens` instead of cost. Absent (default) = unbounded. |
+
+### `spf fanout`
+
+`spf fanout <chain> "<prompt>" [--n 3] [--concurrency N] [--base <branch>]
+[--adw-id <id>] [--first-success] [--config <path>] [--cwd <dir>]` — best-of-N:
+runs `<chain>` N times in parallel, each in its own git worktree and branch
+(`spf/fanout/<base-adw-id>-<i>`), then picks ONE winner by code (succeeded >
+fewest gate failures > most gate passes > lowest cost > fewest tokens >
+lowest wall time > adw_id) and deletes the rest. SPF never merges the
+winner — it prints the branch and the basis; a human runs `git merge`. The
+chain named MUST have a commit step (`plan-build`, `plan-build-test`,
+`plan-build-test-quality`, `simple-sdlc`, or a repo-local chain with one) —
+`spf fanout` refuses any chain without one, since a winner with no commit
+leaves its only copy of the work as uncommitted edits in a worktree.
+`--first-success` opts into stopping early once one attempt succeeds
+(first-past-the-post) instead of the default, which runs every attempt to
+completion for a true N-way comparison. `spf fanout --clean <base-adw-id>`
+removes any worktrees/branches a killed or discarded run left behind under
+that id — a `--adw-id` is never safe to reuse against session rows still in
+the shared db, so a rerun with the same id fails loudly instead of mixing
+the two runs' cost/tokens/gates together.
 
 ### `observability`
 
@@ -130,6 +153,7 @@ Full mechanism: the main README's "`spf watch`" section. Field reference:
 | `base_branch` | string | Branch worktrees fork from and PRs target. Default `main`. |
 | `poll_ms` | int | Tick interval. Default `60000`. |
 | `concurrency` | int ≥1 | Max issues claimed and run at once, the build lane's own budget (independent of `refine.concurrency`). Default `2`. |
+| `chain_options` | map of string -> string | Options passed straight through to `chain` (and `refine.chain`) for every unattended dispatch — the same shape an interactive `spf <chain> --suite <name>` builds, e.g. `{suite: strict}` or `{agent: some-agent}`. Default `{}`. Only useful for a chain whose behavior actually reads the option (a step-derived chain's `--suite`; an imperative chain ignores an option it doesn't know about). |
 | `jira.base_url` / `jira.project_key` | string | Only consulted when `issue_provider: jira`. |
 | `refine.enabled` | bool | Turns on the second lane: decompose a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues, instead of running `chain` against it directly (a spec isn't individually workable). Default `false` — off by default, so an existing `watch:` config is unaffected by upgrading. Needs `issue_provider: github` — `spf watch` fails loudly at startup otherwise, since issue authoring (create + link a hierarchy) isn't implemented for Jira yet. |
 | `refine.chain` | string | Which registered chain runs per claimed spec. Default `refine`. |
@@ -140,6 +164,8 @@ watch:
   repo: owner/name
   label_prefix: spf
   chain: plan-build-test
+  chain_options:
+    suite: strict        # only if plan-build-test's chain declares a step-derived requiredSuites
   refine:
     enabled: true       # decompose spf:spec-ready specs into a feature/story tree
     chain: refine
@@ -154,6 +180,24 @@ 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.
 
+The `refine` chain grounds its decomposition with a `scout` phase before the
+refiner runs, so `scout` is a required agent for it — a roster that pruned
+it fails `spf watch` startup by name.
+
+The refine lane's own state machine has an extra loop beyond
+`spec-ready → refining → done`/`blocked`: when the refiner raises material
+ambiguity instead of a tree (see `assets/prompts/refiner/system.md`'s "Ask,
+don't decide"), the spec moves to `<prefix>:needs-feedback` with a comment
+naming its questions, instead of publishing anything. A human answers in the
+issue's comments and adds `<prefix>:continue-refinement`; `spf watch` claims
+that label back into `refining` and resumes the **same** `adw_id` — the
+comment thread (split into "answers to your open questions" and "earlier
+discussion") is folded into the resumed prompt, and the refiner's own
+coding-agent session continues rather than starting cold. This can loop any
+number of rounds. `spf watch init` must be re-run after upgrading to this
+version to seed the two new labels. Once a spec is fully published it's also
+closed on the tracker (GitHub only, best-effort), not just labeled `done`.
+
 ### `notifications`
 
 Optional outbound push for unattended work — `spf watch`'s daemon lifecycle,
@@ -165,7 +209,7 @@ default; adding it is entirely additive.
 
 | Field | Type | Meaning |
 |---|---|---|
-| `events` | `"off"` \| `"errors"` \| `"all"` | The whole filter. `off` (default): nothing. `errors`: only failed runs/phases, blocked issues, watch errors. `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus errors. |
+| `events` | `"off"` \| `"errors"` \| `"all"` | The whole filter. `off` (default): nothing. `errors`: only failed runs/phases, blocked issues, watch errors, and a spec needing feedback (`spec_needs_feedback` — `error`-level on purpose, same class as a blocked issue). `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus errors. |
 | `timeout_ms` | int | Per-request timeout for a channel's HTTP POST. Default `5000`. |
 | `channels[]` | array | See below. |
 
@@ -224,6 +268,111 @@ 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.
 
+### `tiering`
+
+Risk-tiered per-role model routing (SPF #14) — a run-global cost/strength
+shift on top of the static roster, decided ONCE at run start from signals
+code can read without asking an agent anything (the chain's name and the
+prompt's word count), never re-evaluated mid-run. **OFF by default, and
+`enabled: false`/absent is a TOTAL no-op**: every agent dispatches at
+exactly the model its roster entry names, byte-identical to before this key
+existed — the same discipline `defaults.max_run_cost`/`max_run_tokens` hold
+themselves to.
+
+**Top-level, not nested under `defaults:`.** `loadConfig`'s back-fill loop
+copies a fixed list of `defaults` keys down onto every agent that hasn't set
+them, and a stray copy would be silently *stripped* at parse rather than
+rejected — a top-level key sits outside that loop entirely, so the trap
+cannot apply here. Merges **key-by-key** with a base config, same as
+`review`/`notifications`: a repo that only flips `enabled: true` keeps the
+base's `tiers`/`roles`; `tiers` and `roles` are each a **whole replace** on
+override (a repo's own ladder replaces the packaged one wholesale, never an
+unordered splice of both).
+
+| Field | Type | Meaning |
+|---|---|---|
+| `enabled` | bool | Default `false`. `true` turns on the ladder walk described below; `false` (or the key absent) is a total no-op, checked nowhere and dispatched nowhere. |
+| `tiers` | array, WEAKEST FIRST | The ladder. A risk level shifts every routed role UP or DOWN this list by the same step — order is the whole semantics, which is why this is a sequence and not a mapping. Default `[]`. |
+| `tiers[].name` | string | What `roles` values point at. |
+| `tiers[].coding_agent` | `"flue"` \| `"claude_code"` | Which backend's vocabulary this rung's `model` speaks. Default `flue`, same default an agent's own `coding_agent` uses. A tier changes an agent's `model` and **nothing else** — `coding_agent` always stays the agent's own — so a rung can only route roles whose backend matches (**rule T**, below). |
+| `tiers[].model` | string | Same vocabulary as an agent's own `model:` for that backend: `provider/model-id` for `flue`, Claude Code's bare alias/full name for `claude_code`. No per-provider table — for `flue` the provider is already the string's first segment. |
+| `roles` | map of agent name -> tier name | The baseline tier per **role**. Naming an agent here is the operator's statement "route this one by tier" — the resolved tier then wins over that agent's own `model:`. An agent **not** named here is never retiered; its `model:` stands, untouched. That is the whole precedence rule. Default `{}`. |
+
+```yaml
+tiering:
+  enabled: true
+  tiers:
+    - { name: cheap,  coding_agent: flue, model: ollama/granite4.1:8b }
+    - { name: strong, coding_agent: flue, model: ollama/qwen3.8:27b-mlx }
+  roles:
+    scout:    cheap
+    builder:  strong
+    reviewer: strong
+```
+
+**The risk signal.** Two integer-weighted signals, summed: the chain's own
+kind (`scout`/`prompt`/`document`/`quality` weigh `-1`; `simple-sdlc`/
+`plan-build-test-quality`/`refine` weigh `+1`; everything else, including
+every repo-local `.spf/chains/*.yaml` chain, weighs `0`) and the prompt's
+word count (`-1` at ≤60 words, `+1` at ≥400, `0` between). The sum
+classifies to `low`/`standard`/`high`: reaching `high` needs only one
+signal to agree (a long prompt forces `high` outright), reaching `low`
+needs both to agree — demoting a role a rung is the expensive mistake (a
+wrong answer, a whole re-run); promoting one is the cheap mistake (some
+extra tokens), so the classifier is deliberately asymmetric toward the
+cheap failure. `standard` (step `0`) leaves every role on its configured
+baseline rung.
+
+**Rule T — the backend-compatibility rule.** `coding_agent` is a per-agent
+field and model vocabulary is backend-dependent, so a tier is only usable
+for a role whose `coding_agent` matches the tier's own declared
+`coding_agent`. `enabled: true` on a repo that inherited the packaged
+flue-shaped ladder (every repo does, via key-by-key merge, until it
+declares its own) while running a `claude_code` roster fails **loudly, by
+name** at `agents.validate()` time, before anything spawns — never a silent
+skip, and never a `fireworks/...` id handed to Claude Code.
+
+**Degradation.** A rung that is unusable — a model tag `probeServedOllamaTags`
+found absent from a local Ollama server's `/models` list, or a rule-T
+backend mismatch — is walked **down**, never up: a degradation must never
+silently escalate spend. If every rung at or below the target is unusable,
+the role dispatches on its own configured `model:` unchanged, plus one noted
+line. The availability probe **fails open**: an unreachable server drops
+nothing rather than silently downgrading every agent to the bottom rung.
+
+**Visibility.** Because a retiered agent's *configured* `model:` (what
+`spf.config.yaml` says) and its *effective* model (what actually dispatched)
+can now disagree, every run traces one `tiering` log event carrying the full
+resolved routing, and prints one console line per retiered agent
+(`[spf] tiering <agent> <tier> (<configured> -> <effective>) risk=<risk>`).
+`spf doctor` reports the same resolved ladder and every routed role's
+effective model when `tiering.enabled` — see below.
+
+`spf init`'s interview does not write this block: it collects one model for
+the whole roster, and a `tiering` block over a single-model roster is a
+no-op by construction. `spf init --template ts-flue-ollama` is the one
+packaged template that ships it **on**, with two tags measured live against
+a real local Ollama server; the non-interactive starter (`--yes` / piped
+stdin) shows the shape commented out. Every other packaged template
+inherits the built-in default's populated-but-`enabled: false` ladder
+through key-by-key merge — harmless until a repo opts in, and invisible to
+`spf doctor` until it does (see below).
+
+**`spf doctor`**, only when `cfg.tiering.enabled` — a disabled ladder is
+invisible to doctor, on purpose, so a repo that never opted in (which is
+every packaged template except `ts-flue-ollama`, plus every `spf init`
+starter) can't fail on an unset provider key for a rung that will never
+dispatch:
+
+- the same provider-key check the roster gets, run over `tiers[].model`
+  instead, branching on **the tier's own** `coding_agent`;
+- the `OLLAMA_BASE_URL` reachability probe now also fires for an `ollama/*`
+  rung even when no `cfg.agents[]` entry itself names one;
+- a new report section: the resolved ladder, every routed role's effective
+  model (including roles whose effective model equals their configured
+  one), any degradation note, and — probed the same way `probeServedOllamaTags`
+  does, fail-open — which `ollama/*` rungs are and aren't in `ollama list`.
+
 ### `agents[]`
 
 | Field | Required | Meaning |

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

@@ -65,3 +65,28 @@ agents:
     # a 3B model — a lighter tag here is a real, not merely theoretical,
     # option.
     model: ollama/granite4.1:8b
+
+# Risk-tiered per-role model routing (SPF #14) — ON, local only. The two
+# tags below are the MEASURED ones (last session, live on localhost:11434)
+# and they ALREADY appear in this template today — ollama/qwen3.8:27b-mlx at
+# :48 (defaults.model), :58 (planner), :60 (reviewer) and
+# ollama/granite4.1:8b at :67 (documenter). This block introduces no new
+# model string.
+tiering:
+  enabled: true
+  # coding_agent: flue matches this template's `defaults.coding_agent: flue`
+  # (:46) — every roster agent here is flue, so every role is routable by
+  # these rungs. Stated explicitly rather than left to the default, because
+  # it is the field that keeps a rung from being handed to a backend that
+  # cannot parse it (rule T — see assets/skill/references/config.md's
+  # "tiering" section).
+  tiers:
+    - { name: scout,   coding_agent: flue, model: ollama/granite4.1:8b }    # cheap read/summarize/triage
+    - { name: builder, coding_agent: flue, model: ollama/qwen3.8:27b-mlx }  # first-attempt implementation
+  roles:
+    scout: scout
+    documenter: scout
+    planner: builder
+    builder: builder
+    refiner: builder
+    reviewer: builder

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

@@ -69,6 +69,12 @@ agents:
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+#   # Options threaded straight through to `chain` (and refine.chain below)
+#   # for every unattended dispatch — the same shape an interactive
+#   # `spf <chain> --suite <name>` builds. Only useful for a chain whose
+#   # behavior actually reads the option; empty/omitted by default.
+#   # chain_options:
+#   #   suite: strict
 #   # Optional second lane: decompose a spf:spec-ready product spec into a
 #   # feature/story-or-bug tree of real issues instead of building it
 #   # directly. Off by default; needs issue_provider: github (the default

package/dist/chains/index.d.ts

@@ -118,5 +118,16 @@ export declare function resolveRequiredSuites(chain: ChainDefinition, options: R
  * CLI dispatch sites (`spf <chain>` and `spf watch`) go through this, never
  * `chain.run(...)` directly — the whole reason to route through here is that
  * a `steps`-only chain has no `run` to call.
+ *
+ * Also the one call site both dispatch paths share on the way OUT — success
+ * or thrown error alike, `finally` runs either way — which is what makes it
+ * the right seam for `otel.releaseOtelExporter()` (see otel.ts's RUN-SCOPED
+ * CLEANUP note / #26): a `spf watch` daemon calls this once per issue, in
+ * the same process, for as long as it runs, so a run's exporter has to be
+ * dropped here rather than living until the whole daemon exits. `session.
+ * finalize()` is the same idea for the run itself — it stops the process-
+ * wide signal handler from reaching this (now finished) run, and closes its
+ * Tracer's sqlite handle, so a long `spf watch` daemon does not hold every
+ * issue it has ever processed reachable for the rest of its life.
  */
 export declare function runChain(chain: ChainDefinition, ctx: ChainContext, options?: Record<string, string>): Promise<number>;