@gr8ful/spf 0.2.1 → 0.3.0

package/README.md

@@ -34,7 +34,7 @@ spf init --template ts-cc      # or start from a packaged, ready-to-run template
 spf list                       # every chain this install knows, its phases, what it needs
 ```
 
-On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code` or `flue`) and model, which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
+On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code` or `flue`) and model (optionally customized per agent instead of one model for the whole roster), which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host, and whether to push notifications to Slack/Teams/a webhook — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
 
 Without an interview, `spf init` writes the same small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field. `--template <name>` writes a real, filled-in config instead of the commented-out starter — every packaged template's name prints after `spf init` runs, and the same files live in [`assets/templates/`](assets/templates/) to browse directly. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
 
@@ -322,6 +322,56 @@ export BITBUCKET_API_TOKEN=...   # same Atlassian API token mechanism as Jira ab
 
 **Bitbucket Cloud app passwords are being fully removed** (brownout window closing July 28, 2026) — this project only supports the replacement, API tokens, which need the account's email alongside the token (username alone no longer works).
 
+## Notifications
+
+Optional, off by default: push a curated set of milestones to Slack,
+Microsoft Teams, or a generic webhook. It's scoped to **unattended work**:
+`spf watch`'s daemon lifecycle, and every chain run (`spf <chain>` / `spf
+run`, including watch's own per-issue runs). Interactive commands — `doctor`,
+`list`, `sessions`, `phases`, `events`, `init`, `ui`, `migrate`, `eject`,
+`abort`, `version` — never notify; you're already looking at the terminal
+for those.
+
+```yaml
+# .spf/spf.config.yaml
+notifications:
+  events: errors            # off (default) | errors | all
+  channels:
+    - kind: slack            # slack | teams | webhook
+      webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
+```
+
+`events` is the whole filter: `errors` sends only failed runs/phases, blocked
+issues, and watch errors; `all` adds every milestone — run started/finished,
+issue claimed, PR opened, issue done. A channel's own `events` overrides the
+top-level scope for just that channel. `spf doctor` reports whether each
+configured channel's env var is set.
+
+The webhook URL is a secret and lives only in `.env` — `webhook_url_env`
+names the key, never the URL itself, matching `GITHUB_TOKEN`/
+`JIRA_API_TOKEN`. Defaults per kind: `SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`,
+`SPF_WEBHOOK_URL`. `spf init`'s interview asks for this section and collects
+the URL straight into `.env`, same as every other credential.
+
+Getting each channel's URL:
+
+- **Slack** — [Sending messages using Incoming Webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks): create a Slack app, enable Incoming Webhooks, "Add New Webhook to Workspace".
+- **Microsoft Teams** — [Send messages in Teams using incoming webhooks](https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498): in the target channel, add a Workflows webhook template (search for one along the lines of "Post to a channel when a webhook request is received" / "Send webhook alerts to a channel" — Microsoft's own naming here has shifted between revisions) and copy the generated URL. This is the *only* supported path now — the old Office 365 connector webhook has been retired by Microsoft.
+- **webhook** — any endpoint that accepts a JSON POST of the event: Discord,
+  n8n, Zapier, a homegrown receiver.
+
+Delivery never blocks or fails a run: an unconfigured/misconfigured channel
+is skipped with one warning, and a failed POST logs one line and is
+swallowed — never changes a run's exit code. One thing worth knowing under
+`events: all`: `spf watch` runs its per-issue chains in-process, so a failed
+issue produces **two** notifications for the same failure — `run_failed`
+(keyed to the chain's own `adw_id`, e.g. `issue-142`) from the chain-run
+side, and `issue_blocked` (keyed to the issue) from watch itself. Both are
+genuinely informative, just worth expecting.
+
+Full field reference: `spf install-skill`'s installed skill
+(`references/config.md`).
+
 ## What's in this repo
 
 ```

package/assets/skill/references/config.md

@@ -12,9 +12,10 @@ always shows the resolved, merged result for the repo you're in.
 1. The packaged built-in default (`assets/defaults/spf.config.yaml` inside
    the installed CLI).
 2. `.spf/spf.config.yaml` in the target repo, if present — merged on top,
