@gr8ful/spf 0.3.0 → 0.4.0

package/dist/cli/commands/run.js

@@ -2,7 +2,7 @@
 import * as paths from "../../core/paths.js";
 import { parseCli, resolvePrompt } from "../../core/utils.js";
 import { runChain } from "../../chains/index.js";
-const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base"];
+const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base", "issue"];
 export function usageFor(chain) {
     return `usage: spf ${chain.name} "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id <id>] [--cwd <dir>]`;
 }
@@ -19,6 +19,10 @@ export async function dispatchChain(chain, argv) {
         adw_id: options["adw-id"] ?? null,
         cwd: anchor.cwd,
         chain_name: chain.name,
+        // Only `refine` reads this (a "## Parent: #<id>" back-reference on
+        // every issue it creates — see ChainContext's doc comment); every
+        // other chain ignores it, so it's harmless to always pass through.
+        issue_id: options["issue"] ?? null,
     };
     const chainOptions = {};
     if (options["agent"] !== undefined)

package/dist/cli/commands/watch.js

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

package/dist/cli/index.js

@@ -28,8 +28,8 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
 
   spf list                                  the chain registry — names, phases, what each needs
   spf <chain> "<prompt>" [options]          run a chain (spf run <chain> ... works identically)
-  spf init [--force] [--yes] [--template <name>]  interview to seed .spf/spf.config.yaml + .env (--yes/--template skip the interview)
-  spf install-skill [--user] [--force]      install the Claude Code skill (repo-local by default)
+  spf init [--force] [--yes] [--template <name>] [--no-skills]  interview to seed .spf/spf.config.yaml + .env, and install the Claude Code skill unless --no-skills (--yes/--template skip the interview, not the skill install)
+  spf install-skill [--user] [--force]      (re)install the Claude Code skill by hand — spf init already does this
   spf migrate [--apply] [--force]           move an old stamped adws/ tree onto .spf/ (dry run by default)
   spf eject [--target <dir>] [--force]      copy the installed engine out for reference/hand-editing
   spf doctor [--json]                       check everything that fails silently otherwise
@@ -42,7 +42,7 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf abort <adw_id>                        signal a run's process to stop
   spf version                               print the installed version
 
-Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>]
+Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>]
 Run \`spf list\` to see every chain and what it needs.`;
 /** A raw scan for `--cwd`, ahead of any command-specific argv parsing — every command that takes it means the same thing by it. */
 function findCwdFlag(argv) {

package/dist/cli/interview.js

@@ -231,6 +231,18 @@ export async function runInterview(asker, ctx) {
         const chainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
         const chain = await asker.select("Chain to run per issue", chainChoices, "plan-build-test");
         watch = { issue_provider: issueProvider, code_host: codeHost, repo, label_prefix: labelPrefix, chain, base_branch: baseBranch };
+        // Issue authoring (create + link a hierarchy) is only implemented on
+        // GitHubProvider today — see jira_provider.ts's module comment — so
+        // this lane isn't offered at all on a Jira tracker rather than asking a
+        // question that would just fail at `spf watch` startup.
+        if (issueProvider === "github") {
+            const enableRefine = await asker.confirm(`Also enable the refine lane (decompose a "${labelPrefix}:spec-ready" product spec into a feature/story-or-bug tree)?`, false);
+            if (enableRefine) {
+                const refineChainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
+                const refineChain = await asker.select("Chain to run per spec", refineChainChoices, "refine");
+                watch.refine = { enabled: true, chain: refineChain };
+            }
+        }
         if (issueProvider === "jira") {
             const baseUrl = await asker.text("Jira base URL", {
                 default: "https://your-domain.atlassian.net",
@@ -334,6 +346,11 @@ export async function runInterview(asker, ctx) {
             const concurrency = await asker.text("watch.concurrency", { default: "2" });
             if (concurrency !== "2")
                 watch.concurrency = Number(concurrency);
+            if (watch.refine?.enabled) {
+                const refineConcurrency = await asker.text("watch.refine.concurrency", { default: "1" });
+                if (refineConcurrency !== "1")
+                    watch.refine.concurrency = Number(refineConcurrency);
+            }
         }
         const engineerName = await asker.text("ENGINEER_NAME (falls back to `git config user.name`)", { default: ctx.gitName ?? "" });
         if (engineerName && engineerName !== ctx.gitName)

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,6 +454,15 @@ 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>;
 /**
@@ -516,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";
@@ -529,6 +602,11 @@ 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">;

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,7 @@ 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) —

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>;