@gr8ful/spf 0.2.1 → 0.4.0

package/dist/core/watch.js

@@ -1,10 +1,18 @@
 /**
- * The `spf watch` state machine: poll -> claim -> run a chain -> PR ->
- * done/blocked. Provider-agnostic (drives whatever `IssueProvider` it's
- * given) and chain-agnostic (drives whatever `runChain` callback it's
+ * The `spf watch` state machine — two lanes over the same poll loop.
+ *
+ * The build lane: poll -> claim -> run a chain -> PR -> done/blocked.
+ * The refine lane (`watch.refine.enabled`, off by default): poll a
+ * `spec-ready` product spec -> claim -> decompose it into a feature/story
+ * tree -> publish those as real issues -> done/blocked. A spec is not
+ * individually workable, so this lane never opens a PR — it hands the build
+ * lane its next batch of `ready`-able work instead (see `core/refine.ts`).
+ *
+ * Provider-agnostic (drives whatever `IssueProvider` it's given) and
+ * chain-agnostic (drives whatever `runChain`/`runRefine` callback it's
  * given) — deliberately kept out of `src/chains/`'s dependency direction,
- * so this stays testable against a fake provider and a fake `runChain`
- * with no chain registry involved.
+ * so this stays testable against a fake provider and fake callbacks with no
+ * chain registry involved.
  *
  * Design lifted from the user's own GitHub-poller reference implementation
  * (a label-as-state-machine daemon), leaned down for a v1: no per-issue
@@ -30,24 +38,33 @@
 import path from "node:path";
 const MAX_ORPHAN_ATTEMPTS = 2;
 export function createWatchState() {
-    return { inflight: new Set() };
+    return { inflight: new Set(), refining: new Set() };
 }
-export function branchNameFor(issue) {
-    const slug = issue.title
+function slugifyTitle(title) {
+    return (title
         .toLowerCase()
         .split(/\s+/)
         .filter(Boolean)
         .slice(0, 5)
         .join("-")
-        .replace(/[^a-z0-9-]/g, "");
+        .replace(/[^a-z0-9-]/g, "") || "issue");
+}
+export function branchNameFor(issue) {
     // The issue's own id in the branch name isn't just labeling: Jira's
     // Bitbucket integration auto-links a PR to the issue when its key
     // appears anywhere in the branch name, no explicit API call needed.
-    return `spf-watch/${issue.id}-${slug || "issue"}`.slice(0, 200);
+    return `spf-watch/${issue.id}-${slugifyTitle(issue.title)}`.slice(0, 200);
+}
+/** Same idea as `branchNameFor`, for the refine lane's throwaway worktree — a spec never gets a PR, so this branch is only ever fetched-from-and-thrown-away, never pushed. */
+export function refineBranchNameFor(issue) {
+    return `spf-refine/${issue.id}-${slugifyTitle(issue.title)}`.slice(0, 200);
 }
 function worktreePathFor(deps, issue) {
     return path.join(deps.worktreesDir, `issue-${issue.id}`);
 }
