feat(reports): the per-loop PI report — a 1–2 page LaTeX state-of-campaign filled from the ledger at every loop boundary

[aarontrowbridge]

---

type: issue-draft
repo: harmoniqs/amicode
tier: standard
date: 2026-10-03

Important

Problem — The PI's only legible surface for an autonomous research loop is the raw session/campaign ledger: append-only, nine sections, unbounded. Reading campaign state at a glance is impossible, and catching mistakes means re-parsing the whole record every time. The parked amicissimo implementation proved the build mechanics (tectonic, page cap, best-effort degradation) but its content model was too thin — it dropped hypothesis text and evidence entirely — and too brittle, parsing one ledger shape while real campaigns come in two (vault session ledger, project campaign ledger).
Approach — A 1–2 page LaTeX report filled by the agent at every loop boundary, rendered through tectonic. The director fills fixed template slots from the ledger: this loop's adjudications (one-line hypothesis, verdict, headline number with legs named, provenance stamp), a rolling one-line digest of still-open hypotheses, in-flight work, needs-you, and the next queue. A mechanical gate asserts the page cap, slot presence, and provenance — every number in an adjudication row must appear verbatim in the source ledger. This supersedes amicissimo #478's mechanical-projection doctrine: the agent composes within the template, but cannot launder numbers (verbatim copies + provenance stamps + the gate). Best-effort by construction: a report failure is a receipt line, never a loop pause.
Approaches considered — Pure mechanical markdown→LaTeX projection (#478's shape: rejected — too thin and shape-brittle, as shown against two real campaigns); LLM free-form summary (rejected — no anti-gaming guardrails, no provenance); HTML/markdown-only output (rejected — the vault/paper ecosystem is LaTeX-first and the report must compose into paper workflows).
Scope — in: the template, the per-slot fill contract, the build+gate script, synthetic fixtures for both ledger shapes, example renders · out: the side-panel viewer (follow-up issue), the loop-close cadence wiring (director-core amendment, follow-up), Slack delivery.
Assumptions — tectonic 0.15.0 is the pinned builder; the two ledger shapes above are the input universe; the repo is public, so fixtures are synthetic and no real campaign data is ever committed.

Acceptance Criteria

• Template builds through tectonic within a 1–2 page cap for both fixture ledger shapes (a mid-campaign loop delta and a closed-campaign final report)
• Every number in an adjudication row carries a provenance stamp, and the gate fails if the stamped string does not appear verbatim in the source ledger
• Slot-presence check: a render missing a required slot fails the gate
• Over-cap is a red with a mechanical demotion ladder (digest lines collapse to counts first, queue to top-3), never a silent truncation
• A missing toolchain degrades to the markdown projection + a receipt line, exit 0 — the loop never waits on the report
• Fixtures are synthetic; no real campaign/research data committed

Testing Decisions

A pytest suite for the gate script (build, slot presence, provenance lint, demotion ladder), mirroring the amicissimo test pattern; golden .tex snapshots per fixture shape.

Key Decisions

• Agent-filled template supersedes "never agent-authored prose" (amicissimo BUG: PDF files accepted by library upload but cannot be read by Amico — no upfront warning #477's doctrine) — recorded deliberately, with the replacement guardrails: verdicts and numbers copied verbatim, provenance stamps on every number, mechanical page-cap/slot/provenance gate.
• Content model = loop delta + rolling digest (not a full-ledger mirror): this loop's adjudications, one line per open hypothesis, in-flight work, needs-you, next queue. Enough detail to catch mistakes; concise enough to read in one sitting.
• Page cap 1–2 with the demotion ladder — a hard 1-page cap cannot hold a 26-hypothesis rolling digest.
• Normal LaTeX report styling (article class, booktabs) — deliberately not app-branded; the branded surface is the future side-panel viewer, not the artifact.
• Artifacts land next to the campaign ledger (project ledger reports dir or vault sessions pi dir), with BUG: Input box loses focus and turns yellow when background diagnostics collection completes mid-typing #478's stale-marker pattern: the ledger advancing past the last render marks the report stale.

Constraints & Invariants

• Anti-gaming: verdicts copied verbatim; no number without a source; no LLM judges a fidelity claim — the report surfaces numbers, it never re-derives them.
• Live means live: a stale report is visibly stale, never presented as current.
• The report is a read-only projection: it never writes back to the ledger, the board, or the catalog.

Prior Art

• amicissimo BUG: Input box loses focus and turns yellow when background diagnostics collection completes mid-typing #478's report generator — port the mechanics (tectonic build, stdlib PDF page-count reader, stale markers, best-effort receipts), replace the content model.
• The loop operational contract (amicissimo Fleet Panel: Fleet Profiles CRUD #356, mechanism M3) — the origin spec; its cadence + emission amendments land separately.
• Two real reference ledgers (a research session ledger and a project campaign ledger) — used locally for iteration, never committed.

Source

Supersedes harmoniqs/amicissimo#478; closes its parent amicissimo#477 when this lands.

Notes

amicissimo #478 is closed on this issue's creation with a cross-pointer.