-   field by field (`defaults`/`observability`/`quality` merge key-by-key;
-   `agents` merges by `name`: a matching name patches that entry, a new name
-   appends).
+   field by field (`defaults`/`observability`/`quality`/`watch`/`notifications`
+   merge key-by-key — `notifications.channels` replaces wholesale, same as
+   `quality.checks`; `agents` merges by `name`: a matching name patches that
+   entry, a new name appends).
 3. An explicit `--config <path>` replaces both — standalone, no built-in
    underneath it.
 
@@ -107,6 +108,49 @@ sections: `assets/templates/ts.spf.config.yaml` in the spf package (or
 `spf init --template ts` to write it straight into `.spf/spf.config.yaml`).
 `spf init` with no `--template` prints every packaged template's name.
 
+### `notifications`
+
+Optional outbound push for unattended work — `spf watch`'s daemon lifecycle,
+and every chain run (`spf <chain>` / `spf run`, including watch's own
+per-issue runs). Interactive commands (`doctor`, `list`, `sessions`,
+`phases`, `events`, `init`, `ui`, `migrate`, `eject`, `abort`, `version`)
+never notify — you're already looking at the terminal for those. Off by
+default; adding it is entirely additive.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `events` | `"off"` \| `"errors"` \| `"all"` | The whole filter. `off` (default): nothing. `errors`: only failed runs/phases, blocked issues, watch errors. `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus errors. |
+| `timeout_ms` | int | Per-request timeout for a channel's HTTP POST. Default `5000`. |
+| `channels[]` | array | See below. |
+
+`channels[].kind`: `"slack"` \| `"teams"` \| `"webhook"`. `channels[].events`
+overrides `events` for just that channel (unset = inherit). `webhook_url_env`
+names the `.env` key holding the secret URL — never the URL itself, matching
+`GITHUB_TOKEN`/`JIRA_API_TOKEN`. Empty/omitted uses the kind's own default:
+`SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`, `SPF_WEBHOOK_URL`. `name` is a
+cosmetic label for warning lines when you have two channels of the same
+kind.
+
+```yaml
+notifications:
+  events: errors
+  channels:
+    - kind: slack
+      webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
+    - kind: teams
+      events: all                           # per-channel override
+    - kind: webhook
+      webhook_url_env: OPS_WEBHOOK_URL
+      name: ops-bus
+```
+
+Delivery never blocks or fails a run: a channel with an unset env var is
+skipped with one warning at startup (`spf doctor` reports the same thing as
+a check); a failed POST logs one line and is swallowed, never changing the
+run's exit code. See the main README's "Notifications" section for how to
+get each channel's webhook URL, and `spf init`'s interview, which asks for
+this section and collects the URL straight into `.env`.
+
 ### `agents[]`
 
 | Field | Required | Meaning |

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

@@ -64,3 +64,15 @@ agents:
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+
+# Optional: push notifications for unattended work — spf watch's daemon
+# lifecycle, and every chain run (including watch's own per-issue runs).
+# Interactive commands (doctor, list, sessions, ...) never notify. events:
+# "errors" sends only failures/blocked issues; "all" adds every milestone.
+# The webhook URL is a secret — put it in .env under the key named below,
+# never here. See the main README's "Notifications" section.
+# notifications:
+#   events: errors            # off (default) | errors | all
+#   channels:
+#     - kind: slack            # slack | teams | webhook
+#       webhook_url_env: SLACK_WEBHOOK_URL

package/dist/cli/commands/doctor.js

@@ -13,6 +13,7 @@ import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
 import * as permissions from "../../core/permissions.js";
 import * as agentCc from "../../core/agent_cc.js";
+import { DEFAULT_NOTIFY_ENV_KEY } from "../../core/notify/notifier.js";
 import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
 import { binaryOnPath, parseCli } from "../../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
@@ -143,6 +144,17 @@ export function doctorCommand(argv) {
         }
         check(report, "watch.chain", Boolean(findChain(cfg.watch.chain)), findChain(cfg.watch.chain) ? cfg.watch.chain : `"${cfg.watch.chain}" is not a registered chain`);
     }
+    if (cfg.notifications.events !== "off") {
+        check(report, "notifications.events", true, cfg.notifications.events);
+        if (cfg.notifications.channels.length === 0) {
+            check(report, "notifications.channels", false, `notifications.events is ${JSON.stringify(cfg.notifications.events)} but no channels are configured`);
+        }
+        for (const ch of cfg.notifications.channels) {
+            const envKey = ch.webhook_url_env || DEFAULT_NOTIFY_ENV_KEY[ch.kind];
+            const label = ch.name ? `${ch.kind} (${ch.name})` : ch.kind;
+            check(report, `notifications: ${label}`, Boolean(process.env[envKey]), process.env[envKey] ? `${envKey} set` : `${envKey} is not set`);
+        }
+    }
     return finish(report, flags["json"]);
 }
 function finish(report, json) {

package/dist/cli/commands/init.js

@@ -86,6 +86,20 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+
+# Uncomment to push notifications for unattended work — spf watch's daemon
+# lifecycle, and every chain run (spf <chain> / spf run, including watch's
+# own per-issue runs). Interactive commands (doctor, list, sessions, ...)
+# never notify — you're already looking at the terminal for those. events:
+# "errors" sends only failures/blocked issues; "all" adds every milestone
+# (run started, issue claimed, PR opened, ...). The URL is a secret and
+# lives only in .env — never in this file. See README.md's "Notifications"
+# section for how to get each webhook URL.
+# notifications:
+#   events: errors            # off (default) | errors | all
+#   channels:
+#     - kind: slack            # slack | teams | webhook
+#       webhook_url_env: SLACK_WEBHOOK_URL   # default for slack; TEAMS_WEBHOOK_URL / SPF_WEBHOOK_URL for the others
 `;
 // .spf/spf.config.yaml and .spf/prompt_engineering/ stay tracked — they're
 // shared project config, same as package.json. Only runtime/generated

