@gr8ful/spf 0.6.0 → 0.7.0

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

package/dist/core/refine.js

@@ -14,18 +14,37 @@
  * `runSpec` closes that gap using what this module returns).
  */
 import { GitHubProvider } from "./issues/github_provider.js";
+import { JiraProvider } from "./issues/jira_provider.js";
+import { clampPriority } from "./data_types.js";
 /**
- * `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 function resolveAuthoringProvider(cfg) {
+    if (cfg.watch.issue_provider === "jira") {
+        if (!cfg.watch.jira.base_url.trim() || !cfg.watch.jira.project_key.trim()) {
+            throw new Error(`watch.jira.base_url and watch.jira.project_key must both be set when watch.issue_provider is "jira"`);
+        }
+        const email = process.env["JIRA_EMAIL"];
+        const token = process.env["JIRA_API_TOKEN"];
+        if (!email || !token) {
+            throw new Error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — the refine lane needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens)');
+        }
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types);
+    }
     if (cfg.watch.issue_provider !== "github") {
-        throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — ` +
-            `the refine lane needs "github" (see jira_provider.ts's module comment on why Jira isn't wired up yet)`);
+        throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — the refine lane needs "github" or "jira"`);
     }
     // Issue authoring always targets the ISSUE tracker's repo — `issue_repo`
     // if set, falling back to plain `repo` (the common case: issue_provider
@@ -47,31 +66,78 @@ export function resolveAuthoringProvider(cfg) {
 function typeLabel(labelPrefix, kind) {
     return `${labelPrefix}:type:${kind}`;
 }
+/** `spf:priority:p0..p3` — see `RefinedPrioritySchema`'s doc comment for what each rung means. Mirrors `typeLabel` above, and `github_provider.ts`'s own private `priorityLabel()` method (used by `ensureLabels()` to seed these) — the two aren't unified for the same reason `typeLabel` isn't: this file stays provider-agnostic, building label strings by convention rather than reaching into a concrete `GitHubProvider`. */
+function priorityLabel(labelPrefix, priority) {
+    return `${labelPrefix}:priority:${priority}`;
+}
+/**
+ * Sentinel distinct from `github_provider.ts`'s `MARKER_RE` on purpose: that
+ * one matches a hidden comment (`spf watch`'s own scratch state — worktree,
+ * branch, PR number); this one matches a hidden block INSIDE the issue BODY
+ * this file renders — the graph `spf watch`'s build lane needs to schedule
+ * correctly (`parent`, `blocked_by`, `priority`) but that gets lost once
+ * `blocked_by` is flattened to the human-readable `## Blocked by` prose
+ * below. The two live in different places on the issue and are read by
+ * different code (`readMarker`'s comment scan vs. a plain `Issue.body`
+ * parse), so a single tracker `GET` — which already returns the body — is
+ * all `claimNewWork`'s ordering needs, no per-issue marker-comment fetch.
+ */
+const REFINE_MARKER_RE = /<!--\s*spf-refine:\s*(\{.*?\})\s*-->/s;
+/** What `parseRefineMarker` returns absent (or on a malformed/hand-edited) marker — exactly today's pre-priority, pre-frontier behavior: no parent, no blockers, the default priority. */
+const NO_REFINE_MARKER = { parent: null, blocked_by: [], priority: "p2" };
+/**
+ * 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 function parseRefineMarker(body) {
+    const match = REFINE_MARKER_RE.exec(body);
+    if (!match)
+        return NO_REFINE_MARKER;
+    try {
+        const parsed = JSON.parse(match[1]);
+        return {
+            parent: typeof parsed.parent === "string" ? parsed.parent : null,
+            blocked_by: Array.isArray(parsed.blocked_by) ? parsed.blocked_by.filter((b) => typeof b === "string") : [],
+            priority: ["p0", "p1", "p2", "p3"].includes(parsed.priority) ? parsed.priority : "p2",
+        };
+    }
+    catch {
+        return NO_REFINE_MARKER; // malformed marker JSON — tolerate it, same policy as github_provider.ts's own findMarkerComment
+    }
+}
 /**
  * The body GitHub actually stores: the refiner's own `## What to build` /
  * `## Acceptance criteria` text, plus a `## Parent` back-reference to the
  * source spec (when there is one — a bare `spf refine` run with no
- * `--issue` has none), plus a `## Blocked by` section with real `#n`
- * references — `to-tickets`' own template shape, ported. Every `blocked_by`
- * key is guaranteed to already be in `byKey` by the time this runs:
- * `topoOrder` visits a node's dependencies before the node itself.
+ * `--issue` has none), a `## Blocked by` section with real `#n` references
+ * — `to-tickets`' own template shape, ported — and finally the hidden
+ * `spf-refine:` marker `parseRefineMarker` reads back. Every `blocked_by`
+ * key (and `node.parent`) is guaranteed to already be in `byKey` by the time
+ * this runs: `topoOrder` visits a node's dependencies before the node itself.
  */
 function renderBody(node, byKey, specIssueId) {
     const parts = [node.body.trim()];
     if (specIssueId)
         parts.push(`## Parent\n\nDecomposed from #${specIssueId}.`);
-    if (node.blocked_by.length > 0) {
-        const refs = node.blocked_by.map((key) => {
-            const published = byKey.get(key);
-            // Defensive only: gates.refinementWellFormed already rejects a
-            // blocked_by key that doesn't resolve to another node in the list.
-            return published ? `#${published.issue.id}` : key;
-        });
-        parts.push(`## Blocked by\n\n${refs.map((r) => `- ${r}`).join("\n")}`);
+    const blockedByIds = node.blocked_by.map((key) => {
+        const published = byKey.get(key);
+        // Defensive only: gates.refinementWellFormed already rejects a
+        // blocked_by key that doesn't resolve to another node in the list.
+        return published ? published.issue.id : key;
+    });
+    if (blockedByIds.length > 0) {
+        parts.push(`## Blocked by\n\n${blockedByIds.map((id) => `- #${id}`).join("\n")}`);
     }
     else {
         parts.push(`## Blocked by\n\nNone (can start immediately).`);
     }
+    const parentId = node.parent ? byKey.get(node.parent)?.issue.id ?? node.parent : null;
+    const marker = { parent: parentId, blocked_by: blockedByIds, priority: node.priority };
+    parts.push(`<!-- spf-refine: ${JSON.stringify(marker)} -->`);
     return parts.join("\n\n");
 }
 /**
@@ -112,10 +178,12 @@ function topoOrder(issues) {
 }
 /**
  * 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
@@ -129,13 +197,19 @@ export async function publish(tracker, issues, opts) {
     const childKeys = new Set(issues.filter((i) => i.parent).map((i) => i.parent));
     const byKey = new Map();
     const created = [];
-    for (const node of ordered) {
+    for (const rawNode of ordered) {
+        // Clamp once, up front — every downstream use (the label AND the hidden
+        // marker's own `priority`) must agree, or `claimNewWork`'s label-based
+        // ordering and a human reading the marker would disagree about what this
+        // issue's priority actually is.
+        const priority = clampPriority(rawNode.priority, opts.priorityCeiling);
+        const node = { ...rawNode, priority };
         const isLeaf = !childKeys.has(node.key);
-        const labels = [typeLabel(opts.labelPrefix, node.kind)];
+        const labels = [typeLabel(opts.labelPrefix, node.kind), priorityLabel(opts.labelPrefix, priority)];
         if (isLeaf)
             labels.push(`${opts.labelPrefix}:refined`);
         const body = renderBody(node, byKey, opts.specIssueId);
-        const issue = await tracker.createIssue({ title: node.title, body, labels });
+        const issue = await tracker.createIssue({ title: node.title, body, labels, kind: node.kind });
         const published = { key: node.key, issue, kind: node.kind, isLeaf };
         byKey.set(node.key, published);
         created.push(published);

package/dist/core/watch.d.ts

@@ -1,6 +1,7 @@
 import type { GitHandle } from "./git_helper.ts";
 import type { CodeHostProvider, Issue, IssueComment, IssueProvider, WatchMarker, WatchState } from "./issues/provider.ts";
 import type { NotifyEvent } from "./notify/channel.ts";
+import { type RefinedPriority } from "./data_types.ts";
 export interface ChainRunResult {
     accepted: boolean;
     adwId: string;
@@ -18,7 +19,7 @@ export interface ChainRunResult {
     /** Whether the chain that ran declares a "reviewer" in its `requiredAgents` — distinguishes "reviewer approved" from "nothing reviewed this change" when `reviewSummary` is absent. */
     reviewRequired?: boolean;
 }
-/** One issue the refine lane created — enough for `finishSpec`'s summary comment and the marker's idempotency record. */
+/** One issue the refine lane created — enough for `announceRefined`'s summary comment and the marker's idempotency record. */
 export interface RefinedIssueRef {
     id: string;
     title: string;
@@ -110,6 +111,18 @@ export interface WatchDeps {
         adwId: string;
         chainOptions: Record<string, string>;
     }) => Promise<ChainRunResult>;
+    /**
+     * `IssueAuthoringProvider.listChildren`'s read-back, injected as a bound
+     * function rather than a whole provider object — same reasoning as
+     * `runChain`/`runRefine`/`linkDataDir`: this module drives whatever it's
+     * given without importing a concrete provider type. `undefined` on any
+     * tracker that doesn't implement `IssueAuthoringProvider` (Jira today —
+     * see `jira_provider.ts`'s module comment); `rollUp` treats that as a
+     * logged no-op, not a failure — the build lane still functions without
+     * container roll-up, unlike the refine lane, which cannot function
+     * without authoring at all (see `cli/commands/watch.ts`'s startup check).
+     */
+    listChildren?: (parent: Issue) => Promise<Issue[]>;
     log: (message: string) => void;
     /**
      * Structured push, alongside `log`'s plain string — a required field, like
@@ -134,6 +147,20 @@ export interface WatchRunState {
      * that isn't why this is separate — the budgets are what require it.
      */
     refining: Set<string>;
+    /**
+     * Issue id -> its container's real issue id, recorded the moment
+     * `claimNewWork` claims a leaf whose hidden `spf-refine:` marker names a
+     * parent, deleted in the same `.finally()` that clears `inflight`. Zero
+     * API cost — no tracker read needed to populate it — and it's the whole
+     * basis of sibling affinity in `orderEligible`: a sibling of something
+     * already in flight sorts ahead of an equal-priority issue from an
+     * unrelated feature, so a feature already underway tends to finish before
+     * the daemon starts a new one instead of interleaving both. This holds
+     * only while a sibling is ACTUALLY in flight — a daemon restart begins
+     * with this empty, so ordering falls back to priority + created-asc until
+     * the in-memory picture rebuilds itself over the next few ticks.
+     */
+    inflightParents: Map<string, string>;
 }
 export declare function createWatchState(): WatchRunState;
 export declare function branchNameFor(issue: Issue): string;
@@ -146,6 +173,29 @@ export declare function refineBranchNameFor(issue: Issue): string;
  * merged) PR; otherwise retry up to `MAX_ORPHAN_ATTEMPTS`, then give up.
  */
 export declare function reconcileOrphans(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/**
+ * Poll every `spec-in-progress` spec: once every id `WatchMarker.refined`
+ * recorded — every issue the refiner produced, leaf or container — carries
+ * `<prefix>:done`, the spec's own decomposed work is actually finished, and
+ * only then does this move it `-> done`. This is the whole point of
+ * `announceRefined` landing on `spec-in-progress` rather than `done`
+ * straight away: the spec's status is what a product manager reads to know
+ * whether the work is finished, and "done" the instant a tree gets PUBLISHED
+ * would be a lie — the work hasn't started yet, let alone finished.
+ *
+ * A container in the refined list is done exactly when `rollUp` (see
+ * `finishReviews`) has already rolled it up — by the time every id here is
+ * `<prefix>:done`, every leaf beneath every container is too, transitively,
+ * with no need to walk the hierarchy again from this side.
+ *
+ * A referenced id that 404s (deleted from the tracker) is treated as
+ * satisfied — same policy as `frontierBlockedOn`'s blockers: a removed issue
+ * must not wedge the spec's completion forever. A spec with no marker, or an
+ * empty `refined` list, is left alone with a log line rather than assumed
+ * done — data that shouldn't exist given the gate's at-least-one-leaf rule,
+ * but never silently marked complete on that assumption.
+ */
+export declare function finishTrackedSpecs(deps: WatchDeps): Promise<void>;
 /**
  * Render the spec issue's comment thread for the refiner's prompt, replacing
  * the previous bare `title\n\nbody` — the whole reason a human's answer
@@ -161,9 +211,17 @@ export declare function reconcileOrphans(deps: WatchDeps, state: WatchRunState):
  * `MAX_THREAD_CHARS`, dropping the oldest comments first — an explicit
  * "N earlier comment(s) omitted" line, never a silent truncation.
  *
+ * `priority` — the spec's own `<prefix>:priority:pN` label, read by
+ * `runSpec` below — renders as its own `## Priority` section right after the
+ * header, present or absent independent of whether there's any comment
+ * thread at all: a spec with no priority label (the common case today) omits
+ * the section entirely, exactly the prompt this function produced before
+ * priority existed. `core/refine.ts`'s `publish()` is what actually ENFORCES
+ * the ceiling this section only asks for — see its own doc comment.
+ *
  * Exported and pure (no provider, no I/O) so it's directly unit-testable.
  */
-export declare function buildSpecPrompt(issue: Issue, comments: IssueComment[], feedback?: WatchMarker["feedback"]): string;
+export declare function buildSpecPrompt(issue: Issue, comments: IssueComment[], feedback?: WatchMarker["feedback"], priority?: RefinedPriority | null): string;
 /**
  * The refine lane's own `reconcileOrphans` — a `refining`-labeled spec this
  * process isn't tracking is one of three things: a completed publish that
@@ -179,7 +237,32 @@ export declare function buildSpecPrompt(issue: Issue, comments: IssueComment[],
 export declare function reconcileRefining(deps: WatchDeps, state: WatchRunState): Promise<void>;
 /** Poll every `review`-labeled issue's PR for merged (-> done) or closed-without-merging (-> blocked). */
 export declare function finishReviews(deps: WatchDeps): Promise<void>;
-/** Claim as many `ready` issues as the concurrency budget allows, and kick off `runIssue` for each in the background. */
+/**
+ * Sort `issues` the way `claimNewWork` walks them: priority first (p0 ahead
+ * of p2 regardless of creation order), then sibling affinity (a leaf whose
+ * hidden marker names a parent already in `inflightParents.values()` sorts
+ * ahead of an equal-priority leaf from an unrelated feature — the mechanism
+ * that tends to finish one feature before starting the next, without giving
+ * up the one-PR-per-story design), then creation order (oldest first,
+ * matching `listByLabel`'s own `sort=created&direction=asc` — the final,
+ * stable tiebreaker when priority and affinity both tie).
+ *
+ * Pure and exported so it's directly unit-testable without a provider, same
+ * spirit as `buildSpecPrompt` below. Two honest limits, both already true of
+ * what feeds it: affinity only reflects a sibling ACTUALLY in flight in this
+ * process right now — a daemon restart begins with `inflightParents` empty,
+ * so ordering degrades to priority + created-asc until it rebuilds itself
+ * over the next few ticks; and priority is read from the label, so an issue
+ * a human just relabeled sorts by its NEW priority starting next tick, never
+ * retroactively re-ordering claims a previous tick already made.
+ */
+export declare function orderEligible(issues: Issue[], inflightParents: Map<string, string>, labelPrefix: string): Issue[];
+/**
+ * Claim as many `ready` issues as the concurrency budget allows, in priority
+ * + sibling-affinity + created-asc order (`orderEligible`), skipping any
+ * whose `blocked_by` isn't fully `<prefix>:done` yet (`frontierBlockedOn`),
+ * and kick off `runIssue` for each claimed one in the background.
+ */
 export declare function claimNewWork(deps: WatchDeps, state: WatchRunState): Promise<void>;
 /**
  * Claim as many specs in `from` as `refineConcurrency` allows, and kick off