codecartographer-pi 0.16.0 → 0.17.0

package/.codecarto/workflow/pipeline-scout-first.yaml

@@ -0,0 +1,271 @@
+workflow_name: codebase-reverse-engineering-scout-first
+workflow_version: 1
+workflow_goal: The full deep-audit reverse-engineering run, preceded by a Broad-Side scout phase that distills an existing batch reconnaissance run into a routing brief every later phase reads. Identical to pipeline-full-with-deep-audit.yaml apart from that first phase and the brief each phase must account for.
+source_location: ../
+validation_protocol: workflow/VALIDATE.md
+phase_order:
+  - broadside-scout
+  - architecture
+  - defect-scan-mechanical
+  - contracts
+  - protocols
+  - defect-scan-semantic
+  - porting
+  - reimplementation-spec
+phases:
+  - id: broadside-scout
+    purpose: Distill a completed Broad-Side batch reconnaissance run into a short routing brief that tells each later phase where to look first. Reads only what a prior Broad-Side run already wrote; it never submits a batch and never spends.
+    skill_path: findings/broadside-scout/SKILL.md
+    output_template: templates/broadside-scout-brief.md
+    depends_on: []
+    primary_output: findings/broadside-scout/scout-brief.md
+    secondary_outputs: []
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+    completion_criteria:
+      - Every forwarded lead names a target phase in this pipeline and a source pointer the target phase can start from.
+      - Every lead is marked as an unverified scouting signal; none is stated as a fact or cited as evidence.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots, so unscouted scope is distinguishable from clean scope.
+      - Leads dropped rather than forwarded are recorded with a reason.
+      - Convention candidates are routed to the orchestrator's CONVENTIONS.md review, not to a phase.
+      - When no completed Broad-Side run exists, the brief says so explicitly, forwards no leads, and does not block the pipeline.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
+  - id: architecture
+    purpose: Build the layer map, dependency direction, public surfaces, and high-level system structure.
+    skill_path: findings/architecture/SKILL.md
+    output_template: templates/architecture-map.md
+    depends_on:
+      - broadside-scout
+    primary_output: findings/architecture/architecture-map.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/build-and-deploy/build-and-deploy.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/broadside-scout/scout-brief.md
+    completion_criteria:
+      - Every Broad-Side lead the scout brief routed to this phase is confirmed against the source, dismissed with a reason, or carried forward; none is reported as a finding on the brief's authority alone.
+      - The system intent is documented.
+      - The layer map and dependency direction are documented.
+      - Public surfaces are identified.
+      - Runtime lifecycle, concurrency model, and porting priorities are summarized.
+      - Findings are marked with evidence levels.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
+  - id: defect-scan-mechanical
+    purpose: Early, context-light defect pass covering logic, error handling, and configuration hazards. Runs before contracts so mechanical bugs are surfaced for the contracts and porting phases to reference.
+    skill_path: findings/defect-scan-mechanical/SKILL.md
+    output_template: templates/mechanical-defects.md
+    depends_on:
+      - broadside-scout
+      - architecture
+    primary_output: findings/defect-scan-mechanical/mechanical-defects.md
+    secondary_outputs: []
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/broadside-scout/scout-brief.md
+      - findings/architecture/architecture-map.md
+    completion_criteria:
+      - Every Broad-Side lead the scout brief routed to this phase is confirmed against the source, dismissed with a reason, or carried forward; none is reported as a finding on the brief's authority alone.
+      - At least two of the three mechanical passes (1, 2, 6) produced findings or documented "no defects found."
+      - Each finding has location, severity, evidence level, and recommended action.
+      - Findings are organized by pass and sorted by severity.
+      - Summary tables are complete and counts match the detailed findings.
+      - Items spotted that are actually semantic in nature are routed onward via a carry_forward entry in the phase handoff targeting defect-scan-semantic.
+      - Findings are marked with evidence levels.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
+  - id: contracts
+    purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
+    skill_path: findings/contracts/SKILL.md
+    output_template: templates/behavioral-contracts.md
+    depends_on:
+      - broadside-scout
+      - architecture
+    primary_output: findings/contracts/behavioral-contracts.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/broadside-scout/scout-brief.md
+      - findings/architecture/architecture-map.md
+      - findings/defect-scan-mechanical/mechanical-defects.md
+    completion_criteria:
+      - Every Broad-Side lead the scout brief routed to this phase is confirmed against the source, dismissed with a reason, or carried forward; none is reported as a finding on the brief's authority alone.
+      - User-facing surfaces are split by surface type.
+      - Feature contracts record trigger, defaults, outputs, side effects, persisted state, error behavior, and recovery behavior.
+      - Security and authorization model is documented (if applicable).
+      - Contract ownership is mapped back to a layer or package.
+      - A black-box acceptance list is included.
+      - Findings are marked with evidence levels.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
+  - id: protocols
+    purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
+    skill_path: findings/protocols/SKILL.md
+    output_template: templates/protocols-and-state.md
+    depends_on:
+      - broadside-scout
+      - architecture
+    primary_output: findings/protocols/protocols-and-state.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/broadside-scout/scout-brief.md
+      - findings/architecture/architecture-map.md
+      - findings/defect-scan-mechanical/mechanical-defects.md
+    completion_criteria:
+      - Every Broad-Side lead the scout brief routed to this phase is confirmed against the source, dismissed with a reason, or carried forward; none is reported as a finding on the brief's authority alone.
+      - An event catalog is documented.
+      - A state machine is documented.
+      - Persistent schema notes are documented.
+      - Compatibility hazards are documented.
+      - Findings are marked with evidence levels.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
+  - id: defect-scan-semantic
+    purpose: Deep, context-rich defect pass covering concurrency, security, and API contract violations. Runs after protocols so contracts/protocols context is available, and before porting so the porting phase can synthesize all defects with full understanding of the system.
+    skill_path: findings/defect-scan-semantic/SKILL.md
+    output_template: templates/semantic-defects.md
+    depends_on:
+      - broadside-scout
+      - architecture
+      - contracts
+      - protocols
+      - defect-scan-mechanical
+    primary_output: findings/defect-scan-semantic/semantic-defects.md
+    secondary_outputs: []
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/broadside-scout/scout-brief.md
+      - findings/architecture/architecture-map.md
+      - findings/contracts/behavioral-contracts.md
+      - findings/protocols/protocols-and-state.md
+      - findings/defect-scan-mechanical/mechanical-defects.md
+    completion_criteria:
+      - Every Broad-Side lead the scout brief routed to this phase is confirmed against the source, dismissed with a reason, or carried forward; none is reported as a finding on the brief's authority alone.
+      - All three semantic passes (3, 4, 5) produced findings or documented "no defects found."
+      - Each finding has location, severity, evidence level, and recommended action.
+      - Pass 5 findings cite the contract or protocol reference they violate.
+      - Findings are organized by pass and sorted by severity; summary tables match the detailed findings.
+      - Any carry_forward entries that targeted defect-scan-semantic have been resolved or explicitly re-routed.
+      - Findings are marked with evidence levels.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
+  - id: porting
+    purpose: Synthesize architecture, contracts, protocols, and both defect passes into a reverse-engineering bundle oriented toward porting. Fill the Defect Synthesis section by consolidating mechanical-defects.md and semantic-defects.md into a single porting-oriented view.
+    skill_path: findings/porting/SKILL.md
+    output_template: templates/reverse-engineering-bundle.md
+    depends_on:
+      - broadside-scout
+      - architecture
+      - contracts
+      - protocols
+      - defect-scan-mechanical
+      - defect-scan-semantic
+    primary_output: findings/porting/reverse-engineering-bundle.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/build-and-deploy/build-and-deploy.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/broadside-scout/scout-brief.md
+      - findings/architecture/architecture-map.md
+      - findings/contracts/behavioral-contracts.md
+      - findings/protocols/protocols-and-state.md
+      - findings/defect-scan-mechanical/mechanical-defects.md
+      - findings/defect-scan-semantic/semantic-defects.md
+    completion_criteria:
+      - Every Broad-Side lead the scout brief routed to this phase is confirmed against the source, dismissed with a reason, or carried forward; none is reported as a finding on the brief's authority alone.
+      - The system summary, layer map, contract table, protocol notes, and porting findings are synthesized.
+      - Portability hazards and open questions are separated from facts.
+      - Feature importance is sorted for porting.
+      - Defect Synthesis consolidates mechanical-defects.md and semantic-defects.md with porting recommendations (fix before porting / port differently / leave behind).
+      - Findings are marked with evidence levels.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
+      - The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.
+  - id: reimplementation-spec
+    purpose: Produce the final language-agnostic reimplementation plan and acceptance spec. The Strategic Alignment Hook in GUIDE.md decides between the default and opinionated template variants.
+    skill_path: findings/reimplementation-spec/SKILL.md
+    output_template: templates/reimplementation-spec.md
+    depends_on:
+      - porting
+    primary_output: findings/reimplementation-spec/reimplementation-spec.md
+    secondary_outputs: []
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/porting/reverse-engineering-bundle.md
+    completion_criteria:
+      - Concept-level modules are defined.
+      - Required behaviors are stated.
+      - Protocol and persisted state expectations are stated.
+      - Acceptance scenarios and known unknowns are included.
+      - Defects identified in either scan are explicitly designed-around or noted as "left behind", with the choice cited.
+      - Findings are marked with evidence levels.
+      - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
+      - Lower-level findings are deep-read only when the porting bundle identifies a gap, conflict, missing acceptance detail, or defect rationale.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Write the phase handoff to scratch/handoffs/<phase>.yaml with owner notes, open questions, and carry-forward routings; completion applies it to workflow/status.yaml.
+      - Provide closeout_summary and optional closeout_content in the handoff; completion writes the closeout and THREAD_LOG.md entry.

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

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

