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

[TheAmericanMaker]

Finishes Broad-Side: the surfaces, docs, and pipeline integration that the seven feature PRs left behind, plus the half of multi-model that can be decided without spending money.

Stacked on #153. Base is feat/142-broadside-incremental-rescout so the diff shows only this work — please retarget to main once #153 merges.

What this closes

Commit	Item
9d9c18f	Reading guide reachable + the feature documented
a18d394	Pi extension surface (#138)
d3da986	scout-first pipeline (#139)
fd179e3	Per-lens model overrides (#141, mechanism half)

The defect

.codecarto/broadside/SKILL.md was written but unreachable. codecarto_skill resolves .codecarto/skills/<name>/SKILL.md, so {name: "broadside"} returned "Unknown skill" and codecarto_list_skills never mentioned it. Both surfaces now serve it under the name broadside, exempt from the post-pipeline completion gate — a scout run is read before the pipeline and during it — and readable on a repository with scout state and no workspace.

Pi surface (#138)

/codecarto-broadside [submit|collect|status|models] [lenses…] with tab-completion for actions, lenses, and flags, and a live per-lens progress widget. Two deliberate divergences from MCP:

• The spend decision is interactive. MCP cannot ask a human, so it refuses a run over max_cost until the caller passes force. Pi shows the per-lens breakdown, the rates, and whether the run exceeds the limit — and an approval is the force flag. This needed a confirm hook on runBroadsideSubmit, firing after slicing and before any state write; declining throws BroadsideCancelledError and nothing is submitted. Surfaces with no human omit the hook and keep the old path unchanged.
• No API key argument. A key typed into a slash command lands in the session transcript, so it is OPENROUTER_API_KEY or config.yaml only, and the error says why.

Pipeline phase (#139)

Two constraints shaped this, and neither is what the roadmap item assumed:

• A required_reads entry must be an upstream phase's primary_output, and run directories are timestamped and gitignored — so no pipeline YAML can ever name broadside/<run>/synthesis.md. The broadside-scout phase therefore distills: it reads what a prior run wrote and produces one stable artifact, findings/broadside-scout/scout-brief.md. That indirection is also where the judgment lives — deciding which leads are worth six phases' attention is not a file copy.
• status.yaml phases must match phase_order exactly, so a phase cannot be optional. Scouting ships as its own variant (pipeline-scout-first.yaml, alias scout-first) rather than as a toggle on the default, which would put a paid API scan in front of every run.

Architecture, both defect scans, contracts, protocols, and porting read the brief, and each carries a completion criterion requiring every lead routed to it to be confirmed against the source, dismissed with a reason, or carried forward — never reported as a finding on the brief's authority. That criterion is where "leads, never evidence" stops being a docstring and becomes a gate. reimplementation-spec deliberately does not read it; the porting bundle stays its compression boundary.

The phase never submits a batch and never spends. With no run on disk it writes an explicitly empty brief and the pipeline proceeds exactly as full-with-deep-audit would — which matters because /codecarto-next --auto runs it unattended.

Per-lens models (#141, mechanism only)

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. Each distinct model is resolved and pre-flighted independently, the estimate carries per-lens rates, submission fires from the priced rows rather than recomputing them, and collect's truncation retry re-submits on the lens's own model and ceiling instead of the run default.

Not shipped, on purpose: a stronger default for the semantic lenses. That is a comparative-evaluation question on real repositories with real spend, and choosing one here would spend every user's money on our guess. The config, ROADMAP, and CHANGELOG all say so and point at the models action. Per-model prompt tweaks stay open for the same reason.

Also

• config.yaml gained repo defaults for every per-call run knob (incremental, retry_truncated, include_synthesis, include_triage, wait_seconds) — previously call-parameters only, so a repo could not fix its own scouting policy.
• references/broadside.md in the packaged agent skill, served as the broadside topic of codecarto_guide.
• README section, MANUAL step, MCP-quickstart coverage, in place of a single table row.
• npm run smoke:broadside wires the previously orphaned opt-in live smoke script.

Verification

443 tests pass (was 405), npm run build clean. New invariants worth noting: the documented and parsed config-key sets must match; the extension must register a command for every framework operation; the README table must name every registered command; and pipeline-scout-first.yaml is pinned field-by-field to the deep-audit pipeline it wraps, so the two cannot diverge silently.

🤖 Generated with Claude Code