feat: finish Broad-Side — Pi surface, scout-first pipeline, per-lens models, and the missing paper trail (#138, #139, #141)

.codecarto/.gitignore

@@ -5,6 +5,7 @@ findings/contracts/behavioral-contracts.md
 findings/protocols/protocols-and-state.md
 findings/porting/reverse-engineering-bundle.md
 findings/reimplementation-spec/reimplementation-spec.md
+findings/broadside-scout/scout-brief.md
 
 # Secondary / optional outputs
 findings/public-surfaces/public-surfaces.md

.codecarto/GUIDE.md

@@ -99,6 +99,7 @@ Seven pipeline variants are available. Check the `pipeline` field in `workflow/s
 | Variant | File | Phases | When to use |
 |---|---|---|---|
 | Full with deep audit (default) | `workflow/pipeline-full-with-deep-audit.yaml` | architecture → defect-scan-mechanical → contracts → protocols → defect-scan-semantic → porting → reimplementation-spec | Complete analysis with defect scan split into an early mechanical pass and a deep semantic pass; reimplementation designs around defects with full context |
+| Scout first | `workflow/pipeline-scout-first.yaml` | broadside-scout → architecture → defect-scan-mechanical → contracts → protocols → defect-scan-semantic → porting → reimplementation-spec | The deep-audit run behind a Broad-Side routing brief: the scout phase distills an existing batch reconnaissance run into leads addressed to later phases, each of which must confirm, dismiss, or carry them forward. Leads are never evidence |
 | Full with audit | `workflow/pipeline-full-with-audit.yaml` | architecture → defect-scan → contracts → protocols → porting → reimplementation-spec | Single early defect scan; cheaper than the deep variant when you do not need contracts/protocols-grounded defect findings |
 | Full | `workflow/pipeline.yaml` | architecture → contracts → protocols → porting → reimplementation-spec | Porting bundle without defect scan |
 | Defect scan | `workflow/pipeline-defect-scan.yaml` | architecture → defect-scan | Maintenance audit to surface latent problems |
@@ -304,6 +305,7 @@ your-repo/
         SKILL.md
     workflow/
       pipeline-full-with-deep-audit.yaml  # 7-phase pipeline with split defect scan (default).
+      pipeline-scout-first.yaml   # 8-phase: deep audit behind a broadside-scout routing brief.
       pipeline-full-with-audit.yaml       # 6-phase pipeline with single early defect scan.
       pipeline.yaml                       # 5-phase (no defect scan).
       pipeline-defect-scan.yaml           # 2-phase (architecture + defect scan).

.codecarto/README.md

@@ -31,6 +31,7 @@ The default is the 7-phase **full-with-deep-audit** pipeline, which splits the d
 
 ```yaml
 pipeline: workflow/pipeline-full-with-deep-audit.yaml  # 7-phase with split defect scan (default; depth-first)
+pipeline: workflow/pipeline-scout-first.yaml           # 8-phase: the deep-audit run behind a broadside-scout brief (Pi/MCP only)
 pipeline: workflow/pipeline-full-with-audit.yaml       # 6-phase with single early defect scan — adjust phases to use one defect-scan
 pipeline: workflow/pipeline.yaml                       # 5-phase without defect scan — remove defect-scan phases
 pipeline: workflow/pipeline-defect-scan.yaml           # 2-phase defect audit — remove contracts through reimplementation-spec
@@ -39,4 +40,6 @@ pipeline: workflow/pipeline-architecture-only.yaml     # 1-phase quick overview
 pipeline: workflow/pipeline-synthesis.yaml             # 4-phase forward synthesis — vision + confirmed library specs → project plan (Pi/MCP only)
 ```
 
+The scout-first pipeline is the deep-audit run with one phase in front of it: `broadside-scout` distills a completed Broad-Side batch reconnaissance run into `findings/broadside-scout/scout-brief.md`, and the six phases after it read that brief and must account for the leads routed to them. Firing the reconnaissance run itself needs Pi or MCP; the scout phase only reads what a run already wrote, so with no run on disk it produces an explicitly empty brief and the pipeline proceeds.
+
 The synthesis pipeline is different from the analysis variants: it requires Pi or MCP, a configured non-empty CodeCartographer library, and a completed `inputs/vision.md`. It pauses after proposing candidate specs and will not merge or finalize until the user changes at least one proposal checkbox from `[ ]` to `[x]`.

.codecarto/broadside/SKILL.md

@@ -59,7 +59,16 @@ not replace any phase; it tells phases where to look.
 
 ## Running Broad-Side
 
-Broad-Side is an executable-surface feature (MCP today):
+Broad-Side is an executable-surface feature. On the Pi extension:
+
+```
+/codecarto-broadside submit [lenses…]   # prices the run, asks, then fires
+/codecarto-broadside collect            # poll, save, synthesize
+/codecarto-broadside status             # show recorded runs
+/codecarto-broadside models             # compare batch models
+```
+
+On the MCP server:
 
 ```
 codecarto_broadside {cwd, action: "submit", lenses: [...]}   # fire the batches
@@ -81,6 +90,26 @@ 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.
 
+Lenses do not all have to run on the same model. `lens_models` in `config.yaml`
+routes individual lenses to their own batch model — the usual reason being that
+a stronger model changes security and defect findings more than it changes an
+architecture map. Each override is priced, capability-checked, and clamped like
+the default, the submit estimate breaks cost out per lens, and `run-meta.json`
+records which lens ran on what. No stronger default is shipped: which model is
+worth the money depends on the repository and the budget, so compare with the
+`models` action and decide.
+
+Every run knob — `incremental`, `retry_truncated`, `include_synthesis`,
+`include_triage`, `wait_seconds` — also has a repository default under the same
+name in this directory's `config.yaml`, alongside `model`, `api_key`,
+`default_lenses`, `max_cost`, and the `pricing` overrides. An explicit
+parameter on the call always wins over the file.
+
+This file is also served directly: `codecarto_skill {cwd, name: "broadside"}`
+returns it. Unlike the post-pipeline skills under `.codecarto/skills/`, it is
+not gated on a completed pipeline — a scout run is meant to be read before the
+pipeline starts and while it runs.
+
 It works on any git repository — no initialized workspace required — and needs
 an OpenRouter API key via the `api_key` parameter, the `OPENROUTER_API_KEY`
 environment variable, or `api_key` in this directory's `config.yaml`.

.codecarto/broadside/config.yaml

@@ -32,6 +32,24 @@
 #   - conventions
 #   - porting
 
+# Per-lens model overrides. A lens listed here runs on its own model; every
+# other lens uses the `model` above. This is how you spend more where it pays:
+# the cheap default is right for architecture and conventions, while security
+# and defect findings are the ones a stronger model most changes. Each override
+# is pre-flighted like the default — priced from the live catalog, refused
+# without structured-output support, and clamped to its own completion ceiling
+# — and the submit estimate breaks the cost out per lens so a mixed-model run
+# cannot be approved without seeing which lens costs what.
+#
+# There is deliberately no stronger default shipped here: which model is worth
+# the money for the semantic lenses depends on your repository and your budget,
+# and picking one for you would spend your money on our guess. Compare
+# candidates with the `models` action first.
+#
+# lens_models:
+#   security: anthropic/claude-opus-4.5:batch
+#   defect: anthropic/claude-opus-4.5:batch
+
 # Approximate run expense limit in USD (0 = no limit). Before submitting,
 # Broad-Side estimates the run cost from the collected file sizes and the
 # model's per-token pricing — fetched live from OpenRouter's model catalog
@@ -51,4 +69,36 @@
 #
 # pricing:
 #   input_per_m: 0.1875
-#   output_per_m: 0.9375
+#   output_per_m: 0.9375
+# ---------------------------------------------------------------------------
+# Run defaults. Each key below mirrors a codecarto_broadside parameter of the
+# same name and sets this repository's default for it; an explicit parameter on
+# the call always wins. Set them here when a repo's scouting policy is stable,
+# so it does not have to be restated on every submit and collect.
+
+# Scan only the modules whose files changed since the previous run's git HEAD.
+# Falls back to a full scan on a dirty tree or when no prior run exists.
+#
+# incremental: false
+
+# Re-submit lens results that came back truncated at the output token limit,
+# once, with a doubled output cap. Truncation is always reported either way.
+#
+# retry_truncated: true
+
+# Run the cross-lens synthesis pass (synthesis.md, the executive report) once
+# every lens batch completes.
+#
+# include_synthesis: true
+
+# Run the triage pass (triage.md, the P0-P3 work order) once every lens batch
+# completes.
+#
+# include_triage: true
+
+# Default poll budget in seconds. 0 returns as soon as the batches are
+# submitted or the recorded state is read; a positive value polls that long
+# before returning with whatever is done. Batch jobs routinely take tens of
+# minutes, so a submit-then-collect-later rhythm is normal.
+#
+# wait_seconds: 0

.codecarto/findings/broadside-scout/README.md

@@ -0,0 +1,20 @@
+# Broad-Side Scout
+
+Distills a completed Broad-Side batch reconnaissance run into a routing brief.
+Runs first, before architecture, in the `pipeline-scout-first` workflow.
+
+**Primary output:** `scout-brief.md`
+
+**Depends on:** nothing in the pipeline. It reads what a prior
+`/codecarto-broadside` (Pi) or `codecarto_broadside` (MCP) run wrote under
+`broadside/<run>/`. It never submits a batch and never spends; with no run on
+disk it produces an explicitly empty brief and the pipeline proceeds.
+
+**Consumed by:** architecture, defect-scan-mechanical, contracts, protocols,
+defect-scan-semantic, and porting, each of which must account for the leads
+routed to it at validation. `reimplementation-spec` deliberately does not read
+it — the porting bundle is that phase's compression boundary.
+
+Everything in the brief is an unverified scouting lead. No phase may cite it,
+or any file under `broadside/`, as a source. See `SKILL.md`, and
+`broadside/SKILL.md` for how to read the underlying run.

.codecarto/findings/broadside-scout/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: broadside-scout
+description: Distill a completed Broad-Side batch reconnaissance run into a routing brief the later phases read. Runs first, before architecture, in the scout-first pipeline. Produces leads with a target phase for each — never findings, never evidence.
+---
+
+# Broad-Side Scout
+
+This phase turns a Broad-Side batch reconnaissance run into a **routing brief**:
+a short document that tells each later phase where to spend its attention
+first. It runs before architecture, and everything downstream reads it.
+
+The source code to analyze is in the parent directory (`../` relative to
+`.codecarto/`).
+
+## This phase spends no money
+
+Broad-Side itself is fired by `/codecarto-broadside submit` (Pi) or
+`codecarto_broadside` (MCP), and it is priced and confirmed there. This phase
+only reads what those already wrote under `broadside/<run>/`. It never submits
+a batch, and it must never instruct anyone to.
+
+If no run exists, that is a legitimate outcome — see "When there is no run."
+
+## What you are reading, and what it is worth
+
+Broad-Side findings are **unverified scouting signals** produced by a cheap
+batch model in a single shot: no cross-file traversal, no runtime
+verification, no builds, no tests, no follow-up questions.
+
+The entire value of this phase is routing attention. The entire risk is that a
+lead gets copied forward as a fact. So the brief you write is a list of
+*places to look*, each addressed to a phase, and every entry carries the
+source pointer that phase must confirm for itself.
+
+Nothing you write here is evidence. No later phase may cite this brief, or any
+file under `broadside/`, as a source for a finding. A later phase cites the
+code it confirmed.
+
+## Reading the run
+
+1. Find the most recent run directory under `broadside/`. If several exist,
+   use the newest and say which one you used.
+2. `broadside/<run>/synthesis.md` — the executive summary, severity counts,
+   top cross-lens findings, per-module risk. Start here.
+3. `broadside/<run>/triage.md` — the same findings scored by impact ×
+   difficulty into a P0–P3 order with effort estimates.
+4. `broadside/<run>/run-meta.json` — which lenses ran, at what cost, with what
+   coverage caps. This is where you learn what was *not* scanned.
+5. The per-lens files only when a lead matters enough to need its detail.
+
+## Routing
+
+Each lead goes to exactly one phase. Use the lens it came from as the default
+routing, and override when the content says otherwise:
+
+| Lens | Default target phase |
+|---|---|
+| architecture | `architecture` |
+| api | `contracts`, or `protocols` for wire formats |
+| security | `defect-scan-semantic` |
+| defect | `defect-scan-mechanical` |
+| porting | `porting` |
+| conventions | none — these are candidates for the orchestrator's `CONVENTIONS.md`, not a phase |
+
+A lead you cannot route to a phase in the active pipeline is not a lead for
+this run. Drop it and say you dropped it.
+
+## Cutting the list down
+
+A brief that forwards everything routes nothing. Keep the leads that would
+change where a phase starts looking, and drop the rest. Two filters:
+
+- **Would this phase find it anyway in its first pass?** If yes, it is not
+  worth a lead — the phase's own rubric already covers it.
+- **Is it specific enough to check?** A lead without a file or a module is not
+  actionable. Note the theme in coverage notes instead of forwarding noise.
+
+Prefer 3–8 leads per target phase. If a lens produced far more than that, say
+so in the coverage notes and forward the strongest.
+
+## Coverage is spoken, not implied
+
+`run-meta.json` records truncated slices, skipped lenses, and coverage caps.
+Everything outside the sweep is **unscouted, not clean**, and the brief must
+say which parts of the repository were never looked at. A later phase that
+reads "no leads for module X" must be able to tell "the scout found nothing
+there" from "the scout never looked."
+
+## When there is no run
+
+If `broadside/` holds no completed run, do not submit one and do not stall the
+pipeline. Write the brief with an empty lead table, state plainly under
+Coverage and limits that no run exists and therefore no module was scouted
+(coverage disposition `NONE`), and validate the coverage criteria against that. Every later phase then proceeds on its own
+rubric, exactly as it would in a pipeline without this phase.
+
+## Output
+
+Write the brief to the primary output using
+`templates/broadside-scout-brief.md`. Keep it short: it is read at the top of
+six later phases, and every line costs each of them context.

.codecarto/templates/broadside-scout-brief.md

@@ -0,0 +1,97 @@
+# Broad-Side Scout Brief — [project_name]
+
+<!--
+  Output template for the `broadside-scout` phase.
+  Distills a Broad-Side batch reconnaissance run into leads routed to later
+  phases. See findings/broadside-scout/SKILL.md for instructions.
+
+  Every entry here is an UNVERIFIED lead from a cheap batch model, not a
+  finding. No later phase may cite this file as a source.
+-->
+
+## Scout Context
+
+- **Run:** `broadside/[run-id]/` (or: no completed run — see Scout Coverage)
+- **Model:** [batch model id]
+- **Lenses that ran:** [list]
+- **Recorded cost:** [from run-meta.json]
+- **Pipeline:** [pipeline variant name]
+- **Date:** [date]
+
+> These are unverified scouting leads. Each one is a place to look, not a
+> fact. The receiving phase confirms it against the source and cites the
+> source — never this brief.
+
+---
+
+## Leads by Phase
+
+<!--
+  One row per lead. Target must be a phase in the active pipeline.
+  Source pointer is the file:line (or module) the receiving phase starts from.
+  Confidence is the scout's, not yours: high / medium / low.
+  Drop anything the target phase would find in its own first pass.
+-->
+
+| # | Target phase | Lead | Source pointer | Lens | Scout confidence |
+|---|--------------|------|----------------|------|------------------|
+| 1 | | | | | |
+
+---
+
+## Convention Candidates
+
+<!--
+  From the conventions lens. These route to the orchestrator's CONVENTIONS.md
+  promotion review, not to a phase. Candidates only — promotion still requires
+  the orchestrator's review against the code.
+-->
+
+| # | Candidate convention | Where the scout saw it |
+|---|----------------------|------------------------|
+| 1 | | |
+
+---
+
+## Leads Dropped
+
+<!--
+  What you chose not to forward, and why. This is the record that keeps the
+  brief short without hiding the discard.
+-->
+
+| # | Lead | Why dropped |
+|---|------|-------------|
+| 1 | | |
+
+---
+
+## Coverage and limits
+
+<!--
+  What the scout scanned, what it did not, and what came back unusable. A
+  later phase must be able to tell "the scout found nothing there" from "the
+  scout never looked there." Sourced from broadside/<run>/run-meta.json.
+-->
+
+- Inspected scope: [modules scanned, or "whole repository in one slice"]
+- Skipped scope: [modules the lens globs, slicing cap, or incremental diff excluded; lenses skipped, with reason]
+- Evidence basis: batch-model scouting signals only — no source inspection, no tests, no runtime verification
+- Known blind spots: [truncated slices and the modules they covered; everything under Skipped scope is unscouted, not clean]
+- Coverage disposition: COMPLETE | PARTIAL | NONE (no completed Broad-Side run)
+
+## Validation
+
+<!-- Fill in this table per workflow/VALIDATE.md. The rows below match the broadside-scout scope. -->
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | Every forwarded lead names a target phase in this pipeline and a source pointer the target phase can start from. | PASS / PARTIAL / FAIL | |
+| 2 | Every lead is marked as an unverified scouting signal; none is stated as a fact or cited as evidence. | PASS / PARTIAL / FAIL | |
+| 3 | Leads dropped rather than forwarded are recorded with a reason. | PASS / PARTIAL / FAIL | |
+| 4 | Convention candidates are routed to the orchestrator's CONVENTIONS.md review, not to a phase. | PASS / PARTIAL / FAIL | |
+| 5 | When no completed Broad-Side run exists, the brief says so explicitly and forwards no leads. | PASS / PARTIAL / FAIL | |
+| 6 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL