@gr8ful/spf 0.6.0 → 0.8.0

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,8 +9,21 @@ const STATES = [
     "refined",
     "needs-feedback",
     "continue-refinement",
+    "spec-in-progress",
 ];
-const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*?\})/s;
+/**
+ * GREEDY capture, not lazy — same fix and same reasoning as
+ * `github_provider.ts`'s own `MARKER_RE`: `WatchMarker.feedback` nests its
+ * own object, so a lazy `\{.*?\}` stops at `feedback`'s own closing brace
+ * instead of the marker's outer one, producing unparseable JSON the moment
+ * a spec escalates even once — `readMarker` then returns `null` forever,
+ * `writeMarker` can never find the existing marker to edit in place (a new
+ * one gets posted every tick instead), and `buildSpecPrompt` never sees a
+ * valid `asked_at`, so a human's answer never gets flagged as one. Greedy
+ * backtracks from the end of the comment body to the true last `}` — safe
+ * here because nothing follows the JSON in this format at all.
+ */
+const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*\})/s;
 function toAdf(text) {
     return {
         type: "doc",
@@ -35,13 +48,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 +129,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`. */

package/dist/core/refine.d.ts

@@ -1,5 +1,5 @@
 import type { Issue, IssueAuthoringProvider } from "./issues/provider.ts";
-import type { RefinedIssue, SFConfig } from "./data_types.ts";
+import { type RefinedIssue, type RefinedPriority, type SFConfig } from "./data_types.ts";
 export interface PublishedIssue {
     /** The `RefinedIssue.key` this came from — a run-local id, never a tracker id. */
     key: string;
@@ -9,25 +9,62 @@ export interface PublishedIssue {
     isLeaf: boolean;
 }
 /**
- * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
- * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
- * yet. Throws rather than returning `null` so a `code` phase calling this
+ * `IssueAuthoringProvider` has a real implementation on `GitHubProvider` and
+ * `JiraProvider` — any other `issue_provider` value fails here, defensively
+ * (the config schema's picklist already rejects it earlier). Throws rather
+ * than returning `null` so a `code` phase calling this
  * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
  * the same "fail loudly, never silently do nothing" contract
  * `agents.validate()` uses for an unconfigured quality suite.
+ *
+ * Duplicates `cli/commands/watch.ts`'s own `resolveIssueProvider`
+ * construction logic for each provider — a pre-existing pattern for GitHub
+ * (this function has always rebuilt its own `GitHubProvider` rather than
+ * sharing one with the CLI layer's build-lane provider), mirrored for Jira
+ * rather than refactored away, to stay within this change's scope.
  */
 export declare function resolveAuthoringProvider(cfg: SFConfig): IssueAuthoringProvider;
+export interface RefineMarker {
+    /** The parent's real issue id, or `null` for a top-level node. */
+    parent: string | null;
+    /** Real issue ids — resolved from `blocked_by` `key`s at publish time, see `renderBody`. */
+    blocked_by: string[];
+    priority: RefinedPriority;
+}
+/**
+ * Pure and exported so it's directly unit-testable without a provider —
+ * `core/watch.ts`'s `claimNewWork` and `rollUp` are the real callers, reading
+ * it straight out of the `Issue.body` a `listEligible`/`getIssue` call
+ * already returned. Never throws: a body with no marker (any issue not
+ * created by this lane, or one whose marker a human stripped while editing)
+ * degrades to `NO_REFINE_MARKER`, same as malformed JSON inside one.
+ */
+export declare function parseRefineMarker(body: string): RefineMarker;
 export interface PublishOptions {
     labelPrefix: string;
     /** The originating spec issue's id, for every created issue's `## Parent` back-reference. `null`/omitted for a manual run with no source issue. */
     specIssueId?: string | null;
+    /**
+     * The spec's own priority (its `spf:priority:pN` label, read by
+     * `core/watch.ts`'s `runSpec`, or `spf refine`'s `--priority` flag for a
+     * bare manual run) — a CEILING, never a floor. Every node is clamped down
+     * to this if it outranks it (`clampPriority`), so a p3 "someday" spec
+     * cannot spawn p0 work that jumps the build lane's queue, regardless of
+     * what the refiner's own per-node judgment (or the gate's monotonicity
+     * check, which only sees the tree, never the spec) would otherwise allow.
+     * `null`/omitted — a bare run with nothing to inherit from — is a no-op:
+     * `clampPriority`'s own default.
+     */
+    priorityCeiling?: RefinedPriority | null;
 }
 /**
  * Create every node in `issues`, in dependency order, with its
- * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
- * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
- * via the tracker's native hierarchy, and render real `#n` references into
- * `## Blocked by`. Returns what it created, in creation order.
+ * `<prefix>:type:<kind>` and `<prefix>:priority:<pN>` labels (plus
+ * `<prefix>:refined` on leaves only — see `WatchState`'s doc comment in
+ * `provider.ts`), link each to its parent via the tracker's native
+ * hierarchy, and render real `#n` references into `## Blocked by` plus the
+ * hidden `spf-refine:` marker `parseRefineMarker` reads back. Returns what
+ * it created, in creation order.
  *
  * Not transactional: if a create or link call throws partway through, the
  * nodes already published stay published, orphaned from whatever hadn't run