package/README.md

@@ -239,6 +239,7 @@ The default is a 7-phase run that splits the defect scan into a mechanical early
 | Variant | Phases | Use when |
 |---|---|---|
 | **Full with deep audit** (default) | 7 | Complete analysis with split defect scan; reimplementation grounded in contracts/protocols-aware defect findings |
+| **Scout first** | 8 | The deep-audit run preceded by a `broadside-scout` phase that distills an existing [Broad-Side](#broad-side-batch-reconnaissance) run into a routing brief every later phase reads |
 | **Full with audit** | 6 | Single early defect scan; cheaper than the deep variant when defects are mostly mechanical |
 | **Full** | 5 | Porting or reimplementation without any defect scan |
 | **Defect scan** | 2 | Maintenance audit to surface latent problems |
@@ -253,6 +254,7 @@ Switch the active pipeline with `/codecarto-switch-pipeline <variant>` (Pi) or `
 | Variant | Pipeline file |
 |---|---|
 | Full with deep audit (**default**) | `workflow/pipeline-full-with-deep-audit.yaml` |
+| Scout first | `workflow/pipeline-scout-first.yaml` |
 | Full with audit | `workflow/pipeline-full-with-audit.yaml` |
 | Full | `workflow/pipeline.yaml` |
 | Defect scan | `workflow/pipeline-defect-scan.yaml` |
@@ -318,7 +320,8 @@ Beyond the slash commands, the Pi extension layers on:
 | `/codecarto-phase <id>` | Force a specific phase, even out of pipeline order |
 | `/codecarto-validate [phase]` | Validate a phase output against completion criteria |
 | `/codecarto-complete [phase]` | Validate and atomically apply the phase handoff, canonical status, closeout, and log entry |
-| `/codecarto-skill <name>` | Run a post-pipeline skill once all phases are complete |
+| `/codecarto-skill <name>` | Run a post-pipeline skill once all phases are complete (or `broadside` any time, for the scout reading guide) |
+| `/codecarto-broadside [action] [lenses…]` | Batch reconnaissance (Broad-Side). Actions: `submit`, `collect`, `status`, `models`. Prices the run and asks before spending; works with or without a workspace |
 | `/codecarto-publish` | Publish the reimplementation spec to the configured library after reviewing an explicit confirmation preview |
 | `/codecarto-library-init <path> [--namespace <name>]` | Create a library directory with marker and write the config — fixes the first-publish dead end |
 | `/codecarto-config` | Show the effective merged configuration (global + workspace) and library marker status |
@@ -348,20 +351,61 @@ Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/spec
 | Tool | Pi equivalent |
 |---|---|
 | `codecarto_init` | `/codecarto-init` |
+| `codecarto_open` | `/codecarto-open` |
+| `codecarto_vision` | `/codecarto-vision` |
 | `codecarto_status` | `/codecarto-status` |
+| `codecarto_switch_pipeline` | `/codecarto-switch-pipeline` |
 | `codecarto_next` | `/codecarto-next` |
 | `codecarto_phase` | `/codecarto-phase` |
 | `codecarto_validate` | `/codecarto-validate` |
 | `codecarto_complete` | `/codecarto-complete` |
 | `codecarto_skill` | `/codecarto-skill` |
-| `codecarto_publish` | MCP-only library publish |
+| `codecarto_list_skills` | MCP-only ([#161](https://github.com/HuginnIndustries/CodeCartographer/issues/161)); Pi lists skills when `/codecarto-skill` runs with no argument |
+| `codecarto_publish` | `/codecarto-publish` |
+| `codecarto_library_init` | `/codecarto-library-init` |
 | `codecarto_library_list` | MCP-only library listing |
 | `codecarto_library_reindex` | MCP-only library reindex |
+| `codecarto_config` | `/codecarto-config` |
+| `codecarto_usage` | `/codecarto-usage` |
+| `codecarto_dashboard` | `/codecarto-dashboard` |
+| `codecarto_guide` | MCP-only ([#160](https://github.com/HuginnIndustries/CodeCartographer/issues/160)) |
+| `codecarto_amend` | MCP-only ([#157](https://github.com/HuginnIndustries/CodeCartographer/issues/157)) |
+| `codecarto_refresh_scaffold` | MCP-only ([#159](https://github.com/HuginnIndustries/CodeCartographer/issues/159)) |
+| `codecarto_broadside` | `/codecarto-broadside` |
 
 Each workflow tool accepts an absolute `cwd` for the target repository. `codecarto_init` requires `force: true` to overwrite an existing `.codecarto/` (instead of Pi's interactive confirmation). The library tools accept an explicit absolute `library_path` or resolve `library.path` from `.codecarto/workflow/config.yaml` / `~/.codecarto/config.yaml`. The library schema is experimental and may break before v2.
 
 ---
 
+## Broad-Side (batch reconnaissance)
+
+Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`).
+
+**Broad-Side findings are unverified scouting leads, not evidence.** Each lens is one shot: no cross-file traversal, no runtime verification, no builds, no tests. Every finding is a `file:line` pointer that the interactive pipeline — or you — must confirm before it is a fact. That division of labor is the point: a sub-dollar unattended sweep that tells the expensive run where to look. Nothing downstream may cite a Broad-Side report as a source.
+
+It runs on any git repository — no initialized workspace required — and needs an OpenRouter API key (`api_key` parameter, `OPENROUTER_API_KEY` environment variable, or `api_key` in `.codecarto/broadside/config.yaml`).
+
+```
+codecarto_broadside {cwd, action: "models"}                   # compare batch models and pricing
+codecarto_broadside {cwd, action: "submit", lenses: [...]}    # fire the batches, priced first
+codecarto_broadside {cwd, action: "status"}                   # what is in flight
+codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize, triage
+```
+
+Submit and collect are separate because batch jobs routinely take tens of minutes; collect is resumable and picks up whatever is still in flight. Submit prices the run from the collected file sizes against the model's live per-token pricing (cached 24h) and refuses when the estimate exceeds `max_cost` unless `force: true` is passed — a pre-flight estimate, not a runtime stop. Actual spend lands in each run's `run-meta.json`.
+
+Repository defaults live in `.codecarto/broadside/config.yaml` (`model`, `api_key`, `default_lenses`, `max_cost`, `pricing` overrides, `lens_models`, `incremental`, `retry_truncated`, `include_synthesis`, `include_triage`, `wait_seconds`); an explicit tool parameter always wins. `lens_models` routes individual lenses to their own batch model — a stronger model changes security and defect findings far more than it changes an architecture map — and each override is priced, capability-checked, and clamped exactly like the default, with the estimate broken out per lens so a mixed-model run cannot be approved without seeing which lens costs what. CodeCartographer ships no stronger default: which model earns its price depends on your repository and budget, so compare candidates with the `models` action and choose. `codecarto_skill {cwd, name: "broadside"}` returns the reading guide for a completed run, and unlike post-pipeline skills it is not gated on a finished pipeline.
+
+On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models] [lenses…]`, with tab-completion for actions and lens names and live per-lens progress while batches poll. The two surfaces differ in one deliberate place: MCP cannot ask a human, so it refuses a run over `max_cost` until you pass `force`; Pi shows the per-lens breakdown and asks, and your approval *is* the force flag. Neither surface takes an API key as a command argument — a key typed into a slash command lands in the session transcript.
+
+Broad-Side needs runtime code, so firing a run is an executable-surface feature: Pi and MCP have it, the pure drop-in template does not (it carries only the reading guide).
+
+**Feeding a run into the pipeline** is the `scout-first` variant. Its first phase, `broadside-scout`, distills a completed run into `findings/broadside-scout/scout-brief.md` — a short list of leads, each routed to a specific later phase with the source pointer that phase should start from. Six later phases read the brief, and each must account for the leads addressed to it at validation: confirmed against the source, dismissed with a reason, or carried forward. None may be reported as a finding on the brief's authority. The scout phase itself never submits a batch and never spends; with no run on disk it writes an explicitly empty brief and the pipeline proceeds unchanged.
+
+The indirection is deliberate. Run directories are timestamped and gitignored, so no pipeline YAML could name one as a `required_reads` path; the brief is the stable, reviewable artifact that a phase contract can point at — and distilling into it is where the "which of these is worth anyone's attention" judgment happens.
+
+---
+
 ## Compatible environments
 
 | Environment | Recommended surface |
@@ -506,6 +550,7 @@ If you're testing a new model, start with `pipeline-architecture-only.yaml` on a
   scratch/                   # Disposable notes plus checkpoints and structured phase handoffs.
   templates/                 # Output structure templates.
   workflow/                  # Pipeline definitions, status, validation, config.
+  broadside/                 # Broad-Side batch reconnaissance: config, state, run results.
   closeouts/                 # Per-session closeout files.
   THREAD_LOG.md              # Cross-session summary log.
   dashboard.html             # Generated; gitignored.

package/agent-skill/codecartographer/SKILL.md

@@ -38,6 +38,7 @@ codecarto_status  →  codecarto_init (first time only)
              status reports "complete"
 ```
 
