@gr8ful/spf 0.5.0 → 0.6.0

package/dist/core/data_types.js

@@ -125,9 +125,31 @@ export const RefinedIssueSchema = v.object({
     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
 });
+/**
+ * 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 const RefineQuestionSchema = v.object({
+    id: v.string(),
+    question: v.string(),
+    why_it_matters: v.optional(v.string(), ""),
+    options: v.optional(v.array(v.string()), () => []),
+    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`. */
 export const RefineOutput = envelopeType("RefineOutput", {
     issues: v.optional(v.array(RefinedIssueSchema), () => []),
+    questions: v.optional(v.array(RefineQuestionSchema), () => []),
 });
 // ── Deterministic quality blocks ─────────────────────────────────────────────
 export const QualityAreaSchema = v.picklist(["frontend", "backend"]);
@@ -304,6 +326,50 @@ export const ConfigDefaultsSchema = v.object({
     // .spf/ is the whole per-repo footprint now — no adws/ tree to protect.
     protected_files: v.optional(v.array(v.string()), () => [".spf/", "spf.config.yaml"]),
     data_dir: v.optional(v.string(), ".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`.
+     */
+    max_run_cost: v.optional(v.pipe(v.number(), v.gtValue(0))),
+    max_run_tokens: v.optional(v.pipe(v.number(), v.integer(), v.gtValue(0))),
 });
 /**
  * OpenTelemetry span export — OFF unless this block exists, and `endpoint` is
@@ -403,6 +469,22 @@ export const WatchConfigSchema = v.object({
     base_branch: v.optional(v.string(), "main"),
     poll_ms: v.optional(v.number(), 60_000),
     concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 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.
+     */
+    chain_options: v.optional(v.record(v.string(), v.string()), () => ({})),
     jira: v.optional(WatchJiraConfigSchema, () => v.parse(WatchJiraConfigSchema, {})),
     refine: v.optional(WatchRefineConfigSchema, () => v.parse(WatchRefineConfigSchema, {})),
 });
@@ -462,6 +544,58 @@ export const ReviewConfigSchema = v.object({
     require_human_signoff: v.optional(v.boolean(), false),
     signoff_timeout_seconds: v.optional(v.pipe(v.number(), v.minValue(1)), 300),
 });
+/**
+ * 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 const TierSchema = v.object({
+    name: v.pipe(v.string(), v.minLength(1)),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    model: v.pipe(v.string(), v.minLength(1)),
+});
+/**
+ * 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 const TieringConfigSchema = v.object({
+    enabled: v.optional(v.boolean(), false),
+    tiers: v.optional(v.array(TierSchema), () => []),
+    roles: v.optional(v.record(v.string(), v.string()), () => ({})),
+});
 export const SFConfigSchema = v.object({
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
     observability: v.optional(ObservabilityConfigSchema, () => v.parse(ObservabilityConfigSchema, {})),
@@ -470,6 +604,7 @@ export const SFConfigSchema = v.object({
     watch: v.optional(WatchConfigSchema, () => v.parse(WatchConfigSchema, {})),
     notifications: v.optional(NotificationsConfigSchema, () => v.parse(NotificationsConfigSchema, {})),
     review: v.optional(ReviewConfigSchema, () => v.parse(ReviewConfigSchema, {})),
+    tiering: v.optional(TieringConfigSchema, () => v.parse(TieringConfigSchema, {})),
 });
 // ── Tracing ──────────────────────────────────────────────────────────────────
 /** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */

package/dist/core/fanout.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Best-of-N: run ONE prompt N times in parallel, then let CODE pick the winner.
+ *
+ * THE SHAPE IS NOT NEW, and that is the whole argument for it. `spf watch`
+ * already runs N chains CONCURRENTLY IN ONE PROCESS — each with its own git
+ * worktree, its own adw_id, its own `Run`, all sharing the main repo's WAL
+ * SQLite through a data-dir symlink (see `core/watch.ts`'s `runIssue`,
+ * `cli/commands/watch.ts`'s `runChain` closure and its `linkDataDir`). Fan-out
+ * is that proven mechanism pointed at one prompt instead of N issues: N
+ * sibling Runs with derived adw_ids over N worktrees, followed by a
+ * DETERMINISTIC `pickBest`. "Agent proposes, code disposes" — extended to
+ * SELECTION, which is the only new idea here.
+ *
+ * THE UNIT OF ISOLATION IS THE RUN, NEVER AN AGENT CALL. Every attempt gets a
+ * fresh worktree and a fresh Run whose `repo_root` is bound once, in the Run
+ * constructor. That is what keeps `gates.resolveClaim`,
+ * `permissions.snapshot/enforce`, the quality checks and `changes.capture`
+ * judging the tree their agents actually wrote in. A per-call cwd swap would
+ * point them at the wrong tree and hand out green gates on unverified work; a
+ * `SandboxHandle`/cwd-threading design was evaluated for exactly this and
+ * REJECTED. Do not reintroduce it.
+ *
+ * SELECTION READS SQLITE, NOT RETURN VALUES. Gate reports (`tracer.gateRow`)
+ * and per-run usage (`sessions.total_tokens`/`total_cost`) already land in the
+ * shared db keyed by adw_id, so the basis below is a SELECT away. Widening
+ * `steps.runSteps`' return contract to carry metrics back was evaluated and
+ * REJECTED as needless blast radius: every chain, every step, and the watch
+ * dispatch would change to serve one new caller. `runAttempt` still returns
+ * just an exit code, exactly like `runChainDef` does.
+ *
+ * WHY THE BUDGET SHIPS WITH THIS. An n-multiplier on spend without a ceiling
+ * is a footgun — the only budget-like constant before this changeset was
+ * `JSON_FIX_ATTEMPTS = 2`. `defaults.max_run_cost`/`max_run_tokens`
+ * (`core/agents.ts`'s `assertRunBudget`) are checked before each attempt's
+ * NEXT agent call, never after — so one attempt can still overshoot the
+ * ceiling by a whole call, and a chain with only ONE agent dispatch
+ * (`scout`, `prompt`, `build`) can never trip it at all. With that caveat, N
+ * attempts are bounded by roughly N × ceiling, and each one that DOES trip
+ * it fails its phase closed with a message naming the ceiling and the spend.
+ *
+ * WINNER HANDLING KEEPS THE HUMAN ACCOUNTABLE. Each attempt commits on its own
+ * branch in its own worktree. The winner's branch AND worktree are KEPT and
+ * reported (branch + adw_id + the selection basis); the losers' worktrees and
+ * branches are deleted. SPF DOES NOT MERGE THE WINNER — the operator does.
+ * Keeping the winner's worktree is deliberate, not laziness: a chain that
+ * doesn't commit (or that failed after writing) leaves work in the tree only,
+ * and `git worktree remove --force` would destroy it. `git merge`/
+ * `git cherry-pick` from the main repo work fine against a branch that is
+ * checked out elsewhere, so nothing is blocked by keeping it.
+ *
+ * ABORT GRANULARITY, stated plainly because it is a real limit — and, as of
+ * `deps.firstSuccess`, OPT-IN rather than the default. Best-of-N exists to
+ * COMPARE N candidates; the DEFAULT (`firstSuccess` unset/false) therefore
+ * dispatches every attempt regardless of how early one succeeds, so the
+ * gates/cost/tokens comparison in `pickBest` is over the whole field the
+ * operator actually asked for, not "whatever happened to still be queued."
+ * Passing `firstSuccess: true` restores first-past-the-post: once an attempt
+ * exits 0 the race is decided and no further attempt is STARTED —
+ * `deps.runAttempt` is never called for a queued attempt, which is where the
+ * saving actually is (with `concurrency` 2 and `--n 4`, half the attempts are
+ * typically never dispatched). Either way, attempts ALREADY IN FLIGHT run to
+ * completion: `steps.runSteps` has no cancellation seam, and adding one would
+ * mean changing the driver every chain shares for the benefit of this one
+ * caller. `AttemptDispatch.isAborted()` is threaded to the runner so a
+ * dispatch that CAN check between phases does when `firstSuccess` is on, and
+ * so a test can prove the flag is honored — cooperative by design, not by
+ * accident.
+ */
+import { type GitHandle } from "./git_helper.ts";
+/** Sentinel exit code meaning "never dispatched — the race was already decided". Distinct from any real chain exit code. */
+export declare const ABORTED_EXIT = -1;
+/** What one attempt's metrics look like, read back from the shared SQLite by adw_id. */
+export interface AttemptMetrics {
+    /** `gate_results` rows with passed=1 for this adw_id. */
+    gate_passes: number;
+    /** `gate_results` rows with passed=0. Zero is the bar; a nonzero count is a retried/corrected run. */
+    gate_failures: number;
+    /** `sessions.total_cost` — USD. */
+    cost: number;
+    /** `sessions.total_tokens` — the SPEND number (cached re-reads included). */
+    tokens: number;
+}
+export declare const ZERO_METRICS: AttemptMetrics;
+/**
+ * `"success"` means, and only means, EXIT CODE 0 — the same bar
+ * `cli/commands/watch.ts` applies before it opens a PR. Not the session row's
+ * status (which a killed run can leave stale), not the agent's own opinion of
+ * itself. Only a `"success"` attempt is eligible to win.
+ */
+export type AttemptStatus = "success" | "fail" | "error" | "skipped";
+export interface FanoutAttempt {
+    /** 1-based, matching the branch/adw_id suffix a human reads. */
+    index: number;
+    adw_id: string;
+    branch: string;
+    worktree: string;
+    status: AttemptStatus;
+    /** `null` when the dispatch threw before producing one; `ABORTED_EXIT` for a skipped attempt. */
+    exit_code: number | null;
+    error: string | null;
+    gate_passes: number;
+    gate_failures: number;
+    cost: number;
+    tokens: number;
+    wall_ms: number;
+    /** True only for the winner: its worktree and branch survived cleanup. */
+    kept: boolean;
+}
+export interface FanoutResult {
+    /** `null` when no attempt exited 0 — nothing is kept, and the CLI exits non-zero. */
+    winner: FanoutAttempt | null;
+    /** The printed, human-readable justification. Derived from the same comparator that chose the winner. */
+    basis: string;
+    /** Every attempt, in index order — including the ones never dispatched. */
+    attempts: FanoutAttempt[];
+}
+/** `<baseAdw>-<i>` — a derived, greppable sibling of the base id. */
+export declare function attemptAdwId(baseAdwId: string, index: number): string;
+/**
+ * `spf/fanout/<baseAdw>-<i>` — namespaced so the winner is obvious in
+ * `git branch` and the losers are obviously disposable. Separate from
+ * `spf-watch/*`/`spf-refine/*` (see `core/watch.ts`) because these branches
+ * are never pushed by SPF: a human merges the winner from the local ref.
+ */
+export declare function attemptBranch(baseAdwId: string, index: number): string;
+/** The worktree leaf name. Deterministic from the adw_id, like watch's `issue-<id>`. */
+export declare function attemptWorktreeName(baseAdwId: string, index: number): string;
+export declare function attemptWorktreePath(worktreesDir: string, baseAdwId: string, index: number): string;
+/**
+ * The selection basis, in order. Every criterion is read from the shared
+ * SQLite or measured by this module — never asked of an agent.
+ *
+ *  1. the run SUCCEEDED (exit 0). A failed attempt is not a candidate at all.
+ *  2. fewest gate FAILURES, then most gate PASSES. Failures first because zero
+ *     is the bar: an attempt that needed a correction round is worse than one
+ *     that never tripped a gate, regardless of how many gates each ran. Passes
+ *     break that tie in favour of the attempt that VERIFIED more.
+ *  3. lowest total cost.
+ *  4. fewest tokens.
+ *  5. lowest wall time — a LAST RESORT, deliberately below cost and tokens:
+ *     every code phase runs through `spawnSync` (`core/quality.ts`), which
+ *     blocks the shared event loop, so "concurrent" attempts partly serialize
+ *     on exactly the phases fan-out means to compare, and `wall_ms` ends up
+ *     favouring whichever attempt happened to run last by a scheduling
+ *     accident rather than anything about the candidate. Cost and tokens are
+ *     read from the trace and are not subject to that; wall time still
+ *     breaks a genuine tie between two runs identical on both.
+ *  6. lexicographic adw_id.
+ *
+ * (6) exists to make this a TOTAL order: adw_ids are unique per attempt, so
+ * the comparator can never return 0 for two different attempts, so the winner
+ * cannot depend on which attempt happened to finish first. That is what
+ * "deterministic" has to mean here — pinned by a permutation test in
+ * `src/test/fanout.test.ts`.
+ */
+export declare function compareAttempts(a: FanoutAttempt, b: FanoutAttempt): number;
+/**
+ * Pick the winner. PURE: no I/O, no clock, no filesystem — everything it
+ * needs is already on the attempts, which is what makes the selection
+ * testable and reproducible from a trace.
+ *
+ * Sorts a COPY: the caller's array keeps its index order for printing.
+ */
+export declare function pickBest(attempts: FanoutAttempt[]): {
+    winner: FanoutAttempt | null;
+    basis: string;
+};
+/** What `deps.runAttempt` is handed for one attempt. */
+export interface AttemptDispatch {
+    index: number;
+    adwId: string;
+    /** The attempt's OWN worktree — the anchor its Run binds `repo_root` to. Never the main repo. */
+    cwd: string;
+    branch: string;
+    prompt: string;
+    /** Cooperative early-abort — see the module header's ABORT GRANULARITY note. */
+    isAborted: () => boolean;
+}
+/**
+ * Everything `runBestOf` needs, injected — the same seam `WatchDeps` is, and
+ * for the same reason: `core/` stays out of `src/chains/`'s dependency
+ * direction, so the chain dispatch (and the SQLite read) live in
+ * `cli/commands/fanout.ts` and this module is testable against stubs with no
+ * agents, no chains and no real git.
+ */
+export interface FanoutDeps {
+    chainName: string;
+    prompt: string;
+    /** How many attempts. Bounded by the CLI, not here. */
+    n: number;
+    /** How many run at once. `cfg.watch.concurrency` (default 2) is the reused default. */
+    concurrency: number;
+    /** The parent id every attempt's adw_id and branch derives from. */
+    baseAdwId: string;
+    baseBranch: string;
+    /** The MAIN repo root — every worktree is created from here, and every Run is anchored to its own worktree. */
+    repoRoot: string;
+    /** Absolute, OUTSIDE the repo. */
+    worktreesDir: string;
+    /** Bound to `repoRoot`. */
+    git: GitHandle;
+    /** Wire `<worktree>/.spf/data` to the main repo's data dir — the non-obvious part that keeps traces where `spf ui` can see them. */
+    linkDataDir: (worktreePath: string) => void;
+    /** Run one attempt's chain in `cwd`, returning its exit code. */
+    runAttempt: (dispatch: AttemptDispatch) => Promise<number>;
+    /** Read this adw_id's gate/usage rows from the SHARED db. Must not throw — return `ZERO_METRICS` on any hiccup. */
+    readMetrics: (adwId: string) => AttemptMetrics;
+    log: (message: string) => void;
+    /**
+     * Opt-in first-past-the-post. Default (unset/false): every attempt that
+     * was going to run, runs — true best-of-N. `true`: stop dispatching
+     * further attempts once one exits 0, and let an in-flight one observe the
+     * decided race via `AttemptDispatch.isAborted()`. See the module header's
+     * ABORT GRANULARITY note.
+     */
+    firstSuccess?: boolean;
+}
+/**
+ * Run `n` attempts of one prompt, select deterministically, clean up the
+ * losers, keep the winner.
+ *
+ * Concurrency is the same inflight-budget idea as `watch.claimNewWork`,
+ * expressed as a fixed worker pool over a shared queue: at most
+ * `concurrency` attempts are ever in flight, and a worker that finds the race
+ * already decided records the remaining attempts as `skipped` WITHOUT
+ * dispatching them. Attempts are returned in index order regardless of the
+ * order they finished — the printed table must not shuffle between runs.
+ */
+export declare function runBestOf(deps: FanoutDeps): Promise<FanoutResult>;