package/dist/cli/commands/watch.js

@@ -10,6 +10,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
+import { resolveNotifier } from "../../core/notify/notifier.js";
 import { isRepoAt, makeGit } from "../../core/git_helper.js";
 import { GitHubProvider } from "../../core/issues/github_provider.js";
 import { JiraProvider } from "../../core/issues/jira_provider.js";
@@ -161,6 +162,9 @@ export async function watchCommand(argv) {
     const git = makeGit(anchor.repo_root);
     const worktreesDir = path.join(homedir(), ".spf", "watch", path.basename(anchor.repo_root), "worktrees");
     mkdirSync(worktreesDir, { recursive: true });
+    // `null` when notifications are off/unconfigured — every call below is a
+    // no-op fallback to `console.error` in that case (see notify()`s default).
+    const notifier = resolveNotifier(cfg, { dryRun: Boolean(flags["dry-run"]) });
     /**
      * Without this, a claimed issue's chain resolves its session/trace data
      * relative to `cwd` (the worktree, not the main repo — see
@@ -216,6 +220,7 @@ export async function watchCommand(argv) {
         dryRun: Boolean(flags["dry-run"]),
         runChain,
         log: (message) => console.log(message),
+        notify: (event) => notifier?.send(event),
     };
     const state = createWatchState();
     let stopping = false;
@@ -250,6 +255,16 @@ 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)" : ""}`);
+    deps.notify({
+        kind: "watch_started",
+        level: "info",
+        title: "watch started",
+        fields: [
+            ["repo", cfg.watch.repo],
+            ["label_prefix", cfg.watch.label_prefix],
+            ["chain", cfg.watch.chain],
+        ],
+    });
     try {
         for (;;) {
             await tick(deps, state);
@@ -268,6 +283,8 @@ export async function watchCommand(argv) {
         return 0;
     }
     finally {
+        deps.notify({ kind: "watch_stopped", level: "info", title: "watch stopped", fields: [["repo", cfg.watch.repo]] });
+        await notifier?.flush();
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
         releaseLock(lockPath);

package/dist/cli/index.js

@@ -7,6 +7,7 @@
 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 paths from "../core/paths.js";
 import { findChain } from "../chains/index.js";
 import { dispatchChain, usageFor } from "./commands/run.js";
@@ -152,5 +153,8 @@ export async function main() {
         // agent_cc.ts's shutdown() just kills any still-running claude children.
         await agentFlue.shutdown();
         await agentCc.shutdown();
+        // 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();
     }
 }

package/dist/cli/interview.d.ts

@@ -8,6 +8,8 @@ export interface DetectedContext {
     claudeOnPath: boolean;
     /** Whatever's already in `.env` — shown masked so a re-run can offer "keep current" instead of asking blind. */
     existingEnv: Map<string, string>;
+    /** The packaged roster's agent names (planner, builder, scout, reviewer, documenter today) — read from the built-in config so a 6th agent added there needs no interview change. */
+    rosterNames: string[];
 }
 export declare function gatherContext(repoRoot: string, existingEnv?: Map<string, string>): DetectedContext;
 export interface InterviewResult {

package/dist/cli/interview.js

@@ -18,6 +18,9 @@ import { binaryOnPath } from "../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../core/providers.js";
 import { resolveModel } from "../core/agent_flue.js";
 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";
 function gitConfigValue(repoRoot, key) {
     const result = spawnSync("git", ["config", key], { cwd: repoRoot, encoding: "utf-8" });
@@ -40,6 +43,15 @@ function readScripts(repoRoot) {
         return {};
     }
 }
+/** Best-effort — a corrupt/missing built-in config falls back to the three names the auto-override already knows about, rather than failing the whole interview. */
+function readRosterNames() {
+    try {
+        return loadConfig([BUILTIN_CONFIG_PATH]).agents.map((a) => a.name);
+    }
+    catch {
+        return ["planner", "builder", "scout", "reviewer", "documenter"];
+    }
+}
 export function gatherContext(repoRoot, existingEnv = new Map()) {
     const remote = spawnSync("git", ["config", "--get", "remote.origin.url"], { cwd: repoRoot, encoding: "utf-8" });
     const branch = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot, encoding: "utf-8" });
