@gr8ful/spf 0.12.0 → 0.14.0

package/dist/core/data_types.d.ts

@@ -182,6 +182,37 @@ export declare const RefinedIssueSchema: v.ObjectSchema<{
     readonly key: v.StringSchema<undefined>;
     readonly kind: v.PicklistSchema<["epic", "feature", "story", "bug", "task"], undefined>;
     readonly title: v.StringSchema<undefined>;
+    /**
+     * One sentence: what someone can do once this node lands that they could
+     * not before — the "slice test" sentence from
+     * `assets/prompts/refiner/system.md`. A FIELD rather than a `##` section
+     * inside `body`, for three reasons. It rides the constrained decode —
+     * `core/agents.ts` hands `call.output_type.schema` to the coding agent as
+     * `output_schema` on every send, corrections included — so this is a slot
+     * the model fills while it is still deciding what the slice IS, not a
+     * heading it appends afterwards to satisfy a check it read about (the
+     * asymmetry `c9a4471`'s banned-noun rule lacked, and why the model routed
+     * around it). It is checkable without a regex over prose the model
+     * controls the format of. And it leaves `body`'s documented shape — "##
+     * What to build" then "## Acceptance criteria" only, a rule stated in
+     * `body`'s own comment below, in `assets/prompts/refiner/user.md` and in
+     * `system.md` — alone, instead of contradicting it in three places.
+     *
+     * `v.optional(..., "")` rather than a bare `v.string()`, deliberately, and
+     * against the pattern `title`/`body` set: a MISSING field fails the
+     * valibot parse and burns a JSON-repair retry on a generic "field
+     * required" message, whereas an EMPTY one reaches
+     * `gates.refinementWellFormed`, which sends back a correction that says
+     * what sentence to write and why. The better message is worth more here
+     * than the earlier failure, and every existing `core/refine.ts`
+     * `publish()` caller keeps compiling unchanged.
+     *
+     * Present on every node in the schema (a container should have to answer
+     * for itself too), enforced by the gate on LEAVES only: a container's
+     * outcome is the union of its children's, and a blank one there is a
+     * style note, not a decomposition mistake.
+     */
+    readonly user_outcome: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly body: v.StringSchema<undefined>;
     readonly parent: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly blocked_by: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
@@ -210,7 +241,43 @@ export declare const RefineQuestionSchema: v.ObjectSchema<{
     readonly evidence: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
 }, undefined>;
 export type RefineQuestion = v.InferOutput<typeof RefineQuestionSchema>;
-/** A product spec decomposed into a feature/story tree — see `steps.refine()` and `core/refine.ts`. */
+/**
+ * One proposed standalone spec, part of splitting an over-large spec into
+ * several — the refiner's answer to "this spec doesn't fit the leaf budget"
+ * that is NOT ambiguity (contrast `RefineQuestionSchema`, which is). `body`
+ * is a complete spec in its own right — problem, proposed outcome, scope —
+ * not a fragment or a "phase" of a larger plan: `assets/prompts/refiner/
+ * system.md`'s sizing section requires each entry to be something a human
+ * would ship on its own. `rationale` is why it's coherent alone, and should
+ * state the leaf count the refiner expects it to decompose into, so a human
+ * approving the split can see at a glance that the split actually fixes the
+ * over-budget problem rather than just moving it downstream.
+ *
+ * `core/refine.ts`'s `publishSpecs()` turns an approved list of these into
+ * real tracker issues (`kind: "spec"`, `<prefix>:type:spec` +
+ * `<prefix>:spec-ready` labels) — see `WatchMarker.split` in
+ * `core/issues/provider.ts` for how a proposal is recorded between "the
+ * refiner proposed it" and "a human approved it."
+ */
+export declare const SpecSplitSchema: v.ObjectSchema<{
+    readonly title: v.StringSchema<undefined>;
+    readonly body: v.StringSchema<undefined>;
+    readonly rationale: v.StringSchema<undefined>;
+}, undefined>;
+export type SpecSplit = v.InferOutput<typeof SpecSplitSchema>;
+/**
+ * A product spec decomposed into a feature/story tree — see `steps.refine()`
+ * and `core/refine.ts`. Exactly one of `issues` / `questions` / `split` is
+ * non-empty for a given round (`gates.refinementWellFormed` enforces all
+ * three pairwise): `issues` is an unambiguous decomposition that fits the
+ * budget; `questions` is material ambiguity (scope, data model, an external
+ * dependency, a UX contract — see `system.md`'s "Ask, don't decide");
+ * `split` is neither of those — the spec is simply too large for one
+ * decomposition, and the refiner proposes cutting it into several standalone
+ * specs instead of guessing at a scope cut or force-fitting an oversized
+ * tree. See `SpecSplitSchema`'s own doc comment for what `split`'s job is
+ * *not*: an ambiguity question, or a fragment of a bigger plan.
+ */
 export declare const RefineOutput: EnvelopeType<{
     status: "fail" | "success";
     summary: string;
@@ -220,6 +287,7 @@ export declare const RefineOutput: EnvelopeType<{
         key: string;
         kind: "bug" | "epic" | "feature" | "story" | "task";
         title: string;
+        user_outcome: string;
         body: string;
         parent: string;
         blocked_by: string[];
@@ -233,6 +301,11 @@ export declare const RefineOutput: EnvelopeType<{
         recommendation: string;
         evidence: string[];
     }[];
+    split: {
+        title: string;
+        body: string;
+        rationale: string;
+    }[];
 }>;
 export type RefineOutputT = v.InferOutput<typeof RefineOutput.schema>;
 export declare const QualityAreaSchema: v.PicklistSchema<["frontend", "backend"], undefined>;
@@ -384,8 +457,29 @@ export declare class GateReport {
     get passed(): boolean;
 }
 /** The minimal shape a gate needs from a run — avoids a circular import with runner.ts. */
+/** The minimal shape a gate needs from a run — avoids a circular import with runner.ts. */
 export interface RunContext {
     repo_root: string;
+    /**
+     * The run's resolved config. The one field here that isn't about the
+     * filesystem: `gates.refinementWellFormed` reads `watch.refine`'s
+     * decomposition budget from it. `core/runner.ts`'s `Run` already carries
+     * `cfg` — it satisfies this interface structurally, which is the entire
+     * point of an interface this narrow — so the single production call site
+     * (`core/agents.ts`'s gate loop, which passes the `Run` itself) always
+     * supplies it.
+     *
+     * OPTIONAL rather than required so a gate stays callable from a test or a
+     * tool holding nothing but a repo root; absent, a gate falls back to the
+     * packaged `DEFAULT_REFINE_*` constants — the SAME numbers a config file
+     * that omits those keys resolves to, never a skipped check. Same shape as
+     * `core/permissions.ts`'s own `RunLike` (`{repo_root, cfg}`), deliberately
+     * — two structural narrowings of `Run` that agree.
+     *
+     * `SFConfig` is declared later in this file; a forward reference in a type
+     * position is erased at compile time and needs no reordering.
+     */
+    cfg?: SFConfig;
 }
 export type GateFn = (envelope: EnvelopeBase, run: RunContext) => GateReport | string[];
 /** One agent invocation: prompt in, typed envelope out, gates verified. */
@@ -735,6 +829,14 @@ export declare const JiraIssueTypeMapSchema: v.ObjectSchema<{
     readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
     readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
     readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+    /**
+     * A spec proposed by `core/refine.ts`'s `publishSpecs()` — a Story by
+     * default, the same hierarchy level BT-1789 itself was created at. Never
+     * `"Epic"`: a spec is not a container in the `RefineOutput.issues` tree
+     * `gates.refinementWellFormed` validates (it can't be a `parent` there),
+     * so it doesn't need Epic-under-Epic nesting the way `feature` does.
+     */
+    readonly spec: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
 }, undefined>;
 export type JiraIssueTypeMap = v.InferOutput<typeof JiraIssueTypeMapSchema>;
 /**
@@ -755,12 +857,21 @@ export declare const WatchJiraConfigSchema: v.ObjectSchema<{
         readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
         readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
         readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+        /**
+         * A spec proposed by `core/refine.ts`'s `publishSpecs()` — a Story by
+         * default, the same hierarchy level BT-1789 itself was created at. Never
+         * `"Epic"`: a spec is not a container in the `RefineOutput.issues` tree
+         * `gates.refinementWellFormed` validates (it can't be a `parent` there),
+         * so it doesn't need Epic-under-Epic nesting the way `feature` does.
+         */
+        readonly spec: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
     }, undefined>, () => {
         epic: string;
         feature: string;
         story: string;
         bug: string;
         task: string;
+        spec: string;
     }>;
 }, undefined>;
 export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