+0. **`codecarto_broadside`** — optional, and only worth it on a repository too large to read directly. A cheap batch reconnaissance sweep that produces unverified leads telling the pipeline where to look, before you commit to a pipeline choice. Costs real money and is priced before it fires — `references/broadside.md`.
 1. **`codecarto_status`** — always start here. It reports the active pipeline, progress, next action, and any scaffold-staleness warning. Every tool takes an absolute `cwd` pointing at the target repository.
 2. **`codecarto_init`** — only when no `.codecarto/` exists. Choose the pipeline deliberately (see `references/pipeline-selection.md`). Never pass `force: true` without the user's explicit approval; it moves an existing workspace, findings and all, to a backup directory.
 3. **`codecarto_next`** — returns the prompt for the next eligible phase. It returns *text*; it does not execute anything. Use `codecarto_phase` only to force a specific phase out of order, and only when the user asked for that.
@@ -46,7 +47,7 @@ codecarto_status  →  codecarto_init (first time only)
 6. **`codecarto_validate`** — parses the validation block you appended to the primary output. Returns `PASS`, `PASS WITH GAPS`, `FAIL`, or `MISSING`.
 7. **`codecarto_complete`** — marks the phase done, applies your handoff to canonical state, and writes the closeout and `THREAD_LOG.md` entry. It refuses anything worse than `PASS WITH GAPS`.
 