@@ -51,6 +63,7 @@ export function gatherContext(repoRoot, existingEnv = new Map()) {
         scripts: readScripts(repoRoot),
         claudeOnPath: binaryOnPath("claude"),
         existingEnv,
+        rosterNames: readRosterNames(),
     };
 }
 const QUALITY_TIMEOUTS = { typecheck: 60, lint: 60, build: 120, test: 180 };
@@ -79,7 +92,7 @@ export async function runInterview(asker, ctx) {
         if (!ctx.claudeOnPath) {
             asker.note("warning: `claude` was not found on PATH — install it (or set a launch command below) before running spf.");
         }
-        const launchCommand = await asker.text("Launch command for the `claude` CLI (space-separated; SPF_CLAUDE_CMD)", { default: "claude" });
+        const launchCommand = await asker.text('Launch command for the `claude` CLI — e.g. "ollama launch claude" to route through a wrapper (SPF_CLAUDE_CMD)', { default: "claude" });
         if (launchCommand !== "claude")
             env["SPF_CLAUDE_CMD"] = launchCommand;
         const model = await asker.select("Model (Claude Code's own vocabulary — not provider/model-id)", [
@@ -142,6 +155,34 @@ export async function runInterview(asker, ctx) {
             env[envKey] = key;
         envExampleKeys.push(envKey);
     }
+    // Declined (the default): today's behavior exactly — on claude_code, the
+    // three-agent auto-pin above stands unchanged; on flue, no agents: block
+    // at all. Accepted: ask every roster agent's model, defaulting to the one
+    // chosen above, and patch/append its override — `mergeAgentLists`
+    // (agents.ts:63-71) shallow-patches by name, so re-setting `model` on an
+    // already-pinned entry (claude_code's planner/reviewer/documenter) is
+    // exactly the right shape, no `prompt_engineering` needed (interview.ts's
+    // review-section comment explains why that's fine).
+    const customizeModels = await asker.confirm("Customize models per agent?", false);
+    if (customizeModels) {
+        asker.heading("Per-agent models");
+        for (const name of ctx.rosterNames) {
+            const answer = await asker.text(`  ${name}`, { default: String(defaults.model) });
+            if (codingAgent === "flue") {
+                try {
+                    resolveModel(answer);
+                }
+                catch (error) {
+                    asker.note(`warning: ${error.message}`);
+                }
+            }
+            const existing = agentOverrides.find((a) => a.name === name);
+            if (existing)
+                existing.model = answer;
+            else
+                agentOverrides.push({ name, model: answer });
+        }
+    }
     // ── 2. quality checks ──────────────────────────────────────────────────────
     asker.heading("Quality checks");
     asker.note("a chain that gates on a suite (e.g. plan-build-test's `test`) fails loudly before anything runs if the suite is unconfigured.");
@@ -227,7 +268,46 @@ export async function runInterview(asker, ctx) {
             asker.note("Bitbucket app passwords are being removed — this needs an Atlassian API token instead.");
         }
     }
-    // ── 4. advanced (gated) ─────────────────────────────────────────────────────
+    // ── 4. notifications ─────────────────────────────────────────────────────────
+    asker.heading("Notifications");
+    const enableNotify = await asker.confirm("Send notifications to Slack, Teams, or a webhook?", false);
+    let notifications = null;
+    if (enableNotify) {
+        const events = await asker.select("Notify on", [
+            { value: "errors", label: "errors — failed runs, blocked issues, watch errors" },
+            { value: "all", label: "all — every milestone (claimed, PR opened, done, ...) plus errors" },
+        ], "errors");
+        const channels = [];
+        for (;;) {
+            const kind = await asker.select("Channel", [
+                { value: "slack", label: "Slack — Incoming Webhook" },
+                { value: "teams", label: "Microsoft Teams — Workflows webhook" },
+                { value: "webhook", label: "generic webhook — POSTs the raw event as JSON" },
+            ], "slack");
+            const envKey = DEFAULT_NOTIFY_ENV_KEY[kind];
+            if (kind === "slack") {
+                asker.note("Slack app -> Incoming Webhooks -> Add New Webhook to Workspace.");
+                asker.note("Docs: https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks");
+            }
+            else if (kind === "teams") {
+                asker.note("In the target channel, add a Workflows webhook template (search for one like \"Post to a channel when a webhook request is received\"). The old Office 365 connector webhooks are retired — this is the only path now.");
+                asker.note("Docs: https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498");
+            }
+            else {
+                asker.note("Any endpoint that accepts a JSON POST — Discord, n8n, Zapier, your own.");
+            }
+            const url = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
+            if (url)
+                env[envKey] = url;
+            envExampleKeys.push(envKey);
+            channels.push({ kind, webhook_url_env: envKey });
+            const another = await asker.confirm("Add another channel?", false);
+            if (!another)
+                break;
+        }
+        notifications = { events, channels };
+    }
+    // ── 5. advanced (gated) ─────────────────────────────────────────────────────
     const wantAdvanced = await asker.confirm("\nConfigure advanced settings (thinking level, tools, protected files, data dir, poll intervals, ...)?", false);
     if (wantAdvanced) {
         asker.heading("Advanced");
@@ -263,8 +343,13 @@ export async function runInterview(asker, ctx) {
             if (debug)
                 env["SPF_JIRA_DEBUG"] = "1";
         }
+        if (notifications) {
+            const timeoutMs = await asker.text("notifications.timeout_ms", { default: "5000" });
+            if (timeoutMs !== "5000")
+                notifications.timeout_ms = Number(timeoutMs);
+        }
     }
-    // ── 5. review + confirm ─────────────────────────────────────────────────────
+    // ── 6. review + confirm ─────────────────────────────────────────────────────
     const observability = defaults["__observability__"];
     delete defaults["__observability__"];
     const quality = defaults["__quality__"];
@@ -278,6 +363,8 @@ export async function runInterview(asker, ctx) {
         config.watch = watch;
     if (observability)
         config.observability = observability;
+    if (notifications)
+        config.notifications = notifications;
     // No schema validation here on purpose: `config.agents` overrides are
     // intentionally PARTIAL (name + model only, no prompt_engineering) — valid
     // only once merged by name into the packaged roster (agents.ts's

package/dist/core/agents.js

@@ -57,13 +57,16 @@ function mergeAgentLists(base, override) {
     }
     return merged;
 }
-/** `defaults`/`observability`/`quality` merge key-by-key; `agents` merges by name. */
+/** `defaults`/`observability`/`quality`/`watch`/`notifications` merge key-by-key; `agents` merges by name. */
 function mergeRawConfig(base, override) {
     return {
         defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
         observability: { ...(base.observability || {}), ...(override.observability || {}) },
         quality: { ...(base.quality || {}), ...(override.quality || {}) },
         watch: { ...(base.watch || {}), ...(override.watch || {}) },
+        // channels is a whole-array replace on override, same as quality.checks —
+        // you don't want an override's channels appended to the built-in's.
+        notifications: { ...(base.notifications || {}), ...(override.notifications || {}) },
         agents: mergeAgentLists(base.agents || [], override.agents || []),
     };
 }

package/dist/core/console.d.ts

@@ -7,6 +7,10 @@
  * so a CI log reads exactly like a terminal.
  */
 import type { EnvelopeBase, EventRecord, GateReport, Phase } from "./data_types.ts";
+import type { NotifyEvent } from "./notify/channel.ts";
+interface Notifier {
+    send(event: NotifyEvent): void;
+}
 export declare function paint(style: string, text: string): string;
 interface Tracer {
     event(record: EventRecord): string;
@@ -15,11 +19,19 @@ interface Tracer {
 export declare class Console {
     private tracer;
     private adwId;
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    private notifier;
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    private chainName;
     private phaseId;
     private phaseName;
     private results;
     private finished;
-    constructor(tracer: Tracer, adwId: string);
+    constructor(tracer: Tracer, adwId: string, 
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    notifier?: Notifier | null, 
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    chainName?: string);
     private emit;
     sessionStarted(adwId: string, engineer: string): void;
     sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): void;

package/dist/core/console.js

@@ -45,13 +45,21 @@ function panel(lines, title, borderColor) {
 export class Console {
     tracer;
     adwId;
+    notifier;
+    chainName;
     phaseId = ""; // current lane — log events attach to it
     phaseName = "";
     results = []; // phase statuses, for the summary
     finished = false; // the summary panel prints once
-    constructor(tracer, adwId) {
+    constructor(tracer, adwId, 
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    notifier = null, 
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    chainName = "adw") {
         this.tracer = tracer;
         this.adwId = adwId;
+        this.notifier = notifier;
+        this.chainName = chainName;
     }
     // ── the one helper: print AND trace, always together ────────────────────
     emit(line, level = "info") {
@@ -67,6 +75,15 @@ export class Console {
     // ── session ─────────────────────────────────────────────────────────────
     sessionStarted(adwId, engineer) {
         this.emit(`${paint("bold cyan", "adw_id:")} ${paint("bold", adwId)}   ${paint("dim", "engineer")} ${engineer}`);
+        this.notifier?.send({
+            kind: "run_started",
+            level: "info",
+            title: `run started — ${this.chainName}`,
+            fields: [
+                ["adw_id", adwId],
+                ["engineer", engineer],
+            ],
+        });
     }
     sessionFinished(ok, tokens, cost, dbPath) {
         if (this.finished)
@@ -93,6 +110,17 @@ export class Console {
             name: this.phaseName || "console",
             payload: { message: plain, level: ok ? "info" : "error" },
         }));
+        this.notifier?.send({
+            kind: ok ? "run_finished" : "run_failed",
+            level: ok ? "info" : "error",
+            title: `run ${ok ? "finished" : "failed"} — ${this.chainName}`,
+            fields: [
+                ["adw_id", this.adwId],
+                ["phases", `${passed}/${this.results.length}`],
+                ["tokens", tokens.toLocaleString()],
+                ["cost", `$${cost.toFixed(4)}`],
+            ],
+        });
     }
     // ── phases ──────────────────────────────────────────────────────────────
     phaseStarted(phase) {
@@ -113,6 +141,19 @@ export class Console {
         if (!ok && phase.error)
             line += `  ${paint("red", clip(phase.error))}`;
         this.emit(line, ok ? "info" : "error");
+        if (!ok) {
+            this.notifier?.send({
+                kind: "phase_failed",
+                level: "error",
+                title: `phase failed — ${phase.params.name}`,
+                detail: phase.error ?? undefined,
+                fields: [
+                    ["adw_id", this.adwId],
+                    ["chain", this.chainName],
+                    ["owner", phase.params.owner],
+                ],
+            });
+        }
         this.phaseId = "";
         this.phaseName = "";
     }
@@ -129,6 +170,15 @@ export class Console {
     }
     retry(name, attempt, limit, reason) {
         this.emit(`  ${paint("yellow", "⟳")} ${name} retry ${attempt}/${limit} ${paint("dim", `— same session · ${clip(reason)}`)}`, "warn");
+        // info-level: routine self-healing, same as watch's own untracked
+        // orphan retries — visible under `events: all`, silent under `errors`.
+        this.notifier?.send({
+            kind: "phase_retry",
+            level: "info",
+            title: `retry ${attempt}/${limit} — ${name}`,
+            detail: reason,
+            fields: [["adw_id", this.adwId]],
+        });
     }
     // ── verification ────────────────────────────────────────────────────────
     /** A gate reports WHAT it checked, not just whether it passed. */

package/dist/core/data_types.d.ts

@@ -401,6 +401,42 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
     }>;
 }, undefined>;
 export type WatchConfig = v.InferOutput<typeof WatchConfigSchema>;
+/**
+ * Optional outbound push for unattended work (`spf watch`, any chain run) —
+ * everything else (`spf doctor`, `list`, `sessions`, ...) is interactive, so
+ * it stays console-only on purpose; see `core/notify/notifier.ts`.
+ *
+ * `events` is the whole filter: "off" sends nothing, "errors" sends only
+ * NotifyEvents whose `level` is "error", "all" sends every curated
+ * milestone. A channel's own `events` overrides the top-level scope for
+ * just that channel (e.g. Slack gets everything, Teams gets errors only).
+ *
+ * `webhook_url_env` names the .env key holding the secret URL — never the
+ * URL itself, matching GITHUB_TOKEN/JIRA_API_TOKEN. Empty = the kind's own
+ * default key (see core/notify/notifier.ts's DEFAULT_ENV_KEY).
+ */
+export declare const NotifyScopeSchema: v.PicklistSchema<["off", "errors", "all"], undefined>;
+export type NotifyScope = v.InferOutput<typeof NotifyScopeSchema>;
+export declare const NotifyChannelKindSchema: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+export type NotifyChannelKind = v.InferOutput<typeof NotifyChannelKindSchema>;
+export declare const NotifyChannelSchema: v.ObjectSchema<{
+    readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+    readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+    readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type NotifyChannel = v.InferOutput<typeof NotifyChannelSchema>;
+export declare const NotificationsConfigSchema: v.ObjectSchema<{
+    readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, "off">;
+    readonly timeout_ms: v.OptionalSchema<v.NumberSchema<undefined>, 5000>;
+    readonly channels: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+        readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    }, undefined>, undefined>, () => never[]>;
+}, undefined>;
+export type NotificationsConfig = v.InferOutput<typeof NotificationsConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
@@ -494,6 +530,25 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             project_key: string;
         };
     }>;
+    readonly notifications: v.OptionalSchema<v.ObjectSchema<{
+        readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, "off">;
+        readonly timeout_ms: v.OptionalSchema<v.NumberSchema<undefined>, 5000>;
+        readonly channels: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+            readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
+            readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+            readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        }, undefined>, undefined>, () => never[]>;
+    }, undefined>, () => {
+        events: "all" | "errors" | "off";
+        timeout_ms: number;
+        channels: {
+            kind: "slack" | "teams" | "webhook";
+            webhook_url_env: string;
+            events?: "all" | "errors" | "off" | null | undefined;
+            name: string;
+        }[];
+    }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
 /** One traced event, always logged against adw_id + phase. */