codecartographer-pi 0.16.0 → 0.17.0

package/.codecarto/GUIDE.md

@@ -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/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/skills/spec-delta-application/SKILL.md

@@ -26,11 +26,13 @@ Triage every delta into one of four buckets:
 |---|---|---|
 | **APPLY** | Delta is a real correction or required addition; the spec is wrong without it. | Edit the spec body. Add a `[revised per <source> §<delta-id>]` marker at the changed section. Record in DELTAS-APPLIED.md. |
 | **CLARIFY** | Delta proposes wording change; the spec's *meaning* is correct but the language is ambiguous. | Edit the spec wording (not the rule). Record in DELTAS-APPLIED.md as a clarification. |
-| **DEFER** | Delta is a real improvement but not load-bearing for the next implementation step. | Add to BACKLOG.md with rationale and a back-reference. Do NOT edit the spec. |
+| **DEFER** | Delta is a real improvement but not load-bearing for the next implementation step. | Add to `BACKLOG.md` with rationale and a back-reference (`templates/backlog-project.md` gives the entry shape). Do NOT edit the spec. |
 | **REJECT** | Delta is wrong on close reading (premise was incorrect, scope was misread, the rule it proposes already exists, etc.). | Document in DELTAS-APPLIED.md with a one-line rationale. Do NOT edit the spec. |
 
 The previous wisdom: any delta you can't decisively bucket should default to DEFER. The cost of a missed correction is one re-application pass; the cost of a bad correction is shipped.
 
+**DEFER goes to `BACKLOG.md`, not `DECISIONS.md`, and gets no `D` number.** `DECISIONS.md` is for what the project decided to *do*; `BACKLOG.md` is for what it decided to *defer*. A refinement you make while applying a delta — the applied text going beyond the literal proposal — is a decision: record it in the audit file's Decisions Beyond Triage section, and lift it into `DECISIONS.md` only if it is cross-cutting. An existing `D` entry for a proposed delta has its disposition updated in place (`APPLIED 2026-05-03 round-3`); it is never superseded by a new entry when applied.
+
 ## Citation convention
 
 Every applied or clarified delta leaves a citation marker in the spec body so a future reader can trace the change back to its source.

package/.codecarto/templates/backlog-project.md

@@ -0,0 +1,51 @@
+# Backlog
+
+Project-level deferrals: work this project decided **not** to do yet, with the reasoning
+that made deferring the right call. One entry per deferral.
+
+This is the project's backlog, not CodeCartographer's. Items about the framework itself —
+a phase prompt that misled you, a validation criterion that does not fit — belong in
+feedback to the framework, not here.
+
+**BACKLOG vs DECISIONS.** `DECISIONS.md` records what the project decided to **do**;
+this file records what it decided to **defer**. Deferrals get no `D` number. If a deferred
+item is later picked up, remove its entry here and record the decision in `DECISIONS.md`.
+
+## Format
+
+```
+## <ID>. <Short title>
+
+**Raised by:** <closeout file, phase, or DECISIONS.md entry that produced this deferral>
+
+**Why deferred:** <the reasoning — what made this not worth doing now, not just "later">
+
+**Preconditions:** <what has to land before this can be revisited: a module, an artifact,
+a decision, an answer to an open question. "None" is a valid answer, but say so.>
+
+**Smallest viable form:** <the least you could build that would settle the item, so whoever
+picks it up does not have to redesign it from scratch>
+```
+
+## Entries
+
+<!--
+  Append entries below this marker. Number them however the project prefers (B1, B2, … is
+  the convention the framework's own backlog uses).
+
+  Example:
+
+  ## B1. Retry policy for the upload path
+
+  **Raised by:** closeouts/2026-03-14-contracts.md
+
+  **Why deferred:** The contracts phase found no documented retry behavior, but nothing
+  downstream depends on knowing it — the porting phase can treat uploads as at-most-once
+  and flag the gap.
+
+  **Preconditions:** A protocols-phase answer on whether the server deduplicates by
+  request id. Without that, any retry policy written here is a guess.
+
+  **Smallest viable form:** One paragraph in the contracts report stating the observed
+  behavior and the assumption downstream phases should hold.
+-->

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

package/.codecarto/{THREAD_LOG.md → templates/thread-log.md}

@@ -19,8 +19,7 @@ heredoc-vs-edit sync risks that bite append-to-large-file workflows once the fil
 
 Before appending, scan the bottom 5 entries. If you see a line with the same date AND same
 phase-or-module AND same summary, do not append — the prior session already wrote it. The
-framework has no programmatic dedup gate; this is human-discipline. (See
-`Apply 20 spec deltas to Thaumaturge.txt` for the incident that established this rule.)
+framework has no programmatic dedup gate; this is human-discipline.
 
 A one-liner to surface duplicates from the shell:
 
@@ -33,7 +32,5 @@ grep -E '^- [0-9]{4}-[0-9]{2}-[0-9]{2}' .codecarto/THREAD_LOG.md | sort | uniq -
 <!--
   Append one line per session below this marker.
   Example:
-  - 2026-05-02 — framework-feedback-pass — applied 6 spec-blockers + 5 clarifications from FEEDBACK_INDEX.md — [closeout](closeouts/2026-05-02-framework-feedback-pass.md)
+  - 2026-03-14 — architecture — mapped 14 packages across 3 layers; wire formats deferred to protocols — [closeout](closeouts/2026-03-14-architecture.md)
 -->
-
-- 2026-05-02 — framework-feedback-pass — applied 6 spec-blockers + 5 clarifications from FEEDBACK_INDEX.md; 14 deferred to BACKLOG.md — [closeout](closeouts/2026-05-02-framework-feedback-pass.md)