@gr8ful/spf 0.14.0 → 0.16.0

package/README.md

@@ -36,7 +36,7 @@ spf init --template ts-cc      # or start from a packaged, ready-to-run template
 spf list                       # every chain this install knows, its phases, what it needs
 ```
 
-On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code` or `flue`) and model (optionally customized per agent instead of one model for the whole roster), which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host, and whether to push notifications to Slack/Teams/a webhook — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
+On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code`, `flue`, or `opencode`) and model (optionally customized per agent instead of one model for the whole roster), which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host, and whether to push notifications to Slack/Teams/a webhook — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
 
 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.
 
@@ -175,6 +175,14 @@ env:
 
 Applied to `process.env` before any command runs. A plain value commits as literal text; `${VAR}` interpolates from whatever's already in `process.env` at that point (the real shell, or `.env`, both of which load first) — so a real secret can live in `.env` (gitignored) and be referenced here without ever being written into this file. An already-set `process.env` value always wins over `env:`'s — `spf.config.yaml` supplies the default, a real export still overrides it per machine/session. A `${VAR}` reference to something that's genuinely unset fails loudly at startup, naming the missing variable, rather than silently interpolating to an empty string.
 
+### A third backend: opencode
+
+Set `coding_agent: opencode` on any agent (or in `defaults`) to run it on your own installed [OpenCode](https://opencode.ai) CLI instead of Flue or Claude Code — install it with `npm install -g opencode-ai` (the package is `opencode-ai`; the binary it puts on `PATH` is `opencode`). `spf doctor` checks that `opencode` resolves on `PATH` and that `~/.local/share/opencode/auth.json` exists, the same informational, not-enforced posture as its `claude_code` check for `ANTHROPIC_API_KEY`. Model names follow the same `provider/model-id` shape Flue uses (e.g. `anthropic/claude-sonnet-4-20250514`, `ollama/qwen3-coder:30b`) — not Claude Code's own bare-alias vocabulary (`sonnet`, `opus`, ...); everything else — `tools`, `writes`, `thinking` — stays the same shape.
+
+Authentication is handled entirely outside spf: run `opencode auth login` once (interactive), or `opencode auth list` to check non-interactively what's already configured. spf never drives this itself.
+
+Like `claude_code`, routing the `opencode` command through a wrapper or launcher uses the equivalent `SPF_CLAUDE_CMD`-style env var for this backend, with the same `{model}` token-substitution mechanic — see [Declarative env vars](#declarative-env-vars) above and check `opencode --help` for the flags a wrapper needs to forward.
+
 ### 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/...`:
