@gr8ful/spf 0.2.1 → 0.4.0

package/dist/core/issues/github_provider.js

@@ -1,6 +1,8 @@
 const API = "https://api.github.com";
-const STATES = ["ready", "working", "review", "done", "blocked"];
+const STATES = ["ready", "working", "review", "done", "blocked", "spec-ready", "refining", "refined"];
 const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*?\})\s*-->/s;
+/** The refine lane's leaf/container taxonomy — see `data_types.ts`'s `RefinedIssueSchema.kind`. Not a `WatchState`: these never appear on the left of a `transition()` call, so `transition()` never strips them. */
+export const ISSUE_KINDS = ["epic", "feature", "story", "bug", "task"];
 // GitHub label colors are 6 hex digits, no leading '#'.
 const LABEL_META = {
     ready: { color: "0e8a16", description: "spf watch will claim this issue on its next poll" },
@@ -8,6 +10,16 @@ const LABEL_META = {
     review: { color: "1d76db", description: "spf watch opened a PR for this issue — awaiting merge" },
     done: { color: "5319e7", description: "spf watch's PR for this issue merged" },
     blocked: { color: "d93f0b", description: "spf watch gave up — needs a human" },
+    "spec-ready": { color: "0e8a16", description: "spf watch's refine lane will claim this spec on its next poll" },
+    refining: { color: "fbca04", description: "spf watch has claimed this spec and is decomposing it into issues" },
+    refined: { color: "c2e0c6", description: "generated by spf watch's refine lane — promote to spf:ready when it's worth building" },
+};
+const TYPE_LABEL_META = {
+    epic: { color: "5319e7", description: "a container generated by spf watch's refine lane — not directly workable" },
+    feature: { color: "1d76db", description: "a container generated by spf watch's refine lane — not directly workable" },
+    story: { color: "bfd4f2", description: "a leaf generated by spf watch's refine lane — vertical-slice, independently workable" },
+    bug: { color: "e99695", description: "a leaf generated by spf watch's refine lane — vertical-slice, independently workable" },
+    task: { color: "d4c5f9", description: "a leaf generated by spf watch's refine lane — vertical-slice, independently workable" },
 };
 export class GitHubProvider {
     repo;
@@ -41,6 +53,9 @@ export class GitHubProvider {
     label(state) {
         return `${this.labelPrefix}:${state}`;
     }
+    typeLabel(kind) {
+        return `${this.labelPrefix}:type:${kind}`;
+    }
     /** `null` on a real 404 (label doesn't exist yet) — any other non-2xx still throws, same as `gh()`. */
     async getLabel(name) {
         const response = await fetch(`${API}/repos/${this.repo}/labels/${encodeURIComponent(name)}`, {
@@ -55,39 +70,45 @@ export class GitHubProvider {
         return (await response.json());
     }
     /**
-     * Idempotent by inspection, not by "create and catch a 422": GET each
+     * Idempotent by inspection, not by "create and catch a 422": GET the
      * label first, then create/update/leave alone depending on what's
      * actually there. One fewer request in the common "already correct"
      * case, and no brittle matching against GitHub's error-message text.
+     * Shared by `ensureLabels()`'s state-label and type-label passes.
      */
+    async ensureOneLabel(name, color, description, result) {
+        const existing = await this.getLabel(name);
+        if (!existing) {
+            await this.gh(`/repos/${this.repo}/labels`, { method: "POST", body: JSON.stringify({ name, color, description }) });
+            result.created.push(name);
+        }
+        else if (existing.color !== color || (existing.description ?? "") !== description) {
+            await this.gh(`/repos/${this.repo}/labels/${encodeURIComponent(name)}`, {
+                method: "PATCH",
+                body: JSON.stringify({ color, description }),
+            });
+            result.updated.push(name);
+        }
+        else {
+            result.unchanged.push(name);
+        }
+    }
     async ensureLabels() {
-        const created = [];
-        const updated = [];
-        const unchanged = [];
+        const result = { created: [], updated: [], unchanged: [] };
         for (const state of STATES) {
-            const name = this.label(state);
             const { color, description } = LABEL_META[state];
-            const existing = await this.getLabel(name);
-            if (!existing) {
-                await this.gh(`/repos/${this.repo}/labels`, { method: "POST", body: JSON.stringify({ name, color, description }) });
-                created.push(name);
-            }
-            else if (existing.color !== color || (existing.description ?? "") !== description) {
-                await this.gh(`/repos/${this.repo}/labels/${encodeURIComponent(name)}`, {
-                    method: "PATCH",
-                    body: JSON.stringify({ color, description }),
-                });
-                updated.push(name);
-            }
-            else {
-                unchanged.push(name);
-            }
+            await this.ensureOneLabel(this.label(state), color, description, result);
         }
-        return { created, updated, unchanged };
+        for (const kind of ISSUE_KINDS) {
+            const { color, description } = TYPE_LABEL_META[kind];
+            await this.ensureOneLabel(this.typeLabel(kind), color, description, result);
+        }
+        return result;
     }
     toIssue(raw) {
         return {
             id: String(raw.number),
+            internal_id: String(raw.id),
             title: raw.title,
             body: raw.body ?? "",
             labels: raw.labels.map((l) => (typeof l === "string" ? l : l.name)),
@@ -103,22 +124,24 @@ export class GitHubProvider {
     async listInState(state, opts) {
         return this.listByLabel(this.label(state), opts?.includeAll ? "all" : "open");
     }
-    async claim(issue) {
-        await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels/${encodeURIComponent(this.label("ready"))}`, {
+    async claim(issue, opts) {
+        const from = this.label(opts?.from ?? "ready");
+        const to = this.label(opts?.to ?? "working");
+        await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels/${encodeURIComponent(from)}`, {
             method: "DELETE",
         }).catch(() => undefined); // already gone is fine
         await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels`, {
             method: "POST",
-            body: JSON.stringify({ labels: [this.label("working")] }),
+            body: JSON.stringify({ labels: [to] }),
         });
         const fresh = await this.gh(`/repos/${this.repo}/issues/${issue.id}`);
         const labels = this.toIssue(fresh).labels;
-        const claimed = labels.includes(this.label("working")) && !labels.includes(this.label("ready"));
+        const claimed = labels.includes(to) && !labels.includes(from);
         if (!claimed) {
-            // Lost the race (or something else relabeled it) — put ready back so it's not stuck.
+            // Lost the race (or something else relabeled it) — put the source label back so it's not stuck.
             await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels`, {
                 method: "POST",
-                body: JSON.stringify({ labels: [this.label("ready")] }),
+                body: JSON.stringify({ labels: [from] }),
             }).catch(() => undefined);
         }
         return claimed;
@@ -173,6 +196,31 @@ export class GitHubProvider {
         }
         return { merged: detail.merged, state: detail.state, ciStatus };
     }
+    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). */
+    async createIssue(input) {
+        const raw = await this.gh(`/repos/${this.repo}/issues`, {
+            method: "POST",
+            body: JSON.stringify({ title: input.title, body: input.body, labels: input.labels }),
+        });
+        return this.toIssue(raw);
+    }
+    /**
+     * `POST /repos/{o}/{r}/issues/{parent_number}/sub_issues` — GitHub's
+     * native sub-issue link. Confirmed against GitHub's own REST docs: the
+     * body param is `sub_issue_id`, the CHILD's database id, not its issue
+     * number — hence `linkChild` requiring `child.internal_id` rather than
+     * `child.id`. GitHub's documented limits (not enforced client-side here):
+     * 100 sub-issues per parent, 8 levels of nesting.
+     */
+    async linkChild(parent, child) {
+        if (!child.internal_id) {
+            throw new Error(`linkChild: child issue #${child.id} has no internal_id — only an issue this provider just created/fetched can be linked`);
+        }
+        await this.gh(`/repos/${this.repo}/issues/${parent.id}/sub_issues`, {
+            method: "POST",
+            body: JSON.stringify({ sub_issue_id: Number(child.internal_id) }),
+        });
+    }
     async findMarkerComment(issueId) {
         const comments = await this.gh(`/repos/${this.repo}/issues/${issueId}/comments?per_page=100`);
         let found = null;

package/dist/core/issues/jira_provider.d.ts

@@ -29,6 +29,16 @@
  * `ensureLabels()` is a no-op that reports the labels this run will use:
  * Jira labels are freeform strings with no color/description registry to
  * seed, unlike GitHub's.
+ *
+ * Does NOT implement `IssueAuthoringProvider` — the refine lane's create/
+ * link seam. Jira maps cleanly in principle (native issue types plus a
+ * `parent` field give a real hierarchy, unlike the label trick this file
+ * already leans on for state), but that is a real implementation, not a
+ * one-line stub, so it is a deliberate follow-on rather than done here.
+ * `resolveIssueAuthoringProvider()` (`cli/commands/watch.ts`) returns `null`
+ * for this provider, and `watch.refine.enabled: true` with
+ * `issue_provider: jira` fails loudly at startup rather than silently
+ * running a refine lane that can never publish anything.
  */
 import type { EnsureLabelsResult, Issue, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
 export declare class JiraProvider implements IssueProvider {
@@ -63,7 +73,10 @@ export declare class JiraProvider implements IssueProvider {
      * could make a `review`-labeled issue vanish from an unfiltered query.
      */
     listInState(state: WatchState): Promise<Issue[]>;
-    claim(issue: Issue): Promise<boolean>;
+    claim(issue: Issue, opts?: {
+        from?: WatchState;
+        to?: WatchState;
+    }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
     comment(issue: Issue, body: string): Promise<void>;
     private findMarkerComment;

package/dist/core/issues/jira_provider.js

@@ -1,4 +1,4 @@
-const STATES = ["ready", "working", "review", "done", "blocked"];
+const STATES = ["ready", "working", "review", "done", "blocked", "spec-ready", "refining", "refined"];
 const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*?\})/s;
 function toAdf(text) {
     return {
@@ -103,16 +103,18 @@ export class JiraProvider {
     async listInState(state) {
         return this.searchByLabel(this.label(state));
     }
-    async claim(issue) {
-        const next = issue.labels.filter((l) => l !== this.label("ready"));
-        next.push(this.label("working"));
+    async claim(issue, opts) {
+        const from = this.label(opts?.from ?? "ready");
+        const to = this.label(opts?.to ?? "working");
+        const next = issue.labels.filter((l) => l !== from);
+        next.push(to);
         await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
         const fresh = await this.jira(`/rest/api/3/issue/${issue.id}?fields=summary,description,labels`);
         const labels = fresh.fields.labels;
-        const claimed = labels.includes(this.label("working")) && !labels.includes(this.label("ready"));
+        const claimed = labels.includes(to) && !labels.includes(from);
         if (!claimed) {
-            const revert = labels.filter((l) => l !== this.label("working"));
-            revert.push(this.label("ready"));
+            const revert = labels.filter((l) => l !== to);
+            revert.push(from);
             await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: revert } }) }).catch(() => undefined);
         }
         return claimed;

package/dist/core/issues/provider.d.ts

@@ -1,8 +1,8 @@
 /**
- * The two seams `spf watch` drives — the abstraction the user's own
- * reference implementation (a GitHub-issues SDLC poller) never had: its
- * GitHub client is a concrete class referenced by type everywhere, so
- * adding a second tracker would mean reworking the poll loop itself.
+ * The seams `spf watch` drives — the abstraction the user's own reference
+ * implementation (a GitHub-issues SDLC poller) never had: its GitHub client
+ * is a concrete class referenced by type everywhere, so adding a second
+ * tracker would mean reworking the poll loop itself.
  *
  * `IssueProvider` (tracker: list/claim/transition/comment/markers) and
  * `CodeHostProvider` (PR lifecycle: open/status) are deliberately separate
@@ -13,19 +13,45 @@
  * implements only `IssueProvider`, `bitbucket_provider.ts` only
  * `CodeHostProvider` — any tracker x host combination is just config
  * (`watch.issue_provider` x `watch.code_host`), never a poll-loop change.
+ * `IssueAuthoringProvider` (create/link, at the bottom of this file) is a
+ * third, again separate — the refine lane's own need, optional per tracker,
+ * and orthogonal to which one is the code host.
  *
  * The label-as-state-machine design is deliberate, copied from that same
  * reference: `transition()` is the ONE mutator, so every state change is
  * traceable to one call site, and a provider can layer notifications
  * (Slack, a webhook, whatever) on top of it without the poll loop caring.
  */
-export type WatchState = "ready" | "working" | "review" | "done" | "blocked";
+/**
+ * `spec-ready`/`refining` drive the SECOND lane's state machine (a product
+ * spec being decomposed — see `reconcileRefining`/`claimSpecs` in
+ * `watch.ts`), independent of the build lane's own `ready..blocked` states.
+ * `refined` is not a lane state at all — it never appears on the left of a
+ * `transition()` call. It is the terminal label a generated LEAF issue
+ * (story/bug/task) gets, marking it awaiting a human's promotion to `ready`.
+ * All eight still live in one `WatchState` union (not two separate unions)
+ * because `transition()`'s "strip every `<prefix>:<state>` label, then add
+ * one" logic (see `github_provider.ts`/`jira_provider.ts`) has to know about
+ * every one of them to strip correctly, and `ensureLabels()` seeds all of
+ * them from one `STATES` array.
+ */
+export type WatchState = "ready" | "working" | "review" | "done" | "blocked" | "spec-ready" | "refining" | "refined";
 export interface Issue {
     /** Opaque tracker identifier: a GitHub issue number stringified ("42"), a Jira key ("PROJ-123"). */
     id: string;
     title: string;
     body: string;
     labels: string[];
+    /**
+     * The tracker's own internal/database id, distinct from `id` (the
+     * human-facing number/key) — only populated where an authoring operation
+     * needs it. GitHub's sub-issue API is the reason this exists: `POST
+     * /repos/{o}/{r}/issues/{n}/sub_issues` takes `sub_issue_id` as the
+     * issue's database id, not its issue number, so `linkChild()` cannot work
+     * from `id` alone. `undefined` on any issue this provider didn't just
+     * create/fetch with that field available.
+     */
+    internal_id?: string;
 }
 export interface PrRef {
     number: number;
@@ -42,12 +68,18 @@ export interface PrStatus {
  * on the issue itself — zero infrastructure, survives a daemon crash,
  * human-readable. `attempt` bounds orphan-retry (see `watch.ts`); `ciFixes`
  * is reserved for a future fix-loop, unused by the lean v1 poll logic.
+ * `refined` is the refine lane's own idempotency record: the ids of every
+ * issue a completed publish pass created for this spec. A re-claimed spec
+ * whose marker already lists them skips creation entirely — `to-tickets`
+ * (the skill this lane's prompt is ported from) has no such guard and
+ * duplicates every ticket on a re-run; this is what closes that gap.
  */
 export interface WatchMarker {
     worktree?: string;
     branch?: string;
     pr?: number;
     attempt?: number;
+    refined?: string[];
 }
 /** What `ensureLabels()` actually did, per label — for `spf watch init`'s report. */
 export interface EnsureLabelsResult {
@@ -58,11 +90,12 @@ export interface EnsureLabelsResult {
 export interface IssueProvider {
     /**
      * Idempotently seed whatever this tracker needs for the state machine to
-     * work at all — GitHub: the five `<prefix>:*` labels, with a color and
-     * description, created if missing and corrected if drifted. A tracker
-     * with no such concept (Jira labels are freeform strings, not seedable
-     * objects) can make this a no-op — `spf watch init` just reports
-     * whatever comes back, empty results included.
+     * work at all — GitHub: every `<prefix>:*` state label plus the
+     * `<prefix>:type:*` vocabulary the refine lane's generated issues carry,
+     * each with a color and description, created if missing and corrected if
+     * drifted. A tracker with no such concept (Jira labels are freeform
+     * strings, not seedable objects) can make this a no-op — `spf watch init`
+     * just reports whatever comes back, empty results included.
      */
     ensureLabels(): Promise<EnsureLabelsResult>;
     /** Issues currently labeled `<prefix>:ready`. */
@@ -81,12 +114,20 @@ export interface IssueProvider {
         includeAll?: boolean;
     }): Promise<Issue[]>;
     /**
-     * Move `ready` -> `working`, with a read-back verify (like the reference
-     * implementation's `claimIssue`) — not a true atomic claim, but enough to
-     * catch the common case; the real safety net against two daemons racing
-     * the same issue is `spf watch`'s own single-instance lockfile.
+     * Move `opts.from` (default `ready`) -> `opts.to` (default `working`),
+     * with a read-back verify (like the reference implementation's
+     * `claimIssue`) — not a true atomic claim, but enough to catch the common
+     * case; the real safety net against two daemons racing the same issue is
+     * `spf watch`'s own single-instance lockfile. Parameterized so the refine
+     * lane's `spec-ready -> refining` claim (see `claimSpecs` in `watch.ts`)
+     * reuses the identical DELETE-from/POST-to/read-back-verify dance the
+     * build lane's `ready -> working` claim already does, rather than a
+     * second copy of it per provider.
      */
-    claim(issue: Issue): Promise<boolean>;
+    claim(issue: Issue, opts?: {
+        from?: WatchState;
+        to?: WatchState;
+    }): Promise<boolean>;
     /** The one state-mutating call. `detail`, if given, is also posted as a comment. */
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
     comment(issue: Issue, body: string): Promise<void>;
@@ -111,3 +152,24 @@ export interface CodeHostProvider {
     }): Promise<PrRef>;
     prStatus(pr: PrRef): Promise<PrStatus>;
 }
+/**
+ * The third seam: creating issues and linking them into a hierarchy — what
+ * the refine lane needs and neither `IssueProvider` nor `CodeHostProvider`
+ * provides (a tracker's read/claim/transition surface has no reason to
+ * create new work items). Kept separate rather than folded into
+ * `IssueProvider` for the same reason `CodeHostProvider` is separate: not
+ * every tracker can do this (Jira could, in principle, via its native issue
+ * types + `parent` field, but that is a real future implementation, not a
+ * one-line stub — see `jira_provider.ts`'s module comment), and a tracker
+ * that can't should be a `null` from `resolveIssueAuthoringProvider()`
+ * (`cli/commands/watch.ts`), not a method that throws at call time.
+ */
+export interface IssueAuthoringProvider {
+    createIssue(input: {
+        title: string;
+        body: string;
+        labels: string[];
+    }): Promise<Issue>;
+    /** Link `child` under `parent` using the tracker's native hierarchy — GitHub's sub-issues API today. */
+    linkChild(parent: Issue, child: Issue): Promise<void>;
+}

package/dist/core/issues/provider.js

@@ -1,8 +1,8 @@
 /**
- * The two seams `spf watch` drives — the abstraction the user's own
- * reference implementation (a GitHub-issues SDLC poller) never had: its
- * GitHub client is a concrete class referenced by type everywhere, so
- * adding a second tracker would mean reworking the poll loop itself.
+ * The seams `spf watch` drives — the abstraction the user's own reference
+ * implementation (a GitHub-issues SDLC poller) never had: its GitHub client
+ * is a concrete class referenced by type everywhere, so adding a second
+ * tracker would mean reworking the poll loop itself.
  *
  * `IssueProvider` (tracker: list/claim/transition/comment/markers) and
  * `CodeHostProvider` (PR lifecycle: open/status) are deliberately separate
@@ -13,6 +13,9 @@
  * implements only `IssueProvider`, `bitbucket_provider.ts` only
  * `CodeHostProvider` — any tracker x host combination is just config
  * (`watch.issue_provider` x `watch.code_host`), never a poll-loop change.
+ * `IssueAuthoringProvider` (create/link, at the bottom of this file) is a
+ * third, again separate — the refine lane's own need, optional per tracker,
+ * and orthogonal to which one is the code host.
  *
  * The label-as-state-machine design is deliberate, copied from that same
  * reference: `transition()` is the ONE mutator, so every state change is

package/dist/core/notify/channel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The vocabulary a `NotificationChannel` speaks, and the seam itself —
+ * mirrors `core/issues/provider.ts`'s shape (an interface per concern,
+ * one small implementation module per backend).
+ *
+ * `NotifyKind` is a curated set of milestones, deliberately not the raw
+ * tracer event stream (`Tracer.event()` — see `core/tracer.ts`): a single
+ * chain run emits hundreds of `tool_call`/`log` events, which would need
+ * batching/rate-limiting to be a usable Slack message and would cut against
+ * the tracer's own "no push transport" design. `level` is the ENTIRE filter
+ * predicate a `Notifier` applies — no separate per-kind severity table to
+ * keep in sync with this list.
+ */
+export type NotifyKind = "run_started" | "run_finished" | "run_failed" | "phase_failed" | "phase_retry" | "watch_started" | "watch_stopped" | "watch_error" | "issue_claimed" | "pr_opened" | "issue_done" | "issue_blocked" | "spec_refined";
+export interface NotifyEvent {
+    kind: NotifyKind;
+    /** "error" sends under both `events: errors` and `events: all`; "info" only under `all`. */
+    level: "info" | "error";
+    /** One line, e.g. "run failed — plan-build-test". */
+    title: string;
+    /** The error text / PR body / block detail, if any. */
+    detail?: string;
+    /** Ordered label/value pairs — adw_id, chain, phase, tokens, cost, issue, pr, repo, ... */
+    fields: Array<[string, string]>;
+    /** A PR or issue link, when there is one. */
+    url?: string;
+}
+export interface NotificationChannel {
+    /** For warning lines — "slack", "teams (ops-bus)". */
+    readonly label: string;
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/channel.js

@@ -0,0 +1,14 @@
+/**
+ * The vocabulary a `NotificationChannel` speaks, and the seam itself —
+ * mirrors `core/issues/provider.ts`'s shape (an interface per concern,
+ * one small implementation module per backend).
+ *
+ * `NotifyKind` is a curated set of milestones, deliberately not the raw
+ * tracer event stream (`Tracer.event()` — see `core/tracer.ts`): a single
+ * chain run emits hundreds of `tool_call`/`log` events, which would need
+ * batching/rate-limiting to be a usable Slack message and would cut against
+ * the tracer's own "no push transport" design. `level` is the ENTIRE filter
+ * predicate a `Notifier` applies — no separate per-kind severity table to
+ * keep in sync with this list.
+ */
+export {};

package/dist/core/notify/notifier.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Filter, fan-out, and lifecycle for outbound notifications. A notification
+ * must never be able to break a run: `send()` never throws and never
+ * blocks — it fires the request and tracks it in a pending set, and a
+ * failure is swallowed after logging one line (the URL itself never
+ * appears in that line, or anywhere else — see `resolveNotifier` below).
+ *
+ * `resolveNotifier` returns `null` when notifications are off or no
+ * channel resolved, so every call site uses the same `notifier?.send(...)`
+ * shape as an optional dependency, not a conditional branch.
+ */
+import type { NotifyEvent, NotificationChannel } from "./channel.ts";
+import type { NotifyScope, SFConfig } from "../data_types.ts";
+/** Exported so `spf doctor` and the init interview can name the same key without duplicating this table. */
+export declare const DEFAULT_NOTIFY_ENV_KEY: Record<string, string>;
+export declare class Notifier {
+    private readonly channels;
+    private readonly timeoutMs;
+    private readonly dryRun;
+    private readonly log;
+    private pending;
+    constructor(channels: Array<{
+        channel: NotificationChannel;
+        scope: NotifyScope;
+    }>, timeoutMs: number, dryRun: boolean, log?: (message: string) => void);
+    /** Sync, fire-and-forget — every call site is sync and must stay that way. */
+    send(event: NotifyEvent): void;
+    /** Await every in-flight send — call before process exit so a slow webhook isn't dropped mid-flight. */
+    flush(): Promise<void>;
+}
+/**
+ * Build a `Notifier` from `cfg.notifications`, or `null` if it's off or no
+ * channel resolved. A channel whose env var isn't set is skipped with one
+ * warning naming the missing key — never a hard failure, since a broken
+ * notification setup shouldn't stop the work it's supposed to report on.
+ */
+export declare function resolveNotifier(cfg: SFConfig, opts?: {
+    dryRun?: boolean;
+    log?: (message: string) => void;
+}): Notifier | null;
+/** Await every Notifier this process has created — call once, from the CLI's shutdown path. */
+export declare function flushAll(): Promise<void>;

package/dist/core/notify/notifier.js

@@ -0,0 +1,100 @@
+import { SlackChannel } from "./slack_channel.js";
+import { TeamsChannel } from "./teams_channel.js";
+import { WebhookChannel } from "./webhook_channel.js";
+/** Exported so `spf doctor` and the init interview can name the same key without duplicating this table. */
+export const DEFAULT_NOTIFY_ENV_KEY = {
+    slack: "SLACK_WEBHOOK_URL",
+    teams: "TEAMS_WEBHOOK_URL",
+    webhook: "SPF_WEBHOOK_URL",
+};
+/** `errors` mode only sends `level: "error"`; `all` sends everything; `off` sends nothing. */
+function scopeAllows(scope, level) {
+    if (scope === "off")
+        return false;
+    if (scope === "all")
+        return true;
+    return level === "error";
+}
+export class Notifier {
+    channels;
+    timeoutMs;
+    dryRun;
+    log;
+    pending = new Set();
+    constructor(channels, timeoutMs, dryRun, log = (m) => console.error(m)) {
+        this.channels = channels;
+        this.timeoutMs = timeoutMs;
+        this.dryRun = dryRun;
+        this.log = log;
+    }
+    /** Sync, fire-and-forget — every call site is sync and must stay that way. */
+    send(event) {
+        for (const { channel, scope } of this.channels) {
+            if (!scopeAllows(scope, event.level))
+                continue;
+            if (this.dryRun) {
+                this.log(`spf: would notify (${channel.label}): ${event.title}`);
+                continue;
+            }
+            const task = channel.send(event, this.timeoutMs).catch((error) => {
+                this.log(`spf: ${channel.label} notification failed: ${error.message}`);
+            });
+            this.pending.add(task);
+            task.finally(() => this.pending.delete(task));
+        }
+    }
+    /** Await every in-flight send — call before process exit so a slow webhook isn't dropped mid-flight. */
+    async flush() {
+        await Promise.all([...this.pending]);
+    }
+}
+function makeChannel(kind, url, name) {
+    switch (kind) {
+        case "slack":
+            return new SlackChannel(url, name);
+        case "teams":
+            return new TeamsChannel(url, name);
+        case "webhook":
+            return new WebhookChannel(url, name);
+        default:
+            return null;
+    }
+}
+// Every live Notifier this process created — so the CLI's shutdown path can
+// flush all of them without threading a handle through every call site,
+// matching agent_flue.shutdown()/agent_cc.shutdown()'s module-level shape.
+const LIVE = [];
+/**
+ * Build a `Notifier` from `cfg.notifications`, or `null` if it's off or no
+ * channel resolved. A channel whose env var isn't set is skipped with one
+ * warning naming the missing key — never a hard failure, since a broken
+ * notification setup shouldn't stop the work it's supposed to report on.
+ */
+export function resolveNotifier(cfg, opts = {}) {
+    const nc = cfg.notifications;
+    if (nc.events === "off" || nc.channels.length === 0)
+        return null;
+    const log = opts.log ?? ((m) => console.error(m));
+    const resolved = [];
+    for (const entry of nc.channels) {
+        const envKey = entry.webhook_url_env || DEFAULT_NOTIFY_ENV_KEY[entry.kind];
+        const url = process.env[envKey];
+        if (!url) {
+            log(`spf: notifications.channels[kind=${entry.kind}] is configured but ${envKey} is not set — skipping this channel`);
+            continue;
+        }
+        const channel = makeChannel(entry.kind, url, entry.name);
+        if (!channel)
+            continue;
+        resolved.push({ channel, scope: entry.events ?? nc.events });
+    }
+    if (resolved.length === 0)
+        return null;
+    const notifier = new Notifier(resolved, nc.timeout_ms, Boolean(opts.dryRun), log);
+    LIVE.push(notifier);
+    return notifier;
+}
+/** Await every Notifier this process has created — call once, from the CLI's shutdown path. */
+export async function flushAll() {
+    await Promise.all(LIVE.map((n) => n.flush()));
+}

package/dist/core/notify/slack_channel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Slack Incoming Webhook — a plain `POST` of a Block Kit payload, via native
+ * `fetch()` (same no-dependency stance as `core/issues/github_provider.ts`).
+ * Set up: Slack app -> Incoming Webhooks -> "Add New Webhook to Workspace".
+ * https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks
+ */
+import type { NotificationChannel, NotifyEvent } from "./channel.ts";
+export declare class SlackChannel implements NotificationChannel {
+    private readonly webhookUrl;
+    readonly label: string;
+    constructor(webhookUrl: string, name?: string);
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/slack_channel.js

@@ -0,0 +1,30 @@
+export class SlackChannel {
+    webhookUrl;
+    label;
+    constructor(webhookUrl, name = "") {
+        this.webhookUrl = webhookUrl;
+        this.label = name ? `slack (${name})` : "slack";
+    }
+    async send(event, timeoutMs) {
+        const emoji = event.level === "error" ? ":x:" : ":white_check_mark:";
+        const fieldsText = event.fields.map(([k, v]) => `*${k}:* ${v}`).join("  ·  ");
+        const body = {
+            text: `${emoji} ${event.title}`,
+            blocks: [
+                { type: "section", text: { type: "mrkdwn", text: `${emoji} *${event.title}*` } },
+                ...(event.detail ? [{ type: "section", text: { type: "mrkdwn", text: event.detail.slice(0, 2900) } }] : []),
+                ...(fieldsText ? [{ type: "context", elements: [{ type: "mrkdwn", text: fieldsText }] }] : []),
+                ...(event.url ? [{ type: "section", text: { type: "mrkdwn", text: `<${event.url}|open>` } }] : []),
+            ],
+        };
+        const response = await fetch(this.webhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`slack webhook -> ${response.status}: ${(await response.text().catch(() => "")).slice(0, 300)}`);
+        }
+    }
+}