@gr8ful/spf 0.4.0 → 0.5.1

package/dist/cli/ask.d.ts

@@ -9,7 +9,20 @@ export interface Asker {
         validate?: (value: string) => string | null;
     }): Promise<string>;
     select<T extends string>(label: string, choices: SelectChoice<T>[], dflt: T): Promise<T>;
-    confirm(label: string, dflt: boolean): Promise<boolean>;
+    /**
+     * `opts.timeoutMs`, when given (including `0`, for "don't wait at all" —
+     * checked with `!== undefined`, never truthiness), bounds the wait: expiry
+     * resolves with `dflt` (never with `true` — a caller that wants "expiry
+     * means not approved" passes `dflt: false`, same as any other unanswered
+     * prompt) and prints a `timed out — using default (yes|no)` line, phrased
+     * from `dflt` itself, so the transcript never contradicts what was
+     * returned. Absent -> unbounded, unchanged from before this option existed
+     * (the only caller today that needs it is `simple_sdlc.ts`'s sign-off
+     * prompt — see `review.signoff_timeout_seconds`).
+     */
+    confirm(label: string, dflt: boolean, opts?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
     /** Echo-suppressed. `current` (if any) is shown masked; an empty answer keeps it and resolves to `""`. */
     secret(label: string, opts?: {
         current?: string;

package/dist/cli/ask.js

@@ -30,6 +30,30 @@ class MutableWritable extends Writable {
         callback();
     }
 }
+/** Sentinel distinguishing "the timer fired" from any real answer, including "". */
+const TIMED_OUT = Symbol("timed-out");
+/**
+ * Race `promise` against a `ms` timer. On expiry resolves `TIMED_OUT` and
+ * lets `promise` keep running unobserved — `readline`'s `question()` has no
+ * cancel, so the only alternatives are leaving it pending (harmless: nothing
+ * is still awaiting its result once this returns) or never bounding the
+ * wait at all, which is exactly what `review.signoff_timeout_seconds` exists
+ * to rule out. `.unref()` so a pending prompt with a live timer never keeps
+ * the process alive on its own.
+ */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(TIMED_OUT), ms);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 export function createAsker() {
     const muteableOut = new MutableWritable();
     const rl = createInterface({ input: process.stdin, output: muteableOut, terminal: true });
@@ -81,9 +105,15 @@ export function createAsker() {
                 console.log(paint("red", `  not one of: ${[...valid].join(", ")}`));
             }
         },
-        async confirm(label, dflt) {
+        async confirm(label, dflt, opts) {
             const hint = dflt ? "Y/n" : "y/N";
-            const answer = (await raw(`${label} ${paint("dim", `[${hint}]`)}: `)).toLowerCase();
+            const pending = raw(`${label} ${paint("dim", `[${hint}]`)}: `);
+            const result = opts?.timeoutMs !== undefined ? await withTimeout(pending, opts.timeoutMs) : await pending;
+            if (result === TIMED_OUT) {
+                console.log(paint("yellow", `  timed out — using default (${dflt ? "yes" : "no"})`));
+                return dflt;
+            }
+            const answer = result.toLowerCase();
             if (!answer)
                 return dflt;
             return answer === "y" || answer === "yes";

package/dist/cli/commands/doctor.d.ts

@@ -1 +1 @@
-export declare function doctorCommand(argv: string[]): number;
+export declare function doctorCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/doctor.js

@@ -14,18 +14,136 @@ import * as paths from "../../core/paths.js";
 import * as permissions from "../../core/permissions.js";
 import * as agentCc from "../../core/agent_cc.js";
 import { DEFAULT_NOTIFY_ENV_KEY } from "../../core/notify/notifier.js";
+import { endpointLabel, redact, resolveTracesUrl } from "../../core/otel.js";
 import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
+import { ollamaBaseUrl } from "../../core/ollama_provider.js";
 import { binaryOnPath, parseCli } from "../../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
 import { isRepoAt } from "../../core/git_helper.js";
-import { findChain } from "../../chains/index.js";
-function check(report, name, ok, detail) {
-    report.checks.push({ name, ok, detail });
+import { allChains, findChain, repoChainProblems, resolveRequiredAgents, resolveRequiredSuites } from "../../chains/index.js";
+/**
+ * `severity` is a display-only axis, orthogonal to `ok`/`report.ok`: an
+ * "info"/"warn" check still reports `ok: true` (it never fails `spf doctor`
+ * on its own — see each call site for why), but prints as `ℹ`/`⚠` instead of
+ * a plain `✓` so a real negative finding (e.g. "unreachable", a `/v1`
+ * double-path warning) can't be mistaken for a pass at a glance.
+ */
+function check(report, name, ok, detail, severity) {
+    report.checks.push({ name, ok, detail, severity });
     if (!ok)
         report.ok = false;
 }
-export function doctorCommand(argv) {
-    const { options, flags } = parseCli(argv, ["cwd", "config"], ["json"]);
+/** Same helper as `list.ts`'s — trims a repo chain's absolute `source` path down to the `.spf/chains/...` fragment worth printing. Small enough, and file-local enough, that sharing it isn't worth a new module. */
+function repoChainLabel(source) {
+    const marker = path.join(".spf", "chains");
+    const idx = source.lastIndexOf(marker);
+    return idx === -1 ? source : source.slice(idx);
+}
+const PROBE_TIMEOUT_MS = 3_000;
+/** A GET that never throws — a down/unreachable server is a finding to report, never a crash of `spf doctor` itself. */
+async function probeGet(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        return { ok: true, status: res.status };
+    }
+    catch (error) {
+        return { ok: false, error: error.message };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * An EMPTY OTLP trace batch, POSTed exactly the way `core/otel.ts` posts a
+ * real one (same URL, same configured headers) — `{"resourceSpans":[]}` is
+ * valid OTLP that records nothing, so this probe cannot create a phantom trace
+ * in the operator's backend. Never throws: an unreachable collector is a
+ * finding to print, not a doctor crash. A 4xx is still a useful answer (the
+ * host is up; the path or the auth header is wrong), so the status is reported
+ * rather than collapsed into ok/not-ok.
+ */
+async function probeOtel(url, headers) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(headers ?? {}) },
+            body: JSON.stringify({ resourceSpans: [] }),
+            signal: controller.signal,
+        });
+        return { ok: true, status: res.status };
+    }
+    catch (error) {
+        // undici collapses every connection-level failure to "fetch failed" and
+        // puts the actual reason (DNS, ECONNREFUSED, a TLS error — each with a
+        // different fix) on `error.cause`. Fold it in before redacting so `spf
+        // doctor`, whose whole job is telling the operator what's wrong, can.
+        const err = error;
+        const cause = err.cause;
+        const detail = cause ? ` (${cause.code ?? cause.message ?? String(cause)})` : "";
+        // redact(): a fetch failure routinely embeds the URL it attempted, and the
+        // endpoint may carry userinfo — the same rule the exporter's own log obeys.
+        return { ok: false, error: redact(`${err.message}${detail}`, [url, ...Object.values(headers ?? {})]) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * A minimal `POST {base}/v1/messages` — the same request shape `agent_cc.ts`
+ * ultimately drives, just with `max_tokens: 1` and no tools/schema, so a
+ * genuinely-reachable-but-model-not-found endpoint still answers fast. Never
+ * throws: a network failure or timeout is a finding (`unreachable`), not a
+ * doctor crash. Anthropic's Messages API forced adoption is what Ollama
+ * 0.32.14 natively speaks at this path (spike-verified) — HTTP 200 with a
+ * `type: "message"` body is the positive signal; any other status or body
+ * shape still gets reported, just labeled accordingly, since this check is
+ * informational either way (see its call site).
+ */
+async function probeAnthropicMessages(base, model) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        // Send whatever auth the operator already has configured for this
+        // endpoint, if any: with no header at all, a real hosted endpoint (a
+        // proxy, api.anthropic.com) answers 401, which reads as "broken" even
+        // though the probe itself never authenticated. Harmless for Ollama,
+        // which ignores the header entirely (see the module doc above).
+        const apiKey = process.env["ANTHROPIC_AUTH_TOKEN"] || process.env["ANTHROPIC_API_KEY"];
+        const res = await fetch(`${base}/v1/messages`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "anthropic-version": "2023-06-01",
+                ...(apiKey ? { "x-api-key": apiKey } : {}),
+            },
+            body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: "user", content: "ping" }] }),
+            signal: controller.signal,
+        });
+        let note;
+        if (res.status === 200) {
+            try {
+                const body = (await res.json());
+                note = body?.type === "message" ? "type: message" : `unexpected body shape (type: ${JSON.stringify(body?.type)})`;
+            }
+            catch {
+                note = "non-JSON body";
+            }
+        }
+        return { ok: true, status: res.status, note };
+    }
+    catch (error) {
+        return { ok: false, error: error.message };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function doctorCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "config"], ["json", "no-probe"]);
     const report = { ok: true, checks: [] };
     check(report, "node version", true, process.version);
     const anchor = paths.resolveAnchor(options["cwd"]);