@@ -766,9 +774,24 @@ A **classic** PAT (fine-grained tokens use different permission names — not co
 | Private | `repo` | Everything above, full read/write |
 | Public only | `public_repo` | The same, restricted to public repos |
 
-**Do not grant the `project` scope.** It's a separate, unrelated permission for GitHub Projects (classic/org/user boards) — `spf watch` doesn't touch Projects at all, so granting it would just be more access than this tool ever uses.
+There's no dedicated "issues" or "pull requests" scope on classic PATs — GitHub bundles both into `repo`/`public_repo`, which is why that table covers everything by default.
+
+Native GitHub Projects v2 board status (the board's Status column) is a separate, optional layer on top, off by default — labels alone don't move it, so an issue's Status sits wherever it started unless you opt in with `watch.github.project_number` and `watch.github.status_map`:
+
+```yaml
+watch:
+  issue_provider: github
+  repo: owner/name
+  github:
+    project_number: 3   # owner's Projects v2 board number — see the board's own URL
+    status_map:          # optional — unset by default, per state
+      ready: Todo
+      working: In Progress
+      review: In Review
+      done: Done
+```
 
-There's no dedicated "issues" or "pull requests" scope on classic PATs — GitHub bundles both into `repo`/`public_repo`, which is why that's the whole table.
+Only the states you map are touched; an unmapped state keeps today's label-only behavior, and `project_number: 0` (the default) disables sync outright regardless of `status_map`. This needs the **`project`** scope in addition to `repo`/`public_repo` — Projects v2 has no REST API at all, only GraphQL, and that surface is gated by its own scope; grant it only if you're using `status_map`. A configured option name with no matching Status option (or a rejected mutation) is logged and skipped, never thrown — the label update is what `spf watch` actually depends on; status sync is a best-effort convenience on top of it. `spf watch init` and `spf watch`'s own startup check both validate a configured `status_map` against the real project's Status options, read-only, and exit non-zero on a mismatch, the same way Jira's `issue_types` is validated below.
 
 ### Jira (`issue_provider: jira`)
 
@@ -777,9 +800,26 @@ export JIRA_EMAIL=you@example.com
 export JIRA_API_TOKEN=...   # id.atlassian.com -> Security -> API tokens
 ```
 
-State is modeled as Jira **labels** (`<prefix>:ready`, etc.), mirroring GitHub exactly, rather than native workflow status transitions — the latter would need per-project transition-id mapping, since workflows vary by project/scheme; labels work identically everywhere with zero per-project setup. One caveat: colons are a legal Jira label character and JQL matches on them fine, but they won't show up in Jira's own label autocomplete UI — cosmetic only.
+State is modeled as Jira **labels** (`<prefix>:ready`, etc.), mirroring GitHub exactly — labels are spf's actual state machine and always get written unconditionally, with zero per-project setup. One caveat: colons are a legal Jira label character and JQL matches on them fine, but they won't show up in Jira's own label autocomplete UI — cosmetic only.
 
-`spf watch init` still doesn't create any labels here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it reports the labels this run will use. But with `watch.refine.enabled`, it now also validates `watch.jira.issue_types` against the real project's issue types, read-only, and exits non-zero on a mismatch — see "Refining specs" above.
+Native Jira workflow status (the board's Status column) is a separate, optional layer on top, off by default — labels alone don't move it, so an issue's Status sits wherever it started unless you opt in with `watch.jira.status_map`:
+
+```yaml
+watch:
+  issue_provider: jira
+  jira:
+    base_url: https://your-domain.atlassian.net
+    project_key: PROJ
+    status_map:        # optional — unset by default, per state
+      ready: To Do
+      working: In Progress
+      review: In Review
+      done: Done
+```
+
+Only the states you map are touched; an unmapped state keeps today's label-only behavior. This is opt-in rather than automatic because Jira workflows vary by project/scheme — status names and which transitions are reachable from where isn't something spf can assume, unlike labels. A configured name with no reachable transition (or a rejected one) is logged and skipped, never thrown — the label update is what `spf watch` actually depends on; status sync is a best-effort convenience on top of it.
+
+`spf watch init` still doesn't create any labels here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it reports the labels this run will use. With `watch.refine.enabled`, it also validates `watch.jira.issue_types` against the real project's issue types, read-only, and exits non-zero on a mismatch — see "Refining specs" above. Independent of `refine.enabled`, if `watch.jira.status_map` has any entry configured, both `spf watch init` and `spf watch`'s own startup check validate it against the real project's statuses the same way, and exit non-zero on a mismatch.
 
 ### Bitbucket (`code_host: bitbucket`)
 
@@ -869,14 +909,16 @@ Full field reference: `spf install-skill`'s installed skill
 
 ## 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.
+Every run produces a complete trace: all events, phases, agent calls, and tool invocations stream into SQLite as they happen. By default the trace is local-only and 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:
+The default backend is local SQLite (`.spf/data/spf.db`) — nothing leaves the machine. `observability.db` can instead be pointed at a remote Cloudflare D1 database (`{kind: d1, database_id, ...}`, offered as an `spf init` advanced option): in that mode the **complete trace** — the raw request text, tool arguments and results, envelope payloads, and gate violation details, not just spans or metadata — is written to Cloudflare over the network on every run, and the local-only guarantee above does not hold. Pick D1 only when you're comfortable with your trace data (including prompts and tool arguments) leaving the machine; stay on the default SQLite backend otherwise. See `assets/skill/references/observability.md`'s D1 section for what's sent and how the backend is selected.
+
+Separately, and orthogonally to which trace-db backend you choose, you can export **spans only** (phase/agent/tool timing and allowlisted metadata, never prompts or tool arguments) to an OpenTelemetry collector for integration with a trace UI or observability platform:
 
 ```yaml
 observability:
@@ -889,9 +931,9 @@ observability:
       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.
+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 the trace db regardless of OTEL export — but, per above, the trace db itself is remote Cloudflare D1, not local SQLite, when `observability.db` is configured for `kind: d1`.
 
-**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.
+**OTEL 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 *via OTEL* — that guarantee is enforced in code, not just in documentation, and it holds regardless of trace-db backend. It is separate from the trace-db egress question above: a `kind: d1` trace db ships the full trace (prompts, tool arguments, envelope payloads) to Cloudflare even with OTEL left unconfigured.
 
 See `assets/skill/references/config.md`'s `observability` section for the full field reference.
 

package/assets/skill/references/config.md

@@ -70,8 +70,8 @@ agents:
 
 | Field | Type | Meaning |
 |---|---|---|
-| `coding_agent` | `"flue"` \| `"claude_code"` | Which backend runs the agent. Default `flue`. `claude_code` shells out to your own installed `claude` CLI — `spf doctor` checks it's on `PATH`. |
-| `model` | string | Vocabulary depends on `coding_agent`: Flue wants `provider/model-id`; Claude Code wants its own bare alias/full name (`sonnet`, `claude-sonnet-5`, ...). Default `google/gemini-3.6-flash`. |
+| `coding_agent` | `"flue"` \| `"claude_code"` \| `"opencode"` | Which backend runs the agent. Default `flue`. `claude_code` shells out to your own installed `claude` CLI — `spf doctor` checks it's on `PATH`. `opencode` shells out to your own installed `opencode` CLI (`npm install -g opencode-ai`) — `spf doctor` checks it's on `PATH` and that `~/.local/share/opencode/auth.json` exists. |
+| `model` | string | Vocabulary depends on `coding_agent`: Flue and opencode want `provider/model-id`; Claude Code wants its own bare alias/full name (`sonnet`, `claude-sonnet-5`, ...). Default `google/gemini-3.6-flash`. |
 | `thinking` | enum | `off\|minimal\|low\|medium\|high\|xhigh\|max`. Default `medium`. On a `claude_code` agent this maps to `--effort` (`off`/`minimal` both floor to Claude Code's own minimum — it has no true "disabled" level for a headless run). |
 | `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(). |
@@ -108,7 +108,7 @@ the two runs' cost/tokens/gates together.
 
 | Field | Type | Meaning |
 |---|---|---|
-| `db` | path | The trace sqlite db. Default `.spf/data/spf.db`. |
+| `db` | path \| `{kind: sqlite, path?}` \| `{kind: d1, database_id, account_id_env?, api_token_env?}` | Where the trace db lives. A bare string (or the equivalent spelled-out `{kind: sqlite, ...}`) is a repo-relative local sqlite path, default `.spf/data/spf.db`. `{kind: d1, ...}` points at a remote Cloudflare D1 database instead — `database_id` is required; `account_id_env`/`api_token_env` default to `CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_API_TOKEN` (the same env vars the `cloudflare` model provider reads), naming the env vars to read the credentials from, never the credentials themselves. **Egress**: `kind: d1` sends the complete trace — raw request text, tool arguments/results, envelope payloads, gate violation details — to Cloudflare's D1 HTTP API on every run; `kind: sqlite` (the default) never leaves the machine. See `observability.md`'s "Two stores, one truth" and "D1 ships the complete trace off-box" sections for what changes (and what deliberately doesn't) with a D1-backed trace db — notably, the local backend's WAL live-read guarantee does not hold for D1. |
 | `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. |
@@ -116,6 +116,10 @@ the two runs' cost/tokens/gates together.
 
 **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.
 
+**`spf init`'s interview** asks local-vs-D1 only inside the "advanced" gate (declining advanced settings, or `--yes`, leaves `observability.db` unset — local sqlite at its default path, today's behavior, unchanged). Choosing D1 asks for `database_id` (required) and, unless this same interview run already collected `CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_API_TOKEN` for the Cloudflare Workers AI provider, asks for those too — reusing them instead of asking twice when it did. The generated config omits `account_id_env`/`api_token_env` (they match the schema's own defaults above), so a D1 choice writes just `db: {kind: d1, database_id: ...}`.
+
+**`spf doctor`** probes a `kind: d1` `observability.db` in two steps, right after its `db_path` check: first a static, hard check that the resolved `account_id_env`/`api_token_env` are actually set (naming whichever is missing) — informational, same never-a-hard-failure contract as every other credential-presence check in this file. Then, only when both are set and `--no-probe` isn't passed, a cheap read-only reachability check (`SfDb.exists()` — no `Tracer`, no write) reports `info` whenever the request succeeds, whether the database already has a `sessions` table or (expected before the first run against a fresh database) not — a reachable database is healthy either way, exactly like the local `db_path` check's plain `✓` for a not-yet-created sqlite file. Only when the request itself fails (bad credentials, wrong `database_id`, network error) does it report `warn` (never a hard failure), naming the actual error.
+
 ### `quality`
 
 `checks[]`: `{name, area: "frontend"|"backend", operation: "lint"|"typecheck"|"build", argv: string[], timeout_seconds}`.
@@ -160,6 +164,9 @@ Full mechanism: the main README's "`spf watch`" section. Field reference:
 | `chain_options` | map of string -> string | Options passed straight through to `chain` (and `refine.chain`) for every unattended dispatch — the same shape an interactive `spf <chain> --suite <name>` builds, e.g. `{suite: strict}` or `{agent: some-agent}`. Default `{}`. Only useful for a chain whose behavior actually reads the option (a step-derived chain's `--suite`; an imperative chain ignores an option it doesn't know about). |
 | `jira.base_url` / `jira.project_key` | string | Only consulted when `issue_provider: jira`. |
 | `jira.issue_types` | map: `epic`/`feature`/`story`/`bug`/`task`/`spec` -> string | Only consulted when `issue_provider: jira` AND `refine.enabled`. What each `RefinedIssue.kind` (plus `spec`, a standalone spec proposed by a split — see below) creates as on Jira — defaults `epic`/`feature` → `Epic`, `story`/`spec` → `Story`, `bug` → `Bug`, `task` → `Task`, overridable per kind. Validated against the real project by both `spf watch init` and `spf watch`'s own startup check. |
+| `jira.status_map` | map: `spec-ready`/`ready`/`working`/`review`/`done`/`blocked` -> string | Only consulted when `issue_provider: jira`. Optional, empty (unset) by default — when a state has no entry, `spf watch` updates only the `<prefix>:<state>` label on that transition, exactly as before this field existed. When a state IS mapped to a real Jira status name (e.g. `working: "In Progress"`), `spf watch` also transitions the issue's native Status field there, best-effort: no reachable transition, or a rejected one, is logged and skipped rather than failing the run — the label update is what `spf watch` actually depends on, status sync is a convenience on top. Validated against the real project's statuses by both `spf watch init` and `spf watch`'s own startup check, same as `issue_types`. |
+| `github.project_number` | int ≥0 | Only consulted when `issue_provider: github`. Which of the repo OWNER's Projects v2 boards `status_map` syncs against (Projects v2 numbers are per-owner, not per-repo — see the board's own URL). Default `0`, which disables status sync outright regardless of `status_map`; there's no sane "guess the board" default. |
+| `github.status_map` | map: `spec-ready`/`ready`/`working`/`review`/`done`/`blocked` -> string | Only consulted when `issue_provider: github` AND `project_number` is set. Optional, empty (unset) by default — an unmapped state stays label-only, a mapped one also sets the Projects v2 "Status" field, best-effort (no matching Status option, or a rejected mutation, is logged and skipped, never thrown — the label update is what `spf watch` actually depends on, status sync is a convenience on top). Needs `GITHUB_TOKEN` to carry the `project` scope in addition to `repo`/`public_repo` — Projects v2 is GraphQL-only. Validated against the real project's Status options by both `spf watch init` and `spf watch`'s own startup check. |
 | `refine.enabled` | bool | Turns on the second lane: decompose a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues, instead of running `chain` against it directly (a spec isn't individually workable). Default `false` — off by default, so an existing `watch:` config is unaffected by upgrading. Needs `issue_provider: github` or `"jira"` — both implement issue authoring (create + link a hierarchy); any other value fails loudly at startup. |
 | `refine.chain` | string | Which registered chain runs per claimed spec. Default `refine`. |
 | `refine.concurrency` | int ≥1 | The refine lane's own budget, separate from `concurrency`. Default `1`. |
@@ -361,8 +368,8 @@ unordered splice of both).
 | `enabled` | bool | Default `false`. `true` turns on the ladder walk described below; `false` (or the key absent) is a total no-op, checked nowhere and dispatched nowhere. |
 | `tiers` | array, WEAKEST FIRST | The ladder. A risk level shifts every routed role UP or DOWN this list by the same step — order is the whole semantics, which is why this is a sequence and not a mapping. Default `[]`. |
 | `tiers[].name` | string | What `roles` values point at. |
-| `tiers[].coding_agent` | `"flue"` \| `"claude_code"` | Which backend's vocabulary this rung's `model` speaks. Default `flue`, same default an agent's own `coding_agent` uses. A tier changes an agent's `model` and **nothing else** — `coding_agent` always stays the agent's own — so a rung can only route roles whose backend matches (**rule T**, below). |
-| `tiers[].model` | string | Same vocabulary as an agent's own `model:` for that backend: `provider/model-id` for `flue`, Claude Code's bare alias/full name for `claude_code`. No per-provider table — for `flue` the provider is already the string's first segment. |
+| `tiers[].coding_agent` | `"flue"` \| `"claude_code"` \| `"opencode"` | Which backend's vocabulary this rung's `model` speaks. Default `flue`, same default an agent's own `coding_agent` uses. A tier changes an agent's `model` and **nothing else** — `coding_agent` always stays the agent's own — so a rung can only route roles whose backend matches (**rule T**, below). |
+| `tiers[].model` | string | Same vocabulary as an agent's own `model:` for that backend: `provider/model-id` for `flue` and `opencode`, Claude Code's bare alias/full name for `claude_code`. No per-provider table — for `flue`/`opencode` the provider is already the string's first segment. |
 | `roles` | map of agent name -> tier name | The baseline tier per **role**. Naming an agent here is the operator's statement "route this one by tier" — the resolved tier then wins over that agent's own `model:`. An agent **not** named here is never retiered; its `model:` stands, untouched. That is the whole precedence rule. Default `{}`. |
 
 ```yaml

package/assets/skill/references/observability.md

@@ -6,12 +6,47 @@ always: **agents → sqlite → CLI / web UI.**
 ## Two stores, one truth
 
 **Files are the raw record** (`envelope.json`, `agent_map.json`, Flue's own
-`.spf/data/flue.db` conversation store); **SQLite (`.spf/data/spf.db`, via
-`node:sqlite`) is the queryable mirror** the CLI and UI read. `tracer.ts`
-writes both. Losing the db loses nothing that can't be rebuilt from files.
-
-Location comes from `observability.db` in `spf.config.yaml`, default
-`.spf/data/spf.db` — inside the target repo, always gitignored.
+`.spf/data/flue.db` conversation store); **the trace db is the queryable
+mirror** the CLI and UI read. `tracer.ts` writes both. Losing the trace db
+loses nothing that can't be rebuilt from files.
+
+`observability.db` in `spf.config.yaml` names WHICH trace db backend and
+where — a bare string (a local sqlite path, default `.spf/data/spf.db`,
+inside the target repo, always gitignored), `{kind: sqlite, path?}` spelled
+out the same way, or `{kind: d1, database_id, account_id_env?,
+api_token_env?}` for a remote Cloudflare D1 database instead of a local
+file. `core/trace_db.ts`'s `TraceDb` interface is the one seam both `Tracer`
+(writes) and `SfDb` (reads) go through — `createTraceDb()` picks
+`LocalTraceDb` or `D1TraceDb` from the resolved kind. See `config.md`'s
+`observability.db` rows for the full field reference.
+
+**The WAL live-read guarantee is LOCAL-ONLY.** The rest of this doc's "WAL
+pragmas" section describes a guarantee specific to the local sqlite
+backend — `spf ui` reading while a chain writes, through one shared file.
+A D1-backed repo has no such file to share: `spf ui` and a running chain
+each speak to D1 over independent HTTP calls, and D1's own consistency
+model (sequential consistency, with a Sessions-API "bookmark" for
+read-your-own-writes that this adapter does not use — see
+`D1TraceDb`'s own doc comment in `core/trace_db.ts`) does not promise the
+same instant. This is a deliberate, documented trade-off (SPF #66), not a
+gap: no phase/gate/run OUTCOME depends on it — only how quickly `spf ui`
+can catch up to a chain still writing.
+
+**D1 ships the complete trace off-box.** The "Two stores, one truth"
+guarantee above ("local sqlite, always gitignored") is specific to
+`kind: sqlite`. Point `observability.db` at `kind: d1` and every write
+`tracer.ts` makes — `sessions.request` (the operator's raw request text),
+`events.payload_json` (including each `tool_call` event's `args` and
+`result_snippet`), `envelopes.payload_json`, and
+`gate_results.violations_json` — is POSTed over HTTPS to
+`https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}/query`
+(`trace_db.ts`'s `D1TraceDb`). This is the full trace, not the OTEL
+spans-only attribute allowlist described elsewhere in this doc: prompts,
+tool arguments, and tool results leave the machine on every run once
+`kind: d1` is configured. There is no partial mode — a repo is either
+fully local (`kind: sqlite`, the default) or fully remote for trace data
+(`kind: d1`). Choose D1 only when shipping that data to Cloudflare is
+acceptable for the repo in question.
 
 ## Event schema
 
@@ -86,6 +121,16 @@ up through `agents.execute`, `run.phase`, and every chain's `main()` is
 
 ## Tables
 
+No `REFERENCES` / foreign keys on `adw_id` or `phase_id` anywhere below — a
+deliberate change for the D1 backend (SPF #66), not an oversight: Cloudflare
+D1 enforces FKs unconditionally with no way to disable them, and a session's
+very first write (e.g. its first `events` row) can otherwise land before its
+own `sessions` row has committed, throwing `FOREIGN KEY constraint failed` on
+a perfectly ordinary run. The relationships still hold logically (every
+`adw_id` should resolve to a `sessions` row eventually) — they are just no
+longer enforced by the schema on either backend, so local sqlite and D1
+behave identically.
+
 ```sql
 sessions (
   adw_id TEXT PRIMARY KEY, adw_name TEXT, request TEXT, status TEXT, engineer TEXT,
@@ -93,37 +138,37 @@ sessions (
   archived INTEGER DEFAULT 0            -- review triage, set by the UI; never by a run
 );
 phases (
-  phase_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, seq INTEGER,
+  phase_id TEXT PRIMARY KEY, adw_id TEXT, seq INTEGER,
   name TEXT, kind TEXT, owner TEXT, description TEXT,
   status TEXT DEFAULT 'fail',           -- success must be earned
   attempt INTEGER DEFAULT 0, retries INTEGER DEFAULT 0, error TEXT,
   started_at TEXT, ended_at TEXT
 );
 events (
-  event_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  event_id TEXT PRIMARY KEY, adw_id TEXT, phase_id TEXT,
   parent_id TEXT, type TEXT, name TEXT, payload_json TEXT, tokens INTEGER,
   started_at TEXT, ended_at TEXT        -- ended_at set only on events that span time
 );
 envelopes (
-  envelope_id TEXT PRIMARY KEY, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  envelope_id TEXT PRIMARY KEY, adw_id TEXT, phase_id TEXT,
   agent TEXT, output_type TEXT, payload_json TEXT, valid INTEGER, attempt INTEGER, created_at TEXT
 );
 gate_results (
-  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT REFERENCES sessions, phase_id TEXT REFERENCES phases,
+  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT, phase_id TEXT,
   attempt INTEGER, gate TEXT, passed INTEGER,
   violations_json TEXT,                 -- derived: the failed checks, as "item: note"
   checks_json TEXT,                     -- [{item, ok, note}] — everything the gate looked at
   created_at TEXT
 );
 processes (                             -- adw_id -> pid, so a stuck run can be stopped
-  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT REFERENCES sessions,
+  id INTEGER PRIMARY KEY AUTOINCREMENT, adw_id TEXT,
   kind TEXT,                            -- 'adw' (the chain process) | 'agent' (a real child pid for claude_code; same as the chain's own pid for Flue, which is in-process)
   name TEXT, pid INTEGER,
   command TEXT,                         -- what the pid WAS; pids get recycled, verify before killing
   started_at TEXT, ended_at TEXT        -- ended_at NULL = believed alive
 );
 agent_sessions (                        -- the queryable mirror of agent_map.json
-  adw_id TEXT REFERENCES sessions, agent TEXT,
+  adw_id TEXT, agent TEXT,
   coding_agent TEXT, model TEXT, color TEXT, session_id TEXT,
   context_tokens INTEGER,               -- window occupancy after the agent's last turn
   context_window INTEGER,               -- backend-dependent; 0 = unknown — see "Context is occupancy" above

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

@@ -0,0 +1,54 @@
+# .spf/spf.config.yaml — OpenCode backend. `spf init --template ts-opencode`
+# writes this file as-is.
+#
+# `coding_agent: opencode` shells out to your own locally installed
+# `opencode` CLI — install it with:
+#   npm install -g opencode-ai
+# (the package is `opencode-ai`; the binary it puts on PATH is `opencode` —
+# a common point of confusion, so double-check `which opencode` if a run
+# can't find it.)
+#
+# model: is provider/model-id, the same free-form vocabulary shape Flue
+# uses — NOT Claude Code's own bare-alias vocabulary (sonnet/opus/...).
+# A few concrete examples:
+#   anthropic/claude-sonnet-4-20250514
+#   ollama/qwen3-coder:30b
+#   opencode/gpt-5.1-codex
+#
+# Authentication is handled entirely outside spf: run `opencode auth login`
+# (interactive) once, which writes credentials to
+# ~/.local/share/opencode/auth.json. `spf doctor` checks that `opencode` is
+# on PATH and that that auth.json file exists, but it does not drive login
+# itself and does not know whether the credentials inside are actually
+# valid — same informational, not-enforced posture as its claude_code check
+# for ANTHROPIC_API_KEY.
+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: opencode
+  model: anthropic/claude-sonnet-4-20250514
+
+# REQUIRED, not just an example: the packaged default roster pins
+# planner/reviewer/documenter to their own explicit 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 opencode with whatever model string the packaged roster
+# happened to pin them to, which may point at a provider/model your
+# `opencode auth login` was never set up for. 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: anthropic/claude-sonnet-4-20250514
+  - name: reviewer
+    model: anthropic/claude-sonnet-4-20250514
+  - name: documenter
+    model: anthropic/claude-sonnet-4-20250514

package/dist/chains/index.js

@@ -195,6 +195,6 @@ export async function runChain(chain, ctx, options = {}) {
         // exactly as it always did (the signal listener needs no such fallback:
         // the process is gone).
         await otel.releaseOtelExporter(ctx.adw_id);
-        session.finalize(ctx.adw_id);
+        await session.finalize(ctx.adw_id);
     }
 }

package/dist/chains/simple_sdlc.d.ts

@@ -71,8 +71,8 @@ export interface SignoffParams {
     asker: Asker | null;
     /** `undefined` when `git config user.name`/`user.email` is unset at this repo — see `git_helper.committerIdentity`. */
     identity: CommitterIdentity | undefined;
-    /** Routes into the phase's own trace record — `ph.log`, unchanged (no tracer changes on this thread). */
-    log: (payload: Record<string, unknown>) => void;
+    /** Routes into the phase's own trace record — `ph.log`, now async (`Tracer`'s write methods all are — see `core/tracer.ts`'s header). */
+    log: (payload: Record<string, unknown>) => Promise<void>;
     /** Console-only, never traced — the prompt itself and its framing, kept out of the event stream on purpose (the DECISION is what `log` records). */
     warn: (line: string) => void;
 }

package/dist/chains/simple_sdlc.js

@@ -95,7 +95,7 @@ export async function decideSignoff(params) {
                 "or run via `spf watch`, where a human merges the PR instead of this phase.");
         }
         warn(paint("bold yellow", `⚠ ${AI_ONLY_SIGNOFF_WARNING}`));
-        log({
+        await log({
             decision: "ai_only",
             warning: AI_ONLY_SIGNOFF_WARNING,
             human: false,
@@ -118,7 +118,7 @@ export async function decideSignoff(params) {
     }
     warn("");
     const accepted = await asker.confirm(identity ? `${identity.name}, approve and commit?` : "Approve and commit?", false, { timeoutMs: signoffTimeoutSeconds * 1000 });
-    log({
+    await log({
         decision: accepted ? "approved" : "declined",
         human: true,
         engineer: identity?.name ?? null,
@@ -128,7 +128,7 @@ export async function decideSignoff(params) {
     });
     if (accepted && !identity) {
         warn(paint("dim", "  no git committer identity (user.name/user.email) is set — sign-off recorded, no Signed-off-by trailer"));
-        log({ note: "signoff recorded without a git committer identity — trailer skipped" });
+        await log({ note: "signoff recorded without a git committer identity — trailer skipped" });
     }
     return { accepted, recordedYes: accepted };
 }
@@ -151,10 +151,10 @@ export async function main(ctx) {
     const run = await startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
     const baseline = run.git.rev("HEAD"); // pinned before this run commits anything
     await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
-        ph.log({ input: prompt, baseline: run.git.shortSha(baseline) });
+        await ph.log({ input: prompt, baseline: run.git.shortSha(baseline) });
     });
     const plan = await run.phase(makePhaseParams({ name: "plan", kind: "agent", owner: "planner", description: "Turn the request into an implementable plan" }), (ph) => ph.call(makeAgentCall({ output_type: PlanOutput, prompt, gates: [gates.artifactsExist, gates.filesNonEmpty] })));
-    await run.phase(makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "Put the spec on record before any code exists to blur it" }), async (ph) => commitEnvelope(run, ph, plan));
+    await run.phase(makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "Put the spec on record before any code exists to blur it" }), async (ph) => await commitEnvelope(run, ph, plan));
     let build = await run.phase(makePhaseParams({ name: "build", kind: "agent", owner: "builder", description: "Implement the plan exactly" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt, previous: plan, gates: [gates.diffMatchesClaims] })));
     let test = null;
     for (let i = 1; i <= MAX_FIX_LOOPS; i++) {
@@ -164,8 +164,8 @@ export async function main(ctx) {
             owner: "quality",
             description: "Run the suite — a known command, so code runs it and no agent has to rediscover it",
         }), async (ph) => {
-            const result = quality.runTests(run);
-            quality.record(ph, result);
+            const result = await quality.runTests(run);
+            await quality.record(ph, result);
             return result;
         });
         if (test.passed)
@@ -198,8 +198,8 @@ export async function main(ctx) {
             owner: "quality",
             description: "Re-run the suite — the revision changed code after the last green result",
         }), async (ph) => {
-            const result = quality.runTests(run);
-            quality.record(ph, result);
+            const result = await quality.runTests(run);
+            await quality.record(ph, result);
             return result;
         });
     }