+function specWorktreePathFor(deps, issue) {
+    return path.join(deps.worktreesDir, `spec-${issue.id}`);
+}
 function cleanupWorktree(deps, marker) {
     if (!marker)
         return;
@@ -92,6 +109,13 @@ export async function reconcileOrphans(deps, state) {
         }
         else {
             deps.log(`watch: ${issue.id} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail: `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned attempts.`,
+                fields: [["issue", issue.id], ["title", issue.title]],
+            });
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "blocked", `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned attempts.`);
                 cleanupWorktree(deps, marker);
@@ -99,6 +123,78 @@ export async function reconcileOrphans(deps, state) {
         }
     }
 }
+/**
+ * Post the summary comment on a decomposed spec and transition it to `done`
+ * — the refine lane's one shared finishing move, reached from both the
+ * normal path (`runSpec`, right after a successful publish) and the
+ * orphan-resume path (`reconcileRefining`, when a completed publish's
+ * marker survived a crash the `transition` itself didn't). `created` only
+ * has titles/kinds in the normal path — an orphan resume has nothing but
+ * the ids `WatchMarker.refined` recorded, and the comment degrades to a
+ * bare list of `#id`s rather than blocking on a re-fetch.
+ */
+async function finishSpec(deps, issue, created) {
+    const body = created.length > 0
+        ? `spf watch refined this spec into ${created.length} issue(s):\n\n` +
+            created.map((c) => (c.title ? `- #${c.id} (${c.kind}): ${c.title}` : `- #${c.id}`)).join("\n") +
+            `\n\nPromote any of them to \`${deps.labelPrefix}:ready\` when it's worth building.`
+        : `spf watch refined this spec but the refiner produced no issues.`;
+    deps.notify({
+        kind: "spec_refined",
+        level: "info",
+        title: `spec ${issue.id} refined`,
+        detail: `${created.length} issue(s) created.`,
+        fields: [["issue", issue.id], ["title", issue.title], ["created", String(created.length)]],
+    });
+    if (!deps.dryRun) {
+        await deps.provider.comment(issue, body);
+        await deps.provider.transition(issue, "done");
+    }
+}
+/**
+ * The refine lane's own `reconcileOrphans` — a `refining`-labeled spec this
+ * process isn't tracking is either a completed publish that crashed before
+ * its own `transition(issue, "done")` ran (resume: finish it, no re-run),
+ * or a genuine orphan (retry up to `MAX_ORPHAN_ATTEMPTS`, then give up).
+ * A no-op entirely when `watch.refine` is off — see `WatchDeps.refineEnabled`.
+ */
+export async function reconcileRefining(deps, state) {
+    if (!deps.refineEnabled)
+        return;
+    const refining = await deps.provider.listInState("refining");
+    for (const issue of refining) {
+        if (state.refining.has(issue.id))
+            continue;
+        const marker = await deps.provider.readMarker(issue);
+        if (marker?.refined && marker.refined.length > 0) {
+            deps.log(`watch: spec ${issue.id} orphaned after publish already completed — finishing`);
+            await finishSpec(deps, issue, marker.refined.map((id) => ({ id })));
+            continue;
+        }
+        const attempt = (marker?.attempt ?? 0) + 1;
+        if (attempt <= MAX_ORPHAN_ATTEMPTS) {
+            deps.log(`watch: spec ${issue.id} orphaned mid-refine, retry ${attempt}/${MAX_ORPHAN_ATTEMPTS} — back to spec-ready`);
+            if (!deps.dryRun) {
+                await deps.provider.writeMarker(issue, { ...marker, attempt });
+                await deps.provider.transition(issue, "spec-ready");
+            }
+        }
+        else {
+            deps.log(`watch: spec ${issue.id} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `spec ${issue.id} blocked`,
+                detail: `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned refine attempts.`,
+                fields: [["issue", issue.id], ["title", issue.title]],
+            });
+            if (!deps.dryRun) {
+                await deps.provider.transition(issue, "blocked", `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned refine attempts.`);
+                cleanupWorktree(deps, marker);
+            }
+        }
+    }
+}
 /** Poll every `review`-labeled issue's PR for merged (-> done) or closed-without-merging (-> blocked). */
 export async function finishReviews(deps) {
     const reviewing = await deps.provider.listInState("review", { includeAll: true });
@@ -109,6 +205,13 @@ export async function finishReviews(deps) {
         const status = await deps.codeHost.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
         if (status.merged) {
             deps.log(`watch: ${issue.id}'s PR #${marker.pr} merged — done`);
+            deps.notify({
+                kind: "issue_done",
+                level: "info",
+                title: `issue ${issue.id} done`,
+                detail: `PR #${marker.pr} merged.`,
+                fields: [["issue", issue.id], ["title", issue.title], ["pr", `#${marker.pr}`]],
+            });
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "done");
                 cleanupWorktree(deps, marker);
@@ -116,6 +219,13 @@ export async function finishReviews(deps) {
         }
         else if (status.state === "closed") {
             deps.log(`watch: ${issue.id}'s PR #${marker.pr} closed without merging — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail: `PR #${marker.pr} was closed without merging.`,
+                fields: [["issue", issue.id], ["title", issue.title], ["pr", `#${marker.pr}`]],
+            });
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "blocked", `PR #${marker.pr} was closed without merging.`);
                 cleanupWorktree(deps, marker);
@@ -147,13 +257,28 @@ async function runIssue(deps, issue) {
         const result = await deps.runChain({ prompt, cwd: worktreePath, adwId });
         if (!result.accepted) {
             deps.log(`watch: ${issue.id}: chain "${deps.chain}" did not succeed — blocked`);
-            await deps.provider.transition(issue, "blocked", result.detail || `Chain "${deps.chain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`);
+            const detail = result.detail || `Chain "${deps.chain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`;
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail,
+                fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", adwId]],
+            });
+            await deps.provider.transition(issue, "blocked", detail);
             cleanupWorktree(deps, { worktree: worktreePath, branch });
             return;
         }
         const wtGit = deps.worktreeGit(worktreePath);
         if (wtGit.diffFiles(`origin/${deps.baseBranch}`).length === 0) {
             deps.log(`watch: ${issue.id}: chain succeeded but committed nothing — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail: `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`,
+                fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", adwId]],
+            });
             await deps.provider.transition(issue, "blocked", `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`);
             cleanupWorktree(deps, { worktree: worktreePath, branch });
             return;
@@ -173,14 +298,94 @@ async function runIssue(deps, issue) {
         await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, pr: pr.number, attempt: 0 });
         await deps.provider.transition(issue, "review");
         deps.log(`watch: ${issue.id}: opened PR #${pr.number} — review`);
+        deps.notify({
+            kind: "pr_opened",
+            level: "info",
+            title: `PR #${pr.number} opened`,
+            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain]],
+            url: pr.url || undefined,
+        });
     }
     catch (error) {
         const message = error.message;
         deps.log(`watch: ${issue.id}: error: ${message}`);
+        deps.notify({
+            kind: "watch_error",
+            level: "error",
+            title: `issue ${issue.id} errored`,
+            detail: message,
+            fields: [["issue", issue.id], ["title", issue.title]],
+        });
         await deps.provider.transition(issue, "blocked", `spf watch error: ${message}`).catch(() => undefined);
         cleanupWorktree(deps, { worktree: worktreePath, branch });
     }
 }
+/**
+ * One spec's full claim -> decompose -> publish path, run in the background
+ * — `claimSpecs` doesn't await this. The build lane's `runIssue`, minus the
+ * PR half: no `diffFiles` check (the refiner has `writes: []`, so an empty
+ * diff is the CORRECT outcome, not a failure), no push, no `openPr`. Its
+ * mirror image is "publish, then finish" instead of "commit, then review".
+ */
+async function runSpec(deps, issue) {
+    const branch = refineBranchNameFor(issue);
+    const worktreePath = specWorktreePathFor(deps, issue);
+    const adwId = `spec-${issue.id}`;
+    try {
+        // A spec re-claimed after a completed publish (the transition/comment
+        // that should have followed never ran — a crash, a kill) already has
+        // its answer on disk: skip straight to finishing rather than asking the
+        // refiner to redo work that already exists on the tracker. `to-tickets`
+        // (the skill this lane's prompt is ported from) has no such guard and
+        // would duplicate every issue on a re-run.
+        const existingMarker = await deps.provider.readMarker(issue);
+        if (existingMarker?.refined && existingMarker.refined.length > 0) {
+            deps.log(`watch: spec ${issue.id}: a previous attempt already published ${existingMarker.refined.length} issue(s) — finishing without re-running the refiner`);
+            await finishSpec(deps, issue, existingMarker.refined.map((id) => ({ id })));
+            return;
+        }
+        // See runIssue's identical comment: worktreePath/branch are deterministic
+        // from issue.id, so a leftover from a killed prior attempt is the only
+        // way either could already exist — clear it unconditionally.
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
+        deps.git.fetch("origin", deps.baseBranch);
+        deps.git.worktreeAdd(worktreePath, branch, `origin/${deps.baseBranch}`);
+        deps.linkDataDir(worktreePath);
+        await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, attempt: 0 });
+        const prompt = `${issue.title}\n\n${issue.body}`.trim();
+        const result = await deps.runRefine({ prompt, cwd: worktreePath, adwId, issueId: issue.id });
+        if (!result.accepted) {
+            deps.log(`watch: spec ${issue.id}: refine chain "${deps.refineChain}" did not succeed — blocked`);
+            const detail = result.detail || `Refine chain "${deps.refineChain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`;
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `spec ${issue.id} blocked`,
+                detail,
+                fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.refineChain], ["adw_id", adwId]],
+            });
+            await deps.provider.transition(issue, "blocked", detail);
+            cleanupWorktree(deps, { worktree: worktreePath, branch });
+            return;
+        }
+        await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, attempt: 0, refined: result.created.map((c) => c.id) });
+        await finishSpec(deps, issue, result.created);
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
+    }
+    catch (error) {
+        const message = error.message;
+        deps.log(`watch: spec ${issue.id}: refine error: ${message}`);
+        deps.notify({
+            kind: "watch_error",
+            level: "error",
+            title: `spec ${issue.id} errored`,
+            detail: message,
+            fields: [["issue", issue.id], ["title", issue.title]],
+        });
+        await deps.provider.transition(issue, "blocked", `spf watch refine error: ${message}`).catch(() => undefined);
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
+    }
+}
 /** Claim as many `ready` issues as the concurrency budget allows, and kick off `runIssue` for each in the background. */
 export async function claimNewWork(deps, state) {
     if (state.inflight.size >= deps.concurrency)
@@ -201,13 +406,60 @@ export async function claimNewWork(deps, state) {
             continue;
         }
         deps.log(`watch: claimed ${issue.id}: ${issue.title}`);
+        deps.notify({
+            kind: "issue_claimed",
+            level: "info",
+            title: `issue ${issue.id} claimed`,
+            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain]],
+        });
         state.inflight.add(issue.id);
         runIssue(deps, issue).finally(() => state.inflight.delete(issue.id));
     }
 }
-/** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */
+/** Claim as many `spec-ready` specs as `refineConcurrency` allows, and kick off `runSpec` for each in the background. A no-op when `watch.refine` is off. */
+export async function claimSpecs(deps, state) {
+    if (!deps.refineEnabled)
+        return;
+    if (state.refining.size >= deps.refineConcurrency)
+        return;
+    const eligible = await deps.provider.listInState("spec-ready");
+    for (const issue of eligible) {
+        if (state.refining.size >= deps.refineConcurrency)
+            break;
+        if (state.refining.has(issue.id))
+            continue;
+        if (deps.dryRun) {
+            deps.log(`watch: [dry-run] would claim spec ${issue.id} (${issue.title}) and run refine chain "${deps.refineChain}"`);
+            continue;
+        }
+        const claimed = await deps.provider.claim(issue, { from: "spec-ready", to: "refining" });
+        if (!claimed) {
+            deps.log(`watch: spec ${issue.id} lost the claim race this tick — skipping`);
+            continue;
+        }
+        deps.log(`watch: claimed spec ${issue.id}: ${issue.title}`);
+        deps.notify({
+            kind: "issue_claimed",
+            level: "info",
+            title: `spec ${issue.id} claimed`,
+            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.refineChain]],
+        });
+        state.refining.add(issue.id);
+        runSpec(deps, issue).finally(() => state.refining.delete(issue.id));
+    }
+}
+function tickErrorHandler(deps, stage) {
+    return (error) => {
+        const message = error.message;
+        deps.log(`watch: ${stage} error: ${message}`);
+        deps.notify({ kind: "watch_error", level: "error", title: `watch: ${stage} error`, detail: message, fields: [] });
+    };
+}
+/** One poll tick: reconcile both lanes, finish reviews, then claim both lanes — each stage independently caught, so one stage's error never blocks the rest. */
 export async function tick(deps, state) {
-    await reconcileOrphans(deps, state).catch((error) => deps.log(`watch: reconcileOrphans error: ${error.message}`));
-    await finishReviews(deps).catch((error) => deps.log(`watch: finishReviews error: ${error.message}`));
-    await claimNewWork(deps, state).catch((error) => deps.log(`watch: claimNewWork error: ${error.message}`));
+    await reconcileOrphans(deps, state).catch(tickErrorHandler(deps, "reconcileOrphans"));
+    await reconcileRefining(deps, state).catch(tickErrorHandler(deps, "reconcileRefining"));
+    await finishReviews(deps).catch(tickErrorHandler(deps, "finishReviews"));
+    await claimSpecs(deps, state).catch(tickErrorHandler(deps, "claimSpecs"));
+    await claimNewWork(deps, state).catch(tickErrorHandler(deps, "claimNewWork"));
 }

