@gr8ful/spf 0.5.1 → 0.7.0

package/dist/core/data_types.d.ts

@@ -164,6 +164,20 @@ export type DocumentOutputT = v.InferOutput<typeof DocumentOutput.schema>;
  * this list before publish ever runs (unique keys, resolvable references,
  * no cycles, container/leaf kind agreement, at least one leaf).
  */
+/**
+ * `p0` (drop everything) .. `p3` (someday) — see `assets/prompts/refiner/system.md`'s
+ * `## Priority` section for what each rung means. Two rules the schema alone
+ * can't enforce, checked instead by `gates.refinementWellFormed`
+ * (monotonicity: no node outranks its `parent`) and `core/refine.ts`'s
+ * `publish()` (the spec's own priority, when known, is a ceiling clamped onto
+ * every node): see both files' doc comments.
+ */
+export declare const RefinedPrioritySchema: v.PicklistSchema<["p0", "p1", "p2", "p3"], undefined>;
+export type RefinedPriority = v.InferOutput<typeof RefinedPrioritySchema>;
+/** Lower rank = more urgent. The one place both `gates.refinementWellFormed` (monotonicity) and `core/refine.ts`'s `publish()` (the spec-priority ceiling) get their ordering from — see `RefinedPrioritySchema`'s doc comment. */
+export declare const PRIORITY_RANK: Record<RefinedPriority, number>;
+/** `priority`, pulled down to `ceiling` if it outranks it — never raised. `ceiling` nullish (a bare `spf refine` with nothing to inherit from) is a no-op. */
+export declare function clampPriority(priority: RefinedPriority, ceiling: RefinedPriority | null | undefined): RefinedPriority;
 export declare const RefinedIssueSchema: v.ObjectSchema<{
     readonly key: v.StringSchema<undefined>;
     readonly kind: v.PicklistSchema<["epic", "feature", "story", "bug", "task"], undefined>;
@@ -171,8 +185,31 @@ export declare const RefinedIssueSchema: v.ObjectSchema<{
     readonly body: v.StringSchema<undefined>;
     readonly parent: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly blocked_by: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly priority: v.OptionalSchema<v.PicklistSchema<["p0", "p1", "p2", "p3"], undefined>, "p2">;
 }, undefined>;
 export type RefinedIssue = v.InferOutput<typeof RefinedIssueSchema>;
+/**
+ * One open question the refiner could not answer itself — material ambiguity
+ * (scope, data model, an external dependency choice, a UX contract, anything
+ * that would contradict an ADR) it is refusing to guess on, per
+ * `assets/prompts/refiner/system.md`'s "ask, don't decide" rule. `id` is
+ * stable within one round so a resumed run's answers can be matched back to
+ * the question they answer; `why_it_matters`/`options`/`recommendation`/
+ * `evidence` exist so a human can answer in one word ("go with your rec")
+ * instead of re-deriving the tradeoff the refiner already worked out.
+ * `gates.refinementWellFormed` requires `issues` to be empty whenever this is
+ * non-empty — escalating means publishing nothing THIS round, never a
+ * partial tree pinned to an unanswered question.
+ */
+export declare const RefineQuestionSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly question: v.StringSchema<undefined>;
+    readonly why_it_matters: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly options: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly recommendation: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    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`. */
 export declare const RefineOutput: EnvelopeType<{
     status: "fail" | "success";
@@ -186,6 +223,15 @@ export declare const RefineOutput: EnvelopeType<{
         body: string;
         parent: string;
         blocked_by: string[];
+        priority: "p0" | "p1" | "p2" | "p3";
+    }[];
+    questions: {
+        id: string;
+        question: string;
+        why_it_matters: string;
+        options: string[];
+        recommendation: string;
+        evidence: string[];
     }[];
 }>;
 export type RefineOutputT = v.InferOutput<typeof RefineOutput.schema>;
@@ -388,6 +434,50 @@ export declare const ConfigDefaultsSchema: v.ObjectSchema<{
     readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
     readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
+    /**
+     * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
+     *
+     * BOTH ABSENT BY DEFAULT, and absence is a total no-op: `agents.ts`'s
+     * `assertRunBudget()` returns immediately when neither is set, so every
+     * existing config behaves byte-identically to before this field existed.
+     * There is no ambient environment variable and no implicit default — an
+     * unbounded run stays the default because a surprise mid-run failure on a
+     * ceiling nobody chose is worse than the spend.
+     *
+     * SCOPE IS THE RUN, NOT THE CALL. Enforced against the Run's ACCUMULATED
+     * usage (`run.tokens`/`run.cost` — the same totals `run.addUsage()` mirrors
+     * into the sessions row), checked BEFORE every agent dispatch including
+     * every JSON-repair retry and every gate correction, because the cost of
+     * the call about to happen is unknowable in advance. That makes these a
+     * hard cap on FURTHER spend rather than a post-hoc report: reaching the
+     * ceiling stops the next call, it does not merely note that the last one
+     * was expensive. A tripped ceiling fails the phase closed — see
+     * `agents.ts`'s `BudgetExceeded`.
+     *
+     * `max_run_cost` is USD (the same unit the provider's own usage.cost
+     * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is TOTAL
+     * tokens, i.e. the spend number — every turn re-sends the whole
+     * conversation, so this counts cached re-reads too, exactly like the
+     * `total_tokens` column in `sessions` (see `ui/server/db.ts`'s `usage()`
+     * for why that number is much larger than "material moved").
+     *
+     * Both are `> 0`, not `>= 0`: a zero ceiling would mean "no agent may ever
+     * run", which is a config mistake, not a budget — it would fail the first
+     * phase of every chain with a budget message instead of saying what is
+     * actually wrong.
+     *
+     * THE BACK-FILL TRAP (see `agents.ts`'s `loadConfig`): that function copies
+     * a handful of `defaults` keys DOWN onto each agent that hasn't set them
+     * (coding_agent/model/thinking/color/tools/writes/env_allowlist). These two
+     * keys are deliberately NOT in that list and must never be added to it —
+     * they are RUN-scoped ceilings, not per-agent settings, and a per-agent
+     * copy would read as "each agent may spend this much", which is a
+     * different (and unenforced) feature. `mergeRawConfig`'s `defaults` spread
+     * is what carries them through config layering, key-by-key; pinned by
+     * `src/test/budget.test.ts`.
+     */
+    readonly max_run_cost: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
+    readonly max_run_tokens: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
 }, undefined>;
 export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
 /**
@@ -460,10 +550,50 @@ export declare const WatchIssueProviderSchema: v.PicklistSchema<["github", "jira
 export type WatchIssueProviderKind = v.InferOutput<typeof WatchIssueProviderSchema>;
 export declare const WatchCodeHostSchema: v.PicklistSchema<["github", "bitbucket"], undefined>;
 export type WatchCodeHostKind = v.InferOutput<typeof WatchCodeHostSchema>;
-/** Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. */
+/**
+ * What each `RefinedIssue.kind` creates as, on Jira — Jira's create endpoint
+ * requires a real `issuetype`, and project setups vary (renamed types,
+ * non-English instances, custom schemes), so this is a name -> name map,
+ * not a hardcoded assumption. Every field defaults independently: a config
+ * that only sets `bug: Defect` still gets Epic/Epic/Story/Task for the
+ * other four. `jira_provider.ts`'s `createIssue`/`validateIssueTypes` are
+ * the readers; `spf watch init` and `spf watch`'s own startup check
+ * (`cli/commands/watch.ts`) both validate this against the real project
+ * before anything unattended runs on it.
+ */
+export declare const JiraIssueTypeMapSchema: v.ObjectSchema<{
+    readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+    readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+    readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+    readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+    readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+}, undefined>;
+export type JiraIssueTypeMap = v.InferOutput<typeof JiraIssueTypeMapSchema>;
+/**
+ * Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` +
+ * `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. Whole-
+ * object replace on config-file-layer merge, like `refine`/
+ * `observability.otel` (see `agents.ts`'s `mergeRawConfig`) — an override
+ * file that touches `watch.jira` at all must repeat `issue_types` too if it
+ * wants to keep a customized mapping, same caveat that already applies to
+ * `base_url`/`project_key` today.
+ */
 export declare const WatchJiraConfigSchema: v.ObjectSchema<{
     readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly issue_types: v.OptionalSchema<v.ObjectSchema<{
+        readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+        readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+        readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+        readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+        readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+    }, undefined>, () => {
+        epic: string;
+        feature: string;
+        story: string;
+        bug: string;
+        task: string;
+    }>;
 }, undefined>;
 export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
 /**
@@ -471,10 +601,10 @@ export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
  * spec into a feature/story tree of real issues, instead of running
  * `watch.chain` against it directly (a spec is not individually workable —
  * see `core/refine.ts`). Off by default so an existing `watch:` config's
- * behavior is unchanged by upgrading; turning it on with
- * `issue_provider: jira` fails loudly at `spf watch` startup, since
- * `JiraProvider` doesn't implement `IssueAuthoringProvider` (create/link)
- * yet — see its module comment.
+ * behavior is unchanged by upgrading. Needs `issue_provider: github` or
+ * `"jira"` — both implement `IssueAuthoringProvider` (create/link/list) —
+ * any other value fails loudly at `spf watch` startup rather than running a
+ * refine lane that can never publish anything.
  */
 export declare const WatchRefineConfigSchema: v.ObjectSchema<{
     readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -492,12 +622,48 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
     readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
     readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
     readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+    /**
+     * Threaded straight through as `runChainDef`'s `options` argument for
+     * every unattended `spf watch` dispatch (build lane AND refine lane) —
+     * the exact same `Record<string, string>` shape an interactive `spf
+     * <chain> --suite <name>` builds in `cli/commands/run.ts`'s
+     * `dispatchChain` (e.g. `{suite: "strict"}`, `{agent: "..."}`). Fixes the
+     * KNOWN LIMITATION called out in PR #20: `cli/commands/watch.ts`'s
+     * `runChain`/`runRefine` wrappers used to call `runChainDef` with no
+     * options at all, so nothing --suite-shaped could ever reach a chain run
+     * `spf watch` dispatched — see `cli/commands/watch.ts`. Empty by default,
+     * so an existing `watch:` config's behavior is unchanged by upgrading.
+     * Whole-object replace on merge, like `jira`/`refine` above and
+     * `observability.otel` — see `agents.ts`'s `mergeRawConfig` and
+     * `data_types.test.ts`'s merge-survival test for this field.
+     */
+    readonly chain_options: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
     readonly jira: v.OptionalSchema<v.ObjectSchema<{
         readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
         readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly issue_types: v.OptionalSchema<v.ObjectSchema<{
+            readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+            readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+            readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+            readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+            readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+        }, undefined>, () => {
+            epic: string;
+            feature: string;
+            story: string;
+            bug: string;
+            task: string;
+        }>;
     }, undefined>, () => {
         base_url: string;
         project_key: string;
+        issue_types: {
+            epic: string;
+            feature: string;
+            story: string;
+            bug: string;
+            task: string;
+        };
     }>;
     readonly refine: v.OptionalSchema<v.ObjectSchema<{
         readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -574,6 +740,64 @@ export declare const ReviewConfigSchema: v.ObjectSchema<{
     readonly signoff_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 300>;
 }, undefined>;
 export type ReviewConfig = v.InferOutput<typeof ReviewConfigSchema>;
+/**
+ * Risk-tiered per-role model routing — SPF #14. One rung of a ladder:
+ * `name` is what `tiering.roles` points at, `model` speaks EXACTLY the same
+ * vocabulary as an agent's own `model:` for that backend (provider/model-id
+ * for flue, Claude Code's bare alias/full-name for claude_code) — there is
+ * deliberately no per-provider table, since for flue the provider is
+ * already the first segment of the value.
+ *
+ * `coding_agent` declares WHICH BACKEND'S VOCABULARY this rung's `model`
+ * speaks — same picklist and same default as `AgentConfigSchema`'s own
+ * field (`:409`), reused rather than restated. A tier changes an agent's
+ * `model` and NOTHING else (`coding_agent` stays the agent's own, always),
+ * so a rung can only route roles whose `coding_agent` matches its own — see
+ * `core/tiering.ts`'s rule T, enforced by `agents.ts`'s `validate()`.
+ */
+export declare const TierSchema: v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+    readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>;
+export type Tier = v.InferOutput<typeof TierSchema>;
+/**
+ * OFF by default, and `enabled: false`/absent is a TOTAL no-op: every agent
+ * dispatches at exactly the model its roster entry names, byte-identical to
+ * before this key existed — same discipline `max_run_cost`/`max_run_tokens`
+ * hold themselves to (`ConfigDefaultsSchema`'s own comment above).
+ *
+ * TOP-LEVEL (`SFConfigSchema` below), deliberately NOT nested under
+ * `defaults:` — `agents.ts`'s `loadConfig` back-fill loop copies a FIXED
+ * list of `defaults` keys DOWN onto every agent that hasn't set them, and
+ * `AgentConfigSchema` is a non-strict `v.object`, so a stray copy would be
+ * silently STRIPPED at parse rather than rejected (see
+ * `ConfigDefaultsSchema`'s "THE BACK-FILL TRAP" comment — `max_run_cost`/
+ * `max_run_tokens` needed an explicit never-add-this-to-the-list comment to
+ * survive exactly that trap). A top-level key sits outside that loop
+ * entirely, so the trap cannot apply here at all.
+ *
+ * `tiers` is the ladder, WEAKEST FIRST: a risk level shifts every routed
+ * role UP or DOWN this list by the same step, so order is the whole
+ * semantics — a SEQUENCE states that unambiguously where a mapping's key
+ * order would be parser-dependent.
+ *
+ * `roles` is the baseline tier per ROLE (an agent name). Naming an agent
+ * here IS the operator's statement "route this one by tier" — so the
+ * resolved tier wins over that agent's own `model:`. An agent NOT named
+ * here is never retiered: its `model:` stands, untouched. See
+ * `core/tiering.ts`'s `resolveTiering` for the full precedence rule.
+ */
+export declare const TieringConfigSchema: v.ObjectSchema<{
+    readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly tiers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+        readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>, undefined>, () => never[]>;
+    readonly roles: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
+}, undefined>;
+export type TieringConfig = v.InferOutput<typeof TieringConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
@@ -584,6 +808,50 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
         readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
+        /**
+         * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
+         *
+         * BOTH ABSENT BY DEFAULT, and absence is a total no-op: `agents.ts`'s
+         * `assertRunBudget()` returns immediately when neither is set, so every
+         * existing config behaves byte-identically to before this field existed.
+         * There is no ambient environment variable and no implicit default — an
+         * unbounded run stays the default because a surprise mid-run failure on a
+         * ceiling nobody chose is worse than the spend.
+         *
+         * SCOPE IS THE RUN, NOT THE CALL. Enforced against the Run's ACCUMULATED
+         * usage (`run.tokens`/`run.cost` — the same totals `run.addUsage()` mirrors
+         * into the sessions row), checked BEFORE every agent dispatch including
+         * every JSON-repair retry and every gate correction, because the cost of
+         * the call about to happen is unknowable in advance. That makes these a
+         * hard cap on FURTHER spend rather than a post-hoc report: reaching the
+         * ceiling stops the next call, it does not merely note that the last one
+         * was expensive. A tripped ceiling fails the phase closed — see
+         * `agents.ts`'s `BudgetExceeded`.
+         *
+         * `max_run_cost` is USD (the same unit the provider's own usage.cost
+         * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is TOTAL
+         * tokens, i.e. the spend number — every turn re-sends the whole
+         * conversation, so this counts cached re-reads too, exactly like the
+         * `total_tokens` column in `sessions` (see `ui/server/db.ts`'s `usage()`
+         * for why that number is much larger than "material moved").
+         *
+         * Both are `> 0`, not `>= 0`: a zero ceiling would mean "no agent may ever
+         * run", which is a config mistake, not a budget — it would fail the first
+         * phase of every chain with a budget message instead of saying what is
+         * actually wrong.
+         *
+         * THE BACK-FILL TRAP (see `agents.ts`'s `loadConfig`): that function copies
+         * a handful of `defaults` keys DOWN onto each agent that hasn't set them
+         * (coding_agent/model/thinking/color/tools/writes/env_allowlist). These two
+         * keys are deliberately NOT in that list and must never be added to it —
+         * they are RUN-scoped ceilings, not per-agent settings, and a per-agent
+         * copy would read as "each agent may spend this much", which is a
+         * different (and unenforced) feature. `mergeRawConfig`'s `defaults` spread
+         * is what carries them through config layering, key-by-key; pinned by
+         * `src/test/budget.test.ts`.
+         */
+        readonly max_run_cost: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
+        readonly max_run_tokens: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
     }, undefined>, () => {
         coding_agent: "claude_code" | "flue";
         model: string;
@@ -593,6 +861,8 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         tools?: string[] | null | undefined;
         protected_files: string[];
         data_dir: string;
+        max_run_cost?: number | undefined;
+        max_run_tokens?: number | undefined;
     }>;
     readonly observability: v.OptionalSchema<v.ObjectSchema<{
         readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
@@ -660,12 +930,48 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
         readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
         readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+        /**
+         * Threaded straight through as `runChainDef`'s `options` argument for
+         * every unattended `spf watch` dispatch (build lane AND refine lane) —
+         * the exact same `Record<string, string>` shape an interactive `spf
+         * <chain> --suite <name>` builds in `cli/commands/run.ts`'s
+         * `dispatchChain` (e.g. `{suite: "strict"}`, `{agent: "..."}`). Fixes the
+         * KNOWN LIMITATION called out in PR #20: `cli/commands/watch.ts`'s
+         * `runChain`/`runRefine` wrappers used to call `runChainDef` with no
+         * options at all, so nothing --suite-shaped could ever reach a chain run
+         * `spf watch` dispatched — see `cli/commands/watch.ts`. Empty by default,
+         * so an existing `watch:` config's behavior is unchanged by upgrading.
+         * Whole-object replace on merge, like `jira`/`refine` above and
+         * `observability.otel` — see `agents.ts`'s `mergeRawConfig` and
+         * `data_types.test.ts`'s merge-survival test for this field.
+         */
+        readonly chain_options: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
         readonly jira: v.OptionalSchema<v.ObjectSchema<{
             readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
             readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+            readonly issue_types: v.OptionalSchema<v.ObjectSchema<{
+                readonly epic: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+                readonly feature: v.OptionalSchema<v.StringSchema<undefined>, "Epic">;
+                readonly story: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
+                readonly bug: v.OptionalSchema<v.StringSchema<undefined>, "Bug">;
+                readonly task: v.OptionalSchema<v.StringSchema<undefined>, "Task">;
+            }, undefined>, () => {
+                epic: string;
+                feature: string;
+                story: string;
+                bug: string;
+                task: string;
+            }>;
         }, undefined>, () => {
             base_url: string;
             project_key: string;
+            issue_types: {
+                epic: string;
+                feature: string;
+                story: string;
+                bug: string;
+                task: string;
+            };
         }>;
         readonly refine: v.OptionalSchema<v.ObjectSchema<{
             readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -686,9 +992,19 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         base_branch: string;
         poll_ms: number;
         concurrency: number;
+        chain_options: {
+            [x: string]: string;
+        };
         jira: {
             base_url: string;
             project_key: string;
+            issue_types: {
+                epic: string;
+                feature: string;
+                story: string;
+                bug: string;
+                task: string;
+            };
         };
         refine: {
             enabled: boolean;
@@ -722,6 +1038,25 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         require_human_signoff: boolean;
         signoff_timeout_seconds: number;
     }>;
+    readonly tiering: v.OptionalSchema<v.ObjectSchema<{
+        readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly tiers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+            readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        }, undefined>, undefined>, () => never[]>;
+        readonly roles: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
+    }, undefined>, () => {
+        enabled: boolean;
+        tiers: {
+            name: string;
+            coding_agent: "claude_code" | "flue";
+            model: string;
+        }[];
+        roles: {
+            [x: string]: string;
+        };
+    }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
 /** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */