@gr8ful/spf 0.8.2 → 0.9.0

package/README.md

@@ -7,6 +7,8 @@ A software factory does one thing: it gives you more leverage on your prompt. Ho
 
 Everyone can get an agent to write code once. Almost nobody gets the same result twice. This fixes that by moving the control plane out of the prompt and into TypeScript. A chain script owns sequencing, retries, and acceptance. Agents work inside named phases. Typed JSON envelopes carry context across the seams. Every event streams into SQLite while it is still happening. **Agent proposes, code disposes.**
 
+> **Beta.** SPF is under active development — config schema, chain/CLI surface, and trace/event shapes may change between releases without a deprecation period. Pin a version if you depend on any of these staying stable.
+
 ---
 
 ## Install
@@ -124,17 +126,34 @@ Set `coding_agent: claude_code` on any agent (or in `defaults`) to run it on you
 
 #### Proxy or wrapper launchers
 
-To route the `claude` command through a wrapper, proxy server, or launcher (e.g., [Ollama](https://ollama.com)), set the `SPF_CLAUDE_CMD` environment variable before running `spf`. Space-separated command chains are supported:
+To route the `claude` command through a wrapper, proxy server, or launcher (e.g., [Ollama](https://ollama.com)), set `SPF_CLAUDE_CMD` — as a declarative `env:` entry in `spf.config.yaml`, since it's a launcher choice, not a secret (see [Declarative env vars](#declarative-env-vars) below), or as a plain shell export for a one-off override. Space-separated command chains are supported:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+```
 
 ```bash
-# Route through Ollama's launcher
-export SPF_CLAUDE_CMD="ollama launch claude --model granite4.1:8b"
 spf build "your prompt"
 ```
 
 `ollama launch <cmd>` uses cobra flag parsing, which treats anything typed after it as its own flags unless a literal `--` says otherwise — without one, `claude`'s own flags (`-p`, `--json-schema`, ...) fail with `unknown shorthand flag: 'p' in -p` before `claude` is ever reached. `agent_cc.ts` detects exactly this `ollama launch ...` shape and inserts that `--` automatically, so you never add the separator by hand for this specific launcher.
 
-That `--` alone is not enough to reach `claude`, though: `ollama launch` also needs its OWN `--model <tag>` flag (a tag from `ollama list`), typed BEFORE the auto-inserted `--`, whenever it runs headless — which it always does under SPF, since SPF spawns with piped stdio. Without it, `ollama launch` falls back to an interactive model picker that can never run, and fails one step later than the `--` problem, with `model selection requires an interactive terminal; use --model to run in headless mode`. A `--model` typed after the `--` doesn't help — at that point it belongs to `claude`, not to `ollama launch`. So `SPF_CLAUDE_CMD` must include `ollama launch`'s `--model` yourself, exactly as written above; `spf doctor` hard-fails if it's missing.
+That `--` alone is not enough to reach `claude`, though: `ollama launch` also needs its OWN `--model <tag>` flag, typed BEFORE the auto-inserted `--`, whenever it runs headless — which it always does under SPF, since SPF spawns with piped stdio. Without it, `ollama launch` falls back to an interactive model picker that can never run, and fails one step later than the `--` problem, with `model selection requires an interactive terminal; use --model to run in headless mode`. A `--model` typed after the `--` doesn't help — at that point it belongs to `claude`, not to `ollama launch`. So `SPF_CLAUDE_CMD` must include `ollama launch`'s `--model` yourself; `spf doctor` hard-fails if it's missing.
+
+**Per-agent model choice:** a literal `{model}` token in `SPF_CLAUDE_CMD` is substituted with each call's own agent-config `model:` field before spawning. Since `ollama launch`'s `--model` (its OWN flag) is what actually pins the model serving the whole launched process — not `claude`'s own `--model`, appended after the `--` — a FIXED tag in `SPF_CLAUDE_CMD` means every `claude_code` agent runs on that one model regardless of what each agent's `model:` says. Using `{model}` instead makes it genuinely per-agent:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+agents:
+  - name: planner
+    coding_agent: claude_code
+    model: kimi-k2.7-code:cloud
+  - name: builder
+    coding_agent: claude_code
+    model: qwen3-coder:cloud
+```
 
 ```bash
 # Or use a custom wrapper script
@@ -144,6 +163,18 @@ spf build "your prompt"
 
 The command/launcher must support the full Claude Code CLI interface: `-p` for prompt, `--json-schema`, `--model`, `--session-id`/`--resume`, `--output-format stream-json`, and all other flags `agent_cc` uses. When unset, `SPF_CLAUDE_CMD` defaults to `claude` (resolved from `PATH` normally). A cmdSpec that already contains its own literal `--` is left completely alone — `agent_cc.ts` never inserts a second one.
 
+#### Declarative env vars
+
+`spf.config.yaml` supports an `env:` block for settings like `SPF_CLAUDE_CMD` that are configuration, not secrets — so they can be committed as plain, reviewable text instead of hidden in an out-of-band shell export:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+  SOME_TOKEN: "${SOME_SECRET_FROM_DOTENV}"
+```
+
+Applied to `process.env` before any command runs. A plain value commits as literal text; `${VAR}` interpolates from whatever's already in `process.env` at that point (the real shell, or `.env`, both of which load first) — so a real secret can live in `.env` (gitignored) and be referenced here without ever being written into this file. An already-set `process.env` value always wins over `env:`'s — `spf.config.yaml` supplies the default, a real export still overrides it per machine/session. A `${VAR}` reference to something that's genuinely unset fails loudly at startup, naming the missing variable, rather than silently interpolating to an empty string.
+
 ### flue + local Ollama
 
 Point the default `flue` backend at a local Ollama server the same way you'd pick any other Flue provider — the model string's own prefix, `ollama/<tag>` (whatever `ollama list` shows on your machine) instead of `openai/...`/`anthropic/...`:
@@ -608,23 +639,28 @@ for those.
 ```yaml
 # .spf/spf.config.yaml
 notifications:
-  events: errors            # off (default) | errors | all
+  events: attention         # off (default) | errors | attention | all
   channels:
     - kind: slack            # slack | teams | webhook
       webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
 ```
 
-`events` is the whole filter: `errors` sends only failed runs/phases, blocked
-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 container's roll-up (`feature_done` — see "Container
-roll-up" above), and a spec reaching actual completion (`spec_done` —
-distinct from `spec_refined`, which fires the moment a tree is published;
-see "Human-in-the-loop escalation" above). 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.
+`events` is the whole filter, narrowest to widest:
+
+- `errors` sends only true failures — a failed run/phase (`run_failed`,
+  `phase_failed`) or a `watch_error`.
+- `attention` adds anything that needs a human but isn't itself a failure —
+  a blocked issue (`issue_blocked`) or a spec needing feedback
+  (`spec_needs_feedback` — see "Human-in-the-loop escalation" above).
+- `all` adds every remaining milestone — run started/finished, issue
+  claimed, PR opened, issue done, a container's roll-up (`feature_done` —
+  see "Container roll-up" above), and a spec reaching actual completion
+  (`spec_done` — distinct from `spec_refined`, which fires the moment a
+  tree is published; see "Human-in-the-loop escalation" above).
+
+Each tier includes everything the narrower tiers send. 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/skill/cookbooks/roster.md

@@ -99,11 +99,25 @@ SPF-specific plumbing, no `provider:` config section to write.
 
 There's a second, different way to reach Ollama through `claude_code`: route
 the `claude` command itself through `ollama launch claude` via
-`SPF_CLAUDE_CMD`, instead of pointing `ANTHROPIC_BASE_URL` at Ollama's
-OpenAI-compatible surface. That launcher form needs its own `--model <tag>`
-flag (from `ollama list`) in the command string, since SPF always spawns
-headless — see README.md's "Proxy or wrapper launchers" section for the
-full command and why `--model` is mandatory there, not optional.
+`SPF_CLAUDE_CMD` — as a declarative `env:` entry in `spf.config.yaml`
+(non-secret; see `config.md`'s "Declarative env vars" section), not a raw
+shell export. That launcher form needs its own `--model <tag>` flag in the
+command string, since SPF always spawns headless — use the literal token
+`{model}` there (substituted with each call's own agent `model:` field)
+rather than one fixed tag, or every `claude_code` agent ends up sharing the
+same model regardless of its own `model:`:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+agents:
+  - name: builder
+    coding_agent: claude_code
+    model: kimi-k2.7-code:cloud
+```
+
+See README.md's "Proxy or wrapper launchers" section for the full command
+and why `--model` is mandatory there, not optional.
 
 ## Retune tools
 

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`/`review`/`tiering`
+   field by field (`env`/`defaults`/`observability`/`quality`/`watch`/`notifications`/`review`/`tiering`
    merge key-by-key — `notifications.channels` replaces wholesale, same as
    `quality.checks` and `tiering.tiers`/`tiering.roles`; `agents` merges by
    `name`: a matching name patches that entry, a new name appends).
@@ -20,7 +20,9 @@ always shows the resolved, merged result for the repo you're in.
    underneath it.
 
 `spf init` seeds step 2 — on a TTY, via an interview that asks the fields
-below and appends whatever secrets they imply to `.env`; non-interactively
+below and appends whatever secrets they imply to `.env` (a non-secret,
+declarative setting like `SPF_CLAUDE_CMD` goes into this file's own `env:`
+block instead — see "Declarative env vars" below); non-interactively
 (`--yes`, `--template <name>`, or no TTY) it writes a commented starter
 instead. Omitting `.spf/spf.config.yaml` entirely means running off pure
 built-ins, which is a fully supported, valid state.
@@ -247,7 +249,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, 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. |
+| `events` | `"off"` \| `"errors"` \| `"attention"` \| `"all"` | The whole filter, narrowest to widest. `off` (default): nothing. `errors`: only true failures — failed runs/phases (`run_failed`/`phase_failed`), `watch_error`. `attention`: `errors` plus anything needing a human but not itself a failure — a blocked issue (`issue_blocked`) or a spec needing feedback (`spec_needs_feedback`). `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus `attention` and `errors`. |
 | `timeout_ms` | int | Per-request timeout for a channel's HTTP POST. Default `5000`. |
 | `channels[]` | array | See below. |
 
@@ -261,7 +263,7 @@ kind.
 
 ```yaml
 notifications:
-  events: errors
+  events: attention
   channels:
     - kind: slack
       webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
@@ -497,28 +499,60 @@ change made inside that backend's own module, not config — see
 
 ## Pointing `claude_code` at Ollama
 
-No config section for this — it's an environment-variable recipe, since
-`agent_cc.ts` passes the operator's environment straight through to the
-`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. `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
+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. `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.
+Routing through `SPF_CLAUDE_CMD` instead — e.g.
+`env: { SPF_CLAUDE_CMD: "ollama launch claude --model {model}" }` in
+`spf.config.yaml` (declarative, not a secret — see "Declarative env vars"
+below; a plain shell export also works and still wins) — 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. A literal `{model}`
+token anywhere in `SPF_CLAUDE_CMD` is substituted with the calling agent's
+own `model:` field before spawning — since `ollama launch`'s `--model` is
+what actually pins the model for the whole launched process, a FIXED tag
+there means every `claude_code` agent shares one model regardless of its own
+`model:`; `{model}` is what makes per-agent model choice real under this
+launcher. 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.
+
+## Declarative env vars
+
+A top-level `env:` map in `spf.config.yaml` sets `process.env` defaults for
+settings that are configuration, not secrets — `SPF_CLAUDE_CMD` above is the
+motivating case. Applied once, in `cli/index.ts`'s `main()`, right after
+`.env` loads and before any command runs. Merge is key-by-key (like
+`defaults`/`watch`), so a `.spf/spf.config.yaml` override can add one key
+without repeating the rest.
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+  SOME_TOKEN: "${SOME_SECRET_FROM_DOTENV}"
+```
+
+A plain value commits as literal text. `${VAR}` interpolates from whatever's
+already in `process.env` at that point — the real shell, or `.env`, both of
+which load first — so a genuine secret can stay in `.env` (gitignored) and
+be referenced here without ever being written into this (committed) file.
+Precedence: an already-set `process.env` value always wins over `env:`'s —
+this block supplies a default, never forces an override, the same way
+`process.loadEnvFile()` itself never overwrites an already-set var. A
+`${VAR}` reference to something genuinely unset fails loudly at startup,
+naming the missing variable — see `agents.ts`'s `interpolateEnvValue`/
+`applyConfigEnv`.

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

@@ -91,11 +91,12 @@ agents:
 # Optional: push notifications for unattended work — spf watch's daemon
 # lifecycle, and every chain run (including watch's own per-issue runs).
 # Interactive commands (doctor, list, sessions, ...) never notify. events:
-# "errors" sends only failures/blocked issues; "all" adds every milestone.
-# The webhook URL is a secret — put it in .env under the key named below,
-# never here. See the main README's "Notifications" section.
+# "errors" sends only true failures; "attention" adds blocked issues and
+# feedback requests; "all" adds every milestone too. The webhook URL is a
+# secret — put it in .env under the key named below, never here. See the
+# main README's "Notifications" section.
 # notifications:
-#   events: errors            # off (default) | errors | all
+#   events: attention          # off (default) | errors | attention | all
 #   channels:
 #     - kind: slack            # slack | teams | webhook
 #       webhook_url_env: SLACK_WEBHOOK_URL

package/dist/cli/commands/init.js

@@ -112,12 +112,13 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 # lifecycle, and every chain run (spf <chain> / spf run, including watch's
 # own per-issue runs). Interactive commands (doctor, list, sessions, ...)
 # never notify — you're already looking at the terminal for those. events:
-# "errors" sends only failures/blocked issues; "all" adds every milestone
-# (run started, issue claimed, PR opened, ...). The URL is a secret and
-# lives only in .env — never in this file. See README.md's "Notifications"
-# section for how to get each webhook URL.
+# "errors" sends only true failures; "attention" adds blocked issues and
+# feedback requests; "all" adds every milestone too (run started, issue
+# claimed, PR opened, ...). The URL is a secret and lives only in .env —
+# never in this file. See README.md's "Notifications" section for how to
+# get each webhook URL.
 # notifications:
-#   events: errors            # off (default) | errors | all
+#   events: attention          # off (default) | errors | attention | all
 #   channels:
 #     - kind: slack            # slack | teams | webhook
 #       webhook_url_env: SLACK_WEBHOOK_URL   # default for slack; TEAMS_WEBHOOK_URL / SPF_WEBHOOK_URL for the others

package/dist/cli/index.js

@@ -5,6 +5,7 @@
  * common case. Everything else is a named subcommand.
  */
 import path from "node:path";
+import * as agents from "../core/agents.js";
 import * as agentCc from "../core/agent_cc.js";
 import * as agentFlue from "../core/agent_flue.js";
 import * as notify from "../core/notify/notifier.js";
@@ -57,6 +58,11 @@ function findCwdFlag(argv) {
     const idx = argv.indexOf("--cwd");
     return idx !== -1 ? argv[idx + 1] : undefined;
 }
+/** Same idea, for `--config` — needed before dispatch too, to resolve `cfg.env` early. */
+function findConfigFlag(argv) {
+    const idx = argv.indexOf("--config");
+    return idx !== -1 ? argv[idx + 1] : undefined;
+}
 /**
  * The moment someone types a chain name that doesn't resolve is the highest-
  * traffic place a broken `.spf/chains/*.yaml` file is ever discovered — and,
@@ -104,6 +110,20 @@ export async function main() {
     catch {
         // no .env there — fine, nothing to load
     }
+    // `cfg.env` (spf.config.yaml's declarative env-var defaults — see
+    // data_types.ts's SFConfigSchema doc comment) has to land in process.env
+    // BEFORE any command reads it (SPF_CLAUDE_CMD, a provider key, ...), and
+    // .env/the real shell (just loaded above) must still win over it. Best-
+    // effort only: a config that fails to load here (missing, invalid yaml) is
+    // reported properly by whatever the actual command's own `agents.loadConfig`
+    // call does moments later — this pass exists purely to apply `env`, early.
+    try {
+        const resolution = paths.resolveConfigPaths(anchor, findConfigFlag(rest));
+        agents.applyConfigEnv(agents.loadConfig(resolution.paths).env);
+    }
+    catch {
+        // reported properly by the real command dispatch below, if it matters there
+    }
     // Repo-local chains as DATA: a `.spf/chains/*.yaml` file names existing
     // step factories, it never imports repo code — SPF's own dispatcher stays
     // the one thing that ever executes. Registered here, before the command

package/dist/cli/interview.js

@@ -79,6 +79,11 @@ export async function runInterview(asker, ctx) {
     const defaults = {};
     const agentOverrides = [];
     const env = {};
+    // Declarative, non-secret env vars — written to spf.config.yaml's `env:`
+    // (committable) rather than `.env` (gitignored, and read once from the
+    // shell rather than declared). `SPF_CLAUDE_CMD` is the one case so far:
+    // it names a launcher/wrapper command, not a credential.
+    const configEnv = {};
     const envExampleKeys = [];
     const notes = [];
     // ── 1. coding agent ────────────────────────────────────────────────────────
@@ -92,9 +97,9 @@ export async function runInterview(asker, ctx) {
         if (!ctx.claudeOnPath) {
             asker.note("warning: `claude` was not found on PATH — install it (or set a launch command below) before running spf.");
         }
-        const launchCommand = await asker.text('Launch command for the `claude` CLI — e.g. "ollama launch claude" to route through a wrapper (SPF_CLAUDE_CMD)', { default: "claude" });
+        const launchCommand = await asker.text('Launch command for the `claude` CLI — e.g. "ollama launch claude --model {model}" to route through a wrapper, with {model} substituted per-agent (writes env.SPF_CLAUDE_CMD to spf.config.yaml)', { default: "claude" });
         if (launchCommand !== "claude")
-            env["SPF_CLAUDE_CMD"] = launchCommand;
+            configEnv["SPF_CLAUDE_CMD"] = launchCommand;
         const model = await asker.select("Model (Claude Code's own vocabulary — not provider/model-id)", [
             { value: "sonnet", label: "sonnet" },
             { value: "opus", label: "opus" },
@@ -345,9 +350,10 @@ export async function runInterview(asker, ctx) {
     let notifications = null;
     if (enableNotify) {
         const events = await asker.select("Notify on", [
-            { value: "errors", label: "errors — failed runs, blocked issues, watch errors" },
-            { value: "all", label: "all — every milestone (claimed, PR opened, done, ...) plus errors" },
-        ], "errors");
+            { value: "errors", label: "errors — failed runs and watch errors only" },
+            { value: "attention", label: "attention — errors, plus blocked issues and feedback requests" },
+            { value: "all", label: "all — every milestone (claimed, PR opened, done, ...) plus attention and errors" },
+        ], "attention");
         const channels = [];
         for (;;) {
             const kind = await asker.select("Channel", [
@@ -431,6 +437,8 @@ export async function runInterview(asker, ctx) {
     const quality = defaults["__quality__"];
     delete defaults["__quality__"];
     const config = { defaults };
+    if (Object.keys(configEnv).length > 0)
+        config.env = configEnv;
     if (agentOverrides.length > 0)
         config.agents = agentOverrides;
     if (quality)

package/dist/core/agent_cc.d.ts

@@ -8,8 +8,11 @@
  * dependencies, the same trade the pre-Flue `agent_pi.ts` made for `pi`.
  *
  * The `claude` command is resolved from `PATH` by default. To route it through
- * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD`
- * before running spf. Space-separated command chains are supported:
+ * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD` —
+ * ordinarily via `env: { SPF_CLAUDE_CMD: "..." }` in `spf.config.yaml`
+ * (see `SFConfigSchema`'s doc comment), since this is a declarative launcher
+ * choice, not a secret; a real shell export still works and still wins, for
+ * a one-off local override. Space-separated command chains are supported:
  *   - `SPF_CLAUDE_CMD="claude"` (default)
  *   - `SPF_CLAUDE_CMD="ollama launch claude --model <tag>"` (Ollama launcher —
  *     the `--model` is `ollama launch`'s OWN flag, and is mandatory in
@@ -17,6 +20,17 @@
  * The command/launcher must support the full Claude Code CLI interface.
  * When unset, defaults to `claude`.
  *
+ * A literal `{model}` token anywhere in `SPF_CLAUDE_CMD` is substituted with
+ * THIS call's own `request.model` before spawning — e.g.
+ * `SPF_CLAUDE_CMD="ollama launch claude --model {model}"` with one agent's
+ * `model: kimi-k2.7-code:cloud` and another's `model: qwen3-coder:cloud`
+ * genuinely dispatches each to its own model, since `ollama launch`'s
+ * `--model` (its OWN flag, resolved BEFORE `--`, not `claude`'s) is what
+ * actually pins which model serves the whole launched process — without
+ * `{model}`, that flag would have to be one fixed value for every
+ * claude_code agent in the roster, making each agent's own `model:` field
+ * inert no matter what it said.
+ *
  * Wrapper contract for the flags this module appends (`-p`, `--json-schema`,
  * `--model`, ...): a wrapper token chain is spawned as `[...cmdTokens,
  * ...args]`, so a plain passthrough shim needs nothing special, and a
@@ -101,6 +115,14 @@ export declare class CcToolCallTracker {
     private finish;
 }
 export declare function isKnownToolName(name: string): boolean;
+/**
+ * Resolve `SPF_CLAUDE_CMD` for THIS call, substituting a literal `{model}`
+ * token with `model` — see the module doc comment for why a fixed tag baked
+ * into the wrapper string can't give per-agent model choice under a
+ * launcher like `ollama launch`. Exported as its own pure function so this
+ * substitution is unit-testable without spawning a real subprocess.
+ */
+export declare function resolveClaudeCmdSpec(model: string): string;
 /** Kill any still-running `claude` children — call once, at process exit. Safe if none are running. */
 export declare function shutdown(): Promise<void>;
 /**

package/dist/core/agent_cc.js

@@ -8,8 +8,11 @@
  * dependencies, the same trade the pre-Flue `agent_pi.ts` made for `pi`.
  *
  * The `claude` command is resolved from `PATH` by default. To route it through
- * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD`
- * before running spf. Space-separated command chains are supported:
+ * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD` —
+ * ordinarily via `env: { SPF_CLAUDE_CMD: "..." }` in `spf.config.yaml`
+ * (see `SFConfigSchema`'s doc comment), since this is a declarative launcher
+ * choice, not a secret; a real shell export still works and still wins, for
+ * a one-off local override. Space-separated command chains are supported:
  *   - `SPF_CLAUDE_CMD="claude"` (default)
  *   - `SPF_CLAUDE_CMD="ollama launch claude --model <tag>"` (Ollama launcher —
  *     the `--model` is `ollama launch`'s OWN flag, and is mandatory in
@@ -17,6 +20,17 @@
  * The command/launcher must support the full Claude Code CLI interface.
  * When unset, defaults to `claude`.
  *
+ * A literal `{model}` token anywhere in `SPF_CLAUDE_CMD` is substituted with
+ * THIS call's own `request.model` before spawning — e.g.
+ * `SPF_CLAUDE_CMD="ollama launch claude --model {model}"` with one agent's
+ * `model: kimi-k2.7-code:cloud` and another's `model: qwen3-coder:cloud`
+ * genuinely dispatches each to its own model, since `ollama launch`'s
+ * `--model` (its OWN flag, resolved BEFORE `--`, not `claude`'s) is what
+ * actually pins which model serves the whole launched process — without
+ * `{model}`, that flag would have to be one fixed value for every
+ * claude_code agent in the roster, making each agent's own `model:` field
+ * inert no matter what it said.
+ *
  * Wrapper contract for the flags this module appends (`-p`, `--json-schema`,
  * `--model`, ...): a wrapper token chain is spawned as `[...cmdTokens,
  * ...args]`, so a plain passthrough shim needs nothing special, and a
@@ -225,6 +239,16 @@ const EFFORT_MAP = {
     xhigh: "xhigh",
     max: "max",
 };
+/**
+ * Resolve `SPF_CLAUDE_CMD` for THIS call, substituting a literal `{model}`
+ * token with `model` — see the module doc comment for why a fixed tag baked
+ * into the wrapper string can't give per-agent model choice under a
+ * launcher like `ollama launch`. Exported as its own pure function so this
+ * substitution is unit-testable without spawning a real subprocess.
+ */
+export function resolveClaudeCmdSpec(model) {
+    return (process.env.SPF_CLAUDE_CMD || "claude").replaceAll("{model}", model);
+}
 // ── process lifecycle ────────────────────────────────────────────────────────
 const inFlight = new Set();
 /** Kill any still-running `claude` children — call once, at process exit. Safe if none are running. */
@@ -278,7 +302,7 @@ export async function run(request, onEvent, onSpawn, onExit) {
         toolsFlagValue(request.tools),
         "--strict-mcp-config", // see the module doc comment — required, not optional
     ];
-    const cmdSpec = process.env.SPF_CLAUDE_CMD || "claude";
+    const cmdSpec = resolveClaudeCmdSpec(request.model);
     const cmdTokens = cmdSpec.split(/\s+/).filter(Boolean);
     const [cmd, ...cmdArgs] = cmdTokens;
     // See the module doc comment for why `ollama launch ...` (and ONLY that

package/dist/core/agents.d.ts

@@ -75,6 +75,26 @@ export declare function assertRunBudget(run: RunBudgetState): void;
  * and agents.validate() reports that plainly.
  */
 export declare function loadConfig(configPaths: string[]): SFConfig;
+/**
+ * `${VAR}` substitutes from `process.env` at call time — a real secret can
+ * live in `.env` (gitignored) and be referenced from the committed
+ * `spf.config.yaml` without ever being written into it. An undefined
+ * reference throws rather than silently interpolating to `""`: a value like
+ * `SPF_CLAUDE_CMD="ollama launch claude --model ${OLLAMA_TAG}"` silently
+ * missing its tag would fail confusingly far downstream (a launcher error,
+ * or a wrong-but-plausible model), not here where the actual cause is known.
+ */
+export declare function interpolateEnvValue(key: string, raw: string): string;
+/**
+ * Apply `cfg.env` to `process.env` — called once, in `cli/index.ts`'s
+ * `main()`, right after `.env` loads and before any command runs, so every
+ * later `process.env[...]` read (provider keys, `SPF_CLAUDE_CMD`, ...) sees
+ * the result. A key already set in `process.env` (a real shell export, or
+ * `.env`, both of which load before this) is left untouched — `cfg.env`
+ * supplies a DEFAULT, never forces an override, mirroring
+ * `process.loadEnvFile()`'s own precedence for `.env` itself.
+ */
+export declare function applyConfigEnv(env: Record<string, string>): void;
 export declare function resolve(cfg: SFConfig, name: string): AgentConfig;
 /** Fail fast: every required name must resolve to a usable agent. */
 export declare function validate(cfg: SFConfig, required: string[], requiredSuites?: string[], cwd?: string): void;

package/dist/core/agents.js

@@ -146,6 +146,9 @@ function mergeAgentLists(base, override) {
  */
 function mergeRawConfig(base, override) {
     return {
+        // Key-by-key, like `defaults`/`watch` — a repo override adding ONE env
+        // var shouldn't have to repeat every built-in one.
+        env: { ...(base.env || {}), ...(override.env || {}) },
         defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
         observability: { ...(base.observability || {}), ...(override.observability || {}) },
         quality: { ...(base.quality || {}), ...(override.quality || {}) },
@@ -220,6 +223,41 @@ export function loadConfig(configPaths) {
         throw new Error(`invalid config (${configPaths.join(", ")}): ${describeParseError(error)}`);
     }
 }
+const ENV_VAR_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * `${VAR}` substitutes from `process.env` at call time — a real secret can
+ * live in `.env` (gitignored) and be referenced from the committed
+ * `spf.config.yaml` without ever being written into it. An undefined
+ * reference throws rather than silently interpolating to `""`: a value like
+ * `SPF_CLAUDE_CMD="ollama launch claude --model ${OLLAMA_TAG}"` silently
+ * missing its tag would fail confusingly far downstream (a launcher error,
+ * or a wrong-but-plausible model), not here where the actual cause is known.
+ */
+export function interpolateEnvValue(key, raw) {
+    return raw.replace(ENV_VAR_REF, (_match, name) => {
+        const value = process.env[name];
+        if (value === undefined) {
+            throw new Error(`env.${key}: references \${${name}}, which is not set (.env or the shell) — set it before running spf`);
+        }
+        return value;
+    });
+}
+/**
+ * Apply `cfg.env` to `process.env` — called once, in `cli/index.ts`'s
+ * `main()`, right after `.env` loads and before any command runs, so every
+ * later `process.env[...]` read (provider keys, `SPF_CLAUDE_CMD`, ...) sees
+ * the result. A key already set in `process.env` (a real shell export, or
+ * `.env`, both of which load before this) is left untouched — `cfg.env`
+ * supplies a DEFAULT, never forces an override, mirroring
+ * `process.loadEnvFile()`'s own precedence for `.env` itself.
+ */
+export function applyConfigEnv(env) {
+    for (const [key, rawValue] of Object.entries(env)) {
+        if (process.env[key] !== undefined)
+            continue;
+        process.env[key] = interpolateEnvValue(key, rawValue);
+    }
+}
 export function resolve(cfg, name) {
     const agent = cfg.agents.find((a) => a.name === name);
     if (!agent) {

package/dist/core/data_types.d.ts

@@ -681,33 +681,38 @@ export type WatchConfig = v.InferOutput<typeof WatchConfigSchema>;
  * everything else (`spf doctor`, `list`, `sessions`, ...) is interactive, so
  * it stays console-only on purpose; see `core/notify/notifier.ts`.
  *
- * `events` is the whole filter: "off" sends nothing, "errors" sends only
- * NotifyEvents whose `level` is "error", "all" sends every curated
- * milestone. A channel's own `events` overrides the top-level scope for
- * just that channel (e.g. Slack gets everything, Teams gets errors only).
+ * `events` is the whole filter, from narrowest to widest:
+ *   - "off": sends nothing.
+ *   - "errors": only NotifyEvents whose `level` is "error" (true failures —
+ *     run_failed, phase_failed, watch_error).
+ *   - "attention": "errors" PLUS `level: "notice"` events — things that
+ *     need a human but aren't a failure (issue_blocked, spec_needs_feedback).
+ *   - "all": every curated milestone, `level: "info"` included.
+ * A channel's own `events` overrides the top-level scope for just that
+ * channel (e.g. Slack gets everything, Teams gets errors only).
  *
  * `webhook_url_env` names the .env key holding the secret URL — never the
  * URL itself, matching GITHUB_TOKEN/JIRA_API_TOKEN. Empty = the kind's own
  * default key (see core/notify/notifier.ts's DEFAULT_ENV_KEY).
  */
-export declare const NotifyScopeSchema: v.PicklistSchema<["off", "errors", "all"], undefined>;
+export declare const NotifyScopeSchema: v.PicklistSchema<["off", "errors", "attention", "all"], undefined>;
 export type NotifyScope = v.InferOutput<typeof NotifyScopeSchema>;
 export declare const NotifyChannelKindSchema: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
 export type NotifyChannelKind = v.InferOutput<typeof NotifyChannelKindSchema>;
 export declare const NotifyChannelSchema: v.ObjectSchema<{
     readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
     readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
-    readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+    readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
     readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
 }, undefined>;
 export type NotifyChannel = v.InferOutput<typeof NotifyChannelSchema>;
 export declare const NotificationsConfigSchema: v.ObjectSchema<{
-    readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, "off">;
+    readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, "off">;
     readonly timeout_ms: v.OptionalSchema<v.NumberSchema<undefined>, 5000>;
     readonly channels: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
         readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
         readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
-        readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+        readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
         readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
     }, undefined>, undefined>, () => never[]>;
 }, undefined>;
@@ -799,6 +804,7 @@ export declare const TieringConfigSchema: v.ObjectSchema<{
 }, undefined>;
 export type TieringConfig = v.InferOutput<typeof TieringConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
+    readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
         readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
@@ -1013,21 +1019,21 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         };
     }>;
     readonly notifications: v.OptionalSchema<v.ObjectSchema<{
-        readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, "off">;
+        readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, "off">;
         readonly timeout_ms: v.OptionalSchema<v.NumberSchema<undefined>, 5000>;
         readonly channels: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
             readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
             readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
-            readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+            readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
             readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
         }, undefined>, undefined>, () => never[]>;
     }, undefined>, () => {
-        events: "all" | "errors" | "off";
+        events: "all" | "attention" | "errors" | "off";
         timeout_ms: number;
         channels: {
             kind: "slack" | "teams" | "webhook";
             webhook_url_env: string;
-            events?: "all" | "errors" | "off" | null | undefined;
+            events?: "all" | "attention" | "errors" | "off" | null | undefined;
             name: string;
         }[];
     }>;

package/dist/core/data_types.js

@@ -538,16 +538,21 @@ export const WatchConfigSchema = v.object({
  * everything else (`spf doctor`, `list`, `sessions`, ...) is interactive, so
  * it stays console-only on purpose; see `core/notify/notifier.ts`.
  *
- * `events` is the whole filter: "off" sends nothing, "errors" sends only
- * NotifyEvents whose `level` is "error", "all" sends every curated
- * milestone. A channel's own `events` overrides the top-level scope for
- * just that channel (e.g. Slack gets everything, Teams gets errors only).
+ * `events` is the whole filter, from narrowest to widest:
+ *   - "off": sends nothing.
+ *   - "errors": only NotifyEvents whose `level` is "error" (true failures —
+ *     run_failed, phase_failed, watch_error).
+ *   - "attention": "errors" PLUS `level: "notice"` events — things that
+ *     need a human but aren't a failure (issue_blocked, spec_needs_feedback).
+ *   - "all": every curated milestone, `level: "info"` included.
+ * A channel's own `events` overrides the top-level scope for just that
+ * channel (e.g. Slack gets everything, Teams gets errors only).
  *
  * `webhook_url_env` names the .env key holding the secret URL — never the
  * URL itself, matching GITHUB_TOKEN/JIRA_API_TOKEN. Empty = the kind's own
  * default key (see core/notify/notifier.ts's DEFAULT_ENV_KEY).
  */
-export const NotifyScopeSchema = v.picklist(["off", "errors", "all"]);
+export const NotifyScopeSchema = v.picklist(["off", "errors", "attention", "all"]);
 export const NotifyChannelKindSchema = v.picklist(["slack", "teams", "webhook"]);
 export const NotifyChannelSchema = v.object({
     kind: NotifyChannelKindSchema,
@@ -642,6 +647,17 @@ export const TieringConfigSchema = v.object({
     roles: v.optional(v.record(v.string(), v.string()), () => ({})),
 });
 export const SFConfigSchema = v.object({
+    // Declarative env vars, applied to process.env before anything else reads
+    // it (see cli/index.ts's main()) — for non-secret settings that used to
+    // require an out-of-band shell export (e.g. SPF_CLAUDE_CMD) to be
+    // committable, plain text config instead of hidden process state. A value
+    // already set in process.env (the real shell, or .env, which loads first)
+    // always wins — this only supplies a DEFAULT, never forces an override.
+    // `${VAR}` inside a value interpolates from process.env at that same
+    // point, specifically so a real secret can be pulled in from `.env`
+    // without ever being written into this (committed) file — see
+    // `applyConfigEnv`/`interpolateEnvValue` in agents.ts.
+    env: v.optional(v.record(v.string(), v.string()), () => ({})),
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
     observability: v.optional(ObservabilityConfigSchema, () => v.parse(ObservabilityConfigSchema, {})),
     agents: v.optional(v.array(AgentConfigSchema), () => []),

package/dist/core/notify/channel.d.ts

@@ -14,8 +14,14 @@
 export type NotifyKind = "run_started" | "run_finished" | "run_failed" | "phase_failed" | "phase_retry" | "watch_started" | "watch_stopped" | "watch_error" | "issue_claimed" | "pr_opened" | "issue_done" | "issue_blocked" | "spec_refined" | "spec_needs_feedback" | "feature_done" | "spec_done";
 export interface NotifyEvent {
     kind: NotifyKind;
-    /** "error" sends under both `events: errors` and `events: all`; "info" only under `all`. */
-    level: "info" | "error";
+    /**
+     * The whole filter predicate a scope applies (see `NotifyScopeSchema` in
+     * `core/data_types.ts`): "error" is a true failure (sends under `errors`,
+     * `attention`, and `all`); "notice" needs a human but isn't a failure
+     * (sends under `attention` and `all`); "info" is a routine milestone
+     * (sends only under `all`).
+     */
+    level: "info" | "notice" | "error";
     /** One line, e.g. "run failed — plan-build-test". */
     title: string;
     /** The error text / PR body / block detail, if any. */

package/dist/core/notify/notifier.js

@@ -7,12 +7,17 @@ export const DEFAULT_NOTIFY_ENV_KEY = {
     teams: "TEAMS_WEBHOOK_URL",
     webhook: "SPF_WEBHOOK_URL",
 };
-/** `errors` mode only sends `level: "error"`; `all` sends everything; `off` sends nothing. */
+/**
+ * `off` sends nothing; `errors` only `level: "error"`; `attention` also
+ * lets `level: "notice"` through; `all` sends everything.
+ */
 function scopeAllows(scope, level) {
     if (scope === "off")
         return false;
     if (scope === "all")
         return true;
+    if (scope === "attention")
+        return level === "error" || level === "notice";
     return level === "error";
 }
 export class Notifier {

package/dist/core/notify/slack_channel.js

@@ -6,7 +6,7 @@ export class SlackChannel {
         this.label = name ? `slack (${name})` : "slack";
     }
     async send(event, timeoutMs) {
-        const emoji = event.level === "error" ? ":x:" : ":white_check_mark:";
+        const emoji = event.level === "error" ? ":x:" : event.level === "notice" ? ":warning:" : ":white_check_mark:";
         const fieldsText = event.fields.map(([k, v]) => `*${k}:* ${v}`).join("  ·  ");
         const body = {
             text: `${emoji} ${event.title}`,

package/dist/core/notify/teams_channel.js

@@ -6,7 +6,7 @@ export class TeamsChannel {
         this.label = name ? `teams (${name})` : "teams";
     }
     async send(event, timeoutMs) {
-        const color = event.level === "error" ? "attention" : "good";
+        const color = event.level === "error" ? "attention" : event.level === "notice" ? "warning" : "good";
         const facts = event.fields.map(([title, value]) => ({ title, value }));
         const card = {
             type: "AdaptiveCard",

package/dist/core/watch.js

@@ -134,7 +134,7 @@ export async function reconcileOrphans(deps, state) {
             deps.log(`watch: ${issue.id} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
             deps.notify({
                 kind: "issue_blocked",
-                level: "error",
+                level: "notice",
                 title: `issue ${issue.id} blocked`,
                 detail: `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned attempts.`,
                 fields: [["issue", issue.id], ["title", issue.title]],
@@ -348,11 +348,11 @@ async function escalateSpec(deps, issue, marker, questions, adwId, round) {
             .join("\n\n---\n\n") +
         `\n\n---\n\nAnswer inline, then add the \`${deps.labelPrefix}:continue-refinement\` label — refinement resumes from where it left off (adw_id \`${adwId}\`).`;
     deps.notify({
-        // "error" level, not "info" — this is the same class of event as
-        // issue_blocked ("spf needs a human"), and it belongs on an `errors`-scope
-        // channel just as much as an `all`-scope one.
+        // "notice" level, not "info" — this is the same class of event as
+        // issue_blocked ("spf needs a human"), and it belongs on an
+        // `attention`-scope channel just as much as an `all`-scope one.
         kind: "spec_needs_feedback",
-        level: "error",
+        level: "notice",
         title: `spec ${issue.id} needs feedback`,
         detail: `${questions.length} question(s), round ${round}.`,
         fields: [
@@ -398,7 +398,7 @@ export async function reconcileRefining(deps, state) {
             deps.log(`watch: spec ${issue.id} orphaned after asking round ${marker.feedback.rounds} — finishing the transition to needs-feedback`);
             deps.notify({
                 kind: "spec_needs_feedback",
-                level: "error",
+                level: "notice",
                 title: `spec ${issue.id} needs feedback`,
                 detail: `Round ${marker.feedback.rounds}.`,
                 fields: [["issue", issue.id], ["title", issue.title], ["round", String(marker.feedback.rounds)]],
@@ -419,7 +419,7 @@ export async function reconcileRefining(deps, state) {
             deps.log(`watch: spec ${issue.id} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
             deps.notify({
                 kind: "issue_blocked",
-                level: "error",
+                level: "notice",
                 title: `spec ${issue.id} blocked`,
                 detail: `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned refine attempts.`,
                 fields: [["issue", issue.id], ["title", issue.title]],
@@ -530,7 +530,7 @@ export async function finishReviews(deps) {
             deps.log(`watch: ${issue.id}'s PR #${marker.pr} closed without merging — blocked`);
             deps.notify({
                 kind: "issue_blocked",
-                level: "error",
+                level: "notice",
                 title: `issue ${issue.id} blocked`,
                 detail: `PR #${marker.pr} was closed without merging.`,
                 fields: [["issue", issue.id], ["title", issue.title], ["pr", `#${marker.pr}`]],
@@ -569,7 +569,7 @@ async function runIssue(deps, issue) {
             const detail = result.detail || `Chain "${deps.chain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`;
             deps.notify({
                 kind: "issue_blocked",
-                level: "error",
+                level: "notice",
                 title: `issue ${issue.id} blocked`,
                 detail,
                 fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", adwId]],
@@ -583,7 +583,7 @@ async function runIssue(deps, issue) {
             deps.log(`watch: ${issue.id}: chain succeeded but committed nothing — blocked`);
             deps.notify({
                 kind: "issue_blocked",
-                level: "error",
+                level: "notice",
                 title: `issue ${issue.id} blocked`,
                 detail: `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`,
                 fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", adwId]],
@@ -722,7 +722,7 @@ async function runSpec(deps, issue) {
             const detail = result.detail || `Refine chain "${deps.refineChain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`;
             deps.notify({
                 kind: "issue_blocked",
-                level: "error",
+                level: "notice",
                 title: `spec ${issue.id} blocked`,
                 detail,
                 fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.refineChain], ["adw_id", adwId]],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",