@gr8ful/spf 0.6.0 → 0.7.0

package/dist/cli/commands/watch.js

@@ -16,6 +16,7 @@ import { isRepoAt, makeGit } from "../../core/git_helper.js";
 import { GitHubProvider } from "../../core/issues/github_provider.js";
 import { JiraProvider } from "../../core/issues/jira_provider.js";
 import { BitbucketProvider } from "../../core/issues/bitbucket_provider.js";
+import { isAuthoringProvider } from "../../core/issues/provider.js";
 import { createWatchState, tick } from "../../core/watch.js";
 import { findChain, resolveRequiredAgents, runChain as runChainDef } from "../../chains/index.js";
 import { ReviewOutput } from "../../core/data_types.js";
@@ -107,7 +108,7 @@ function resolveIssueProvider(cfg) {
             console.error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens). See README.md\'s "spf watch" section.');
             return null;
         }
-        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token);
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types);
     }
     console.error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} is not supported`);
     return null;
@@ -177,6 +178,14 @@ function releaseLock(lockPath) {
  * machine needs, with sensible colors/descriptions. Doesn't touch git or
  * run anything, so it skips watchCommand's repo/chain checks entirely —
  * you can seed labels before ever wiring up a worktree-capable checkout.
+ *
+ * On Jira, with `watch.refine.enabled`, this also runs a READ-ONLY check of
+ * `watch.jira.issue_types` against the real project — the same check
+ * `watchCommand`'s own startup gate runs, exposed here too so a bad mapping
+ * can be caught (and fixed) before ever starting the daemon, not just at
+ * startup time. Labels themselves stay a pure report on Jira either way
+ * (Jira labels are freeform strings with no color/description registry to
+ * seed — see `jira_provider.ts`'s module comment).
  */
 export async function watchInitCommand(argv) {
     const { options } = parseCli(argv, ["cwd", "config"], []);
@@ -193,6 +202,15 @@ export async function watchInitCommand(argv) {
         console.log(`  ~ ${name} (updated color/description)`);
     for (const name of result.unchanged)
         console.log(`  = ${name} (already correct)`);
+    if (cfg.watch.refine.enabled && cfg.watch.issue_provider === "jira" && provider instanceof JiraProvider) {
+        const checks = await provider.validateIssueTypes();
+        console.log(`\nvalidating watch.jira.issue_types against ${cfg.watch.jira.project_key}:`);
+        for (const c of checks) {
+            console.log(`  ${c.exists ? "✓" : "✗"} ${c.kind} → ${c.jiraType}${c.exists ? "" : ` — no issue type named "${c.jiraType}" in ${cfg.watch.jira.project_key}`}`);
+        }
+        if (checks.some((c) => !c.exists))
+            return 1;
+    }
     return 0;
 }
 export async function watchCommand(argv) {
@@ -215,19 +233,37 @@ export async function watchCommand(argv) {
         return 1;
     }
     if (cfg.watch.refine.enabled) {
-        if (cfg.watch.issue_provider !== "github") {
-            // Fail loudly at startup, not silently every tick: JiraProvider
-            // doesn't implement IssueAuthoringProvider yet (see its module
-            // comment) — a refine lane that can never publish would otherwise
-            // just claim every spec-ready spec and block it, forever.
+        if (cfg.watch.issue_provider !== "github" && cfg.watch.issue_provider !== "jira") {
+            // Fail loudly at startup, not silently every tick: neither provider
+            // implements IssueAuthoringProvider besides these two — a refine lane
+            // that can never publish would otherwise just claim every spec-ready
+            // spec and block it, forever.
             console.error(`watch.refine.enabled is true but watch.issue_provider is ${JSON.stringify(cfg.watch.issue_provider)} — ` +
-                `the refine lane needs "github" (issue authoring isn't implemented for Jira yet)`);
+                `the refine lane needs "github" or "jira"`);
             return 1;
         }
         if (!findChain(cfg.watch.refine.chain)) {
             console.error(`watch.refine.chain ${JSON.stringify(cfg.watch.refine.chain)} is not a registered chain — run \`spf list\` to see every chain`);
             return 1;
         }
