Honor fidelity in burn plans (#108)

[willwashburn]

Summary

• computePlanUsage now annotates each cycle with a fidelity: { confidence, summary } block. confidence === 'high' only when every contributing turn is full or usage-only with both per-turn input and output token coverage; otherwise low. Records without a fidelity field stay best-effort high (matches the codebase's existing pre-Coverage and fidelity metadata: distinguish missing, zero, aggregate-only, and partial usage #41 backward-compat policy). Spend totals continue to include partial / aggregate-only / cost-only contributions — under-counting silently is worse than annotating low-confidence — so spentUsd becomes the lower bound the consumer renders against the new flag.
• burn plans (list view) gains a confidence column when at least one plan has any low-confidence cycle, and a footer note naming the affected plan + lower-bound caveat (note: claude-pro: 3 of 412 turns this cycle lack per-turn token data — totals are a lower bound.). Full-fidelity cycles render exactly as before — no extra column, no footer.
• --json emits a per-plan usage.fidelity: { confidence, summary } block carrying the same FidelitySummary shape summarizeFidelity produces elsewhere.
• PlanUsageFidelity is exported from @relayburn/analyze.

Devin Review fixes + rebase integration

• Added missing root CHANGELOG.md entry for cross-package change (burn plans: honor fidelity (mark monthly spend totals low-confidence on partial usage) #108) — per AGENTS.md, work spanning packages/analyze and packages/cli requires a root-level [Unreleased] entry.
• Rebased on main after PR Migrate burn plans rolling-window usage to archive (#91) #131 (plans-from-archive) landed, resolving CHANGELOG + import + test fixture conflicts.
• Wired fidelity into planUsageFromArchive so the archive-backed path emits the same fidelity: { confidence, summary } block as the in-memory path. Queries attribution_fidelity / tokens_present / cost_present columns from the archive's turns table and synthesizes Fidelity objects matching the ledger's synthesizeFidelity logic. Added the three fidelity columns to the test fixture DDL.

Rebase consideration for PR #131

PR #131 (issue #91) is migrating burn plans to read from archive.sqlite. Resolved — PR #131 has landed and this branch is rebased on top of it. The fidelity annotation flows through both the in-memory and archive-backed paths.

Review & Testing Checklist for Human

• Verify root CHANGELOG.md entry reads well as a release note
• Verify the archive fidelity integration matches the ledger's synthesizeFidelity semantics
• Confirm the 3 additional Devin Review findings visible in the Devin Review UI are addressed or acceptable

Notes

• pnpm run build — clean
• All 32 analyze plan-usage tests pass (23 in-memory + 9 archive parity)
• The branch is cleanly rebased on current main (includes Migrate burn plans rolling-window usage to archive (#91) #131)

Test plan

• pnpm run build clean.
• All analyze plan-usage tests pass (32 total: 23 in-memory + 9 archive parity).
• New analyze tests cover: high-confidence cycle (all full), high-confidence cycle (usage-only with both axes), high-confidence cycle for unknown-fidelity (older ledger writers), low-confidence cycle (partial turn), cost-only contributions counted toward spend + flagged low-confidence, empty cycle, and out-of-cycle turns ignored.
• New CLI tests cover: text table omits the column + footer when every cycle is full-fidelity, text table renders the confidence column + footer note when any cycle is low-confidence, and --json emits the usage.fidelity block with the right confidence / summary shape.

Refs

Closes #108 — refs #41, #76 (which shipped summarizeFidelity / hasMinimumFidelity).

Link to Devin session: https://app.devin.ai/sessions/64f0c6f8e1cf4e7aad523f45a21c5aca
Requested by: @willwashburn

---

[devin-ai-integration]

Devin Review found 1 potential issue.

⚠️ 1 issue in files not directly in the diff

⚠️ Missing root CHANGELOG entry for cross-package change (AGENTS.md violation) (CHANGELOG.md:7-11)

This PR touches both packages/analyze (new PlanUsageFidelity type + deriveFidelity logic) and packages/cli (fidelity column + footer in burn plans list view + JSON). AGENTS.md states: "Update [Unreleased] only when the work spans packages or warrants a top-level summary; single-package work belongs only in that package's CHANGELOG." Since the work spans two packages, the root CHANGELOG.md's [Unreleased] section should have an entry for #108, but it does not (CHANGELOG.md:7-11).

View 3 additional findings in Devin Review.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🟡 Analyze CHANGELOG entry placed under already-released [0.31.0] instead of [Unreleased]

The new PlanUsage.fidelity entry is appended under the already-stamped [0.31.0] - 2026-04-27 section (line 15) instead of under [Unreleased] (line 8). The release commit 3164aaf already promoted the previous [Unreleased] block to [0.31.0], leaving [Unreleased] empty. AGENTS.md explicitly states: "Curate [Unreleased] in the relevant per-package packages/*/CHANGELOG.md as you land PRs." The root CHANGELOG.md and packages/cli/CHANGELOG.md correctly place their entries under [Unreleased], making this inconsistent. As written, the entry falsely claims the feature shipped in 0.31.0, and the publish workflow won't pick it up for the next release since it only promotes the [Unreleased] block.

Prompt for agents

The new changelog entry for PlanUsage.fidelity (issue #108) was added under the already-released [0.31.0] section at line 15 of packages/analyze/CHANGELOG.md. Per the AGENTS.md convention, new work should be placed under the [Unreleased] section (currently empty at line 8). Move the bullet from under [0.31.0] to under [Unreleased] with an ### Added subsection, matching how the root CHANGELOG.md and packages/cli/CHANGELOG.md handle the same feature's entry.

---

Was this helpful? React with 👍 or 👎 to provide feedback.