codecartographer-pi 0.24.0 → 0.25.0

package/.codecarto/broadside/SKILL.md

@@ -35,6 +35,10 @@ not replace any phase; it tells phases where to look.
    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.
+   Then make sure the work order was built from it: `status` shows
+   `triage: completed (built from N verdicts)`; if it says `(no verdicts)`,
+   run `collect --regenerate` (`regenerate_post_passes: true`) before
+   reading `triage.md`.
    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
@@ -50,7 +54,11 @@ not replace any phase; it tells phases where to look.
    - `architecture-*.json` → the architecture phase's seed of prior knowledge
    - `api-*.json` → endpoints and data types (contracts/protocols phases)
    - `security-*.json` → auth, trust boundaries (defect-scan-semantic pass 5)
-   - `defect-*.json` → mechanical defect leads (defect-scan-mechanical)
+   - `defect-*.json` → mechanical defect leads (defect-scan-mechanical). The
+     scan is asked to name the input, call site, or sequence that reaches
+     each failure, and to file a cast, assertion, or style observation that
+     every caller satisfies at severity low under the pattern `type-hygiene`
+     — read those as notes, not defects.
    - `conventions-*.json` → naming/idiom candidates for CONVENTIONS.md
    - `porting-*.json` → platform coupling (porting phase)
 4. `run-meta.json` records scope: which lenses ran, at what cost, with what
@@ -81,6 +89,7 @@ Broad-Side is an executable-surface feature. On the Pi extension:
 /codecarto-broadside status             # show recorded runs
 /codecarto-broadside models             # compare batch models
 /codecarto-broadside verify --top=10    # read the top findings against the source
+/codecarto-broadside collect --regenerate  # rebuild synthesis and triage from the verdicts
 ```
 
 On the MCP server:
@@ -91,6 +100,7 @@ codecarto_broadside {cwd, action: "collect"}                  # poll, save, synt
 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
+codecarto_broadside {cwd, action: "collect", regenerate_post_passes: true}   # rebuild synthesis and triage from the verdicts
 ```
 
 The `models` action lists every `:batch` variant on OpenRouter — pricing per
@@ -108,14 +118,16 @@ every source file; the **security** and **API** lenses target where the
 trust boundary usually lives — `server/**`, `**/auth*`, `**/middleware/**`,
 `SECURITY.md` (security) and `server/**`, `api/**`, `src/server/**`,
 `src/api/**`, `**/*routes*`, `**/*router*`, `**/*handler*`, `**/*endpoint*`
-(API). A repository whose server is `src/server.js` matches none of those, so
-when the targeted patterns find nothing those two lenses **fall back to every
-source file** — priced as such, chunked at the lens's slice size rather than
-truncated, and said so on the lens line of the estimate, the submit report,
-`status`, and the prompt the model receives. A lens whose targeted patterns
-and fallback both find nothing (only test files, say) is skipped with a line
-naming both. `max_cost` is the guard against a fallback scan on a large
-repository being more than you meant to spend.
+(API). A repository whose server is `src/server.js` matches none of those,
+and one whose only match is `SECURITY.md` has given the lens a policy to read
+and no code to check it against; so when the targeted patterns find **no
+source file** those two lenses **fall back to every source file**, on top of
+whatever did match — priced as such, chunked at the lens's slice size rather
+than truncated, and said so on the lens line of the estimate, the submit
+report, `status`, and the prompt the model receives. A lens whose targeted
+patterns and fallback both find nothing (only test files, say) is skipped
+with a line naming both. `max_cost` is the guard against a fallback scan on
+a large repository being more than you meant to spend.
 
 Collect runs two cross-lens post-passes by default: **synthesis** (the
 executive report) and **triage** (the prioritized work order). Pass
@@ -133,6 +145,16 @@ 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.
 
+The post-passes read the verdicts when they exist: a synthesis or triage
+built after a `verify` ranks the confirmed findings first, drops the
+discarded ones, lists the not-a-defect ones apart in `omitted`, and says in
+its summary how many verdicts it was built from; `status` and the collect
+report show `(built from N verdicts)` or `(no verdicts)` on each pass. A run
+collected before it was verified has a work order built from batch
+severities alone — `collect --regenerate` (`regenerate_post_passes: true`)
+resets the settled passes and runs them again with the verdicts, for another
+post-pass pair's cost; a pass still in flight is left to finish.
+
 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.24.0
+scaffold_version: 0.25.0

package/README.md

