@gr8ful/spf 0.3.0 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ Everyone can get an agent to write code once. Almost nobody gets the same result
 npm i -g @gr8ful/spf
 ```
 
-No Bun, no separate coding-agent binary to install first, no template stamped into your repo. `spf` ships with a packaged default agent roster and default prompts — it runs against any repo with zero setup, and only writes files into that repo if you explicitly ask it to (`spf init`, `spf install-skill`).
+No Bun, no separate coding-agent binary to install first, no template stamped into your repo. `spf` ships with a packaged default agent roster and default prompts — it runs against any repo with zero setup, and only writes files into that repo if you explicitly ask it to (`spf init`, which also installs the Claude Code skill unless you pass `--no-skills`; `spf install-skill` does just the skill by hand).
 
 ```bash
 cd your-repo
@@ -38,6 +38,8 @@ On a real terminal, `spf init` asks a short interview — which coding agent (`c
 
 Without an interview, `spf init` writes the same small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field. `--template <name>` writes a real, filled-in config instead of the commented-out starter — every packaged template's name prints after `spf init` runs, and the same files live in [`assets/templates/`](assets/templates/) to browse directly. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
 
+Every `spf init` run — interview or not — also installs the repo-local Claude Code skill (`.claude/skills/spf`), the same work `spf install-skill` does by hand: pass `--no-skills` to skip it. It's idempotent (a no-op once the skill is already current, and writes a `.new` sibling instead of overwriting a file you've locally edited), so re-running `spf init` never clobbers anything there. `spf install-skill --user` (installing to `~/.claude/skills/spf` instead) is still its own separate invocation.
+
 ### Local development
 
 Working from a clone instead of the published package:
@@ -108,7 +110,7 @@ agents:
     writes: [specs/]                 # the plan is all it may leave in the repo
 ```
 
-Five starter agents ship in the box: `planner`, `builder`, `scout` (read-only recon), `reviewer`, and `documenter`. There is no tester, because running a suite is a known command and therefore code, not an agent's job.
+Six starter agents ship in the box: `planner`, `builder`, `scout` (read-only recon), `refiner` (decomposes a product spec for `spf watch`'s refine lane — see "`spf watch`" below), `reviewer`, and `documenter`. There is no tester, because running a suite is a known command and therefore code, not an agent's job.
 
 Every agent gets its own model, thinking level, prompts, and tools. Give the planner a frontier model and the builder a cheap fast one. Give the reviewer no ability to write code at all.
 
@@ -118,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
 
@@ -126,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.
 
 ---
 
@@ -212,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 |
@@ -230,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
@@ -237,12 +276,44 @@ 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`
 
 Polls an issue tracker for issues labeled `<prefix>:ready`, runs a configured chain against each in its own git worktree, opens a PR against a code host, and tracks it through to merged or blocked — driving the same chains above rather than reimplementing an SDLC. Labels are the whole state machine: `ready → working → review → done`/`blocked`.
 
+A second, optional lane (`watch.refine`, off by default) decomposes a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues instead — see "Refining specs" below.
+
 The tracker (`issue_provider`) and the code host (`code_host`) are independent config choices, not one bundled "provider" — a tracker and a host are independent choices in practice (Jira issues against a Bitbucket repo is a real setup). Supported today: `issue_provider: github | jira`, `code_host: github | bitbucket` — any combination works, including Jira+GitHub or GitHub-issues+Bitbucket.
 
 The easiest way into any of this is `spf init`'s interview: it asks whether to enable `spf watch`, which tracker and code host, and collects exactly the env vars that combination needs (below) straight into `.env` — no hand-editing YAML or hunting down which credential pair a given combination wants.
@@ -274,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
@@ -283,15 +377,61 @@ spf watch --dry-run          # log intended claims/transitions, mutate nothing
 
 No GitHub App, no webhook, no Jira/Bitbucket app install — it's a plain REST poll against whichever combination is configured, same philosophy as the trace db's own polling contract. See [`assets/templates/`](assets/templates/) for full worked configs (also usable directly via `spf init --template <name>`), and `spf install-skill`'s installed skill (`roster.md`, `references/config.md`) for the field-by-field reference.
 
+### Refining specs (`watch.refine`)
+
+A product spec isn't individually workable — it needs to become a feature,
+broken down into user stories and bugs, before the build lane above has
+anything to claim. `watch.refine` is a second lane over the same poll loop
+that does exactly that: it polls `<prefix>:spec-ready`, runs a decomposition
+chain (`refine` by default) against the spec in its own worktree, and
+publishes what it produces as real tracker issues — a feature/epic container
+plus story/bug/task leaves, linked via GitHub's native sub-issue hierarchy.
+
+```yaml
+watch:
+  issue_provider: github    # required — issue authoring isn't implemented for Jira yet
+  repo: owner/name
+  refine:
+    enabled: true
+    chain: refine           # any chain that ends in steps.publishIssues()
+    concurrency: 1          # this lane's own budget, independent of watch.concurrency
+```
+
+Every generated issue carries a `<prefix>:type:epic|feature|story|bug|task`
+label. A container (a feature/epic — something else names it as `parent`)
+gets only that label; a leaf additionally gets `<prefix>:refined` — **never**
+`<prefix>:ready`. Promoting a leaf to `<prefix>:ready` is a deliberate human
+decision: the refine lane never auto-promotes anything, so a spec fanning out
+into twenty stories doesn't turn into twenty unattended chain runs and twenty
+PRs with nobody having looked at the breakdown first. Once you do promote a
+leaf, the existing build lane picks it up completely unchanged.
+
+The spec issue itself gets a `spec-ready → refining → done`/`blocked`
+lifecycle, same shape as the build lane, and a summary comment listing every
+issue it created. Try it by hand first, against a real spec, before turning
+on the daemon:
+
+```bash
+spf refine "<spec text or path/to/spec.md>" --issue 42   # --issue renders a "## Parent: #42" back-reference
+```
+
+`spf watch init` seeds the type labels alongside the state ones. This lane's
+prompt (`assets/prompts/refiner/`) is adapted from a "tracer-bullet ticket"
+decomposition skill — vertical slices, a `blocked_by` dependency graph, and
+an expand/migrate/contract sequence for wide mechanical refactors — with a
+gate (`gates.refinementWellFormed`) added on top to enforce the
+container/leaf shape that skill left as prose convention rather than a
+checked rule.
+
 ### GitHub (`issue_provider: github` and/or `code_host: github`)
 
 ```bash
 export GITHUB_TOKEN=...   # classic PAT; spf doctor checks it's set
 ```
 
-`spf watch init` seeds `<prefix>:ready`/`working`/`review`/`done`/`blocked` labels with a color and description each — safe to re-run any time (creates what's missing, corrects any that drifted, leaves the rest alone).
+`spf watch init` seeds `<prefix>:ready`/`working`/`review`/`done`/`blocked`/`spec-ready`/`refining`/`refined` labels, plus `<prefix>:type:epic`/`feature`/`story`/`bug`/`task` (used by the refine lane whether or not it's enabled), each with a color and description — safe to re-run any time (creates what's missing, corrects any that drifted, leaves the rest alone).
 
-A **classic** PAT (fine-grained tokens use different permission names — not covered here), scoped to the minimum that covers every call `spf watch`/`spf watch init` makes on GitHub: creating/editing labels, reading and labeling issues, posting comments, opening PRs, and reading PR/check-run status.
+A **classic** PAT (fine-grained tokens use different permission names — not covered here), scoped to the minimum that covers every call `spf watch`/`spf watch init` makes on GitHub: creating/editing labels, reading and labeling issues, posting comments, opening PRs, reading PR/check-run status, and — with `watch.refine.enabled` — creating issues and linking them via the sub-issues API. All of it is already covered by `repo`/`public_repo`; refine needs no additional scope.
 
 | Target repo | Scope | Covers |
 |---|---|---|
@@ -372,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
 
 ```
@@ -385,7 +553,7 @@ super-portable-software-factory/
 └── assets/
     ├── defaults/    # the packaged default roster
     ├── prompts/     # default system.md + user.md per starter agent
-    └── skill/       # an optional Claude Code skill — `spf install-skill` to use it
+    └── skill/       # a Claude Code skill — `spf init` installs it by default (`--no-skills` to opt out), or `spf install-skill` by hand
 ```
 
 There's no template stamped into your repo. Everything above ships inside the installed npm package; a repo you run `spf` against only ever gains a `.spf/` directory, and only if you ask for one.

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
@@ -101,6 +107,22 @@ agents:
   # No tester agent: running the suite is a known command, so it is a kind="code"
   # phase over core/quality.ts. See SKILL.md hard rule 8.
 
+  - name: refiner
+    thinking: high
+    color: "#34d399"
+    purpose: Decompose a product spec into a feature/story-or-bug tree of vertical slices; change nothing.
+    prompt_engineering:
+      system: refiner/system.md
+      user: refiner/user.md
+    writes: []                     # read-only w.r.t. the repo; refine_plan.md lands in context_handoff_dir, not here
+    tools:                         # full recon; write only for refine_plan.md, no edit
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+
   - name: reviewer
     model: openai/gpt-5.6-terra
     thinking: high

package/assets/prompts/refiner/system.md

@@ -0,0 +1,53 @@
+# Refiner Agent
+
+## Purpose
+
+Decompose a product spec into a feature/story-or-bug tree of vertical slices the factory can build one at a time. Change nothing.
+
+## Instructions
+
+- Read-only: explore the codebase to ground the decomposition, never write to it.
+- Use the project's domain glossary vocabulary in every title and description, if the repo has one. Respect existing ADRs in any area you're touching — a slice that would contradict one is a slice to reconsider, not to write down anyway.
+- You inherit the operator's shell environment — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `pytest`); 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.
+- Write your working notes to `<context_handoff_dir>/refine_plan.md` before emitting your Report JSON.
+
+## The tree
+
+Every node you produce is either a **container** (`epic` or `feature` — exists only to group other nodes; never itself a unit of work) or a **leaf** (`story`, `bug`, or `task` — the independently workable unit). A node is a container exactly when some other node names it as `parent`; everything else is a leaf. At least one leaf is required — a decomposition that is all containers has produced nothing to build.
+
+Emit a **flat list**, not nested JSON: each node names its `parent` by another node's `key`, or leaves `parent` empty for a top-level feature/epic. A flat list with parent pointers is far more reliable to produce correctly than a recursive tree, and it's what lets `blocked_by` point at any other node — sibling or not.
+
+## Vertical-slice rules (for every leaf)
+
+- Each slice cuts a narrow but COMPLETE path through every layer it touches (schema, API, UI, tests) — vertical, never a horizontal slice of one layer.
+- A completed slice is demoable or verifiable on its own.
+- Size each slice to fit in a single fresh context window for the builder that will implement it — when in doubt, split.
+- Any prefactoring the spec implies should be its own slice, sequenced first via `blocked_by`, not folded into the first "real" slice.
+
+## Dependencies: a DAG, not a tree
+
+Give every node its `blocked_by`: the other nodes' `key`s that must land first. A node with no blockers can start immediately — leave `blocked_by` empty rather than inventing an order where none is required. The factory works the **frontier**: any leaf whose blockers are all done. For a purely linear chain that means top to bottom; for anything wider, only real dependencies belong in `blocked_by` — an artificial one just stalls the frontier.
+
+## Wide refactors — the one exception to vertical slicing
+
+A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose blast radius fans across the codebase, so a single edit breaks thousands of call sites and no vertical slice can land green on its own. Sequence it as **expand -> migrate -> contract**, each stage its own leaf(s):
+
+- **expand**: add the new form beside the old so nothing breaks yet.
+- **migrate**: batch the call sites by blast radius (per package, per directory) — each batch its own leaf, `blocked_by` the expand leaf. CI stays green throughout, because the old form still exists alongside the new one.
+- **contract**: delete the old form — `blocked_by` every migrate batch.
+
+If even a batch can't stay green alone, keep the same three-stage sequence but let the migrate batches share an integration branch that all block a final integrate-and-verify leaf — green is promised only there, not at every batch.
+
+## Writing titles and bodies
+
+- Title and body describe end-to-end behavior from the user's (or the next engineer's) perspective — not a layer-by-layer implementation list.
+- Avoid specific file paths or code snippets; they go stale fast. Exception: if your exploration surfaced a snippet that encodes a decision more precisely than prose can (a state machine, a reducer, a schema, a type shape), inline it and note briefly where it came from. Trim to the decision-rich part, not a working demo.
+- Do **not** write a "Blocked by" or "Parent" section into `body` yourself — the harness renders both from `blocked_by`/the source issue automatically, with real issue numbers once everything is created. Writing your own would go stale or duplicate the real one.
+- `body` should read as `## What to build` followed by `## Acceptance criteria` (a checklist).
+
+## Subagents
+
+`subagent_create` / `_continue` / `_list` / `_remove` fan out exploration — one per subsystem or open question — when the spec spans more than you can read cheaply. Give each a self-contained task, hold it to read-only work, and omit `model`.
+
+They run in the background. **Wait for every one you spawned to report before writing `refine_plan.md` or your Report JSON.** Skip them when a few reads would do.

package/assets/prompts/refiner/user.md

@@ -0,0 +1,70 @@
+# Refine Task
+
+## Variables
+
+### prompt
+
+{{prompt}}
+
+### previous_envelope
+
+{{previous_envelope}}
+
+### context_handoff_dir
+
+{{context_handoff_dir}}
+
+## Task
+
+Decompose the product spec in `prompt` into a feature/story-or-bug tree, following every rule in your system instructions (vertical slices, the `blocked_by` DAG, expand/migrate/contract for wide refactors, no "Blocked by"/"Parent" text of your own).
+
+1. Explore the codebase only as far as you need to ground the decomposition in what actually exists.
+2. Write your working notes to `<context_handoff_dir>/refine_plan.md`.
+3. Emit your `Report` JSON, declaring that one file in `artifacts`.
+
+## Report
+
+Respond with ONLY valid JSON matching `RefineOutput` — no prose before or after:
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence: how many features and how many leaves, and the shape of the dependency chain>",
+  "artifacts": ["<context_handoff_dir>/refine_plan.md"],
+  "notes_for_next_agent": "<anything the publish step or a human reviewer should know>",
+  "issues": [
+    {
+      "key": "F1",
+      "kind": "feature",
+      "title": "<feature title>",
+      "body": "## What to build\n\n<end-to-end behavior this feature covers>\n\n## Acceptance criteria\n\n- [ ] <criterion>",
+      "parent": "",
+      "blocked_by": []
+    },
+    {
+      "key": "S1",
+      "kind": "story",
+      "title": "<leaf title>",
+      "body": "## What to build\n\n<end-to-end behavior from the user's perspective>\n\n## Acceptance criteria\n\n- [ ] <criterion>\n- [ ] <criterion>",
+      "parent": "F1",
+      "blocked_by": []
+    },
+    {
+      "key": "S2",
+      "kind": "bug",
+      "title": "<leaf title>",
+      "body": "## What to build\n\n<the fix, described end-to-end>\n\n## Acceptance criteria\n\n- [ ] <criterion>",
+      "parent": "F1",
+      "blocked_by": ["S1"]
+    }
+  ]
+}
+```
+
+Rules on the shape (enforced by a gate — a violation sends this back to you as a correction, not a silent acceptance):
+
+- `key` is your own local id for this run, unique within `issues` — never a real tracker id.
+- A node is a **container** (`kind: "epic"` or `"feature"`) exactly when some other node names it in `parent`; every other node is a **leaf** (`kind: "story"`, `"bug"`, or `"task"`) and must not be a container. At least one leaf is required.
+- `parent` is another node's `key`, or `""` for a top-level feature/epic.
+- `blocked_by` is a list of other nodes' `key`s — real dependencies only, and no cycles (through `parent` or `blocked_by`, or both together).
+- `body` is `## What to build` then `## Acceptance criteria` only — no "Blocked by" or "Parent" section; those are rendered for you once every node has a real issue number.

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.