@oscharko-dev/keiko 0.1.0-beta.0

package/dist/workflows/bug-investigation/report.js

@@ -0,0 +1,151 @@
+// Report assembly and Markdown rendering (ADR-0009 D3). assembleBugReport composes the
+// JSON-serializable BugInvestigationReport from pipeline stage outputs, enforcing the STRUCTURAL
+// verified/hypothesis split: `verified` carries only facts the workflow established (patch validated,
+// patch applied, verification summary, parsed failure frames) and `hypothesis` carries the redacted,
+// explicitly-UNVERIFIED model output. ALL prose, the diff, the dry-run preview, frame paths, changed
+// paths, and nextActions are redacted via redact() here — defence in depth on top of upstream
+// redaction. renderBugMarkdownReport produces the CLI text path. Pure: no IO, no clock; the caller
+// injects durationMs and counters.
+import { redact } from "../../gateway/redaction.js";
+import { isElevatedReviewPath } from "./guard.js";
+const TEST_CASE_PREFIXES = ["test(", "it(", "describe("];
+// Best-effort count of added regression-test cases: added (`+`) lines whose trimmed text begins
+// with a known test-case opener. Not authoritative — informational only.
+function estimateRegressionCount(files) {
+    let count = 0;
+    for (const file of files) {
+        for (const hunk of file.hunks) {
+            for (const line of hunk.lines) {
+                if (!line.startsWith("+")) {
+                    continue;
+                }
+                const trimmed = line.slice(1).trimStart();
+                if (TEST_CASE_PREFIXES.some((prefix) => trimmed.startsWith(prefix))) {
+                    count += 1;
+                }
+            }
+        }
+    }
+    return count;
+}
+function toChangedFiles(files) {
+    return files.map((file) => ({
+        path: redact(file.path),
+        kind: file.kind,
+        addedLines: file.addedLines,
+        removedLines: file.removedLines,
+        elevatedReview: isElevatedReviewPath(file.path),
+    }));
+}
+function redactFrames(frames) {
+    return frames.map((frame) => frame.line === undefined
+        ? { file: redact(frame.file), line: undefined }
+        : { file: redact(frame.file), line: frame.line });
+}
+function redactHypothesis(hypothesis) {
+    return {
+        rootCause: redactOptional(hypothesis.rootCause),
+        regressionTestStrategy: redactOptional(hypothesis.regressionTestStrategy),
+        uncertainty: redactOptional(hypothesis.uncertainty),
+        confidence: hypothesis.confidence,
+    };
+}
+function redactOptional(value) {
+    return value === undefined ? undefined : redact(value);
+}
+export function assembleBugReport(parts) {
+    return {
+        workflowId: "bug-investigation",
+        status: parts.status,
+        modelId: parts.modelId,
+        durationMs: parts.durationMs,
+        verified: {
+            patchValidates: parts.patchValidates,
+            patchApplied: parts.patchApplied,
+            verification: parts.verification,
+            failureFrames: redactFrames(parts.failureFrames),
+        },
+        hypothesis: redactHypothesis(parts.hypothesis),
+        proposedDiff: redactOptional(parts.proposedDiff),
+        dryRunPreview: redactOptional(parts.dryRunPreview),
+        changedFiles: toChangedFiles(parts.patchFiles),
+        regressionCoverage: estimateRegressionCount(parts.patchFiles),
+        verificationSkipReason: redactOptional(parts.verificationSkipReason),
+        nextActions: parts.nextActions.map((action) => redact(action)),
+        failureReason: redactOptional(parts.failureReason),
+        modelCallCount: parts.modelCallCount,
+        patchRetryCount: parts.patchRetryCount,
+    };
+}
+// ─── Markdown rendering ──────────────────────────────────────────────────────────
+function sectionIf(heading, body) {
+    return body === undefined ? [] : [`## ${heading}`, body, ""];
+}
+function frameLines(report) {
+    if (report.verified.failureFrames.length === 0) {
+        return [];
+    }
+    const rows = report.verified.failureFrames.map((f) => f.line === undefined ? `- ${f.file}` : `- ${f.file}:${String(f.line)}`);
+    return ["## Failure locations (verified)", ...rows, ""];
+}
+function changedFileLines(report) {
+    if (report.changedFiles.length === 0) {
+        return [];
+    }
+    const rows = report.changedFiles.map((f) => {
+        const flag = f.elevatedReview ? " [elevated review]" : "";
+        return `- ${f.kind} ${f.path} (+${String(f.addedLines)} -${String(f.removedLines)})${flag}`;
+    });
+    return ["## Changed files (verified)", ...rows, ""];
+}
+function verificationLines(report) {
+    if (report.verified.verification !== undefined) {
+        return [
+            "## Verification (verified)",
+            `Status: ${report.verified.verification.overallStatus}`,
+            "",
+        ];
+    }
+    if (report.verificationSkipReason !== undefined) {
+        return ["## Verification (verified)", report.verificationSkipReason, ""];
+    }
+    return [];
+}
+function hypothesisLines(report) {
+    const h = report.hypothesis;
+    // Suppress the section entirely when the model produced no hypothesis (rejected/failed paths), so
+    // the rendered report does not show a bare "UNVERIFIED" header with no content.
+    const hasContent = h.rootCause !== undefined ||
+        h.regressionTestStrategy !== undefined ||
+        h.uncertainty !== undefined ||
+        h.confidence !== undefined;
+    if (!hasContent) {
+        return [];
+    }
+    return [
+        "## Hypothesis (UNVERIFIED — model output)",
+        ...sectionIf("Root cause", h.rootCause),
+        ...sectionIf("Regression test", h.regressionTestStrategy),
+        ...sectionIf("Uncertainty", h.uncertainty),
+        ...(h.confidence === undefined ? [] : [`Confidence: ${h.confidence}`, ""]),
+    ];
+}
+// A human-readable Markdown report for the CLI text path. Every field is already redacted by
+// assembleBugReport, so rendering is plain string composition. Verified facts and the UNVERIFIED
+// model hypothesis are clearly separated (AC #7).
+export function renderBugMarkdownReport(report) {
+    return [
+        `# Bug investigation: ${report.status}`,
+        `Model: ${report.modelId} · ${String(report.durationMs)}ms · ` +
+            `${String(report.modelCallCount)} model call(s) · ${String(report.patchRetryCount)} retry(ies)`,
+        "",
+        ...frameLines(report),
+        ...changedFileLines(report),
+        ...verificationLines(report),
+        ...hypothesisLines(report),
+        ...sectionIf("Failure", report.failureReason),
+        ...(report.nextActions.length > 0
+            ? ["## Next actions", ...report.nextActions.map((a) => `- ${a}`), ""]
+            : []),
+    ].join("\n");
+}

