@gr8ful/spf 0.4.0 → 0.5.1

package/dist/cli/commands/list.js

@@ -1,14 +1,51 @@
-import { CHAINS } from "../../chains/index.js";
+import path from "node:path";
+import { allChains, repoChainProblems } from "../../chains/index.js";
+/**
+ * A repo-defined chain's `source` is an absolute path into `.spf/chains/` by
+ * construction (that's the one place `loadRepoChains` ever looks) — trim it
+ * back to the repo-relative fragment a human actually wants to see, rather
+ * than a long absolute path that's identical on every machine's checkout
+ * except for the leading segment.
+ */
+function repoChainLabel(source) {
+    const marker = path.join(".spf", "chains");
+    const idx = source.lastIndexOf(marker);
+    return idx === -1 ? source : source.slice(idx);
+}
 export function listCommand() {
-    const width = Math.max(...CHAINS.map((c) => c.name.length));
-    for (const chain of CHAINS) {
+    // Built-ins first, then repo chains — same order `allChains()` guarantees,
+    // so this listing and `findChain`'s resolution order never disagree about
+    // which chain wins on a name collision.
+    const chains = allChains();
+    const width = Math.max(...chains.map((c) => c.name.length));
+    for (const chain of chains) {
         const agents = typeof chain.requiredAgents === "function" ? "(--agent picks who)" : chain.requiredAgents.join(", ") || "(none)";
+        const suites = typeof chain.requiredSuites === "function" ? chain.requiredSuites({}) : chain.requiredSuites;
+        const suiteNote = typeof chain.requiredSuites === "function" ? " (--suite overrides)" : "";
         console.log(`${chain.name.padEnd(width)}  ${chain.phases}`);
         console.log(`${"".padEnd(width)}  ${chain.describe}`);
-        console.log(`${"".padEnd(width)}  agents: ${agents}${chain.requiredSuites.length ? `  ·  quality suites: ${chain.requiredSuites.join(", ")}` : ""}`);
+        console.log(`${"".padEnd(width)}  agents: ${agents}${suites.length ? `  ·  quality suites: ${suites.join(", ")}${suiteNote}` : ""}`);
+        // `source` is undefined for every built-in — only a chain loaded from a
+        // `.spf/chains/*.yaml` file carries one (see chains/repo_chains.ts).
+        if (chain.source) {
+            console.log(`${"".padEnd(width)}  (repo: ${repoChainLabel(chain.source)})`);
+        }
         console.log();
     }
-    console.log(`spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>]   (spf run <name> ... works identically)`);
+    console.log(`spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>] [--suite <name>]   (spf run <name> ... works identically)`);
     console.log(`spf watch polls a tracker and runs one of these chains per issue — spf doctor shows the current config.`);
+    // Every malformed `.spf/chains/*.yaml` file (bad YAML, a schema/params
+    // mismatch, a name naming a step factory that doesn't exist) becomes a
+    // problem here instead of a chain in the list above — loadRepoChains()
+    // never throws, so this is the only place an operator finds out their
+    // chain file didn't register at all.
+    const problems = repoChainProblems();
+    if (problems.length > 0) {
+        console.log();
+        console.log(`${problems.length} repo chain file(s) failed to load — run \`spf doctor\` for detail:`);
+        for (const problem of problems) {
+            console.log(`  ! ${problem.file}: ${problem.message}`);
+        }
+    }
     return 0;
 }

package/dist/cli/commands/run.js

@@ -2,9 +2,10 @@
 import * as paths from "../../core/paths.js";
 import { parseCli, resolvePrompt } from "../../core/utils.js";
 import { runChain } from "../../chains/index.js";
-const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base", "issue"];
+import { isInteractive } from "../ask.js";
+const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base", "issue", "suite"];
 export function usageFor(chain) {
-    return `usage: spf ${chain.name} "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id <id>] [--cwd <dir>]`;
+    return `usage: spf ${chain.name} "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id <id>] [--cwd <dir>] [--suite <name>]`;
 }
 export async function dispatchChain(chain, argv) {
     const { positionals, options } = parseCli(argv, KNOWN_OPTIONS);
@@ -12,6 +13,15 @@ export async function dispatchChain(chain, argv) {
         console.error(usageFor(chain));
         return 1;
     }
+    // Only a step-derived chain's requiredSuites can actually read --suite
+    // (see deriveRequiredSuites/qualityCheck/fixLoop) — an imperative chain
+    // like simple-sdlc has a compiled-in static array and never consults
+    // options["suite"] at all, so accepting the flag there would silently do
+    // nothing. Reject loudly instead of letting it lie.
+    if (options["suite"] !== undefined && typeof chain.requiredSuites !== "function") {
+        console.error(`--suite has no effect on chain "${chain.name}" — its quality suite is fixed at ${JSON.stringify(chain.requiredSuites)}`);
+        return 2;
+    }
     const anchor = paths.resolveAnchor(options["cwd"]);
     const ctx = {
         prompt: resolvePrompt(positionals[0]),
@@ -23,11 +33,24 @@ export async function dispatchChain(chain, argv) {
         // every issue it creates — see ChainContext's doc comment); every
         // other chain ignores it, so it's harmless to always pass through.
         issue_id: options["issue"] ?? null,
+        // A real TTY (isInteractive(), from cli/ask.ts) is the one case an
+        // agent step could plausibly block on a human — everything else (a CI
+        // run, a piped `spf <chain>`, spf watch's own dispatch) is unattended.
+        // Read by `simple_sdlc.ts`'s sign-off phase (`isInteractive() &&
+        // !ctx.unattended`, folded into `canPrompt`) — see `decideSignoff`.
+        unattended: !isInteractive(),
+        // `undefined` for every built-in chain (ChainDefinition.source is only
+        // ever set for a chain loaded from `.spf/chains/*.yaml` — see
+        // chains/repo_chains.ts) — passed through unconditionally since a
+        // `string | undefined` field is exactly what ChainContext declares.
+        chain_source: chain.source,
     };
     const chainOptions = {};
     if (options["agent"] !== undefined)
         chainOptions["agent"] = options["agent"];
     if (options["base"] !== undefined)
         chainOptions["base"] = options["base"];
+    if (options["suite"] !== undefined)
+        chainOptions["suite"] = options["suite"];
     return runChain(chain, ctx, chainOptions);
 }

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

@@ -1,3 +1,21 @@
+import { type ReviewOutputT } from "../../core/data_types.ts";
+/**
+ * `&`/`<`/`>` are active markup in every destination a digest lands in —
+ * `<url|text>`/`*bold*` in Slack mrkdwn, raw HTML in GitHub's markdown
+ * pipeline, and (cosmetically only — Adaptive Cards don't decode entities)
+ * Teams' TextBlock and the generic webhook payload — and a reviewer's
+ * findings/blocking text is LLM-authored, so it is untrusted content, not a
+ * template. Escaped before it ever reaches any renderer, never trusted as
+ * pre-formatted. Note this runs BEFORE truncateDigest, so a cut can in
+ * principle land mid-entity (e.g. `&am…`) — cosmetic only, since the `<`
+ * escape (the one that actually prevents Slack link forgery) is always
+ * complete by the time truncation could touch it.
+ */
+export declare function escapeForMarkup(text: string): string;
+/** Codepoint-safe truncation — a plain `.slice(0, n)` can land mid surrogate pair on a multi-byte finding. */
+export declare function truncateDigest(text: string): string;
+/** A `ReviewOutput` envelope, reduced to the short digest threaded into the PR body and the `pr_opened` notification — see `core/watch.ts`'s `ChainRunResult.reviewSummary`. */
+export declare function formatReviewDigest(review: ReviewOutputT): string;
 /**
  * `spf watch init` — idempotently seed the `<prefix>:*` labels the state
  * machine needs, with sensible colors/descriptions. Doesn't touch git or

package/dist/cli/commands/watch.js

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import * as v from "valibot";
 import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
 import { resolveNotifier } from "../../core/notify/notifier.js";
@@ -16,9 +17,58 @@ import { GitHubProvider } from "../../core/issues/github_provider.js";
 import { JiraProvider } from "../../core/issues/jira_provider.js";
 import { BitbucketProvider } from "../../core/issues/bitbucket_provider.js";
 import { createWatchState, tick } from "../../core/watch.js";
-import { findChain, runChain as runChainDef } from "../../chains/index.js";
+import { findChain, resolveRequiredAgents, runChain as runChainDef } from "../../chains/index.js";
+import { ReviewOutput } from "../../core/data_types.js";
 import { SfDb } from "../../ui/server/db.js";
 import { parseCli } from "../../core/utils.js";
+/** Kept well under Slack's own 2900-char slice on `detail` (see `slack_channel.ts`) — a reviewer can emit a lot of findings, but the PR body/notification only needs enough to tell a human whether to look closer. */
+const MAX_REVIEW_DIGEST_CHARS = 1200;
+/**
+ * `&`/`<`/`>` are active markup in every destination a digest lands in —
+ * `<url|text>`/`*bold*` in Slack mrkdwn, raw HTML in GitHub's markdown
+ * pipeline, and (cosmetically only — Adaptive Cards don't decode entities)
+ * Teams' TextBlock and the generic webhook payload — and a reviewer's
+ * findings/blocking text is LLM-authored, so it is untrusted content, not a
+ * template. Escaped before it ever reaches any renderer, never trusted as
+ * pre-formatted. Note this runs BEFORE truncateDigest, so a cut can in
+ * principle land mid-entity (e.g. `&am…`) — cosmetic only, since the `<`
+ * escape (the one that actually prevents Slack link forgery) is always
+ * complete by the time truncation could touch it.
+ */
+export function escapeForMarkup(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Codepoint-safe truncation — a plain `.slice(0, n)` can land mid surrogate pair on a multi-byte finding. */
+export function truncateDigest(text) {
+    const codepoints = Array.from(text);
+    if (codepoints.length <= MAX_REVIEW_DIGEST_CHARS)
+        return text;
+    return `${codepoints.slice(0, MAX_REVIEW_DIGEST_CHARS).join("")}…`;
+}
+/** A `ReviewOutput` envelope, reduced to the short digest threaded into the PR body and the `pr_opened` notification — see `core/watch.ts`'s `ChainRunResult.reviewSummary`. */
+export function formatReviewDigest(review) {
+    const lines = [`Reviewer verdict: ${review.approved ? "approved" : "changes requested"}.`];
+    if (review.blocking.length > 0) {
+        lines.push("Blocking:", ...review.blocking.map((b) => `- ${escapeForMarkup(b)}`));
+    }
+    const unmet = review.findings.filter((f) => !f.met);
+    if (unmet.length > 0) {
+        lines.push("Unmet requirements:", ...unmet.map((f) => `- ${escapeForMarkup(f.requirement)}${f.evidence ? ` — ${escapeForMarkup(f.evidence)}` : ""}`));
+    }
+    // The common case on the success path (see the module comment on
+    // `reviewSummaryFor`): every reachable ReviewOutput has approved:true,
+    // blocking:[], unmet:[] — gates.verdictConsistent throws otherwise, and a
+    // gate failure exits the run non-zero before a digest is ever built. So
+    // without this, an approved run's digest would be the vacuous constant
+    // "Reviewer verdict: approved." with zero information in it. The met
+    // findings ARE the reviewer's signal on an approved run — what it actually
+    // verified — so surface them.
+    const met = review.findings.filter((f) => f.met);
+    if (met.length > 0) {
+        lines.push(`Verified ${met.length} requirement(s):`, ...met.map((f) => `- ${escapeForMarkup(f.requirement)}${f.evidence ? ` — ${escapeForMarkup(f.evidence)}` : ""}`));
+    }
+    return truncateDigest(lines.join("\n"));
+}
 /**
  * Shared by `watch` and `watch init`: resolve config into an `IssueProvider`
  * — checking only what BOTH need. `watch`'s own extra checks (a real git
@@ -27,8 +77,16 @@ import { parseCli } from "../../core/utils.js";
  */
 function resolveIssueProvider(cfg) {
     if (cfg.watch.issue_provider === "github") {
-        if (!cfg.watch.repo.trim()) {
-            console.error(`watch.repo is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+        // `issue_repo` (falling back to `repo`) — NOT `repo` alone — because
+        // `repo` always names `code_host`'s own repo (see WatchConfigSchema's
+        // doc comment). Those coincide for issue_provider: github + code_host:
+        // github (the common case, and why the fallback exists at all), but
+        // for issue_provider: github + code_host: bitbucket they are two
+        // different repos in two different systems — reading `repo` here would
+        // silently poll the BITBUCKET repo's identifier for GitHub issues.
+        const repo = cfg.watch.issue_repo.trim() || cfg.watch.repo.trim();
+        if (!repo) {
+            console.error(`watch.repo (or watch.issue_repo, if code_host names a different repo) is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
             return null;
         }
         const token = process.env["GITHUB_TOKEN"];
@@ -36,7 +94,7 @@ function resolveIssueProvider(cfg) {
             console.error('GITHUB_TOKEN is not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo). See README.md\'s "GITHUB_TOKEN scope" section.');
             return null;
         }
-        return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+        return new GitHubProvider(repo, cfg.watch.label_prefix, token);
     }
     if (cfg.watch.issue_provider === "jira") {
         if (!cfg.watch.jira.base_url.trim() || !cfg.watch.jira.project_key.trim()) {
@@ -54,7 +112,13 @@ function resolveIssueProvider(cfg) {
     console.error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} is not supported`);
     return null;
 }
-/** Same shape as `resolveIssueProvider`, for `watch.code_host`. */
+/**
+ * Same shape as `resolveIssueProvider`, for `watch.code_host` — always
+ * reads plain `watch.repo`, never `watch.issue_repo`. `repo` is defined as
+ * the CODE HOST's own repo (see `WatchConfigSchema`'s doc comment); `issue_repo`
+ * exists only to give the issue-tracker side an override when it names a
+ * different repo, which is `resolveIssueProvider`'s concern, not this one's.
+ */
 function resolveCodeHostProvider(cfg) {
     if (!cfg.watch.repo.trim()) {
         console.error(`watch.repo is not configured — add it to spf.config.yaml's watch: section`);
@@ -196,6 +260,17 @@ export async function watchCommand(argv) {
      */
     function linkDataDir(worktreePath) {
         const target = path.join(worktreePath, ".spf", "data");
+        // Hard guard, independent of however `worktreePath` got resolved: a real
+        // self-referential .spf/data symlink was observed live once already
+        // (points at itself — every later `mkdirSync` through it throws ELOOP;
+        // see `paths.healBrokenDataDir` for the recovery side of this same bug).
+        // The exact trigger was never pinned down, but `worktreePath` resolving
+        // to the main repo's own `data_dir` can never be correct regardless of
+        // how it got there, so refuse outright rather than create it again.
+        if (path.resolve(target) === path.resolve(dataPaths.data_dir)) {
+            console.error(`watch: refusing to link ${target} to itself — worktree path resolved to the main repo's own data_dir`);
+            return;
+        }
         if (existsSync(target))
             return;
         mkdirSync(path.dirname(target), { recursive: true });
@@ -204,10 +279,11 @@ export async function watchCommand(argv) {
     /** Shared by `runChain`/`runRefine`: best-effort enrichment of a generic "didn't succeed" message with the first phase that actually failed, read back from the worktree's own (symlinked) trace db. */
     function detailFromFailedPhase(cwd, adwId, prefix) {
         let detail = prefix;
+        let db;
         try {
             const wtAnchor = paths.resolveAnchor(cwd);
             const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-            const db = new SfDb(wtDataPaths.db_path);
+            db = new SfDb(wtDataPaths.db_path);
             const failed = db.phases(adwId).find((p) => p.status === "fail");
             if (failed)
                 detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
@@ -215,16 +291,83 @@ export async function watchCommand(argv) {
         catch {
             // best-effort — the generic message above still points at where to look
         }
+        finally {
+            db?.close();
+        }
         return detail;
     }
+    /**
+     * Best-effort: the reviewer's latest verdict for this run, read back from
+     * the worktree's own (symlinked) trace db and reduced to a digest — same
+     * DB, same try/catch shape as `detailFromFailedPhase` above, but on the
+     * SUCCESS path. `undefined` on any DB/parse hiccup, or when the chain
+     * never produced a `ReviewOutput` envelope at all — never thrown: a digest
+     * is a nice-to-have, not something that gets to block the PR-open flow
+     * it's decorating.
+     */
+    function reviewSummaryFor(cwd, adwId) {
+        let db;
+        try {
+            const wtAnchor = paths.resolveAnchor(cwd);
+            const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
+            db = new SfDb(wtDataPaths.db_path);
+            const envelope = db
+                .envelopes(adwId)
+                .filter((e) => e.output_type === ReviewOutput.name)
+                .at(-1); // the LATEST verdict — a revise loop can produce several
+            if (!envelope?.payload_json)
+                return undefined;
+            const review = v.parse(ReviewOutput.schema, JSON.parse(envelope.payload_json));
+            return formatReviewDigest(review);
+        }
+        catch {
+            return undefined; // best-effort — see the doc comment above
+        }
+        finally {
+            db?.close();
+        }
+    }
     const runChain = async (opts) => {
+        // WATCH DIVERGENCE: `findChain` here resolves against the registry
+        // `cli/index.ts`'s `main()` built ONCE, at daemon start, from the MAIN
+        // repo anchor (the `registerRepoChains(...)` call before the command
+        // switch). `opts.cwd` below is a per-issue WORKTREE, which may carry a
+        // different (or edited) `.spf/chains/`, but that file is never
+        // re-read here — this is deliberate, not a gap: the disposer stays the
+        // OPERATOR's, never the branch's, so an agent can't rewrite its own
+        // quality gate mid-run by editing a chain file as part of the change
+        // it's making. (Also documented in the `spf init` scaffold, since that's
+        // the one place an author is invited to edit a chain file at all.)
         const chainDef = findChain(cfg.watch.chain); // checked above
-        const ctx = { prompt: opts.prompt, config_paths: configPaths, adw_id: opts.adwId, cwd: opts.cwd, chain_name: chainDef.name };
+        const ctx = {
+            prompt: opts.prompt,
+            config_paths: configPaths,
+            adw_id: opts.adwId,
+            cwd: opts.cwd,
+            chain_name: chainDef.name,
+            // Every `spf watch` dispatch is unattended by definition — there is
+            // no human at a TTY to prompt, ever, for an issue claimed off a
+            // tracker poll. `chain_source` is undefined for a built-in chain,
+            // the resolved chain's `.spf/chains/*.yaml` path for a repo one.
+            unattended: true,
+            chain_source: chainDef.source,
+        };
+        // KNOWN LIMITATION (not fixed here): runChainDef is called below with no
+        // third `options` argument, so nothing --suite-shaped ever reaches this
+        // dispatch — `resolveRequiredSuites`/`resolveRequiredAgents` below both
+        // fall back to each chain's compiled-in/YAML-declared default. An
+        // unattended watch run therefore can't override a chain's suite the way
+        // an interactive `spf <chain> --suite <name>` can.
         const code = await runChainDef(chainDef, ctx);
-        if (code === 0)
-            return { accepted: true, adwId: opts.adwId, detail: "" };
+        // Static for every chain but "prompt" (whose --agent flag `spf watch`
+        // never passes) — resolved with no options, exactly like `runChainDef`
+        // above ran it.
+        const reviewRequired = resolveRequiredAgents(chainDef, {}).includes("reviewer");
+        if (code === 0) {
+            return { accepted: true, adwId: opts.adwId, detail: "", reviewRequired, reviewSummary: reviewSummaryFor(opts.cwd, opts.adwId) };
+        }
         const detail = detailFromFailedPhase(opts.cwd, opts.adwId, `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
-        return { accepted: false, adwId: opts.adwId, detail };
+        return { accepted: false, adwId: opts.adwId, detail, reviewRequired };
     };
     /**
      * Same shape as `runChain`, for the refine lane — with one extra step on
@@ -243,6 +386,11 @@ export async function watchCommand(argv) {
             cwd: opts.cwd,
             chain_name: chainDef.name,
             issue_id: opts.issueId,
+            // Same reasoning as runChain's ctx above — an unattended dispatch,
+            // with no --suite-shaped options reaching it either (same KNOWN
+            // LIMITATION).
+            unattended: true,
+            chain_source: chainDef.source,
         };
         const code = await runChainDef(chainDef, ctx);
         if (code !== 0) {

package/dist/cli/index.js

@@ -8,8 +8,10 @@ import path from "node:path";
 import * as agentCc from "../core/agent_cc.js";
 import * as agentFlue from "../core/agent_flue.js";
 import * as notify from "../core/notify/notifier.js";
+import * as otel from "../core/otel.js";
 import * as paths from "../core/paths.js";
-import { findChain } from "../chains/index.js";
+import { findChain, registerRepoChains, repoChainProblems } from "../chains/index.js";
+import { loadRepoChains } from "../chains/repo_chains.js";
 import { dispatchChain, usageFor } from "./commands/run.js";
 import { listCommand } from "./commands/list.js";
 import { initCommand } from "./commands/init.js";
@@ -49,6 +51,26 @@ function findCwdFlag(argv) {
     const idx = argv.indexOf("--cwd");
     return idx !== -1 ? argv[idx + 1] : undefined;
 }
+/**
+ * The moment someone types a chain name that doesn't resolve is the highest-
+ * traffic place a broken `.spf/chains/*.yaml` file is ever discovered — and,
+ * before this, the one place its load problem was withheld (`spf list` and
+ * `spf doctor` report it; this "unknown chain"/"unknown command or chain"
+ * path printed only the full HELP text). A file named for exactly the chain
+ * someone typed is surfaced first, ahead of any other broken file, since
+ * that's the one they're actually looking for right now.
+ */
+function reportUnresolvedChain(typedName) {
+    const problems = repoChainProblems();
+    if (problems.length === 0)
+        return;
+    const matching = typedName ? problems.filter((p) => path.basename(p.file).startsWith(typedName)) : [];
+    const rest = problems.filter((p) => !matching.includes(p));
+    const ordered = [...matching, ...rest];
+    console.error(`${problems.length} repo chain file(s) failed to load — one of these may be what you meant:`);
+    for (const p of ordered)
+        console.error(`  ! ${p.file}: ${p.message}`);
+}
 export async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     // `process.loadEnvFile()` with no argument reads from `process.cwd()` —
@@ -58,13 +80,41 @@ export async function main() {
     // invoking shell's directory instead of the target repo's is exactly the
     // anchor-mismatch bug that principle exists to close. Resolve the same
     // way every command does, and load .env from the repo root it finds.
+    //
+    // Hoisted out of the try/catch below: resolveAnchor() cannot throw —
+    // findRepoRoot() (core/git_helper.ts) guards its own `git rev-parse
+    // --git-dir` probe with isRepoAt() and falls back to `cwd` itself when
+    // it's not a repo, AND guards the follow-up `--show-toplevel` call the
+    // same way (that one can fail even when isRepoAt() said yes — a bare repo
+    // or a `.git/` directory itself has no work tree), so it never throws
+    // either. findSfDir()'s walk is a plain existsSync/statSync loop with no
+    // failure path. The only thing in this block that CAN throw is
+    // loadEnvFile() (ENOENT when there's no .env), which is exactly what the
+    // catch below still guards.
+    const anchor = paths.resolveAnchor(findCwdFlag(rest));
     try {
-        const anchor = paths.resolveAnchor(findCwdFlag(rest));
         process.loadEnvFile(path.join(anchor.repo_root, ".env"));
     }
     catch {
         // no .env there — fine, nothing to load
     }
+    // Repo-local chains as DATA: a `.spf/chains/*.yaml` file names existing
+    // step factories, it never imports repo code — SPF's own dispatcher stays
+    // the one thing that ever executes. Registered here, before the command
+    // switch, so every dispatch path (`spf <chain>`, `spf run <chain>`, `spf
+    // list`, `spf doctor`, `spf watch`) sees the same merged registry without
+    // each of them re-scanning `.spf/chains/` on its own. This is also the
+    // ONCE in "`spf watch` registers chains from the main anchor once, at
+    // daemon start" — see the WATCH DIVERGENCE comment on `runChain` in
+    // `cli/commands/watch.ts` for what that means for a chain file edited on
+    // an issue branch mid-run. Zero filesystem cost when there's no `.spf/` at
+    // all (anchor.spf_dir is null for a repo that
+    // never ran `spf init`) — loadRepoChains() is only ever called once we
+    // know there's something to look at.
+    if (anchor.spf_dir) {
+        const { chains, problems } = loadRepoChains(anchor);
+        registerRepoChains(chains, problems);
+    }
     if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
         console.log(HELP);
         process.exitCode = 0;
@@ -81,6 +131,7 @@ export async function main() {
                 const chain = chainName ? findChain(chainName) : undefined;
                 if (!chain) {
                     console.error(`unknown chain: ${chainName ?? "(none given)"} — run \`spf list\` to see every chain`);
+                    reportUnresolvedChain(chainName);
                     process.exitCode = 1;
                     return;
                 }
@@ -103,7 +154,7 @@ export async function main() {
                 process.exitCode = ejectCommand(rest);
                 return;
             case "doctor":
-                process.exitCode = doctorCommand(rest);
+                process.exitCode = await doctorCommand(rest);
                 return;
             case "ui":
                 process.exitCode = await uiCommand(rest);
@@ -129,6 +180,7 @@ export async function main() {
                 const chain = findChain(cmd);
                 if (!chain) {
                     console.error(`unknown command or chain: ${cmd}\n`);
+                    reportUnresolvedChain(cmd);
                     console.error(HELP);
                     process.exitCode = 1;
                     return;
@@ -156,5 +208,10 @@ export async function main() {
         // A no-op if notifications are off/unconfigured — awaits any in-flight
         // webhook POST so a fast-exiting command doesn't drop it mid-flight.
         await notify.flushAll();
+        // A no-op if `observability.otel` is not configured — drains the bounded
+        // span queue and awaits any in-flight OTLP POST, under its own hard
+        // deadline, so a fast-exiting command neither drops spans mid-flight nor
+        // waits on an unreachable collector. Never throws (core/otel.ts).
+        await otel.flushAll();
     }
 }

package/dist/cli/interview.js

@@ -21,7 +21,7 @@ import { ThinkingLevelSchema } from "../core/data_types.js";
 import { loadConfig } from "../core/agents.js";
 import { BUILTIN_CONFIG_PATH } from "../core/paths.js";
 import { DEFAULT_NOTIFY_ENV_KEY } from "../core/notify/notifier.js";
-import { CHAINS } from "../chains/index.js";
+import { allChains } from "../chains/index.js";
 function gitConfigValue(repoRoot, key) {
     const result = spawnSync("git", ["config", key], { cwd: repoRoot, encoding: "utf-8" });
     const value = result.status === 0 ? result.stdout.trim() : "";
@@ -120,7 +120,7 @@ export async function runInterview(asker, ctx) {
             const token = await asker.secret("ANTHROPIC_AUTH_TOKEN", { current: ctx.existingEnv.get("ANTHROPIC_AUTH_TOKEN") });
             env["ANTHROPIC_AUTH_TOKEN"] = token || "ollama";
             envExampleKeys.push("ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN");
-            asker.note("spf doctor does not check these two — confirm the endpoint is reachable yourself.");
+            asker.note("spf doctor now probes ANTHROPIC_BASE_URL with a minimal POST /v1/messages (informational only, never a hard failure) and flags a base URL that already ends in \"/v1\" as a likely double-path mistake — the default above (without a trailing /v1) is exactly what that check is guarding against. It still cannot validate ANTHROPIC_AUTH_TOKEN itself.");
         }
         // The packaged roster pins planner/reviewer/documenter to their own
         // Flue-style provider/model-id strings, which always win over
@@ -149,11 +149,44 @@ export async function runInterview(asker, ctx) {
             asker.note(`warning: ${error.message}`);
         }
         defaults.model = model;
-        const envKey = PROVIDER_ENV_KEYS[provider][0];
-        const key = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
-        if (key)
-            env[envKey] = key;
-        envExampleKeys.push(envKey);
+        const envKeys = PROVIDER_ENV_KEYS[provider];
+        if (envKeys.length > 0) {
+            const envKey = envKeys[0];
+            const key = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
+            if (key)
+                env[envKey] = key;
+            envExampleKeys.push(envKey);
+        }
+        else {
+            asker.note(`${provider} is keyless — no API key to collect.`);
+            if (provider === "ollama") {
+                // Same shape as the claude_code branch's ANTHROPIC_BASE_URL prompt
+                // above: a local/cloud Ollama server has no key, just an address.
+                // The `/v1` suffix matches agent_flue.ts's own registration default
+                // (spike-verified: Ollama serves its OpenAI-compatible surface —
+                // the one Flue's pi-ai backend actually speaks — under `/v1`, not
+                // at the bare root `/api/...` Ollama also exposes).
+                const baseUrl = await asker.text("OLLAMA_BASE_URL", {
+                    default: "http://localhost:11434/v1",
+                    validate: (v) => (v.trim() ? null : "required"),
+                });
+                env["OLLAMA_BASE_URL"] = baseUrl;
+                envExampleKeys.push("OLLAMA_BASE_URL");
+                asker.note("spf doctor checks this one — a probe against OLLAMA_BASE_URL/models runs on every `spf doctor`.");
+                // Same problem the claude_code branch already solves above: the
+                // packaged roster pins planner/reviewer/documenter to their own
+                // fireworks/gemini/openai model strings, which always win over
+                // defaults.model. Left alone, this flow would produce a config
+                // where three of six agents are still routed at hosted providers
+                // whose keys this ollama flow never collects — `spf doctor` would
+                // immediately report missing FIREWORKS_API_KEY/GEMINI_API_KEY/
+                // OPENAI_API_KEY right after an interview that asked for neither.
+                for (const name of ["planner", "reviewer", "documenter"]) {
+                    agentOverrides.push({ name, model: defaults.model });
+                }
+                notes.push("planner/reviewer/documenter pin their own model in the packaged roster and always win over defaults.model — overriding all three to the ollama model chosen above, or spf doctor would report missing FIREWORKS_API_KEY/GEMINI_API_KEY/OPENAI_API_KEY for providers this flow never asked about.");
+            }
+        }
     }
     // Declined (the default): today's behavior exactly — on claude_code, the
     // three-agent auto-pin above stands unchanged; on flue, no agents: block
@@ -222,15 +255,37 @@ export async function runInterview(asker, ctx) {
             { value: "bitbucket", label: "Bitbucket" },
         ], "github");
         const repoHint = codeHost === "bitbucket" ? "workspace/repo_slug" : "owner/name";
-        const repo = await asker.text(`Repo (${repoHint})`, {
+        // github issues + bitbucket code is the one combination where a single
+        // repo field is ambiguous — they're two different repos in two
+        // different systems, not one repo worn two ways (github+github is one
+        // repo by construction; jira never reads `repo` at all). Ask a second,
+        // explicitly-labeled question only in that one case.
+        const splitRepo = issueProvider === "github" && codeHost === "bitbucket";
+        const repo = await asker.text(splitRepo ? `Code repo, where PRs open (${repoHint})` : `Repo (${repoHint})`, {
             default: codeHost === "github" ? ctx.repoSlug ?? "" : "",
             validate: (val) => (val.includes("/") && val.split("/").filter(Boolean).length === 2 ? null : `must be "${repoHint}"`),
         });
+        let issueRepo = "";
+        if (splitRepo) {
+            asker.note("GitHub issues and the Bitbucket code repo are different repos here — spf watch needs both.");
+            issueRepo = await asker.text("Issue repo, where spf:ready issues live (owner/name)", {
+                default: ctx.repoSlug ?? "",
+                validate: (val) => (val.includes("/") && val.split("/").filter(Boolean).length === 2 ? null : `must be "owner/name"`),
+            });
+        }
         const labelPrefix = await asker.text("Label prefix", { default: "spf" });
         const baseBranch = await asker.text("Base branch", { default: ctx.currentBranch });
-        const chainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
+        // allChains(), not the built-in-only CHAINS: `registerRepoChains` already
+        // ran in main() before initCommand, so a pre-existing `.spf/chains/`
+        // repo chain is a legal watch.chain everywhere else (watch.ts resolves
+        // it via findChain, doctor.ts validates and labels it) — this picker is
+        // the one place a user chooses watch.chain, so it must offer the same
+        // set. The "(repo)" hint marker distinguishes it in the list.
+        const chainChoices = allChains().map((c) => ({ value: c.name, label: c.name, hint: c.source ? `${c.describe} (repo)` : c.describe }));
         const chain = await asker.select("Chain to run per issue", chainChoices, "plan-build-test");
         watch = { issue_provider: issueProvider, code_host: codeHost, repo, label_prefix: labelPrefix, chain, base_branch: baseBranch };
+        if (issueRepo)
+            watch.issue_repo = issueRepo;
         // Issue authoring (create + link a hierarchy) is only implemented on
         // GitHubProvider today — see jira_provider.ts's module comment — so
         // this lane isn't offered at all on a Jira tracker rather than asking a
@@ -238,7 +293,7 @@ export async function runInterview(asker, ctx) {
         if (issueProvider === "github") {
             const enableRefine = await asker.confirm(`Also enable the refine lane (decompose a "${labelPrefix}:spec-ready" product spec into a feature/story-or-bug tree)?`, false);
             if (enableRefine) {
-                const refineChainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
+                const refineChainChoices = allChains().map((c) => ({ value: c.name, label: c.name, hint: c.source ? `${c.describe} (repo)` : c.describe }));
                 const refineChain = await asker.select("Chain to run per spec", refineChainChoices, "refine");
                 watch.refine = { enabled: true, chain: refineChain };
             }