@@ -774,10 +885,61 @@ export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
  * any other value fails loudly at `spf watch` startup rather than running a
  * refine lane that can never publish anything.
  */
+/**
+ * The decomposition BUDGET's packaged defaults, and the single source of
+ * truth for them: `WatchRefineConfigSchema` below uses them as its valibot
+ * defaults, and `gates.refineBudget` falls back to them for a `RunContext`
+ * carrying no `cfg` (see `RunContext.cfg`). Two copies of a default is how a
+ * config file and the gate that enforces it come to disagree about what the
+ * budget IS, so there is one copy.
+ *
+ * These are CEILINGS, not targets. `assets/prompts/refiner/system.md` states
+ * the target — one feature, three or four leaves. A gate that failed AT the
+ * target would MAKE the target a floor: every spec would land exactly on the
+ * number and none would land under it. So the gate fires one slice past
+ * where a good decomposition sits, not at it.
+ *
+ * The unit of `DEFAULT_REFINE_MAX_LEAVES` is HUMAN REVIEWS, not model effort:
+ * every leaf gets `<prefix>:refined`, and `core/watch.ts`'s build lane turns
+ * each one into its own worktree, its own chain run and its own pull request
+ * a person reads.
+ */
+export declare const DEFAULT_REFINE_MAX_LEAVES = 4;
+export declare const DEFAULT_REFINE_MAX_NODES = 6;
+export declare const DEFAULT_REFINE_MAX_DEPTH = 2;
+/**
+ * `max_leaves`/`max_nodes`/`max_depth` are the decomposition budget
+ * `gates.refinementWellFormed` enforces — see `DEFAULT_REFINE_*` above for
+ * what each is denominated in and why the gate's number is looser than the
+ * prompt's target. Three notes an operator tuning these needs:
+ *
+ *  - `max_nodes` DOES NOT BIND at the defaults. With `max_depth: 2` and the
+ *    gate's no-singleton-container rule, every container has at least two
+ *    children, so a tree is at most `max_leaves + floor(max_leaves / 2)` = 6
+ *    nodes at the default `max_leaves: 4`. It exists so that raising ONE of
+ *    the other two knobs cannot silently uncap the whole tree.
+ *  - RAISING `max_depth` ABOVE 2 IS UNSAFE ON JIRA. `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) — a three-level tree reaches `linkChild` and
+ *    comes back as a raw Atlassian API error partway through a publish that
+ *    is deliberately not transactional. At 2, that tree is rejected before a
+ *    single issue is created.
+ *  - There is no "unlimited". `minValue(1)` on all three is deliberate: a
+ *    spec that genuinely needs more slices than the budget allows is a spec
+ *    that should be SPLIT, and the refiner has a first-class way to say so
+ *    (`RefineOutput.split` -> `core/watch.ts`'s `proposeSpecSplit` ->
+ *    `split-proposed`, approved by a human, executed by
+ *    `executeApprovedSplits`). An operator who disagrees raises the number
+ *    rather than removing it.
+ */
 export declare const WatchRefineConfigSchema: v.ObjectSchema<{
     readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
     readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
     readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+    readonly max_leaves: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 50, undefined>]>, 4>;
+    readonly max_nodes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 100, undefined>]>, 6>;
+    readonly max_depth: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 4, undefined>]>, 2>;
 }, undefined>;
 export type WatchRefineConfig = v.InferOutput<typeof WatchRefineConfigSchema>;
 /**
@@ -846,12 +1008,21 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
             readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
             readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
             readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+            /**
+             * A spec proposed by `core/refine.ts`'s `publishSpecs()` — a Story by
+             * default, the same hierarchy level BT-1789 itself was created at. Never
+             * `"Epic"`: a spec is not a container in the `RefineOutput.issues` tree
+             * `gates.refinementWellFormed` validates (it can't be a `parent` there),
+             * so it doesn't need Epic-under-Epic nesting the way `feature` does.
+             */
+            readonly spec: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
         }, undefined>, () => {
             epic: string;
             feature: string;
             story: string;
             bug: string;
             task: string;
+            spec: string;
         }>;
     }, undefined>, () => {
         base_url: string;
@@ -862,16 +1033,23 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
             story: string;
             bug: string;
             task: string;
+            spec: string;
         };
     }>;
     readonly refine: v.OptionalSchema<v.ObjectSchema<{
         readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
         readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
         readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+        readonly max_leaves: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 50, undefined>]>, 4>;
+        readonly max_nodes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 100, undefined>]>, 6>;
+        readonly max_depth: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 4, undefined>]>, 2>;
     }, undefined>, () => {
         enabled: boolean;
         chain: string;
         concurrency: number;
+        max_leaves: number;
+        max_nodes: number;
+        max_depth: number;
     }>;
     readonly fanout: v.OptionalSchema<v.ObjectSchema<{
         readonly n: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 8, undefined>]>, 1>;
