@gr8ful/spf 0.3.0 → 0.5.0

package/dist/core/git_helper.d.ts

@@ -16,8 +16,37 @@ export declare function isRepoAt(cwd: string): boolean;
  * not inside one — ADWs run fine in a non-git dir; only a commit phase
  * requires a repo. Always absolute, so it is safe to hand to a subprocess
  * regardless of where the ADW was launched from.
+ *
+ * `isRepoAt` only proves `git rev-parse --git-dir` succeeds, which is also
+ * true inside a bare repo and inside a `.git/` directory itself — neither
+ * has a work tree, so `--show-toplevel` fails there even though `isRepoAt`
+ * said yes. That failure is not a bug to propagate: there is still an
+ * honest answer (`cwd` itself), so it falls back rather than throwing —
+ * this function's whole contract is "never throws, always returns some root."
  */
 export declare function findRepoRoot(cwd: string): string;
+export interface CommitterIdentity {
+    name: string;
+    email: string;
+}
+/**
+ * `git config user.name`/`user.email` at `repoRoot` — `undefined` (never a
+ * fallback literal) when either is unset, so a caller can tell "no identity
+ * configured" from "identity is the empty string."
+ *
+ * Deliberately NOT `utils.engineerName()`: that helper tries the
+ * `ENGINEER_NAME` env var (spoofable by an operator), then `git config
+ * user.name`, then `$USER`/`$USERNAME`, and finally falls back to the
+ * literal string `"engineer"` when nothing is set — fine for a phase's
+ * display `owner`, but a `Signed-off-by:` trailer is a git attestation, and
+ * this is the one thing on this branch that ends up in one (see
+ * `chains/simple_sdlc.ts`'s `decideSignoff` and `chains/steps.ts`'s
+ * `commitEnvelope`). A trailer needs the identity git itself would use for
+ * the commit — `undefined` here means the caller records the sign-off
+ * decision in the trace anyway and skips the trailer with a logged note,
+ * rather than inventing a name for it.
+ */
+export declare function committerIdentity(repoRoot: string): CommitterIdentity | undefined;
 export interface GitHandle {
     currentBranch(): string;
     createBranch(name: string): string;

package/dist/core/git_helper.js

@@ -28,13 +28,53 @@ export function isRepoAt(cwd) {
  * not inside one — ADWs run fine in a non-git dir; only a commit phase
  * requires a repo. Always absolute, so it is safe to hand to a subprocess
  * regardless of where the ADW was launched from.
+ *
+ * `isRepoAt` only proves `git rev-parse --git-dir` succeeds, which is also
+ * true inside a bare repo and inside a `.git/` directory itself — neither
+ * has a work tree, so `--show-toplevel` fails there even though `isRepoAt`
+ * said yes. That failure is not a bug to propagate: there is still an
+ * honest answer (`cwd` itself), so it falls back rather than throwing —
+ * this function's whole contract is "never throws, always returns some root."
  */
 export function findRepoRoot(cwd) {
     if (isRepoAt(cwd)) {
-        return path.resolve(git(["rev-parse", "--show-toplevel"], cwd));
+        const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8" });
+        if (result.status === 0)
+            return path.resolve(result.stdout.trim());
     }
     return path.resolve(cwd);
 }
+/**
+ * `git config user.name`/`user.email` at `repoRoot` — `undefined` (never a
+ * fallback literal) when either is unset, so a caller can tell "no identity
+ * configured" from "identity is the empty string."
+ *
+ * Deliberately NOT `utils.engineerName()`: that helper tries the
+ * `ENGINEER_NAME` env var (spoofable by an operator), then `git config
+ * user.name`, then `$USER`/`$USERNAME`, and finally falls back to the
+ * literal string `"engineer"` when nothing is set — fine for a phase's
+ * display `owner`, but a `Signed-off-by:` trailer is a git attestation, and
+ * this is the one thing on this branch that ends up in one (see
+ * `chains/simple_sdlc.ts`'s `decideSignoff` and `chains/steps.ts`'s
+ * `commitEnvelope`). A trailer needs the identity git itself would use for
+ * the commit — `undefined` here means the caller records the sign-off
+ * decision in the trace anyway and skips the trailer with a logged note,
+ * rather than inventing a name for it.
+ */
+export function committerIdentity(repoRoot) {
+    const name = gitConfigValue(repoRoot, "user.name");
+    const email = gitConfigValue(repoRoot, "user.email");
+    if (!name || !email)
+        return undefined;
+    return { name, email };
+}
+/** `""` on anything short of a clean, non-empty value — unset, unreadable, or blank all read the same to a caller that only wants "do we have one?" */
+function gitConfigValue(repoRoot, key) {
+    const result = spawnSync("git", ["config", "--get", key], { cwd: repoRoot, encoding: "utf-8" });
+    if (result.status !== 0)
+        return "";
+    return result.stdout.trim();
+}
 /** Every operation this returns is bound to `repoRoot` — never `process.cwd()`. */
 export function makeGit(repoRoot) {
     const run = (args) => git(args, repoRoot);

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

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`. */