-When `codecarto_status` reports all phases complete, post-pipeline skills become available via `codecarto_list_skills` and `codecarto_skill`.
+When `codecarto_status` reports all phases complete, post-pipeline skills become available via `codecarto_list_skills` and `codecarto_skill`. One name that tool answers to is exempt from that gate: `codecarto_skill {name: "broadside"}` returns the reading guide for a batch reconnaissance run, which is meant to be read *before* the pipeline and during it.
 
 ## The handoff contract
 
@@ -133,6 +134,7 @@ If the goal is to rebuild or refactor rather than to understand, two phases carr
 
 Running the pipeline:
 
+- `references/broadside.md` — batch reconnaissance: when to scout, cost guardrails, and why its findings are leads rather than evidence
 - `references/orchestration.md` — the orchestrator's duties, inline vs delegated execution, and the session-by-session fallback's real costs
 - `references/pipeline-selection.md` — choosing a variant, and switching without losing work
 - `references/executors.md` — the executor contract, adapters, and model selection

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

@@ -0,0 +1,115 @@
+# Broad-Side: scouting a repository before you spend on it
+
+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 a repository as single-turn prompts
+over the OpenRouter Batch API, then cross-references them into one executive
+report and a prioritized work order.
+
+It is not a phase, and it does not replace one. It is the cheap sweep that
+tells the expensive interactive run where to look.
+
+## Leads, never evidence
+
+Every Broad-Side finding is an **unverified scouting signal**. Each lens is one
+shot: no cross-file traversal, no runtime verification, no builds, no tests, no
+follow-up questions. The batch model is chosen for price, not strength.
+
+This is the rule the whole feature rests on: a finding is a `file:line` lead
+that a phase — or you — must confirm against the source before it is a fact.
+Cite the source you confirmed it from, never the Broad-Side report. A "high"
+you can neither confirm nor dismiss becomes an open question in your handoff,
+not a finding in your report.
+
+## When to fire it
+
+- **Before `codecarto_init`,** on a repository nobody on the team knows. The
+  synthesis report is a map of where the risk sits, which makes the pipeline
+  choice an informed one instead of a guess.
+- **Before an expensive phase,** when the repository is large enough that the
+  architecture or defect phases would otherwise read blind.
+- **Not at all,** when the repository is small enough to read directly. A sweep
+  that costs more than the reading it saves is waste.
+
+It works on any git repository — no workspace required — and `codecarto_init`
+tolerates a `.codecarto/` that holds nothing but scout state.
+
+## Driving it
+
+```
+codecarto_broadside {cwd, action: "models"}                    # compare batch models first
+codecarto_broadside {cwd, action: "submit", lenses: [...]}     # fire the batches
+codecarto_broadside {cwd, action: "status"}                    # what is in flight
+codecarto_broadside {cwd, action: "collect"}                   # poll, save, synthesize, triage
+```
+
+(The Pi extension exposes the same four actions as `/codecarto-broadside <action> [lenses…]`.)
+
+Submit and collect are separate on purpose: batch jobs routinely take tens of
+minutes, and nothing is lost by returning between them. Pass `wait_seconds` to
+poll inline when you would rather block. Collect is resumable — call it again
+and it picks up the batches the recorded state still lists as in flight.
+
+Requires an OpenRouter API key via the `api_key` parameter, the
+`OPENROUTER_API_KEY` environment variable, or `api_key` in
+`.codecarto/broadside/config.yaml`.
+
+## Cost is a first-class parameter
+
+Submit prices the run before it fires: it estimates from the collected file
+sizes against the model's live per-token pricing (cached 24h) and refuses when
+the estimate exceeds `max_cost`, printing the per-lens breakdown. `force: true`
+overrides. This is a pre-flight estimate, not a runtime stop — actual spend
+lands in the run's `run-meta.json`.
+
+**Never pass `force: true` on the user's behalf without telling them what the
+estimate was.** The guardrail exists because the expensive end of the batch
+model catalog runs past $80 per million output tokens. On MCP the refusal is
+the only protection there is — the server cannot ask, which is exactly why
+`force` must be the user's decision rather than your retry. (Pi has a human to
+ask, so it shows the breakdown and prompts instead of refusing.)
+
+Two more economies worth knowing:
+
+- `incremental: true` diffs against the previous run's git HEAD and scans only
+  the modules whose files changed, falling back to a full scan on a dirty tree.
+- Every knob above has a repository default in `.codecarto/broadside/config.yaml`
+  (`model`, `default_lenses`, `max_cost`, `lens_models`, `incremental`,
+  `retry_truncated`, `include_synthesis`, `include_triage`, `wait_seconds`). An
+  explicit parameter on the call always wins.
+- `lens_models` runs individual lenses on their own model. Spending more on the
+  security and defect lenses while the cheap default carries architecture and
+  conventions is usually a better trade than raising the model for everything.
+  Overrides are priced and capability-checked individually, and the estimate
+  breaks cost out per lens.
+
+## Reading a run
+
+Results land in `.codecarto/broadside/<run>/`. Read them in this order:
+
+1. `synthesis.md` — executive summary, severity counts, top cross-lens
+   findings, per-module risk.
+2. `triage.md` — the same findings scored by impact × difficulty into a P0–P3
+   work order with effort estimates. A starting point for re-verification, not
+   a commitment.
+3. The per-lens `*.json` / `*.md` behind whatever matters to the phase you are
+   about to run: `architecture-*` seeds the architecture phase, `api-*` the
+   contracts and protocols phases, `security-*` and `defect-*` the defect
+   scans, `conventions-*` the convention candidates, `porting-*` the porting
+   phase.
+4. `run-meta.json` — scope: which lenses ran, at what cost, with what coverage
+   caps.
+
+`codecarto_skill {cwd, name: "broadside"}` returns the full reading guide.
+Unlike post-pipeline skills, that one is not gated on a completed pipeline,
+because a scout run is meant to be read before the pipeline and during it.
+
+## Coverage is spoken, not implied
+
+- A lens output whose JSON does not parse is saved verbatim and marked
+  `truncated`. The collect summary counts it, `run-meta.json` records it, and
+  the synthesis prompt is told that module is unrepresented — not clean. By
+  default a truncated slice is resubmitted once with a doubled output cap.
+- A skipped lens, a capped slice, and unscanned scope are all reported. Scope
+  outside the sweep is **unscouted, not clean**, and saying otherwise in a phase
+  report is the one way Broad-Side can actively mislead a run.

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

