@gr8ful/spf 0.5.1 → 0.7.0

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,8 +153,10 @@ 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. |
+| `jira.issue_types` | map: `epic`/`feature`/`story`/`bug`/`task` -> string | Only consulted when `issue_provider: jira` AND `refine.enabled`. What each `RefinedIssue.kind` creates as on Jira — defaults `epic`/`feature` → `Epic`, `story` → `Story`, `bug` → `Bug`, `task` → `Task`, overridable per kind. Validated against the real project by both `spf watch init` and `spf watch`'s own startup check. |
+| `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` or `"jira"` — both implement issue authoring (create + link a hierarchy); any other value fails loudly at startup. |
 | `refine.chain` | string | Which registered chain runs per claimed spec. Default `refine`. |
 | `refine.concurrency` | int ≥1 | The refine lane's own budget, separate from `concurrency`. Default `1`. |
 
@@ -140,6 +165,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 +181,61 @@ 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.
 
+A third label vocabulary — `<prefix>:priority:p0|p1|p2|p3` — is what
+`claimNewWork` actually schedules `<prefix>:ready` issues by: priority first,
+then sibling affinity (a leaf whose parent already has a sibling in flight
+goes first), then creation order. The refiner proposes a priority per node
+(clamped to the spec's own priority, when the spec issue has one, as a
+ceiling — never a floor); a human can relabel before promoting, which is the
+entire override mechanism. Independently, a `<prefix>:ready` leaf whose
+`blocked_by` isn't fully `<prefix>:done` is skipped until it is — the
+frontier check. This label is separate from any GitHub Projects v2
+"Priority" field a repo's board might have; `spf watch` never touches
+Projects v2, so the two are unreconciled if you use both.
+
+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 → spec-in-progress → 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.
+
+Publishing a tree does NOT mean the spec is done: `<prefix>:spec-in-progress`
+is where a spec lands right after publish, and it stays there — with a
+summary comment listing every issue created — until **every one of those
+issues** is itself `<prefix>:done` (`finishTrackedSpecs`, polled every tick,
+reads `WatchMarker.refined` back to check). Only then does it move to
+`<prefix>:done`, get a closing comment, and close on the tracker (GitHub
+only, best-effort) — firing `spec_done`, distinct from the earlier
+`spec_refined`. This exists so a spec's tracker status means what a product
+manager expects it to mean: "done" is the work being finished, not merely
+having been decomposed. `spf watch init` must be re-run after upgrading to
+this version to seed the new labels.
+
+Container roll-up mirrors that same "close, don't just label" behavior for a
+generated feature/epic: once every child under it carries `<prefix>:done`
+(checked reactively, each time a leaf's PR merges), the container gets a
+summary comment and transitions to `<prefix>:done` — then the check repeats
+on ITS OWN parent, so an epic rolls up once its last feature does. A
+container with one unfinished child (including a leaf still sitting at
+`<prefix>:refined`, never promoted) is left alone; nothing forces it. This
+needs a native hierarchy read-back — GitHub's sub-issues API, or a Jira
+`parent = "<id>"` JQL search — so it works on both today; a tracker that
+implements neither gets a logged no-op, not a startup failure, since the
+build lane still works fine without roll-up. Whether the container actually
+CLOSES on the tracker (not just relabels) depends on `closeIssue` being
+implemented at all — GitHub yes, Jira no (its own resolution workflow isn't
+wired up), same asymmetry as leaf and spec completion already have on Jira.
+
 ### `notifications`
 
 Optional outbound push for unattended work — `spf watch`'s daemon lifecycle,
@@ -165,7 +247,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 +306,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,10 +69,20 @@ 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
-#   # above) — issue authoring isn't implemented for Jira yet.
+#   # directly. Off by default; needs issue_provider: github OR jira — both
+#   # support issue authoring (create + link a hierarchy). On Jira, each
+#   # RefinedIssue.kind maps to a real Jira issue type via
+#   # watch.jira.issue_types (defaults: epic/feature -> Epic, story -> Story,
+#   # bug -> Bug, task -> Task) — spf watch init validates this against the
+#   # real project when refine is enabled.
 #   refine:
 #     enabled: true
 #     chain: refine

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>;

package/dist/chains/index.js

@@ -1,5 +1,7 @@
 import * as steps from "./steps.js";
 import * as simpleSdlc from "./simple_sdlc.js";
+import * as otel from "../core/otel.js";
+import * as session from "../core/session.js";
 /**
  * Build a step-based ChainDefinition, deriving phases/requiredAgents/
  * requiredSuites from its steps.
@@ -66,6 +68,15 @@ export const CHAINS = [
     stepChain("document", "write up the work that was just done, from the diff", [steps.request(), steps.changes(), steps.document()]),
     stepChain("refine", "decompose a product spec into a feature/story-or-bug tree of tracker issues — spf watch's spec-ready lane", [
         steps.request(),
+        // Grounds the decomposition in code that actually exists, rather than
+        // leaving "explore the codebase" as prose the refiner may or may not
+        // follow (see assets/prompts/refiner/system.md). Its ScoutOutput flows
+        // into refine() as `previous` — agentStep() threads state.previous into
+        // every agent phase, and refiner/user.md already renders it as
+        // {{previous_envelope}}. This makes `scout` a required agent for this
+        // chain: a roster that pruned it fails agents.validate() by name at
+        // `spf watch` startup, same as any other missing required agent.
+        steps.scout({ description: "Map the subsystems this spec touches — change nothing" }),
         steps.refine(),
         steps.publishIssues(),
     ]),
@@ -147,9 +158,33 @@ export function resolveRequiredSuites(chain, options) {
  * 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 async function runChain(chain, ctx, options = {}) {
-    if (chain.run)
-        return chain.run(ctx, options);
-    return steps.runSteps(ctx, resolveRequiredAgents(chain, options), resolveRequiredSuites(chain, options), chain.steps, options);
+    try {
+        if (chain.run)
+            return await chain.run(ctx, options);
+        return await steps.runSteps(ctx, resolveRequiredAgents(chain, options), resolveRequiredSuites(chain, options), chain.steps, options);
+    }
+    finally {
+        // Both are no-ops for a one-shot `spf <chain>` invocation with no
+        // explicit `--adw-id` (ctx.adw_id is null; the id session.ensure()
+        // actually minted never makes it back up here) — that process exits
+        // right after this call returns, and the existing end-of-process
+        // `flushAll()` in `cli/index.ts`'s `finally` still drains the exporter
+        // exactly as it always did (the signal listener needs no such fallback:
+        // the process is gone).
+        await otel.releaseOtelExporter(ctx.adw_id);
+        session.finalize(ctx.adw_id);
+    }
 }

package/dist/chains/repo_chains.js

@@ -223,6 +223,7 @@ export const RepoChainFileSchema = v.strictObject({
  */
 const RESERVED_COMMAND_NAMES = new Set([
     "run",
+    "fanout",
     "list",
     "init",
     "install-skill",

package/dist/chains/simple_sdlc.js

@@ -148,7 +148,7 @@ export function trailerFor(outcome, identity) {
 }
 export async function main(ctx) {
     const { prompt } = ctx;
-    const run = startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
+    const run = await startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
     const baseline = run.git.rev("HEAD"); // pinned before this run commits anything
     await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
         ph.log({ input: prompt, baseline: run.git.shortSha(baseline) });

package/dist/chains/steps.d.ts

@@ -82,8 +82,14 @@ export interface Step {
     /** Display fragment for derivePhases() — e.g. "planner", "git(commit)". */
     label?: string;
 }
-/** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
-export declare function startRun(ctx: ChainContext, requiredAgents: string[], requiredSuites: string[]): Run;
+/**
+ * The identical loadConfig -> validate -> session.ensure prologue every
+ * chain repeated. `async` since the tiering availability probe below is an
+ * awaited `fetch` — firing it unawaited would let `agents.execute` read
+ * `run.tiering` before the probe resolved. Both call sites are already
+ * inside `async` functions, so this stays a one-token change for each.
+ */
+export declare function startRun(ctx: ChainContext, requiredAgents: string[], requiredSuites: string[]): Promise<Run>;
 /**
  * Commit an envelope in its own author's words — the message-fallback four
  * chains repeated.
@@ -310,21 +316,6 @@ export declare function refine(opts?: {
     retries?: number;
     extraGates?: string[];
 }): Step;
-/**
- * Create the tree `refine()` produced on the tracker, in dependency order,
- * and link each node to its parent. A `code` phase, not an agent one — the
- * decision-making (topological order, label assignment, `## Blocked by`
- * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
- * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
- *
- * Writes what it created to `<context_handoff_dir>/refine_publish.json` —
- * the side channel `cli/commands/watch.ts`'s `runRefine` reads after the
- * chain returns, since a chain's own return value is just an exit code.
- * `spf watch`'s own marker/comment/transition bookkeeping for the spec
- * issue lives entirely in `core/watch.ts`'s `runSpec`, never here — a bare
- * `spf refine` run (no daemon, no spec issue in play) still needs this step
- * to work standalone.
- */
 export declare function publishIssues(opts?: {
     description?: string;
 }): Step;

package/dist/chains/steps.js

@@ -48,6 +48,7 @@ import * as quality from "../core/quality.js";
 import * as agentsCfg from "../core/agents.js";
 import * as session from "../core/session.js";
 import * as refineLib from "../core/refine.js";
+import * as tiering from "../core/tiering.js";
 import { DOCUMENT_NOTES } from "../core/prompts.js";
 import { BuildOutput, DocumentOutput, GenericOutput, PlanOutput, RefineOutput, ReviewOutput, ScoutOutput, makeAgentCall, makeChangeCapture, makeEventRecord, makePhaseParams, } from "../core/data_types.js";
 import { Run } from "../core/runner.js";
@@ -62,8 +63,14 @@ function makeStep(fn, meta = {}) {
     return step;
 }
 // ── layer 1: the shared prologue ────────────────────────────────────────
-/** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
-export function startRun(ctx, requiredAgents, requiredSuites) {
+/**
+ * The identical loadConfig -> validate -> session.ensure prologue every
+ * chain repeated. `async` since the tiering availability probe below is an
+ * awaited `fetch` — firing it unawaited would let `agents.execute` read
+ * `run.tiering` before the probe resolved. Both call sites are already
+ * inside `async` functions, so this stays a one-token change for each.
+ */
+export async function startRun(ctx, requiredAgents, requiredSuites) {
     const cfg = agentsCfg.loadConfig(ctx.config_paths);
     agentsCfg.validate(cfg, requiredAgents, requiredSuites, ctx.cwd);
     const run = session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name);
@@ -83,6 +90,41 @@ export function startRun(ctx, requiredAgents, requiredSuites) {
     if (ctx.chain_source) {
         run.tracer.event(makeEventRecord({ adw_id: run.adw_id, type: "log", name: "chain_source", payload: { source: ctx.chain_source } }));
     }
+    // Tiering resolution (SPF #14) — one more run-scoped fact, computed once,
+    // before any phase opens, beside chain_source above. `risk`/`signals` are
+    // always computed (a pure function of chain name + prompt); `routing`/
+    // `notes` are only ever non-empty when `cfg.tiering.enabled` — see
+    // `resolveTiering`'s own no-op guarantee.
+    const servedOllamaTags = await tiering.probeServedOllamaTags(cfg);
+    run.tiering = tiering.resolveTiering({
+        cfg,
+        chainName: ctx.chain_name,
+        prompt: ctx.prompt,
+        servedOllamaTags,
+        required: requiredAgents,
+    });
+    run.tracer.event(makeEventRecord({
+        adw_id: run.adw_id,
+        type: "log",
+        name: "tiering",
+        payload: {
+            risk: run.tiering.risk,
+            signals: run.tiering.signals,
+            routing: run.tiering.routing,
+            notes: run.tiering.notes,
+        },
+    }));
+    // One console line per RETIERED agent (changedModels — not per routing
+    // entry: a role whose tier resolves to the model it was already
+    // configured with is not news). Routed through the existing
+    // `Console.note()` — no new Console method. This is what reconciles
+    // `run.cfg.agents[].model` (which keeps the configured value) with
+    // `agent_sessions.model` (which records the effective one) for a human
+    // reading the console when the two disagree.
+    for (const [agentName, effective] of Object.entries(tiering.changedModels(run.tiering))) {
+        const route = run.tiering.routing[agentName];
+        run.console.note(`[spf] tiering ${agentName} ${route.tier} (${route.configured} -> ${effective}) risk=${run.tiering.risk}`);
+    }
     return run;
 }
 /** A trailer line: `Key: value...`, one per line, no blank lines inside the block. */
@@ -622,10 +664,19 @@ export function refine(opts = {}) {
         output_type: RefineOutput,
         description: opts.description ?? "Decompose the spec into a feature/story tree of vertical slices",
         // refinementWellFormed is NOT in GATE_ALLOWLIST — it is meaningless on
-        // any other envelope type (it reads `issues`), so there is nothing to
-        // gain by letting a definition name it, and it stays non-removable here.
+        // any other envelope type (it reads `issues`/`questions`), so there is
+        // nothing to gain by letting a definition name it, and it stays
+        // non-removable here.
+        //
+        // retries: 1, not 0 — this gate's own doc comment says a violation
+        // "re-prompts the SAME refiner session before publishIssues() ever
+        // runs." With 0 retries that was never true: agents.ts throws
+        // GateFailure on the first violation and the whole spec goes straight to
+        // spf:blocked with no correction round-trip. The mutual-exclusion rule
+        // between `issues` and `questions` (see refinementWellFormed) makes that
+        // mismatch more likely to bite in practice, not less.
         gates: withExtraGates([gates.refinementWellFormed], opts.extraGates),
-        retries: opts.retries ?? 0,
+        retries: opts.retries ?? 1,
     });
 }
 /**
@@ -635,14 +686,43 @@ export function refine(opts = {}) {
  * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
  * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
  *
- * Writes what it created to `<context_handoff_dir>/refine_publish.json` —
- * the side channel `cli/commands/watch.ts`'s `runRefine` reads after the
- * chain returns, since a chain's own return value is just an exit code.
- * `spf watch`'s own marker/comment/transition bookkeeping for the spec
- * issue lives entirely in `core/watch.ts`'s `runSpec`, never here — a bare
- * `spf refine` run (no daemon, no spec issue in play) still needs this step
- * to work standalone.
+ * When the refiner raised material ambiguity instead of a tree
+ * (`envelope.questions` non-empty — `gates.refinementWellFormed` already
+ * guarantees `issues` is empty whenever that's true), this publishes
+ * nothing: it writes those questions to
+ * `<context_handoff_dir>/refine_questions.json` instead of
+ * `refine_publish.json` and returns. That is a successful phase outcome, not
+ * a failure — escalating to a human is a legitimate way for this chain to
+ * end, same as publishing a tree is.
+ *
+ * Writes what it created (or asked) to `<context_handoff_dir>/`, one of
+ * `refine_publish.json` or `refine_questions.json` — the side channel
+ * `cli/commands/watch.ts`'s `runRefine` reads after the chain returns, since
+ * a chain's own return value is just an exit code. `spf watch`'s own
+ * marker/comment/transition bookkeeping for the spec issue (including
+ * posting the questions and moving it to `needs-feedback`) lives entirely in
+ * `core/watch.ts`'s `runSpec`/`escalateSpec`, never here — a bare `spf
+ * refine` run (no daemon, no spec issue in play) still needs this step to
+ * work standalone, and just leaves the questions on disk for a human to
+ * read.
  */
+/**
+ * `state.options["priority"]` -> a `RefinedPriority` ceiling, or `null` when
+ * unset — the generic chain-options path (`cli/commands/run.ts`'s
+ * `--priority`, or `core/watch.ts`'s `runSpec` threading a spec's own
+ * `<prefix>:priority:pN` label) is the ONLY place this string enters the
+ * system, so it's validated here rather than trusted: a typo'd or stale
+ * `--priority urgent` fails the phase with a clear message instead of
+ * silently publishing every node at its own, un-clamped priority.
+ */
+function parsePriorityOption(raw) {
+    if (raw === undefined)
+        return null;
+    if (raw !== "p0" && raw !== "p1" && raw !== "p2" && raw !== "p3") {
+        throw new Error(`publishIssues(): --priority ${JSON.stringify(raw)} is not one of p0|p1|p2|p3`);
+    }
+    return raw;
+}
 export function publishIssues(opts = {}) {
     preflightDescription("publish", opts.description);
     const fn = async (run, state) => {
@@ -650,19 +730,27 @@ export function publishIssues(opts = {}) {
         if (!envelope || !Array.isArray(envelope.issues)) {
             throw new Error("publishIssues() requires a preceding refine() step in the chain's step list");
         }
+        const questions = envelope.questions ?? [];
+        const priorityCeiling = parsePriorityOption(state.options["priority"]);
         await run.phase(makePhaseParams({
             name: "publish",
             kind: "code",
             owner: "tracker",
             description: opts.description ?? "Create the feature/story tree on the tracker, in dependency order, and link each to its parent",
         }), async (ph) => {
+            if (questions.length > 0) {
+                writeFileSync(path.join(run.context_handoff_dir, "refine_questions.json"), JSON.stringify(questions, null, 2));
+                ph.log({ escalated: questions.length });
+                return;
+            }
             const tracker = refineLib.resolveAuthoringProvider(run.cfg);
             const created = await refineLib.publish(tracker, envelope.issues, {
                 labelPrefix: run.cfg.watch.label_prefix,
                 specIssueId: state.issue_id,
+                priorityCeiling,
             });
             writeFileSync(path.join(run.context_handoff_dir, "refine_publish.json"), JSON.stringify(created.map((c) => ({ id: c.issue.id, title: c.issue.title, kind: c.kind, isLeaf: c.isLeaf })), null, 2));
-            ph.log({ created: created.length, leaves: created.filter((c) => c.isLeaf).length });
+            ph.log({ created: created.length, leaves: created.filter((c) => c.isLeaf).length, priority_ceiling: priorityCeiling });
         });
     };
     return makeStep(fn, { label: "code(publish)" });
@@ -709,7 +797,7 @@ export function derivePhases(steps) {
 // ── the driver ────────────────────────────────────────────────────────────
 /** Run a chain's step list start to finish: prologue, every step in order, then run.finish(). */
 export async function runSteps(ctx, requiredAgents, requiredSuites, steps, options = {}) {
-    const run = startRun(ctx, requiredAgents, requiredSuites);
+    const run = await startRun(ctx, requiredAgents, requiredSuites);
     const state = makeState(ctx.prompt, options, ctx.issue_id ?? null);
     for (const step of steps) {
         await step(run, state);