@gr8ful/spf 0.3.0 → 0.5.0

package/dist/cli/commands/init.js

@@ -10,6 +10,14 @@
  * `src/cli/index.ts`). Piped input, `--yes`, or `--template <name>` all
  * fall through to the original non-interactive behavior unchanged — a
  * scripted `spf init` must never hang waiting on stdin.
+ *
+ * Every path here also installs the repo-local Claude Code skill (the same
+ * work `spf install-skill` does by hand) unless `--no-skills` is passed —
+ * on every run, not just the first: `install-skill` is idempotent (a no-op
+ * once the skill is already up to date), so this never re-does work or
+ * clobbers a locally-edited skill file. `--user` (installing to
+ * `~/.claude/skills/spf` instead) stays a `spf install-skill` invocation of
+ * its own; `init` only ever writes the repo-local default.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -22,6 +30,7 @@ import { paint } from "../../core/console.js";
 import { createAsker, isInteractive, InterviewAborted } from "../ask.js";
 import { gatherContext, runInterview } from "../interview.js";
 import { readEnvFile, upsertEnvFile, writeEnvExample } from "../env_file.js";
+import { installSkillCommand } from "./install-skill.js";
 const TEMPLATE_SUFFIX = ".spf.config.yaml";
 /** Every template's short name (e.g. "ts-cc"), derived from disk rather than hand-maintained — never drifts from what's actually packaged. */
 function listTemplates() {
@@ -67,8 +76,8 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 # explicit Flue-style provider/model-id strings, and an agent's own model
 # always wins over defaults.model — so those three keep running on whatever
 # backend you just switched to, with a model id it can't resolve, unless
-# you override their model here too (builder/scout have no model of their
-# own in the packaged roster, so they need no override). See
+# you override their model here too (builder/scout/refiner have no model of
+# their own in the packaged roster, so they need no override). See
 # assets/templates/ts.spf.config.yaml (or --template ts) for the full
 # working pattern.
 
@@ -82,10 +91,19 @@ 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
+#   # Optional second lane: decompose a spf:spec-ready product spec into a
+#   # feature/story-or-bug tree of real issues. Off by default; needs
+#   # issue_provider: github — issue authoring isn't implemented for Jira yet.
+#   refine:
+#     enabled: true
+#     chain: refine
+#     concurrency: 1
 
 # Uncomment to push notifications for unattended work — spf watch's daemon
 # lifecycle, and every chain run (spf <chain> / spf run, including watch's
@@ -100,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
@@ -113,10 +195,29 @@ const GENERATED_HEADER = `# .spf/spf.config.yaml — written by \`spf init\`'s i
 # (gitignored) — .env.example lists the key names only.
 `;
 export async function initCommand(argv) {
-    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force", "yes"]);
+    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force", "yes", "no-skills"]);
     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.
+    const installSkill = () => {
+        if (flags["no-skills"])
+            return;
+        installSkillCommand(options["cwd"] ? ["--cwd", options["cwd"]] : []);
+    };
     const configPath = path.join(sfDir, "spf.config.yaml");
     const templateName = options["template"];
     const interactive = !templateName && !flags["yes"] && isInteractive();
@@ -129,6 +230,7 @@ export async function initCommand(argv) {
             writeFileSync(configPath, content);
             console.log(`wrote ${configPath}${templateName ? ` (from template "${templateName}")` : ""}`);
         }
+        installSkill();
     }
     else {
         const asker = createAsker();
@@ -138,6 +240,7 @@ export async function initCommand(argv) {
                 if (!overwrite) {
                     console.log("leaving the existing config alone (--force to skip this prompt)");
                     asker.close();
+                    installSkill();
                     ensureGitignore(anchor.repo_root, GITIGNORE_ENTRIES);
                     return 0;
                 }
@@ -155,6 +258,7 @@ export async function initCommand(argv) {
             if (Object.keys(result.env).length > 0)
                 upsertEnvFile(anchor.repo_root, result.env);
             writeEnvExample(anchor.repo_root, result.envExampleKeys);
+            installSkill();
             // The same merge-then-validate pipeline `spf doctor` runs — catches a
             // bad answer (e.g. a suite naming an unconfigured check) right after
             // writing, not at the user's first real chain run. Non-fatal: the

package/dist/cli/commands/install-skill.js

@@ -1,7 +1,10 @@
 /**
  * `spf install-skill` — copy the packaged Claude Code skill (`assets/skill/`)
- * into a target repo (or `~/.claude/skills/spf` with `--user`), on explicit
- * request only. Nothing here ever runs unless a user asks for it.
+ * into a target repo (or `~/.claude/skills/spf` with `--user`). `spf init`
+ * calls this itself, every run, unless `--no-skills` is passed — it's the
+ * command name a user (or a script) still reaches for by hand: to reinstall
+ * after an edit, to target `--user` instead of repo-local, or on a repo
+ * that never ran `spf init` at all (a pure-built-ins setup).
  *
  * Idempotent via a manifest (`.spf-skill-version`: {package, version,
  * files: {relpath: sha256}}) written at the skill root:

package/dist/cli/commands/list.js

@@ -1,13 +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>] [--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}`);
+        }
     }
-    console.log(`spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>]   (spf run <name> ... works identically)`);
     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"];
+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]),
@@ -19,11 +29,28 @@ export async function dispatchChain(chain, argv) {
         adw_id: options["adw-id"] ?? null,
         cwd: anchor.cwd,
         chain_name: chain.name,
+        // Only `refine` reads this (a "## Parent: #<id>" back-reference on
+        // 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`);
@@ -150,6 +214,21 @@ export async function watchCommand(argv) {
         console.error(`watch.chain ${JSON.stringify(cfg.watch.chain)} is not a registered chain — run \`spf list\` to see every chain`);
         return 1;
     }
+    if (cfg.watch.refine.enabled) {
+        if (cfg.watch.issue_provider !== "github") {
+            // Fail loudly at startup, not silently every tick: JiraProvider
+            // doesn't implement IssueAuthoringProvider yet (see its module
+            // comment) — a refine lane that can never publish would otherwise
+            // just claim every spec-ready spec and block it, forever.
+            console.error(`watch.refine.enabled is true but watch.issue_provider is ${JSON.stringify(cfg.watch.issue_provider)} — ` +
+                `the refine lane needs "github" (issue authoring isn't implemented for Jira yet)`);
+            return 1;
+        }
+        if (!findChain(cfg.watch.refine.chain)) {
+            console.error(`watch.refine.chain ${JSON.stringify(cfg.watch.refine.chain)} is not a registered chain — run \`spf list\` to see every chain`);
+            return 1;
+        }
+    }
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
     const lockPath = path.join(dataPaths.data_dir, "watch.lock");
     try {
@@ -186,25 +265,138 @@ export async function watchCommand(argv) {
         mkdirSync(path.dirname(target), { recursive: true });
         symlinkSync(dataPaths.data_dir, target, "dir");
     }
+    /** 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);
+            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)"}`;
+        }
+        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);
+        // 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, reviewRequired };
+    };
+    /**
+     * Same shape as `runChain`, for the refine lane — with one extra step on
+     * success: a chain's return value is just an exit code, so the created-
+     * issues list `steps.publishIssues()` actually produced has to come back
+     * through the side channel it wrote (`refine_publish.json`, under the
+     * SAME symlinked session dir `linkDataDir` already wires up), not through
+     * `runChainDef`'s return value.
+     */
+    const runRefine = async (opts) => {
+        const chainDef = findChain(cfg.watch.refine.chain); // checked above
+        const ctx = {
+            prompt: opts.prompt,
+            config_paths: configPaths,
+            adw_id: opts.adwId,
+            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)
-            return { accepted: true, adwId: opts.adwId, detail: "" };
-        let detail = `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`;
+        if (code !== 0) {
+            const detail = detailFromFailedPhase(opts.cwd, opts.adwId, `Refine chain "${cfg.watch.refine.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, created: [] };
+        }
+        let created = [];
         try {
             const wtAnchor = paths.resolveAnchor(opts.cwd);
             const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-            const db = new SfDb(wtDataPaths.db_path);
-            const failed = db.phases(opts.adwId).find((p) => p.status === "fail");
-            if (failed)
-                detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
+            const summaryPath = path.join(wtDataPaths.data_dir, "sessions", opts.adwId, "context_handoff", "refine_publish.json");
+            created = JSON.parse(readFileSync(summaryPath, "utf-8"));
         }
         catch {
-            // best-effort — the generic message above still points at where to look
+            // best-effort — an empty list still lets runSpec finish cleanly, just with no per-issue summary
         }
-        return { accepted: false, adwId: opts.adwId, detail };
+        return { accepted: true, adwId: opts.adwId, detail: "", created };
     };
     const deps = {
         provider,
@@ -215,6 +407,10 @@ export async function watchCommand(argv) {
         chain: cfg.watch.chain,
         baseBranch: cfg.watch.base_branch,
         concurrency: cfg.watch.concurrency,
+        refineEnabled: cfg.watch.refine.enabled,
+        refineConcurrency: cfg.watch.refine.concurrency,
+        refineChain: cfg.watch.refine.chain,
+        runRefine,
         worktreesDir,
         linkDataDir,
         dryRun: Boolean(flags["dry-run"]),
@@ -254,7 +450,9 @@ export async function watchCommand(argv) {
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
-    console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}${flags["dry-run"] ? "  (dry run)" : ""}`);
+    console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}` +
+        (cfg.watch.refine.enabled ? `  refine "${cfg.watch.refine.chain}" concurrency ${cfg.watch.refine.concurrency}` : "") +
+        (flags["dry-run"] ? "  (dry run)" : ""));
     deps.notify({
         kind: "watch_started",
         level: "info",