@@ -383,7 +383,7 @@ Each workflow tool accepts an absolute `cwd` for the target repository. `codecar
 
 ## Broad-Side (batch reconnaissance)
 
-Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`). The security and API lenses target the paths where a trust boundary usually lives (`server/`, `auth*`, `middleware/`, routers and handlers) and fall back to every source file when a repository has none of them — priced as such, and said so on the estimate — so a service whose server is `src/server.js` still gets its security review.
+Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`). The security and API lenses target the paths where a trust boundary usually lives (`server/`, `auth*`, `middleware/`, routers and handlers) and fall back to every source file when a repository has no code under them — priced as such, and said so on the estimate — so a service whose server is `src/server.js`, or one whose only match is its `SECURITY.md`, still gets its security review.
 
 **Broad-Side findings are unverified scouting leads, not evidence.** Each lens is one shot: no cross-file traversal, no runtime verification, no builds, no tests. Every finding is a `file:line` pointer that the interactive pipeline — or you — must confirm before it is a fact. That division of labor is the point: a sub-dollar unattended sweep that tells the expensive run where to look. Nothing downstream may cite a Broad-Side report as a source.
 
@@ -395,15 +395,16 @@ codecarto_broadside {cwd, action: "submit", lenses: [...]}    # fire the batches
 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
+codecarto_broadside {cwd, action: "collect", regenerate_post_passes: true}   # rebuild the report and work order from the verdicts
 ```
 
-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`.
+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` — and have `triage.md` built from it: the synthesis and triage passes rank on the verdicts when they exist (confirmed first, discarded dropped, not-a-defect listed apart), and `collect` with `regenerate_post_passes: true` (`--regenerate` on Pi) rebuilds both for a run that was collected before it was verified.
 
 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|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.
+On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models|verify] [lenses…] [--model=ID] [--lens-model=LENS:ID] [--top=N] [--regenerate]`, 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

@@ -99,7 +99,11 @@ 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:
+that shows it, unclear). The post-passes rank on those verdicts when they
+exist; a run collected before it was verified has a work order built from
+batch severities alone (`status` says `(no verdicts)`), and
+`action: "collect", regenerate_post_passes: true` rebuilds both passes from
+the verdicts for another post-pass pair's cost. Then, in this order:
 
 1. `synthesis.md` — executive summary, severity counts, top cross-lens
    findings, per-module risk.

package/dist/core/amendment.d.ts

@@ -39,8 +39,11 @@ export declare function listAmendmentNames(workspaceDir: string): Promise<string
 export declare function loadAmendmentFile(name: string, workspaceDir: string): Promise<Amendment>;
 /**
  * Apply one amendment to canonical state under the completion lock. Refuses
- * while the pipeline is incomplete — mid-pipeline resolutions belong in the
- * phase handoff, and allowing both channels at once would race them.
- * Idempotent: ids that no longer match anything are reported, not fatal.
+ * while the pipeline is incomplete, judged on the state read under the lock:
+ * the check used to run on a read taken before the lock, so a status change
+ * that landed in between — a pipeline switch, a re-init, a rolled-back
+ * completion — was amended over as if the pipeline were still complete
+ * (Broad-Side verify, 2026-09-13 run). Idempotent: ids that no longer match
+ * anything are reported, not fatal.
  */
 export declare function applyAmendment(cwd: string, name: string): Promise<AmendmentResult>;

package/dist/core/amendment.js

@@ -91,17 +91,12 @@ function renderAmendmentCloseout(amendment, applied, timestamp) {
     return lines.join("\n");
 }
 /**
- * Apply one amendment to canonical state under the completion lock. Refuses
- * while the pipeline is incomplete — mid-pipeline resolutions belong in the
- * phase handoff, and allowing both channels at once would race them.
- * Idempotent: ids that no longer match anything are reported, not fatal.
+ * The refusal an amendment gets while the pipeline is incomplete —
+ * mid-pipeline resolutions belong in the phase handoff, and allowing both
+ * channels at once would race them.
  */
-export async function applyAmendment(cwd, name) {
-    const initialState = await getWorkspaceState(cwd);
-    if (!initialState)
-        throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
-    const amendment = await loadAmendmentFile(name, initialState.workspaceDir);
-    const outcome = resolvePipelineOutcome(initialState);
+function refuseUnlessComplete(state) {
+    const outcome = resolvePipelineOutcome(state);
     if (outcome.kind === "eligible") {
         throw new Error(`Cannot amend: the pipeline is not complete (next phase: ${outcome.phase.id}). `
             + `Resolve open questions and routed items through that phase's handoff (open_question_closures / carry_forward_closures) instead.`);
@@ -111,10 +106,26 @@ export async function applyAmendment(cwd, name) {
         // finish is not there yet (#228).
         throw new Error(`Cannot amend: the pipeline is not complete. ${describeStuckPipeline(outcome.blocked)}`);
     }
+}
+/**
+ * Apply one amendment to canonical state under the completion lock. Refuses
+ * while the pipeline is incomplete, judged on the state read under the lock:
+ * the check used to run on a read taken before the lock, so a status change
+ * that landed in between — a pipeline switch, a re-init, a rolled-back
+ * completion — was amended over as if the pipeline were still complete
+ * (Broad-Side verify, 2026-09-13 run). Idempotent: ids that no longer match
+ * anything are reported, not fatal.
+ */
+export async function applyAmendment(cwd, name) {
+    const initialState = await getWorkspaceState(cwd);
+    if (!initialState)
+        throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+    const amendment = await loadAmendmentFile(name, initialState.workspaceDir);
     const timestamp = new Date().toISOString();
     const applied = { openQuestionsClosed: [], postPipelineClosed: [], unknownIds: [] };
     let closeoutNotice = "";
     const updatedState = await updateStatusAtomically(cwd, async (lockedState) => {
+        refuseUnlessComplete(lockedState);
         const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
         for (const closureId of amendment.open_question_closures) {
             if (!closureId)

package/dist/core/broadside.d.ts

@@ -226,6 +226,12 @@ export type BroadsideSynthesisEntry = {
     cost?: number;
     /** Why the pass was retired, when the batch reported one. */
     error?: string;
+    /**
+     * How many verification verdicts the pass was built from (#338): the
+     * `verified.json` a `verify` pass wrote before this pass was submitted.
+     * Absent when the pass was built from the lens findings alone.
+     */
+    verdicts?: number;
 };
 /** One triage item — a scouting lead turned into a work-order entry. */
 export type TriageItem = {
@@ -238,12 +244,8 @@ export type TriageItem = {
     effort_estimate: string;
     rationale: string;
 };
-export type BroadsideTriageEntry = {
-    batchId?: string;
-    status: "pending" | "submitted" | "completed" | "failed";
-    cost?: number;
-    error?: string;
-};
+/** The triage post-pass entry: the same shape as synthesis's. */
+export type BroadsideTriageEntry = BroadsideSynthesisEntry;
 /** 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. */
@@ -264,6 +266,8 @@ export type BroadsideRetryEntry = {
     }>;
     /** When the owning collect claimed the pass (#322). */
     claimedAt: string;
+    /** What the retry batches cost, once polled to completion. */
+    cost?: number;
 };
 /**
  * The parts of a run that cost money to submit and that exactly one collect
@@ -288,6 +292,11 @@ export type BroadsideRun = {
     retry?: BroadsideRetryEntry;
     /** The verification pass over the top findings, when one has run (#143). */
     verify?: BroadsideVerifyEntry;
+    /**
+     * What post-pass results that were later regenerated had cost (#338):
+     * money the run spent that no current entry accounts for.
+     */
+    retiredCost?: number;
     totalCost?: number;
     pricing?: ModelPricing;
     maxCost?: number;
@@ -505,6 +514,8 @@ export type BroadsideCollectResult = {
         summary: string;
     }[];
     topTriageItems: TriageItem[];
+    /** The post-passes this collect reset and re-ran on request (#338). */
+    regenerated?: Array<"synthesis" | "triage">;
 };
 type LensDefinition = {
     id: BroadsideLensId;
@@ -518,12 +529,16 @@ type LensDefinition = {
     skipTestFiles?: boolean;
     globsFor: (info: RepoInfo) => string[];
     /**
-     * Where to look when `globsFor` matches nothing (#319). The security and
-     * api lenses target server/, auth, and middleware paths because that is
-     * where the trust boundary usually lives; a service whose server is
-     * `src/server.js` matched none of them and got no security review at all.
-     * The fallback is the language's whole source set — priced as such, and
-     * said so in the estimate, the run record, and the prompt.
+     * Where to look when `globsFor` matches no source file (#319). The
+     * security and api lenses target server/, auth, and middleware paths
+     * because that is where the trust boundary usually lives; a service whose
+     * server is `src/server.js` matched none of them and got no security
+     * review at all. A match that is only documents is the same starvation:
+     * `SECURITY.md` satisfied the security lens on CodeCartographer itself,
+     * which then reviewed a policy and reported zero findings. The fallback
+     * is the language's whole source set, added to whatever did match —
+     * priced as such, and said so in the estimate, the run record, and the
+     * prompt.
      */
     fallbackGlobsFor?: (info: RepoInfo) => string[];
     systemPrompt: (info: RepoInfo) => string;
@@ -554,10 +569,15 @@ type CollectedFile = {
     moduleName: string;
 };
 /**
- * The files a lens will read: its targeted globs, or — when those match
- * nothing and the lens declares a fallback — the fallback globs, with a
- * sentence saying so (#319). The sentence travels to the estimate, the
- * batch entry, and the prompt, so a fallback scan is never a silent one.
+ * The files a lens will read: its targeted globs, or — when those match no
+ * source file and the lens declares a fallback — the fallback globs on top
+ * of whatever did match, with a sentence saying so (#319). The sentence
+ * travels to the estimate, the batch entry, and the prompt, so a fallback
+ * scan is never a silent one.
+ *
+ * "No source file" rather than "no file": a policy document or a config
+ * file under a targeted path satisfies the globs and leaves the lens with
+ * nothing to review, and the coverage note it writes back is the only sign.
  */
 export declare function selectLensFiles(allFiles: string[], lens: LensDefinition, info: RepoInfo): {
     files: CollectedFile[];
@@ -671,6 +691,17 @@ export declare function persistBroadsideRunMerging(broadsideDir: string, run: Br
  * flight elsewhere.
  */
 export declare function claimRunSlot(broadsideDir: string, run: BroadsideRun, slot: BroadsideRunSlot): Promise<boolean>;
+/**
+ * Put a run's settled post-passes back to `pending` on disk so the next
+ * claim re-runs them (#338). A pass another collect has in flight is left
+ * alone — its result is still coming. The replaced results' cost moves to
+ * `retiredCost`, so the run's total keeps counting money it spent. Returns
+ * the passes that were reset, in the order they will be re-run.
+ */
+export declare function resetRunPostPasses(broadsideDir: string, run: BroadsideRun, wanted: {
+    synthesis: boolean;
+    triage: boolean;
+}): Promise<Array<"synthesis" | "triage">>;
 export declare function loadBroadsideConfig(broadsideDir: string): Promise<BroadsideConfig>;
 /** The shipped defaults: what an absent config.yaml means. */
 export declare function defaultBroadsideConfig(): BroadsideConfig;
@@ -822,6 +853,39 @@ export declare function saveLensResults(runDir: string, lensId: BroadsideLensId,
  * "a resumed collect can finish whichever is still pending" true.
  */
 export declare function loadSavedLensResults(runDir: string, lenses: BroadsideLensId[]): Promise<StoredLensResult[]>;
+/**
+ * One verdict from a run's `verified.json` (written by the verify pass in
+ * `broadside-verify.ts`), reduced to what the post-passes are told.
+ */
+export type PostPassVerdict = {
+    lensId: string;
+    customId: string;
+    severity: string;
+    title: string;
+    location: string;
+    verdict: string;
+    confidence: string;
+    evidence: Array<{
+        file: string;
+        lines: string;
+        note: string;
+    }>;
+    reasoning: string;
+};
+/**
+ * The verdicts a verify pass left in the run directory, or null when none
+ * has run (#338). A file that does not parse is treated as absent: the
+ * post-passes then run from the findings alone, which is what they did
+ * before verdicts existed, and `status` shows the pass carried no verdicts.
+ */
+export declare function loadPostPassVerdicts(runDir: string): Promise<PostPassVerdict[] | null>;
+/**
+ * The verdicts as a section of the post-pass user message: one line per
+ * finding with the verdict, the evidence the verifier cited, and its
+ * reasoning, so the pass can rank on them rather than on the batch model's
+ * own severities (#338).
+ */
+export declare function renderPostPassVerdicts(verdicts: PostPassVerdict[]): string;
 export declare function runBroadsideCollect(cwd: string, apiKey: string, opts?: {
     waitMs?: number;
     includeSynthesis?: boolean;
@@ -844,6 +908,13 @@ export declare function runBroadsideCollect(cwd: string, apiKey: string, opts?:
     signal?: AbortSignal;
     /** Poll cadence override; tests drive the loop faster than 15 s. */
     pollIntervalMs?: number;
+    /**
+     * Reset the wanted post-passes of a collected run and run them again
+     * (#338) — after a `verify`, so the executive report and the work order
+     * are built from the verdicts. A pass still in flight is left to finish;
+     * a run whose lens batches are still running is refused.
+     */
+    regeneratePostPasses?: boolean;
 }): Promise<BroadsideCollectResult>;
 export declare function runBroadsideStatus(cwd: string): Promise<{
     state: BroadsideStateFile;