@gr8ful/spf 0.3.0 → 0.5.0

package/assets/skill/cookbooks/ocr_reviewer.md

@@ -0,0 +1,196 @@
+# Using `alibaba/open-code-review` as reviewer evidence
+
+Opt-in, repo-level, docs-only: nothing in the packaged reviewer prompt
+mentions `open-code-review` ("ocr"), and nothing ships that runs it. This
+cookbook is for a repo that wants its *own* reviewer to shell out to ocr and
+fold its findings in — a second opinion the reviewer reads as evidence, never
+a second decision-maker.
+
+**The rule this whole cookbook exists to protect: the reviewer agent stays
+the sole producer of `ReviewOutput`.** `ocr review`/`ocr scan` is a bash
+command whose stdout the reviewer reads, the same as `git diff` — nothing
+new gates a commit, because the reviewer's own `approved`/`findings`/
+`blocking` is still the only envelope anything downstream ever consumes. If
+you want that packaged-prompt wording, see the one line
+`assets/prompts/reviewer/system.md` already carries: "except tools whose
+output is the product ... which you read as evidence, never as a verdict."
+
+You wire this in with a repo-local prompt override, not a fork of `spf`
+itself — `.spf/prompt_engineering/<agent>/` resolves before the packaged
+default (see `core/paths.ts`'s `resolvePromptRef`: repo root, then
+`.spf/<ref>`, then `.spf/prompt_engineering/<ref>`, then the packaged asset —
+first hit wins). Copy `reviewer/system.md` into
+`.spf/prompt_engineering/reviewer/system.md`, add the ocr instructions, and
+every chain that names `reviewer` picks it up with no code change.
+
+## (a) Credentials — set `env_allowlist` before you add ocr
+
+The reviewer's `bash` tool does not run in a sandbox; it inherits whatever
+environment this agent's request carries. Today, unless you configure
+otherwise, that is the FULL operator environment — every key in the shell
+`spf` was launched from, plus anything loaded from the repo's `.env`
+(`AgentConfigSchema.env_allowlist`, `core/agents.ts`'s `agentEnv()`: unset
+means "don't filter at all"). That is fine for a reviewer that only ever
+runs `git diff`/`grep`/`bun test`. It stops being fine the moment `bash` can
+also run `ocr`, because ocr is a THIRD-PARTY BINARY THAT INVOKES ITS OWN LLM
+— it can send anything reachable in that environment (your `ANTHROPIC_API_KEY`,
+`GITHUB_TOKEN`, cloud credentials, database URLs in `.env`) to wherever its
+own model call goes, and nothing in `spf` observes that call to say otherwise.
+
+Before pointing the reviewer's prompt at ocr, give that agent an explicit
+allowlist so its `bash` tool — and therefore ocr — only ever sees what ocr
+itself actually needs, plus the baseline `PATH`/`HOME`/`USER`/`LANG`/`TERM`/
+`TMPDIR` every backend keeps regardless.
+
+**What `env_allowlist` actually scopes depends on the reviewer's backend.**
+On `coding_agent: claude_code`, it is the environment of the WHOLE `claude`
+subprocess, not just its `bash` tool (`core/agent_cc.ts`'s `spawn(cmd,
+fullArgs, { cwd, env: request.env ?? operatorEnv() })`) — so an allowlist
+scoped only to ocr's own keys strips `ANTHROPIC_API_KEY` from the `claude`
+CLI itself, and the reviewer stops authenticating (unless it relies on
+`claude login`, since `HOME` is in the baseline and that flow's credentials
+live under it). A `claude_code` reviewer must therefore also keep its own
+backend credential in the list. On the default `flue` backend it is safe as
+written below, because `request.env` there only reaches the tool sandbox
+(`local({cwd, env})` in `core/agent_flue.ts`) — Flue's own provider
+credentials are read from the parent's `process.env` regardless of this
+list.
+
+```yaml
+# .spf/spf.config.yaml — patches the packaged "reviewer" entry by name
+agents:
+  - name: reviewer
+    env_allowlist:
+      - OCR_API_KEY        # whatever credential ocr's own model call needs
+      - OCR_BASE_URL        # if ocr talks to a self-hosted or proxied endpoint
+```
+
+Agent config entries merge by name (`core/agents.ts`'s `mergeAgentLists`) and
+patch by field, so this adds `env_allowlist` to the reviewer without having
+to repeat its `model`/`prompt_engineering`/`writes`/`tools`. Do this even if
+you think the reviewer "doesn't have secrets to leak" — the allowlist is
+what makes that true, not an assumption about what happens to be in the
+shell today.
+
+## (b) Writes — ocr must not put a file in the repo
+
+The packaged reviewer runs `writes: []` — read-only with respect to the
+repo, enforced in code after the call (`core/permissions.ts`), not by asking
+the model nicely. That enforcement has no retry path: it is not a gate a
+violation can re-prompt its way past. A path ocr drops anywhere in the
+working tree becomes a `PermissionBreach`, which `agents.execute()` throws
+straight out of the phase — the run aborts, the same session does not get a
+chance to fix it, and whatever ocr wrote gets rolled back if it can be
+(deleted, if untracked; left alone and reported if it collided with a file
+that was already dirty).
+
+Two things to do before wiring ocr in for real, not after the first failed
+run teaches you the hard way:
+
+- **Verify ocr's cache/output behavior first**, outside of `spf` — run it
+  by hand in a scratch clone and check `git status` afterward. Some
+  review/scan tools default to writing a cache directory or a report file
+  next to the code they scanned.
+- **Point any output ocr can be configured to write at a path outside the
+  repo, or under the run's own data directory** — `context_handoff_dir` is
+  always writable regardless of `writes: []` (`core/permissions.ts`'s
+  `alwaysWritable()`: the session runtime under `defaults.data_dir` is
+  granted to every agent, read-only ones included, because it is where an
+  agent hands its own report to the next phase, not repo content). The
+  reviewer's own prompt template already receives it as `{{context_handoff_dir}}`
+  — reuse that instead of a path ocr would put inside the tracked tree.
+
+If ocr has no such flag, prefer piping its output to stdout and letting the
+reviewer's bash call capture it that way — no file, nothing to breach.
+
+## (c) Accounting honesty — ocr's spend is invisible to spf
+
+`spf` counts tokens and dollars in exactly one place:
+`core/agents.ts`'s `execute()`, around the ONE backend call it makes per
+agent turn (Flue or Claude Code), via `run.addUsage()`. That is the
+reviewer's own LLM call. `ocr review`/`ocr scan` invoked from inside that
+call's `bash` tool is a subprocess the tracer sees as a `tool_call` event —
+arguments, an ok/error flag, and captured output (both clipped at 20,000
+characters) — not an exit status; a non-zero `ocr` exit usually still comes
+back as ordinary successful tool output with the code inside the text, the
+same as any other shell command — never as a second `agent_start`/
+`agent_end` pair, because it isn't one from `spf`'s point of view: it is a
+program the reviewer ran, the same shape as `bun test`. Whatever ocr's own
+model call cost, on whatever credential you scoped in (a), is spent and
+billed entirely outside `spf`'s usage tracking (`spf sessions`, the `cost`
+column, the UI's usage panel — none of them will show it).
+
+Be honest with yourself and whoever reads the trace about what this means:
+the session total you see for a `reviewer` phase is a **floor**, not the
+full cost of that review, whenever ocr ran. And whether ocr ran at all on a
+given run is at the MODEL's discretion — it's an instruction in a prompt,
+not a step in a chain, so a reviewer that judges the diff sufficient on its
+own is free to never invoke it. If you need to know it ran, ask the prompt
+to say so in its own `notes_for_next_agent`, and read the phase's
+`tool_call` events for the `ocr` invocation itself — that is the only
+record of it that exists.
+
+## (d) `spf doctor` does not check for ocr
+
+Deliberately. `spf doctor` checks binaries it has a specific, packaged
+reason to expect: `quality.checks[].argv[0]` (your configured lint/test/build
+commands), the `claude` CLI when `coding_agent: claude_code`, provider env
+keys for whatever `model:` a roster entry names. None of those surfaces ever
+mention ocr, because nothing packaged expects it to exist — it is named only
+inside a prompt file YOU wrote, in a place `doctor` has no reason to read. A
+missing or broken `ocr` binary therefore fails silently from `doctor`'s point
+of view; the reviewer will simply get a failed-command result back from its
+own `bash` tool call, the same as any other missing binary, and has to
+handle that in its judgment like any other tool failure — never a `spf
+doctor` line telling you in advance.
+
+## (e) A worked prompt-override snippet
+
+`.spf/prompt_engineering/reviewer/system.md` — the packaged file, with one
+instruction added (keep everything else; this only appends):
+
+```markdown
+# Reviewer Agent
+
+## Purpose
+
+Confirm that what was built is what was asked for. This is not testing.
+
+## Instructions
+
+- Your spec is `<context_handoff_dir>/plan.md` when that file exists — the plan is the refined ask. Otherwise the spec is `prompt`, verbatim.
+- Judge the code on disk, never the builder's summary of it. Start from `previous_envelope.changed_files`, read them, and use `git diff` for anything the envelope did not mention.
+- Break the spec into concrete requirements and rule on each one: met, or not met with the evidence — a `file:line`, or exactly what is missing.
+- Not your job: running tests, style opinions, refactors, or anything the request did not ask for. Work the request never asked for is not blocking on its own; work the request DID ask for and is missing always is.
+- Change nothing. Findings go back to the builder — that is the only repair path.
+- `approved` is true ONLY when every requirement is met and `blocking` is empty. Every blocking item names the specific gap, so the builder can fix it without guessing.
+- You inherit the operator's shell environment, filtered to this agent's `env_allowlist` — call tools by bare name (`bun`, `uv`, `git`, `ocr`); never hunt for a binary or fall back to an absolute `/usr/bin/*` path.
+- Judge any command you run by its exit status, never by scanning its output for words — except tools whose output is the product, such as `git diff`, or a review tool you were asked to consult, which you read as evidence, never as a verdict.
+
+## One more evidence source: `ocr`
+
+Before writing your findings, run `ocr review --format json` (falls back to
+`ocr scan` if `review` is unavailable in this ocr version) against the
+files in `previous_envelope.changed_files`, piping its output rather than
+writing it to any path in the repo. Treat whatever it reports exactly like a
+`git diff` hunk: evidence to weigh, in your own words, against the spec —
+never a verdict you pass through. Fold anything it found that maps to a real
+requirement into your own `findings`/`blocking`; ignore style opinions it
+raises that the spec never asked about. You alone decide `approved` — ocr
+has no vote. If `ocr` is not on `PATH` or the command errors, note that in
+`notes_for_next_agent` and review from the diff alone; a missing second
+opinion is not a blocking finding about the CODE.
+```
+
+And the config half, from (a):
+
+```yaml
+# .spf/spf.config.yaml
+agents:
+  - name: reviewer
+    env_allowlist:
+      - OCR_API_KEY
+      - OCR_BASE_URL
+```
+
+That's the whole integration: one prompt file, one config patch, zero code.

package/assets/skill/cookbooks/roster.md

@@ -72,10 +72,13 @@ agents:
     tools: [read, edit, bash]  # same canonical names either way — see "Retune tools" below
 ```
 
-`claude_code` shells out to your own installed `claude` CLI (`spf doctor`
-checks it's on `PATH`) — it needs no separate npm install, since SPF never
-depends on it directly. A missing `ANTHROPIC_API_KEY` is informational, not
-a hard failure: Claude Code also supports its own `claude login` flow.
+`claude_code` shells out to your own installed `claude` CLI — it needs no
+separate npm install, since SPF never depends on it directly. `spf doctor`
+checks whatever `SPF_CLAUDE_CMD`'s first token resolves to on `PATH` (see
+below for routing through a wrapper or launcher), falling back to the
+literal `claude` when `SPF_CLAUDE_CMD` is unset. A missing `ANTHROPIC_API_KEY`
+is informational, not a hard failure: Claude Code also supports its own
+`claude login` flow.
 
 **Pointing a `claude_code` agent at Ollama** — local or cloud — needs no
 config at all, just environment variables set before you run `spf` (Claude
@@ -94,6 +97,14 @@ set `ANTHROPIC_AUTH_TOKEN` to a real Ollama Cloud API key. This is exactly
 the same environment-variable pass-through every agent already gets — no
 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.
+
 ## Retune tools
 
 Known tool names: `read`, `bash`, `edit`, `write`, `grep`, `glob` (`find` is

package/assets/skill/cookbooks/spf_overview.md

@@ -106,6 +106,7 @@ launching anything.
 | Launch a chain, watch it, report on it | `cookbooks/run_adw.md` (after `how_to_prompt_for_the_eng.md`) |
 | Retune the roster, add an agent | `cookbooks/roster.md` |
 | Add or extend a chain | `cookbooks/authoring_chains.md` |
+| Fold a third-party review tool's findings into the reviewer's verdict | `cookbooks/ocr_reviewer.md` |
 | Envelope/gate/session contract | `references/handoff.md` |
 | Trace schema, spend vs. context | `references/observability.md` |
 | Full config field reference | `references/config.md` |

package/assets/skill/references/config.md

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

package/assets/skill/references/observability.md

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

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

@@ -47,9 +47,9 @@ defaults:
 # provider/model-id strings, which an agent's own model always wins over
 # defaults.model above — switching coding_agent globally does NOT reset
 # those three, so they'd run on Claude Code (redirected at Ollama) with a
-# model id Ollama has never heard of, and fail outright. builder/scout
-# have no model of their own in the packaged roster, so they correctly
-# inherit defaults.model above and need no override here.
+# model id Ollama has never heard of, and fail outright. builder/scout/
+# refiner have no model of their own in the packaged roster, so they
+# correctly inherit defaults.model above and need no override here.
 agents:
   - name: planner
     model: qwen3-coder:30b

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

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

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

@@ -39,8 +39,8 @@ defaults:
 # always wins over defaults.model — switching coding_agent globally does
 # NOT reset those three, so they'd run on Claude Code with a model id it
 # can't resolve at all ("There's an issue with the selected model...").
-# builder/scout have no model of their own in the packaged roster, so they
-# correctly inherit defaults.model above and need no override here.
+# builder/scout/refiner have no model of their own in the packaged roster,
+# so they correctly inherit defaults.model above and need no override here.
 agents:
   - name: planner
     model: sonnet
@@ -61,9 +61,22 @@ agents:
 # Needs a GITHUB_TOKEN env var (classic PAT, repo scope) for the defaults below.
 # watch:
 #   repo: owner/name
+#   # issue_repo: owner/name   # ONLY for issue_provider: github + code_host: bitbucket,
+#   #                          # where the issue tracker and code host are genuinely
+#   #                          # different repos — repo above is then the BITBUCKET
+#   #                          # repo, and issue_repo is the GitHub one. Unused/unset
+#   #                          # for every other combination.
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+#   # 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.
+#   refine:
+#     enabled: true
+#     chain: refine
+#     concurrency: 1
 
 # Optional: push notifications for unattended work — spf watch's daemon
 # lifecycle, and every chain run (including watch's own per-issue runs).

package/dist/chains/context.d.ts

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