@gr8ful/spf 0.12.0 → 0.13.0

package/dist/core/gates.js

@@ -17,9 +17,10 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, statSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { GateReport, PRIORITY_RANK } from "./data_types.js";
+import { DEFAULT_REFINE_MAX_DEPTH, DEFAULT_REFINE_MAX_LEAVES, DEFAULT_REFINE_MAX_NODES, GateReport, PRIORITY_RANK, } from "./data_types.js";
 import { operatorEnv } from "./utils.js";
 const TAIL_CHARS = 1000; // command output kept as evidence on a failure
+const MIN_OUTCOME_CHARS = 20; // shortest string that can still be the sentence RefinedIssue.user_outcome asks for
 /**
  * Anchor an envelope-declared path to `run.repo_root`. Absolute paths pass
  * through unchanged (an agent that reports an absolute path meant exactly
@@ -130,6 +131,34 @@ export function verdictConsistent(envelope, _run) {
 }
 const CONTAINER_KINDS = new Set(["epic", "feature"]);
 const LEAF_KINDS = new Set(["story", "bug", "task"]);
+export function refineBudget(run) {
+    const refine = run.cfg?.watch.refine;
+    return {
+        maxLeaves: refine?.max_leaves ?? DEFAULT_REFINE_MAX_LEAVES,
+        maxNodes: refine?.max_nodes ?? DEFAULT_REFINE_MAX_NODES,
+        maxDepth: refine?.max_depth ?? DEFAULT_REFINE_MAX_DEPTH,
+    };
+}
+/**
+ * How many containment levels deep `key` sits: a top-level node is 1, a node
+ * under a top-level container is 2. Bounded by a `seen` set — the cycle
+ * check earlier in this gate already reports a `parent` cycle as its own
+ * violation, so this just has to not hang on one, not detect it again.
+ */
+function containmentDepth(key, byKey) {
+    let depth = 1;
+    const seen = new Set([key]);
+    let current = byKey.get(key);
+    while (current?.parent) {
+        const parent = byKey.get(current.parent);
+        if (!parent || seen.has(parent.key))
+            break;
+        seen.add(parent.key);
+        depth += 1;
+        current = parent;
+    }
+    return depth;
+}
 /**
  * The gate that turns `to-tickets`' flat, untyped ticket list into an
  * actually-enforced feature/story-or-bug tree — see `RefinedIssueSchema`'s
@@ -142,34 +171,52 @@ const LEAF_KINDS = new Set(["story", "bug", "task"]);
  * "Container" and "leaf" are derived from the graph, not asserted by the
  * agent: a node is a container iff some other node names it as `parent`.
  *
- * `questions` (see `RefineQuestionSchema`'s doc comment) is the human-in-the-
- * loop escalation path, and it is mutually exclusive with `issues`: a
- * refinement that raises material ambiguity must publish NOTHING this round
- * — a partial tree pinned to an unanswered question is worse than none.
- * When `questions` is non-empty this gate checks only its own shape (unique,
- * non-blank ids; non-blank question text) and skips every `issues` rule
- * below, since there is no tree to validate.
+ * `issues` / `questions` / `split` (see `RefineQuestionSchema`'s and
+ * `SpecSplitSchema`'s doc comments) are three mutually exclusive ways this
+ * round can end: an unambiguous tree, material ambiguity to escalate, or a
+ * spec too large for one decomposition. A refinement that raises questions
+ * or proposes a split must publish NOTHING this round — a partial tree
+ * pinned to either is worse than none. When `questions` or `split` is
+ * non-empty this gate checks only that shape (never both at once, and never
+ * alongside `issues`) and skips every `issues` rule below, since there is no
+ * tree to validate.
  */