@@ -921,6 +1099,7 @@ export declare const NotificationsConfigSchema: v.ObjectSchema<{
         readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
         readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
     }, undefined>, undefined>, () => never[]>;
+    readonly project: v.OptionalSchema<v.StringSchema<undefined>, "">;
 }, undefined>;
 export type NotificationsConfig = v.InferOutput<typeof NotificationsConfigSchema>;
 /**
@@ -1168,12 +1347,21 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
                 readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
                 readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+                /**
+                 * A spec proposed by `core/refine.ts`'s `publishSpecs()` — a Story by
+                 * default, the same hierarchy level BT-1789 itself was created at. Never
+                 * `"Epic"`: a spec is not a container in the `RefineOutput.issues` tree
+                 * `gates.refinementWellFormed` validates (it can't be a `parent` there),
+                 * so it doesn't need Epic-under-Epic nesting the way `feature` does.
+                 */
+                readonly spec: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
             }, undefined>, () => {
                 epic: string;
                 feature: string;
                 story: string;
                 bug: string;
                 task: string;
+                spec: string;
             }>;
         }, undefined>, () => {
             base_url: string;
@@ -1184,16 +1372,23 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 story: string;
                 bug: string;
                 task: string;
+                spec: string;
             };
         }>;
         readonly refine: v.OptionalSchema<v.ObjectSchema<{
             readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
             readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
             readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+            readonly max_leaves: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 50, undefined>]>, 4>;
+            readonly max_nodes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 100, undefined>]>, 6>;
+            readonly max_depth: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 4, undefined>]>, 2>;
         }, undefined>, () => {
             enabled: boolean;
             chain: string;
             concurrency: number;
+            max_leaves: number;
+            max_nodes: number;
+            max_depth: number;
         }>;
         readonly fanout: v.OptionalSchema<v.ObjectSchema<{
             readonly n: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 8, undefined>]>, 1>;
@@ -1224,12 +1419,16 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 story: string;
                 bug: string;
                 task: string;
+                spec: string;
             };
         };
         refine: {
             enabled: boolean;
             chain: string;
             concurrency: number;
+            max_leaves: number;
+            max_nodes: number;
+            max_depth: number;
         };
         fanout: {
             n: number;
@@ -1245,6 +1444,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
             readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
         }, undefined>, undefined>, () => never[]>;
