codecartographer-pi 0.23.0 → 0.24.0

package/.codecarto/broadside/SKILL.md

@@ -26,7 +26,21 @@ not replace any phase; it tells phases where to look.
 
 ## Reading a Broad-Side run
 
-1. Read `synthesis.md` first. It carries the executive summary, severity counts,
+0. If `verified.md` exists, read it first. A verification pass
+   (`codecarto_broadside {action: "verify"}`, `/codecarto-broadside verify`)
+   has read the top defect and security findings against the real source with
+   read-only tools and given each a verdict: **confirmed** (a reachable
+   failure, with the input or call site that triggers it), **not-a-defect**
+   (the claim is literally true of the code but nothing can reach the failure
+   it describes), **discarded** (the claim is wrong about the code, with the
+   guard or line that shows it), or **unclear**. Start from the confirmed
+   ones; treat a discarded one as answered unless the reasoning is thin.
+   Measured on this repository, the top twelve findings by severity were two
+   real defects and ten that a look at the guard, the caller, or the tsconfig
+   dismissed — the pass agreed with a reviewer on all twelve for about a cent
+   a finding. A confirmed verdict is still a model's reading: a strong lead for
+   a human's next look, not a validated claim.
+1. Read `synthesis.md`. It carries the executive summary, severity counts,
    the top cross-lens findings, and per-module risk levels.
 2. Read `triage.md` for the work order: each lead scored by impact ×
    difficulty with a P0–P3 priority and an effort estimate. It is a starting
@@ -66,6 +80,7 @@ Broad-Side is an executable-surface feature. On the Pi extension:
 /codecarto-broadside collect            # poll, save, synthesize
 /codecarto-broadside status             # show recorded runs
 /codecarto-broadside models             # compare batch models
+/codecarto-broadside verify --top=10    # read the top findings against the source
 ```
 
 On the MCP server:
@@ -75,6 +90,7 @@ codecarto_broadside {cwd, action: "submit", lenses: [...]}   # fire the batches
 codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize
 codecarto_broadside {cwd, action: "status"}                   # show recorded runs
 codecarto_broadside {cwd, action: "models"}                   # compare batch models
+codecarto_broadside {cwd, action: "verify", top: 10}          # read the top findings against the source
 ```
 
 The `models` action lists every `:batch` variant on OpenRouter — pricing per
@@ -105,6 +121,18 @@ Collect runs two cross-lens post-passes by default: **synthesis** (the
 executive report) and **triage** (the prioritized work order). Pass
 `include_synthesis: false` or `include_triage: false` on collect to skip one.
 
+`verify` is the third pass, run separately after collect because it is
+sync-priced rather than batch-priced: for each of the top `top` findings
+(default 10, most severe first) of the defect and security lenses, one chat
+completion on the run's model without its `:batch` suffix (`model` overrides),
+with three read-only tools confined to the repository's source files —
+`read_file` by line range, `grep`, `list_dir` — at most eight tool calls, low
+reasoning effort, then a verdict. It writes `verified.md` and `verified.json`
+beside `triage.md` and records the pass on the run. `max_cost` is a running
+cap here, since a sync call's cost is known only when it returns: the pass
+stops before the next finding once the calls so far have reached it and
+reports `partial`. About a cent a finding on the default model.
+
 Two caveats apply to any model you pick. The `models` action lists every id
 OpenRouter advertises a `:batch` variant for, and many of those variants do not
 exist — submitting one returns `does not have a :batch endpoint`, with nothing in

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.23.0
+scaffold_version: 0.24.0

package/README.md

@@ -394,13 +394,16 @@ codecarto_broadside {cwd, action: "models"}                   # compare batch mo
 codecarto_broadside {cwd, action: "submit", lenses: [...]}    # fire the batches, priced first
 codecarto_broadside {cwd, action: "status"}                   # what is in flight
 codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize, triage
