napkin-math: wire prior-baseline ledger into Stage 0 reruns

[neoneye]

Summary

• Stage 0 of the napkin-math pipeline now passes a prior parameters.json into prepare_extract_input.py --prior so the extract LLM actually sees the # Prior Signal Ledger that PR napkin-math: prior-signal ledger orchestration for extract skill (proposal 141 PR 3) #753 (napkin-math: prior-signal ledger orchestration for extract skill (proposal 141 PR 3) #753) added rules for.
• All five edits are documentation + tests; no production-Python behaviour change. prepare_extract_input.py --prior already existed; the wiring change is teaching the orchestrator (and any agent invoking the extract skills standalone) to use it.
• Path-Forward item 1 from experiments/napkin_math/docs/20260522_plan.md. Items 2–6 explicitly out of scope.

Why

PR #753 told the extract LLM to record dropped_signals with origin: "prior_baseline" when a Prior Signal Ledger is present in the digest. The discipline existed, but no orchestration ever supplied the ledger:

$ grep -c 'Prior Signal Ledger' experiments/napkin_math/output/v58/*/extract_parameters_input.md
…/20260516_datacenter_in_france/extract_parameters_input.md:0
…/20260201_yellowstone_evacuation/extract_parameters_input.md:0
…/20251114_paperclip_automation/extract_parameters_input.md:0
… (every v58 plan: 0)
…/v57a_paperclip_priorledger/extract_parameters_input.md:1   ← the one experimental run

That regression — 124 unexplained absent signals in the v49 → v58 source-preservation audit — is the load-bearing observation in the 2026-05-22 plan reset.

Changes (5 files, +169/-3)

File	What changed
.claude/skills/run-napkin-math-pipeline/SKILL.md	Stage 0 dispatch row + command block show --prior; new "Prior-baseline context for reruns" subsection makes it mandatory when a prior version exists for the slug; Inputs scenario (a) and resume-mode decision table updated.
.claude/skills/extract-parameters-from-digest/SKILL.md	One-paragraph pointer so a standalone invocation knows the ledger is upstream-controlled by --prior.
.claude/skills/extract-parameters-from-full/SKILL.md	Same pointer for the full-report extract path.
prepare_extract_input.py	Module docstring documents --prior as the wiring point. No behaviour change.
tests/test_prepare_extract_input_prior_ledger.py	Three new CLI-level tests: main() with --prior (ledger lands in digest), without --prior (digest stays clean), and with a non-existent prior path (loud SystemExit). Locks the orchestration contract.

Acceptance evidence

CLI demo (out-of-tree, with run_compress monkey-patched so it doesn't need worker_plan):

=== ACCEPTANCE EVIDENCE ===
With --prior:    '# Prior Signal Ledger' appears 1x
With --prior:    'demo_signal' appears        1x
Without --prior: 'Prior Signal Ledger' appears 0x

Test suite:

146 passed, 6 subtests passed in 0.41s

Out of scope

Documented for follow-up, not implemented here:

• Path-Forward item 2 — strict-mode source-preservation audit gate. The wiring this PR ships is the necessary precondition; a strict policy that fails v49 → v58 is the next PR.
• Auto-discovery of the most-recent prior in prepare_extract_input.py (e.g. a --auto-prior flag scanning output/v*/<slug>/). Considered and rejected for this PR: explicit is clearer than implicit, and the orchestrator can already resolve the prior path. If future runs keep forgetting --prior, revisit.
• Items 3–6 (deterministic gate selection, corpus regression report, regenerated snapshot, methodology backlog) — orthogonal to this wiring.

Test plan

• pytest experiments/napkin_math/tests/ — 146 passed
• pytest experiments/napkin_math/tests/test_prepare_extract_input_prior_ledger.py -v — 15 passed (12 existing + 3 new CLI-level)
• CLI demo above: ledger present with --prior, absent without it, loud failure on bad path
• Reviewer to spot-check the run skill's "Prior-baseline context for reruns" subsection for clarity (this is the load-bearing doc; a clear rule that agents will actually follow is the whole point)

🤖 Generated with Claude Code

[neoneye]

Addressed both review items in 1cab128.

P1 (blocking) — closed. Replaced the "Resume mode" carve-out with a mandatory Stage 1 preflight that applies regardless of whether Stage 0 just ran or is being resumed:

grep -q '# Prior Signal Ledger' $D/extract_parameters_input.md

When a prior baseline exists and that grep returns non-zero, the orchestrator MUST stop and offer two resolutions:

1. Delete the digest and re-run Stage 0 with --prior <baseline>/<slug>/parameters.json. The pinned-digest cardinal rule explicitly does not apply when the digest is being repaired for missing ledger.
2. Write $D/.no_prior_waiver with a one-line reason. The waiver file is the only path that lets Stage 1 proceed with absent ledger when a prior exists.

I also retracted the contradicting "treat absent-ledger as first-iteration" line from both extract SKILL.md files. Absent-ledger is now declared ambiguous on its own; the orchestrator disambiguates via the preflight. Standalone invocations of the extract skill must confirm no prior accepted baseline exists for the slug, or stop and ask.

Open Question — addressed. Replaced the "most-recent earlier version" default with "accepted baseline named by the user." The skill now explicitly says integer-numbered versions are the typical accepted shape (v(N-1) for a v(N) → v(N+1) bump); letter-suffixed dirs (v52a, v53b, v57a_<topic>, …) are experimental probes and are never auto-selected. If the user has not named the baseline, the orchestrator asks rather than guessing or using mtime.

Verification: 146 napkin_math tests still pass. No production-Python behaviour change — the preflight is a Bash check the orchestrator runs plus prose updates in three SKILL.md files.

Note on test coverage. The preflight is a doc-level orchestration rule, not Python. A unit test of an orchestrator instruction is reviewing prose. If you'd prefer a deterministic enforcement point (e.g. a validate_parameters.py rule, or a small check_prior_ledger.py invoked by the orchestrator), say so and I'll add it in a follow-up — but the deterministic grep already gives the agent a one-liner to run, which is the same enforcement surface the script-based checks would have.

[neoneye]

Both P2 items addressed in 85f7459.

P2 #1 — fresh-start contradiction fixed. "Inputs scenario (a)" no longer says "resolve the most-recent prior." It now reads: "ask the user to name (or confirm) the accepted baseline — typically the immediately-preceding integer-numbered version — and pass it as --prior. Never auto-select a letter-suffixed dir (v52a, v53b, v57a_<topic>, …) as the prior; those are experimental probes." Consistent with the rule at lines 112–120.

P2 #2 — preflight now checks correctness, not just presence. Implemented the "better" option you suggested: prepare_extract_input.py now stamps the ledger header with a Prior source: \`line. The path is rendered relative toexperiments/napkin_math/` when the prior lives under that tree (so the stamp is stable across worktrees), else absolute. Stage 1 preflight extended to two greps:

# (a) Ledger present?
grep -q '# Prior Signal Ledger' $D/extract_parameters_input.md

# (b) Ledger built from the named accepted baseline?
grep -q "Prior source:.*\$BASELINE/\$SLUG/parameters.json" \
  $D/extract_parameters_input.md

Both must pass. Either failure stops Stage 1 with the same two-resolution choice (regenerate Stage 0 or write \$D/.no_prior_waiver).

Implementation details on the stamp:

• build_prior_signal_ledger and build_combined_digest accept an optional prior_path. When supplied, the stamp line lands between the header text and the ## Signals block. When not supplied, no stamp — backwards compatible with programmatic callers.
• New render_prior_source(prior_path) helper does the relative/absolute rendering. Covered by tests.
• 4 new tests: stamp omitted when no path is supplied, relative rendering under NAPKIN_MATH_DIR, absolute rendering outside it, and render_prior_source standalone. Existing CLI-level test extended to assert the stamp lands end-to-end through main().

CLI acceptance evidence:

=== STAMP ACCEPTANCE EVIDENCE ===
  Prior source: \`output/v58/demo_slug/parameters.json\`
  (a) ledger present?                   True
  (b) source matches v58/demo_slug?         True
  (b') source matches wrong baseline?    False

A digest built against the named baseline (v58/demo_slug) passes both checks; a preflight against a wrong baseline (v52a/demo_slug) returns False — the differentiation you asked for.

Verification: 150 napkin_math tests pass (was 146).