@@ -25,7 +25,7 @@ The moment `reimplementation-spec` completes and validates is the publish moment
 codecarto_publish cwd:<workspace repo> source_repo:<repo URL or path> headline:"<one line>" spec_path:<abs path to reimplementation-spec.md>
 ```
 
-Set `publish_confirm` in config if you want an explicit confirmation gate before writes.
+Set `publish_confirm` in config if you want an explicit confirmation gate before writes. **Pi-only today:** the Pi extension asks for interactive confirmation before `/codecarto-publish` writes; the MCP `codecarto_publish` tool does not act on the key (an MCP host has no one to ask — [#162](https://github.com/HuginnIndustries/CodeCartographer/issues/162) tracks whether it should refuse-unless-forced instead), so on MCP treat it as advisory.
 
 ## What this is not
 

package/agent-skill/codecartographer/references/pipeline-selection.md

@@ -10,6 +10,7 @@ Pass an alias to `codecarto_init` as `pipeline`. The default is `full-with-deep-
 | `full` | architecture → contracts → protocols → porting → reimplementation-spec | porting or rewriting, no defect audit |
 | `full-with-audit` | adds a single defect-scan after architecture | porting, with defects surfaced once |
 | `full-with-deep-audit` *(default)* | splits the scan: mechanical after architecture, semantic after protocols | porting or rewriting where correctness matters |
