@gr8ful/spf 0.3.0 → 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

@@ -11,7 +11,7 @@
  * 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";
+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`. */

package/dist/core/refine.d.ts

@@ -0,0 +1,39 @@
+import type { Issue, IssueAuthoringProvider } from "./issues/provider.ts";
+import type { RefinedIssue, SFConfig } from "./data_types.ts";
+export interface PublishedIssue {
+    /** The `RefinedIssue.key` this came from — a run-local id, never a tracker id. */
+    key: string;
+    issue: Issue;
+    kind: RefinedIssue["kind"];
+    /** A node nothing else names as `parent` — the independently-workable unit `spf:refined` goes on. */
+    isLeaf: boolean;
+}
+/**
+ * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
+ * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
+ * yet. Throws rather than returning `null` so a `code` phase calling this
+ * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
+ * the same "fail loudly, never silently do nothing" contract
+ * `agents.validate()` uses for an unconfigured quality suite.
+ */
+export declare function resolveAuthoringProvider(cfg: SFConfig): IssueAuthoringProvider;
+export interface PublishOptions {
+    labelPrefix: string;
+    /** The originating spec issue's id, for every created issue's `## Parent` back-reference. `null`/omitted for a manual run with no source issue. */
+    specIssueId?: string | null;
+}
+/**
+ * Create every node in `issues`, in dependency order, with its
+ * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
+ * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
+ * via the tracker's native hierarchy, and render real `#n` references into
+ * `## Blocked by`. Returns what it created, in creation order.
+ *
+ * Not transactional: if a create or link call throws partway through, the
+ * nodes already published stay published, orphaned from whatever hadn't run
+ * yet. No rollback is attempted — the gate already ran, so this only fails
+ * on a live tracker error (rate limit, network), which a human re-running
+ * the spec (once the marker's `refined` list explains what already exists)
+ * can sort out same as any other `spf watch` failure.
+ */
+export declare function publish(tracker: IssueAuthoringProvider, issues: RefinedIssue[], opts: PublishOptions): Promise<PublishedIssue[]>;

package/dist/core/refine.js

@@ -0,0 +1,144 @@
+/**
+ * Publish logic for the refine lane: turn a gated `RefineOutput.issues` list
+ * (a product spec decomposed into a feature/story tree — see
+ * `RefinedIssueSchema` in `data_types.ts`) into real tracker issues, in
+ * dependency order, with the right labels and parent/child links. Nothing
+ * else: no marker bookkeeping, no `transition()`, no comment posted back
+ * onto the spec issue. Those are watch-lifecycle concerns `core/watch.ts`'s
+ * `runSpec` owns, exactly the way `runIssue` (the build lane) owns
+ * `openPr`/`transition` rather than a chain step doing it — this file is
+ * "given issues and a tracker, create them correctly," the one part
+ * `to-tickets` (the skill this lane's prompt is ported from) leaves
+ * entirely unspecified, and the part that makes a re-run duplicate every
+ * ticket (see `WatchMarker.refined`'s doc comment in `provider.ts` for how
+ * `runSpec` closes that gap using what this module returns).
+ */
+import { GitHubProvider } from "./issues/github_provider.js";
+/**
+ * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
+ * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
+ * yet. Throws rather than returning `null` so a `code` phase calling this
+ * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
+ * the same "fail loudly, never silently do nothing" contract
+ * `agents.validate()` uses for an unconfigured quality suite.
+ */
+export function resolveAuthoringProvider(cfg) {
+    if (cfg.watch.issue_provider !== "github") {
+        throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — ` +
+            `the refine lane needs "github" (see jira_provider.ts's module comment on why Jira isn't wired up yet)`);
+    }
+    if (!cfg.watch.repo.trim()) {
+        throw new Error(`watch.repo is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+    }
+    const token = process.env["GITHUB_TOKEN"];
+    if (!token) {
+        throw new Error('GITHUB_TOKEN is not set — the refine lane needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo)');
+    }
+    return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+}
+function typeLabel(labelPrefix, kind) {
+    return `${labelPrefix}:type:${kind}`;
+}
+/**
+ * The body GitHub actually stores: the refiner's own `## What to build` /
+ * `## Acceptance criteria` text, plus a `## Parent` back-reference to the
+ * source spec (when there is one — a bare `spf refine` run with no
+ * `--issue` has none), plus a `## Blocked by` section with real `#n`
+ * references — `to-tickets`' own template shape, ported. Every `blocked_by`
+ * key is guaranteed to already be in `byKey` by the time this runs:
+ * `topoOrder` visits a node's dependencies before the node itself.
+ */
+function renderBody(node, byKey, specIssueId) {
+    const parts = [node.body.trim()];
+    if (specIssueId)
+        parts.push(`## Parent\n\nDecomposed from #${specIssueId}.`);
+    if (node.blocked_by.length > 0) {
+        const refs = node.blocked_by.map((key) => {
+            const published = byKey.get(key);
+            // Defensive only: gates.refinementWellFormed already rejects a
+            // blocked_by key that doesn't resolve to another node in the list.
+            return published ? `#${published.issue.id}` : key;
+        });
+        parts.push(`## Blocked by\n\n${refs.map((r) => `- ${r}`).join("\n")}`);
+    }
+    else {
+        parts.push(`## Blocked by\n\nNone (can start immediately).`);
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Order nodes so every `parent` and every `blocked_by` reference is already
+ * published (a real issue, in `byKey`) before the node that names it —
+ * required both for the sub-issue link (the parent must exist first) and
+ * for `renderBody`'s `#n` references. `gates.refinementWellFormed` has
+ * already rejected a cyclic input by the time `publish()` ever runs; the
+ * `visiting` check here is a defensive backstop against a caller that
+ * skipped the gate, not the primary line of defense.
+ */
+function topoOrder(issues) {
+    const byKey = new Map(issues.map((i) => [i.key, i]));
+    const ordered = [];
+    const done = new Set();
+    const visiting = new Set();
+    function visit(node) {
+        if (done.has(node.key))
+            return;
+        if (visiting.has(node.key)) {
+            throw new Error(`refine: dependency cycle detected at key ${JSON.stringify(node.key)} — gates.refinementWellFormed should have caught this before publish ran`);
+        }
+        visiting.add(node.key);
+        for (const depKey of [node.parent, ...node.blocked_by]) {
+            if (!depKey)
+                continue;
+            const dep = byKey.get(depKey);
+            if (dep)
+                visit(dep);
+        }
+        visiting.delete(node.key);
+        done.add(node.key);
+        ordered.push(node);
+    }
+    for (const issue of issues)
+        visit(issue);
+    return ordered;
+}
+/**
+ * Create every node in `issues`, in dependency order, with its
+ * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
+ * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
+ * via the tracker's native hierarchy, and render real `#n` references into
+ * `## Blocked by`. Returns what it created, in creation order.
+ *
+ * Not transactional: if a create or link call throws partway through, the
+ * nodes already published stay published, orphaned from whatever hadn't run
+ * yet. No rollback is attempted — the gate already ran, so this only fails
+ * on a live tracker error (rate limit, network), which a human re-running
+ * the spec (once the marker's `refined` list explains what already exists)
+ * can sort out same as any other `spf watch` failure.
+ */
+export async function publish(tracker, issues, opts) {
+    const ordered = topoOrder(issues);
+    const childKeys = new Set(issues.filter((i) => i.parent).map((i) => i.parent));
+    const byKey = new Map();
+    const created = [];
+    for (const node of ordered) {
+        const isLeaf = !childKeys.has(node.key);
+        const labels = [typeLabel(opts.labelPrefix, node.kind)];
+        if (isLeaf)
+            labels.push(`${opts.labelPrefix}:refined`);
+        const body = renderBody(node, byKey, opts.specIssueId);
+        const issue = await tracker.createIssue({ title: node.title, body, labels });
+        const published = { key: node.key, issue, kind: node.kind, isLeaf };
+        byKey.set(node.key, published);
+        created.push(published);
+        if (node.parent) {
+            const parent = byKey.get(node.parent);
+            // topoOrder guarantees the parent was visited (and thus published)
+            // first; a missing entry here would mean the gate let an
+            // unresolved parent through, which refinementWellFormed rejects.
+            if (parent)
+                await tracker.linkChild(parent.issue, issue);
+        }
+    }
+    return created;
+}