+        // Jira's issue-type mapping is user-configured (watch.jira.issue_types)
+        // and project-specific — validated here, at startup, for the same
+        // reason findChain() is: a bad mapping should stop the daemon before
+        // it starts, not fail silently every tick once the first spec-ready
+        // spec tries to publish. Silent on success, matching this function's
+        // other startup checks; loud (and the full per-kind report) on failure.
+        if (cfg.watch.issue_provider === "jira" && provider instanceof JiraProvider) {
+            const checks = await provider.validateIssueTypes();
+            const mismatches = checks.filter((c) => !c.exists);
+            if (mismatches.length > 0) {
+                console.error(`watch.jira.issue_types has ${mismatches.length} mismatch(es) against ${cfg.watch.jira.project_key}:`);
+                for (const c of checks) {
+                    console.error(`  ${c.exists ? "✓" : "✗"} ${c.kind} → ${c.jiraType}${c.exists ? "" : ` — no issue type named "${c.jiraType}" in ${cfg.watch.jira.project_key}`}`);
+                }
+                console.error(`Fix watch.jira.issue_types, or the project's issue types, before running spf watch unattended. Run \`spf watch init\` any time to re-check.`);
+                return 1;
+            }
+        }
     }
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
     const lockPath = path.join(dataPaths.data_dir, "watch.lock");
@@ -422,6 +458,17 @@ export async function watchCommand(argv) {
         }
         return { accepted: true, adwId: opts.adwId, detail: "", created, questions };
     };
+    // `IssueAuthoringProvider`'s read-back half — `isAuthoringProvider()` is a
+    // structural check (see `provider.ts`), so both GitHub and Jira are
+    // recognized here without an `instanceof` chain that would need editing
+    // for every future authoring-capable provider. `null` on any tracker that
+    // ISN'T authoring-capable makes `rollUp` a logged no-op there rather than
+    // a startup failure the way `watch.refine.enabled` without authoring
+    // support is above: the build lane functions fine without container
+    // roll-up, unlike refine, which cannot function without authoring at all.
+    // Not a second `resolveAuthoringProvider()` call: that helper's own config
+    // validation already ran to produce `provider` itself.
+    const authoringProvider = isAuthoringProvider(provider) ? provider : null;
     const deps = {
         provider,
         codeHost,
@@ -440,6 +487,7 @@ export async function watchCommand(argv) {
         linkDataDir,
         dryRun: Boolean(flags["dry-run"]),
         runChain,
+        listChildren: authoringProvider ? (parent) => authoringProvider.listChildren(parent) : undefined,
         log: (message) => console.log(message),
         notify: (event) => notifier?.send(event),
     };

package/dist/cli/index.js

@@ -49,7 +49,7 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf abort <adw_id>                        signal a run's process to stop
   spf version                               print the installed version
 
-Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>]
+Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>] [--priority p0|p1|p2|p3]
 Run budget: set defaults.max_run_cost (USD) and/or defaults.max_run_tokens in spf.config.yaml to stop the NEXT agent call once a run has already spent this much — checked before each call, never after, so a single call is never capped and a one-agent-dispatch chain (scout/prompt/build) can never trip it; absent (the default) = unbounded.
 Run \`spf list\` to see every chain and what it needs.`;
 /** A raw scan for `--cwd`, ahead of any command-specific argv parsing — every command that takes it means the same thing by it. */

package/dist/cli/interview.js

@@ -286,16 +286,20 @@ export async function runInterview(asker, ctx) {
         watch = { issue_provider: issueProvider, code_host: codeHost, repo, label_prefix: labelPrefix, chain, base_branch: baseBranch };
         if (issueRepo)
             watch.issue_repo = issueRepo;
-        // Issue authoring (create + link a hierarchy) is only implemented on
-        // GitHubProvider today — see jira_provider.ts's module comment — so
-        // this lane isn't offered at all on a Jira tracker rather than asking a
-        // question that would just fail at `spf watch` startup.
-        if (issueProvider === "github") {
+        // Issue authoring (create + link a hierarchy) is implemented on both
+        // GitHubProvider and JiraProvider — see jira_provider.ts's module
+        // comment for how Jira's version works (native issue types + the
+        // `parent` field).
+        if (issueProvider === "github" || issueProvider === "jira") {
             const enableRefine = await asker.confirm(`Also enable the refine lane (decompose a "${labelPrefix}:spec-ready" product spec into a feature/story-or-bug tree)?`, false);
             if (enableRefine) {
                 const refineChainChoices = allChains().map((c) => ({ value: c.name, label: c.name, hint: c.source ? `${c.describe} (repo)` : c.describe }));
                 const refineChain = await asker.select("Chain to run per spec", refineChainChoices, "refine");
                 watch.refine = { enabled: true, chain: refineChain };
+                if (issueProvider === "jira") {
+                    asker.note('Jira issue types default to epic/feature -> "Epic", story -> "Story", bug -> "Bug", task -> "Task" — ' +
+                        "customize per-kind in watch.jira.issue_types if your project renames any of them, then run `spf watch init` to validate.");
+                }
             }
         }
         if (issueProvider === "jira") {

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