feat(020): deterministic empirical-value strip — GUARANTEED planning removal

The LLM extractor's recall is non-deterministic, so it alone cannot guarantee
SC-001 (a run found 0 claims on the real plan). claims/planning_scan adds a
DETERMINISTIC final pass to the planning branch that removes every high-confidence
empirical value regardless of LLM recall:

  STRIPPED  comma-grouped counts (27,635; 1,701,936; 2,000), percentages (≥95%,
            10%), timed/measured quantities (15 minutes, 60s, 1s)
  PRESERVED structural numbers — scope bounds (≤13 crossings), indices (crossing
            number 13), ranges (1-10), versions (1.0.0), dates (2026-05-29),
            identifiers (SHA-256, ds002800), bare decimal thresholds (0.7);
            markdown headers + fenced code untouched.

Runs AFTER the LLM strip/smooth (which handles prose quality on what it detected)
as the guarantee net. Idempotent. process_document(stage=planning) now strips the
empirical value even when extract_claims returns [] (proven in test_planning_scan).

Real PROJ-552 plan end-to-end: the wrong "27,635 at crossing 13", "~2,000",
"≥95%", "15 minutes" are removed while "crossing number 13"/"Phase 1"/dates/SHA
survive — and it passes even on a run where the LLM extractor found 0 claims.

Offline gate 2295 passed / 0 failed; planning_scan suite 18/0. ruff + mypy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jeremymanning

src/llmxive/claims/planning_scan.py

@@ -0,0 +1,112 @@
+"""Spec 020 — deterministic empirical-value strip for planning documents.
+
+The LLM extractor (``extract_claims``) raises planning recall but cannot GUARANTEE
+that every low-level empirical value is detected — it is non-deterministic, so a
+given run may miss some. This module is the deterministic GUARANTEE: it removes the
+high-confidence empirical patterns spec 020 defers out of planning docs, regardless
+of the LLM's recall, while being conservative enough never to touch STRUCTURAL
+numbers.
+
+STRIPPED (high-confidence empirical specifics):
+  - comma-grouped counts/magnitudes:  27,635   1,701,936   2,000
+  - percentages:                      95%   ≥10%   0.5%
+  - timed/measured quantities:        15 minutes   60s   1s   2 hours   30 ms
+
+PRESERVED (structural / qualifier — never matched):
+  - scope bounds & indices:           ≤13 crossings   Phase 1   crossing number 13
+  - ranges:                           1-10
+  - versions / dotted:                1.0.0
+  - dates:                            2026-05-29
+  - hashes / identifiers:             SHA-256   ds002800
+  - bare decimals (thresholds):       0.7   (ambiguous — left to the LLM pass)
+
+It runs as the FINAL pass of the planning claim layer, AFTER the LLM strip/smooth,
+so the LLM handles prose quality on what it detected and this guarantees nothing
+empirical survives. Idempotent: once the tokens are gone, re-running is a no-op.
+PURE / deterministic — no IO, no LLM.
+"""
+
+from __future__ import annotations
+
+import re
+
+# A comma-grouped number requires at least one ``,ddd`` group, so a bare index/year
+# (13, 1976) and a sentence comma after a number ("number 13, the …") never match.
+_COMMA_NUM = r"\d{1,3}(?:,\d{3})+(?:\.\d+)?"
+_PERCENT = r"\d+(?:\.\d+)?\s*%"
+# Explicit time/size units allow a space; the bare "s" form must be attached
+# (``60s``) so "13 strands" / "5 servers" are never matched.
+_TIMED = (
+    r"\d+(?:\.\d+)?\s*"
+    r"(?:milliseconds?|ms|seconds?|secs?|minutes?|mins?|hours?|hrs?|days?)\b"
+    r"|\d+s\b"
+)
+
+# The empirical token, NOT preceded by a word char / slash / dot / hyphen — so a
+# number inside an identifier or hyphenated/dotted token (SHA-256, 1.0.0, ds-002)
+# is never picked up.
+_EMPIRICAL_TOKEN = re.compile(
+    rf"(?<![\w/.\-])(?:{_COMMA_NUM}|{_PERCENT}|{_TIMED})",
+    re.IGNORECASE,
+)
+
+# A leading comparison operator (≥ ~ < …) or approximator word to absorb together
+# with the value, so "≥95%" / "within 15 minutes" / "~27,635" leave clean prose.
+_LEAD = re.compile(
+    r"(?:[~≈≥≤<>±]\s*|"
+    r"\b(?:approximately|about|roughly|around|nearly|exactly|over|under|"
+    r"up\s+to|at\s+least|at\s+most|within|a\s+total\s+of|some)\s+)$",
+    re.IGNORECASE,
+)
+
+
+def has_empirical_value(text: str) -> bool:
+    """True iff ``text`` contains a high-confidence empirical value (count/%/time)."""
+    return _EMPIRICAL_TOKEN.search(text) is not None
+
+
+def _tidy(line: str) -> str:
+    line = re.sub(r"[ \t]{2,}", " ", line)
+    line = re.sub(r"\(\s*\)", "", line)        # empty parens left by removal
+    line = re.sub(r"\(\s+", "(", line)
+    line = re.sub(r"\s+([.,;:)])", r"\1", line)
+    line = re.sub(r"([(])\s*[,;]\s*", r"\1", line)
+    return line.rstrip()
+
+
+def strip_empirical_values(text: str) -> str:
+    """Remove every high-confidence empirical value from ``text`` (deterministic).
+
+    Operates line by line (markdown headers and fenced code are left untouched).
+    For each empirical token it also absorbs an immediately-preceding comparison
+    operator / approximator (``≥95%`` → removed whole). Guaranteed claim-free of
+    these patterns and idempotent. Surrounding prose, references, and all
+    structural numbers are preserved.
+    """
+    out: list[str] = []
+    in_fence = False
+    for line in text.split("\n"):
+        stripped = line.lstrip()
+        if stripped.startswith("```") or stripped.startswith("~~~"):
+            in_fence = not in_fence
+            out.append(line)
+            continue
+        if in_fence or stripped.startswith("#"):
+            out.append(line)
+            continue
+        new = line
+        # Remove tokens right-to-left so earlier offsets stay valid.
+        while True:
+            m = _EMPIRICAL_TOKEN.search(new)
+            if m is None:
+                break
+            start = m.start()
+            lead = _LEAD.search(new[:start])
+            if lead is not None:
+                start = lead.start()
+            new = new[:start] + new[m.end():]
+        out.append(_tidy(new) if new != line else line)
+    return "\n".join(out)
+
+
+__all__ = ["has_empirical_value", "strip_empirical_values"]

src/llmxive/claims/service.py

@@ -21,6 +21,7 @@
 from llmxive.claims.extract import extract_claims
 from llmxive.claims.gate import strip_claim_artifacts
 from llmxive.claims.models import Claim, ClaimKind, ClaimStatus
+from llmxive.claims.planning_scan import strip_empirical_values
 from llmxive.claims.pointer import (
     GateReport,
     drop_orphan_pointers,
@@ -216,6 +217,14 @@ def _process_planning_document(
             continue
         if replacement != span:
             smoothed = smoothed.replace(span, replacement, 1)
+    # spec 020 GUARANTEE: the LLM extractor's recall is non-deterministic, so a
+    # final DETERMINISTIC pass removes any high-confidence empirical value (a
+    # comma-grouped count, a percentage, a timed quantity) it missed — structural
+    # numbers (versions, dates, indices, scope bounds) are preserved. Idempotent.
+    try:
+        smoothed = strip_empirical_values(smoothed)
+    except Exception as exc:  # never block a planning render on the guarantee pass
+        logger.warning("claims.service: deterministic empirical strip failed (%s)", exc)
     # No markers, no kickback, no resolution: planning never blocks on low-level.
     return smoothed, [], GateReport()
 

tests/integration/test_proj552_real_plan.py

@@ -79,15 +79,17 @@ def test_real_proj552_plan_planning_stage_no_kickback(tmp_path: Path) -> None:
     # The real file on disk is untouched (read-only).
     assert _PLAN.read_text(encoding="utf-8") == original
 
-    # Value REMOVAL (SC-001) is BEST-EFFORT, not guaranteed per-run: the planning
-    # extractor uses the PLANNING-RECALL addendum (verified deterministically in
-    # tests/unit/test_planning_recall_prompt.py), which substantially raises recall
-    # on planning scope/metadata (0 -> 6 empirical claims in the real plan). But
-    # extract_claims is an LLM call and is NON-DETERMINISTIC, so a given run may
-    # miss some/all values. Only a deterministic detector could GUARANTEE removal.
-    # This test therefore asserts the RELIABLE guarantees (anti-stall above) + that
-    # the doc is never over-stripped/mangled; whatever values ARE detected get
-    # smoothed (the strip/smooth fallback guarantees the detected value is removed).
+    # Value REMOVAL (SC-001) is now GUARANTEED: after the (non-deterministic) LLM
+    # strip/smooth, a DETERMINISTIC pass (claims/planning_scan) removes every
+    # high-confidence empirical value, so the wrong "27,635 at crossing number 13"
+    # and the other counts/percentages/durations cannot survive — regardless of
+    # what the LLM extractor recalled this run.
+    assert "27,635" not in out and "27635" not in out, (
+        f"the wrong low-level count survived the planning stage:\n{out[:1500]}"
+    )
+    assert "2,000" not in out and "95%" not in out, "an empirical value survived"
+    # …while the document is NOT over-stripped/mangled: structure, the research
+    # subject, and STRUCTURAL numbers (the crossing-number index, the project id) survive.
     assert "## " in out, "document headers were lost (over-stripping)"
-    assert "crossing number" in out, "the research subject was over-stripped"
+    assert "crossing number 13" in out, "the structural crossing-number index was over-stripped"
     assert len(out) > len(original) * 0.6, "document was massively truncated (over-strip)"

tests/unit/test_planning_scan.py

@@ -0,0 +1,102 @@
+"""Spec 020 — deterministic empirical-value strip + the planning GUARANTEE (offline).
+
+``planning_scan.strip_empirical_values`` removes high-confidence empirical values
+(comma-grouped counts, percentages, timed quantities) while preserving structural
+numbers. The integration test proves the GUARANTEE: even when the LLM extractor
+returns ZERO claims (its non-deterministic worst case), the planning branch still
+strips the empirical value via this deterministic pass.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from llmxive.claims import service as svc
+from llmxive.claims.gate import CLAIM_MARKER_PREFIX
+from llmxive.claims.planning_scan import has_empirical_value, strip_empirical_values
+
+
+@pytest.mark.parametrize(
+    "text,gone",
+    [
+        ("There are 27,635 prime knots.", "27,635"),
+        ("~2,000 prime knots downloaded.", "2,000"),
+        ("≥95% data completeness.", "95%"),
+        ("reference coverage ≥10%.", "10%"),
+        ("Complete within 15 minutes.", "15 minutes"),
+        ("Exponential backoff (1s → 60s max).", "60s"),
+        ("The first 1,701,936 knots.", "1,701,936"),
+    ],
+)
+def test_strips_empirical(text: str, gone: str) -> None:
+    out = strip_empirical_values(text)
+    assert gone not in out
+    assert not has_empirical_value(out)
+
+
+@pytest.mark.parametrize(
+    "text,kept",
+    [
+        ("prime knots at ≤13 crossings", "13"),       # scope bound
+        ("crossing number 13", "13"),                  # index
+        ("crossing numbers 1-10", "1-10"),             # range
+        ("Phase 1 analysis", "Phase 1"),               # phase
+        ("checksummed via SHA-256", "SHA-256"),        # identifier
+        ("version 1.0.0 ratified", "1.0.0"),           # version
+        ("on 2026-05-29", "2026-05-29"),               # date
+        ("citation title overlap ≥0.7", "0.7"),        # bare decimal threshold
+        ("dataset ds002800", "ds002800"),              # dataset id
+    ],
+)
+def test_preserves_structural(text: str, kept: str) -> None:
+    assert kept in strip_empirical_values(text)
+
+
+def test_idempotent_and_headers_and_fences() -> None:
+    doc = (
+        "# Heading with 27,635 in it\n"
+        "There are 27,635 knots, ≥95% complete.\n"
+        "```\ncode with 1,234 stays\n```\n"
+    )
+    once = strip_empirical_values(doc)
+    # header line + fenced code are untouched
+    assert "# Heading with 27,635 in it" in once
+    assert "code with 1,234 stays" in once
+    # the prose value is gone
+    assert "There are 27,635 knots" not in once
+    assert strip_empirical_values(once) == once  # idempotent
+
+
+def _lowlevel_claim_doc() -> str:
+    return (
+        "# Plan\n\n## Scale/Scope\n\n"
+        "~2,000 prime knots (1-10), ~27,635 at crossing number 13 (Phase 1).\n"
+    )
+
+
+def test_planning_branch_guarantees_strip_even_when_extractor_finds_nothing(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    # Simulate the LLM extractor's worst case: it returns ZERO claims. The
+    # deterministic pass must STILL strip the empirical values (the guarantee).
+    monkeypatch.setattr(svc, "extract_claims", lambda *a, **k: [])
+
+    def _boom(*a: Any, **k: Any) -> Any:
+        raise AssertionError("resolve() called in a planning stage")
+
+    monkeypatch.setattr(svc, "resolve", _boom)
+
+    out, claims, report = svc.process_document(
+        _lowlevel_claim_doc(),
+        artifact_path="projects/PROJ-x/specs/plan.md",
+        project_id="PROJ-x", backend=object(), model=None,
+        repo_root=tmp_path, stage_label="plan",
+    )
+    assert "27,635" not in out and "2,000" not in out      # stripped (guaranteed)
+    assert "crossing number 13" in out and "Phase 1" in out  # structural preserved
+    assert CLAIM_MARKER_PREFIX not in out                   # still no kickback
+    assert report.blocked is False
+    assert claims == []