package/dist/workflows/bug-investigation/stages.d.ts

@@ -0,0 +1,13 @@
+import type { WorkspaceInfo } from "../../workspace/index.js";
+import { type AcceptedBugPatch, type BugModelLoopResult, type BugRunState } from "./internal.js";
+import type { BugInvestigationReport, FailureEvidence, Hypothesis } from "./types.js";
+export declare function rejectedReport(state: BugRunState, loop: BugModelLoopResult, evidence: FailureEvidence): BugInvestigationReport;
+export declare function insufficientInputReport(state: BugRunState): BugInvestigationReport;
+export declare function investigationOnlyReport(state: BugRunState, loop: BugModelLoopResult, hypothesis: Hypothesis, evidence: FailureEvidence): BugInvestigationReport;
+export declare function dryRunReport(state: BugRunState, loop: BugModelLoopResult, accepted: AcceptedBugPatch, evidence: FailureEvidence): BugInvestigationReport;
+export declare function cancelledReport(state: BugRunState, loop: BugModelLoopResult, accepted: AcceptedBugPatch | undefined, evidence: FailureEvidence, applied?: {
+    readonly changedFiles: readonly string[];
+}): BugInvestigationReport;
+export declare function failedReport(state: BugRunState, error: unknown): BugInvestigationReport;
+export declare function emitCompleted(state: BugRunState, report: BugInvestigationReport): BugInvestigationReport;
+export declare function finishPipeline(state: BugRunState, workspace: WorkspaceInfo, loop: BugModelLoopResult, evidence: FailureEvidence): Promise<BugInvestigationReport>;

