ledger

<!-- CANONICAL: shared/ledger-reduce.md -->

# Ledger weekly renderer

Renders `docs/ledger/weekly-YYYY-Www.md` from the **central ledger**
`~/.claude/crucible/ledger/runs.jsonl` (override `CRUCIBLE_LEDGER_DIR`; plus
`falsification.jsonl` beside it for the cross-link). The SKILL.md is a thin
prompt wrapper; the source of truth is the testable Python core at
`scripts/render_ledger.py`. Reports are written to `docs/ledger/` relative to
your cwd — run from the crucible repo to update the committed reports.

**Skill type:** Utility — direct execution, no subagent dispatch.

## Trigger

Manual `/ledger [--weeks N]` (default `N=1`, the most recent ISO week).

## What it does

Invoke the renderer directly. Resolve `scripts/render_ledger.py` by **absolute
path** from the plugin root (it self-locates its own modules via `__file__`, so
no `PYTHONPATH` is needed and it runs from any cwd):

```
python3 <plugin_root>/scripts/render_ledger.py --weeks N
```

That command:

1. Reads the central ledger `~/.claude/crucible/ledger/runs.jsonl` (the
   `--ledger` default; `CRUCIBLE_LEDGER_DIR` overrides). **First-time-ever: if
   the file is MISSING, print "no ledger data yet" and exit 0 — do NOT write an
   empty report.**
2. Groups entries by ISO week (`YYYY-Www`).
3. For each of the most-recent `N` weeks, writes `docs/ledger/weekly-YYYY-Www.md`.

## Algorithm summary

- **Tolerant load** (`load_runs`): skips blank / malformed / partial-trailing
  lines, dedups defensively by `(run_id, skill)` latest-position-wins.
- **Honest "caught N" headline** (`caught_count`): counts entries with
  `would_have_shipped_without_gate == true`, **EXCLUDING `backfilled == true`**.
  Backfilled entries carry `severity_histogram: null` ⇒ WHS `null` (the
  mechanical L-3 rule) and are reported in a SEPARATE "Backfilled historical
  context" section — never in the headline (L-5). This is what test T-5 asserts.
- **Per-skill `significant_rate` / `fatal_rate`** (`week_summary`): computed
  **from forward-captured entries only** (`backfilled == false` AND
  `severity_histogram != null`). Raw rates are printed from week 1.
- **Inflation detector (§4a)** (`inflation_alert`): alerts when a skill's
  `significant_rate` or `fatal_rate` exceeds **3× its 4-week rolling median**.
  **Silent for a skill until 4 weeks of forward data exist** (the v1 bootstrap
  — with no forward history yet, the detector is silent, but raw rates still
  print so a human can eyeball drift).
- **Falsified cross-link** (`falsified_count`): the all-time count of falsified
  verdicts via the **L-9 latest-entry-wins reduction** over
  `falsification.jsonl` (`scripts.ledger_reduce.reduce`, the canonical helper
  cited above). **Graceful degradation:** if `falsification.jsonl` is absent
  (Phase 4 reconciler not built yet), the reduction returns `{}` ⇒ count `0`;
  the renderer never crashes.
- **Monthly spot-check (§4a)**: on the first `/ledger` run of a calendar month,
  the report appends an advisory checklist prompting a spot-check of 5 random
  `would_have_shipped_without_gate: true` entries against
  `skills/shared/severity-rubric.md`.

## Commit citations

Design §4 calls for "findings with commit citations". The v1 schema has **no
commit field** (`artifact_hash` is null for backfill). So:

- **Backfilled entries** (`backfill-<PR>-quality-gate`) cite **`PR #<PR>`**,
  extracted from the deterministic `run_id`.
- **Forward entries** (UUIDv7 `run_id`) have no commit in v1 ⇒ the citation is
  omitted gracefully. No SHAs are invented. A future schema rev capturing the
  gating commit can replace this with a real SHA.

## Honest-count rule (binding)

The headline is `would_have_shipped_without_gate == true` **minus backfilled**.
Backfilled entries seed the corpus but never inflate the caught-N number; they
appear only in the separate historical-context section. Inflation drift is
defended structurally (the 3× detector) and culturally (the monthly spot-check).