muonroi-cli 1.3.4 → 1.4.1

package/dist/src/product-loop/sprint-planner.js

@@ -0,0 +1,189 @@
+/**
+ * src/product-loop/sprint-planner.ts
+ *
+ * Converts a Backlog (P6 output) into a SprintPlan by:
+ *  1. Filtering to v1 items only.
+ *  2. Topo-sorting by blockers[] (items with no blockers first).
+ *  3. Greedy bin-packing items into sprints with target effort ≈ 8 pts.
+ *  4. Batch LLM call for sprint goal strings.
+ *  5. Updating each packed BacklogItem with status="in_sprint" + assigned_sprint.
+ *
+ * Model discipline: sprint goal generation uses
+ *   pickCouncilTaskModel("sprint_goal", leaderModelId, costAware=true)
+ * — NO hardcoded model id or provider in this file.
+ */
+import { pickCouncilTaskModel } from "../council/leader.js";
+import { updateBacklogItem } from "./backlog-store.js";
+// ─── Topo-sort helpers ───────────────────────────────────────────────────────
+/**
+ * Topological sort of v1 BacklogItems by their blockers[] references.
+ * Items that have no v1 blockers come first. Cycles are detected; on cycle,
+ * a warning is logged and the remaining items are appended in insertion order.
+ */
+function topoSort(items) {
+    const idSet = new Set(items.map((i) => i.id));
+    // Build adjacency: item depends on its blockers that are also in the v1 set.
+    const deps = new Map();
+    for (const item of items) {
+        deps.set(item.id, new Set((item.blockers ?? []).filter((b) => idSet.has(b))));
+    }
+    const sorted = [];
+    const visited = new Set();
+    const inStack = new Set();
+    let cycleDetected = false;
+    function visit(id) {
+        if (visited.has(id))
+            return;
+        if (inStack.has(id)) {
+            cycleDetected = true;
+            return; // break cycle
+        }
+        inStack.add(id);
+        for (const dep of deps.get(id) ?? []) {
+            visit(dep);
+        }
+        inStack.delete(id);
+        visited.add(id);
+        const item = items.find((i) => i.id === id);
+        if (item)
+            sorted.push(item);
+    }
+    for (const item of items) {
+        visit(item.id);
+    }
+    if (cycleDetected) {
+        // Append any items that were skipped due to cycle detection (in insertion order).
+        for (const item of items) {
+            if (!visited.has(item.id)) {
+                sorted.push(item);
+            }
+        }
+        console.warn(`[sprint-planner] Dependency cycle detected in backlog for runId. Falling back to insertion order for affected items.`);
+    }
+    return sorted;
+}
+// ─── Bin-packing ─────────────────────────────────────────────────────────────
+/**
+ * Greedy bin-pack: walk sorted items, add to current sprint while
+ * sumEffort + item.effort <= targetEffortPerSprint + 2 (allow ±2 slack).
+ * When exceeded, start the next sprint.
+ */
+function packIntoSprints(items, target) {
+    const slack = 2;
+    const bins = [];
+    let current = [];
+    let currentEffort = 0;
+    for (const item of items) {
+        if (current.length > 0 && currentEffort + item.effortPoints > target + slack) {
+            bins.push(current);
+            current = [];
+            currentEffort = 0;
+        }
+        current.push(item);
+        currentEffort += item.effortPoints;
+    }
+    if (current.length > 0) {
+        bins.push(current);
+    }
+    return bins;
+}
+/**
+ * Ask the LLM to generate a 1-line goal for each sprint in a single batch call.
+ * On any failure, gracefully degrade to "Complete items: <titles>".
+ */
+async function generateSprintGoalsBatch(bins, llm, leaderModelId, costAware) {
+    const model = pickCouncilTaskModel("sprint_goal", leaderModelId, costAware);
+    const system = "You are a technical product manager. For each sprint given, write a concise 1-line sprint goal " +
+        "(what the sprint delivers, user-value focused, max 15 words). " +
+        'Respond ONLY with a JSON array: [{"sprintNumber":1,"goal":"..."},{"sprintNumber":2,"goal":"..."},...]';
+    const sprintDescriptions = bins
+        .map((items, idx) => {
+        const titles = items.map((i) => i.title).join(", ");
+        return `Sprint ${idx + 1}: ${titles}`;
+    })
+        .join("\n");
+    const prompt = `Generate a 1-line sprint goal for each of the following ${bins.length} sprints:\n\n` +
+        sprintDescriptions +
+        "\n\nRespond with a JSON array only.";
+    let raw;
+    try {
+        raw = await llm.generate(model, system, prompt, 512);
+    }
+    catch {
+        return bins.map((items) => `Complete items: ${items.map((i) => i.title).join(", ")}`);
+    }
+    try {
+        const match = raw.match(/\[[\s\S]*\]/);
+        if (match) {
+            const arr = JSON.parse(match[0]);
+            return bins.map((items, idx) => {
+                const entry = arr.find((e) => e.sprintNumber === idx + 1);
+                if (entry?.goal)
+                    return entry.goal;
+                return `Complete items: ${items.map((i) => i.title).join(", ")}`;
+            });
+        }
+    }
+    catch {
+        // JSON parse failed — fall through
+    }
+    return bins.map((items) => `Complete items: ${items.map((i) => i.title).join(", ")}`);
+}
+// ─── Main export ──────────────────────────────────────────────────────────────
+/**
+ * Build a SprintPlan from a Backlog.
+ * Also updates each picked BacklogItem in backlog.json with
+ * status="in_sprint" and assigned_sprint=sprint.id.
+ */
+export async function planSprints(input) {
+    const { runId, backlog, llm, leaderModelId, costAware, targetEffortPerSprint = 8 } = input;
+    // Step 1: filter to v1 items.
+    const v1Items = backlog.items.filter((i) => i.mvp_priority === "v1");
+    // Step 2: topo-sort by blockers.
+    const sorted = topoSort(v1Items);
+    // Step 3: greedy bin-pack.
+    const bins = packIntoSprints(sorted, targetEffortPerSprint);
+    // Step 4: batch sprint goal generation.
+    const goals = bins.length > 0 ? await generateSprintGoalsBatch(bins, llm, leaderModelId, costAware) : [];
+    // Step 5: construct Sprint objects.
+    const sprints = bins.map((items, idx) => ({
+        id: `sprint-${idx + 1}`,
+        number: idx + 1,
+        goal: goals[idx] ?? `Complete items: ${items.map((i) => i.title).join(", ")}`,
+        itemIds: items.map((i) => i.id),
+        status: "planned",
+    }));
+    const plan = {
+        runId,
+        sprints,
+        createdAtUtc: new Date().toISOString(),
+    };
+    // Step 6: update each BacklogItem with status="in_sprint" + assigned_sprint.
+    const flowDir = backlog.runId ? undefined : undefined; // flowDir comes from the call site
+    // We cannot update backlog items here because we don't have flowDir in this function.
+    // Callers should call updateBacklogItemsForPlan after planSprints.
+    // Exporting a helper for this:
+    void flowDir; // suppress lint
+    return plan;
+}
+/**
+ * After planSprints(), call this to patch each BacklogItem in backlog.json
+ * with status="in_sprint" and assigned_sprint=sprint.id.
+ *
+ * Separated from planSprints() so that callers who persist the plan to disk
+ * can also trigger item updates without needing to re-read the plan.
+ */
+export async function applySprintAssignments(flowDir, runId, plan) {
+    for (const sprint of plan.sprints) {
+        for (const itemId of sprint.itemIds) {
+            await updateBacklogItem(flowDir, runId, itemId, {
+                status: "in_sprint",
+                assigned_sprint: sprint.id,
+            }).catch((err) => {
+                // Non-fatal: item may have been deleted or runId changed between plan and apply.
+                console.warn(`[sprint-planner] Failed to update backlog item ${itemId}: ${err.message}`);
+            });
+        }
+    }
+}
+//# sourceMappingURL=sprint-planner.js.map

package/dist/src/product-loop/sprint-runner.js

@@ -22,7 +22,9 @@
  *   - CB-2 (oscillation) is checked AFTER this sprint's score is known.
  */
 import * as path from "node:path";
+import { prependDecisionsLock, readDecisionsLock } from "../council/decisions-lock.js";
 import { runCouncil } from "../council/index.js";
+import { phaseDone, phaseError, phaseStart } from "../council/phase-events.js";
 import { readArtifact, writeArtifact } from "../flow/artifact-io.js";
 import { detectProviderForModel } from "../providers/runtime.js";
 import { logUIInteraction } from "../storage/index.js";
@@ -31,6 +33,7 @@ import { CapBreachError } from "../usage/types.js";
 import { runVerifyOrchestration } from "../verify/orchestrator.js";
 import { appendIteration, readCriteria } from "./artifact-io.js";
 import { formatUnverifiedForSprintContext, readLedger } from "./assumption-ledger.js";
+import { readBacklog } from "./backlog-store.js";
 import { CB1_costProjection, CB2_oscillation, CB3_verifyBlank } from "./circuit-breakers.js";
 import { reserveForProduct } from "./cost-scoper.js";
 import { formatProjectContextForPrompt } from "./discovery-context-format.js";
@@ -38,6 +41,7 @@ import { readProjectContext } from "./discovery-persistence.js";
 import { evaluateDoneGate } from "./done-gate.js";
 import { buildContinueFeedback } from "./feedback-routing.js";
 import { postSprintBoundary } from "./phase-tracker-bridge.js";
