@gr8ful/spf 0.2.1 → 0.4.0

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

@@ -150,6 +150,45 @@ export declare const DocumentOutput: EnvelopeType<{
     commit_message: string;
 }>;
 export type DocumentOutputT = v.InferOutput<typeof DocumentOutput.schema>;
+/**
+ * One node in a decomposed product spec — a feature/epic container, or a
+ * story/bug/task leaf. Flat with a `parent` key, not nested JSON: a model
+ * emits a flat list far more reliably than a recursive tree, and a flat
+ * shape is what lets `blocked_by` reference ANY other node, container or
+ * leaf, not just siblings under the same parent.
+ *
+ * `key` is the refiner's own local id for this run (e.g. "F1", "S1.1") —
+ * scoped to one `RefineOutput`, never a tracker id; `core/refine.ts`
+ * resolves `key`s to real issue numbers as it creates them, in dependency
+ * order. See `gates.refinementWellFormed` for the shape rules enforced on
+ * this list before publish ever runs (unique keys, resolvable references,
+ * no cycles, container/leaf kind agreement, at least one leaf).
+ */
+export declare const RefinedIssueSchema: v.ObjectSchema<{
+    readonly key: v.StringSchema<undefined>;
+    readonly kind: v.PicklistSchema<["epic", "feature", "story", "bug", "task"], undefined>;
+    readonly title: v.StringSchema<undefined>;
+    readonly body: v.StringSchema<undefined>;
+    readonly parent: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly blocked_by: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+}, undefined>;
+export type RefinedIssue = v.InferOutput<typeof RefinedIssueSchema>;
+/** A product spec decomposed into a feature/story tree — see `steps.refine()` and `core/refine.ts`. */
+export declare const RefineOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    issues: {
+        key: string;
+        kind: "bug" | "epic" | "feature" | "story" | "task";
+        title: string;
+        body: string;
+        parent: string;
+        blocked_by: string[];
+    }[];
+}>;
+export type RefineOutputT = v.InferOutput<typeof RefineOutput.schema>;
 export declare const QualityAreaSchema: v.PicklistSchema<["frontend", "backend"], undefined>;
 export type QualityArea = v.InferOutput<typeof QualityAreaSchema>;
 export declare const QualityOperationSchema: v.PicklistSchema<["lint", "typecheck", "build"], undefined>;
@@ -383,6 +422,22 @@ export declare const WatchJiraConfigSchema: v.ObjectSchema<{
     readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
 }, undefined>;
 export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
+/**
+ * The second `spf watch` lane: decompose a `<prefix>:spec-ready` product
+ * spec into a feature/story tree of real issues, instead of running
+ * `watch.chain` against it directly (a spec is not individually workable —
+ * see `core/refine.ts`). Off by default so an existing `watch:` config's
+ * behavior is unchanged by upgrading; turning it on with
+ * `issue_provider: jira` fails loudly at `spf watch` startup, since
+ * `JiraProvider` doesn't implement `IssueAuthoringProvider` (create/link)
+ * yet — see its module comment.
+ */
+export declare const WatchRefineConfigSchema: v.ObjectSchema<{
+    readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
+    readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+}, undefined>;
+export type WatchRefineConfig = v.InferOutput<typeof WatchRefineConfigSchema>;
 export declare const WatchConfigSchema: v.ObjectSchema<{
     readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
     readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
@@ -399,8 +454,53 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
         base_url: string;
         project_key: string;
     }>;
+    readonly refine: v.OptionalSchema<v.ObjectSchema<{
+        readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
+        readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+    }, undefined>, () => {
+        enabled: boolean;
+        chain: string;
+        concurrency: number;
+    }>;
 }, 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">;
@@ -480,6 +580,15 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             base_url: string;
             project_key: string;
         }>;
+        readonly refine: v.OptionalSchema<v.ObjectSchema<{
+            readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+            readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
+            readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+        }, undefined>, () => {
+            enabled: boolean;
+            chain: string;
+            concurrency: number;
+        }>;
     }, undefined>, () => {
         issue_provider: "github" | "jira";
         code_host: "bitbucket" | "github";
@@ -493,6 +602,30 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             base_url: string;
             project_key: string;
         };
+        refine: {
+            enabled: boolean;
+            chain: string;
+            concurrency: number;
+        };
+    }>;
+    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>;

package/dist/core/data_types.js

@@ -103,6 +103,32 @@ export const DocumentOutput = envelopeType("DocumentOutput", {
     documented_files: v.optional(v.array(v.string()), () => []),
     commit_message: v.optional(v.string(), ""),
 });
+/**
+ * One node in a decomposed product spec — a feature/epic container, or a
+ * story/bug/task leaf. Flat with a `parent` key, not nested JSON: a model
+ * emits a flat list far more reliably than a recursive tree, and a flat
+ * shape is what lets `blocked_by` reference ANY other node, container or
+ * leaf, not just siblings under the same parent.
+ *
+ * `key` is the refiner's own local id for this run (e.g. "F1", "S1.1") —
+ * scoped to one `RefineOutput`, never a tracker id; `core/refine.ts`
+ * resolves `key`s to real issue numbers as it creates them, in dependency
+ * order. See `gates.refinementWellFormed` for the shape rules enforced on
+ * this list before publish ever runs (unique keys, resolvable references,
+ * no cycles, container/leaf kind agreement, at least one leaf).
+ */
+export const RefinedIssueSchema = v.object({
+    key: v.string(),
+    kind: v.picklist(["epic", "feature", "story", "bug", "task"]),
+    title: v.string(),
+    body: v.string(), // "## What to build" / "## Acceptance criteria" — see assets/prompts/refiner/user.md
+    parent: v.optional(v.string(), ""), // another node's `key`; "" = top level
+    blocked_by: v.optional(v.array(v.string()), () => []), // other nodes' `key`s that must land first
+});
+/** A product spec decomposed into a feature/story tree — see `steps.refine()` and `core/refine.ts`. */
+export const RefineOutput = envelopeType("RefineOutput", {
+    issues: v.optional(v.array(RefinedIssueSchema), () => []),
+});
 // ── Deterministic quality blocks ─────────────────────────────────────────────
 export const QualityAreaSchema = v.picklist(["frontend", "backend"]);
 export const QualityOperationSchema = v.picklist(["lint", "typecheck", "build"]);
@@ -299,6 +325,21 @@ export const WatchJiraConfigSchema = v.object({
     base_url: v.optional(v.string(), ""), // e.g. "https://your-domain.atlassian.net"
     project_key: v.optional(v.string(), ""), // e.g. "PROJ"
 });
+/**
+ * The second `spf watch` lane: decompose a `<prefix>:spec-ready` product
+ * spec into a feature/story tree of real issues, instead of running
+ * `watch.chain` against it directly (a spec is not individually workable —
+ * see `core/refine.ts`). Off by default so an existing `watch:` config's
+ * behavior is unchanged by upgrading; turning it on with
+ * `issue_provider: jira` fails loudly at `spf watch` startup, since
+ * `JiraProvider` doesn't implement `IssueAuthoringProvider` (create/link)
+ * yet — see its module comment.
+ */
+export const WatchRefineConfigSchema = v.object({
+    enabled: v.optional(v.boolean(), false),
+    chain: v.optional(v.string(), "refine"),
+    concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 1),
+});
 export const WatchConfigSchema = v.object({
     issue_provider: v.optional(WatchIssueProviderSchema, "github"),
     code_host: v.optional(WatchCodeHostSchema, "github"),
@@ -309,6 +350,36 @@ export const WatchConfigSchema = v.object({
     poll_ms: v.optional(v.number(), 60_000),
     concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 2),
     jira: v.optional(WatchJiraConfigSchema, () => v.parse(WatchJiraConfigSchema, {})),
+    refine: v.optional(WatchRefineConfigSchema, () => v.parse(WatchRefineConfigSchema, {})),
+});
+/**
+ * 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 const NotifyScopeSchema = v.picklist(["off", "errors", "all"]);
+export const NotifyChannelKindSchema = v.picklist(["slack", "teams", "webhook"]);
+export const NotifyChannelSchema = v.object({
+    kind: NotifyChannelKindSchema,
+    webhook_url_env: v.optional(v.string(), ""),
+    events: v.optional(v.nullable(NotifyScopeSchema)),
+    // Shown in warning lines / message footers to tell two channels of the
+    // same kind apart (e.g. two webhook: entries) — cosmetic only.
+    name: v.optional(v.string(), ""),
+});
+export const NotificationsConfigSchema = v.object({
+    events: v.optional(NotifyScopeSchema, "off"),
+    timeout_ms: v.optional(v.number(), 5_000),
+    channels: v.optional(v.array(NotifyChannelSchema), () => []),
 });
 export const SFConfigSchema = v.object({
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
@@ -316,6 +387,7 @@ export const SFConfigSchema = v.object({
     agents: v.optional(v.array(AgentConfigSchema), () => []),
     quality: v.optional(QualityConfigSchema, () => v.parse(QualityConfigSchema, {})),
     watch: v.optional(WatchConfigSchema, () => v.parse(WatchConfigSchema, {})),
+    notifications: v.optional(NotificationsConfigSchema, () => v.parse(NotificationsConfigSchema, {})),
 });
 export function makeEventRecord(input) {
     return {

package/dist/core/gates.d.ts

@@ -29,5 +29,18 @@ export declare function diffMatchesClaims(envelope: EnvelopeBase, run: RunContex
  * reading a line of the diff.
  */
 export declare function verdictConsistent(envelope: EnvelopeBase, _run: RunContext): GateReport;
+/**
+ * The gate that turns `to-tickets`' flat, untyped ticket list into an
+ * actually-enforced feature/story-or-bug tree — see `RefinedIssueSchema`'s
+ * doc comment in `data_types.ts`. Checks the envelope's `issues` list
+ * against itself, never anything already published: `core/refine.ts` never
+ * gets a chance to publish a malformed tree in the first place, because a
+ * violation here re-prompts the SAME refiner session before `steps.refine()`
+ * ever hands off to `steps.publishIssues()`.
+ *
+ * "Container" and "leaf" are derived from the graph, not asserted by the
+ * agent: a node is a container iff some other node names it as `parent`.
+ */
+export declare function refinementWellFormed(envelope: EnvelopeBase, _run: RunContext): GateReport;
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */
 export declare function testsPass(command: string): GateFn;

package/dist/core/gates.js

@@ -128,6 +128,109 @@ export function verdictConsistent(envelope, _run) {
         : "approved=false but no blocking item or unmet requirement was given");
     return report;
 }