package/dist/workflows/bug-investigation/stages.js

@@ -0,0 +1,242 @@
+// Terminal-report stages (ADR-0009 D3/D4/D11). Each function maps a pipeline outcome —
+// fix-proposed (dry-run), fix-applied, investigation-only, rejected, cancelled, or failed — to the
+// redacted BugInvestigationReport via assembleBugReport. applyPatch (apply mode) is the one IO
+// boundary here and is fail-closed in #6 (applyEnabled gates the write); it receives the SAME
+// tighter PatchLimits as validatePatch (D6 bound 1, defence-in-depth re-validation). finishPipeline
+// selects the branch; emitCompleted stamps the terminal event. All redaction is inside assembleBugReport.
+import { redact } from "../../gateway/redaction.js";
+import { applyPatch, CommandCancelledError, renderDryRun, } from "../../tools/index.js";
+import { nodeWorkspaceFs } from "../../workspace/fs.js";
+import { assembleBugReport } from "./report.js";
+import { runBugVerification } from "./verify-stage.js";
+import { investigationNextActions, nextActionsFor, patchLimitsFrom, } from "./internal.js";
+import { isElevatedReviewPath } from "./guard.js";
+const EMPTY_HYPOTHESIS = {
+    rootCause: undefined,
+    regressionTestStrategy: undefined,
+    uncertainty: undefined,
+    confidence: undefined,
+};
+function elevatedPaths(accepted) {
+    return accepted.validation.files.map((f) => f.path).filter((p) => isElevatedReviewPath(p));
+}
+export function rejectedReport(state, loop, evidence) {
+    return assembleBugReport({
+        status: "rejected",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: [],
+        patchValidates: false,
+        patchApplied: false,
+        verification: undefined,
+        failureFrames: evidence.frames,
+        hypothesis: EMPTY_HYPOTHESIS,
+        proposedDiff: undefined,
+        dryRunPreview: undefined,
+        verificationSkipReason: undefined,
+        nextActions: [
+            `The model did not produce an in-scope fix (${loop.lastRejectionCode ?? "insufficient evidence"})`,
+        ],
+        failureReason: undefined,
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+// Insufficient-input rejection: returned by the intake precondition before any model call.
+export function insufficientInputReport(state) {
+    return assembleBugReport({
+        status: "rejected",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: [],
+        patchValidates: false,
+        patchApplied: false,
+        verification: undefined,
+        failureFrames: [],
+        hypothesis: EMPTY_HYPOTHESIS,
+        proposedDiff: undefined,
+        dryRunPreview: undefined,
+        verificationSkipReason: undefined,
+        nextActions: [
+            "Provide at least one of: a description, failing output, a stack trace, or suspected target files",
+        ],
+        failureReason: undefined,
+        modelCallCount: 0,
+        patchRetryCount: 0,
+    });
+}
+export function investigationOnlyReport(state, loop, hypothesis, evidence) {
+    return assembleBugReport({
+        status: "investigation-only",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: [],
+        patchValidates: false,
+        patchApplied: false,
+        verification: undefined,
+        failureFrames: evidence.frames,
+        hypothesis,
+        proposedDiff: undefined,
+        dryRunPreview: undefined,
+        verificationSkipReason: "verification skipped: no patch produced (investigation-only)",
+        nextActions: investigationNextActions(),
+        failureReason: undefined,
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+export function dryRunReport(state, loop, accepted, evidence) {
+    const files = accepted.validation.files.map((f) => f.path);
+    return assembleBugReport({
+        status: "fix-proposed",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: accepted.validation.files,
+        patchValidates: true,
+        patchApplied: false,
+        verification: undefined,
+        failureFrames: evidence.frames,
+        hypothesis: accepted.hypothesis,
+        proposedDiff: accepted.diff,
+        dryRunPreview: renderDryRun(accepted.validation),
+        verificationSkipReason: "verification skipped: dry-run, no files written",
+        nextActions: nextActionsFor(false, files, elevatedPaths(accepted)),
+        failureReason: undefined,
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+// `applied` is set ONLY on a post-apply abort: the patch is already on disk, so the report (and the
+// #10 ledger record) must reflect that (patchApplied: true) rather than hard-coding false. A
+// pre-apply abort passes applied === undefined and stays patchApplied: false.
+export function cancelledReport(state, loop, accepted, evidence, applied) {
+    const nextActions = applied === undefined
+        ? ["The workflow was cancelled before completion"]
+        : [
+            `The fix was applied to ${applied.changedFiles[0] ?? "disk"} but the workflow was cancelled before verification completed`,
+            "Run `keiko verify` to confirm the suite",
+        ];
+    return assembleBugReport({
+        status: "cancelled",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: accepted?.validation.files ?? [],
+        patchValidates: accepted !== undefined,
+        patchApplied: applied !== undefined,
+        verification: undefined,
+        failureFrames: evidence.frames,
+        hypothesis: accepted?.hypothesis ?? EMPTY_HYPOTHESIS,
+        proposedDiff: accepted?.diff,
+        dryRunPreview: accepted === undefined ? undefined : renderDryRun(accepted.validation),
+        verificationSkipReason: "verification skipped: cancelled",
+        nextActions,
+        failureReason: undefined,
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+export function failedReport(state, error) {
+    const message = redact(error instanceof Error ? error.message : "unexpected workflow failure");
+    const errorCode = error instanceof Error ? error.name : "UNKNOWN";
+    state.emitter.emit({ type: "bug:failed", errorCode, message });
+    return assembleBugReport({
+        status: "failed",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: [],
+        patchValidates: false,
+        patchApplied: false,
+        verification: undefined,
+        failureFrames: [],
+        hypothesis: EMPTY_HYPOTHESIS,
+        proposedDiff: undefined,
+        dryRunPreview: undefined,
+        verificationSkipReason: undefined,
+        nextActions: [`Inspect the error and retry: ${message}`],
+        failureReason: message,
+        modelCallCount: state.progress.modelCallCount,
+        patchRetryCount: state.progress.patchRetryCount,
+    });
+}
+function applyBugPatch(state, workspace, accepted) {
+    const fs = state.deps.fs ?? nodeWorkspaceFs;
+    const applyResult = applyPatch(workspace, accepted.diff, {
+        applyEnabled: true,
+        signal: state.signal,
+        fs,
+        limits: patchLimitsFrom(state.limits),
+        ...(state.deps.writer === undefined ? {} : { writer: state.deps.writer }),
+    });
+    return { fs, applyResult };
+}
+async function applyAndVerify(state, workspace, loop, accepted, evidence) {
+    let applyResult;
+    let fs;
+    try {
+        ({ fs, applyResult } = applyBugPatch(state, workspace, accepted));
+    }
+    catch (error) {
+        if (error instanceof CommandCancelledError) {
+            return cancelledReport(state, loop, accepted, evidence);
+        }
+        throw error;
+    }
+    state.emitter.emit({
+        type: "bug:patch:applied",
+        changedFiles: applyResult.changedFiles.length,
+        created: applyResult.created.length,
+        deleted: applyResult.deleted.length,
+    });
+    if (state.signal.aborted) {
+        // Post-apply abort: the patch is already on disk, so the report must reflect patchApplied: true
+        // (M1) — the #10 ledger record must match the real filesystem state.
+        return cancelledReport(state, loop, accepted, evidence, {
+            changedFiles: applyResult.changedFiles,
+        });
+    }
+    const verification = await runBugVerification(state, workspace, accepted.validation.files, fs);
+    return assembleBugReport({
+        status: "fix-applied",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: accepted.validation.files,
+        patchValidates: true,
+        patchApplied: true,
+        verification: verification.summary,
+        failureFrames: evidence.frames,
+        hypothesis: accepted.hypothesis,
+        proposedDiff: accepted.diff,
+        dryRunPreview: renderDryRun(accepted.validation),
+        verificationSkipReason: verification.skipReason,
+        nextActions: nextActionsFor(true, applyResult.changedFiles, elevatedPaths(accepted)),
+        failureReason: undefined,
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+export function emitCompleted(state, report) {
+    state.emitter.emit({
+        type: "bug:completed",
+        status: report.status,
+        durationMs: report.durationMs,
+    });
+    return report;
+}
+// Selects the terminal branch from the model-loop result: investigation-only (hypothesis, no
+// patch), rejected (nothing usable), cancelled (abort before apply), apply+verify (apply mode), or
+// dry-run (default).
+export async function finishPipeline(state, workspace, loop, evidence) {
+    if (loop.accepted === undefined) {
+        if (loop.investigationOnly !== undefined) {
+            return investigationOnlyReport(state, loop, loop.investigationOnly, evidence);
+        }
+        return rejectedReport(state, loop, evidence);
+    }
+    if (state.signal.aborted) {
+        return cancelledReport(state, loop, loop.accepted, evidence);
+    }
+    if (state.input.apply === true) {
+        return applyAndVerify(state, workspace, loop, loop.accepted, evidence);
+    }
+    return dryRunReport(state, loop, loop.accepted, evidence);
+}

package/dist/workflows/bug-investigation/types.d.ts

@@ -0,0 +1,91 @@
+import type { ModelPort } from "../../harness/ports.js";
+import type { PatchChangeKind, SpawnFn, WorkspaceWriter } from "../../tools/index.js";
+import type { WorkspaceFs } from "../../workspace/index.js";
+import type { VerificationAuditSummary } from "../../verification/index.js";
+import type { BugWorkflowEventSink } from "./events.js";
+export type BugWorkflowStatus = "fix-applied" | "fix-proposed" | "investigation-only" | "rejected" | "cancelled" | "failed";
+export interface FailureFrame {
+    readonly file: string;
+    readonly line?: number | undefined;
+}
+export interface FailureEvidence {
+    readonly frames: readonly FailureFrame[];
+    readonly messages: readonly string[];
+}
+export interface BugWorkflowLimits {
+    readonly maxModelCalls: number;
+    readonly maxRetries: number;
+    readonly contextBudgetBytes: number;
+    readonly maxBytesPerFile: number;
+    readonly maxFilesChanged: number;
+    readonly maxChangedLines: number;
+    readonly maxPatchBytes: number;
+}
+export declare const DEFAULT_BUG_WORKFLOW_LIMITS: BugWorkflowLimits;
+export interface BugReportInput {
+    readonly description?: string | undefined;
+    readonly failingOutput?: string | undefined;
+    readonly stackTrace?: string | undefined;
+    readonly targetFiles?: readonly string[] | undefined;
+}
+export interface BugInvestigationInput {
+    readonly workspaceRoot: string;
+    readonly report: BugReportInput;
+    readonly apply?: boolean | undefined;
+    readonly modelId: string;
+    readonly limits?: Partial<BugWorkflowLimits> | undefined;
+}
+export interface BugInvestigationDeps {
+    readonly model: ModelPort;
+    readonly fs?: WorkspaceFs | undefined;
+    readonly writer?: WorkspaceWriter | undefined;
+    readonly spawn?: SpawnFn | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly idSource?: (() => string) | undefined;
+    readonly sink?: BugWorkflowEventSink | undefined;
+    readonly processEnv?: NodeJS.ProcessEnv | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface VerifiedFindings {
+    readonly patchValidates: boolean;
+    readonly patchApplied: boolean;
+    readonly verification?: VerificationAuditSummary | undefined;
+    readonly failureFrames: readonly FailureFrame[];
+}
+export interface Hypothesis {
+    readonly rootCause?: string | undefined;
+    readonly regressionTestStrategy?: string | undefined;
+    readonly uncertainty?: string | undefined;
+    readonly confidence?: "low" | "medium" | "high" | undefined;
+}
+export interface ChangedFile {
+    readonly path: string;
+    readonly kind: PatchChangeKind;
+    readonly addedLines: number;
+    readonly removedLines: number;
+    readonly elevatedReview: boolean;
+}
+export interface BugInvestigationReport {
+    readonly workflowId: "bug-investigation";
+    readonly status: BugWorkflowStatus;
+    readonly modelId: string;
+    readonly durationMs: number;
+    readonly verified: VerifiedFindings;
+    readonly hypothesis: Hypothesis;
+    readonly proposedDiff?: string | undefined;
+    readonly dryRunPreview?: string | undefined;
+    readonly changedFiles: readonly ChangedFile[];
+    readonly regressionCoverage: number;
+    readonly verificationSkipReason?: string | undefined;
+    readonly nextActions: readonly string[];
+    readonly failureReason?: string | undefined;
+    readonly modelCallCount: number;
+    readonly patchRetryCount: number;
+}
+export interface ParsedBugOutput {
+    readonly diff: string;
+    readonly rootCause: string | undefined;
+    readonly regressionTestStrategy: string | undefined;
+    readonly uncertainty: string | undefined;
+    readonly confidence: "low" | "medium" | "high" | undefined;
+}

package/dist/workflows/bug-investigation/types.js

@@ -0,0 +1,14 @@
+// All interfaces, type aliases, and frozen constant tables for the bug-investigation workflow
+// (ADR-0009 D2/D3/D4/D7/D13). No runtime logic beyond the frozen tables. `readonly` everywhere;
+// optional props are `| undefined` because exactOptionalPropertyTypes is on. Every report shape is
+// plain JSON-serializable so the #10 audit ledger can persist it. Names are DISTINCT from the
+// unit-test workflow's (ADR-0009 D5) because both barrels are re-exported from the package root.
+export const DEFAULT_BUG_WORKFLOW_LIMITS = {
+    maxModelCalls: 3,
+    maxRetries: 2,
+    contextBudgetBytes: 65_536,
+    maxBytesPerFile: 8_192,
+    maxFilesChanged: 10,
+    maxChangedLines: 300,
+    maxPatchBytes: 65_536,
+};

package/dist/workflows/bug-investigation/verify-stage.d.ts

@@ -0,0 +1,10 @@
+import { type PatchFileChange } from "../../tools/index.js";
+import { type WorkspaceFs, type WorkspaceInfo } from "../../workspace/index.js";
+import { type VerificationAuditSummary } from "../../verification/index.js";
+import type { BugRunState } from "./internal.js";
+export declare const SKIP_UNRESOLVED = "verification skipped: framework unknown or no test files resolved";
+export interface BugVerificationOutcome {
+    readonly summary: VerificationAuditSummary | undefined;
+    readonly skipReason: string | undefined;
+}
+export declare function runBugVerification(state: BugRunState, workspace: WorkspaceInfo, changedFiles: readonly PatchFileChange[], fs: WorkspaceFs): Promise<BugVerificationOutcome>;

package/dist/workflows/bug-investigation/verify-stage.js

@@ -0,0 +1,91 @@
+// The verification stage (ADR-0009 D11). Runs ONLY after a successful apply: it resolves a
+// verification plan by deriving the just-fixed/added tests from the changed SOURCE files via #7
+// resolveTargetedTests (so it finds the sibling/mirrored test incl. the just-added regression
+// test), falling back to the full `test` script, and records an explicit skip reason when neither
+// resolves or the framework is unknown. Verification reuses the #7 orchestrator unchanged; this
+// stage only wires the plan and projects an output-text-free audit summary. DEFERRED (D11): a
+// pre-patch reproduction baseline — Wave-1 verifies only the post-apply state.
+import { nodeSpawnFn } from "../../tools/index.js";
+import {} from "../../workspace/index.js";
+import { buildVerificationPlan, detectScripts, resolveTargetedTests, runVerification, summarizeForAudit, DEFAULT_VERIFICATION_LIMITS, } from "../../verification/index.js";
+import { isSensitivePath } from "./guard.js";
+export const SKIP_UNRESOLVED = "verification skipped: framework unknown or no test files resolved";
+// The non-test source files the patch changed — passed to resolveTargetedTests so it can find the
+// associated tests (incl. the just-added regression test). We approximate "source" as any changed
+// path that is not itself a test file (basename marks .test/.spec) and not a sensitive path.
+function changedSourceFiles(files) {
+    return files.map((f) => f.path).filter((path) => !isSensitivePath(path) && !isTestFile(path));
+}
+function changedTestFiles(files) {
+    return files.map((f) => f.path).filter((path) => !isSensitivePath(path) && isTestFile(path));
+}
+function isTestFile(path) {
+    const slash = path.lastIndexOf("/");
+    const base = slash === -1 ? path : path.slice(slash + 1);
+    const segments = base.split(".");
+    return segments.includes("test") || segments.includes("spec");
+}
+function buildPlanFallback(workspace, fs) {
+    const catalog = detectScripts(workspace, fs);
+    return buildVerificationPlan(workspace, catalog, { only: ["test"] }, fs);
+}
+function targetedChangedTests(workspace, testFiles) {
+    if (testFiles.length === 0) {
+        return undefined;
+    }
+    if (workspace.testFramework === "vitest") {
+        return {
+            kind: "targeted-test",
+            scriptName: undefined,
+            command: "npx",
+            args: ["vitest", "run", ...testFiles],
+            limits: DEFAULT_VERIFICATION_LIMITS,
+        };
+    }
+    if (workspace.testFramework === "jest") {
+        return {
+            kind: "targeted-test",
+            scriptName: undefined,
+            command: "npx",
+            args: ["jest", ...testFiles],
+            limits: DEFAULT_VERIFICATION_LIMITS,
+        };
+    }
+    return undefined;
+}
+function resolveVerificationPlan(workspace, changedFiles, fs) {
+    const directTests = targetedChangedTests(workspace, changedTestFiles(changedFiles));
+    if (directTests !== undefined) {
+        return { workspaceRoot: workspace.root, steps: [directTests] };
+    }
+    const targeted = resolveTargetedTests(workspace, changedSourceFiles(changedFiles), fs, DEFAULT_VERIFICATION_LIMITS);
+    if (targeted.length > 0) {
+        return { workspaceRoot: workspace.root, steps: targeted };
+    }
+    const fallback = buildPlanFallback(workspace, fs);
+    const runnable = fallback.steps.filter((step) => step.skipReason === undefined);
+    return runnable.length > 0 ? { workspaceRoot: workspace.root, steps: runnable } : undefined;
+}
+export async function runBugVerification(state, workspace, changedFiles, fs) {
+    const plan = resolveVerificationPlan(workspace, changedFiles, fs);
+    if (plan === undefined) {
+        return { summary: undefined, skipReason: SKIP_UNRESOLVED };
+    }
+    const report = await runVerification(plan, {
+        workspace,
+        signal: state.signal,
+        spawn: state.deps.spawn ?? nodeSpawnFn,
+        processEnv: state.deps.processEnv ?? process.env,
+        now: state.now,
+        fs,
+    });
+    const summary = summarizeForAudit(report);
+    state.emitter.emit({
+        type: "bug:verification:result",
+        overallStatus: summary.overallStatus,
+        stepCount: summary.results.length,
+        passedCount: summary.results.filter((r) => r.status === "passed").length,
+        durationMs: summary.durationMs,
+    });
+    return { summary, skipReason: undefined };
+}

package/dist/workflows/bug-investigation/workflow.d.ts

@@ -0,0 +1,2 @@
+import type { BugInvestigationDeps, BugInvestigationInput, BugInvestigationReport } from "./types.js";
+export declare function investigateBug(input: BugInvestigationInput, deps: BugInvestigationDeps): Promise<BugInvestigationReport>;