@gr8ful/spf 0.6.0 → 0.8.0

package/dist/core/data_types.d.ts

@@ -164,6 +164,20 @@ export type DocumentOutputT = v.InferOutput<typeof DocumentOutput.schema>;
  * this list before publish ever runs (unique keys, resolvable references,
  * no cycles, container/leaf kind agreement, at least one leaf).
  */
+/**
+ * `p0` (drop everything) .. `p3` (someday) — see `assets/prompts/refiner/system.md`'s
+ * `## Priority` section for what each rung means. Two rules the schema alone
+ * can't enforce, checked instead by `gates.refinementWellFormed`
+ * (monotonicity: no node outranks its `parent`) and `core/refine.ts`'s
+ * `publish()` (the spec's own priority, when known, is a ceiling clamped onto
+ * every node): see both files' doc comments.
+ */
+export declare const RefinedPrioritySchema: v.PicklistSchema<["p0", "p1", "p2", "p3"], undefined>;
+export type RefinedPriority = v.InferOutput<typeof RefinedPrioritySchema>;
+/** Lower rank = more urgent. The one place both `gates.refinementWellFormed` (monotonicity) and `core/refine.ts`'s `publish()` (the spec-priority ceiling) get their ordering from — see `RefinedPrioritySchema`'s doc comment. */
+export declare const PRIORITY_RANK: Record<RefinedPriority, number>;
+/** `priority`, pulled down to `ceiling` if it outranks it — never raised. `ceiling` nullish (a bare `spf refine` with nothing to inherit from) is a no-op. */
+export declare function clampPriority(priority: RefinedPriority, ceiling: RefinedPriority | null | undefined): RefinedPriority;
 export declare const RefinedIssueSchema: v.ObjectSchema<{
     readonly key: v.StringSchema<undefined>;
     readonly kind: v.PicklistSchema<["epic", "feature", "story", "bug", "task"], undefined>;
@@ -171,6 +185,7 @@ export declare const RefinedIssueSchema: v.ObjectSchema<{
     readonly body: v.StringSchema<undefined>;
     readonly parent: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly blocked_by: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly priority: v.OptionalSchema<v.PicklistSchema<["p0", "p1", "p2", "p3"], undefined>, "p2">;
 }, undefined>;
 export type RefinedIssue = v.InferOutput<typeof RefinedIssueSchema>;
 /**
@@ -208,6 +223,7 @@ export declare const RefineOutput: EnvelopeType<{
         body: string;
         parent: string;
         blocked_by: string[];
+        priority: "p0" | "p1" | "p2" | "p3";
     }[];
     questions: {
         id: string;
@@ -534,10 +550,50 @@ export declare const WatchIssueProviderSchema: v.PicklistSchema<["github", "jira
 export type WatchIssueProviderKind = v.InferOutput<typeof WatchIssueProviderSchema>;
 export declare const WatchCodeHostSchema: v.PicklistSchema<["github", "bitbucket"], undefined>;
 export type WatchCodeHostKind = v.InferOutput<typeof WatchCodeHostSchema>;
-/** Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. */
+/**
+ * What each `RefinedIssue.kind` creates as, on Jira — Jira's create endpoint
+ * requires a real `issuetype`, and project setups vary (renamed types,
+ * non-English instances, custom schemes), so this is a name -> name map,
+ * not a hardcoded assumption. Every field defaults independently: a config
+ * that only sets `bug: Defect` still gets Epic/Epic/Story/Task for the
+ * other four. `jira_provider.ts`'s `createIssue`/`validateIssueTypes` are
+ * the readers; `spf watch init` and `spf watch`'s own startup check
+ * (`cli/commands/watch.ts`) both validate this against the real project
+ * before anything unattended runs on it.
+ */
+export declare const JiraIssueTypeMapSchema: v.ObjectSchema<{
+    readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+    readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+    readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+    readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+    readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+}, undefined>;
+export type JiraIssueTypeMap = v.InferOutput<typeof JiraIssueTypeMapSchema>;
+/**
+ * Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` +
+ * `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. Whole-
+ * object replace on config-file-layer merge, like `refine`/
+ * `observability.otel` (see `agents.ts`'s `mergeRawConfig`) — an override
+ * file that touches `watch.jira` at all must repeat `issue_types` too if it
+ * wants to keep a customized mapping, same caveat that already applies to
+ * `base_url`/`project_key` today.
+ */
 export declare const WatchJiraConfigSchema: v.ObjectSchema<{
     readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly issue_types: v.OptionalSchema<v.ObjectSchema<{
+        readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+        readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+        readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+        readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+        readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+    }, undefined>, () => {
+        epic: string;
+        feature: string;
+        story: string;
+        bug: string;
+        task: string;
+    }>;
 }, undefined>;
 export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
 /**
@@ -545,10 +601,10 @@ export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
  * spec into a feature/story tree of real issues, instead of running
  * `watch.chain` against it directly (a spec is not individually workable —
  * see `core/refine.ts`). Off by default so an existing `watch:` config's
- * behavior is unchanged by upgrading; turning it on with
- * `issue_provider: jira` fails loudly at `spf watch` startup, since
- * `JiraProvider` doesn't implement `IssueAuthoringProvider` (create/link)
- * yet — see its module comment.
+ * behavior is unchanged by upgrading. Needs `issue_provider: github` or
+ * `"jira"` — both implement `IssueAuthoringProvider` (create/link/list) —
+ * any other value fails loudly at `spf watch` startup rather than running a
+ * refine lane that can never publish anything.
  */
 export declare const WatchRefineConfigSchema: v.ObjectSchema<{
     readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -585,9 +641,29 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
     readonly jira: v.OptionalSchema<v.ObjectSchema<{
         readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
         readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly issue_types: v.OptionalSchema<v.ObjectSchema<{
+            readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+            readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+            readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+            readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+            readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+        }, undefined>, () => {
+            epic: string;
+            feature: string;
+            story: string;
+            bug: string;
+            task: string;
+        }>;
     }, undefined>, () => {
         base_url: string;
         project_key: string;
+        issue_types: {
+            epic: string;
+            feature: string;
+            story: string;
+            bug: string;
+            task: string;
+        };
     }>;
     readonly refine: v.OptionalSchema<v.ObjectSchema<{
         readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -873,9 +949,29 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly jira: v.OptionalSchema<v.ObjectSchema<{
             readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
             readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+            readonly issue_types: v.OptionalSchema<v.ObjectSchema<{
+                readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+                readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+                readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+                readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+                readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+            }, undefined>, () => {
+                epic: string;
+                feature: string;
+                story: string;
+                bug: string;
+                task: string;
+            }>;
         }, undefined>, () => {
             base_url: string;
             project_key: string;
+            issue_types: {
+                epic: string;
+                feature: string;
+                story: string;
+                bug: string;
+                task: string;
+            };
         }>;
         readonly refine: v.OptionalSchema<v.ObjectSchema<{
             readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -902,6 +998,13 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         jira: {
             base_url: string;
             project_key: string;
+            issue_types: {
+                epic: string;
+                feature: string;
+                story: string;
+                bug: string;
+                task: string;
+            };
         };
         refine: {
             enabled: boolean;

package/dist/core/data_types.js

@@ -117,6 +117,23 @@ export const DocumentOutput = envelopeType("DocumentOutput", {
  * this list before publish ever runs (unique keys, resolvable references,
  * no cycles, container/leaf kind agreement, at least one leaf).
  */
+/**
+ * `p0` (drop everything) .. `p3` (someday) — see `assets/prompts/refiner/system.md`'s
+ * `## Priority` section for what each rung means. Two rules the schema alone
+ * can't enforce, checked instead by `gates.refinementWellFormed`
+ * (monotonicity: no node outranks its `parent`) and `core/refine.ts`'s
+ * `publish()` (the spec's own priority, when known, is a ceiling clamped onto
+ * every node): see both files' doc comments.
+ */
+export const RefinedPrioritySchema = v.picklist(["p0", "p1", "p2", "p3"]);
+/** Lower rank = more urgent. The one place both `gates.refinementWellFormed` (monotonicity) and `core/refine.ts`'s `publish()` (the spec-priority ceiling) get their ordering from — see `RefinedPrioritySchema`'s doc comment. */
+export const PRIORITY_RANK = { p0: 0, p1: 1, p2: 2, p3: 3 };
+/** `priority`, pulled down to `ceiling` if it outranks it — never raised. `ceiling` nullish (a bare `spf refine` with nothing to inherit from) is a no-op. */
+export function clampPriority(priority, ceiling) {
+    if (!ceiling)
+        return priority;
+    return PRIORITY_RANK[priority] < PRIORITY_RANK[ceiling] ? ceiling : priority;
+}
 export const RefinedIssueSchema = v.object({
     key: v.string(),
     kind: v.picklist(["epic", "feature", "story", "bug", "task"]),
@@ -124,6 +141,7 @@ export const RefinedIssueSchema = v.object({
     body: v.string(), // "## What to build" / "## Acceptance criteria" — see assets/prompts/refiner/user.md
     parent: v.optional(v.string(), ""), // another node's `key`; "" = top level
     blocked_by: v.optional(v.array(v.string()), () => []), // other nodes' `key`s that must land first
+    priority: v.optional(RefinedPrioritySchema, "p2"), // what spf watch's build lane schedules by — see RefinedPrioritySchema
 });
 /**
  * One open question the refiner could not answer itself — material ambiguity
@@ -439,20 +457,47 @@ export const ObservabilityConfigSchema = v.object({
  */
 export const WatchIssueProviderSchema = v.picklist(["github", "jira"]);
 export const WatchCodeHostSchema = v.picklist(["github", "bitbucket"]);
-/** Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. */
+/**
+ * What each `RefinedIssue.kind` creates as, on Jira — Jira's create endpoint
+ * requires a real `issuetype`, and project setups vary (renamed types,
+ * non-English instances, custom schemes), so this is a name -> name map,
+ * not a hardcoded assumption. Every field defaults independently: a config
+ * that only sets `bug: Defect` still gets Epic/Epic/Story/Task for the
+ * other four. `jira_provider.ts`'s `createIssue`/`validateIssueTypes` are
+ * the readers; `spf watch init` and `spf watch`'s own startup check
+ * (`cli/commands/watch.ts`) both validate this against the real project
+ * before anything unattended runs on it.
+ */
+export const JiraIssueTypeMapSchema = v.object({
+    epic: v.optional(v.string(), "Epic"),
+    feature: v.optional(v.string(), "Epic"),
+    story: v.optional(v.string(), "Story"),
+    bug: v.optional(v.string(), "Bug"),
+    task: v.optional(v.string(), "Task"),
+});
+/**
+ * Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` +
+ * `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. Whole-
+ * object replace on config-file-layer merge, like `refine`/
+ * `observability.otel` (see `agents.ts`'s `mergeRawConfig`) — an override
+ * file that touches `watch.jira` at all must repeat `issue_types` too if it
+ * wants to keep a customized mapping, same caveat that already applies to
+ * `base_url`/`project_key` today.
+ */
 export const WatchJiraConfigSchema = v.object({
     base_url: v.optional(v.string(), ""), // e.g. "https://your-domain.atlassian.net"
     project_key: v.optional(v.string(), ""), // e.g. "PROJ"
+    issue_types: v.optional(JiraIssueTypeMapSchema, () => v.parse(JiraIssueTypeMapSchema, {})),
 });
 /**
  * The second `spf watch` lane: decompose a `<prefix>:spec-ready` product
  * spec into a feature/story tree of real issues, instead of running
  * `watch.chain` against it directly (a spec is not individually workable —
  * see `core/refine.ts`). Off by default so an existing `watch:` config's
- * behavior is unchanged by upgrading; turning it on with
- * `issue_provider: jira` fails loudly at `spf watch` startup, since
- * `JiraProvider` doesn't implement `IssueAuthoringProvider` (create/link)
- * yet — see its module comment.
+ * behavior is unchanged by upgrading. Needs `issue_provider: github` or
+ * `"jira"` — both implement `IssueAuthoringProvider` (create/link/list) —
+ * any other value fails loudly at `spf watch` startup rather than running a
+ * refine lane that can never publish anything.
  */
 export const WatchRefineConfigSchema = v.object({
     enabled: v.optional(v.boolean(), false),

package/dist/core/fanout.d.ts

@@ -214,6 +214,15 @@ export interface FanoutDeps {
      * ABORT GRANULARITY note.
      */
     firstSuccess?: boolean;
+    /**
+     * Fires once per attempt the moment it settles (success, fail, error, or
+     * skipped) — the same record that lands in the final `attempts` array, just
+     * as it happens instead of only once every worker has finished. Purely
+     * observational: nothing here changes selection or cleanup. `cli/commands/
+     * fanout.ts` uses it to update a live results table row by row on a TTY;
+     * omitted (the default) everywhere else, including every test.
+     */
+    onAttempt?: (attempt: FanoutAttempt) => void;
 }
 /**
  * Run `n` attempts of one prompt, select deterministically, clean up the

package/dist/core/fanout.js

@@ -284,10 +284,14 @@ export async function runBestOf(deps) {
                 return;
             if (decided) {
                 deps.log(`fanout: attempt ${index} skipped — an earlier attempt already succeeded`);
-                attempts.push(skipped(index));
+                const attempt = skipped(index);
+                attempts.push(attempt);
+                deps.onAttempt?.(attempt);
                 continue;
             }
-            attempts.push(await runOne(index));
+            const attempt = await runOne(index);
+            attempts.push(attempt);
+            deps.onAttempt?.(attempt);
         }
     };
     const workers = Array.from({ length: Math.max(1, Math.min(deps.concurrency, deps.n)) }, () => worker());

package/dist/core/gates.js

@@ -17,7 +17,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, statSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { GateReport } from "./data_types.js";
+import { GateReport, PRIORITY_RANK } from "./data_types.js";
 import { operatorEnv } from "./utils.js";
 const TAIL_CHARS = 1000; // command output kept as evidence on a failure
 /**
@@ -252,6 +252,29 @@ export function refinementWellFormed(envelope, _run) {
     }
     const leafCount = issues.filter((i) => !childKeys.has(i.key)).length;
     report.check("has leaves", leafCount > 0, leafCount > 0 ? `${leafCount} leaf issue(s)` : "every node is a container — nothing here is independently workable");
+    // Monotonicity: no node may be MORE urgent than its own parent — p0 < p1 <
+    // p2 < p3, so "more urgent" is a lower rank. Only checked against `parent`
+    // (the containment edge), never `blocked_by` (a real dependency can easily
+    // be less urgent than the thing it blocks — a p3 prefactor gating a p0
+    // feature is normal, not a mistake). A violation here is a decomposition
+    // mistake worth a correction round-trip (this gate's `retries: 1` —
+    // steps.ts's `refine()`), not a hard block: a p0 story wearing a p3
+    // feature's parent almost always means the feature was mis-scored, not the
+    // story. The spec's OWN priority ceiling is enforced separately, in
+    // `core/refine.ts`'s `publish()` — this gate only knows about the tree,
+    // never the spec issue it came from.
+    for (const issue of issues) {
+        if (!issue.parent)
+            continue;
+        const parent = byKey.get(issue.parent);
+        if (!parent)
+            continue; // already reported above as an unresolved parent
+        const childRank = PRIORITY_RANK[issue.priority] ?? 2;
+        const parentRank = PRIORITY_RANK[parent.priority] ?? 2;
+        report.check(`${issue.key}.priority`, childRank >= parentRank, childRank >= parentRank
+            ? `${issue.priority} — no more urgent than parent ${JSON.stringify(issue.parent)} (${parent.priority})`
+            : `${issue.priority} is more urgent than parent ${JSON.stringify(issue.parent)}'s ${parent.priority} — a container's priority is a ceiling for everything under it`);
+    }
     return report;
 }
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */

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

@@ -10,12 +10,16 @@
  *
  * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope), read once at
  * construction — matching the reference implementation's pattern and this
- * project's existing env-var-for-credentials philosophy. No pagination
- * beyond one page of 100: fine for the label-scoped queries a lean v1
- * makes (a repo with >100 open `<prefix>:ready` issues at once is not this
- * version's problem to solve).
+ * project's existing env-var-for-credentials philosophy. `listByLabel`
+ * paginates up to `MAX_LIST_PAGES` (500 issues per label query) — no longer
+ * "not this version's problem to solve," now that priority ordering makes a
+ * truncated first page a correctness bug (an old, high-priority issue past
+ * page 1 would silently lose to a new low-priority one), not just a missed
+ * issue. A repo past even that cap gets a loud warning, never a silent
+ * truncation — see `listByLabel`'s own doc comment.
  */
 import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueAuthoringProvider, IssueComment, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
+import type { RefinedIssue } from "../data_types.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];
@@ -28,6 +32,8 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
     private gh;
     private label;
     private typeLabel;
+    /** 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. */
+    private priorityLabel;
     /** `null` on a real 404 (label doesn't exist yet) — any other non-2xx still throws, same as `gh()`. */
     private getLabel;
     /**
@@ -40,11 +46,32 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
     private ensureOneLabel;
     ensureLabels(): Promise<EnsureLabelsResult>;
     private toIssue;
+    /**
+     * `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.
+     */
     private listByLabel;
     listEligible(): Promise<Issue[]>;
     listInState(state: WatchState, opts?: {
         includeAll?: boolean;
     }): Promise<Issue[]>;
+    /** `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()`. */
+    getIssue(id: string): Promise<Issue | null>;
+    /** `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. */
+    listChildren(parent: Issue): Promise<Issue[]>;
     claim(issue: Issue, opts?: {
         from?: WatchState;
         to?: WatchState;
@@ -58,11 +85,18 @@ 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). */
+    /**
+     * `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.
+     */
     createIssue(input: {
         title: string;
         body: string;
         labels: string[];
+        kind: RefinedIssue["kind"];
     }): Promise<Issue>;
     /**
      * `POST /repos/{o}/{r}/issues/{parent_number}/sub_issues` — GitHub's

package/dist/core/issues/github_provider.js

@@ -10,8 +10,26 @@ const STATES = [
     "refined",
     "needs-feedback",
     "continue-refinement",
+    "spec-in-progress",
 ];
-const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*?\})\s*-->/s;
+/**
+ * GREEDY capture, not lazy: `WatchMarker.feedback` nests its own object
+ * (`{rounds, asked_at}`), so a lazy `\{.*?\}` stops at the FIRST `}` it
+ * finds — which is `feedback`'s own closing brace, not the marker's outer
+ * one — capturing an unbalanced, unparseable fragment the instant a spec
+ * escalates even once. `JSON.parse` then throws, is silently caught, and
+ * `readMarker` returns `null` forever after that point: the round counter
+ * can never advance past 1, a fresh marker comment gets posted every tick
+ * instead of the existing one being edited in place, and — worst of all —
+ * `buildSpecPrompt` never receives a valid `asked_at`, so a human's answer
+ * is never recognized as one, just dumped into undifferentiated "earlier
+ * discussion." A greedy match backtracks from the END of the string to find
+ * the LAST `}` — the marker's own outer brace — which is exactly right
+ * here since nothing meaningful follows it but the closing `-->`.
+ */
+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 +44,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 +53,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 +106,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 +157,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 +175,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 +212,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 +302,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",