+| `scout-first` | `full-with-deep-audit` behind a `broadside-scout` brief | a repository large enough that a Broad-Side sweep already ran and should steer the phases |
 | `synthesis` | vision-capture → goal-synthesis-propose → spec-merge → goal-synthesis-finalize | forward synthesis of a *new* product, not reverse-engineering |
 
 ## Deep audit versus plain audit
@@ -23,6 +24,19 @@ The mechanical pass routes anything it cannot settle locally to the semantic pas
 
 Choose `full-with-audit` when one combined pass is enough and you want fewer phases. Choose `full-with-deep-audit` when the output will drive a rewrite, since a semantic pass without protocols context will miss the findings that most change a port.
 
+## Scout-first needs a scout run
+
+`scout-first` is `full-with-deep-audit` with one phase in front: `broadside-scout`
+distills a completed Broad-Side batch reconnaissance run into a routing brief,
+and the six phases after it read that brief and must account for the leads
+addressed to them — confirmed, dismissed with a reason, or carried forward.
+See `references/broadside.md` for the sweep itself.
+
+The scout phase never submits a batch and never spends; it reads only what a
+prior run wrote. Choosing this variant without having run Broad-Side gets you an
+explicitly empty brief and, from there on, exactly `full-with-deep-audit`. So
+fire the sweep first, or choose the plain deep-audit variant.
+
 ## Synthesis is a different workspace
 
 The `synthesis` pipeline plans a new product from a vision brief and a library of reusable specs. It does **not** treat the surrounding repository as source evidence. It has preflight gates: a completed `inputs/vision.md`, a valid non-empty library, and — for merge and finalization — at least one human-confirmed selection. `codecarto_vision` runs the guided interview that produces the brief.