@gr8ful/spf 0.6.0 → 0.7.0

package/dist/core/issues/github_provider.js

@@ -10,8 +10,11 @@ const STATES = [
     "refined",
     "needs-feedback",
     "continue-refinement",
+    "spec-in-progress",
 ];
 const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*?\})\s*-->/s;
+/** `listByLabel`'s pagination bound — see its own doc comment. */
+const MAX_LIST_PAGES = 5;
 /** 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 '#'.
@@ -26,6 +29,7 @@ const LABEL_META = {
     refined: { color: "c2e0c6", description: "generated by spf watch's refine lane — promote to spf:ready when it's worth building" },
     "needs-feedback": { color: "d93f0b", description: "spf's refiner needs a human answer before it can finish decomposing this spec" },
     "continue-refinement": { color: "0e8a16", description: "add this once you've answered — spf will resume refining from where it left off" },
+    "spec-in-progress": { color: "1d76db", description: "decomposed and published — waiting on every generated issue to reach spf:done" },
 };
 const TYPE_LABEL_META = {
     epic: { color: "5319e7", description: "a container generated by spf watch's refine lane — not directly workable" },
@@ -34,6 +38,24 @@ const TYPE_LABEL_META = {
     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" },
 };
+/**
+ * What `claimNewWork` (`watch.ts`) schedules by — see `RefinedPrioritySchema`
+ * in `data_types.ts`. Deliberately a LABEL, not this repo's own GitHub
+ * Projects v2 "Priority" field (a single-select with its own Urgent/High/
+ * Medium/Low options): a Projects v2 value is GraphQL-only, needs a
+ * `project` token scope and a project id in config, and has no Jira
+ * equivalent — the exact abstraction `jira_provider.ts` exists to protect.
+ * If a repo's board also carries a Priority field, the two are independent
+ * and nothing reconciles them; `spf watch` obeys only this label. See
+ * README.md's `spf watch` section for the reconciliation-by-hand caveat.
+ */
+const PRIORITIES = ["p0", "p1", "p2", "p3"];
+const PRIORITY_LABEL_META = {
+    p0: { color: "b60205", description: "drop everything — a broken promise to users, or blocking everything else" },
+    p1: { color: "d93f0b", description: "the spec's core value — the slices without which it isn't shipped" },
+    p2: { color: "fbca04", description: "the default — real scope, can wait a cycle" },
+    p3: { color: "c5def5", description: "worth writing down, not worth scheduling yet" },
+};
 export class GitHubProvider {
     repo;
     labelPrefix;
@@ -69,6 +91,10 @@ export class GitHubProvider {
     typeLabel(kind) {
         return `${this.labelPrefix}:type:${kind}`;
     }
+    /** Mirrors `core/refine.ts`'s own module-level `priorityLabel()` — that one stays provider-agnostic (a plain string, no `this`); this one is `ensureLabels()`'s seeding half. */
+    priorityLabel(priority) {
+        return `${this.labelPrefix}:priority:${priority}`;
+    }
     /** `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)}`, {
@@ -116,6 +142,13 @@ export class GitHubProvider {
             const { color, description } = TYPE_LABEL_META[kind];
             await this.ensureOneLabel(this.typeLabel(kind), color, description, result);
         }
+        // `<prefix>:priority:p0..p3` — what claimNewWork schedules by (see
+        // PRIORITY_LABEL_META's doc comment above on why this is a label, not
+        // this repo's own Projects v2 Priority field).
+        for (const priority of PRIORITIES) {
+            const { color, description } = PRIORITY_LABEL_META[priority];
+            await this.ensureOneLabel(this.priorityLabel(priority), color, description, result);
+        }
         return result;
     }
     toIssue(raw) {
@@ -127,9 +160,36 @@ export class GitHubProvider {
             labels: raw.labels.map((l) => (typeof l === "string" ? l : l.name)),
         };
     }
+    /**
+     * `sort=created&direction=asc` is stated, not inherited: without it,
+     * GitHub's own default (`created`, `desc` — newest first) is what
+     * `claimNewWork` used to walk, silently, which is why a >100-issue ready
+     * backlog used to be a real risk before pagination existed at all.
+     * Oldest-first is also `orderEligible`'s own final tiebreaker (`watch.ts`),
+     * so this method's order and that function's are the same order absent a
+     * priority/affinity difference — no redundant client-side re-sort needed
+     * for the plain case.
+     *
+     * Paginates up to `MAX_LIST_PAGES` (500 issues) — no longer "this
+     * version's problem to solve": a client-side priority sort over a
+     * truncated first page would silently misorder or hide real work, which is
+     * worse than the old unordered-100-issues behavior it replaces. A repo
+     * that still exceeds the cap gets a loud, named warning rather than a
+     * silent truncation.
+     */
     async listByLabel(label, state) {
-        const raw = await this.gh(`/repos/${this.repo}/issues?labels=${encodeURIComponent(label)}&state=${state}&per_page=100`);
-        return raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i));
+        const results = [];
+        for (let page = 1; page <= MAX_LIST_PAGES; page++) {
+            const raw = await this.gh(`/repos/${this.repo}/issues?labels=${encodeURIComponent(label)}&state=${state}&sort=created&direction=asc&per_page=100&page=${page}`);
+            results.push(...raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i)));
+            if (raw.length < 100)
+                return results; // short page — this was the last one
+            if (page === MAX_LIST_PAGES) {
+                console.error(`spf watch: listByLabel(${JSON.stringify(label)}) hit the ${MAX_LIST_PAGES}-page (${MAX_LIST_PAGES * 100}-issue) cap — ` +
+                    `older ${JSON.stringify(label)} issues past this cap are invisible this tick`);
+            }
+        }
+        return results;
     }
     async listEligible() {
         return this.listByLabel(this.label("ready"), "open");
@@ -137,6 +197,24 @@ export class GitHubProvider {
     async listInState(state, opts) {
         return this.listByLabel(this.label(state), opts?.includeAll ? "all" : "open");
     }
+    /** `null` on a real 404 — deleted, or (state defaults to open in a plain fetch) an issue GitHub itself considers gone. Any other non-2xx still throws, same as `gh()`. */
+    async getIssue(id) {
+        const response = await fetch(`${API}/repos/${this.repo}/issues/${id}`, {
+            headers: { Authorization: `Bearer ${this.token}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" },
+        });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`GitHub GET /repos/${this.repo}/issues/${id} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        return this.toIssue((await response.json()));
+    }
+    /** `GET .../sub_issues` — the read-back half of `linkChild`; what makes container roll-up possible (`rollUp` in `watch.ts`). Closed children ARE returned (no `state` filter) — roll-up needs to see a `blocked` child too, to correctly NOT finish the container. */
+    async listChildren(parent) {
+        const raw = await this.gh(`/repos/${this.repo}/issues/${parent.id}/sub_issues`);
+        return raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i));
+    }
     async claim(issue, opts) {
         const from = this.label(opts?.from ?? "ready");
         const to = this.label(opts?.to ?? "working");
@@ -209,7 +287,13 @@ export class GitHubProvider {
         }
         return { merged: detail.merged, state: detail.state, ciStatus };
     }
-    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). */
+    /**
+     * `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s
+     * module doc). `input.kind` is unused here: GitHub has no native
+     * issue-type field the way Jira does, and `input.labels` already carries
+     * `<prefix>:type:<kind>` for GitHub's own bookkeeping — the parameter
+     * exists on the shared interface for `JiraProvider`'s sake.
+     */
     async createIssue(input) {
         const raw = await this.gh(`/repos/${this.repo}/issues`, {
             method: "POST",

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

@@ -30,25 +30,45 @@
  * 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.
+ * Implements `IssueAuthoringProvider` — the refine lane's create/link seam
+ * — via Jira's native issue types plus the `parent` field: `createIssue`
+ * maps a `RefinedIssue.kind` to a real Jira issue type name through the
+ * configured `issueTypes` map (project setups rename/customize these often
+ * enough that hardcoding "Epic"/"Story"/"Bug"/"Task" would break silently
+ * on plenty of real projects), and `linkChild` sets the child's `parent`
+ * field to the parent's key. This is the MODERN mechanism only — it works
+ * on team-managed projects and on company-managed projects with Jira's
+ * current issue-hierarchy setting; it does NOT fall back to the legacy
+ * "Epic Link" custom field some older company-managed projects still rely
+ * on. A project not configured for `parent`-based hierarchy gets Jira's own
+ * API error surfaced as-is (this file's `jira()` wrapper never swallows a
+ * non-2xx), never silently ignored. `listChildren` reads the hierarchy back
+ * via a `parent = "<id>"` JQL search (same POST-body pattern
+ * `searchByLabel` already uses below), which is what makes container
+ * roll-up (`rollUp` in `watch.ts`) work here too, not just on GitHub.
+ * `validateIssueTypes()` (below) is a plain method, not part of any shared
+ * interface — GitHub has no equivalent concept — that `spf watch init` and
+ * `spf watch`'s own startup check (`cli/commands/watch.ts`) both call to
+ * catch a misconfigured `issueTypes` entry before anything unattended runs.
+ *
+ * One accepted platform limitation: Jira doesn't support Epic-under-Epic
+ * nesting the way GitHub's sub-issues API supports up to 8 levels. A
+ * refiner tree with a `feature` node parented under another `epic`/
+ * `feature` (both mapping to Jira's Epic type by default) surfaces a real
+ * Jira API error at publish time — a genuine platform difference, not
+ * something this file tries to paper over.
  */
-import type { EnsureLabelsResult, Issue, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
-export declare class JiraProvider implements IssueProvider {
+import type { RefinedIssue, JiraIssueTypeMap } from "../data_types.ts";
+import type { EnsureLabelsResult, Issue, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
+export declare class JiraProvider implements IssueProvider, IssueAuthoringProvider {
     private readonly baseUrl;
     private readonly projectKey;
     private readonly labelPrefix;
     private readonly email;
     private readonly apiToken;
+    private readonly issueTypes;
     constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey: string, labelPrefix: string, email: string, apiToken: string);
+    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap);
     private authHeader;
     private jira;
     private label;
@@ -73,6 +93,53 @@ export declare class JiraProvider implements IssueProvider {
      * could make a `review`-labeled issue vanish from an unfiltered query.
      */
     listInState(state: WatchState): Promise<Issue[]>;
+    /**
+     * `null` on a real 404 (deleted, or a key that never existed) — any other
+     * non-2xx still throws, same as `jira()`. What `claimNewWork`'s frontier
+     * check (`watch.ts`) uses to look up a `blocked_by` id's current labels.
+     * Unlike `github_provider.ts`'s hidden `spf-refine:` body marker, this
+     * file has no equivalent for a Jira issue's OWN parent/blockers — a
+     * caller here only ever sees what `blocked_by` it already has in hand,
+     * never discovers it from the issue body itself.
+     */
+    getIssue(id: string): Promise<Issue | null>;
+    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). `POST /rest/api/3/issue`'s response is `{id, key, self}`, not the full read shape `toIssue` expects, so this constructs the returned `Issue` locally rather than re-fetching. */
+    createIssue(input: {
+        title: string;
+        body: string;
+        labels: string[];
+        kind: RefinedIssue["kind"];
+    }): Promise<Issue>;
+    /**
+     * The modern mechanism only — Jira's `parent` field, not the legacy
+     * "Epic Link" custom field. Works on team-managed projects and on
+     * company-managed projects with Jira's current issue-hierarchy setting;
+     * a project not configured for it surfaces Jira's own API error here,
+     * unmodified — see this file's module comment on the accepted
+     * Epic-under-Epic limitation this implies.
+     */
+    linkChild(parent: Issue, child: Issue): Promise<void>;
+    /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
+    listChildren(parent: Issue): Promise<Issue[]>;
+    /**
+     * Read-only validation of the configured `issueTypes` map against this
+     * project's real issue types — what `spf watch init` and `spf watch`'s
+     * own refine-lane startup check (`cli/commands/watch.ts`) both call to
+     * catch a bad mapping before anything unattended runs on it, rather than
+     * discovering it the first time a spec tries to publish. Not part of
+     * `IssueAuthoringProvider` — GitHub has no equivalent concept, since it
+     * has no native issue-type field to get wrong.
+     *
+     * Fetches a single page (Jira's own default: 50) — a project with more
+     * issue types than that is exotic enough to warrant a loud warning
+     * rather than a silent multi-page fetch loop for an edge case this
+     * unlikely.
+     */
+    validateIssueTypes(): Promise<Array<{
+        kind: string;
+        jiraType: string;
+        exists: boolean;
+    }>>;
     claim(issue: Issue, opts?: {
         from?: WatchState;
         to?: WatchState;

package/dist/core/issues/jira_provider.js

@@ -9,6 +9,7 @@ const STATES = [
     "refined",
     "needs-feedback",
     "continue-refinement",
+    "spec-in-progress",
 ];
 const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*?\})/s;
 function toAdf(text) {
@@ -35,13 +36,15 @@ export class JiraProvider {
     labelPrefix;
     email;
     apiToken;
+    issueTypes;
     constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey, labelPrefix, email, apiToken) {
+    projectKey, labelPrefix, email, apiToken, issueTypes) {
         this.baseUrl = baseUrl;
         this.projectKey = projectKey;
         this.labelPrefix = labelPrefix;
         this.email = email;
         this.apiToken = apiToken;
+        this.issueTypes = issueTypes;
     }
     authHeader() {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
@@ -114,6 +117,86 @@ export class JiraProvider {
     async listInState(state) {
         return this.searchByLabel(this.label(state));
     }
+    /**
+     * `null` on a real 404 (deleted, or a key that never existed) — any other
+     * non-2xx still throws, same as `jira()`. What `claimNewWork`'s frontier
+     * check (`watch.ts`) uses to look up a `blocked_by` id's current labels.
+     * Unlike `github_provider.ts`'s hidden `spf-refine:` body marker, this
+     * file has no equivalent for a Jira issue's OWN parent/blockers — a
+     * caller here only ever sees what `blocked_by` it already has in hand,
+     * never discovers it from the issue body itself.
+     */
+    async getIssue(id) {
+        const response = await fetch(`${this.baseUrl}/rest/api/3/issue/${id}?fields=summary,description,labels`, {
+            headers: { Authorization: this.authHeader(), Accept: "application/json" },
+        });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`Jira GET /rest/api/3/issue/${id} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        return this.toIssue((await response.json()));
+    }
+    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). `POST /rest/api/3/issue`'s response is `{id, key, self}`, not the full read shape `toIssue` expects, so this constructs the returned `Issue` locally rather than re-fetching. */
+    async createIssue(input) {
+        const response = await this.jira("/rest/api/3/issue", {
+            method: "POST",
+            body: JSON.stringify({
+                fields: {
+                    project: { key: this.projectKey },
+                    summary: input.title,
+                    description: toAdf(input.body),
+                    issuetype: { name: this.issueTypes[input.kind] },
+                    labels: input.labels,
+                },
+            }),
+        });
+        return { id: response.key, title: input.title, body: input.body, labels: input.labels };
+    }
+    /**
+     * The modern mechanism only — Jira's `parent` field, not the legacy
+     * "Epic Link" custom field. Works on team-managed projects and on
+     * company-managed projects with Jira's current issue-hierarchy setting;
+     * a project not configured for it surfaces Jira's own API error here,
+     * unmodified — see this file's module comment on the accepted
+     * Epic-under-Epic limitation this implies.
+     */
+    async linkChild(parent, child) {
+        await this.jira(`/rest/api/3/issue/${child.id}`, { method: "PUT", body: JSON.stringify({ fields: { parent: { key: parent.id } } }) });
+    }
+    /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
+    async listChildren(parent) {
+        const jql = `parent = ${JSON.stringify(parent.id)}`;
+        const result = await this.jira("/rest/api/3/search/jql", {
+            method: "POST",
+            body: JSON.stringify({ jql, maxResults: 100, fields: ["summary", "description", "labels"] }),
+        });
+        return result.issues.map((i) => this.toIssue(i));
+    }
+    /**
+     * Read-only validation of the configured `issueTypes` map against this
+     * project's real issue types — what `spf watch init` and `spf watch`'s
+     * own refine-lane startup check (`cli/commands/watch.ts`) both call to
+     * catch a bad mapping before anything unattended runs on it, rather than
+     * discovering it the first time a spec tries to publish. Not part of
+     * `IssueAuthoringProvider` — GitHub has no equivalent concept, since it
+     * has no native issue-type field to get wrong.
+     *
+     * Fetches a single page (Jira's own default: 50) — a project with more
+     * issue types than that is exotic enough to warrant a loud warning
+     * rather than a silent multi-page fetch loop for an edge case this
+     * unlikely.
+     */
+    async validateIssueTypes() {
+        const result = await this.jira(`/rest/api/3/issue/createmeta/${encodeURIComponent(this.projectKey)}/issuetypes`);
+        if (result.isLast === false) {
+            console.error(`spf watch: ${this.projectKey} has more issue types than one page reports — validateIssueTypes() may be missing some; ` +
+                `re-run with a narrower watch.jira.issue_types check if a false mismatch shows up`);
+        }
+        const available = new Set(result.issueTypes.map((t) => t.name));
+        return Object.entries(this.issueTypes).map(([kind, jiraType]) => ({ kind, jiraType, exists: available.has(jiraType) }));
+    }
     async claim(issue, opts) {
         const from = this.label(opts?.from ?? "ready");
         const to = this.label(opts?.to ?? "working");

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

@@ -9,19 +9,25 @@
  * interfaces, not one bundled seam — a tracker and a code host are
  * independent choices in practice (Jira issues against a Bitbucket repo is
  * a real setup, not a hypothetical one). `github_provider.ts`'s single
- * class implements both, since GitHub natively is both; `jira_provider.ts`
- * 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.
+ * class implements all three (GitHub natively is a tracker, a code host,
+ * AND an authoring API); `jira_provider.ts` implements `IssueProvider` and
+ * `IssueAuthoringProvider` (Jira is a tracker and can author, but never
+ * opens PRs); `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.
+ * third, again separate — the refine lane's own need, optional per tracker
+ * (not every tracker's write API can author + link a hierarchy), and
+ * orthogonal to which one is the code host. `isAuthoringProvider()` (below)
+ * is how the rest of the codebase asks "can this provider author?" without
+ * caring which concrete class answers yes.
  *
  * 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.
  */
+import type { RefinedIssue } from "../data_types.ts";
 /**
  * `spec-ready`/`refining` drive the SECOND lane's state machine (a product
  * spec being decomposed — see `reconcileRefining`/`claimSpecs` in
@@ -42,13 +48,23 @@
  * the issue id) with the comment thread folded into the prompt. This can
  * loop any number of rounds; there is no cap.
  *
- * All ten still live in one `WatchState` union (not several 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.
+ * `spec-in-progress` is where a spec lands once it's been decomposed and
+ * published — deliberately NOT `done` yet: a product manager watching this
+ * spec's status must not see "done" until every issue the refiner produced
+ * (every story/bug/task, and every feature/epic container once its own
+ * children finish — see `rollUp` in `watch.ts`) is itself `<prefix>:done`.
+ * `announceRefined` (`watch.ts`) makes the move `refining -> spec-in-progress`
+ * once publish succeeds; `finishTrackedSpecs` (`watch.ts`) polls every
+ * `spec-in-progress` spec each tick and moves it the rest of the way,
+ * `-> done`, once `WatchMarker.refined` is entirely `<prefix>:done`.
+ *
+ * All eleven still live in one `WatchState` union (not several 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" | "needs-feedback" | "continue-refinement";
+export type WatchState = "ready" | "working" | "review" | "done" | "blocked" | "spec-ready" | "refining" | "refined" | "needs-feedback" | "continue-refinement" | "spec-in-progress";
 export interface Issue {
     /** Opaque tracker identifier: a GitHub issue number stringified ("42"), a Jira key ("PROJ-123"). */
     id: string;
@@ -94,7 +110,10 @@ export interface PrStatus {
  * 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.
+ * duplicates every ticket on a re-run; this is what closes that gap. It does
+ * double duty once the spec reaches `spec-in-progress`: `finishTrackedSpecs`
+ * (`watch.ts`) reads this same list back to check whether every one of them
+ * is `<prefix>:done` yet — the gate on the spec's OWN move to `done`.
  *
  * `feedback` is the refine lane's human-in-the-loop cursor: `rounds` counts
  * how many times this spec has been escalated (so a resumed run's summary
@@ -134,6 +153,15 @@ export interface IssueProvider {
     ensureLabels(): Promise<EnsureLabelsResult>;
     /** Issues currently labeled `<prefix>:ready`. */
     listEligible(): Promise<Issue[]>;
+    /**
+     * One issue by its tracker-facing id, or `null` if it no longer exists
+     * (deleted, or — on a tracker where a closed item 404s a plain fetch —
+     * closed). The frontier check needs this on every tracker (`claimNewWork`
+     * in `watch.ts` calls it once per distinct `blocked_by` id per tick, to
+     * decide whether a leaf's blockers all carry `<prefix>:done`), so unlike
+     * `IssueAuthoringProvider`'s methods below, this is required, not optional.
+     */
+    getIssue(id: string): Promise<Issue | null>;
     /**
      * Issues currently in `state`. `includeAll` queries closed issues too —
      * required for `review` on a tracker where closing an issue is a side
@@ -209,18 +237,44 @@ export interface 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.
+ * every tracker can do this — GitHub and Jira both implement it today
+ * (GitHub via sub-issues, Jira via native issue types + the `parent`
+ * field), Bitbucket does not — and a tracker that can't should be
+ * recognized as such via `isAuthoringProvider()` (below), not a method
+ * that throws at call time.
  */
 export interface IssueAuthoringProvider {
     createIssue(input: {
         title: string;
         body: string;
         labels: string[];
+        kind: RefinedIssue["kind"];
     }): Promise<Issue>;
-    /** Link `child` under `parent` using the tracker's native hierarchy — GitHub's sub-issues API today. */
+    /** Link `child` under `parent` using the tracker's native hierarchy — GitHub's sub-issues API, Jira's `parent` field. */
     linkChild(parent: Issue, child: Issue): Promise<void>;
+    /**
+     * Read back what `linkChild` wrote — every issue currently linked under
+     * `parent`. What makes container roll-up possible at all (`rollUp` in
+     * `watch.ts`: a container is `done` once every one of these carries
+     * `<prefix>:done`); lives here rather than on `IssueProvider` for the same
+     * reason `linkChild` does — a tracker's plain list/claim/transition surface
+     * has no reason to know about a hierarchy it may not even have. A tracker
+     * without this (Bitbucket-as-issue-tracker isn't a real combination this
+     * codebase supports, so in practice: any provider that isn't `IssueAuthoringProvider`
+     * at all) makes roll-up a logged no-op, not a startup failure the way
+     * `watch.refine.enabled` without ANY authoring support is
+     * (`cli/commands/watch.ts`) — the build lane still functions without
+     * roll-up, refine cannot function without authoring at all.
+     */
+    listChildren(parent: Issue): Promise<Issue[]>;
 }
+/**
+ * Structural, not nominal: checks for the three methods rather than
+ * `instanceof SomeConcreteClass` — so a new authoring-capable provider is
+ * recognized automatically everywhere this is used (today: `cli/commands/
+ * watch.ts`'s container-roll-up wiring) without an edit to an `instanceof`
+ * chain. Every current implementer (`GitHubProvider`, `JiraProvider`)
+ * satisfies `IssueProvider` too, so the intersection type is sound in
+ * practice, not just at the type level.
+ */
+export declare function isAuthoringProvider(provider: IssueProvider): provider is IssueProvider & IssueAuthoringProvider;

package/dist/core/issues/provider.js

@@ -9,17 +9,34 @@
  * interfaces, not one bundled seam — a tracker and a code host are
  * independent choices in practice (Jira issues against a Bitbucket repo is
  * a real setup, not a hypothetical one). `github_provider.ts`'s single
- * class implements both, since GitHub natively is both; `jira_provider.ts`
- * 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.
+ * class implements all three (GitHub natively is a tracker, a code host,
+ * AND an authoring API); `jira_provider.ts` implements `IssueProvider` and
+ * `IssueAuthoringProvider` (Jira is a tracker and can author, but never
+ * opens PRs); `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.
+ * third, again separate — the refine lane's own need, optional per tracker
+ * (not every tracker's write API can author + link a hierarchy), and
+ * orthogonal to which one is the code host. `isAuthoringProvider()` (below)
+ * is how the rest of the codebase asks "can this provider author?" without
+ * caring which concrete class answers yes.
  *
  * 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 {};
+/**
+ * Structural, not nominal: checks for the three methods rather than
+ * `instanceof SomeConcreteClass` — so a new authoring-capable provider is
+ * recognized automatically everywhere this is used (today: `cli/commands/
+ * watch.ts`'s container-roll-up wiring) without an edit to an `instanceof`
+ * chain. Every current implementer (`GitHubProvider`, `JiraProvider`)
+ * satisfies `IssueProvider` too, so the intersection type is sound in
+ * practice, not just at the type level.
+ */
+export function isAuthoringProvider(provider) {
+    const candidate = provider;
+    return typeof candidate.createIssue === "function" && typeof candidate.linkChild === "function" && typeof candidate.listChildren === "function";
+}

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" | "spec_refined" | "spec_needs_feedback";
+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" | "spec_needs_feedback" | "feature_done" | "spec_done";
 export interface NotifyEvent {
     kind: NotifyKind;
     /** "error" sends under both `events: errors` and `events: all`; "info" only under `all`. */