+        readonly project: v.OptionalSchema<v.StringSchema<undefined>, "">;
     }, undefined>, () => {
         events: "all" | "attention" | "errors" | "off";
         timeout_ms: number;
@@ -1254,6 +1454,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             events?: "all" | "attention" | "errors" | "off" | null | undefined;
             name: string;
         }[];
+        project: string;
     }>;
     readonly review: v.OptionalSchema<v.ObjectSchema<{
         readonly require_human_signoff: v.OptionalSchema<v.BooleanSchema<undefined>, false>;

package/dist/core/data_types.js

@@ -138,6 +138,37 @@ export const RefinedIssueSchema = v.object({
     key: v.string(),
     kind: v.picklist(["epic", "feature", "story", "bug", "task"]),
     title: v.string(),
+    /**
+     * One sentence: what someone can do once this node lands that they could
+     * not before — the "slice test" sentence from
+     * `assets/prompts/refiner/system.md`. A FIELD rather than a `##` section
+     * inside `body`, for three reasons. It rides the constrained decode —
+     * `core/agents.ts` hands `call.output_type.schema` to the coding agent as
+     * `output_schema` on every send, corrections included — so this is a slot
+     * the model fills while it is still deciding what the slice IS, not a
+     * heading it appends afterwards to satisfy a check it read about (the
+     * asymmetry `c9a4471`'s banned-noun rule lacked, and why the model routed
+     * around it). It is checkable without a regex over prose the model
+     * controls the format of. And it leaves `body`'s documented shape — "##
+     * What to build" then "## Acceptance criteria" only, a rule stated in
+     * `body`'s own comment below, in `assets/prompts/refiner/user.md` and in
+     * `system.md` — alone, instead of contradicting it in three places.
+     *
+     * `v.optional(..., "")` rather than a bare `v.string()`, deliberately, and
+     * against the pattern `title`/`body` set: a MISSING field fails the
+     * valibot parse and burns a JSON-repair retry on a generic "field
+     * required" message, whereas an EMPTY one reaches
+     * `gates.refinementWellFormed`, which sends back a correction that says
+     * what sentence to write and why. The better message is worth more here
+     * than the earlier failure, and every existing `core/refine.ts`
+     * `publish()` caller keeps compiling unchanged.
+     *
+     * Present on every node in the schema (a container should have to answer
+     * for itself too), enforced by the gate on LEAVES only: a container's
+     * outcome is the union of its children's, and a blank one there is a
+     * style note, not a decomposition mistake.
+     */
+    user_outcome: v.optional(v.string(), ""),
     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
@@ -164,10 +195,46 @@ export const RefineQuestionSchema = v.object({
     recommendation: v.optional(v.string(), ""),
     evidence: v.optional(v.array(v.string()), () => []),
 });
-/** A product spec decomposed into a feature/story tree — see `steps.refine()` and `core/refine.ts`. */
+/**
+ * One proposed standalone spec, part of splitting an over-large spec into
+ * several — the refiner's answer to "this spec doesn't fit the leaf budget"
+ * that is NOT ambiguity (contrast `RefineQuestionSchema`, which is). `body`
+ * is a complete spec in its own right — problem, proposed outcome, scope —
+ * not a fragment or a "phase" of a larger plan: `assets/prompts/refiner/
+ * system.md`'s sizing section requires each entry to be something a human
+ * would ship on its own. `rationale` is why it's coherent alone, and should
+ * state the leaf count the refiner expects it to decompose into, so a human
+ * approving the split can see at a glance that the split actually fixes the
+ * over-budget problem rather than just moving it downstream.
+ *
+ * `core/refine.ts`'s `publishSpecs()` turns an approved list of these into
+ * real tracker issues (`kind: "spec"`, `<prefix>:type:spec` +
+ * `<prefix>:spec-ready` labels) — see `WatchMarker.split` in
+ * `core/issues/provider.ts` for how a proposal is recorded between "the
+ * refiner proposed it" and "a human approved it."
+ */
+export const SpecSplitSchema = v.object({
+    title: v.string(),
+    body: v.string(),
+    rationale: v.string(),
+});
+/**
+ * A product spec decomposed into a feature/story tree — see `steps.refine()`
+ * and `core/refine.ts`. Exactly one of `issues` / `questions` / `split` is
+ * non-empty for a given round (`gates.refinementWellFormed` enforces all
+ * three pairwise): `issues` is an unambiguous decomposition that fits the
+ * budget; `questions` is material ambiguity (scope, data model, an external
+ * dependency, a UX contract — see `system.md`'s "Ask, don't decide");
+ * `split` is neither of those — the spec is simply too large for one
+ * decomposition, and the refiner proposes cutting it into several standalone
+ * specs instead of guessing at a scope cut or force-fitting an oversized
+ * tree. See `SpecSplitSchema`'s own doc comment for what `split`'s job is
+ * *not*: an ambiguity question, or a fragment of a bigger plan.
+ */
 export const RefineOutput = envelopeType("RefineOutput", {
     issues: v.optional(v.array(RefinedIssueSchema), () => []),
     questions: v.optional(v.array(RefineQuestionSchema), () => []),
+    split: v.optional(v.array(SpecSplitSchema), () => []),
 });
 // ── Deterministic quality blocks ─────────────────────────────────────────────
 export const QualityAreaSchema = v.picklist(["frontend", "backend"]);
@@ -585,6 +652,14 @@ export const JiraIssueTypeMapSchema = v.object({
     story: v.optional(v.string(), "Story"),
     bug: v.optional(v.string(), "Bug"),
     task: v.optional(v.string(), "Task"),
+    /**
+     * A spec proposed by `core/refine.ts`'s `publishSpecs()` — a Story by
+     * default, the same hierarchy level BT-1789 itself was created at. Never
+     * `"Epic"`: a spec is not a container in the `RefineOutput.issues` tree
+     * `gates.refinementWellFormed` validates (it can't be a `parent` there),
+     * so it doesn't need Epic-under-Epic nesting the way `feature` does.
+     */
+    spec: v.optional(v.string(), "Story"),
 });
 /**
  * Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` +
@@ -610,10 +685,61 @@ export const WatchJiraConfigSchema = v.object({
  * any other value fails loudly at `spf watch` startup rather than running a
  * refine lane that can never publish anything.
  */
+/**
+ * The decomposition BUDGET's packaged defaults, and the single source of
+ * truth for them: `WatchRefineConfigSchema` below uses them as its valibot
+ * defaults, and `gates.refineBudget` falls back to them for a `RunContext`
+ * carrying no `cfg` (see `RunContext.cfg`). Two copies of a default is how a
+ * config file and the gate that enforces it come to disagree about what the
+ * budget IS, so there is one copy.
+ *
+ * These are CEILINGS, not targets. `assets/prompts/refiner/system.md` states
+ * the target — one feature, three or four leaves. A gate that failed AT the
+ * target would MAKE the target a floor: every spec would land exactly on the
+ * number and none would land under it. So the gate fires one slice past
+ * where a good decomposition sits, not at it.
+ *
+ * The unit of `DEFAULT_REFINE_MAX_LEAVES` is HUMAN REVIEWS, not model effort:
+ * every leaf gets `<prefix>:refined`, and `core/watch.ts`'s build lane turns
+ * each one into its own worktree, its own chain run and its own pull request
+ * a person reads.
+ */
+export const DEFAULT_REFINE_MAX_LEAVES = 4;
+export const DEFAULT_REFINE_MAX_NODES = 6;
+export const DEFAULT_REFINE_MAX_DEPTH = 2;
+/**
+ * `max_leaves`/`max_nodes`/`max_depth` are the decomposition budget
+ * `gates.refinementWellFormed` enforces — see `DEFAULT_REFINE_*` above for
+ * what each is denominated in and why the gate's number is looser than the
+ * prompt's target. Three notes an operator tuning these needs:
+ *
+ *  - `max_nodes` DOES NOT BIND at the defaults. With `max_depth: 2` and the
+ *    gate's no-singleton-container rule, every container has at least two
+ *    children, so a tree is at most `max_leaves + floor(max_leaves / 2)` = 6
+ *    nodes at the default `max_leaves: 4`. It exists so that raising ONE of
+ *    the other two knobs cannot silently uncap the whole tree.
+ *  - RAISING `max_depth` ABOVE 2 IS UNSAFE ON JIRA. `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) — a three-level tree reaches `linkChild` and
+ *    comes back as a raw Atlassian API error partway through a publish that
+ *    is deliberately not transactional. At 2, that tree is rejected before a
+ *    single issue is created.
+ *  - There is no "unlimited". `minValue(1)` on all three is deliberate: a
+ *    spec that genuinely needs more slices than the budget allows is a spec
+ *    that should be SPLIT, and the refiner has a first-class way to say so
+ *    (`RefineOutput.split` -> `core/watch.ts`'s `proposeSpecSplit` ->
+ *    `split-proposed`, approved by a human, executed by
+ *    `executeApprovedSplits`). An operator who disagrees raises the number
+ *    rather than removing it.
+ */
 export const WatchRefineConfigSchema = v.object({
     enabled: v.optional(v.boolean(), false),
     chain: v.optional(v.string(), "refine"),
     concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 1),
+    max_leaves: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(50)), DEFAULT_REFINE_MAX_LEAVES),
+    max_nodes: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100)), DEFAULT_REFINE_MAX_NODES),
+    max_depth: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(4)), DEFAULT_REFINE_MAX_DEPTH),
 });
 /**
  * Best-of-N per claimed issue — `core/fanout.ts`'s proven machinery pointed at
@@ -708,6 +834,13 @@ export const NotificationsConfigSchema = v.object({
     events: v.optional(NotifyScopeSchema, "off"),
     timeout_ms: v.optional(v.number(), 5_000),
     channels: v.optional(v.array(NotifyChannelSchema), () => []),
+    // Prefixed onto every outbound title (e.g. "[api] watch: ..." ) and added
+    // as a `repo` field, so one Slack/Teams/webhook endpoint shared across
+    // several `spf watch` instances (one per repo) can tell them apart.
+    // Empty means "derive from watch.repo" (see `resolveNotifier`) — set this
+    // explicitly only when that repo string isn't a good enough label, e.g.
+    // it's blank, or two watched repos share a basename.
+    project: v.optional(v.string(), ""),
 });
 /**
  * `simple_sdlc`'s human-signoff gate — see the ACCEPTED ADVERSARIAL

package/dist/core/gates.d.ts

@@ -29,6 +29,20 @@ export declare function diffMatchesClaims(envelope: EnvelopeBase, run: RunContex
  * reading a line of the diff.
  */
 export declare function verdictConsistent(envelope: EnvelopeBase, _run: RunContext): GateReport;
+/**
+ * The decomposition budget in force for this run: `watch.refine`'s
+ * configured ceilings, or the packaged defaults when the caller handed us no
+ * `cfg` (see `RunContext.cfg`). Its own function, and exported, so `spf
+ * doctor` can print the three numbers this gate enforces by calling the SAME
+ * resolution the gate uses, rather than a second reading of the config that
+ * can drift from it — the `clampPriority` pattern.
+ */
+export interface RefineBudget {
+    maxLeaves: number;
+    maxNodes: number;
+    maxDepth: number;
+}
+export declare function refineBudget(run: RunContext): RefineBudget;
 /**
  * The gate that turns `to-tickets`' flat, untyped ticket list into an
  * actually-enforced feature/story-or-bug tree — see `RefinedIssueSchema`'s
@@ -41,14 +55,16 @@ export declare function verdictConsistent(envelope: EnvelopeBase, _run: RunConte
  * "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 declare function refinementWellFormed(envelope: EnvelopeBase, _run: RunContext): GateReport;
+export declare function refinementWellFormed(envelope: EnvelopeBase, run: RunContext): GateReport;
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */
 export declare function testsPass(command: string): GateFn;