spec 020: deterministic claim caching + planning reference-only verification

[jeremymanning]

Summary

Re-architects the claim-verification stack (specs 016→019) to fix two
maintainer-observed failures, reusing existing machinery rather than
duplicating it:

1. Claim waffling — a verified value was made → flagged → corrected → then
   overwritten next round → re-flagged, never stabilizing.
2. Planning thrash — planning docs asserted low-level empirical values
   (e.g. the prime-knot count), which were fully fetched/grounded and, when
   wrong, drove kickbacks that exhausted the convergence cap toward human
   escalation (the PROJ-552 "49 vs 9,988" stall).

Accuracy stays paramount: references are verified everywhere, and paper-stage
verification is made stronger (deterministic + immutable). Only the
location of low-level-claim verification changes — out of planning.

Full speckit pipeline: plan → tasks → analyze (7 findings, all fixed) → implement → verify.

Part A — planning = references-only

• Stage signal (claims/stage.py): is_planning_stage SSoT; threaded from the
  speckit commands via claim_stage_label() and the convergence reviser's
  self-consistency pass (so planning revisions are gated too — plan_cmd/
  paper_plan_cmd can't be told apart by slash_command_name).
• Strip/smooth (claims/smooth.py): a detected low-level claim is replaced by
  a higher-level statement (LLM rewrite → deterministic re-detect guard →
  clause-removal fallback). References still fail-closed via the existing path.
• Recall + GUARANTEE: the LLM extractor is tuned for research claims and has
  low recall on planning scope/metadata, so a planning-recall prompt addendum
  raises it (0→6 on the real plan) and a deterministic final pass
  (claims/planning_scan.py) removes every high-confidence empirical value
  (comma-grouped counts, percentages, timed quantities) regardless of LLM recall,
  while preserving structural numbers (scope bounds, indices, ranges, versions,
  dates, hashes). This closes SC-001 deterministically.
• Templates/prompts (FR-006): spec/plan templates + speckit SKILLs + the
  data-resources panel defer empirical specifics; the 20 stale per-project
  template copies are re-synced and a gate-enforced sync test prevents future drift.

Part B — deterministic frozen cache

• Freeze (FR-009/010/011): reuse keyed by the value-independent subject_key;
  a VERIFIED (kind, subject_key) record is adopted without re-resolution and is
  never re-opened by a transient failure or a pending re-extraction.
• Durable placeholder (FR-007/008/SC-007): the canonical stored doc carries a
  durable {{claim:id}} for each verified claim (never the baked value, so it is
  never re-extracted); render_view/render_artifact_view substitute values for
  the human/published view. The proven-good value-correction path is preserved
  (render()'s default mode is unchanged; citation repair re-anchors on the
  placeholder). Convergence operates on the placeholder form (per the clarification).
• Value-independent cache key (FR-012): the fill verdict key drops the asserted
  value and keys on subject_key, so "49 at 13" and "9,988 at 13" share one entry.
• Asserted-value SSoT: unified the two duplicated asserted-value
  implementations into one pointer.select_asserted_token/asserted_value (dup
  regex removed) and added copula-following disambiguation, ordered after the
  comma rule so every grouped case is byte-identical to before (zero regression)
  and only comma-less prose like "…13 is 27635"→27635 is fixed.

Verification

• Offline gate: 2295 passed / 0 failed (baseline 2165 → +130, no regression).
• Real-call (free Dartmouth models): planning strip on the real PROJ-552 plan
  (anti-stall + 27,635/2,000/95% stripped, structural numbers preserved); fabricated
  DOI still blocks; paper-stage freeze (FR-011) through the real pipeline; SC-005
  no-regression on the proven-good suite (10/10); PROJ-552 stall regression (SC-006).
• ruff + mypy clean throughout.

Honest note

The LLM extractor is non-deterministic (one run found 6 empirical claims on the
real plan, another found 0). Improving its prompt raises recall but cannot
guarantee removal; the deterministic planning_scan pass is what provides the
guarantee. Tests reflect this: a deterministic test pins the addendum wiring + the
strip behavior, and the real-plan test passes even on a run where the LLM found 0.

Review guidance

Touches the claim layer that runs on every artifact across 600+ projects. Highest-
risk areas to review: the durable-placeholder render boundary (claims/pointer.py,
claims/service.py) and the subject_key cache key + asserted-value disambiguation
(claims/pointer.py, claims/canonical.py, fill/service.py).

🤖 Generated with Claude Code