+codecarto_broadside {cwd, action: "verify", top: 10}          # read the top findings against the source
 ```
 
+A third action, `verify`, reads the top defect and security findings of a collected run against the real source — one sync-priced call each with read-only tools (`read_file`, `grep`, `list_dir`) confined to the repository — and writes `verified.md` with a verdict per finding: **confirmed** (a reachable failure, with the trigger), **not-a-defect**, **discarded**, or **unclear**. Measured on this repository, the top twelve findings by severity were two real defects and ten claims a look at the guard or the caller dismissed; the pass agreed with a reviewer on all twelve for a cent a finding. Read `verified.md` before `triage.md`.
+
 Submit and collect are separate because batch jobs routinely take tens of minutes; collect is resumable and picks up whatever is still in flight (`wait_seconds: 0`, the default, polls once and returns), and two collects on one run — a retried tool call, a second session — never pay for the synthesis, triage, or truncation retry twice: each is claimed in the run's state before it is submitted, and a collect whose client has gone away stops polling and submits nothing further. Submit prices the run from the collected file sizes against the model's live per-token pricing (cached 24h) and refuses when the estimate exceeds `max_cost` — $1.00 unless the config or the call sets another value, `0` for no limit — unless `force: true` is passed — a pre-flight estimate, not a runtime stop. Actual spend lands in each run's `run-meta.json`.
 
 Repository defaults live in `.codecarto/broadside/config.yaml` (`model`, `api_key`, `default_lenses`, `max_cost`, `pricing` overrides, `lens_models`, `incremental`, `retry_truncated`, `include_synthesis`, `include_triage`, `wait_seconds`); an explicit tool parameter always wins. `lens_models` routes individual lenses to their own batch model — a stronger model changes security and defect findings far more than it changes an architecture map — and each override is priced, capability-checked, and clamped exactly like the default, with the estimate broken out per lens so a mixed-model run cannot be approved without seeing which lens costs what. CodeCartographer ships no stronger default: which model earns its price depends on your repository and budget, so compare candidates with the `models` action and choose — for one run with the `model` and `lens_models` parameters (Pi: `--model=ID`, `--lens-model=LENS:ID`), or for the repository in `config.yaml`. The `models` listing is advisory: OpenRouter's catalog returns a `:batch` id for some models its Batch API then refuses (`does not have a :batch endpoint`), at no cost, and nothing in the catalog tells them apart — so the listing tags the ids this repository's own submits have seen accepted or refused, and a refused lens says why in the submit report. `codecarto_skill {cwd, name: "broadside"}` returns the reading guide for a completed run, and unlike post-pipeline skills it is not gated on a finished pipeline.
 
-On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models] [lenses…] [--model=ID] [--lens-model=LENS:ID]`, with tab-completion for actions, lens names, and flags and live per-lens progress while batches poll. The two surfaces differ in one deliberate place: MCP cannot ask a human, so it refuses a run over `max_cost` until you pass `force`; Pi shows the per-lens breakdown and asks, and your approval *is* the force flag. Neither surface takes an API key as a command argument — a key typed into a slash command lands in the session transcript.
+On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models|verify] [lenses…] [--model=ID] [--lens-model=LENS:ID] [--top=N]`, with tab-completion for actions, lens names, and flags and live per-lens progress while batches poll. The two surfaces differ in one deliberate place: MCP cannot ask a human, so it refuses a run over `max_cost` until you pass `force`; Pi shows the per-lens breakdown and asks, and your approval *is* the force flag. Neither surface takes an API key as a command argument — a key typed into a slash command lands in the session transcript.
 
 Broad-Side needs runtime code, so firing a run is an executable-surface feature: Pi and MCP have it, the pure drop-in template does not (it carries only the reading guide).
 

package/agent-skill/codecartographer/references/broadside.md

@@ -95,7 +95,11 @@ Two more economies worth knowing:
 
 ## Reading a run
 
-Results land in `.codecarto/broadside/<run>/`. Read them in this order:
+Results land in `.codecarto/broadside/<run>/`. If `verified.md` is there, read
+it before anything else: `action: "verify"` has read the top defect and
+security findings against the source with read-only tools and given each a
+verdict (confirmed with its trigger, not-a-defect, discarded with the guard
+that shows it, unclear). Then, in this order:
 
 1. `synthesis.md` — executive summary, severity counts, top cross-lens
    findings, per-module risk.

package/dist/core/broadside-verify.d.ts

@@ -0,0 +1,95 @@
+import { type BroadsideLensId, type BroadsideVerifyEntry, type FetchLike, type StoredLensResult } from "./broadside.ts";
+export declare const BROADSIDE_CHAT_URL = "https://openrouter.ai/api/v1/chat/completions";
+/** How many findings `verify` reads by default, most severe first. */
+export declare const BROADSIDE_VERIFY_DEFAULT_TOP = 10;
+/** Tool calls one finding may spend before it must answer. */
+export declare const BROADSIDE_VERIFY_MAX_TOOL_CALLS = 8;
+/** The lenses whose findings carry a file:line and a claim to check. */
+export declare const BROADSIDE_VERIFIABLE_LENSES: readonly BroadsideLensId[];
+export type VerifyVerdict = "confirmed" | "not-a-defect" | "discarded" | "unclear";
+export type VerifiedFinding = {
+    index: number;
+    lensId: BroadsideLensId;
+    customId: string;
+    severity: string;
+    title: string;
+    location: string;
+    verdict: VerifyVerdict | "error";
+    confidence: string;
+    evidence: Array<{
+        file: string;
+        lines: string;
+        note: string;
+    }>;
+    reasoning: string;
+    toolCalls: number;
+    cost: number;
+};
+export type BroadsideVerifyResult = {
+    runId: string;
+    outputDir: string;
+    model: string;
+    status: BroadsideVerifyEntry["status"];
+    /** How many findings the run had in the verifiable lenses. */
+    candidates: number;
+    findings: VerifiedFinding[];
+    totalCost: number;
+    /** Set when the cost cap stopped the pass before every selected finding was read. */
+    stoppedByCost?: boolean;
+};
+type CandidateFinding = {
+    lensId: BroadsideLensId;
+    customId: string;
+    severity: string;
+    title: string;
+    location: string;
+    description: string;
+    pattern: string;
+};
+/** The sync-priced id behind a `:batch` model id (`vendor/name:batch` → `vendor/name`). */
+export declare function syncModelFor(batchModel: string): string;
+/** The findings a run's saved lens results carry, most severe first. */
+export declare function rankVerifiableFindings(stored: StoredLensResult[]): CandidateFinding[];
+export type RepoReader = {
+    readFile(path: string, startLine?: number, endLine?: number): Promise<string>;
+    grep(pattern: string, pathPrefix?: string): Promise<string>;
+    listDir(path: string): Promise<string>;
+};
+/**
+ * Three read-only tools over the repository's own file list — the same
+ * listing the lenses scan (tracked and untracked, ignore rules applied) minus
+ * everything {@link isSlurpable} keeps out of a lens: credential stores, build
+ * output, binaries. A path outside the repository, or one the listing does
+ * not contain, is an error the model sees, not a read.
+ */
+export declare function createRepoReader(cwd: string): Promise<RepoReader>;
+/**
+ * The rubric. The order is deliberate — it is the order a reviewer settles a
+ * claim in — and `not-a-defect` is the verdict that separates "the code does
+ * what the claim says" from "and that is a bug": without it, a cast every
+ * caller satisfies gets confirmed because it is literally there.
+ */
+export declare const BROADSIDE_VERIFY_SYSTEM_PROMPT: string;
+/** Verify one finding: up to the tool budget, then a verdict. */
+export declare function verifyFinding(finding: CandidateFinding, index: number, reader: RepoReader, apiKey: string, model: string, fetcher: FetchLike): Promise<Omit<VerifiedFinding, "index" | "lensId" | "customId" | "severity" | "title" | "location">>;
+/**
+ * Verify the top findings of a collected run against the repository.
+ *
+ * `maxCost` is a running cap, not a pre-flight estimate: a sync call's cost
+ * is only known when it returns, so the pass stops *before* starting the next
+ * finding once the cap is reached and reports `partial`. On the default
+ * model a finding costs about a cent.
+ */
+export declare function runBroadsideVerify(cwd: string, apiKey: string, opts?: {
+    runId?: string;
+    top?: number;
+    model?: string;
+    /** USD; 0 means no limit. */
+    maxCost?: number;
+    fetcher?: FetchLike;
+    signal?: AbortSignal;
+    onProgress?: (finding: VerifiedFinding) => void;
+}): Promise<BroadsideVerifyResult>;
+export declare function renderVerifiedMarkdown(result: BroadsideVerifyResult): string;
+export declare function verifyResultText(result: BroadsideVerifyResult): string;
+export {};

package/dist/core/broadside-verify.js

@@ -0,0 +1,433 @@
+// Broad-Side verification pass (#143): the hybrid the roadmap kept coming
+// back to. The batch sweep is cheap and reads files without being able to
+// look anything up, and its measured weakness is precision, not coverage —
+// on this repository the top twelve findings by severity were two real
+// defects and ten claims that a look at the guard, the caller, or the
+// tsconfig would have dismissed. So after collect, one sync-priced call per
+// finding, with three read-only tools confined to the repository, reads the
+// cited code and says whether the failure is reachable.
+//
+// Measured on 2026-09-13 (the #143 comparison run): twelve findings, the
+// rubric below, `google/gemini-3.7-flash` at low reasoning effort —
+// twelve-for-twelve agreement with a reviewer's ground truth, precision of
+// the confirmed set from 17% to 100%, both true findings kept, $0.13 in all
+// (about a cent a finding). The rubric mattered more than the model: a first
+// draft without the `not-a-defect` verdict "confirmed" two type casts that
+// every caller satisfies, because they were literally true of the code.
+//
+// Read-only on purpose. A tool-using pass that could mutate would need the
+// headless-agent retry rule (retry only before the first tool call); one
+// that only reads keeps the batch property that re-running is always safe.
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { BROADSIDE_DIR, BROADSIDE_LENS_IDS, broadsideDirFor, defaultReasoningFor, isSlurpable, listRepoFiles, loadBroadsideState, loadSavedLensResults, parseLensJson, persistBroadsideRunMerging, } from "./broadside.js";
+export const BROADSIDE_CHAT_URL = "https://openrouter.ai/api/v1/chat/completions";
+/** How many findings `verify` reads by default, most severe first. */
+export const BROADSIDE_VERIFY_DEFAULT_TOP = 10;
+/** Tool calls one finding may spend before it must answer. */
+export const BROADSIDE_VERIFY_MAX_TOOL_CALLS = 8;
+/** The lenses whose findings carry a file:line and a claim to check. */
+export const BROADSIDE_VERIFIABLE_LENSES = ["defect", "security"];
+const READ_FILE_MAX_LINES = 200;
+const GREP_MAX_MATCHES = 40;
+const GREP_MAX_FILE_BYTES = 1_000_000;
+const TOOL_OUTPUT_MAX_CHARS = 12_000;
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3 };
+/** The sync-priced id behind a `:batch` model id (`vendor/name:batch` → `vendor/name`). */
+export function syncModelFor(batchModel) {
+    return batchModel.replace(/:batch$/, "");
+}
+/** The findings a run's saved lens results carry, most severe first. */
+export function rankVerifiableFindings(stored) {
+    const out = [];
+    for (const result of stored) {
+        if (!BROADSIDE_VERIFIABLE_LENSES.includes(result.lensId) || result.truncated)
+            continue;
+        const parsed = parseLensJson(result.content);
+        for (const finding of parsed?.findings ?? []) {
+            const location = typeof finding.location === "string" ? finding.location : "";
+            const title = typeof finding.title === "string" ? finding.title : "";
+            if (!location || !title)
+                continue;
+            out.push({
+                lensId: result.lensId,
+                customId: result.customId,
+                severity: typeof finding.severity === "string" ? finding.severity.toLowerCase() : "unknown",
+                title,
+                location,
+                description: typeof finding.description === "string" ? finding.description : "",
+                pattern: typeof finding.pattern === "string" ? finding.pattern : typeof finding.category === "string" ? finding.category : "",
+            });
+        }
+    }
+    // Stable: severity, then lens order, then the order the lens listed them.
+    return out
+        .map((finding, order) => ({ finding, order }))
+        .sort((a, b) => (SEVERITY_RANK[a.finding.severity] ?? 9) - (SEVERITY_RANK[b.finding.severity] ?? 9)
+        || BROADSIDE_LENS_IDS.indexOf(a.finding.lensId) - BROADSIDE_LENS_IDS.indexOf(b.finding.lensId)
+        || a.order - b.order)
+        .map(({ finding }) => finding);
+}
+/**
+ * Three read-only tools over the repository's own file list — the same
+ * listing the lenses scan (tracked and untracked, ignore rules applied) minus
+ * everything {@link isSlurpable} keeps out of a lens: credential stores, build
+ * output, binaries. A path outside the repository, or one the listing does
+ * not contain, is an error the model sees, not a read.
+ */
+export async function createRepoReader(cwd) {
+    const { files } = await listRepoFiles(cwd);
+    const readable = new Set(files.filter(isSlurpable));
+    const confine = (path) => {
+        const abs = resolve(cwd, path);
+        const rel = relative(cwd, abs).split("\\").join("/");
+        if (!rel || rel.startsWith("..") || isAbsolute(rel))
+            throw new Error(`path is outside the repository: ${path}`);
+        return rel;
+    };
+    return {
+        async readFile(path, startLine, endLine) {
+            const rel = confine(path);
+            if (!readable.has(rel))
+                return `error: ${rel} is not a readable source file of this repository`;
+            const lines = (await readFile(join(cwd, rel), "utf8")).split("\n");
+            const start = Math.max(1, Math.floor(Number(startLine ?? 1)) || 1);
+            const requestedEnd = Math.floor(Number(endLine ?? start + READ_FILE_MAX_LINES - 1)) || start;
+            const end = Math.min(lines.length, requestedEnd, start + READ_FILE_MAX_LINES - 1);
+            if (start > lines.length)
+                return `error: ${rel} has ${lines.length} lines`;
+            return lines.slice(start - 1, end).map((line, i) => `${start + i}: ${line}`).join("\n");
+        },
+        async grep(pattern, pathPrefix) {
+            let regex;
+            try {
+                regex = new RegExp(pattern);
+            }
+            catch (error) {
+                return `error: invalid pattern (${error instanceof Error ? error.message : String(error)})`;
+            }
+            const prefix = pathPrefix ? confine(pathPrefix) : "";
+            const matches = [];
+            for (const rel of readable) {
+                if (prefix && rel !== prefix && !rel.startsWith(`${prefix}/`) && !rel.startsWith(prefix))
+                    continue;
+                let text;
+                try {
+                    if ((await stat(join(cwd, rel))).size > GREP_MAX_FILE_BYTES)
+                        continue;
+                    text = await readFile(join(cwd, rel), "utf8");
+                }
+                catch {
+                    continue;
+                }
+                const lines = text.split("\n");
+                for (let i = 0; i < lines.length && matches.length < GREP_MAX_MATCHES; i++) {
+                    if (regex.test(lines[i]))
+                        matches.push(`${rel}:${i + 1}: ${lines[i]}`);
+                }
+                if (matches.length >= GREP_MAX_MATCHES)
+                    break;
+            }
+            return matches.length > 0 ? matches.join("\n") : "(no matches)";
+        },
+        async listDir(path) {
+            const rel = path === "." || path === "" ? "" : confine(path);
+            try {
+                const entries = await readdir(join(cwd, rel), { withFileTypes: true });
+                return entries
+                    .filter((entry) => {
+                    const child = rel ? `${rel}/${entry.name}` : entry.name;
+                    return entry.isDirectory() ? [...readable].some((f) => f.startsWith(`${child}/`)) : readable.has(child);
+                })
+                    .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+                    .sort()
+                    .join("\n") || "(empty)";
+            }
+            catch (error) {
+                return `error: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    };
+}
+const TOOLS = [
+    { type: "function", function: { name: "read_file", description: "Read a range of lines (1-based, inclusive) from a source file of the repository; at most 200 lines per call.", parameters: { type: "object", properties: { path: { type: "string" }, start_line: { type: "integer" }, end_line: { type: "integer" } }, required: ["path"] } } },
+    { type: "function", function: { name: "grep", description: "Search the repository's source files for a regular expression; returns at most 40 matching lines as path:line: text.", parameters: { type: "object", properties: { pattern: { type: "string" }, path_prefix: { type: "string", description: "optional directory or file to search under" } }, required: ["pattern"] } } },
+    { type: "function", function: { name: "list_dir", description: "List a directory of the repository.", parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] } } },
+];
+const VERDICT_SCHEMA = {
+    name: "broadside_verification",
+    strict: true,
+    schema: {
+        type: "object",
+        properties: {
+            verdict: { type: "string", enum: ["confirmed", "not-a-defect", "discarded", "unclear"] },
+            confidence: { type: "string", enum: ["high", "medium", "low"] },
+            evidence: {
+                type: "array",
+                items: { type: "object", properties: { file: { type: "string" }, lines: { type: "string" }, note: { type: "string" } }, required: ["file", "lines", "note"], additionalProperties: false },
+            },
+            reasoning: { type: "string" },
+        },
+        required: ["verdict", "confidence", "evidence", "reasoning"],
+        additionalProperties: false,
+    },
+};
+/**
+ * The rubric. The order is deliberate — it is the order a reviewer settles a
+ * claim in — and `not-a-defect` is the verdict that separates "the code does
+ * what the claim says" from "and that is a bug": without it, a cast every
+ * caller satisfies gets confirmed because it is literally there.
+ */
+export const BROADSIDE_VERIFY_SYSTEM_PROMPT = "You verify a scouting finding produced by a one-shot batch scan against the real source code. " +
+    "The scan saw files without being able to look anything up; you can. Use the tools to read the cited location " +
+    "and whatever else the claim depends on (callers, the definition of a helper, error handling around it). " +
+    "Then decide, in this order: " +
+    "'discarded' — the claim is wrong about the code (the guard exists, the value cannot be what the claim assumes, " +
+    "the cited line does something else, the condition it fears is ruled out by the project's config or runtime); " +
+    "'not-a-defect' — the claim is literally true of the code but no caller, input, or state can reach the failure it " +
+    "describes: a TypeScript cast every caller satisfies, a hypothetical about an environment the project does not " +
+    "target, a style or type-hygiene observation; " +
+    "'confirmed' — the failure is reachable: name the concrete input, call site, or sequence that triggers it, and what " +
+    "then goes wrong; " +
+    "'unclear' — settling it needs runtime behaviour or specification knowledge the code does not contain. " +
+    "Be strict: a real but different problem than the one claimed is 'discarded' with the difference noted, and " +
+    "'confirmed' without a trigger you found in the code is not allowed. " +
+    "Cite line ranges you actually read. When you are done, reply with only the JSON verdict object.";
+function findingPrompt(index, finding) {
+    return (`Finding ${index} (${finding.lensId} lens, severity ${finding.severity}):\n` +
+        `Title: ${finding.title}\nLocation: ${finding.location}\nPattern/category: ${finding.pattern || "-"}\n` +
+        `Description: ${finding.description}\n\n` +
+        "Verify it. Reply with a JSON object {verdict, confidence, evidence:[{file,lines,note}], reasoning}.");
+}
+async function chat(fetcher, apiKey, model, body) {
+    const resp = await fetcher(BROADSIDE_CHAT_URL, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ model, reasoning: defaultReasoningFor(), usage: { include: true }, ...body }),
+        signal: AbortSignal.timeout(120_000),
+    });
+    const data = (await resp.json());
+    if (!resp.ok || data.error) {
+        const detail = data.error?.message ?? JSON.stringify(data.error ?? data).slice(0, 300);
+        throw new Error(`OpenRouter chat: HTTP ${resp.status}: ${detail}`);
+    }
+    return data;
+}
+function parseVerdict(text) {
+    const trimmed = text.trim();
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+    try {
+        const parsed = JSON.parse(fenced ? fenced[1] : trimmed);
+        return typeof parsed?.verdict === "string" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Verify one finding: up to the tool budget, then a verdict. */
+export async function verifyFinding(finding, index, reader, apiKey, model, fetcher) {
+    const messages = [
+        { role: "system", content: BROADSIDE_VERIFY_SYSTEM_PROMPT },
+        { role: "user", content: findingPrompt(index, finding) },
+    ];
+    let toolCalls = 0;
+    let cost = 0;
+    const usageCost = (data) => {
+        const usage = data.usage;
+        return typeof usage?.cost === "number" ? usage.cost : 0;
+    };
+    try {
+        // The +2 leaves room for the final schema-forced call after the budget.
+        for (let step = 0; step < BROADSIDE_VERIFY_MAX_TOOL_CALLS + 2; step++) {
+            const budgetSpent = toolCalls >= BROADSIDE_VERIFY_MAX_TOOL_CALLS;
+            if (budgetSpent)
+                messages.push({ role: "user", content: "Tool budget spent. Emit the verdict JSON object now from what you have read." });
+            const data = await chat(fetcher, apiKey, model, budgetSpent
+                ? { messages, response_format: { type: "json_schema", json_schema: VERDICT_SCHEMA }, max_tokens: 2000 }
+                : { messages, tools: TOOLS, tool_choice: "auto", max_tokens: 4000 });
+            cost += usageCost(data);
+            const choice = data.choices?.[0];
+            const message = choice?.message ?? { role: "assistant", content: "" };
+            messages.push(message);
+            const calls = message.tool_calls;
+            if (calls && calls.length > 0 && !budgetSpent) {
+                for (const call of calls) {
+                    toolCalls += 1;
+                    let args = {};
+                    try {
+                        args = JSON.parse(call.function.arguments || "{}");
+                    }
+                    catch {
+                        // Malformed arguments: the model sees the error and can retry.
+                    }
+                    let output;
+                    try {
+                        output = call.function.name === "read_file"
+                            ? await reader.readFile(String(args.path ?? ""), args.start_line, args.end_line)
+                            : call.function.name === "grep"
+                                ? await reader.grep(String(args.pattern ?? ""), typeof args.path_prefix === "string" ? args.path_prefix : undefined)
+                                : call.function.name === "list_dir"
+                                    ? await reader.listDir(String(args.path ?? "."))
+                                    : `error: unknown tool ${call.function.name}`;
+                    }
+                    catch (error) {
+                        output = `error: ${error instanceof Error ? error.message : String(error)}`;
+                    }
+                    messages.push({ role: "tool", tool_call_id: call.id, content: output.slice(0, TOOL_OUTPUT_MAX_CHARS) });
+                }
+                continue;
+            }
+            const verdict = parseVerdict(typeof message.content === "string" ? message.content : "");
+            if (verdict)
+                return finish(verdict, toolCalls, cost);
+            if (budgetSpent)
+                break;
+            // Prose instead of JSON: one schema-forced call, no tools.
+            const final = await chat(fetcher, apiKey, model, {
+                messages: [...messages, { role: "user", content: "Emit the verdict JSON object now." }],
+                response_format: { type: "json_schema", json_schema: VERDICT_SCHEMA },
+                max_tokens: 2000,
+            });
+            cost += usageCost(final);
+            const forced = parseVerdict(String((final.choices?.[0]?.message?.content) ?? ""));
+            if (forced)
+                return finish(forced, toolCalls, cost);
+            break;
+        }
+        return { verdict: "error", confidence: "low", evidence: [], reasoning: "no verdict within the tool budget", toolCalls, cost };
+    }
+    catch (error) {
+        return { verdict: "error", confidence: "low", evidence: [], reasoning: error instanceof Error ? error.message : String(error), toolCalls, cost };
+    }
+}
+function finish(verdict, toolCalls, cost) {
+    const known = ["confirmed", "not-a-defect", "discarded", "unclear"];
+    const value = String(verdict.verdict);
+    const evidence = Array.isArray(verdict.evidence)
+        ? verdict.evidence.map((e) => ({ file: String(e.file ?? ""), lines: String(e.lines ?? ""), note: String(e.note ?? "") }))
+        : [];
+    return {
+        verdict: (known.includes(value) ? value : "unclear"),
+        confidence: typeof verdict.confidence === "string" ? verdict.confidence : "low",
+        evidence,
+        reasoning: typeof verdict.reasoning === "string" ? verdict.reasoning : "",
+        toolCalls,
+        cost,
+    };
+}
+/**
+ * Verify the top findings of a collected run against the repository.
+ *
+ * `maxCost` is a running cap, not a pre-flight estimate: a sync call's cost
+ * is only known when it returns, so the pass stops *before* starting the next
+ * finding once the cap is reached and reports `partial`. On the default
+ * model a finding costs about a cent.
+ */
+export async function runBroadsideVerify(cwd, apiKey, opts = {}) {
+    const broadsideDir = broadsideDirFor(cwd);
+    const state = await loadBroadsideState(broadsideDir);
+    const run = opts.runId ? state.runs.find((candidate) => candidate.id === opts.runId) : state.runs[state.runs.length - 1];
+    if (!run) {
+        throw new Error(opts.runId ? `No Broad-Side run with id ${opts.runId}.` : "No Broad-Side run recorded. Submit and collect one first.");
+    }
+    const runDir = join(broadsideDir, run.outputDir);
+    const stored = await loadSavedLensResults(runDir, run.lenses);
+    const ranked = rankVerifiableFindings(stored);
+    if (ranked.length === 0) {
+        throw new Error(`Run ${run.id} has no verifiable findings on disk: the defect and security lenses either did not run, are not collected yet, or found nothing. Collect the run first.`);
+    }
+    const top = Math.max(1, Math.floor(opts.top ?? BROADSIDE_VERIFY_DEFAULT_TOP));
+    // The run's model is a `:batch` variant; the sync endpoint wants the base id.
+    const model = opts.model ?? syncModelFor(run.model);
+    const maxCost = opts.maxCost ?? 0;
+    const fetcher = opts.fetcher ?? fetch;
+    const reader = await createRepoReader(cwd);
+    const selected = ranked.slice(0, top);
+    const findings = [];
+    let totalCost = 0;
+    let stoppedByCost = false;
+    for (const [i, candidate] of selected.entries()) {
+        if (opts.signal?.aborted)
+            break;
+        if (maxCost > 0 && totalCost >= maxCost) {
+            stoppedByCost = true;
+            break;
+        }
+        const outcome = await verifyFinding(candidate, i + 1, reader, apiKey, model, fetcher);
+        const finding = {
+            index: i + 1,
+            lensId: candidate.lensId,
+            customId: candidate.customId,
+            severity: candidate.severity,
+            title: candidate.title,
+            location: candidate.location,
+            ...outcome,
+        };
+        findings.push(finding);
+        totalCost += outcome.cost;
+        opts.onProgress?.(finding);
+    }
+    const status = findings.length === selected.length ? "completed" : "partial";
+    const entry = {
+        status,
+        model,
+        top,
+        verified: findings.length,
+        confirmed: findings.filter((f) => f.verdict === "confirmed").length,
+        cost: totalCost,
+        at: new Date().toISOString(),
+    };
+    const result = {
+        runId: run.id,
+        outputDir: join(".codecarto", BROADSIDE_DIR, run.id),
+        model,
+        status,
+        candidates: ranked.length,
+        findings,
+        totalCost,
+        ...(stoppedByCost && { stoppedByCost: true }),
+    };
+    await writeFile(join(runDir, "verified.json"), `${JSON.stringify({ ...entry, run_id: run.id, candidates: ranked.length, findings }, null, "\t")}\n`, "utf8");
+    await writeFile(join(runDir, "verified.md"), renderVerifiedMarkdown(result), "utf8");
+    run.verify = entry;
+    await persistBroadsideRunMerging(broadsideDir, run);
+    return result;
+}
+const VERDICT_MARK = { confirmed: "✓", "not-a-defect": "–", discarded: "✗", unclear: "?", error: "!" };
+export function renderVerifiedMarkdown(result) {
+    const lines = [
+        `# Verified findings — run ${result.runId}`,
+        "",
+        `${result.findings.length} of ${result.candidates} verifiable finding(s) read against the source on \`${result.model}\` (most severe first), $${result.totalCost.toFixed(4)}.` +
+            (result.stoppedByCost ? " Stopped by the cost cap before the rest." : ""),
+        "",
+        "A **confirmed** finding names the input, call site, or sequence that reaches the failure. **not-a-defect** means the claim is",
+        "literally true of the code but nothing can reach the failure it describes; **discarded** means the claim is wrong about the",
+        "code; **unclear** needs runtime or specification knowledge. Every verdict is still a model's reading — a confirmed finding",
+        "is a lead worth a human's next look, not a validated claim.",
+        "",
+    ];
+    for (const f of result.findings) {
+        lines.push(`## ${VERDICT_MARK[f.verdict] ?? "?"} ${f.index}. [${f.severity}] ${f.title}`, "", `- **verdict**: ${f.verdict} (${f.confidence})`, `- **location**: ${f.location}`, `- **lens**: ${f.lensId} (${f.customId})`);
+        if (f.evidence.length > 0)
+            lines.push(`- **evidence**: ${f.evidence.map((e) => `${e.file}:${e.lines} — ${e.note}`).join("; ")}`);
+        lines.push(`- **reasoning**: ${f.reasoning.replace(/\s+/g, " ").trim()}`, `- **cost**: $${f.cost.toFixed(4)} (${f.toolCalls} tool call(s))`, "");
+    }
+    return lines.join("\n");
+}
+export function verifyResultText(result) {
+    const counts = { confirmed: 0, "not-a-defect": 0, discarded: 0, unclear: 0, error: 0 };
+    for (const f of result.findings)
+        counts[f.verdict] = (counts[f.verdict] ?? 0) + 1;
+    const lines = [
+        `Broad-Side verify — run ${result.runId}: ${result.status}`,
+        `  ${result.findings.length} of ${result.candidates} verifiable finding(s) read on ${result.model} | cost: $${result.totalCost.toFixed(4)}` +
+            (result.stoppedByCost ? " (stopped by the cost cap)" : ""),
+        `  confirmed ${counts.confirmed} · not-a-defect ${counts["not-a-defect"]} · discarded ${counts.discarded} · unclear ${counts.unclear}` + (counts.error ? ` · error ${counts.error}` : ""),
+    ];
+    for (const f of result.findings) {
+        lines.push(`  ${VERDICT_MARK[f.verdict] ?? "?"} [${f.severity}] ${f.title} @ ${f.location} — ${f.verdict}`);
+    }
+    lines.push(`Details in ${result.outputDir}/verified.md. A confirmed finding is a lead for a human's next look, not a validated claim.`);
+    return lines.join("\n");
+}

package/dist/core/broadside.d.ts

@@ -244,6 +244,17 @@ export type BroadsideTriageEntry = {
     cost?: number;
     error?: string;
 };
+/** Recorded on the run once a verification pass has run (#143); see core/broadside-verify.ts. */
+export type BroadsideVerifyEntry = {
+    /** `completed`: every selected finding got a verdict; `partial`: the cost cap or an abort stopped it early. */
+    status: "completed" | "partial";
+    model: string;
+    top: number;
+    verified: number;
+    confirmed: number;
+    cost: number;
+    at: string;
+};
 /** The truncation retry pass of one run: one batch per model (#206). */
 export type BroadsideRetryEntry = {
     status: "submitted" | "completed" | "failed";
@@ -275,6 +286,8 @@ export type BroadsideRun = {
      * run cannot both submit it (#322). Absent until a collect claims it.
      */
     retry?: BroadsideRetryEntry;
+    /** The verification pass over the top findings, when one has run (#143). */
+    verify?: BroadsideVerifyEntry;
     totalCost?: number;
     pricing?: ModelPricing;
     maxCost?: number;
@@ -520,9 +533,22 @@ export declare function getLens(lensId: BroadsideLensId): LensDefinition;
 export declare function listLenses(): LensDefinition[];
 /** The languages Broad-Side can scan; anything else is refused at submit. */
 export declare const BROADSIDE_LANGUAGES: readonly ["go", "python", "rust", "typescript", "javascript"];
+/**
+ * The files a run scans, and where they came from. Contents are always read
+ * from the working tree, so the list is the working tree's too: tracked files
+ * plus untracked ones git does not ignore, minus files deleted on disk. The
+ * list used to come from `git ls-tree HEAD`, so a run mixed the committed
+ * file list with uncommitted contents and never saw an untracked file (#248).
+ * A target that is not a git repository gets a bounded walk.
+ */
+export declare function listRepoFiles(targetDir: string): Promise<{
+    files: string[];
+    snapshot: RepoSnapshotSource;
+}>;
 export declare function collectRepoInfo(targetDir: string, opts?: {
     redact?: boolean;
 }): Promise<RepoInfo>;
+export declare function isSlurpable(relPath: string): boolean;
 type CollectedFile = {
     relPath: string;
     moduleName: string;

package/dist/core/broadside.js

@@ -920,7 +920,7 @@ const SOURCE_SPECS = {
  * file list with uncommitted contents and never saw an untracked file (#248).
  * A target that is not a git repository gets a bounded walk.
  */
-async function listRepoFiles(targetDir) {
+export async function listRepoFiles(targetDir) {
     try {
         const listed = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         const deleted = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--deleted"], {
@@ -1200,7 +1200,7 @@ function matchesAnyGlob(path, globs) {
     }
     return false;
 }
-function isSlurpable(relPath) {
+export function isSlurpable(relPath) {
     // A credential store is never a lens input, whatever its globs say (#252).
     if (isSecretFile(relPath))
         return false;
@@ -1624,6 +1624,10 @@ export async function persistBroadsideRunMerging(broadsideDir, run) {
                 run.triage = onDisk.triage;
             if (retryEntryRank(onDisk.retry) > retryEntryRank(run.retry))
                 run.retry = onDisk.retry;
+            // A verification pass another process recorded is never dropped by
+            // a collect that never knew about it; a newer pass replaces an older.
+            if (onDisk.verify && (!run.verify || onDisk.verify.at > run.verify.at))
+                run.verify = onDisk.verify;
             for (const [lensId, theirs] of Object.entries(onDisk.batches)) {
                 if (theirs && batchEntryRank(theirs) > batchEntryRank(run.batches[lensId]))
                     run.batches[lensId] = theirs;
@@ -3545,6 +3549,9 @@ export function statusText(state) {
         }
         lines.push(`  synthesis: ${run.synthesis.status}`);
         lines.push(`  triage: ${run.triage?.status ?? "pending"}`);
+        if (run.verify) {
+            lines.push(`  verify: ${run.verify.status} — ${run.verify.confirmed} confirmed of ${run.verify.verified} read on ${run.verify.model}, $${run.verify.cost.toFixed(4)}`);
+        }
         if (run.totalCost !== undefined)
             lines.push(`  total cost: $${run.totalCost.toFixed(6)}`);
     }

package/dist/core/index.d.ts

@@ -16,5 +16,6 @@ export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
 export * from "./broadside.ts";
+export * from "./broadside-verify.ts";
 export * from "./secrets.ts";
 export * from "./dashboard-writer.ts";

package/dist/core/index.js

@@ -19,5 +19,6 @@ export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
 export * from "./broadside.js";
+export * from "./broadside-verify.js";
 export * from "./secrets.js";
 export * from "./dashboard-writer.js";

package/dist/extensions/codecarto/broadside-flags.d.ts

@@ -1,5 +1,5 @@
 import { type BroadsideLensId } from "../../core/index.ts";
-export type BroadsideAction = "submit" | "collect" | "status" | "models";
+export type BroadsideAction = "submit" | "collect" | "status" | "models" | "verify";
 export interface BroadsideFlags {
     action: BroadsideAction;
     /** Empty means "the repository's default lens set". */
@@ -22,11 +22,13 @@ export interface BroadsideFlags {
     model?: string;
     /** For submit: per-lens model overrides, layered over config.yaml's (#141). */
     lensModels?: Partial<Record<BroadsideLensId, string>>;
+    /** For verify: how many findings to read (#143). */
+    top?: number;
     benchmarks: boolean;
     unknown: string[];
     /** Set on an invalid combination. The caller surfaces it as an error. */
     error?: string;
 }
 /** Every token the completer offers, in the order it offers them. */
-export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--model=", "--lens-model=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
+export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "verify", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--model=", "--lens-model=", "--top=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
 export declare function parseBroadsideFlags(args: string): BroadsideFlags;

package/dist/extensions/codecarto/broadside-flags.js

@@ -6,6 +6,7 @@
 //   /codecarto-broadside collect --wait=900
 //   /codecarto-broadside status
 //   /codecarto-broadside models --benchmarks
+//   /codecarto-broadside verify --top=10       → read the top findings against the source
 //
 // Flags mirror the codecarto_broadside tool parameters, with the negative
 // forms spelled out because a slash command has no place to pass `false`:
@@ -14,8 +15,9 @@
 //   --max-cost=N           --no-retry-truncated
 //   --wait=SECONDS         --benchmarks (models only)
 //   --run=ID (collect only: an older run, as listed by status)
-//   --model=ID (submit only: the run's batch model, as listed by models)
+//   --model=ID (submit: the run's batch model, as listed by models; verify: the sync model to read with)
 //   --lens-model=LENS:ID (submit only, repeatable: one lens on its own model)
+//   --top=N (verify only: how many findings to read, most severe first)
 //
 // A model id itself contains a colon (`vendor/name:batch`), so --lens-model
 // splits on the first colon only: `security:deepseek/deepseek-v4-pro:batch`.
@@ -28,13 +30,14 @@
 // The parser never throws. index.ts decides how to surface unknown tokens and
 // invalid combinations, matching parseNextFlags.
 import { BROADSIDE_LENS_IDS } from "../../core/index.js";
-const ACTIONS = new Set(["submit", "collect", "status", "models"]);
+const ACTIONS = new Set(["submit", "collect", "status", "models", "verify"]);
 /** Every token the completer offers, in the order it offers them. */
 export const KNOWN_BROADSIDE_TOKENS = [
     "submit",
     "collect",
     "status",
     "models",
+    "verify",
     ...BROADSIDE_LENS_IDS,
     "--incremental",
     "--no-incremental",
@@ -43,6 +46,7 @@ export const KNOWN_BROADSIDE_TOKENS = [
     "--run=",
     "--model=",
     "--lens-model=",
+    "--top=",
     "--no-synthesis",
     "--no-triage",
     "--no-retry-truncated",
@@ -122,6 +126,14 @@ export function parseBroadsideFlags(args) {
             result.runId = value || undefined;
             continue;
         }
+        if (token.startsWith("--top=")) {
+            const value = parseNumeric(token, "--top", result);
+            if (value !== undefined && (!Number.isInteger(value) || value < 1))
+                result.error ??= `--top needs a positive whole number (got "${token.slice("--top=".length)}").`;
+            else if (value !== undefined)
+                result.top = value;
+            continue;
+        }
         if (token.startsWith("--model=")) {
             const value = token.slice("--model=".length).trim();
             // An empty value is a mistyped selection, not "use the default":
@@ -167,11 +179,17 @@ export function parseBroadsideFlags(args) {
     if (result.action === "status" && result.waitSeconds !== undefined) {
         result.error ??= "--wait is only meaningful for submit and collect; status reads recorded state.";
     }
-    if (result.runId !== undefined && result.action !== "collect") {
-        result.error ??= `--run is only meaningful for collect (got action "${result.action}").`;
+    if (result.runId !== undefined && result.action !== "collect" && result.action !== "verify") {
+        result.error ??= `--run is only meaningful for collect and verify (got action "${result.action}").`;
+    }
+    if (result.model !== undefined && result.action !== "submit" && result.action !== "verify") {
+        result.error ??= `--model is only meaningful for submit and verify (got action "${result.action}").`;
+    }
+    if (result.top !== undefined && result.action !== "verify") {
+        result.error ??= `--top is only meaningful for verify (got action "${result.action}").`;
     }
-    if (result.model !== undefined && result.action !== "submit") {
-        result.error ??= `--model is only meaningful for submit (got action "${result.action}").`;
+    if (result.action === "verify" && result.waitSeconds !== undefined) {
+        result.error ??= "--wait is only meaningful for submit and collect; verify runs to completion.";
     }
     if (result.lensModels !== undefined && result.action !== "submit") {
         result.error ??= `--lens-model is only meaningful for submit (got action "${result.action}").`;

package/dist/extensions/codecarto/index.js

@@ -10,7 +10,7 @@ import { completeLastToken } from "./completions.js";
 import { buildPiGuideMessage } from "./guide-framing.js";
 import { isCtxLive, notifyCtx } from "./notify.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, expandTilde, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, describeConfigProblems, describeIncrementalFallback, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../../core/index.js";
+import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, expandTilde, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, runBroadsideVerify, verifyResultText, statusText, describeConfigProblems, describeIncrementalFallback, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
@@ -995,7 +995,7 @@ export default function codeCartographerExtension(pi) {
         },
     });
     pi.registerCommand("codecarto-broadside", {
-        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [--model=ID] [--lens-model=LENS:ID] [flags]",
+        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models|verify] [lenses…] [--model=ID] [--lens-model=LENS:ID] [--top=N] [flags]",
         // Completes the token under the cursor, so lens names and flags are
         // offered after the action too, and keeps everything typed before it.
         getArgumentCompletions: (prefix) => completeLastToken(prefix, KNOWN_BROADSIDE_TOKENS.map((value) => ({ value }))),
@@ -1181,6 +1181,35 @@ export default function codeCartographerExtension(pi) {
                 }
                 return;
             }
+            if (flags.action === "verify") {
+                // The verification pass (#143): one sync call per finding with
+                // read-only tools; the widget counts verdicts as they land.
+                const tally = { done: 0 };
+                renderProgress("Reading the top findings against the source…");
+                try {
+                    const verified = await runBroadsideVerify(ctx.cwd, apiKey, {
+                        ...(flags.runId && { runId: flags.runId }),
+                        ...(flags.top !== undefined && { top: flags.top }),
+                        ...(flags.model && { model: flags.model }),
+                        maxCost: flags.maxCost ?? config.maxCost,
+                        signal: ctx.signal,
+                        onProgress: (finding) => {
+                            tally.done += 1;
+                            progress.set(`#${finding.index}`, `${finding.verdict} — ${finding.title}`);
+                            renderProgress(`Verifying findings… ${tally.done} read`);
+                        },
+                    });
+                    const lines = verifyResultText(verified).split("\n");
+                    const confirmed = verified.findings.filter((f) => f.verdict === "confirmed").length;
+                    finish(lines, `Broad-Side verify: ${confirmed} confirmed of ${verified.findings.length} read`, verified.status === "completed" ? "info" : "warning");
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    notifyCtx(ctx, `Broad-Side verify failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                }
+                return;
+            }
             // action === "collect"
             renderProgress("Polling batches…");
             try {

package/dist/mcp-server/server.d.ts

@@ -233,7 +233,7 @@ export declare function handleAmend(args: {
 }>;
 export declare function handleBroadside(args: {
     cwd: string;
-    action: "submit" | "collect" | "status" | "models";
+    action: "submit" | "collect" | "status" | "models" | "verify";
     lenses?: string[];
     api_key?: string;
     wait_seconds?: number;
@@ -247,6 +247,7 @@ export declare function handleBroadside(args: {
     incremental?: boolean;
     model?: string;
     lens_models?: Record<string, string>;
+    top?: number;
 }): Promise<{
     content: {
         type: "text";

package/dist/mcp-server/server.js

@@ -17,7 +17,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusLineWriter, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, runBroadsideVerify, verifyResultText, seedOrchestratorFiles, statusLineWriter, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../core/index.js";
 import { applyAmendment } from "../core/amendment.js";
 import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
@@ -1037,8 +1037,8 @@ function resolveBroadsideApiKey(explicit, config) {
 export async function handleBroadside(args) {
     const cwd = await validateCwd(args.cwd);
     const action = args.action ?? "submit";
-    if (!["submit", "collect", "status", "models"].includes(action)) {
-        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models.`);
+    if (!["submit", "collect", "status", "models", "verify"].includes(action)) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models, verify.`);
     }
     // A config.yaml that exists but cannot be read refuses every action that
     // would act on it (#232); status only reads recorded runs, so it answers
@@ -1173,8 +1173,40 @@ export async function handleBroadside(args) {
             maxCost: result.maxCost,
         });
     }
-    // action === "collect"
     const runId = typeof args.run_id === "string" && args.run_id.trim() ? args.run_id.trim() : undefined;
+    if (action === "verify") {
+        // The verification pass (#143): one sync call per finding with read-only
+        // tools, most severe first. `max_cost` is a running cap here — a sync
+        // call's cost is known only when it returns — so the pass stops before
+        // the next finding once reached; absent, config.yaml's cap applies.
+        if (args.top !== undefined && !(typeof args.top === "number" && Number.isInteger(args.top) && args.top >= 1)) {
+            throw new McpError(ErrorCode.InvalidParams, "top must be a positive integer.");
+        }
+        if (args.model !== undefined && !(typeof args.model === "string" && args.model.trim())) {
+            throw new McpError(ErrorCode.InvalidParams, "model must be a non-empty OpenRouter model id.");
+        }
+        const maxCost = typeof args.max_cost === "number" && args.max_cost >= 0 ? args.max_cost : config.maxCost;
+        const verified = await runBroadsideVerify(cwd, apiKey, {
+            ...(runId && { runId }),
+            ...(args.top !== undefined && { top: args.top }),
+            ...(typeof args.model === "string" && args.model.trim() && { model: args.model.trim() }),
+            maxCost,
+            signal: serverLifetime?.signal,
+        }).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        return textResult(verifyResultText(verified), {
+            runId: verified.runId,
+            outputDir: verified.outputDir,
+            status: verified.status,
+            model: verified.model,
+            candidates: verified.candidates,
+            totalCost: verified.totalCost,
+            ...(verified.stoppedByCost && { stoppedByCost: true }),
+            findings: verified.findings,
+        });
+    }
+    // action === "collect"
     const collect = await runBroadsideCollect(cwd, apiKey, {
         waitMs,
         includeSynthesis,
@@ -1502,8 +1534,8 @@ const TOOLS = [
                 cwd: { type: "string", description: "Absolute path to the target repository." },
                 action: {
                     type: "string",
-                    enum: ["submit", "collect", "status", "models"],
-                    description: "submit fires all lens batches and returns batch ids; collect polls submitted batches, saves results, and optionally runs the synthesis pass; status shows recorded runs; models lists batch-capable models with pricing and capabilities.",
+                    enum: ["submit", "collect", "status", "models", "verify"],
+                    description: "submit fires all lens batches and returns batch ids; collect polls submitted batches, saves results, and optionally runs the synthesis pass; status shows recorded runs; models lists batch-capable models with pricing and capabilities; verify reads a collected run's top defect and security findings against the repository with read-only tools (one sync-priced call each, about a cent on the default model) and writes verified.md/verified.json beside triage.md with a verdict per finding: confirmed (a reachable failure, with the trigger), not-a-defect, discarded, or unclear.",
                 },
                 lenses: {
                     type: "array",
@@ -1516,7 +1548,11 @@ const TOOLS = [
                 },
                 run_id: {
                     type: "string",
-                    description: "For collect: the run to collect, as listed by the status action. Defaults to the most recent run; pass this to collect an older run that is still in flight after a newer submit.",
+                    description: "For collect and verify: the run to act on, as listed by the status action. Defaults to the most recent run; pass this to collect an older run that is still in flight after a newer submit.",
+                },
+                top: {
+                    type: "integer",
+                    description: "For verify: how many findings to read, most severe first (default 10). Each costs one sync call; max_cost caps the pass as a running total.",
                 },
                 wait_seconds: {
                     type: "number",
@@ -1536,7 +1572,7 @@ const TOOLS = [
                 },
                 max_cost: {
                     type: "number",
-                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml, whose default is $1.00; pass 0 for no limit.",
+                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. For verify it is a running cap: the pass stops before the next finding once the calls so far have reached it. Falls back to max_cost in .codecarto/broadside/config.yaml, whose default is $1.00; pass 0 for no limit.",
                 },
                 force: {
                     type: "boolean",
@@ -1552,7 +1588,7 @@ const TOOLS = [
                 },
                 model: {
                     type: "string",
-                    description: "For submit: the OpenRouter batch model for this run (an id ending in :batch, as listed by action 'models'). Falls back to model in .codecarto/broadside/config.yaml, then the shipped default. Pre-flighted like the configured model: priced from the live catalog, refused without structured-output support, clamped to its completion ceiling. The models listing is advisory — some catalog ids have no batch endpoint and are refused at submit, at no cost; the listing tags ids this repository has already seen accepted or refused.",
+                    description: "For verify: the sync (non-batch) OpenRouter model to read with; defaults to the run's model without its :batch suffix. For submit: the OpenRouter batch model for this run (an id ending in :batch, as listed by action 'models'). Falls back to model in .codecarto/broadside/config.yaml, then the shipped default. Pre-flighted like the configured model: priced from the live catalog, refused without structured-output support, clamped to its completion ceiling. The models listing is advisory — some catalog ids have no batch endpoint and are refused at submit, at no cost; the listing tags ids this repository has already seen accepted or refused.",
                 },
                 lens_models: {
                     type: "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",