codecartographer-pi 0.16.0 → 0.17.1

package/.codecarto/GUIDE.md

@@ -17,7 +17,7 @@ CodeCartographer distinguishes two roles. They are different jobs — but they a
 **Orchestrator.** The persistent chat driving the run — normally the very session reading this guide. The role is defined by its **duties**, not by who executes phases:
 
 - **Curate `CONVENTIONS.md` and `DECISIONS.md`**: promote patterns when they recur; append cross-cutting decisions as they land.
-- **Re-triage open questions at every phase boundary.** A question's `kind` label is itself a claim that needs evidence: before accepting `needs-maintainer-decision` or `needs-runtime-test`, re-test whether the question has become answerable by reading. A mislabeled question suppresses verification for every later phase (the `orchestration` guide topic records a real four-phase failure).
+- **Re-triage open questions at every phase boundary.** A question's `kind` label is itself a claim that needs evidence: before accepting `needs-maintainer-decision` or `needs-runtime-test`, re-test whether the question has become answerable by reading. A mislabeled question suppresses verification for every later phase (the `orchestration` guide topic records a real four-phase failure). The duty has a counterpart: when re-triage concludes a question genuinely still needs a runtime test, no finding in the next phase may assert one of that question's candidate answers with a settled action (`fix before porting`, `fix now`) — it inherits the question's uncertainty (`verify at runtime`) until runtime evidence closes the question.
 - **Sweep for contradictions** between the incoming phase's required reads and earlier phases' `owner_notes`. A measured fact that contradicts a summarized claim is a gap to route, not a nuance to smooth over.
 - **Route gaps**: confirm each completed phase's declared secondary outputs were written or explicitly routed, and that handoff `decisions` deferring work landed somewhere a later phase will actually see.
 - **Gate strategic forks** with the user: pipeline switches, opinionated-vs-agnostic specs, scope changes.
@@ -57,6 +57,7 @@ Read these files in order before doing any analysis:
 4. `scratch/checkpoints/<phase>.md`, if present, to resume durable in-phase progress after compaction or interruption.
 5. The current phase's `SKILL.md` for detailed instructions on what to analyze and produce.
 6. The output template from `templates/` for the current phase (if starting a new output).
+7. `broadside/synthesis.md`, if a Broad-Side batch reconnaissance run has completed — it carries unverified scouting leads (see `broadside/SKILL.md`) that tell you where the interactive phases should spend attention.
 
 All paths in this guide are relative to `.codecarto/` unless stated otherwise.
 
@@ -71,7 +72,7 @@ Some files in this workspace are **read-only instructions** and must not be modi
 | Category | Files | Access |
 |---|---|---|
 | Orchestration (read-only) | `GUIDE.md`, `CONTRIBUTING.md`, `LICENSE` | Read only. Never modify. |
-| Skills (read-only) | `findings/*/SKILL.md`, `findings/defect-scan/passes/*.md`, `skills/*/SKILL.md` | Read only. Never modify. |
+| Skills (read-only) | `findings/*/SKILL.md`, `findings/defect-scan/passes/*.md`, `skills/*/SKILL.md`, `broadside/SKILL.md` | Read only. Never modify. |
 | Templates (read-only) | `templates/*.md` | Read only. Never modify. |
 | Pipeline definitions (read-only) | `workflow/pipeline*.yaml`, `workflow/VALIDATE.md` | Read only. Never modify. |
 | Source code (read-only) | `../` (everything outside `.codecarto/`) | Read only. Analyze but never modify. |
@@ -83,11 +84,17 @@ Some files in this workspace are **read-only instructions** and must not be modi
 | Closeouts (framework-owned) | `closeouts/<date>-<phase-or-module>.md`, `THREAD_LOG.md` | Completion writes or updates one canonical closeout and one idempotent index entry. |
 | Conventions (orchestrator-maintained) | `CONVENTIONS.md` | Cross-cutting patterns promoted to project-wide invariants. Phase executors propose; the orchestrator promotes at the phase boundary — in inline runs, the same chat changing hats. |
 | Decisions (orchestrator-maintained, append-only) | `DECISIONS.md` | Numbered log of decisions that diverge from spec, prompt, or obvious-default. Completion appends each handoff's `decisions` under `## Completion log`; the orchestrator may re-file entries into categories. |