package/dist/test/chains.test.js

@@ -41,6 +41,7 @@ const EXPECTED = {
     },
     quality: { phases: "engineer(request) -> code(quality)", agents: [], suites: ["all"] },
     document: { phases: "engineer(request) -> code(changes) -> documenter", agents: ["documenter"], suites: [] },
+    refine: { phases: "engineer(request) -> refiner -> code(publish)", agents: ["refiner"], suites: [] },
     "simple-sdlc": {
         phases: "engineer(request) -> planner -> git(commit_plan) -> builder -> code(test) [-> builder(fix) -> code(test) ...] " +
             "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> git(commit_build) " +

package/dist/test/data_types.test.js

@@ -9,9 +9,13 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import * as v from "valibot";
 import { toJsonSchema } from "@valibot/to-json-schema";
-import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, GenericOutput, PhaseParamsSchema, PlanOutput, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
+import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, GenericOutput, NotificationsConfigSchema, PhaseParamsSchema, PlanOutput, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
+import { loadConfig } from "../core/agents.js";
 test("writes: three-state semantics — absent, null, and [] all mean something different", () => {
     const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
     const unrestricted = v.parse(AgentConfigSchema, base);
@@ -47,3 +51,32 @@ test("every envelope type still converts to JSON Schema (the sf_report tool wiri
 test("PhaseParamsSchema itself (the one schema WITH a rawTransform) correctly refuses JSON Schema conversion", () => {
     assert.throws(() => toJsonSchema(PhaseParamsSchema), /raw_transform/);
 });
+test("NotificationsConfigSchema defaults to off, no channels", () => {
+    const parsed = v.parse(NotificationsConfigSchema, {});
+    assert.equal(parsed.events, "off");
+    assert.equal(parsed.timeout_ms, 5_000);
+    assert.deepEqual(parsed.channels, []);
+});
+test("a channel's own `events` overrides the top-level scope; unset inherits it", () => {
+    const parsed = v.parse(NotificationsConfigSchema, {
+        events: "errors",
+        channels: [{ kind: "slack" }, { kind: "teams", events: "all" }],
+    });
+    assert.equal(parsed.channels[0].events, undefined, "unset per-channel scope stays undefined, not defaulted to the top-level value — the caller inherits at read time");
+    assert.equal(parsed.channels[1].events, "all");
+});
+test("notifications survives loadConfig's merge — key-by-key like observability/quality, channels replaced wholesale on override", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-notify-merge-test-"));
+    try {
+        const base = join(dir, "base.yaml");
+        const override = join(dir, "override.yaml");
+        writeFileSync(base, "notifications:\n  events: off\n  channels:\n    - {kind: webhook, webhook_url_env: BASE_HOOK}\n");
+        writeFileSync(override, "notifications:\n  events: all\n  channels:\n    - {kind: slack, webhook_url_env: SLACK_WEBHOOK_URL}\n");
+        const cfg = loadConfig([base, override]);
+        assert.equal(cfg.notifications.events, "all", "events: key-by-key, override wins");
+        assert.deepEqual(cfg.notifications.channels.map((c) => c.kind), ["slack"], "channels: a whole-array replace, not an append — same semantics as quality.checks");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/test/init_command.test.js

@@ -64,3 +64,20 @@ test("never writes .env or .env.example on the non-interactive paths", async ()
     assert.equal(existsSync(join(dir, ".env")), false);
     assert.equal(existsSync(join(dir, ".env.example")), false);
 });
+test("also installs the repo-local Claude Code skill by default, on every non-interactive path", async () => {
+    const code = await initCommand(["--cwd", dir, "--yes"]);
+    assert.equal(code, 0);
+    assert.ok(existsSync(join(dir, ".claude", "skills", "spf", "SKILL.md")), "spf init should install the skill unless --no-skills is passed");
+});
+test("--no-skills skips the skill install", async () => {
+    const code = await initCommand(["--cwd", dir, "--yes", "--no-skills"]);
+    assert.equal(code, 0);
+    assert.equal(existsSync(join(dir, ".claude", "skills", "spf")), false);
+});
+test("re-running spf init doesn't re-copy an unchanged skill install (install-skill's own idempotency)", async () => {
+    await initCommand(["--cwd", dir, "--yes"]);
+    const manifestPath = join(dir, ".claude", "skills", "spf", ".spf-skill-version");
+    const before = readFileSync(manifestPath, "utf-8");
+    await initCommand(["--cwd", dir, "--template", "ts-cc"]); // no --force: config write is a no-op, skill install still runs
+    assert.equal(readFileSync(manifestPath, "utf-8"), before);
+});

package/dist/test/interview.test.js

@@ -151,6 +151,125 @@ test("declining the final confirm returns null — nothing to write", async () =
     const result = await runInterview(asker, ctx);
     assert.equal(result, null);
 });
+test("notifications: declining the gate leaves config.notifications undefined", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "sonnet", Authentication: "login" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.notifications, undefined);
+});
+test("notifications: accepting collects the scope, a channel, and its webhook env key", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Notify on": "all",
+            Channel: "slack",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Send notifications": true,
+            "Add another channel": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { SLACK_WEBHOOK_URL: "https://hooks.slack.com/services/T000/B000/XXXX" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.notifications.events, "all");
+    assert.deepEqual(config.notifications.channels, [{ kind: "slack", webhook_url_env: "SLACK_WEBHOOK_URL" }]);
+    assert.equal(result.env.SLACK_WEBHOOK_URL, "https://hooks.slack.com/services/T000/B000/XXXX");
+    assert.ok(result.envExampleKeys.includes("SLACK_WEBHOOK_URL"));
+    // The written document must still merge and validate cleanly, same
+    // pipeline `spf doctor` runs.
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    assert.equal(cfg.notifications.events, "all");
+    assert.equal(cfg.notifications.channels[0].kind, "slack");
+});
+test("customize models per agent: declining keeps today's behavior — only the three pinned agents, all matching defaults.model", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "opus", Authentication: "login" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Customize models per agent": false,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.deepEqual(config.agents.map((a) => a.name).sort(), ["documenter", "planner", "reviewer"]);
+    for (const a of config.agents)
+        assert.equal(a.model, "opus");
+});
+test("customize models per agent: accepting patches the pinned three and appends builder/scout/refiner", async () => {
+    const ctx = gatherContext(dir, new Map());
+    assert.deepEqual(ctx.rosterNames.slice().sort(), ["builder", "documenter", "planner", "refiner", "reviewer", "scout"]);
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "sonnet", Authentication: "login" },
+        text: {
+            "  planner": "opus",
+            "  builder": "sonnet",
+            "  scout": "haiku",
+            "  refiner": "opus",
+            "  reviewer": "opus",
+            "  documenter": "sonnet",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Customize models per agent": true,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    const byName = Object.fromEntries(config.agents.map((a) => [a.name, a.model]));
+    assert.deepEqual(byName, { planner: "opus", reviewer: "opus", documenter: "sonnet", builder: "sonnet", scout: "haiku", refiner: "opus" });
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    validate(cfg, cfg.agents.map((a) => a.name), Object.keys(cfg.quality.suites), dir); // throws on any problem
+    assert.equal(cfg.agents.find((a) => a.name === "scout").model, "haiku");
+});
 test("an existing .env value is offered back as the default when a secret is left blank", async () => {
     const ctx = gatherContext(dir, new Map([["GITHUB_TOKEN", "ghp_existingvalue"]]));
     const asker = createFakeAsker({

package/dist/test/notify.test.d.ts

@@ -0,0 +1 @@
+export {};