+import { computeProgressSnapshot, renderSnapshotMarkdown } from "./progress-snapshot.js";
 import { appendRoleMemory } from "./role-memory.js";
 import { loadVerifyFailureSignatures, recordVerifyFailureAndMaybePush } from "./verify-failure-tracking.js";
 import { parseVerifyResult } from "./verify-result.js";
@@ -126,6 +130,19 @@ export async function* runSprint(args) {
     }
     // ── Step 3: Plan stage (council, skipClarification=true) ──────────────────
     yield { type: "content", content: `\n## Sprint ${sprintN} — Planning\n` };
+    // P4-C: emit council_phase so the TUI's CouncilPhaseTimeline shows a live
+    // spinner row "Sprint N — Planning" with ticking elapsed time. Without this
+    // the timeline goes silent for the duration of the planning council, which
+    // is how session f1cec5324716 felt "đơ" for 9+ minutes.
+    const planPhaseId = `sprint-${sprintN}-planning`;
+    const planStartedAt = Date.now();
+    yield phaseStart({
+        phaseId: planPhaseId,
+        kind: "sprint_stage",
+        label: `Sprint ${sprintN} — Planning`,
+        detail: "Council debate to draft sprint plan",
+        startedAt: planStartedAt,
+    });
     // 2.5a — planning stage entry
     try {
         const _ar = globalThis.__muonroiAgentRuntime;
@@ -153,27 +170,53 @@ export async function* runSprint(args) {
         const ledger = await readLedger(ctx.flowDir, ctx.runId);
         const formatted = formatUnverifiedForSprintContext(ledger);
         if (formatted)
-            assumptionContext = "\n" + formatted;
+            assumptionContext = `\n${formatted}`;
     }
     catch {
         /* non-critical */
     }
     const projectCtx = await readProjectContext(ctx.flowDir, ctx.runId);
-    const projectContextStr = projectCtx ? "\nProject Context:\n" + formatProjectContextForPrompt(projectCtx) : "";
+    const projectContextStr = projectCtx ? `\nProject Context:\n${formatProjectContextForPrompt(projectCtx)}` : "";
+    // P6: Anchor council debate to persisted BacklogItems so scope doesn't drift.
+    // Read backlog.json; if it exists, prepend active items for this sprint to
+    // the councilTopic so the council debate cannot introduce out-of-scope features.
+    let backlogAnchor = "";
+    try {
+        const backlog = await readBacklog(ctx.flowDir, ctx.runId);
+        if (backlog) {
+            const sprintKey = `sprint-${sprintN}`;
+            // Active items: status "in_sprint" assigned to this sprint.
+            let activeItems = backlog.items.filter((item) => item.status === "in_sprint" && item.assigned_sprint === sprintKey);
+            // Fallback: first v1 item still in backlog status.
+            if (activeItems.length === 0) {
+                const firstV1 = backlog.items.find((item) => item.mvp_priority === "v1" && item.status === "backlog");
+                if (firstV1)
+                    activeItems = [firstV1];
+            }
+            if (activeItems.length > 0) {
+                backlogAnchor =
+                    `\n## Active Backlog Item\n${JSON.stringify(activeItems, null, 2)}\n\n` +
+                        `The debate MUST address these acceptance criteria. Do NOT introduce features outside this scope.\n`;
+            }
+        }
+    }
+    catch {
+        // Non-critical — proceed without backlog anchor if read fails.
+    }
     const councilTopic = `Plan sprint ${sprintN} for product: ${productSpec.idea}\n\n` +
         `Persona: ${productSpec.persona}\n` +
         `MVP features: ${productSpec.mvp.join(", ")}\n` +
         `Architecture: ${productSpec.architecture}\n` +
         `IO contract: ${productSpec.ioContract}\n` +
         `Folder structure: ${productSpec.folderStructure}\n` +
-        `${carryOverContext}${focusContext}${assumptionContext}${projectContextStr}\n` +
+        `${carryOverContext}${focusContext}${assumptionContext}${projectContextStr}${backlogAnchor}\n` +
         `Goal: produce concrete edits and verifications that move the criteria toward "met".`;
     const productLlm = createProductLlm(ctx.llm, ctx.runId, ctx.flags.maxCost);
     const sessionModelId = roleAssignments.get("Architect")?.modelId ?? roleAssignments.get("PO")?.modelId ?? ctx.sessionModelId;
     const noopProcess = async function* () {
         /* no host orchestrator wired during planning */
     };
-    const planGen = runCouncil(councilTopic, sessionModelId, [], ctx.runId, productLlm, ctx.respondToQuestion, ctx.respondToPreflight, ctx.processMessageFn ?? noopProcess, { skipClarification: true, cwd });
+    const planGen = runCouncil(councilTopic, sessionModelId, [], ctx.runId, productLlm, ctx.respondToQuestion, ctx.respondToPreflight, ctx.processMessageFn ?? noopProcess, { skipClarification: true, cwd, runDir });
     let planSynthesis = "";
     while (true) {
         const step = await planGen.next();
@@ -183,8 +226,24 @@ export async function* runSprint(args) {
         }
         yield step.value;
     }
+    // P4-C: close the planning phase row before opening implementation.
+    yield phaseDone({
+        phaseId: planPhaseId,
+        kind: "sprint_stage",
+        label: `Sprint ${sprintN} — Planning`,
+        startedAt: planStartedAt,
+    });
     // ── Step 4: Implement stage — pipe plan through host process loop ─────────
     yield { type: "content", content: `\n## Sprint ${sprintN} — Implementation\n` };
+    const implPhaseId = `sprint-${sprintN}-implementation`;
+    const implStartedAt = Date.now();
+    yield phaseStart({
+        phaseId: implPhaseId,
+        kind: "sprint_stage",
+        label: `Sprint ${sprintN} — Implementation`,
+        detail: planSynthesis.trim() ? "Orchestrator executing sprint plan" : "Skipped — no plan synthesis",
+        startedAt: implStartedAt,
+    });
     // 2.5b — implementation stage entry
     try {
         const _ar = globalThis.__muonroiAgentRuntime;
@@ -203,10 +262,55 @@ export async function* runSprint(args) {
         subtype: "sprint_stage",
         data: { sprintIndex: sprintN, stage: "implementation", runId: ctx.runId },
     });
-    if (ctx.processMessageFn && planSynthesis.trim()) {
-        const implGen = ctx.processMessageFn(planSynthesis);
-        for await (const chunk of implGen) {
-            yield chunk;
+    // C2: Pre-impl gate — read decisions.lock.md and prepend to implementation prompt.
+    // When lock file is missing (greenfield / no council with runDir), pass-through unchanged.
+    let implPrompt = planSynthesis;
+    try {
+        const lockContent = await readDecisionsLock(runDir);
+        if (lockContent) {
+            implPrompt = prependDecisionsLock(planSynthesis, lockContent);
+            yield {
+                type: "content",
+                content: "\n> [decisions.lock.md] Locked decisions prepended to implementation prompt.\n",
+            };
+        }
+    }
+    catch {
+        /* fail-open — lock read failure must not block implementation */
+    }
+    let implError = null;
+    if (ctx.processMessageFn && implPrompt.trim()) {
+        try {
+            const implGen = ctx.processMessageFn(implPrompt);
+            for await (const chunk of implGen) {
+                yield chunk;
+            }
+        }
+        catch (e) {
+            implError = e instanceof Error ? e.message : String(e);
+        }
+        finally {
+            // A3 FIX: phaseDone for implementation MUST always fire, even when
+            // processMessageFn throws mid-stream (e.g. /gsd executor fails after
+            // writing some files). Without the finally guard the TUI phase timeline
+            // shows "Implementation" stuck in "active" state forever.
+            if (implError) {
+                yield phaseError({
+                    phaseId: implPhaseId,
+                    kind: "sprint_stage",
+                    label: `Sprint ${sprintN} — Implementation`,
+                    startedAt: implStartedAt,
+                    errorMessage: implError,
+                });
+            }
+            else {
+                yield phaseDone({
+                    phaseId: implPhaseId,
+                    kind: "sprint_stage",
+                    label: `Sprint ${sprintN} — Implementation`,
+                    startedAt: implStartedAt,
+                });
+            }
         }
     }
     else {
@@ -214,9 +318,27 @@ export async function* runSprint(args) {
             type: "content",
             content: "\n> Implementation step skipped (no processMessageFn or empty plan).\n",
         };
+        yield phaseDone({
+            phaseId: implPhaseId,
+            kind: "sprint_stage",
+            label: `Sprint ${sprintN} — Implementation`,
+            startedAt: implStartedAt,
+        });
+    }
+    if (implError) {
+        throw new Error(implError);
     }
     // ── Step 5: Verify stage ──────────────────────────────────────────────────
     yield { type: "content", content: `\n## Sprint ${sprintN} — Verification\n` };
+    const verifyPhaseId = `sprint-${sprintN}-verification`;
+    const verifyStartedAt = Date.now();
+    yield phaseStart({
+        phaseId: verifyPhaseId,
+        kind: "sprint_stage",
+        label: `Sprint ${sprintN} — Verification`,
+        detail: "Running verify recipe",
+        startedAt: verifyStartedAt,
+    });
     // 2.5c — verification stage entry
     try {
         const _ar = globalThis.__muonroiAgentRuntime;
@@ -230,8 +352,45 @@ export async function* runSprint(args) {
         data: { sprintIndex: sprintN, stage: "verification", runId: ctx.runId },
     });
     const verifyResult = await runVerifyOrchestration(verifyAgent);
-    const verifyVerdict = parseVerifyResult(verifyResult);
+    yield phaseDone({
+        phaseId: verifyPhaseId,
+        kind: "sprint_stage",
+        label: `Sprint ${sprintN} — Verification`,
+        startedAt: verifyStartedAt,
+    });
+    let verifyVerdict = parseVerifyResult(verifyResult);
     const recipeFromVerify = verifyResult.verifyRecipe ?? verifyRecipe;
+    // Tier 3 — opt-in self-verify gate. Only fires when recipe PASSED and the
+    // sprint touched UI / harness watched surfaces. Failure downgrades the
+    // sprint verdict to FAIL so the loop iterates again with feedback.
+    // Default OFF; opt-in via MUONROI_SPRINT_SELF_VERIFY=1.
+    if (verifyVerdict === "PASS") {
+        try {
+            const { runSprintSelfVerify } = await import("./sprint-self-verify.js");
+            const sv = await runSprintSelfVerify({
+                repoRoot: cwd,
+                baseRef: "HEAD~1",
+            });
+            if (sv.ran && sv.verdict === "fail") {
+                verifyVerdict = "FAIL";
+                const tail = sv.detail ? `\n\n[self-verify] ${sv.detail}` : "";
+                verifyResult.error = (verifyResult.error ?? "") + tail;
+                yield {
+                    type: "content",
+                    content: `\n> [self-verify] Sprint ${sprintN} verdict downgraded to FAIL by Tier 1 self-QA (${sv.elapsedMs}ms).\n`,
+                };
+            }
+            else if (sv.ran && sv.verdict === "pass") {
+                yield {
+                    type: "content",
+                    content: `\n> [self-verify] Tier 1 PASS (${sv.elapsedMs}ms) — UI/harness regressions checked.\n`,
+                };
+            }
+        }
+        catch {
+            /* self-verify must NEVER block the sprint pipeline */
+        }
+    }
     // P3.3: Track repeating failures; push to EE judge-worker when count hits 3.
     if (verifyVerdict === "FAIL" || verifyVerdict === "ERROR") {
         const errorMessage = verifyResult.error?.trim() ? verifyResult.error : (verifyResult.output ?? "");
@@ -253,6 +412,15 @@ export async function* runSprint(args) {
     }
     // ── Step 6: Read current criteria + judge stage ──────────────────────────
     yield { type: "content", content: `\n## Sprint ${sprintN} — Judgment\n` };
+    const judgePhaseId = `sprint-${sprintN}-judgment`;
+    const judgeStartedAt = Date.now();
+    yield phaseStart({
+        phaseId: judgePhaseId,
+        kind: "sprint_stage",
+        label: `Sprint ${sprintN} — Judgment`,
+        detail: "Done-gate evaluation",
+        startedAt: judgeStartedAt,
+    });
     // 2.5d — judgment stage entry
     try {
         const _ar = globalThis.__muonroiAgentRuntime;
@@ -295,6 +463,14 @@ export async function* runSprint(args) {
         flowDir: ctx.flowDir,
         runId: ctx.runId,
     });
+    // P4-C: judgment phase complete — closing this row keeps the timeline tidy
+    // even if CB-2 halts below (the halt is a separate event).
+    yield phaseDone({
+        phaseId: judgePhaseId,
+        kind: "sprint_stage",
+        label: `Sprint ${sprintN} — Judgment`,
+        startedAt: judgeStartedAt,
+    });
     // ── Step 7: CB-2 oscillation check (now we know this sprint's score) ─────
     const cb2History = history.map((h) => ({ score: h.score ?? h.scoreAfter ?? 0 })).concat([{ score: verdict.score }]);
     const cb2 = CB2_oscillation(cb2History, sprintN);
@@ -350,6 +526,22 @@ export async function* runSprint(args) {
     const stateMap = (await readArtifact(runDir, "state.md")) ?? { preamble: "", sections: new Map() };
     stateMap.sections.set("Resume Digest", `Sprint: ${sprintN} | Stage: ${iter.stage} | Score: ${verdict.score.toFixed(2)} | Verify: ${verifyVerdict}`);
     await writeArtifact(runDir, "state.md", stateMap);
+    // Emit ProgressSnapshot on sprint boundary so the user sees rolling progress.
+    // Wrapped in try/catch — never crash sprint-runner because the snapshot failed.
+    try {
+        const backlogForSnap = await readBacklog(ctx.flowDir, ctx.runId);
+        const productSlug = backlogForSnap?.productSlug ?? ctx.runId;
+        const snapshot = await computeProgressSnapshot({
+            flowDir: ctx.flowDir,
+            runId: ctx.runId,
+            productSlug,
+        });
+        const snapshotMd = renderSnapshotMarkdown(snapshot);
+        yield { type: "content", content: `\n---\n${snapshotMd}\n` };
+    }
+    catch {
+        /* snapshot failure must never crash sprint-runner */
+    }
     // Per-role rolling memory (2KB hard cap, oldest-first truncation handled by helper)
     for (const [slot] of roleAssignments.entries()) {
         await appendRoleMemory(ctx.flowDir, ctx.runId, slot, sprintN, `Sprint ${sprintN}: verify=${verifyVerdict}, score=${verdict.score.toFixed(2)}, pass=${verdict.pass}`).catch(() => {

package/dist/src/product-loop/sprint-self-verify.d.ts

@@ -0,0 +1,54 @@
+/**
+ * src/product-loop/sprint-self-verify.ts
+ *
+ * Tier 3 — sprint pipeline integration of the self-QA harness.
+ *
+ * After the verification stage passes (recipe verdict = PASS), if the sprint
+ * touched UI / harness watched surfaces, spawn Tier 1 self-verify to catch
+ * lifecycle / modal / focus bugs that vitest cannot see. Result is ADDITIVE:
+ * a self-verify failure downgrades the sprint verdict to FAIL so the loop
+ * iterates again with the failure context in the carryOver feedback.
+ *
+ * Default OFF — opt-in via MUONROI_SPRINT_SELF_VERIFY=1. Off keeps the sprint
+ * loop fast and avoids the ~30s tax on every iteration during /ideal runs.
+ *
+ * Hook point: `src/product-loop/sprint-runner.ts` ~ line 425 (after
+ * `parseVerifyResult` if verdict === "PASS"). See CLAUDE.md §Tier 3 doc.
+ */
+export interface SprintSelfVerifyResult {
+    ran: boolean;
+    /** Reason the verifier did not run, when `ran === false`. */
+    skipReason?: "disabled" | "no-watched-changes" | "no-baseref" | "spawn-failed";
+    /** Verdict from self-verify when `ran === true`. */
+    verdict?: "pass" | "fail" | "inconclusive";
+    /** Markdown-formatted detail for inclusion in sprint feedback / verifyResult.error. */
+    detail?: string;
+    /** Wall-clock elapsed in ms. */
+    elapsedMs?: number;
+}
+export interface SprintSelfVerifyOpts {
+    /** Project root — used as cwd for git and the self-verify spawn. */
+    repoRoot: string;
+    /**
+     * Git ref to diff HEAD against. Typical caller passes `ctx.baseRef` or
+     * falls back to `origin/master`. When undefined, falls back to `HEAD~1`
+     * so a single-commit sprint still gets coverage.
+     */
+    baseRef?: string;
+    /** Max scenarios for the Tier 1 heuristic run. Defaults to 4. */
+    maxScenarios?: number;
+    /** Timeout for the self-verify child. Defaults to 90s. */
+    timeoutMs?: number;
+    /**
+     * Optional override for the env-var gate. Tests pass `true` to bypass the
+     * default-off behaviour without setting process.env.
+     */
+    forceEnable?: boolean;
+}
+/**
+ * Spawn `bun run src/index.ts self-verify --since <baseRef> --max <n> --no-emit --json`
+ * and parse the trailing JSON summary line.
+ *
+ * Returns the parsed verdict plus elapsed ms. Crash / timeout = inconclusive.
+ */
+export declare function runSprintSelfVerify(opts: SprintSelfVerifyOpts): Promise<SprintSelfVerifyResult>;