-| Backlog (read-write) | `BACKLOG.md` | Deferred items with rationale. |
+| Backlog (orchestrator-maintained) | `BACKLOG.md` | Work this project decided to **defer**, with the reasoning, the preconditions for revisiting, and the smallest viable form. Seeded from `templates/backlog-project.md` at init. |
 | Scratch (read-write) | `scratch/*` | Working notes; `scratch/checkpoints/<phase>.md` is the durable in-phase continuation checkpoint until the phase validates; `scratch/spikes/<spike-id>/<scenario>.md` holds spike reports (`templates/spike-report.md`); `scratch/amendments/<slug>.yaml` holds post-pipeline amendments (`templates/amendment.yaml`). |
 
 If you are uncertain whether a file should be modified, treat it as read-only.
 
+### Two things named "backlog", and neither is the other
+
+- **`BACKLOG.md` in this workspace** is *this project's* deferrals: work the project chose not to do yet. `DECISIONS.md` records what the project decided to **do**; `BACKLOG.md` records what it decided to **defer**. Deferrals get no `D` number. When a deferred item is later picked up, remove its entry here and record the decision in `DECISIONS.md`.
+- **`status.yaml`'s `post_pipeline` list** is framework-owned lifecycle state, not this file. Items there are retired by `codecarto_amend`, never by hand.
+- **CodeCartographer's own backlog** — deferred improvements to the *framework* — lives in the CodeCartographer repository, not in your workspace. If a phase prompt misled you or a validation criterion did not fit, that is feedback to the framework; it does not belong in this file.
+
 ## Pipeline Selection
 
 Seven pipeline variants are available. Check the `pipeline` field in `workflow/status.yaml` to see which is active.
@@ -98,6 +105,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 |
@@ -303,6 +311,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).
@@ -313,6 +322,10 @@ your-repo/
       VALIDATE.md              # Validation protocol. Run after every phase.
     closeouts/                 # Per-session closeout files (replaces monolithic THREAD_LOG body).
       <YYYY-MM-DD>-<phase-or-module>.md
+    broadside/                 # Batch reconnaissance state and results (see broadside/SKILL.md).
+      SKILL.md                 # How to read Broad-Side scouting leads (unverified, not evidence).
+      config.yaml              # Broad-Side model/key/lens configuration.
+      <run-id>/                # Per-run JSON + markdown findings, run-meta.json, synthesis report.
     CONVENTIONS.md             # (Optional, project-grown) Cross-cutting invariants. Orchestrator-maintained.
     DECISIONS.md               # (Optional, project-grown) Numbered decisions log. Orchestrator-maintained.
     BACKLOG.md                 # (Optional) Deferred items with rationale.