-export function refinementWellFormed(envelope, _run) {
+export function refinementWellFormed(envelope, run) {
     const report = new GateReport();
     const issues = envelope.issues ?? [];
     const questions = envelope.questions ?? [];
-    if (questions.length > 0) {
+    const split = envelope.split ?? [];
+    if (questions.length > 0 || split.length > 0) {
         report.check("issues empty while escalating", issues.length === 0, issues.length === 0
-            ? "no issues published alongside the questions"
-            : `${issues.length} issue(s) published alongside ${questions.length} question(s) — escalating means publishing nothing this round`);
-        const seenIds = new Set();
-        for (const q of questions) {
-            const blank = !q.id.trim();
-            const dup = !blank && seenIds.has(q.id);
-            seenIds.add(q.id);
-            report.check(`question ${JSON.stringify(q.id)}`, !blank && !dup, blank ? "question id is blank" : dup ? "duplicate question id — every question needs a unique id within this round" : "id ok");
-            report.check(`question ${JSON.stringify(q.id)}.question`, q.question.trim().length > 0, q.question.trim().length > 0 ? "has text" : "question text is blank");
+            ? "no issues published alongside the escalation"
+            : `${issues.length} issue(s) published alongside ${questions.length} question(s)/${split.length} split proposal(s) — escalating means publishing nothing this round`);
+        report.check("questions xor split", !(questions.length > 0 && split.length > 0), questions.length > 0 && split.length > 0
+            ? "both questions and split are non-empty — ambiguity (questions) and size (split) are different problems, escalate one at a time"
+            : "exactly one escalation shape used");
+        if (split.length > 0) {
+            report.check("split has at least 2 entries", split.length >= 2, split.length >= 2
+                ? `${split.length} proposed specs`
+                : "a split into 1 entry is not a split — it's the same spec renamed. Either propose 2+ standalone specs, or this spec fits after all: emit issues instead");
+            split.forEach((s, i) => {
+                report.check(`split[${i}].title`, s.title.trim().length > 0, s.title.trim().length > 0 ? "has text" : "blank title");
+                report.check(`split[${i}].body`, s.body.trim().length > 0, s.body.trim().length > 0 ? "has text" : "blank body — each proposed spec needs its own complete problem/outcome/scope");
+                report.check(`split[${i}].rationale`, s.rationale.trim().length > 0, s.rationale.trim().length > 0 ? "has text" : "blank rationale — say why this is a coherent standalone spec and roughly how many leaves you expect it to decompose into");
+            });
+        }
+        else {
+            const seenIds = new Set();
+            for (const q of questions) {
+                const blank = !q.id.trim();
+                const dup = !blank && seenIds.has(q.id);
+                seenIds.add(q.id);
+                report.check(`question ${JSON.stringify(q.id)}`, !blank && !dup, blank ? "question id is blank" : dup ? "duplicate question id — every question needs a unique id within this round" : "id ok");
+                report.check(`question ${JSON.stringify(q.id)}.question`, q.question.trim().length > 0, q.question.trim().length > 0 ? "has text" : "question text is blank");
+            }
         }
         return report;
     }
     if (issues.length === 0) {
-        report.check("issues", false, "a refinement produced no issues at all and raised no questions — decompose the spec into at least one leaf, or escalate what's ambiguous");
+        report.check("issues", false, "a refinement produced no issues at all and raised no questions or split — decompose the spec into at least one leaf, escalate what's ambiguous, or propose a split if it's too large");
         return report;
     }
     const byKey = new Map();
@@ -182,6 +229,7 @@ export function refinementWellFormed(envelope, _run) {
         }
     }
     const childKeys = new Set(); // keys named as some OTHER node's parent -> that node is a container
+    const childCount = new Map(); // and HOW MANY name it — a container of exactly 1 is a violation below
     for (const issue of issues) {
         if (!issue.parent)
             continue;
@@ -190,6 +238,7 @@ export function refinementWellFormed(envelope, _run) {
             continue;
         }
         childKeys.add(issue.parent);
+        childCount.set(issue.parent, (childCount.get(issue.parent) ?? 0) + 1);
     }
     for (const issue of issues) {
         for (const blocker of issue.blocked_by) {
@@ -252,6 +301,112 @@ 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");
+    // ── the decomposition budget ────────────────────────────────────────────
+    //
+    // The first CARDINALITY rules this gate has ever had, and the reason they
+    // are gate rules rather than one more paragraph of prompt: a prompt-only
+    // version was tried (c9a4471, "tests are not their own leaf") and the model
+    // kept the ticket and renamed it around the banned noun. A count is not a
+    // noun — there is nothing to rename.
+    //
+    // BOTH MESSAGES NAME THE ESCALATION BRANCH EXPLICITLY, and that is
+    // load-bearing rather than decorative. `core/agents.ts`'s correction prompt
+    // is generic ("Your previous response failed validation: ... Fix these
+    // problems, then re-emit ONLY your Report JSON"), so a violation's own
+    // `note` is the ONLY channel through which the refiner learns that
+    // proposing a `split` is a legal way out. Without that sentence, the
+    // correction round `steps.refine()`'s `retries` buys gets spent producing a
+    // smaller WRONG tree instead of a split proposal.
+    //
+    // The leaf message also forecloses the other cheap escape: satisfying a
+    // leaf cap by MERGING unrelated slices into a few oversized ones. That
+    // passes every check here and violates the one rule no gate can measure
+    // ("sized to fit what a reviewer can hold in their head" —
+    // assets/prompts/refiner/system.md). Saying so is the only lever available.
+    const budget = refineBudget(run);
+    report.check("leaf budget", leafCount <= budget.maxLeaves, leafCount <= budget.maxLeaves
+        ? `${leafCount} leaf/leaves, within the budget of ${budget.maxLeaves}`
+        : `${leafCount} leaves exceeds the budget of ${budget.maxLeaves}. Every leaf becomes its own branch, its own build run and its own pull request a person reads, so this spec as decomposed costs ${leafCount} human reviews. Take exactly one of two paths: (1) re-emit a tree of at most ${budget.maxLeaves} leaves, dropping slices that are process rather than product and combining slices that are genuinely one vertical slice — do NOT merge unrelated slices to hit the number, an oversized leaf is a worse outcome than a large tree; or (2) if this spec honestly cannot be built in ${budget.maxLeaves} slices, publish NOTHING: emit an empty "issues" and a "split" entry proposing 2 or more standalone specs to cut it into, each with your expected leaf count.`);
+    report.check("node budget", issues.length <= budget.maxNodes, issues.length <= budget.maxNodes
+        ? `${issues.length} node(s), within the budget of ${budget.maxNodes}`
+        : `${issues.length} nodes exceeds the budget of ${budget.maxNodes} — drop containers that only group, or publish nothing and propose a "split" into separate specs instead`);
+    // ── no singleton container ──────────────────────────────────────────────
+    //
+    // A container with exactly one child buys nothing and costs twice: a
+    // second tracker issue to create, link, label and roll up, and a second
+    // place the same acceptance criteria are written down. A container's only
+    // job is to GROUP (see `assets/prompts/refiner/system.md`'s "The tree"),
+    // and one child is nothing to group. It is also the cheapest way an
+    // over-decomposed tree pads its node count, which is why this sits beside
+    // the budget rather than with the kind checks above.
+    for (const issue of issues) {
+        const children = childCount.get(issue.key) ?? 0;
+        if (children === 0)
+            continue; // a leaf — not this check's business
+        report.check(`${issue.key}.children`, children >= 2, children >= 2
+            ? `${children} children`
+            : `container has exactly 1 child — a container exists only to group, and one child is nothing to group. Delete ${JSON.stringify(issue.key)} and re-parent its child to ${issue.parent ? JSON.stringify(issue.parent) : `top level (parent "")`}, folding anything ${JSON.stringify(issue.key)} said into the child's own body`);
+    }
+    // ── depth cap ───────────────────────────────────────────────────────────
+    //
+    // Two levels by default: one top-level container, and the leaves directly
+    // under it. Deeper nesting is exactly how "6 features and 14 stories" gets
+    // built — an epic over features over stories READS as organization and
+    // COSTS three tiers of tracker issue for one spec.
+    //
+    // It is also a live bug fix for the Jira provider, not only a scoping rule.
+    // `jira.issue_types` maps both `epic` and `feature` to Jira's Epic type by
+    // default, and Jira has no Epic-under-Epic nesting (see
+    // `core/issues/jira_provider.ts`'s accepted-limitation note) — so a
+    // `feature` parented under an `epic`/`feature` reaches `linkChild` and
+    // returns a raw Atlassian API error PARTWAY THROUGH a publish that is
+    // deliberately not transactional, leaving whatever was already created
+    // stranded on the board. At the default `max_depth: 2`, that tree is now
+    // refused before a single issue is created. See `WatchRefineConfigSchema`
+    // for why raising this above 2 is unsafe on Jira specifically.
+    for (const issue of issues) {
+        const depth = containmentDepth(issue.key, byKey);
+        report.check(`${issue.key}.depth`, depth <= budget.maxDepth, depth <= budget.maxDepth
+            ? `level ${depth} of ${budget.maxDepth}`
+            : `nested ${depth} levels deep, past the limit of ${budget.maxDepth} — the shape is one top-level container with its leaves directly under it, not an epic over features over stories. Re-parent ${JSON.stringify(issue.key)} onto a top-level container, or delete the intermediate container entirely`);
+    }
+    // ── every leaf states a user-observable outcome ─────────────────────────
+    //
+    // A required SLOT, not a banned-word list. A leaf must say in one sentence
+    // what someone can do once it lands that they could not before — see
+    // `RefinedIssueSchema.user_outcome`. "Cross-browser testing" has no such
+    // sentence that isn't obviously a restatement of a slice that already
+    // exists, and a model made to write one tends to notice that itself. A word
+    // list only renames the ticket (c9a4471); an empty slot has nowhere to
+    // hide.
+    //
+    // This is a BACKSTOP TO THE BUDGET, not a substitute for it: a determined
+    // model CAN write a plausible outcome for a process leaf ("an on-call
+    // engineer can revert in under 5 minutes"). What actually kills a process
+    // leaf is that it must beat a real product slice for one of `maxLeaves`
+    // slots. If process leaves reappear despite this check, lower the budget —
+    // do not add words to a list.
+    //
+    // Checked on LEAVES only (a container's outcome is the union of its
+    // children's) and for SHAPE only — non-blank, long enough to be a sentence,
+    // not the title again. Whether the sentence is TRUE is a reviewer's
+    // judgment, not a mechanical fact, and a gate that tried to grade it would
+    // be the word list under another name.
+    for (const issue of issues) {
+        if (childKeys.has(issue.key))
+            continue;
+        const outcome = issue.user_outcome.trim();
+        const blank = outcome.length === 0;
+        const tooShort = !blank && outcome.length < MIN_OUTCOME_CHARS;
+        const echoesTitle = !blank && outcome.toLowerCase() === issue.title.trim().toLowerCase();
+        report.check(`${issue.key}.user_outcome`, !blank && !tooShort && !echoesTitle, blank
+            ? `blank — every leaf must state, in ONE sentence, what someone can do once it lands that they could not before (e.g. "A workspace owner can invite a teammate by email and see the invite listed as pending."). A slice with no such sentence is process, not product: fold it into the slice whose behavior it actually serves, or drop it`
+            : tooShort
+                ? `${JSON.stringify(outcome)} is too short to be that sentence — name who, and what they can now do`
+                : echoesTitle
+                    ? `repeats the title verbatim — the title NAMES the slice; this sentence says what changes for a person once it lands`
+                    : "states a user-observable outcome");
+    }
     // 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

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

@@ -18,10 +18,15 @@
  * 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"];
+import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
+/**
+ * The refine lane's leaf/container taxonomy — see `data_types.ts`'s
+ * `RefinedIssueSchema.kind` — plus `"spec"`, a proposed spec's own kind (see
+ * `IssueAuthoringKind` in `provider.ts`). 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", "spec"];
 export type IssueKind = (typeof ISSUE_KINDS)[number];
 export declare class GitHubProvider implements IssueProvider, CodeHostProvider, IssueAuthoringProvider {
     private readonly repo;
@@ -96,7 +101,7 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
         title: string;
         body: string;
         labels: string[];
-        kind: RefinedIssue["kind"];
+        kind: IssueAuthoringKind;
     }): Promise<Issue>;
     /**
      * `POST /repos/{o}/{r}/issues/{parent_number}/sub_issues` — GitHub's

package/dist/core/issues/github_provider.js

@@ -11,6 +11,8 @@ const STATES = [
     "needs-feedback",
     "continue-refinement",
     "spec-in-progress",
+    "split-proposed",
+    "split-approved",
 ];
 /**
  * GREEDY capture, not lazy: `WatchMarker.feedback` nests its own object
@@ -30,8 +32,14 @@ const STATES = [
 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"];
+/**
+ * The refine lane's leaf/container taxonomy — see `data_types.ts`'s
+ * `RefinedIssueSchema.kind` — plus `"spec"`, a proposed spec's own kind (see
+ * `IssueAuthoringKind` in `provider.ts`). 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", "spec"];
 // GitHub label colors are 6 hex digits, no leading '#'.
 const LABEL_META = {
     ready: { color: "0e8a16", description: "spf watch will claim this issue on its next poll" },
@@ -45,6 +53,8 @@ const LABEL_META = {
     "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" },
+    "split-proposed": { color: "d93f0b", description: "spf's refiner proposed splitting this spec into several — review the proposal comment" },
+    "split-approved": { color: "0e8a16", description: "add this once you approve the proposed split — spf will create the new specs" },
 };
 const TYPE_LABEL_META = {
     epic: { color: "5319e7", description: "a container generated by spf watch's refine lane — not directly workable" },
@@ -52,6 +62,7 @@ const TYPE_LABEL_META = {
     story: { color: "bfd4f2", description: "a leaf generated by spf watch's refine lane — vertical-slice, independently workable" },
     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" },
+    spec: { color: "fef2c0", description: "a standalone spec proposed by splitting a larger one — not yet decomposed" },
 };
 /**
  * What `claimNewWork` (`watch.ts`) schedules by — see `RefinedPrioritySchema`

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

@@ -58,8 +58,8 @@
  * Jira API error at publish time — a genuine platform difference, not
  * something this file tries to paper over.
  */
-import type { RefinedIssue, JiraIssueTypeMap } from "../data_types.ts";
-import type { EnsureLabelsResult, Issue, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
+import type { JiraIssueTypeMap } from "../data_types.ts";
+import type { EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
 export declare class JiraProvider implements IssueProvider, IssueAuthoringProvider {
     private readonly baseUrl;
     private readonly projectKey;
@@ -108,7 +108,7 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
         title: string;
         body: string;
         labels: string[];
-        kind: RefinedIssue["kind"];
+        kind: IssueAuthoringKind;
     }): Promise<Issue>;
     /**
      * The modern mechanism only — Jira's `parent` field, not the legacy

package/dist/core/issues/jira_provider.js

@@ -11,6 +11,8 @@ const STATES = [
     "needs-feedback",
     "continue-refinement",
     "spec-in-progress",
+    "split-proposed",
+    "split-approved",
 ];
 /**
  * GREEDY capture, not lazy — same fix and same reasoning as

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

@@ -27,7 +27,21 @@
  * 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";
+import type { RefinedIssue, SpecSplit } from "../data_types.ts";
+/**
+ * Every `kind` `IssueAuthoringProvider.createIssue` can be asked to create:
+ * `RefinedIssue["kind"]` (a node in a decomposed spec's tree — never
+ * includes `"spec"`, since a spec is never a node `gates.refinementWellFormed`
+ * validates) plus `"spec"` itself — a spec proposed by `core/refine.ts`'s
+ * `publishSpecs()` when a spec splits into several (see `WatchMarker.split`
+ * below). Kept as its own union here rather than folded into
+ * `RefinedIssueSchema.kind` in `data_types.ts`, because widening THAT
+ * picklist would also widen what `gates.refinementWellFormed`'s
+ * container/leaf derivation has to reason about for a shape ("spec") that
+ * can never legally appear in a `RefineOutput.issues` tree in the first
+ * place.
+ */
+export type IssueAuthoringKind = RefinedIssue["kind"] | "spec";
 /**
  * `spec-ready`/`refining` drive the SECOND lane's state machine (a product
  * spec being decomposed — see `reconcileRefining`/`claimSpecs` in
@@ -58,13 +72,29 @@ import type { RefinedIssue } from "../data_types.ts";
  * `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
+ * `split-proposed`/`split-approved` are a second escape hatch alongside
+ * `needs-feedback`, for a different problem: not ambiguity, but a spec that
+ * is honestly too big to decompose within the leaf budget (see
+ * `gates.refinementWellFormed`'s budget checks). Instead of asking a
+ * `questions`-shaped question, the refiner proposes splitting the spec into
+ * several standalone specs (`RefineOutput.split` — see `SpecSplitSchema` in
+ * `data_types.ts`); `watch.ts`'s `proposeSpecSplit` records the proposal in
+ * `WatchMarker.split` and moves the spec to `split-proposed`. A human reviews
+ * the proposal comment and either adds `split-approved` (executed
+ * deterministically, no agent re-run — `watch.ts`'s `executeApprovedSplits`)
+ * or answers inline and adds `continue-refinement` to have the refiner
+ * revise its proposal. Deliberately a DIFFERENT label from
+ * `continue-refinement`'s own approval path: approving a split is an
+ * instruction to CODE ("go create these"), not new information a refiner
+ * session needs to reason about, so it skips the agent entirely.
+ *
+ * All thirteen 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" | "spec-in-progress";
+export type WatchState = "ready" | "working" | "review" | "done" | "blocked" | "spec-ready" | "refining" | "refined" | "needs-feedback" | "continue-refinement" | "spec-in-progress" | "split-proposed" | "split-approved";
 export interface Issue {
     /** Opaque tracker identifier: a GitHub issue number stringified ("42"), a Jira key ("PROJ-123"). */
     id: string;
@@ -122,6 +152,15 @@ export interface PrStatus {
  * `buildSpecPrompt` uses it to split the issue's comment thread into
  * "answers to the open questions" versus "earlier discussion" when building
  * the resumed run's prompt.
+ *
+ * `split` is the recorded proposal behind `split-proposed` /
+ * `split-approved` (see `WatchState`'s doc comment above): the exact specs
+ * `watch.ts`'s `proposeSpecSplit` posted as a comment, so a human's approval
+ * executes precisely what they read rather than whatever the marker happens
+ * to hold by the time `executeApprovedSplits` runs. `rounds` mirrors
+ * `feedback.rounds` — how many times this spec has been through the
+ * propose/revise loop, for the same "answered after N rounds" summary-comment
+ * purpose.
  */
 export interface WatchMarker {
     worktree?: string;
@@ -133,6 +172,11 @@ export interface WatchMarker {
         rounds: number;
         asked_at: string;
     };
+    split?: {
+        specs: SpecSplit[];
+        proposed_at: string;
+        rounds: number;
+    };
 }
 /** What `ensureLabels()` actually did, per label — for `spf watch init`'s report. */
 export interface EnsureLabelsResult {
@@ -248,7 +292,7 @@ export interface IssueAuthoringProvider {
         title: string;
         body: string;
         labels: string[];
-        kind: RefinedIssue["kind"];
+        kind: IssueAuthoringKind;
     }): Promise<Issue>;
     /** 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>;

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" | "feature_done" | "spec_done";
+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" | "spec_split_proposed" | "feature_done" | "spec_done";
 export interface NotifyEvent {
     kind: NotifyKind;
     /**

package/dist/core/refine.d.ts

@@ -1,5 +1,5 @@
 import type { Issue, IssueAuthoringProvider } from "./issues/provider.ts";
-import { type RefinedIssue, type RefinedPriority, type SFConfig } from "./data_types.ts";
+import { type RefinedIssue, type RefinedPriority, type SFConfig, type SpecSplit } from "./data_types.ts";
 export interface PublishedIssue {
     /** The `RefinedIssue.key` this came from — a run-local id, never a tracker id. */
     key: string;
@@ -74,3 +74,37 @@ export interface PublishOptions {
  * can sort out same as any other `spf watch` failure.
  */
 export declare function publish(tracker: IssueAuthoringProvider, issues: RefinedIssue[], opts: PublishOptions): Promise<PublishedIssue[]>;
+export interface PublishSpecsOptions {
+    labelPrefix: string;
+    /** The original, over-large spec's id — every created spec's `## Parent` back-reference names it. */
+    originalSpecId: string;
+    /** The original spec's own priority label, if any — inherited by every proposed spec, same ceiling semantics as `PublishOptions.priorityCeiling`. */
+    priority?: RefinedPriority | null;
+}
+/**
+ * `publish()`'s twin for the OTHER escalation path: a spec too large for one
+ * decomposition, split into several standalone specs a human has already
+ * approved (see `WatchState`'s doc comment on `split-proposed`/
+ * `split-approved` in `core/issues/provider.ts`). Called by
+ * `core/watch.ts`'s `executeApprovedSplits` — never by an agent phase, since
+ * approving a recorded proposal is a deterministic instruction, not new
+ * information a refiner session needs to reason about.
+ *
+ * Two deliberate differences from `publish()`:
+ *
+ *  - **No `<prefix>:refined` label.** A spec is not a workable leaf — it is
+ *    itself a thing that gets refined later, by `claimSpecs` picking it up
+ *    once it carries `<prefix>:spec-ready`.
+ *  - **No `linkChild`.** On Jira a spec is a Story by default
+ *    (`JiraIssueTypeMapSchema.spec`), and a Story cannot parent a Story — the
+ *    tracker-native hierarchy `publish()` uses for a `RefinedIssue` tree is
+ *    unavailable for spec-under-spec. The `## Parent` body section is the
+ *    only link, same as a bare `spf refine --issue N` run with no authored
+ *    hierarchy to speak of.
+ *
+ * Same not-transactional contract as `publish()`: a create call failing
+ * partway through leaves whatever was already created stranded, for a human
+ * to sort out the way any other `spf watch` failure is sorted out (`spf
+ * phases`, then a re-run).
+ */
+export declare function publishSpecs(tracker: IssueAuthoringProvider, specs: SpecSplit[], opts: PublishSpecsOptions): Promise<Issue[]>;

package/dist/core/refine.js

@@ -120,7 +120,18 @@ export function parseRefineMarker(body) {
  * this runs: `topoOrder` visits a node's dependencies before the node itself.
  */
 function renderBody(node, byKey, specIssueId) {
-    const parts = [node.body.trim()];
+    const parts = [];
+    // First on the issue, ahead of the refiner's own prose: the one sentence
+    // saying why this ticket exists (see `RefinedIssueSchema.user_outcome`). A
+    // human triaging `spf:refined` leaves reads a title and a first line, and
+    // this is the line worth reading. OMITTED when blank rather than rendered
+    // as an empty heading — a container legitimately has none, and neither a
+    // hand-built `publish()` call nor a tree from before this field existed
+    // carries one. Same tolerate-and-degrade policy as `parseRefineMarker`.
+    const outcome = node.user_outcome.trim();
+    if (outcome)
+        parts.push(`## Outcome\n\n${outcome}`);
+    parts.push(node.body.trim());
     if (specIssueId)
         parts.push(`## Parent\n\nDecomposed from #${specIssueId}.`);
     const blockedByIds = node.blocked_by.map((key) => {
@@ -224,3 +235,47 @@ export async function publish(tracker, issues, opts) {
     }
     return created;
 }
+/**
+ * `publish()`'s twin for the OTHER escalation path: a spec too large for one
+ * decomposition, split into several standalone specs a human has already
+ * approved (see `WatchState`'s doc comment on `split-proposed`/
+ * `split-approved` in `core/issues/provider.ts`). Called by
+ * `core/watch.ts`'s `executeApprovedSplits` — never by an agent phase, since
+ * approving a recorded proposal is a deterministic instruction, not new
+ * information a refiner session needs to reason about.
+ *
+ * Two deliberate differences from `publish()`:
+ *
+ *  - **No `<prefix>:refined` label.** A spec is not a workable leaf — it is
+ *    itself a thing that gets refined later, by `claimSpecs` picking it up
+ *    once it carries `<prefix>:spec-ready`.
+ *  - **No `linkChild`.** On Jira a spec is a Story by default
+ *    (`JiraIssueTypeMapSchema.spec`), and a Story cannot parent a Story — the
+ *    tracker-native hierarchy `publish()` uses for a `RefinedIssue` tree is
+ *    unavailable for spec-under-spec. The `## Parent` body section is the
+ *    only link, same as a bare `spf refine --issue N` run with no authored
+ *    hierarchy to speak of.
+ *
+ * Same not-transactional contract as `publish()`: a create call failing
+ * partway through leaves whatever was already created stranded, for a human
+ * to sort out the way any other `spf watch` failure is sorted out (`spf
+ * phases`, then a re-run).
+ */
+export async function publishSpecs(tracker, specs, opts) {
+    const created = [];
+    for (const spec of specs) {
+        const labels = [
+            typeLabel(opts.labelPrefix, "spec"),
+            `${opts.labelPrefix}:spec-ready`,
+            ...(opts.priority ? [priorityLabel(opts.labelPrefix, opts.priority)] : []),
+        ];
+        const body = [
+            spec.body.trim(),
+            `## Parent\n\nSplit from #${opts.originalSpecId} — too large to decompose as one spec.`,
+            `## Why this is its own spec\n\n${spec.rationale.trim()}`,
+        ].join("\n\n");
+        const issue = await tracker.createIssue({ title: spec.title, body, labels, kind: "spec" });
+        created.push(issue);
+    }
+    return created;
+}