@gr8ful/spf 0.4.0 → 0.5.1

package/README.md

@@ -120,7 +120,7 @@ Config defines who an agent **is**. The chain call site defines how it is **used
 
 ### A second backend: Claude Code
 
-Set `coding_agent: claude_code` on any agent (or in `defaults`) to run it on your own installed [Claude Code](https://claude.com/product/claude-code) CLI instead of Flue — `spf doctor` checks it's on `PATH`. Model names follow Claude Code's own vocabulary (a bare alias like `sonnet`, not `provider/model-id`); everything else — `tools`, `writes`, `thinking` — stays the same shape. Pointing a `claude_code` agent at a local or cloud [Ollama](https://ollama.com) server needs no config at all — just `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` set before you run `spf`, since Claude Code's CLI reads those itself.
+Set `coding_agent: claude_code` on any agent (or in `defaults`) to run it on your own installed [Claude Code](https://claude.com/product/claude-code) CLI instead of Flue — `spf doctor` checks whatever `SPF_CLAUDE_CMD`'s first token resolves to on `PATH` (`claude` itself, by default). Model names follow Claude Code's own vocabulary (a bare alias like `sonnet`, not `provider/model-id`); everything else — `tools`, `writes`, `thinking` — stays the same shape. Pointing a `claude_code` agent at a local or cloud [Ollama](https://ollama.com) server needs no config at all — just `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` set before you run `spf`, since Claude Code's CLI reads those itself.
 
 #### Proxy or wrapper launchers
 
@@ -128,17 +128,52 @@ To route the `claude` command through a wrapper, proxy server, or launcher (e.g.
 
 ```bash
 # Route through Ollama's launcher
-export SPF_CLAUDE_CMD="ollama launch claude"
+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.
+
 ```bash
 # Or use a custom wrapper script
 export SPF_CLAUDE_CMD=/path/to/my-wrapper
 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).
+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.
+
+### 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/...`:
+
+```yaml
+defaults:
+  coding_agent: flue
+  model: ollama/qwen3.8:27b-mlx
+```
+
+```bash
+export OLLAMA_BASE_URL=http://localhost:11434/v1   # default if unset
+spf build "your prompt"
+```
+
+That's the whole config change. `ollama` is a keyless provider — `spf doctor` and the `spf init` interview both know this: no API key is ever asked for or checked, and interview.ts asks for `OLLAMA_BASE_URL` instead when you pick `ollama` as your provider. A ready-to-run starting point ships at [`assets/templates/ts-flue-ollama.spf.config.yaml`](assets/templates/ts-flue-ollama.spf.config.yaml) (`spf init --template ts-flue-ollama`).
+
+Two things worth knowing before pointing a full roster at local models: tool-calling — the injected `sf_report` contract every agent's structured output rides on — worked reliably in testing down to a 3B-parameter model, which isn't a "only frontier models get tools" situation. And context-window occupancy reporting is disabled for `ollama/*` models specifically, which turns off threshold-based compaction rather than reporting a number Ollama's OpenAI-compatible API doesn't actually provide per model.
+
+---
+
+## Isolation: post-hoc, not a sandbox
+
+Agent isolation in SPF is enforced **after the fact**, not upfront. This matters because the `tools:` capability list is not a sandbox — a `bash` tool can run `git checkout` to discard changes, and a `write` tool can reach any path, regardless of the allowlist you write. So permission is verified the way every other claim in this system is: the working tree is fingerprinted before an agent runs, then compared after. If the agent touched anything outside its `writes:` allowlist (or a `protected_files:` path it wasn't given access to), the phase fails and anything the agent *introduced* outside its allowlist is rolled back. What it cannot undo, it names: a file that was already dirty before the agent ran is left alone rather than discarded, and uncommitted work the agent reverted cannot be restored. And because the check is post-hoc and tree-scoped, nothing outside the working tree is in scope at all — a push, a network call, a write above `repo_root`. When running an agent on the claude_code backend, SPF spawns it with `--permission-mode bypassPermissions --dangerously-skip-permissions` because the backend has no need to enforce — SPF will enforce in code instead, within those bounds.
+
+For unattended work, `spf watch`'s PR-merge is the only human accountability checkpoint: the daemon opens a PR for each automated run, and a human approves the merge. For any other workflow, this enforcement is the backbone of letting a bounded agent proposal survive code's inspection without a human having to read it in between — but it is bounded, not a sandbox, and the scope above is what a reviewer should actually rely on. (Attended `simple-sdlc` runs get a second checkpoint of their own — see below.)
+
+See `core/permissions.ts` for the implementation — the snapshot/compare logic, not the config terms.
+
+`simple-sdlc`'s `commit_build` phase is the one place in this codebase where an AI reviewer's `approved` flag alone would otherwise gate a commit — everywhere else the reviewer either doesn't run (`plan-build-test`, ...) or nothing commits on its verdict (`build-review` has no commit step). Run attended, that phase asks before committing — default **no**, never `review.approved` itself, bounded by `review.signoff_timeout_seconds` (default 300s; expiry answers no) — and only an explicit, recorded "yes" ever earns a `Signed-off-by:` trailer, built from `git config user.name`/`user.email` at the repo, never an env var. Run unattended (`spf watch`, CI), there is nobody to ask: `spf watch`'s own human gate is the PR merge above, informed by the reviewer's digest in the PR body, and the phase either proceeds on the AI verdict alone with a loud warning (`review.require_human_signoff: false`, this release's default — fail-open until `spf watch` itself becomes signoff-aware) or fails closed and asks you to rerun attended (`require_human_signoff: true`). See `assets/skill/references/config.md`'s `review` section for the two knobs, and [`assets/skill/cookbooks/ocr_reviewer.md`](assets/skill/cookbooks/ocr_reviewer.md) if you want the reviewer to fold a third-party review tool's findings into its own verdict as one more piece of evidence.
 
 ---
 
@@ -214,7 +249,7 @@ Files stay the raw record (`envelope.json`, `agent_map.json`, Flue's own convers
 
 ```bash
 spf list                                              # every chain, its phases, what it needs
-spf <chain> "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4] [--cwd <dir>]
+spf <chain> "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4] [--cwd <dir>] [--suite <name>]
 ```
 
 | Chain | Phases | Reach for it when |
@@ -232,6 +267,8 @@ spf <chain> "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4
 | `document` | code(git diff), documenter | write up what just shipped |
 | `simple-sdlc` | plan, build, test, review, document | the work is real and its shape is not obvious |
 
+A chain with a compiled-in quality suite (`build-test`, `plan-build-test`, `plan-build-test-quality`, `quality`) accepts `--suite <name>` to override it for one run — `spf list` marks which chains this applies to with `(--suite overrides)`. `simple-sdlc`'s suite is not overridable this way; passing `--suite` to it is rejected rather than silently ignored.
+
 `--adw-id` is optional everywhere. Omit it and a fresh id is minted and printed. Supply it and the run joins that session — same session directory, each agent **resumes its existing context window** instead of starting cold. That's how you chain runs:
 
 ```bash
@@ -239,6 +276,36 @@ spf plan "add a /health endpoint"                        # prints adw_id a1b2c3d
 spf build-test "implement the plan" --adw-id a1b2c3d4
 ```
 
+### Repo-local chains
+
+Every chain above is built in. A target repo can also compose its own out of
+the same step factories, with zero forking and zero build step, by dropping a
+file in `.spf/chains/*.yaml` — `spf init` scaffolds `.spf/chains/example.yaml`
+(fully commented out) showing the shape:
+
+```yaml
+# .spf/chains/ship-it.yaml — spf ship-it "<prompt>" / spf run ship-it "<prompt>"
+name: ship-it
+describe: plan, build, test, land — with our own reviewer in the loop
+steps:
+  - step: request
+  - step: plan
+    owner: architect
+  - step: build
+    extraGates: [jsonParses]   # additive only — a step's built-in gates can never be removed
+  - step: fixLoop
+    suite: test
+  - step: commit
+    onlyIfAccepted: true
+```
+
+It shows up in `spf list`/`spf doctor` exactly like a built-in, and runs on
+the identical `stepChain()` driver — there is no second interpreter. The full
+step vocabulary, the gate rules, and the `spf watch` main-anchor divergence
+(a chain edited on an issue branch is *not* what an in-flight `spf watch` run
+uses) are documented in the installed skill's "Repo-local chains" section
+(`.claude/skills/spf/cookbooks/authoring_chains.md`, after `spf init`).
+
 ---
 
 ## `spf watch`
@@ -278,6 +345,29 @@ watch:
     project_key: PROJ
 ```
 
+```yaml
+# .spf/spf.config.yaml — GitHub issues + Bitbucket PRs, in TWO DIFFERENT repos
+watch:
+  issue_provider: github
+  code_host: bitbucket
+  repo: workspace/repo_slug     # Bitbucket's repo — the CODE HOST always reads plain `repo`
+  issue_repo: owner/name        # GitHub's repo — only needed here, where issue tracker != code host
+  label_prefix: spf             # polls GitHub issues labeled spf:ready
+  chain: plan-build-test
+  base_branch: main
+```
+
+`repo` always names the code host's own repo; `issue_repo` overrides it for
+the issue-tracker side. This only matters for `issue_provider: github` +
+`code_host: bitbucket` — the one combination where they're genuinely
+different repos in different systems, not the same repo worn two ways
+(`github`+`github` is one repo by construction; `issue_provider: jira` never
+reads `repo` at all, so it's never ambiguous). Leave `issue_repo` unset
+everywhere else. `spf doctor` flags this specific combination when
+`issue_repo` is missing, since the silent failure mode — polling GitHub with
+the Bitbucket identifier — finds no matching issues and looks exactly like
+nothing being configured at all.
+
 ```bash
 spf watch init                # idempotently seed tracker state (no-op for Jira — see below); run this first
 spf watch                    # foreground daemon; Ctrl-C drains in-flight claims first
@@ -422,6 +512,34 @@ genuinely informative, just worth expecting.
 Full field reference: `spf install-skill`'s installed skill
 (`references/config.md`).
 
+## Observability
+
+Every run produces a complete trace: all events, phases, agent calls, and tool invocations stream into SQLite as they happen. The local trace stays the source of truth — prompts, envelopes, tool arguments, and your source code never leave the machine. Token counts and costs ride alongside.
+
+```bash
+spf ui                           # browser-based visualizer over the trace
+spf events <adw_id> --follow    # live event stream, tailable
+```
+
+The default export is SQLite only (`.spf/data/spf.db`). Optionally, you can export **spans only** (phase/agent/tool timing and allowlisted metadata) to an OpenTelemetry collector for integration with a trace UI or observability platform:
+
+```yaml
+observability:
+  db: .spf/data/spf.db
+  poll_ms: 500
+  otel:
+    endpoint: https://your-otel-collector/v1/traces
+    service_name: spf                    # optional; default "spf"
+    headers:                             # optional; e.g. auth headers
+      Authorization: Bearer ...
+```
+
+OTEL export is **explicit config only** — an unrelated shell variable cannot become a data-egress switch. OTEL is strictly a spans-only export: each phase is a span with child spans for agent calls and tool calls, annotated with phase status, agent model, token/cost counts, and gate results. This export never blocks a run: if the collector is slow or unreachable, SPF continues normally and logs a single line per run when export fails (not one per batch), and reports the number of dropped spans on the final flush as `spf.otel.dropped_spans` for the backend to surface. The complete trace stays in SQLite regardless.
+
+**Attribute allowlist**: only phase name/kind/owner/status, chain name, adw_id, agent name/model/coding_agent, gate name + passed + violation count, token counts and cost, and durations. Prompts, envelopes, tool arguments, and your source code never leave — that guarantee is enforced in code, not just in documentation.
+
+See `assets/skill/references/config.md`'s `observability` section for the full field reference.
+
 ## What's in this repo
 
 ```

package/assets/defaults/spf.config.yaml

@@ -34,6 +34,12 @@ defaults:
 observability:
   db: .spf/data/spf.db               # tracer writes here directly; the UI polls it
   poll_ms: 500                     # visualizer live-poll cadence
+  # Optional OpenTelemetry spans export (explicit config only; no ambient env activation)
+  # otel:
+  #   endpoint: https://your-otel-collector/v1/traces
+  #   service_name: spf                    # optional; default "spf"
+  #   headers:                             # optional; e.g. auth headers
+  #     Authorization: Bearer ...
 
 # No default quality checks or suites are shipped — an unconfigured chain
 # that needs one fails loudly at agents.validate() time (before anything

package/assets/prompts/reviewer/system.md

@@ -13,4 +13,4 @@ Confirm that what was built is what was asked for. This is not testing.
 - 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 — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `git`); 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. `error` or `not found` inside passing output is text, not a failure.
+- 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. `error` or `not found` inside passing output is text, not a failure.

package/assets/skill/SKILL.md

@@ -45,6 +45,7 @@ phases`/`spf events` exist so nobody has to guess the schema again).
 | "add/retune an agent or model" | `roster.md` |
 | "add a chain / a phase / an output type / a gate" | `authoring_chains.md` |
 | "what is SPF" | `spf_overview.md` |
+| "fold a third-party review tool's findings into the reviewer" | `cookbooks/ocr_reviewer.md` |
 | envelope/gate/session contract | `references/handoff.md` |
 | trace schema, spend vs. context | `references/observability.md` |
 | config field reference | `references/config.md` |

package/assets/skill/cookbooks/authoring_chains.md

@@ -1,13 +1,86 @@
 # Authoring Chains
 
 Composing a new chain, extending an existing one, and adding the engine
-primitives a chain needs (an output type, a gate, a step) are one skill with
-three doors. All three live in `src/` inside the SPF package itself — there
-is no per-repo copy to edit. If you need to change engine behavior for a
-specific target repo without forking the package, that's `spf eject` (prints
-the path to the installed package's `src/` for you to copy and load from your
-own `.spf/` — engine-level changes are the one thing `.spf/` config can't
-express).
+primitives a chain needs (an output type, a gate, a step) is one skill with
+four doors. Engine primitives (a new gate, a new envelope type, a modified
+phase primitive) live in `src/` inside the SPF package itself — those do
+require forking the package, because they change what every repo's chains
+can mean. But COMPOSING a chain out of the existing step factories does not:
+that's what a repo-local chain (below) is for. Read that section first if
+you just want your own chain in your own repo — reach for the rest of this
+document only once you've decided you need a new primitive.
+
+## Repo-local chains (`.spf/chains/*.yaml`)
+
+The zero-fork door: a `.spf/chains/*.yaml` file in a target repo names
+existing step factories from `spf`'s own `src/chains/steps.ts` and passes
+them params — never imports or runs code from the target repo. `spf init`
+scaffolds `.spf/chains/example.yaml`, fully commented out, showing the shape.
+
+```yaml
+# .spf/chains/ship-it.yaml — spf ship-it "<prompt>" / spf run ship-it "<prompt>"
+name: ship-it
+describe: plan, build, test, land — with our own reviewer in the loop
+steps:
+  - step: request               # every chain opens with this
+  - step: plan
+    owner: architect             # any agent named in spf.config.yaml
+  - step: build
+    retries: 2
+    extraGates: [jsonParses]     # additive — see below
+  - step: fixLoop
+    suite: test
+  - step: commit
+    onlyIfAccepted: true
+```
+
+**Shape.** One file, one chain — the filename is a handle a problem can point
+at. `steps` is a flat list; each entry names a `step:` and its params sit as
+FLAT SIBLINGS of `step:` — never nested under a `params:` key. Param names are
+exactly the step factory's `opts` keys, camelCase (`extraGates`, `fixExtraGates`,
+`onlyIfAccepted`, ...). An unknown param, an unknown step, or a param of the
+wrong type is a load-time problem naming the step index and what's allowed —
+never a silently-ignored typo and never a runtime surprise.
+
+**Step vocabulary** (`repo_chains.STEP_NAMES`) — the same factories the table
+in Step 2 below documents: `request`, `plan`, `build`, `scout`, `promptOnly`,
+`qualityCheck`, `fixLoop`, `reviseLoop`, `commit`, `changes`, `document`,
+`refine`, `publishIssues`.
+
+**Gates are additive only, and per-step.** A step's built-in gates
+(`diffMatchesClaims` on `build`, `verdictConsistent` on `reviseLoop`'s review
+phase, ...) are non-removable — there is no `gates:` param that replaces
+them, and there must never be one (see `GATE_ALLOWLIST`'s comment in
+`steps.ts` for why: the first thing anyone deletes under deadline pressure is
+the gate that keeps failing). `extraGates` can only ADD from an explicit
+allowlist SCOPED to what that param's envelope actually supports:
+`artifactsExist`/`filesNonEmpty`/`jsonParses` anywhere (they only read
+`envelope.artifacts`, present on every envelope); `diffMatchesClaims` only on
+a param whose phase produces a `BuildOutput` (`build.extraGates`,
+`fixLoop.fixExtraGates`, `reviseLoop.reviseExtraGates`); `verdictConsistent`
+only on `reviseLoop.extraGates` (the review phase, a `ReviewOutput`). Naming
+a gate outside its param's list is a load problem, not a chain that loads
+clean and then fails (or vacuously passes) its gate on every run.
+
+**Names are guarded.** A chain name must be lowercase letters/digits/`._-`
+(it's typed on the command line). It cannot collide with an `spf` subcommand
+(`run`, `list`, `init`, `watch`, ...) — `spf watch` would always run the
+daemon, never a same-named chain. Two repo-chain files can't claim the same
+`name` either: the trace's `chain_name` column has to keep meaning one thing.
+
+**The `spf watch` divergence.** `spf watch` registers `.spf/chains/` from the
+MAIN repo anchor ONCE, at daemon start — not per-issue, not per-worktree. A
+chain file edited on an issue branch (inside the worktree `spf watch` checks
+that branch out into) is NOT what runs for that issue; the daemon keeps using
+whatever `.spf/chains/` looked like when it started. This is deliberate: the
+disposer stays the OPERATOR's, never the branch's, which is exactly what
+keeps an agent from rewriting its own quality gate mid-run by editing a chain
+file as part of the change it's making.
+
+Everything below this section is about the OTHER three doors: designing a
+brand-new built-in chain, adding a step to the vocabulary above, or adding an
+engine primitive (gate/envelope type/phase primitive) — none of which a
+target repo needs, or can do, on its own.
 
 ## Step 1 — design the chain before writing code
 
@@ -24,6 +97,16 @@ the step list itself — see Step 2 — so it can't drift from what actually run
 | test | code | quality | — | (suite pass/fail is the phase's own result) |
 | commit | code | git | — | — |
 
+If you need to change engine behavior for a specific target repo without forking
+the package, that's `spf eject`. It copies the installed engine's compiled
+artifacts (`dist/core/` and `dist/chains/`) out to `.spf/engine/` for reference
+or reading — but understand that these files are **not wired into any spf
+command**: editing them changes nothing about how spf itself runs. Engine-level
+changes (a new gate, a new envelope type, a modified phase primitive) have no
+config surface by design, because the codebase is a single shared engine all
+repos trust to sequence their work the same way. If you are genuinely changing
+the engine semantics, you are forking the package itself, not ejecting a copy.
+
 **Ownership rules**, non-negotiable:
 
 - **`engineer`** phases capture input only — no agent, no code decision.

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