@@ -254,10 +254,10 @@ export async function main(ctx) {
         // trailerFor gates the trailer on recordedYes, not just `verified` — see
         // its own comment: a Signed-off-by line must trace back to an explicit
         // "yes", never to the AI-only path (where `verified` can also be true).
-        async (ph) => commitEnvelope(run, ph, build, trailerFor({ accepted: verified, recordedYes }, identity)));
+        async (ph) => await commitEnvelope(run, ph, build, trailerFor({ accepted: verified, recordedYes }, identity)));
         const changeset = await run.phase(makePhaseParams({ name: "changes", kind: "code", owner: "git", description: "Diff the whole run against its pinned baseline, for the documenter" }), async (ph) => {
             const result = changes.capture(run, makeChangeCapture({ base: baseline }));
-            logChangeset(ph, result);
+            await logChangeset(ph, result);
             if (result.empty) {
                 throw new Error(`nothing changed since ${result.base.label} (${result.base.reason}) — there is nothing to document.`);
             }
@@ -269,7 +269,7 @@ export async function main(ctx) {
             previous: changes.asEnvelope(changeset, DOCUMENT_NOTES),
             gates: [gates.artifactsExist, gates.filesNonEmpty],
         })));
-        await run.phase(makePhaseParams({ name: "commit_docs", kind: "code", owner: "git", description: "Ship the write-up in its own commit, beside the code it describes" }), async (ph) => commitEnvelope(run, ph, document));
+        await run.phase(makePhaseParams({ name: "commit_docs", kind: "code", owner: "git", description: "Ship the write-up in its own commit, beside the code it describes" }), async (ph) => await commitEnvelope(run, ph, document));
     }
-    return run.finish(verified, "the suite or the review never came back clean, or sign-off never came");
+    return await run.finish(verified, "the suite or the review never came back clean, or sign-off never came");
 }

package/dist/chains/steps.d.ts

@@ -107,9 +107,9 @@ export declare function startRun(ctx: ChainContext, requiredAgents: string[], re
  */
 export declare function commitEnvelope(run: Run, ph: PhaseHandle, envelope: EnvelopeBase & {
     commit_message?: string;
-}, signoff?: CommitterIdentity | null): void;
+}, signoff?: CommitterIdentity | null): Promise<void>;
 /** Log a change-capture result the same way every chain that captures one did. */
-export declare function logChangeset(ph: PhaseHandle, result: ChangeSet): void;
+export declare function logChangeset(ph: PhaseHandle, result: ChangeSet): Promise<void>;
 /**
  * The gates a chain definition is allowed to name, by name.
  *