@@ -36,6 +154,16 @@ export function doctorCommand(argv) {
     check(report, ".spf directory", true, anchor.spf_dir ?? "(none — running off packaged built-ins; run `spf init` to override)");
     const isRepo = isRepoAt(anchor.repo_root);
     check(report, "git repository", isRepo, isRepo ? "yes" : "no — commit phases and change capture will fail");
+    // Informational only: gitignoring .spf/ itself (as opposed to the usual
+    // .spf/data/, which SHOULD be ignored) silently defeats protected_files
+    // for everything under it, including chain files not written yet — git
+    // never sees them, so permissions.ts's tracked/dirty scan can't either.
+    if (isRepo && anchor.spf_dir) {
+        const ignored = spawnSync("git", ["check-ignore", "-q", ".spf"], { cwd: anchor.repo_root }).status === 0;
+        check(report, ".spf/ not gitignored", true, ignored
+            ? "WARNING: .spf/ itself is gitignored — this silently defeats protected_files for everything under it; ignore .spf/data/ instead, not .spf/"
+            : "good");
+    }
     const resolution = paths.resolveConfigPaths(anchor, options["config"]);
     check(report, "config resolution", true, `${resolution.source}: ${resolution.paths.join(" -> ")}`);
     let cfg;
@@ -62,13 +190,100 @@ export function doctorCommand(argv) {
     }
     const usesClaudeCode = cfg.agents.some((a) => a.coding_agent === "claude_code");
     if (usesClaudeCode) {
-        const claudeOnPath = binaryOnPath("claude");
+        // A custom SPF_CLAUDE_CMD points the real work at something other than
+        // the literal `claude` binary (a wrapper, a launcher) — checking `claude`
+        // itself in that case both misses the wrapper being missing and can
+        // falsely pass on a machine where `claude` happens to be on PATH but
+        // unused. Check whatever agent_cc.ts will actually `spawn()`: cmdSpec's
+        // first token.
+        const cmdSpec = process.env["SPF_CLAUDE_CMD"] || "claude";
+        const cmdTokens = cmdSpec.split(/\s+/).filter(Boolean);
+        const cmdBin = cmdTokens[0] || "claude";
+        const claudeOnPath = binaryOnPath(cmdBin);
         let version = "";
-        if (claudeOnPath) {
+        if (claudeOnPath && cmdBin === "claude") {
             const result = spawnSync("claude", ["--version"], { encoding: "utf-8" });
             version = result.status === 0 ? result.stdout.trim() : "";
         }
-        check(report, "claude CLI", claudeOnPath, claudeOnPath ? version || "on PATH, but --version failed" : "not found on PATH — required by any coding_agent: claude_code agent");
+        check(report, "claude CLI", claudeOnPath, claudeOnPath
+            ? version || (cmdBin === "claude" ? "on PATH, but --version failed" : `"${cmdBin}" on PATH (via SPF_CLAUDE_CMD) — --version not checked for a wrapper/launcher`)
+            : `"${cmdBin}" not found on PATH — required by any coding_agent: claude_code agent${cmdBin !== "claude" ? " (checked SPF_CLAUDE_CMD's first token, not the literal \"claude\")" : ""}`);
+        // `ollama launch <cmd>` needs an explicit `--` before claude's own flags
+        // (cobra flag parsing otherwise consumes them as ITS OWN — see
+        // agent_cc.ts's module comment for the spike-verified failure and fix),
+        // and agent_cc.ts now inserts that separator automatically for exactly
+        // this token shape. But `--` alone is NOT sufficient: `ollama launch`
+        // also requires its OWN `--model <tag>` flag, typed BEFORE the `--`,
+        // whenever it's run headless — SPF always spawns with piped stdio, so
+        // without `--model` there, `ollama launch` falls back to an interactive
+        // model picker that can never run and fails with "model selection
+        // requires an interactive terminal" (spike-verified; see agent_cc.ts's
+        // module comment). Unlike the reachability probes below, this is a
+        // static, deterministic misconfiguration knowable from the string alone
+        // — a real hard failure, not an informational note.
+        if (cmdTokens[0] === "ollama" && cmdTokens[1] === "launch") {
+            const dashIdx = cmdTokens.indexOf("--");
+            const beforeSeparator = dashIdx === -1 ? cmdTokens : cmdTokens.slice(0, dashIdx);
+            const hasModelFlag = beforeSeparator.includes("--model");
+            check(report, "SPF_CLAUDE_CMD ollama launch wrapper", hasModelFlag, hasModelFlag
+                ? cmdTokens.includes("--")
+                    ? 'explicit "--" and "--model" (before it) already present in SPF_CLAUDE_CMD — left as-is'
+                    : 'auto-handled: agent_cc.ts inserts "--" before claude\'s flags for this wrapper shape (see its module comment); "--model" is present before that point, as `ollama launch` requires in headless mode'
+                : 'missing "--model <tag>" before any "--" — `ollama launch` runs headless (SPF pipes stdio) and will fail with "model selection requires an interactive terminal" even though agent_cc.ts inserts the "--" separator for you. Set SPF_CLAUDE_CMD="ollama launch claude --model <tag>" (tag from `ollama list`).');
+        }
+        const anthropicBaseUrl = process.env["ANTHROPIC_BASE_URL"];
+        if (anthropicBaseUrl && !flags["no-probe"]) {
+            const trimmed = anthropicBaseUrl.replace(/\/+$/, "");
+            // The claude CLI appends "/v1/messages" itself — a base URL that
+            // already ends in "/v1" produces a double "/v1/v1/messages" 404, a
+            // real mistake seen in practice, not a hypothetical.
+            const doubledPath = /\/v1$/.test(trimmed);
+            if (doubledPath) {
+                check(report, "ANTHROPIC_BASE_URL shape", true, `${anthropicBaseUrl} ends in "/v1" — the claude CLI appends "/v1/messages" itself; this looks like a double-path mistake (try dropping the trailing "/v1")`, "warn");
+            }
+            // Informational/warning only (ok always true): reachability here says
+            // nothing about auth or model correctness, and a down server between
+            // doctor runs shouldn't fail the whole command — it's a fact to
+            // surface, the same pattern as the other checks in this file that are
+            // never allowed to fail `spf doctor` on their own. When the shape
+            // check above just flagged a double "/v1", probe the CORRECTED base
+            // instead of the known-bad one — probing the bad path would just
+            // confirm the mistake we already diagnosed, spending the probe on
+            // nothing new.
+            const probeBase = doubledPath ? trimmed.replace(/\/v1$/, "") : trimmed;
+            const claudeCodeAgent = cfg.agents.find((a) => a.coding_agent === "claude_code");
+            const probeModel = claudeCodeAgent?.model || "claude-sonnet-5";
+            const result = await probeAnthropicMessages(probeBase, probeModel);
+            check(report, "ANTHROPIC_BASE_URL reachability", true, (result.ok
+                ? `${doubledPath ? `dropping the trailing "/v1" makes it ` : ""}reachable: POST ${probeBase}/v1/messages -> HTTP ${result.status}${result.note ? ` (${result.note})` : ""}`
+                : `unreachable: POST ${probeBase}/v1/messages -> ${result.error}`) +
+                " (this is a real, billable inference request — pass --no-probe to skip both network probes)", result.ok ? "info" : "warn");
+        }
+    }
+    // Flue agents pointed at a local Ollama server (`model: ollama/...`) have
+    // no API key to check (providers.ts's PROVIDER_ENV_KEYS.ollama is `[]`,
+    // handled in the per-agent loop below) but DO have a server that might
+    // simply not be running — worth a reachability probe the same way
+    // ANTHROPIC_BASE_URL gets one above.
+    const usesOllamaFlue = cfg.agents.some((a) => a.coding_agent !== "claude_code" && a.model.startsWith("ollama/"));
+    if (usesOllamaFlue && !flags["no-probe"]) {
+        // `ollamaBaseUrl()` (ollama_provider.ts) is the SAME default-substitution
+        // logic `registerOllamaModel` uses for a real dispatch, including
+        // treating a set-but-EMPTY OLLAMA_BASE_URL as unset — re-deriving the
+        // default here with `||` would agree on the common cases but diverge on
+        // that one, which is exactly the failure mode doctor exists to catch,
+        // not mask.
+        const ollamaBase = ollamaBaseUrl().replace(/\/+$/, "");
+        // `/models` (the OpenAI-compat list, matching the base URL's own `/v1`
+        // shape) over `/api/tags` (Ollama's native catalog endpoint): measured
+        // live against a real local server, `/models` returned 886 bytes vs.
+        // `/api/tags`'s 4461 bytes for the identical model catalog, same ~20ms
+        // latency either way — strictly cheaper for a pure reachability check,
+        // and there's no live-server dependency in this choice: doctor's probe
+        // itself tolerates either endpoint being down (see `probeGet`).
+        const result = await probeGet(`${ollamaBase}/models`);
+        check(report, "OLLAMA_BASE_URL reachability", true, // informational/warning only — see the ANTHROPIC_BASE_URL check above for why
+        result.ok ? `reachable: GET ${ollamaBase}/models -> HTTP ${result.status}` : `unreachable: GET ${ollamaBase}/models -> ${result.error}`, result.ok ? "info" : "warn");
     }
     for (const agent of cfg.agents) {
         const label = `agent "${agent.name}"`;
@@ -85,6 +300,9 @@ export function doctorCommand(argv) {
                 if (!envKeys) {
                     check(report, `${label} provider key`, true, `provider "${provider}" not in doctor's known list — skipped, not a failure`);
                 }
+                else if (envKeys.length === 0) {
+                    check(report, `${label} provider key`, true, `provider "${provider}" is keyless — no key required`);
+                }
                 else {
                     const set = envKeys.find((k) => process.env[k]);
                     check(report, `${label} provider key`, Boolean(set), set ? `${set} is set` : `none of ${envKeys.join(", ")} is set`);
@@ -107,6 +325,34 @@ export function doctorCommand(argv) {
         const missing = names.filter((n) => !cfg.quality.checks.some((c) => c.name === n));
         check(report, `quality suite "${suiteName}"`, missing.length === 0, missing.length === 0 ? names.join(", ") : `names unknown check(s): ${missing.join(", ")}`);
     }
+    // Repo-local chains (`.spf/chains/*.yaml`, registered as DATA — see
+    // `chains/repo_chains.ts` — never as imported repo code): already merged
+    // into the registry by `cli/index.ts`'s `main()` before any command runs,
+    // so `allChains()`/`repoChainProblems()` here reflect exactly what `spf
+    // list` and `spf run`/`spf <chain>` would resolve, not a re-parse of our
+    // own. A malformed chain file is a real ✗, not informational — an operator
+    // wrote a chain they cannot run, and that is exactly the "fails silently
+    // otherwise" class of problem this command exists to surface.
+    for (const problem of repoChainProblems()) {
+        check(report, `repo chain ${problem.file}`, false, problem.message);
+    }
+    for (const chain of allChains().filter((c) => c.source !== undefined)) {
+        const owners = resolveRequiredAgents(chain, {});
+        const missingOwners = owners.filter((o) => !cfg.agents.some((a) => a.name === o));
+        check(report, `repo chain "${chain.name}" owners`, missingOwners.length === 0, missingOwners.length === 0 ? owners.join(", ") || "(none)" : `unknown agent(s): ${missingOwners.join(", ")} — not in cfg.agents`);
+        const suiteNames = resolveRequiredSuites(chain, {});
+        const missingSuites = suiteNames.filter((s) => !(s in cfg.quality.suites));
+        const missingChecks = missingSuites.length === 0 ? suiteNames.flatMap((s) => cfg.quality.suites[s].filter((n) => !cfg.quality.checks.some((c) => c.name === n))) : [];
+        check(report, `repo chain "${chain.name}" suites`, missingSuites.length === 0 && missingChecks.length === 0, missingSuites.length > 0
+            ? `unknown suite(s): ${missingSuites.join(", ")} — not in cfg.quality.suites`
+            : missingChecks.length > 0
+                ? `suite(s) name unknown check(s): ${missingChecks.join(", ")}`
+                : suiteNames.join(", ") || "(none)");
+        // Informational: the derived sequence itself, same string `spf list`
+        // shows — printed here so the chain's author can eyeball what they
+        // actually wrote without a second command.
+        check(report, `repo chain "${chain.name}" phases`, true, chain.phases, "info");
+    }
     // A protected_files pattern matching nothing anywhere in the trace is
     // usually a stale convention (e.g. an old adws/... pattern) that silently
     // stopped protecting anything.
@@ -124,6 +370,18 @@ export function doctorCommand(argv) {
     if (cfg.watch.repo.trim()) {
         check(report, "watch.issue_provider", true, cfg.watch.issue_provider);
         check(report, "watch.code_host", true, cfg.watch.code_host);
+        check(report, "watch.repo", true, `${cfg.watch.repo} (code_host's repo)`);
+        // The one combination where a single `repo` field is ambiguous: GitHub
+        // issues against a Bitbucket repo are two different repos in two
+        // different systems, not one repo worn two ways. Every other
+        // combination is unambiguous even with issue_repo unset — flag this
+        // one specifically rather than silently polling GitHub with the
+        // Bitbucket workspace/repo_slug string as if it were "owner/name".
+        if (cfg.watch.issue_provider === "github" && cfg.watch.code_host === "bitbucket") {
+            check(report, "watch.issue_repo", Boolean(cfg.watch.issue_repo.trim()), cfg.watch.issue_repo.trim()
+                ? cfg.watch.issue_repo
+                : `not set — issue_provider is github and code_host is bitbucket, two different repos in two different systems; without watch.issue_repo, GitHub issues will be polled using watch.repo (${JSON.stringify(cfg.watch.repo)}), which is the BITBUCKET repo`);
+        }
         if (cfg.watch.issue_provider === "github" || cfg.watch.code_host === "github") {
             check(report, "GITHUB_TOKEN", Boolean(process.env["GITHUB_TOKEN"]), process.env["GITHUB_TOKEN"]
                 ? "set"
@@ -142,14 +400,63 @@ export function doctorCommand(argv) {
                 ? "set"
                 : 'not set — Bitbucket app passwords are being removed; spf watch needs an Atlassian account email plus an API token instead; see README.md\'s "spf watch" section');
         }
-        check(report, "watch.chain", Boolean(findChain(cfg.watch.chain)), findChain(cfg.watch.chain) ? cfg.watch.chain : `"${cfg.watch.chain}" is not a registered chain`);
+        // findChain() consults built-ins first, then the repo-chain registry
+        // (registered by cli/index.ts's main() before doctorCommand ever runs)
+        // — a watch.chain naming a `.spf/chains/*.yaml` chain resolves here the
+        // same way it would for `spf watch` itself, no special-casing needed.
+        const watchChain = findChain(cfg.watch.chain);
+        check(report, "watch.chain", Boolean(watchChain), watchChain ? `${cfg.watch.chain}${watchChain.source ? ` (repo: ${repoChainLabel(watchChain.source)})` : ""}` : `"${cfg.watch.chain}" is not a registered chain`);
+        // Informational only, never a failure: a chain that skips review and/or
+        // never commits is a legitimate choice (e.g. `scout`, `plan`) — this is
+        // here so an unattended `spf watch` posture is a visible fact, not a
+        // silent assumption.
+        if (watchChain) {
+            // Structural, not name-coupled: `reviseLoop`'s derived label is always
+            // `${reviewer} [-> ${builder}(revise) -> ${reviewer} ...] bounded` (see
+            // steps.ts), so this holds for a built-in chain and for a repo chain
+            // that overrides `reviewer`/`builder` to something other than the
+            // literal agent named "reviewer" — the same owner-override feature
+            // this changeset added everywhere else. Matching on the literal name
+            // "reviewer" would report "does not include a reviewer" for a chain
+            // that is entirely built around a review loop, the moment its reviewer
+            // is renamed.
+            const hasReviewer = watchChain.phases.includes("(revise)");
+            const hasCommitPhase = watchChain.phases.includes("commit");
+            check(report, "watch.chain review posture", true, `${hasReviewer ? "includes" : "does not include"} a reviewer; ${hasCommitPhase ? "includes" : "does not include"} a commit phase`);
+        }
         if (cfg.watch.refine.enabled) {
-            check(report, "watch.refine.chain", Boolean(findChain(cfg.watch.refine.chain)), findChain(cfg.watch.refine.chain) ? cfg.watch.refine.chain : `"${cfg.watch.refine.chain}" is not a registered chain`);
+            const refineChain = findChain(cfg.watch.refine.chain);
+            check(report, "watch.refine.chain", Boolean(refineChain), refineChain ? `${cfg.watch.refine.chain}${refineChain.source ? ` (repo: ${repoChainLabel(refineChain.source)})` : ""}` : `"${cfg.watch.refine.chain}" is not a registered chain`);
             check(report, "watch.refine issue authoring", cfg.watch.issue_provider === "github", cfg.watch.issue_provider === "github"
                 ? "github supports issue authoring (createIssue/sub-issues)"
                 : `watch.issue_provider is ${JSON.stringify(cfg.watch.issue_provider)} — the refine lane needs "github" (Jira issue authoring isn't implemented yet)`);
         }
     }
+    // OTel span export: informational in every direction. It is off unless
+    // `observability.otel` exists (no env var can turn it on — see
+    // core/otel.ts), and when it IS on, an unreachable collector must never fail
+    // `spf doctor` any more than it fails a run: export is a lossy projection of
+    // a trace SQLite already holds. What doctor adds is visibility — "configured
+    // but nothing is listening" is otherwise a single redacted log line inside a
+    // run nobody re-reads.
+    if (cfg.observability.otel) {
+        const url = resolveTracesUrl(cfg.observability.otel.endpoint);
+        const insecure = url.startsWith("http://") && !/^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/)/.test(url);
+        check(report, "observability.otel", true, 
+        // endpointLabel() drops any userinfo and query string — both are places
+        // a token gets smuggled into a URL, and doctor's output gets pasted into
+        // issues. Header VALUES are never printed at all, only their key names.
+        `span export -> ${endpointLabel(url)} (service_name: ${cfg.observability.otel.service_name}` +
+            `${cfg.observability.otel.headers ? `, headers: ${Object.keys(cfg.observability.otel.headers).join(", ")}` : ""})` +
+            (insecure ? " — WARNING: plain http to a non-loopback host sends this telemetry in cleartext" : ""), insecure ? "warn" : "info");
+        if (!flags["no-probe"]) {
+            const result = await probeOtel(url, cfg.observability.otel.headers);
+            check(report, "observability.otel reachability", true, // informational/warning only — same rule as the base-URL probes above
+            result.ok
+                ? `reachable: POST ${endpointLabel(url)} (empty batch) -> HTTP ${result.status}${result.status >= 400 ? " — reachable but rejecting; check the path (/v1/traces) and headers" : ""}`
+                : `unreachable: POST ${endpointLabel(url)} -> ${result.error}`, result.ok && result.status < 400 ? "info" : "warn");
+        }
+    }
     if (cfg.notifications.events !== "off") {
         check(report, "notifications.events", true, cfg.notifications.events);
         if (cfg.notifications.channels.length === 0) {
@@ -169,7 +476,8 @@ function finish(report, json) {
     }
     else {
         for (const c of report.checks) {
-            console.log(`${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`);
+            const icon = c.severity === "warn" ? "⚠" : c.severity === "info" ? "ℹ" : c.ok ? "✓" : "✗";
+            console.log(`${icon} ${c.name}: ${c.detail}`);
         }
         console.log(report.ok ? "\nspf doctor: clean" : "\nspf doctor: problems found above");
     }

package/dist/cli/commands/init.d.ts

@@ -1 +1,13 @@
+/**
+ * Scaffolded once by `spf init` — fully commented out, so every line is a
+ * `#` comment and `parseYaml` reads the whole file as an empty document;
+ * `loadOne` (repo_chains.ts) treats that as "declares no chain" and skips it
+ * silently — no chain registered, but also no problem reported against
+ * spf's own scaffold. It exists to show the shape (naming existing
+ * `chains/steps.ts` factories as data, never importing repo code — params
+ * are flat siblings of `step:`, never nested under a `params:` key) and to
+ * carry the one divergence an author needs to know before writing a real
+ * one.
+ */
+export declare const EXAMPLE_CHAIN_YAML = "# .spf/chains/example.yaml \u2014 a repo-local chain, loaded as DATA.\n#\n# This file NAMES existing step factories from spf's own chains/steps.ts\n# (request, plan, build, fixLoop, commit, ...) \u2014 it never imports or runs\n# code from this repo. \"Agent proposes, code disposes,\" and the code that\n# disposes is always SPF's own, packaged code; a chain file only ever picks\n# which of ITS steps run, in which order, with which params. See\n# .claude/skills/spf/cookbooks/authoring_chains.md (installed by `spf init`\n# into THIS repo) for the full step vocabulary \u2014 its \"Repo-local chains\"\n# section is written for exactly this file.\n#\n# WATCH DIVERGENCE: `spf watch` registers chains from the MAIN repo anchor\n# once, at daemon start \u2014 not per-issue, not per-worktree. A chain file\n# edited on an issue branch (inside the worktree `spf watch` checks that\n# branch out into) is NOT what runs for that issue; the daemon keeps using\n# whatever `.spf/chains/` looked like in the main repo when it started. The\n# disposer stays the OPERATOR's, never the branch's \u2014 exactly the property\n# that keeps an agent from being able to rewrite its own quality gate mid-run\n# by editing a chain file as part of the change it's making.\n#\n# Uncomment and edit to register this chain (spf list / spf doctor will\n# then show it). Every field below is required unless noted.\n#\n# name: example                  # spf example \"<prompt>\" / spf run example \"<prompt>\"\n# describe: small build+fix example chain \u2014 build, then a bounded test-fix loop\n# steps:\n#   - step: request               # every chain opens with this\n#   - step: build\n#     fromPlan: false              # no preceding plan() step in this chain\n#   - step: fixLoop\n#     suite: test                  # must name a key under quality.suites in spf.config.yaml\n#     owner: builder               # must name an agent in the roster (cfg.agents)\n#     max: 3                       # optional \u2014 defaults to 3 if omitted\n#   - step: commit\n#     onlyIfAccepted: true\n";
 export declare function initCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/init.js

@@ -91,7 +91,9 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 # watch:
 #   issue_provider: github   # github | jira
 #   code_host: github        # github | bitbucket
-#   repo: owner/name          # "owner/name" (github) or "workspace/repo_slug" (bitbucket)
+#   repo: owner/name          # the CODE HOST's repo — "owner/name" (github) or "workspace/repo_slug" (bitbucket)
+#   # issue_repo: owner/name  # ONLY for issue_provider: github + code_host: bitbucket, when
+#   #                         # the tracker and code host are genuinely different repos
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
@@ -116,12 +118,76 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 #   channels:
 #     - kind: slack            # slack | teams | webhook
 #       webhook_url_env: SLACK_WEBHOOK_URL   # default for slack; TEAMS_WEBHOOK_URL / SPF_WEBHOOK_URL for the others
+
+# Uncomment to change the human sign-off gate in front of simple-sdlc's
+# commit_build phase — the one place an AI reviewer's approved flag alone
+# can gate a commit. See assets/skill/references/config.md's "review"
+# section for the full behavior.
+# review:
+#   require_human_signoff: false   # true = an unattended simple-sdlc run fails closed instead of committing on the reviewer's verdict alone
+#   signoff_timeout_seconds: 300
 `;
 // .spf/spf.config.yaml and .spf/prompt_engineering/ stay tracked — they're
 // shared project config, same as package.json. Only runtime/generated
 // content is ignored: session traces (data/), a hand-editable engine copy
 // (engine/, from `spf eject`), and secrets (.env).
+//
+// `.spf/chains/` is deliberately NOT in this list. A chain file is DATA
+// that decides what the disposer runs (see repo_chains.ts's module comment)
+// — the same trust boundary `defaults.protected_files` exists to guard.
+// Gitignoring it would let anyone (or any agent) rewrite what "spf plan-
+// build-test" or a watch.chain even means, invisibly to `git diff`/PR
+// review, in a repo that otherwise protects every other file that judges
+// agent output. Chain files stay tracked so `protected_files` covers the
+// chain that judges the agents, not just the code it judges.
 const GITIGNORE_ENTRIES = [".spf/data/", ".spf/engine/", ".env"];
+/**
+ * Scaffolded once by `spf init` — fully commented out, so every line is a
+ * `#` comment and `parseYaml` reads the whole file as an empty document;
+ * `loadOne` (repo_chains.ts) treats that as "declares no chain" and skips it
+ * silently — no chain registered, but also no problem reported against
+ * spf's own scaffold. It exists to show the shape (naming existing
+ * `chains/steps.ts` factories as data, never importing repo code — params
+ * are flat siblings of `step:`, never nested under a `params:` key) and to
+ * carry the one divergence an author needs to know before writing a real
+ * one.
+ */
+export const EXAMPLE_CHAIN_YAML = `# .spf/chains/example.yaml — a repo-local chain, loaded as DATA.
+#
+# This file NAMES existing step factories from spf's own chains/steps.ts
+# (request, plan, build, fixLoop, commit, ...) — it never imports or runs
+# code from this repo. "Agent proposes, code disposes," and the code that
+# disposes is always SPF's own, packaged code; a chain file only ever picks
+# which of ITS steps run, in which order, with which params. See
+# .claude/skills/spf/cookbooks/authoring_chains.md (installed by \`spf init\`
+# into THIS repo) for the full step vocabulary — its "Repo-local chains"
+# section is written for exactly this file.
+#
+# WATCH DIVERGENCE: \`spf watch\` registers 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 in the main repo when it started. The
+# disposer stays the OPERATOR's, never the branch's — exactly the property
+# that keeps an agent from being able to rewrite its own quality gate mid-run
+# by editing a chain file as part of the change it's making.
+#
+# Uncomment and edit to register this chain (spf list / spf doctor will
+# then show it). Every field below is required unless noted.
+#
+# name: example                  # spf example "<prompt>" / spf run example "<prompt>"
+# describe: small build+fix example chain — build, then a bounded test-fix loop
+# steps:
+#   - step: request               # every chain opens with this
+#   - step: build
+#     fromPlan: false              # no preceding plan() step in this chain
+#   - step: fixLoop
+#     suite: test                  # must name a key under quality.suites in spf.config.yaml
+#     owner: builder               # must name an agent in the roster (cfg.agents)
+#     max: 3                       # optional — defaults to 3 if omitted
+#   - step: commit
+#     onlyIfAccepted: true
+`;
 const GENERATED_HEADER = `# .spf/spf.config.yaml — written by \`spf init\`'s interview, merged ON TOP of
 # spf's packaged built-in defaults. Only what you changed is here; run
 # \`spf doctor\` any time to see what's actually in effect for this repo, and
@@ -133,6 +199,17 @@ export async function initCommand(argv) {
     const anchor = paths.resolveAnchor(options["cwd"]);
     const sfDir = path.join(anchor.repo_root, ".spf");
     mkdirSync(sfDir, { recursive: true });
+    // Scaffold `.spf/chains/` unconditionally, on every path below (interview
+    // or not) — same idempotent shape as installSkill(): never overwrites a
+    // file that's already there (an author may have started editing the
+    // example, or written their own chains alongside it), so this is always
+    // safe to run again on a repo that already has one.
+    const chainsDir = path.join(sfDir, "chains");
+    mkdirSync(chainsDir, { recursive: true });
+    const exampleChainPath = path.join(chainsDir, "example.yaml");
+    if (!existsSync(exampleChainPath)) {
+        writeFileSync(exampleChainPath, EXAMPLE_CHAIN_YAML);
+    }
     // Idempotent (a no-op once the skill is already up to date, a `.new`
     // sibling rather than an overwrite for a locally-edited file) — safe to
     // call on every `spf init`, not just the first.