+const CONTAINER_KINDS = new Set(["epic", "feature"]);
+const LEAF_KINDS = new Set(["story", "bug", "task"]);
+/**
+ * The gate that turns `to-tickets`' flat, untyped ticket list into an
+ * actually-enforced feature/story-or-bug tree — see `RefinedIssueSchema`'s
+ * doc comment in `data_types.ts`. Checks the envelope's `issues` list
+ * against itself, never anything already published: `core/refine.ts` never
+ * gets a chance to publish a malformed tree in the first place, because a
+ * violation here re-prompts the SAME refiner session before `steps.refine()`
+ * ever hands off to `steps.publishIssues()`.
+ *
+ * "Container" and "leaf" are derived from the graph, not asserted by the
+ * agent: a node is a container iff some other node names it as `parent`.
+ */
+export function refinementWellFormed(envelope, _run) {
+    const report = new GateReport();
+    const issues = envelope.issues ?? [];
+    if (issues.length === 0) {
+        report.check("issues", false, "a refinement produced no issues at all — decompose the spec into at least one leaf");
+        return report;
+    }
+    const byKey = new Map();
+    for (const issue of issues) {
+        if (byKey.has(issue.key)) {
+            report.check(`key ${JSON.stringify(issue.key)}`, false, "duplicate key — every node needs a unique key within this refinement");
+        }
+        else {
+            byKey.set(issue.key, issue);
+        }
+    }
+    const childKeys = new Set(); // keys named as some OTHER node's parent -> that node is a container
+    for (const issue of issues) {
+        if (!issue.parent)
+            continue;
+        if (!byKey.has(issue.parent)) {
+            report.check(`${issue.key}.parent`, false, `parent ${JSON.stringify(issue.parent)} does not match any issue's key`);
+            continue;
+        }
+        childKeys.add(issue.parent);
+    }
+    for (const issue of issues) {
+        for (const blocker of issue.blocked_by) {
+            if (!byKey.has(blocker)) {
+                report.check(`${issue.key}.blocked_by`, false, `blocked_by ${JSON.stringify(blocker)} does not match any issue's key`);
+            }
+        }
+    }
+    // Cycle check over the union of parent + blocked_by edges — both mean
+    // "must exist before this node" from core/refine.ts's own topological
+    // publish order, so a cycle in either (or across both) would hang it.
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    let cyclic = false;
+    const edgesFrom = (key) => {
+        const issue = byKey.get(key);
+        if (!issue)
+            return [];
+        const out = [];
+        if (issue.parent && byKey.has(issue.parent))
+            out.push(issue.parent);
+        for (const b of issue.blocked_by)
+            if (byKey.has(b))
+                out.push(b);
+        return out;
+    };
+    const visit = (key) => {
+        if (cyclic)
+            return;
+        color.set(key, GRAY);
+        for (const next of edgesFrom(key)) {
+            const c = color.get(next) ?? WHITE;
+            if (c === GRAY) {
+                cyclic = true;
+                return;
+            }
+            if (c === WHITE)
+                visit(next);
+        }
+        color.set(key, BLACK);
+    };
+    for (const issue of issues) {
+        if ((color.get(issue.key) ?? WHITE) === WHITE)
+            visit(issue.key);
+    }
+    report.check("dependency graph", !cyclic, cyclic ? "parent/blocked_by edges form a cycle — nothing to publish first" : "acyclic");
+    for (const issue of issues) {
+        const isContainer = childKeys.has(issue.key);
+        if (isContainer && !CONTAINER_KINDS.has(issue.kind)) {
+            report.check(`${issue.key}.kind`, false, `has children but kind is ${JSON.stringify(issue.kind)} — a container must be "epic" or "feature"`);
+        }
+        else if (!isContainer && !LEAF_KINDS.has(issue.kind)) {
+            report.check(`${issue.key}.kind`, false, `has no children but kind is ${JSON.stringify(issue.kind)} — a leaf must be "story", "bug", or "task"`);
+        }
+        else {
+            report.check(`${issue.key}.kind`, true, isContainer ? "container" : "leaf");
+        }
+    }
+    const leafCount = issues.filter((i) => !childKeys.has(i.key)).length;
+    report.check("has leaves", leafCount > 0, leafCount > 0 ? `${leafCount} leaf issue(s)` : "every node is a container — nothing here is independently workable");
+    return report;
+}
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */
 export function testsPass(command) {
     const gate = (_envelope, run) => {

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

@@ -1,10 +1,12 @@
 /**
- * GitHub REST implementation of both `IssueProvider` and `CodeHostProvider`
- * — one class, since GitHub natively is both an issue tracker and a code
- * host — via Node 22's native `fetch()`: deliberately not `octokit`, whose
+ * GitHub REST implementation of `IssueProvider`, `CodeHostProvider`, AND
+ * `IssueAuthoringProvider` — one class, since GitHub natively is an issue
+ * tracker, a code host, and (via sub-issues) an issue-hierarchy API all at
+ * once — via Node 22's native `fetch()`: deliberately not `octokit`, whose
  * full meta-package resolves to ~82MB of installed dependencies (`@octokit/app`,
- * `oauth-app`, `webhooks`, ...) for what `spf watch` actually needs, which
- * is six REST calls. `spf`'s own package stays dependency-free either way.
+ * `oauth-app`, `webhooks`, ...) for what `spf watch` actually needs, which is
+ * a couple dozen REST calls, none of them exotic. `spf`'s own package stays
+ * dependency-free either way.
  *
  * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope), read once at
  * construction — matching the reference implementation's pattern and this
@@ -13,8 +15,11 @@
  * makes (a repo with >100 open `<prefix>:ready` issues at once is not this
  * version's problem to solve).
  */
-import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
-export declare class GitHubProvider implements IssueProvider, CodeHostProvider {
+import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueAuthoringProvider, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
+/** 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 declare const ISSUE_KINDS: readonly ["epic", "feature", "story", "bug", "task"];
+export type IssueKind = (typeof ISSUE_KINDS)[number];
+export declare class GitHubProvider implements IssueProvider, CodeHostProvider, IssueAuthoringProvider {
     private readonly repo;
     private readonly labelPrefix;
     private readonly token;
@@ -22,14 +27,17 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider {
     labelPrefix: string, token: string);
     private gh;
     private label;
+    private typeLabel;
     /** `null` on a real 404 (label doesn't exist yet) — any other non-2xx still throws, same as `gh()`. */
     private getLabel;
     /**
-     * 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.
      */
+    private ensureOneLabel;
     ensureLabels(): Promise<EnsureLabelsResult>;
     private toIssue;
     private listByLabel;
@@ -37,7 +45,10 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider {
     listInState(state: WatchState, opts?: {
         includeAll?: boolean;
     }): 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>;
     openPr(opts: {
@@ -47,6 +58,21 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider {
         base: string;
     }): Promise<PrRef>;
     prStatus(pr: PrRef): Promise<PrStatus>;
+    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). */
+    createIssue(input: {
+        title: string;
+        body: string;
+        labels: string[];
+    }): Promise<Issue>;
+    /**
+     * `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.
+     */
+    linkChild(parent: Issue, child: Issue): Promise<void>;
     private findMarkerComment;
     readMarker(issue: Issue): Promise<WatchMarker | null>;
     writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;