package/.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]`.

package/.codecarto/broadside/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: broadside
+description: Interpret a Broad-Side batch reconnaissance run. Use after codecarto_broadside collect has produced .codecarto/broadside/<run>/ results, to triage scouting signals before or during an interactive CodeCartographer pipeline run.
+---
+
+# Broad-Side
+
+Broad-Side is CodeCartographer's batch reconnaissance pass. It fires six
+analysis lenses — architecture, API surface, security, mechanical defect scan,
+convention extraction, and porting — at the repository as single-turn prompts
+over the OpenRouter Batch API (~50% of sync pricing, asynchronous, unattended),
+then synthesizes one cross-lens report. Results live under
+`.codecarto/broadside/<run>/` alongside this file.
+
+## What Broad-Side findings are — and are not
+
+Broad-Side findings are **unverified scouting signals**, not validated claims.
+Every lens is one shot: no cross-file traversal, no runtime verification, no
+builds, no tests, no follow-up questions. The batch model is cheap, not strong.
+Treat every finding as a lead with a file:line pointer that the interactive
+pipeline — or you — must confirm before it is a fact.
+
+This is the division of labor: Broad-Side is cheap enough to run on any repo to
+decide where the expensive interactive run should spend its attention. It does
+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,
+   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
+   point for re-verification, not a commitment — every item still needs
+   confirmation against the source before work begins.
+3. Read the per-lens files behind anything that matters to your current phase:
+   - `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)
+   - `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
+   coverage caps.
+
+## How to use the leads
+
+- **A finding that matches your phase's scope is a starting point, not an answer.**
+  Re-derive it from the source yourself; cite the source, not the Broad-Side
+  report. Broad-Side output is not evidence.
+- **Route, don't believe.** A Broad-Side "high" that your phase can neither
+  confirm nor dismiss becomes an open question with `needs-runtime-test` or
+  `needs-maintainer-decision` — never a finding.
+- **Promotable conventions are candidates only.** CONVENTIONS.md promotions
+  still require the orchestrator's review against the code, per the usual
+  promotion rules.
+- **Coverage caps are real.** Directory-sliced lenses cap each slice's input;
+  `run-meta.json` and the synthesis `coverage` field say what was scanned.
+  Everything outside that is unscouted, not clean.
+
+## Running Broad-Side
+
+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
+codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize
+codecarto_broadside {cwd, action: "status"}                   # show recorded runs
+codecarto_broadside {cwd, action: "models"}                   # compare batch models
+```
+
+The `models` action lists every `:batch` variant on OpenRouter — pricing per
+million tokens, context window, output ceiling, structured-output support, and
+(optionally) Artificial Analysis coding indices — cheapest first, with the
+configured model marked. Use it before switching models in `config.yaml`.
+Submits pre-flight the chosen model: pricing comes from the live catalog
+(cached 24h), requests clamp to the provider's completion ceiling, and a
+model that does not advertise structured-output support is refused outright,
+because every lens depends on `json_schema` response_format.
+
+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`.
+
+Submits are priced before they fire: Broad-Side estimates the run from the
+collected file sizes against the model's live per-token pricing and refuses
+when the estimate exceeds `max_cost` (`config.yaml` or the tool parameter)
+unless `force` is passed. See `config.yaml` for the model, limit, and manual
+pricing-override keys.
+
+The `max_cost` guardrail is an **estimate-based pre-flight limit**, distinct
+from OpenRouter's runtime cost tracking: it predicts from file sizes before
+spend, it does not stop a batch mid-flight. Actual spend appears in
+`run-meta.json` after collect.
+
+## Resilience notes
+
+- **Truncation is spoken.** A lens output whose JSON does not parse — even
+  after code-fence stripping — is saved verbatim but marked `truncated`:
+  the collect summary counts it, `run-meta.json` records it, and the
+  synthesis prompt is told its module is unrepresented, not clean.
+- **Resubmission is always safe.** Batch requests are pure (no tools, no
+  filesystem, no side effects), so a failed or truncated slice can be
+  resubmitted freely. This is the same retry-safety rule OpenRouter's
+  headless-agent scaffold enforces for tool-using agents ("retry only
+  before tool calls"); Broad-Side satisfies it by construction. If
+  Broad-Side ever gains server tools, this invariant becomes load-bearing.
+- **Field shapes** for the model catalog and benchmarks endpoints follow
+  the official OpenRouter skills (`OpenRouterTeam/skills`:
+  `openrouter-models`, `openrouter-benchmarks`) — consult them when
+  extending catalog parsing.

package/.codecarto/broadside/config.yaml

@@ -0,0 +1,104 @@
+# Broad-Side batch reconnaissance configuration. Optional.
+# Missing keys fall back to the defaults listed below.
+
+# OpenRouter model to use for batch requests. The default is Google Gemini
+# 3.7 Flash (batch) — the cheapest batch model with tool-calling support and
+# a 1M-token context window. Change this to another OpenRouter batch model
+# if you need a different cost/capability trade-off. To compare what's
+# available, run codecarto_broadside with action "models" — it lists every
+# :batch variant with pricing, context, output caps, structured-output
+# support, and optional coding benchmarks. Beware the expensive end of that
+# list — some batch models exceed $80 per million output tokens — and note
+# that every lens requires structured-output (json_schema) support, which
+# submit refuses to proceed without.
+#
+# model: google/gemini-3.7-flash:batch
+
+# OpenRouter API key. Prefer the OPENROUTER_API_KEY environment variable —
+# keys in this file are committed if you track .codecarto/ after init.
+# The codecarto_broadside tool also accepts api_key as a parameter.
+#
+# api_key: ""
+
+# Default lens set for codecarto_broadside submit when no lenses are
+# specified. All six lenses are on by default. Remove a lens id to skip it
+# globally, or pass an explicit lenses array on the submit call to override.
+#
+# default_lenses:
+#   - architecture
+#   - api
+#   - security
+#   - defect
+#   - 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
+# and cached for 24h. If the estimate exceeds max_cost, submit refuses and
+# prints the per-lens breakdown; pass force: true to override, or set a
+# value here so every run is guarded by default.
+#
+# This is a pre-flight estimate guardrail, not a runtime stop: OpenRouter
+# bills actual usage, which may differ from the estimate either direction.
+# Actual cost lands in each run's run-meta.json after collect.
+#
+# max_cost: 1.00
+
+# Manual pricing overrides in USD per MILLION tokens. Normally Broad-Side
+# looks the model's pricing up automatically; set both fields only when the
+# lookup fails (offline, private model) or you want to assert a ceiling.
+#
+# pricing:
+#   input_per_m: 0.1875
+#   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

package/.codecarto/findings/architecture/SKILL.md

@@ -84,6 +84,7 @@ Write the output in seven sections:
 Mark every conclusion with one of these evidence levels:
 - `observed fact`: direct statement from docs, tests, schemas, types, or code.
 - `strong inference`: architectural conclusion drawn from multiple facts.
+- `external-behavior claim`: a claim about what a system outside this source tree does (a server, engine, driver, third-party API, OS); unverifiable by reading this code, so it stays unsettled until a runtime probe or that system's own source confirms it.
 - `portability hazard`: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
 - `open question`: missing or conflicting behavior that still needs evidence.
 

package/.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.

package/.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.

package/.codecarto/findings/contracts/SKILL.md

@@ -79,6 +79,7 @@ End with a black-box acceptance list:
 Mark every finding with one of these evidence levels:
 - `observed fact`: direct statement from docs, tests, schemas, types, or code.
 - `strong inference`: behavioral conclusion drawn from multiple facts.
+- `external-behavior claim`: a claim about what a system outside this source tree does (a server, engine, driver, third-party API, OS); unverifiable by reading this code, so it stays unsettled until a runtime probe or that system's own source confirms it.
 - `portability hazard`: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
 - `open question`: missing or conflicting behavior that still needs evidence.
 

package/.codecarto/findings/defect-scan/SKILL.md

@@ -45,8 +45,11 @@ Not every pass applies to every codebase. Use the architecture map to decide emp
 Mark every finding with one of these evidence levels:
 - `observed fact`: the defect is directly visible in the code.
 - `strong inference`: the defect is highly likely based on multiple code observations.
+- `external-behavior claim`: the claim is about a component outside the analyzed source tree — a server, engine, driver, third-party API, or OS — including how it parses a payload, what it silently ignores, and version-dependent behavior. Not obtainable at any read depth of this source: settling it needs a runtime probe against the pinned version, or that system's own source at that version. This is not a weaker `strong inference`; it is a claim about a different artifact. "The client sends a map where the server's API documents an array" is an `external-behavior claim` about the server, even when both halves of the sentence are observed facts.
 - `open question`: the code is suspicious but would need runtime testing to confirm.
 
+**Cite or hedge quantities.** Any number in a finding — a file size, a default value, a call-site count, a version, a timeout — cites the file and line or the command output it was read from, or is written as an explicit estimate ("~300 MB, not measured"). A plausible specific stated in the same register as a read one is how a 32.8 MB artifact gets recorded as ~300 MB and a default of -20 as -5.
+
 ## Severity Classification
 
 Assign one severity per finding:
@@ -59,10 +62,11 @@ Assign one severity per finding:
 
 Tag each finding with a recommended action. Use the set that matches your pipeline:
 
-**Pre-porting pipelines** (full-with-audit, full-with-deep-audit):
+**Pre-porting pipelines** (full-with-audit, full-with-deep-audit, scout-first):
 - `fix before porting`: the defect would carry into a new implementation if not addressed first.
 - `port differently`: the new implementation should handle this case differently by design.
 - `leave behind`: the defect is specific to the source implementation and won't survive porting.
+- `verify at runtime`: the diagnosis names behavior of a system outside the analyzed source, or otherwise cannot be settled by reading; a runtime probe must confirm it before any fix is designed. Its destination is the spec's Spike List plus a `post_pipeline` entry of `kind: spike` — not a design change.
 
 **Maintenance pipelines** (defect-scan):
 - `fix now`: the defect is actively causing or risking problems.
@@ -72,6 +76,16 @@ Tag each finding with a recommended action. Use the set that matches your pipeli
 
 Determine which action set to use by checking the `pipeline` field in `workflow/status.yaml`.
 
+### Pairing rules — the evidence level bounds the action
+
+A finding's action may not assert more certainty than its evidence level carries:
+
+- Evidence `open question` or `external-behavior claim` ⇒ action is `verify at runtime` or `port differently` (pre-porting), or `investigate` (maintenance). **Never `fix before porting` or `fix now`.** A fix designed from an unsettled diagnosis can convert working behavior into the one shape the external system ignores — a real run recommended exactly that reshape, and runtime testing inverted it.
+- Evidence `observed fact` ⇒ action is not `verify at runtime`. A settled label with an unsettled action contradicts itself; pick the one that is true.
+- Every finding whose evidence is `open question` or `external-behavior claim` also appears in the report's **Open Questions** table, so the hedge travels with the finding into every document a later phase or a human reads — not only into the handoff.
+
+Validation checks the first rule mechanically on the findings tables; on a current scaffold a violation fails the phase. If a routed `carry_forward` item derives from an open question of `kind: needs-runtime-test` that is still unresolved, the finding that addresses it inherits that uncertainty: it closes the carry-forward with `verify at runtime`, not with a settled action, unless the question itself is closed with runtime evidence in the same handoff.
+
 ## Output
 
 Write findings to the primary output using the template at `templates/defect-report.md`.

package/.codecarto/findings/defect-scan/passes/01-logic-and-correctness.md

@@ -41,7 +41,7 @@ For each finding, record:
 - **Defect**: what is wrong, in one sentence.
 - **Evidence**: what you observed that proves or strongly suggests the defect.
 - **Severity**: critical (incorrect results in normal use), high (incorrect results in edge cases), medium (dead code or latent risk), low (style issue with correctness implications).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/02-error-handling.md

@@ -47,7 +47,7 @@ For each finding, record:
 - **Defect**: what error scenario is mishandled.
 - **Evidence**: the specific code pattern or path that demonstrates the gap.
 - **Severity**: critical (data loss or corruption on failure), high (silent failure in normal operations), medium (poor error messages or missing cleanup), low (observability gap).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/03-concurrency-and-resources.md

@@ -46,7 +46,7 @@ For each finding, record:
 - **Defect**: what concurrent or resource scenario is mishandled.
 - **Evidence**: the specific shared state, missing synchronization, or unclosed resource.
 - **Severity**: critical (data corruption or deadlock in normal operation), high (race condition in common paths), medium (resource leak under error conditions), low (theoretical race in rarely-exercised path).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/04-security-and-trust.md

@@ -54,7 +54,7 @@ For each finding, record:
 - **Defect**: what security property is violated.
 - **Evidence**: the specific code path, missing check, or exposed secret.
 - **Severity**: critical (actively exploitable, data exposure, auth bypass), high (exploitable with some effort or preconditions), medium (defense-in-depth gap, hardcoded non-production secret), low (missing header, informational disclosure).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/05-api-contract-violations.md

@@ -47,9 +47,10 @@ For each finding, record:
 - **Location**: file path and function/method name.
 - **Defect**: what contract is violated and how.
 - **Spec source**: where the expected behavior is documented (docstring, type signature, contracts phase, protocols phase, README).
+- **Which side implements the contract**: the analyzed code is often the *caller* of a contract another system implements (an HTTP API, an inference engine, a driver). A divergence between what this code sends and what the other side documents is only an `observed fact` about this code; what the other side actually does with it — accepts, ignores, rejects — is an `external-behavior claim` until a runtime probe against the pinned version says otherwise, and its action is `verify at runtime`, never `fix before porting`.
 - **Evidence**: the specific divergence between spec and implementation.
 - **Severity**: critical (public API returns wrong results), high (documented behavior incorrect in edge cases), medium (internal API inconsistency), low (stale docs, minor parameter mismatch).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/06-config-and-environment.md

@@ -50,7 +50,7 @@ For each finding, record:
 - **Defect**: what configuration or environment hazard exists.
 - **Evidence**: the specific hardcoded value, missing validation, or dangerous default.
 - **Severity**: critical (security exposure in default config, data loss on misconfiguration), high (production failure from missing validation), medium (hardcoded value that will break in a different environment), low (undocumented config behavior).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan-mechanical/SKILL.md

@@ -39,9 +39,10 @@ Use the architecture map to decide emphasis:
 
 Use the same scheme as the legacy defect-scan SKILL:
 
-- **Evidence levels:** `observed fact`, `strong inference`, `open question`.
+- **Evidence levels:** `observed fact`, `strong inference`, `external-behavior claim`, `open question`.
 - **Severity:** `critical`, `high`, `medium`, `low`.
-- **Action (pre-porting pipelines):** `fix before porting`, `port differently`, `leave behind`.
+- **Action (pre-porting pipelines):** `fix before porting`, `port differently`, `leave behind`, `verify at runtime`.
+- **Pairing rule:** `open question` or `external-behavior claim` evidence takes `verify at runtime` or `port differently`, never `fix before porting`, and the finding also appears in the report's Open Questions table. Validation checks this on the findings tables.
 
 See `findings/defect-scan/SKILL.md` for the full criteria; this phase intentionally does not duplicate them.
 

package/.codecarto/findings/defect-scan-semantic/SKILL.md

@@ -47,6 +47,8 @@ When citing a contract or protocol violation, include the contract ID or state-m
 
 Read the `carry_forward` entries in `workflow/status.yaml` whose `target_phase` is `defect-scan-semantic`. The mechanical phase may have routed semantic-flavored sightings here for closure.
 
+**Closing a routed item does not settle the question it came from.** Before closing a carry-forward, check whether it derives from an `open_questions` entry of `kind: needs-runtime-test` that is still unresolved — the mechanical phase typically registers the question and routes one of its candidate explanations onward in the same handoff. If the question stands, the finding that addresses the carry-forward inherits its uncertainty: evidence `external-behavior claim` or `open question`, action `verify at runtime`, and a row in this report's Open Questions table naming the question's id. Asserting one of the question's candidates as `strong inference` / `fix before porting` while the question remains open is the contradiction this rule exists to prevent — a real run did exactly that, and runtime testing inverted the finding. Only runtime evidence (or the external system's own source at the pinned version) closes such a question; when you have it, list the question in `open_question_closures` and cite the evidence in the finding.
+
 ## Output
 
 Write findings to the primary output using `templates/semantic-defects.md`. Organize by pass, then by severity within each pass. End with a summary table covering only passes 3, 4, and 5.

package/.codecarto/findings/porting/SKILL.md

@@ -19,6 +19,7 @@ Keep four classes of findings separate throughout:
 - `observed fact`: direct statements from docs, tests, schemas, types, and code.
 - `strong inference`: architectural conclusions drawn from multiple facts.
 - `portability hazard`: assumptions tied to the source language, runtime, terminal, OS, or third-party SDKs.
+- `external-behavior claim`: a claim about what a system outside this source tree does (a server, engine, driver, third-party API, OS) — unverifiable at any read depth here; carry it forward as unsettled, never promote it to a fact.
 - `open question`: missing or conflicting behavior that still needs evidence.
 
 Prefer concept names over source names:
@@ -39,7 +40,7 @@ Sort features by porting importance:
 
 If the defect report is available, integrate defect findings into the porting bundle:
 - Reference relevant defects in the feature contract table.
-- Tag each referenced defect with a porting recommendation: `fix before porting` (the defect would carry into a new implementation), `port differently` (the new implementation should handle this case differently by design), or `leave behind` (the defect is specific to the source implementation and won't survive porting).
+- Tag each referenced defect with a porting recommendation: `fix before porting` (the defect would carry into a new implementation), `port differently` (the new implementation should handle this case differently by design), `leave behind` (the defect is specific to the source implementation and won't survive porting), or `verify at runtime` (the diagnosis is an `external-behavior claim` or `open question` — carry it as a spike for the spec, and do not design around an unverified diagnosis). Preserve `verify at runtime` as written: flattening it into one of the settled three is how a hedge stops traveling.
 - Consolidate defect-related portability hazards alongside hazards from other phases.
 
 Use the output template at `templates/reverse-engineering-bundle.md`. Produce: