From 8987cceb0da1402a31cd278feebf0e00ed022b5a Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:04:20 -0700
Subject: [PATCH 01/25] feat: add PRXREF_LLM_PARSE_RETRIES config key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the `llm_parse_retries` key (int, default 1, >= 0, no ceiling)
across all four config surfaces: config._DEFAULTS/_INT_KEYS/_RANGES,
the config.py module docstring, .env.example, and docs/env-vars.md
(with its derived key/name/group counts). Nothing reads the key yet;
a later task wires it into the reply-retry loop in reviewer.py.

🤖 Authored with Claude Code

— Claude Sonnet 5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 .env.example                       |   6 ++
 docs/env-vars.md                   |   7 +-
 src/prxref/config.py               |  11 ++-
 tests/test_parse_retries_config.py | 117 +++++++++++++++++++++++++++++
 4 files changed, 137 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_parse_retries_config.py

diff --git a/.env.example b/.env.example
index 420139b..d4ab7fc 100644
--- a/.env.example
+++ b/.env.example
@@ -74,6 +74,12 @@ PRXREF_LLM_REASONING_EFFORT=
 # account. Must be > 0.
 # PRXREF_LLM_CLI_CONCURRENCY=2
 
+# Times a reply that is empty, that fails to parse, or that lacks a
+# "findings" list is re-sent (default 1). Must be >= 0; 0 keeps only the
+# single empty-reply retry. Each discarded attempt is written as
+# <label>.attemptN.response.json when --trace-dir is set.
+# PRXREF_LLM_PARSE_RETRIES=1
+
 # Findings below this confidence floor are dropped (default 0.6).
 # A probability: must be within [0.0, 1.0] inclusive.
 PRXREF_CONFIDENCE_FLOOR=0.6
diff --git a/docs/env-vars.md b/docs/env-vars.md
index 4fb86b3..ce75940 100644
--- a/docs/env-vars.md
+++ b/docs/env-vars.md
@@ -21,6 +21,7 @@ Configuration is loaded from built-in defaults, overridden by environment variab
 | `PRXREF_LLM_SEED` | *(auto-derived)* | Optional integer sampling seed, sent as top-level `seed` to OpenAI-compatible backends (under `litellm` too). Must be **>= 0**; `0` is a valid seed. Empty or unset does not omit the parameter: one random seed is derived per process and sent on every call of the run, and the run record's `sampling.seed` reports it. `claude-cli` and `kiro-cli` send no seed, log one WARNING when it is set, and report `sampling.seed` as `null`. Together with the default `PRXREF_LLM_TEMPERATURE=0` this is the strongest reproducibility lever the API offers. |
 | `PRXREF_LLM_CLI_PATH` | *(empty — found on `PATH`)* | `claude-cli` / `kiro-cli` only: the CLI binary to run (`~` is expanded). Empty looks up `claude` or `kiro-cli` on `PATH`. A path that does not resolve to an executable raises `ConfigError` and `prxref review` exits `2`. Ignored by the other backends. |
 | `PRXREF_LLM_CLI_CONCURRENCY` | `2` | `claude-cli` / `kiro-cli` only: how many CLI processes one client may run at once. Must be **greater than 0**. Each call is a full CLI process, and subscription limits are per account. |
+| `PRXREF_LLM_PARSE_RETRIES` | `1` | Times a reply that is empty, that fails to parse, or that lacks a `findings` list is re-sent. Must be **>= 0**; `0` keeps only the single empty-reply retry. Each discarded attempt is written as `<label>.attemptN.response.json` when `--trace-dir` is set. |
 | `PRXREF_CONFIDENCE_FLOOR` | `0.6` | Minimum confidence score. Must be **within `[0.0, 1.0]` inclusive** — it is a probability everywhere in the pipeline. Findings below the floor are dropped. |
 | `PRXREF_MAX_ERROR_FINDINGS` | `10` | Maximum number of error-severity findings reported per review. Excess errors are dropped lowest-confidence-first. Must be **>= 0**; `0` is legal and caps every error. (Legacy alias: `PRXREF_MAX_ERRORS`.) |
 | `PRXREF_MAX_WARNING_FINDINGS` | *(empty — unlimited)* | **Per-severity caps (0.15.0).** Maximum number of warning-severity findings reported per review. Excess warnings are dropped lowest-confidence-first, with `drop_reason` `warning cap exceeded (max N)`. Must be **>= 0**; `0` is legal and caps every warning, distinct from unset, which caps nothing. |
@@ -166,11 +167,11 @@ The two knobs above, plus the four opt-in levers added in 0.15.0 (`PRXREF_MAX_WA
 
 ## Environment Cross-Check & Defaults
 
-The tables above define all **67** configuration keys in `src/prxref/config.py` (`_DEFAULTS`), and every one of them appears in `.env.example`:
+The tables above define all **68** configuration keys in `src/prxref/config.py` (`_DEFAULTS`), and every one of them appears in `.env.example`:
 
-- **LLM / Pipeline (49):** `PRXREF_LLM_BACKEND`, `PRXREF_LLM_BASE_URL`, `PRXREF_LLM_API_KEY`, `PRXREF_LLM_MODELS`, `PRXREF_LLM_REASONING_EFFORT`, `PRXREF_LLM_MAX_TOKENS`, `PRXREF_LLM_TIMEOUT`, `PRXREF_LLM_TEMPERATURE`, `PRXREF_LLM_SEED`, `PRXREF_LLM_CLI_PATH`, `PRXREF_LLM_CLI_CONCURRENCY`, `PRXREF_CONFIDENCE_FLOOR`, `PRXREF_MAX_ERROR_FINDINGS`, `PRXREF_MAX_WARNING_FINDINGS`, `PRXREF_MAX_OUTOFSCOPE_FINDINGS`, `PRXREF_MAX_FINDINGS_PER_RULE`, `PRXREF_GROUP_FINDINGS`, `PRXREF_DEDUP_SIMILARITY`, `PRXREF_MAX_CHUNKS`, `PRXREF_CHUNK_TOKEN_BUDGET`, `PRXREF_CHUNK_MAX_FILES`, `PRXREF_CHUNK_CONTEXT_LINES`, `PRXREF_MAX_WORKERS`, `PRXREF_MAX_INLINE_COMMENTS`, `PRXREF_FAIL_ON`, `PRXREF_DRY_RUN`, `PRXREF_TRACE_FILE`, `PRXREF_TRACE_DIR`, `PRXREF_POST_MODE`, `PRXREF_POST_VERDICT`, `PRXREF_PRICE_TABLE`, `PRXREF_POST_COST`, `PRXREF_SIZE_WARN_LINES`, `PRXREF_SIZE_WARN_FILES`, `PRXREF_SIZE_IGNORE_GLOBS`, `PRXREF_SPEC_SOURCES`, `PRXREF_SPEC_MAX_CHARS`, `PRXREF_SPEC_DIGEST_TOKENS`, `PRXREF_REVIEW_RULES`, `PRXREF_REVIEW_RULES_MAX_CHARS`, `PRXREF_SCOPED_RULES`, `PRXREF_SCOPED_RULES_MAX_CHARS`, `PRXREF_PROMPTS_DIR`, `PRXREF_TICKET_CONTEXT_FILE`, `PRXREF_TICKET_CONTEXT_MAX_CHARS`, `PRXREF_REPO_CONTEXT`, `PRXREF_REPO_CONTEXT_MAX_CHARS`, `PRXREF_CONTEXT_CONTRACT_GLOBS`, `PRXREF_CONTEXT_EXCLUDE_GLOBS`
+- **LLM / Pipeline (50):** `PRXREF_LLM_BACKEND`, `PRXREF_LLM_BASE_URL`, `PRXREF_LLM_API_KEY`, `PRXREF_LLM_MODELS`, `PRXREF_LLM_REASONING_EFFORT`, `PRXREF_LLM_MAX_TOKENS`, `PRXREF_LLM_TIMEOUT`, `PRXREF_LLM_TEMPERATURE`, `PRXREF_LLM_SEED`, `PRXREF_LLM_CLI_PATH`, `PRXREF_LLM_CLI_CONCURRENCY`, `PRXREF_LLM_PARSE_RETRIES`, `PRXREF_CONFIDENCE_FLOOR`, `PRXREF_MAX_ERROR_FINDINGS`, `PRXREF_MAX_WARNING_FINDINGS`, `PRXREF_MAX_OUTOFSCOPE_FINDINGS`, `PRXREF_MAX_FINDINGS_PER_RULE`, `PRXREF_GROUP_FINDINGS`, `PRXREF_DEDUP_SIMILARITY`, `PRXREF_MAX_CHUNKS`, `PRXREF_CHUNK_TOKEN_BUDGET`, `PRXREF_CHUNK_MAX_FILES`, `PRXREF_CHUNK_CONTEXT_LINES`, `PRXREF_MAX_WORKERS`, `PRXREF_MAX_INLINE_COMMENTS`, `PRXREF_FAIL_ON`, `PRXREF_DRY_RUN`, `PRXREF_TRACE_FILE`, `PRXREF_TRACE_DIR`, `PRXREF_POST_MODE`, `PRXREF_POST_VERDICT`, `PRXREF_PRICE_TABLE`, `PRXREF_POST_COST`, `PRXREF_SIZE_WARN_LINES`, `PRXREF_SIZE_WARN_FILES`, `PRXREF_SIZE_IGNORE_GLOBS`, `PRXREF_SPEC_SOURCES`, `PRXREF_SPEC_MAX_CHARS`, `PRXREF_SPEC_DIGEST_TOKENS`, `PRXREF_REVIEW_RULES`, `PRXREF_REVIEW_RULES_MAX_CHARS`, `PRXREF_SCOPED_RULES`, `PRXREF_SCOPED_RULES_MAX_CHARS`, `PRXREF_PROMPTS_DIR`, `PRXREF_TICKET_CONTEXT_FILE`, `PRXREF_TICKET_CONTEXT_MAX_CHARS`, `PRXREF_REPO_CONTEXT`, `PRXREF_REPO_CONTEXT_MAX_CHARS`, `PRXREF_CONTEXT_CONTRACT_GLOBS`, `PRXREF_CONTEXT_EXCLUDE_GLOBS`
 - **Per-Forge Auth (10):** `PRXREF_BITBUCKET_TOKEN`, `PRXREF_BITBUCKET_USER`, `PRXREF_BITBUCKET_APP_PASSWORD`, `PRXREF_BITBUCKET_SERVER_TOKEN`, `PRXREF_BITBUCKET_SERVER_USER`, `PRXREF_BITBUCKET_SERVER_PASSWORD`, `PRXREF_GITHUB_TOKEN`, `PRXREF_GITHUB_ENTERPRISE_TOKEN`, `PRXREF_GITLAB_TOKEN`, `PRXREF_AZURE_DEVOPS_TOKEN`
 - **Spec Sources / Jira (3):** `PRXREF_JIRA_BASE_URL`, `PRXREF_JIRA_EMAIL`, `PRXREF_JIRA_API_TOKEN`
 - **Webhooks (5):** `PRXREF_BITBUCKET_WEBHOOK_SECRET`, `PRXREF_GITHUB_WEBHOOK_SECRET`, `PRXREF_GITLAB_WEBHOOK_SECRET`, `PRXREF_AZURE_DEVOPS_WEBHOOK_SECRET`, `PRXREF_ALLOW_UNSIGNED`
 
-*(67 configuration keys, plus one deprecated alias — `PRXREF_MAX_ERRORS` for `PRXREF_MAX_ERROR_FINDINGS` — for 68 accepted variable names.)*
+*(68 configuration keys, plus one deprecated alias — `PRXREF_MAX_ERRORS` for `PRXREF_MAX_ERROR_FINDINGS` — for 69 accepted variable names.)*
diff --git a/src/prxref/config.py b/src/prxref/config.py
index ccd85b4..1339652 100644
--- a/src/prxref/config.py
+++ b/src/prxref/config.py
@@ -44,6 +44,13 @@
   PRXREF_LLM_CLI_CONCURRENCY    claude-cli / kiro-cli only: max CLI
                                 processes one client runs at once; positive
                                 int (default 2)
+  PRXREF_LLM_PARSE_RETRIES      Times a reply that is empty, does not parse, or
+                                lacks a ``findings`` list is re-sent up to N
+                                times; >= 0, where 0 keeps only the single
+                                empty-reply retry (default 1). Each discarded
+                                attempt is written as
+                                ``<label>.attempt<K>.response.json`` when
+                                ``--trace-dir`` is set.
   PRXREF_CONFIDENCE_FLOOR       Findings below this confidence are dropped;
                                 a probability in [0.0, 1.0] (default 0.6)
   PRXREF_MAX_ERROR_FINDINGS     Max error-severity findings reported per
@@ -393,6 +400,7 @@
     "llm_seed": None,
     "llm_cli_path": "",
     "llm_cli_concurrency": 2,
+    "llm_parse_retries": 1,
     "confidence_floor": DEFAULT_CONFIDENCE_FLOOR,
     "max_error_findings": DEFAULT_MAX_ERRORS,
     "max_warning_findings": None,
@@ -484,7 +492,7 @@
     "llm_cli_concurrency", "review_rules_max_chars",
     "ticket_context_max_chars", "size_warn_lines", "size_warn_files",
     "max_warning_findings", "max_outofscope_findings", "scoped_rules_max_chars",
-    "max_findings_per_rule", "repo_context_max_chars",
+    "max_findings_per_rule", "repo_context_max_chars", "llm_parse_retries",
 })
 _FLOAT_KEYS = frozenset({"confidence_floor", "llm_timeout", "dedup_similarity"})
 _BOOL_KEYS = frozenset({
@@ -576,6 +584,7 @@ def describe(self) -> str:
     "spec_max_chars": _Range(0),
     "spec_digest_tokens": _Range(0),
     "llm_cli_concurrency": _Range(0),
+    "llm_parse_retries": _Range(0, low_inclusive=True),
     "review_rules_max_chars": _Range(0),
     "ticket_context_max_chars": _Range(0),
     "size_warn_lines": _Range(0, low_inclusive=True),
diff --git a/tests/test_parse_retries_config.py b/tests/test_parse_retries_config.py
new file mode 100644
index 0000000..ee972d4
--- /dev/null
+++ b/tests/test_parse_retries_config.py
@@ -0,0 +1,117 @@
+"""Tests for the ``PRXREF_LLM_PARSE_RETRIES`` config key (#21).
+
+Nothing reads this key yet -- it is wired to the reply-retry loop in a later
+task. This file only pins the config surface: default, valid range, the exit-2
+path shared with the other int keys, and that the docs surfaces agree with the
+schema on the derived key/name counts.
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import pytest
+
+from prxref import config
+from prxref.config import load_config
+from prxref.llm import ConfigError
+from tests.conftest import prxref_env_names
+from tests.test_docs_consistency import REPO_ROOT, SURFACES
+
+
+class TestDefault:
+    def test_unset_defaults_to_one(self):
+        assert config._DEFAULTS["llm_parse_retries"] == 1
+        assert load_config()["llm_parse_retries"] == 1
+
+    def test_zero_is_valid(self, monkeypatch):
+        monkeypatch.setenv("PRXREF_LLM_PARSE_RETRIES", "0")
+        cfg = load_config()
+        assert cfg["llm_parse_retries"] == 0
+
+    def test_env_coercion_yields_an_int(self, monkeypatch):
+        monkeypatch.setenv("PRXREF_LLM_PARSE_RETRIES", "3")
+        cfg = load_config()
+        assert cfg["llm_parse_retries"] == 3
+        assert isinstance(cfg["llm_parse_retries"], int)
+
+    def test_the_env_name_is_derived_for_the_suite_wide_clear(self):
+        assert "PRXREF_LLM_PARSE_RETRIES" in prxref_env_names()
+
+
+class TestRangeEnforcement:
+    """Same exit-2 path every other int key uses (see TestLLMSeedConfig in
+    tests/test_config.py for the pattern this mirrors)."""
+
+    def test_negative_value_exits_2_naming_the_variable(self, monkeypatch):
+        monkeypatch.setenv("PRXREF_LLM_PARSE_RETRIES", "-1")
+        with pytest.raises(ConfigError, match="PRXREF_LLM_PARSE_RETRIES"):
+            load_config()
+
+    def test_non_numeric_value_exits_2_naming_the_variable(self, monkeypatch):
+        monkeypatch.setenv("PRXREF_LLM_PARSE_RETRIES", "x")
+        with pytest.raises(ConfigError, match="PRXREF_LLM_PARSE_RETRIES"):
+            load_config()
+
+    def test_an_override_cannot_smuggle_a_negative_value(self):
+        """Still rejected, and reported as the override it came from."""
+        with pytest.raises(ConfigError, match="llm_parse_retries") as exc:
+            load_config(llm_parse_retries=-1)
+        assert "PRXREF_LLM_PARSE_RETRIES" not in str(exc.value)
+
+
+class TestDocsAgreeWithTheSchema:
+    """The docs' stated counts must equal what an independent AST walk of
+    ``_DEFAULTS`` (and ``_LEGACY_ENV_ALIASES``) finds -- never eyeballed."""
+
+    def _ast_counts(self) -> tuple[int, int]:
+        src = (REPO_ROOT / "src" / "prxref" / "config.py").read_text(encoding="utf-8")
+        tree = ast.parse(src)
+        defaults_count = None
+        legacy_count = None
+        for node in ast.walk(tree):
+            targets = None
+            if isinstance(node, ast.Assign):
+                targets = node.targets
+            elif isinstance(node, ast.AnnAssign) and node.target is not None:
+                targets = [node.target]
+            if not targets:
+                continue
+            for target in targets:
+                if not isinstance(target, ast.Name):
+                    continue
+                if target.id == "_DEFAULTS":
+                    assert isinstance(node.value, ast.Dict)
+                    defaults_count = len(node.value.keys)
+                elif target.id == "_LEGACY_ENV_ALIASES":
+                    assert isinstance(node.value, ast.Dict)
+                    legacy_count = len(node.value.keys)
+        assert defaults_count is not None
+        assert legacy_count is not None
+        return defaults_count, legacy_count
+
+    def test_key_count_matches_ast(self):
+        defaults_count, _ = self._ast_counts()
+        assert defaults_count == len(config._DEFAULTS)
+        assert f"**{defaults_count}** configuration keys" in SURFACES["docs/env-vars.md"]
+
+    def test_accepted_name_count_matches_ast(self):
+        defaults_count, legacy_count = self._ast_counts()
+        accepted = defaults_count + legacy_count
+        assert accepted == len(config._DEFAULTS) + len(config._LEGACY_ENV_ALIASES)
+        assert f"for {accepted} accepted variable names" in SURFACES["docs/env-vars.md"]
+
+    def test_llm_parse_retries_row_exists_in_docs(self):
+        text = SURFACES["docs/env-vars.md"]
+        rows = [
+            ln for ln in text.splitlines()
+            if ln.startswith("| `PRXREF_LLM_PARSE_RETRIES` |")
+        ]
+        assert len(rows) == 1
+
+    def test_llm_parse_retries_row_exists_in_env_example(self):
+        text = Path(REPO_ROOT / ".env.example").read_text(encoding="utf-8")
+        assert "PRXREF_LLM_PARSE_RETRIES=1" in text
+
+    def test_llm_parse_retries_documented_in_module_docstring(self):
+        assert "PRXREF_LLM_PARSE_RETRIES" in (config.__doc__ or "")

From 0b8437d84b460c381edf812f826dcf69f7f39fbc Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:08:05 -0700
Subject: [PATCH 02/25] feat: flag a default-on toggle the test setup pins off
 (#22)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add heuristics.toggle_pinned_off_findings(files), a pure, deterministic
check modelled on release_shape_findings. When a PR adds a toggle whose
default is a literal true and, in the same PR, a suite-wide test-setup
file (conftest.py, setupTests.*, jest.setup.*, vitest.setup.*) that sets
a matching name to "false", "0" or "off", it returns one warning at the
toggle's line with confidence 1.0 and the deterministic-check suffix. The
green suite never runs the shipped default, which is why issue #22's
fixture passed its own tests while breaking two unchanged readers.

Both sides must be added lines, so a pre-existing toggle or pin never
fires. A pin names a toggle when its lowercase name tokens (split on
_ . -) end with the toggle's: ASSISTANT_PROGRESS_NOTES names
progress_notes. The body quotes the toggle call so line alignment keeps
the anchor on the toggle line, and it carries no hedge wording.

The check is not wired into the review yet; tests cover the #22 fixture
lines, every supported toggle and pin form, and the negatives (no pin,
a true pin, a pin in a plain test, either side on a context line,
unrelated names, a False default).

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/heuristics.py        | 186 ++++++++++++++++
 tests/test_toggle_pinned_off.py | 371 ++++++++++++++++++++++++++++++++
 2 files changed, 557 insertions(+)
 create mode 100644 tests/test_toggle_pinned_off.py

diff --git a/src/prxref/heuristics.py b/src/prxref/heuristics.py
index 009c7cf..a4ab204 100644
--- a/src/prxref/heuristics.py
+++ b/src/prxref/heuristics.py
@@ -10,6 +10,8 @@
 """
 from __future__ import annotations
 
+import re
+from collections.abc import Iterator
 from pathlib import PurePosixPath
 
 from .triage import FileDiff, Finding
@@ -133,3 +135,187 @@ def release_shape_findings(files: list[FileDiff]) -> list[Finding]:
         body=body,
     )
     return [finding]
+
+
+# Test-setup files that run ahead of every test in a suite, matched on
+# basename: pytest's conftest.py, and the setup modules Jest (setupTests.*,
+# jest.setup.*) and Vitest (vitest.setup.*) load before each test file. A
+# value pinned here is pinned for the whole suite; a pin inside one test's own
+# body is not, so plain test files never count as the pin side.
+_TEST_SETUP_BASENAME = "conftest.py"
+_TEST_SETUP_PREFIXES = ("setupTests.", "jest.setup.", "vitest.setup.")
+
+# Regex building blocks shared by the toggle and pin patterns below. A name is
+# the quoted key a toggle or a pin is looked up by: an env var, a property key,
+# or a flag name. ``_PROCESS_ENV`` reads ``process.env.NAME`` or
+# ``process.env["NAME"]`` and leaves the name in ``name`` or ``bname``.
+_NAME = r"[A-Za-z0-9_.\-]+"
+_QUOTED_NAME = r"(?P<q>[\"'])(?P<name>" + _NAME + r")(?P=q)"
+_NOT_AFTER_IDENT = r"(?<![\w$])"
+_DOTTED_PREFIX = r"(?:[A-Za-z_$][\w$]*\.)*"
+_PROCESS_ENV = (
+    r"process\.env(?:\.(?P<name>[A-Za-z_$][\w$]*)"
+    r"|\[\s*(?P<bq>[\"'])(?P<bname>" + _NAME + r")(?P=bq)\s*\])"
+)
+_TRUE_STRING = r"(?P<v>[\"'])(?i:true)(?P=v)"
+_FALSY_STRING = r"(?P<v>[\"'])(?P<value>(?i:false|0|off))(?P=v)"
+
+# Toggle side, the three shapes of "a call named by a string literal whose
+# default is a literal true":
+#   any call ``f("name", default=True)`` / ``f("name", True)`` / ``f("name", true)``
+#     with exactly those two arguments;
+#   an env or property lookup ``getenv("NAME", "true")``,
+#     ``environ.get("NAME", "true")`` or ``getProperty("name", "true")``;
+#   ``process.env.NAME ?? "true"`` or ``|| "true"``, dot or bracket access.
+_TOGGLE_CALL_RE = re.compile(
+    _NOT_AFTER_IDENT
+    + r"(?P<callee>" + _DOTTED_PREFIX + r"[A-Za-z_$][\w$]*)\(\s*"
+    + _QUOTED_NAME
+    + r"\s*,\s*(?:default\s*=\s*)?(?:True|true)\s*\)"
+)
+_TOGGLE_LOOKUP_RE = re.compile(
+    _NOT_AFTER_IDENT
+    + _DOTTED_PREFIX
+    + r"(?:getenv|environ\.get|getProperty)\(\s*"
+    + _QUOTED_NAME
+    + r"\s*,\s*" + _TRUE_STRING + r"\s*\)"
+)
+_TOGGLE_PROCESS_ENV_RE = re.compile(
+    _NOT_AFTER_IDENT + _PROCESS_ENV + r"\s*(?:\?\?|\|\|)\s*" + _TRUE_STRING
+)
+_TOGGLE_RES = (_TOGGLE_CALL_RE, _TOGGLE_LOOKUP_RE, _TOGGLE_PROCESS_ENV_RE)
+
+# A call whose last name segment is a setter (``set``, ``setFlag``,
+# ``set_flag``, ``put``, ``putBoolean``) writes a value rather than declaring
+# a default, so ``settings.set("name", True)`` is not a toggle.
+_SETTER_SEGMENT_RE = re.compile(r"(?:[Ss]et|[Pp]ut)(?![a-z])")
+
+# Pin side, each setting a name to "false", "0" or "off" (any case):
+#   ``setenv("NAME", ...)`` (pytest's monkeypatch), ``stubEnv("NAME", ...)``
+#     (Vitest) and ``setProperty("name", ...)`` (a JVM system property);
+#   ``process.env.NAME = ...`` or ``process.env["NAME"] = ...``;
+#   ``os.environ["NAME"] = ...``.
+_PIN_CALL_RE = re.compile(
+    _NOT_AFTER_IDENT
+    + _DOTTED_PREFIX
+    + r"(?:setenv|stubEnv|setProperty)\(\s*"
+    + _QUOTED_NAME
+    + r"\s*,\s*" + _FALSY_STRING + r"\s*\)"
+)
+_PIN_PROCESS_ENV_RE = re.compile(_NOT_AFTER_IDENT + _PROCESS_ENV + r"\s*=\s*" + _FALSY_STRING)
+_PIN_ENVIRON_RE = re.compile(
+    _NOT_AFTER_IDENT + _DOTTED_PREFIX + r"environ\[\s*" + _QUOTED_NAME + r"\s*\]\s*=\s*" + _FALSY_STRING
+)
+_PIN_RES = (_PIN_CALL_RE, _PIN_PROCESS_ENV_RE, _PIN_ENVIRON_RE)
+
+_NAME_SEPARATORS_RE = re.compile(r"[_.\-]+")
+
+
+def _is_test_setup_file(path: str) -> bool:
+    """True when ``path``'s basename is a suite-wide test-setup file."""
+    name = PurePosixPath(path).name
+    return name == _TEST_SETUP_BASENAME or name.startswith(_TEST_SETUP_PREFIXES)
+
+
+def _added_lines(file: FileDiff) -> Iterator[tuple[int, str]]:
+    """``(new_line, text)`` for every added (``+``) line of ``file``, in diff order."""
+    for hunk in file.hunks:
+        for ln in hunk.lines:
+            if ln.kind == "+" and ln.new_line is not None:
+                yield ln.new_line, ln.text
+
+
+def _matched_name(match: re.Match[str]) -> str:
+    """The toggle or pin name a pattern captured, in either access form."""
+    groups = match.groupdict()
+    return groups.get("name") or groups.get("bname") or ""
+
+
+def _name_tokens(name: str) -> tuple[str, ...]:
+    """``name`` lowercased and split on ``_``, ``.`` and ``-``, empty parts dropped."""
+    return tuple(part for part in _NAME_SEPARATORS_RE.split(name.lower()) if part)
+
+
+def _pin_names_toggle(pin: tuple[str, ...], toggle: tuple[str, ...]) -> bool:
+    """True when the pin's name tokens END with the toggle's name tokens."""
+    return bool(toggle) and len(pin) >= len(toggle) and pin[-len(toggle):] == toggle
+
+
+def toggle_pinned_off_findings(files: list[FileDiff]) -> list[Finding]:
+    """Flag a default-on toggle that this PR's test setup pins off (issue #22).
+
+    A green suite proves nothing about a toggle's shipped default when a
+    suite-wide setup file turns the toggle off. Both sides must be ADDED
+    lines of this PR; a toggle or a pin that only appears on a context or
+    removed line is never reported.
+
+    The toggle side is a call named by a string literal whose default is a
+    literal true: ``f("name", default=True)``, ``f("name", True)`` or
+    ``f("name", true)`` with exactly those two arguments, where ``f`` is any
+    call except a setter (a last name segment that is ``set`` or ``put``, or
+    starts with one and goes on with anything but a lowercase letter:
+    ``setFlag``, ``set_flag``, ``putBoolean``); ``getenv``, ``environ.get``
+    or ``getProperty`` called as ``("NAME", "true")``; or
+    ``process.env.NAME ?? "true"`` / ``|| "true"``. The pin side is a line
+    in a test-setup file (basename ``conftest.py``, ``setupTests.*``,
+    ``jest.setup.*`` or ``vitest.setup.*``) that sets a name to ``"false"``,
+    ``"0"`` or ``"off"`` (any case, either quote): ``setenv``, ``stubEnv``
+    or ``setProperty`` called as ``("NAME", value)``,
+    ``process.env.NAME = value`` or ``os.environ["NAME"] = value``. A pin
+    names a toggle when the pin name's tokens (lowercased, split on ``_``,
+    ``.`` and ``-``) END with the toggle name's tokens, so
+    ``ASSISTANT_PROGRESS_NOTES`` names ``progress_notes``.
+
+    Returns one ``warning`` per pinned toggle, anchored at the toggle's own
+    line, with confidence 1.0, a body quoting the toggle call and naming
+    every pinning file, ending with " (deterministic check, no model)".
+    Sorted by file, line and position on the line. Pure and deterministic:
+    no LLM call, no I/O, no randomness.
+    """
+    pins: list[tuple[str, str, str]] = []
+    for file in files:
+        if not _is_test_setup_file(file.path):
+            continue
+        for _, text in _added_lines(file):
+            for pattern in _PIN_RES:
+                for m in pattern.finditer(text):
+                    pins.append((file.path, _matched_name(m), m.group("value")))
+
+    toggles: dict[tuple[str, int, str], tuple[int, str]] = {}
+    for file in files:
+        for line, text in _added_lines(file):
+            for pattern in _TOGGLE_RES:
+                for m in pattern.finditer(text):
+                    callee = m.groupdict().get("callee")
+                    if callee and _SETTER_SEGMENT_RE.match(callee.rsplit(".", 1)[-1]):
+                        continue
+                    key = (file.path, line, _matched_name(m))
+                    if key not in toggles or m.start() < toggles[key][0]:
+                        toggles[key] = (m.start(), m.group(0))
+
+    findings: list[Finding] = []
+    for (path, line, name), (_, call) in sorted(toggles.items(), key=lambda kv: (kv[0][0], kv[0][1], kv[1][0])):
+        wanted = _name_tokens(name)
+        matched = sorted({
+            (pin_path, pin_name, value)
+            for pin_path, pin_name, value in pins
+            if _pin_names_toggle(_name_tokens(pin_name), wanted)
+        })
+        if not matched:
+            continue
+        pinned = "; ".join(f'{pin_path} sets `{pin_name}` to "{value}"' for pin_path, pin_name, value in matched)
+        body = (
+            f"`{call}` in {path} turns the `{name}` toggle on by default, but the test setup "
+            f"turns it off for the whole suite: {pinned}. The passing tests therefore run with "
+            f"the toggle off and do not exercise the shipped default."
+            + _BODY_SUFFIX
+        )
+        findings.append(Finding(
+            file=path,
+            line=line,
+            severity="warning",
+            confidence=1.0,
+            title=f'Toggle "{name}" defaults on but the test setup pins it off',
+            body=body,
+        ))
+    return findings
diff --git a/tests/test_toggle_pinned_off.py b/tests/test_toggle_pinned_off.py
new file mode 100644
index 0000000..8bdd333
--- /dev/null
+++ b/tests/test_toggle_pinned_off.py
@@ -0,0 +1,371 @@
+"""Unit tests for ``heuristics.toggle_pinned_off_findings`` (issue #22, proposal 3).
+
+A PR adds a toggle that defaults on and, in the same PR, a suite-wide test
+setup file that turns it off, so the green suite never runs the shipped
+default. Every FileDiff here comes out of the production parser,
+``triage.parse_unified_diff``, over hand-written diff text, so added,
+context and removed lines are exactly what a real review would see.
+"""
+from __future__ import annotations
+
+import pytest
+
+from prxref import markers
+from prxref.heuristics import _BODY_SUFFIX, toggle_pinned_off_findings
+from prxref.quality import apply_hedge_gate, apply_line_align
+from prxref.triage import FileDiff, added_lines_by_file, parse_unified_diff
+
+PROGRESS_PY = [
+    '"""Progress notes: a short user-facing line announced before each step runs.',
+    "",
+    'Each note is saved as a message (role "progress") so the transcript holds exactly what the',
+    "user saw. A per-turn ledger on the root frame drops a note that repeats one already shown.",
+    '"""',
+    "from assistant.features import enabled",
+    "from assistant.messages import Message, MessageTable",
+    "from assistant.session import Run",
+    "",
+    'LEDGER_KEY = "progress.ledger"',
+    "",
+    "",
+    "class ProgressLedger:",
+    '    """Notes shown to the user during one turn."""',
+    "",
+    "    def __init__(self, turn_id: str) -> None:",
+    "        self._turn_id = turn_id",
+    "        self._lines: list[str] = []",
+    "",
+    "    def turn_id(self) -> str:",
+    "        return self._turn_id",
+    "",
+    "    def record(self, line: str) -> bool:",
+    "        key = line.strip().lower()",
+    "        if any(shown.strip().lower() == key for shown in self._lines):",
+    "            return False",
+    "        self._lines.append(line)",
+    "        return True",
+    "",
+    "",
+    "class ProgressAnnouncer:",
+    "    def __init__(self, table: MessageTable) -> None:",
+    "        self.table = table",
+    '        self.active = enabled("progress_notes", default=True)',
+    "",
+    "    def announce(self, run: Run, text: str) -> None:",
+    "        if not self.active:",
+    "            return",
+    "        if self._ledger(run).record(text):",
+    '            self.table.append(Message(run.session_id, "progress", text))',
+]
+
+CONFTEST_PY = [
+    "import pytest",
+    "",
+    "",
+    "@pytest.fixture(autouse=True)",
+    "def _progress_notes_off(monkeypatch):",
+    "    # Keep exact message-table assertions deterministic; progress tests opt in.",
+    '    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")',
+]
+
+TOGGLE = '        self.active = enabled("progress_notes", default=True)'
+PIN = '    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")'
+TOGGLE_LINE = PROGRESS_PY.index(TOGGLE) + 1
+
+
+def _section(path: str, lines: list[str], *, new_file: bool = False) -> str:
+    """One file's diff section; each line already carries its ``+``/``-``/`` `` prefix."""
+    old = sum(1 for ln in lines if ln[0] in " -")
+    new = sum(1 for ln in lines if ln[0] in " +")
+    if new_file:
+        head = f"diff --git a/{path} b/{path}\nnew file mode 100644\n--- /dev/null\n+++ b/{path}\n@@ -0,0 +1,{new} @@\n"
+    else:
+        head = f"diff --git a/{path} b/{path}\n--- a/{path}\n+++ b/{path}\n@@ -1,{old} +1,{new} @@\n"
+    return head + "".join(ln + "\n" for ln in lines)
+
+
+def _added_file(path: str, lines: list[str]) -> str:
+    """A diff section that adds ``path`` with ``lines`` as its whole content."""
+    return _section(path, ["+" + ln for ln in lines], new_file=True)
+
+
+def _files(*sections: str) -> list[FileDiff]:
+    return parse_unified_diff("".join(sections))
+
+
+def _fixture_files() -> list[FileDiff]:
+    return _files(
+        _added_file("assistant/progress.py", PROGRESS_PY),
+        _added_file("tests/conftest.py", CONFTEST_PY),
+    )
+
+
+class TestIssue22Fixture:
+    """The #22 fixture's own lines: progress.py adds the toggle, conftest.py pins it off."""
+
+    def test_exactly_one_warning_at_the_toggle_line(self):
+        findings = toggle_pinned_off_findings(_fixture_files())
+        assert len(findings) == 1
+        f = findings[0]
+        assert f.file == "assistant/progress.py"
+        assert f.line == TOGGLE_LINE
+        assert f.severity == "warning"
+        assert f.confidence == 1.0
+        assert f.drop_reason is None
+        assert f.rule is None
+        assert f.body.endswith(_BODY_SUFFIX)
+
+    def test_body_says_what_happened_and_names_both_files(self):
+        f = toggle_pinned_off_findings(_fixture_files())[0]
+        assert "progress_notes" in f.title
+        assert '`enabled("progress_notes", default=True)`' in f.body
+        assert "assistant/progress.py" in f.body
+        assert 'tests/conftest.py sets `ASSISTANT_PROGRESS_NOTES` to "false"' in f.body
+        assert "on by default" in f.body
+        assert "whole suite" in f.body
+        assert "do not exercise the shipped default" in f.body
+
+    def test_text_is_ascii_with_no_glyph(self):
+        f = toggle_pinned_off_findings(_fixture_files())[0]
+        text = f.title + f.body
+        assert all(ord(ch) < 128 for ch in text)
+        glyphs = [*markers.SEVERITY_MARKERS.values(), markers.OUT_OF_TICKET_MARKER]
+        assert not any(g in text for g in glyphs)
+
+    def test_anchor_survives_line_alignment(self):
+        files = _fixture_files()
+        findings = toggle_pinned_off_findings(files)
+        aligned = apply_line_align(findings, added_lines_by_file(files), files=files)
+        assert [f.line for f in aligned] == [TOGGLE_LINE]
+
+    def test_body_is_not_hedged(self):
+        findings = toggle_pinned_off_findings(_fixture_files())
+        assert [f.drop_reason for f in apply_hedge_gate(findings)] == [None]
+
+    def test_pure_and_order_independent(self):
+        files = _fixture_files()
+        first = toggle_pinned_off_findings(files)
+        assert toggle_pinned_off_findings(files) == first
+        assert toggle_pinned_off_findings(list(reversed(files))) == first
+
+
+class TestNegatives:
+    """Every shape that must stay silent."""
+
+    def test_no_pin(self):
+        assert toggle_pinned_off_findings(_files(_added_file("assistant/progress.py", PROGRESS_PY))) == []
+
+    def test_pin_sets_true(self):
+        conftest = [ln.replace('"false"', '"true"') for ln in CONFTEST_PY]
+        assert conftest != CONFTEST_PY
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _added_file("tests/conftest.py", conftest),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    def test_pin_in_a_plain_test_body(self):
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _added_file("tests/test_x.py", ["def test_quiet(monkeypatch):", PIN]),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    def test_toggle_on_a_context_line(self):
+        files = _files(
+            _section("assistant/progress.py", [
+                " class ProgressAnnouncer:",
+                "     def __init__(self, table: MessageTable) -> None:",
+                "         self.table = table",
+                " " + TOGGLE,
+                "+        self.muted = False",
+            ]),
+            _added_file("tests/conftest.py", CONFTEST_PY),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    def test_pin_on_a_context_line(self):
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _section("tests/conftest.py", [
+                " @pytest.fixture(autouse=True)",
+                " def _progress_notes_off(monkeypatch):",
+                " " + PIN,
+                '+    monkeypatch.setenv("ASSISTANT_LOG_LEVEL", "debug")',
+            ]),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    def test_toggle_on_a_removed_line(self):
+        files = _files(
+            _section("assistant/progress.py", [
+                " class ProgressAnnouncer:",
+                "-" + TOGGLE,
+                "+" + TOGGLE.replace("default=True", "default=False"),
+            ]),
+            _added_file("tests/conftest.py", CONFTEST_PY),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    @pytest.mark.parametrize("pin_name", [
+        "ASSISTANT_DARK_MODE",
+        "NOTES",
+        "PROGRESS_NOTES_EXTRA",
+        "ASSISTANT_XPROGRESS_NOTES",
+        "PROGRESSNOTES",
+    ])
+    def test_pin_name_does_not_end_with_the_toggle_name(self, pin_name):
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _added_file("tests/conftest.py", [PIN.replace("ASSISTANT_PROGRESS_NOTES", pin_name)]),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    def test_toggle_defaults_false(self):
+        progress = [ln.replace("default=True", "default=False") for ln in PROGRESS_PY]
+        assert progress != PROGRESS_PY
+        files = _files(
+            _added_file("assistant/progress.py", progress),
+            _added_file("tests/conftest.py", CONFTEST_PY),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    @pytest.mark.parametrize("toggle", [
+        'settings.set("progress_notes", True)',
+        'prefs.putBoolean("progress_notes", true)',
+        'config.set_flag("progress_notes", True)',
+        'enabled("progress_notes", True, strict=True)',
+        'enabled(progress_notes, default=True)',
+        'monkeypatch.setenv("PROGRESS_NOTES", "true")',
+    ])
+    def test_not_a_default_on_toggle(self, toggle):
+        files = _files(
+            _added_file("assistant/progress.py", [toggle]),
+            _added_file("tests/conftest.py", CONFTEST_PY),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    @pytest.mark.parametrize("path", [
+        "tests/conftest_helpers.py",
+        "tests/test_conftest.py",
+        "tests/setup.py",
+        "web/jest.config.js",
+        "web/setupTests",
+        "web/vitest.config.ts",
+    ])
+    def test_not_a_test_setup_file(self, path):
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _added_file(path, [PIN]),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+    def test_a_comparison_is_not_a_pin(self):
+        files = _files(
+            _added_file("web/src/progress.ts", ['const on = process.env.PROGRESS_NOTES ?? "true";']),
+            _added_file("web/src/setupTests.ts", ['if (process.env.PROGRESS_NOTES == "false") {}']),
+        )
+        assert toggle_pinned_off_findings(files) == []
+
+
+class TestSupportedForms:
+    """One positive per toggle shape and per pin shape, as the docstring lists them."""
+
+    @pytest.mark.parametrize(("path", "toggle", "call", "name"), [
+        ("app/progress.py", 'on = enabled("progress_notes", default=True)',
+         'enabled("progress_notes", default=True)', "progress_notes"),
+        ("app/progress.py", 'on = flag("progress_notes", True)', 'flag("progress_notes", True)', "progress_notes"),
+        ("web/progress.ts", 'const on = features.isEnabled("progress-notes", true);',
+         'features.isEnabled("progress-notes", true)', "progress-notes"),
+        ("app/Progress.kt", 'val on = Flags.flag("progress.notes", default = true)',
+         'Flags.flag("progress.notes", default = true)', "progress.notes"),
+        ("app/progress.py", 'on = os.getenv("APP_PROGRESS_NOTES", "true") == "true"',
+         'os.getenv("APP_PROGRESS_NOTES", "true")', "APP_PROGRESS_NOTES"),
+        ("app/progress.py", "on = os.environ.get('PROGRESS_NOTES', 'True')",
+         "os.environ.get('PROGRESS_NOTES', 'True')", "PROGRESS_NOTES"),
+        ("app/Progress.java", 'boolean on = Boolean.parseBoolean(System.getProperty("app.progress.notes", "true"));',
+         'System.getProperty("app.progress.notes", "true")', "app.progress.notes"),
+        ("web/progress.ts", 'const on = process.env.PROGRESS_NOTES ?? "true";',
+         'process.env.PROGRESS_NOTES ?? "true"', "PROGRESS_NOTES"),
+        ("web/progress.js", "const on = process.env['PROGRESS_NOTES'] || 'true';",
+         "process.env['PROGRESS_NOTES'] || 'true'", "PROGRESS_NOTES"),
+    ])
+    def test_toggle_form(self, path, toggle, call, name):
+        files = _files(
+            _added_file(path, [toggle]),
+            _added_file("tests/conftest.py", ['    monkeypatch.setenv("APP_PROGRESS_NOTES", "false")']),
+        )
+        findings = toggle_pinned_off_findings(files)
+        assert [(f.file, f.line) for f in findings] == [(path, 1)]
+        assert f"`{call}`" in findings[0].body
+        assert f'"{name}"' in findings[0].title
+
+    @pytest.mark.parametrize(("path", "pin", "pin_name", "value"), [
+        ("tests/conftest.py", 'monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")',
+         "ASSISTANT_PROGRESS_NOTES", "false"),
+        ("tests/conftest.py", "monkeypatch.setenv('ASSISTANT_PROGRESS_NOTES', '0')", "ASSISTANT_PROGRESS_NOTES", "0"),
+        ("conftest.py", 'monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "OFF")', "ASSISTANT_PROGRESS_NOTES", "OFF"),
+        ("tests/conftest.py", 'os.environ["ASSISTANT_PROGRESS_NOTES"] = "False"', "ASSISTANT_PROGRESS_NOTES", "False"),
+        ("web/src/setupTests.ts", 'process.env.ASSISTANT_PROGRESS_NOTES = "false";',
+         "ASSISTANT_PROGRESS_NOTES", "false"),
+        ("web/jest.setup.js", "process.env['ASSISTANT_PROGRESS_NOTES'] = '0';", "ASSISTANT_PROGRESS_NOTES", "0"),
+        ("web/vitest.setup.ts", 'vi.stubEnv("ASSISTANT_PROGRESS_NOTES", "off");', "ASSISTANT_PROGRESS_NOTES", "off"),
+        ("src/test/setupTests.kt", 'System.setProperty("assistant.progress.notes", "false")',
+         "assistant.progress.notes", "false"),
+    ])
+    def test_pin_form(self, path, pin, pin_name, value):
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _added_file(path, [pin]),
+        )
+        findings = toggle_pinned_off_findings(files)
+        assert [(f.file, f.line) for f in findings] == [("assistant/progress.py", TOGGLE_LINE)]
+        assert f'{path} sets `{pin_name}` to "{value}"' in findings[0].body
+
+
+class TestMultiplicity:
+    """One finding per toggle, every pinning file named, stable order."""
+
+    def test_two_pin_files_one_finding_naming_both_in_order(self):
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _added_file("web/vitest.setup.ts", ['vi.stubEnv("PROGRESS_NOTES", "0");']),
+            _added_file("tests/conftest.py", CONFTEST_PY),
+        )
+        findings = toggle_pinned_off_findings(files)
+        assert len(findings) == 1
+        body = findings[0].body
+        first = body.index('tests/conftest.py sets `ASSISTANT_PROGRESS_NOTES` to "false"')
+        second = body.index('web/vitest.setup.ts sets `PROGRESS_NOTES` to "0"')
+        assert first < second
+
+    def test_a_repeated_pin_is_named_once(self):
+        files = _files(
+            _added_file("assistant/progress.py", PROGRESS_PY),
+            _added_file("tests/conftest.py", [PIN, PIN]),
+        )
+        body = toggle_pinned_off_findings(files)[0].body
+        assert body.count("tests/conftest.py sets") == 1
+
+    def test_two_pinned_toggles_two_findings_sorted(self):
+        files = _files(
+            _added_file("b/second.py", ['dark = enabled("dark_mode", default=True)']),
+            _added_file("a/first.py", ["", 'on = flag("progress_notes", True)']),
+            _added_file("tests/conftest.py", [
+                PIN,
+                '    monkeypatch.setenv("ASSISTANT_DARK_MODE", "off")',
+            ]),
+        )
+        findings = toggle_pinned_off_findings(files)
+        assert [(f.file, f.line) for f in findings] == [("a/first.py", 2), ("b/second.py", 1)]
+
+    def test_only_the_pinned_toggle_is_reported(self):
+        files = _files(
+            _added_file("app/flags.py", [
+                'notes = enabled("progress_notes", default=True)',
+                'dark = enabled("dark_mode", default=True)',
+            ]),
+            _added_file("tests/conftest.py", [PIN]),
+        )
+        findings = toggle_pinned_off_findings(files)
+        assert [(f.file, f.line) for f in findings] == [("app/flags.py", 1)]

From a466e5c4764f8ef192a1bb027e39ea6bfb06c3b1 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:09:48 -0700
Subject: [PATCH 03/25] feat: retry a worker or sweep reply that cannot be used
 (#21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

review_chunk and review_systemic take a keyword-only parse_retries (library
default 0) and thread it into _invoke_and_parse, which now runs one shared
retry budget over the same request: an empty reply, an unparseable one, a
non-object, and, at parse_retries >= 1 only, an object without a findings
list are sent again while fewer than N retries have run. An empty reply
keeps its single retry at N=0, so a unit makes at most 1+max(N,1) calls.
Budget stops (finish_reason length/max_tokens) and raised calls are never
retried.

A reply still unusable when the budget is spent fails with its own error,
worded as before; at N >= 1 an object without findings fails with
"worker review JSON has no findings list". At N=0 the behaviour, log lines,
meta keys and trace files are unchanged, and {} stays a clean review.

Every call's usage folds through _fold_retry_usage. When a retry ran at
N >= 1, meta and meta.json gain parse_retries and first_error after the
eight base keys, each retry logs one "parse retry <k> of <N>" warning, and
each discarded reply is traced as <label>.attempt<K>.response.json beside
the four files of the used attempt. _write_trace_files keeps its
positional signature and gains a keyword-only attempts argument; a later
write of the same label removes attempt files it did not make.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/reviewer.py             | 274 +++++++++-----
 tests/test_parse_retry_reviewer.py | 560 +++++++++++++++++++++++++++++
 2 files changed, 754 insertions(+), 80 deletions(-)
 create mode 100644 tests/test_parse_retry_reviewer.py

diff --git a/src/prxref/reviewer.py b/src/prxref/reviewer.py
index 2b9763a..497c6cf 100644
--- a/src/prxref/reviewer.py
+++ b/src/prxref/reviewer.py
@@ -2,9 +2,10 @@
 
 The reviewer renders ``prompts/worker.md`` with the chunk's unified diff,
 makes a single :meth:`LLMClient.invoke` call (the model fallback chain
-handles transient failures; the one retry here is for a reply that came
-back empty, made once with the same prompt), and maps the JSON response
-onto :class:`prxref.triage.Finding` records. Unparseable or malformed
+handles transient failures; the retries here re-send the same request when
+the reply came back empty, and, when the caller grants ``parse_retries``,
+when it cannot be used as a review), and maps the JSON response onto
+:class:`prxref.triage.Finding` records. Unparseable or malformed
 responses degrade to ``([], [])`` with a logged warning; this layer
 never raises. :func:`review_systemic` is the same contract over the
 whole-PR digest built by :mod:`prxref.systemic`, for the second-order
@@ -187,13 +188,13 @@ def _result_cost(result: Any) -> tuple[float | None, str]:
 
 
 def _fold_retry_usage(meta: dict, result: Any) -> None:
-    """Add the empty-reply retry's usage to ``meta``, which holds the first call's.
+    """Add one retry call's usage to ``meta``, which holds the earlier calls'.
 
-    Both calls were billed, so ``input_tokens`` and ``output_tokens`` are
+    Every call was billed, so ``input_tokens`` and ``output_tokens`` are
     summed. ``model`` becomes the retry's, the reply the unit went on to use.
     The reported cost folds through :func:`prxref.costs.combine_reported`,
     the rule a backend applies to the attempts inside one invoke: the sum
-    when both calls reported a figure, else ``None`` with source ``""``. A
+    when every call reported a figure, else ``None`` with source ``""``. A
     ``None`` leaves the unit to :func:`prxref.costs.run_cost`, which prices it
     from the summed tokens when a price table knows the model.
     """
@@ -493,6 +494,8 @@ def _write_trace_files(
     user: str,
     raw_text: str | None,
     meta: dict,
+    *,
+    attempts: Sequence[str | None] | None = None,
 ) -> None:
     """Dump one review unit's prompt, response, and cost meta under ``trace_dir``.
 
@@ -503,15 +506,23 @@ def _write_trace_files(
     produced a response), and ``<label>.meta.json`` carries ``unit``, ``model``,
     token counts, ``elapsed_ms``, ``error``, ``cost_usd`` (the dollar figure
     the backend reported for the call, ``null`` when it reported none) and
-    ``cost_source`` (where that figure came from, ``""`` when ``null``).
+    ``cost_source`` (where that figure came from, ``""`` when ``null``). When
+    ``meta`` holds ``parse_retries``, the meta file adds ``parse_retries`` and
+    ``first_error`` after those eight keys; otherwise it has exactly the eight.
 
     Each file lands via a temp file plus :func:`os.replace`, so a concurrent
     reader never observes a half-written file, and a timeout retry simply
     overwrites: the trace ends up showing the attempt whose result was used.
-    The empty-reply retry in :func:`_invoke_and_parse` writes only once,
-    after its final call, so the files describe that call (the meta's token
-    counts cover both calls) and the empty first reply is visible only in its
-    WARNING log line.
+    The retries in :func:`_invoke_and_parse` write only once, after the
+    final call, so the four files describe that call (the meta's token
+    counts cover every call). ``attempts`` holds the raw texts of the replies
+    that were discarded before it, in call order, and each lands in
+    ``<label>.attempt<K>.response.json`` (K from 1), encoded like the
+    response file; any ``attempt<K>`` file beyond them left by an earlier
+    write of the same label is removed, so the set always matches the meta.
+    ``None``, the default, touches no attempt file: that is the 0.16.0
+    behaviour, where an empty first reply is visible only in its WARNING log
+    line.
     Empty ``trace_dir`` is the declared off switch and does nothing — no
     directory, no syscalls, no cost. Every failure (directory cannot be
     created, path unwritable, disk full) is a logged warning and nothing more:
@@ -532,25 +543,84 @@ def _write_trace_files(
             "cost_usd": meta.get("cost_usd"),
             "cost_source": meta.get("cost_source", ""),
         }
+        if "parse_retries" in meta:
+            payload["parse_retries"] = meta["parse_retries"]
+            payload["first_error"] = meta.get("first_error", "")
         files = [
             (".system.md", system),
             (".user.md", user),
             (".response.json", json.dumps(raw_text, ensure_ascii=False)),
             (".meta.json", json.dumps(payload, ensure_ascii=False, indent=2) + "\n"),
         ]
+        files.extend(
+            (f".attempt{k}.response.json", json.dumps(text, ensure_ascii=False))
+            for k, text in enumerate(attempts or (), start=1)
+        )
         for suffix, data in files:
             tmp = base + suffix + ".tmp"
             with open(tmp, "w", encoding="utf-8") as f:
                 f.write(data)
             os.replace(tmp, base + suffix)
+        if attempts is not None:
+            _remove_stale_attempts(base, len(attempts) + 1)
     except OSError as e:
         logger.warning("trace write for %s failed (continuing): %s", trace_label, e)
 
 
+def _remove_stale_attempts(base: str, first: int) -> None:
+    """Delete ``<base>.attempt<K>.response.json`` for K from ``first`` until one is missing."""
+    k = first
+    while True:
+        try:
+            os.remove(f"{base}.attempt{k}.response.json")
+        except FileNotFoundError:
+            return
+        k += 1
+
+
+_NO_FINDINGS_ERROR = "worker review JSON has no findings list"
+
+
+def _read_reply(result: Any, *, require_findings: bool) -> tuple[Any, str, bool]:
+    """Parse one reply into ``(parsed, problem, unparseable)``.
+
+    ``problem`` is ``""`` for a usable reply: one that parses to a JSON
+    object and, when ``require_findings``, holds a ``findings`` list.
+    Otherwise it is the error the unit reports for this reply when the
+    budget is not to blame, and ``unparseable`` is true when no strategy of
+    :func:`prxref.parser.loads_lenient` produced JSON at all.
+    """
+    try:
+        parsed = loads_lenient(result.text)
+    except Exception as e:  # noqa: BLE001
+        return None, f"{type(e).__name__}: {e}", True
+    if not isinstance(parsed, dict):
+        return parsed, f"worker review JSON is not an object: {type(parsed).__name__}", False
+    if require_findings and not isinstance(parsed.get("findings"), list):
+        return parsed, _NO_FINDINGS_ERROR, False
+    return parsed, "", False
+
+
+def _may_retry(result: Any, problem: str, retries: int, parse_retries: int) -> bool:
+    """True when an unusable reply earns one more call under the shared budget.
+
+    ``retries`` counts the retries already made. An EMPTY reply is retried
+    while ``retries < max(parse_retries, 1)``, so it gets one retry even at
+    ``parse_retries=0``; every other unusable reply only while
+    ``retries < parse_retries``. A usable reply is never retried, and the
+    caller keeps budget stops away from here, because those never are.
+    """
+    if not problem:
+        return False
+    if _is_empty_reply(result):
+        return retries < max(parse_retries, 1)
+    return retries < parse_retries
+
+
 def _invoke_and_parse(
     llm: LLMClient, system: str, user: str, *, budget: int, label: str,
     trace_dir: str = "", trace_label: str = "", accept_scope: bool = False,
-    accept_rule: bool = False,
+    accept_rule: bool = False, parse_retries: int = 0,
 ) -> tuple[list[Finding], dict]:
     """One single-shot invoke plus lenient JSON parse, shared by both reviewers.
 
@@ -573,23 +643,44 @@ def _invoke_and_parse(
     :func:`prxref.triage.normalize_rule`); false, the default, leaves every
     finding's ``rule`` at ``None``.
 
-    A reply that came back EMPTY (no text, or whitespace only) is asked for
-    again, once, with the same prompt and the same budget, after one WARNING
-    ``<label>: empty model reply (finish_reason=<reason>); retrying once``
-    (``-`` when no reason was reported). Nothing else is retried: not a reply
-    the provider stopped at the budget (``finish_reason`` ``length`` or
-    ``max_tokens``, the truncation path, which already names the budget
-    lever), not a non-empty reply that fails to parse, and not a call that
-    raised. At most one extra call is made. ``input_tokens``,
-    ``output_tokens`` and ``elapsed_ms`` then cover both calls, ``model`` is
-    the second call's, and ``cost_usd`` follows
-    :func:`_fold_retry_usage`. The second reply is handled exactly as a
-    first reply would be, so an empty one fails the unit with the same error
-    as before. A retry that raises fails the unit with that exception, keeping
-    the first call's tokens. Per unit the worst case is 4 ``invoke`` calls
-    for a chunk (these 2, times the orchestrator's one timeout retry of the
-    whole chunk) and 2 for the systemic sweep, which has no timeout retry;
-    each ``invoke`` may still walk the backend's model fallback chain.
+    ``parse_retries`` (N, default 0) is one retry budget shared by every
+    kind of reply that cannot be used as a review. The same request, with
+    the same prompt and the same budget, is sent again while fewer than N
+    retries have run, when the reply is empty (no text, or whitespace
+    only), fails to parse, parses to something other than a JSON object,
+    or, at N of 1 or more only, parses to an object without a ``findings``
+    list. An EMPTY reply is asked for again once even at N=0, after one
+    WARNING ``<label>: empty model reply (finish_reason=<reason>); retrying
+    once`` (``-`` when no reason was reported), so a unit makes at most
+    ``1 + max(N, 1)`` calls here. At N=0 nothing else is retried and an
+    object without ``findings`` is a clean review with none, exactly as in
+    0.16.0. Never retried at any N: a reply the provider stopped at the
+    budget (``finish_reason`` ``length`` or ``max_tokens``, the truncation
+    path, which already names the budget lever) and a call that raised.
+
+    At N of 1 or more each retry logs one WARNING, ``<label>: empty model
+    reply (finish_reason=<reason>); parse retry <k> of <N>`` or ``<label>:
+    unusable model reply (<error>); parse retry <k> of <N>``, and ``meta``
+    gains ``parse_retries`` (the retries made) and ``first_error`` (the
+    error the first reply would have failed the unit with) after its eight
+    base keys; with a trace on, each discarded reply lands in
+    ``<label>.attempt<K>.response.json`` (:func:`_write_trace_files`). At
+    N=0 ``meta`` keeps exactly its eight keys and no attempt file is
+    written, even after an empty-reply retry.
+
+    Every call's usage counts: ``input_tokens``, ``output_tokens`` and
+    ``elapsed_ms`` cover all of them, ``model`` is the last call's, and
+    ``cost_usd`` follows :func:`_fold_retry_usage`. The last reply is
+    handled exactly as a first reply would be: once the budget is spent, a
+    reply that still cannot be used fails the unit with ITS error, worded
+    as in 0.16.0, and an object without ``findings`` fails it with
+    ``worker review JSON has no findings list``. A retry that raises fails
+    the unit with that exception, keeping the earlier calls' tokens. Per
+    unit the worst case is ``2 * (1 + max(N, 1))`` ``invoke`` calls for a
+    chunk (these, times the orchestrator's one timeout retry of the whole
+    chunk) and ``1 + max(N, 1)`` for the systemic sweep, which has no
+    timeout retry; each ``invoke`` may still walk the backend's model
+    fallback chain.
     """
     t0 = time.perf_counter()
     meta = {
@@ -602,36 +693,14 @@ def _invoke_and_parse(
         "cost_usd": None,
         "cost_source": "",
     }
+    attempts: list[str | None] | None = [] if parse_retries >= 1 else None
+    retries = 0
 
     # The invoke and the parse are caught separately on purpose: only the
     # invoke's result knows WHY generation stopped, and the parse failure is
     # exactly where that reason has to be spoken. Neither is allowed to raise
     # out of this function — the never-raise contract is unchanged.
-    try:
-        result = llm.invoke(
-            system=system,
-            user=user,
-            max_tokens=budget,
-            json_mode=True,
-        )
-    except Exception as e:  # noqa: BLE001
-        logger.warning("worker review failed for %s: %s", label, e)
-        meta["error"] = f"{type(e).__name__}: {e}"
-        meta["elapsed_ms"] = int((time.perf_counter() - t0) * 1000)
-        _write_trace_files(trace_dir, trace_label, system, user, None, meta)
-        return [], meta
-
-    meta["input_tokens"] = result.input_tokens
-    meta["output_tokens"] = result.output_tokens
-    meta["model"] = result.model
-    meta["cost_usd"], meta["cost_source"] = _result_cost(result)
-
-    stop_reason = _budget_stop_reason(result)
-    if not stop_reason and _is_empty_reply(result):
-        logger.warning(
-            "%s: empty model reply (finish_reason=%s); retrying once",
-            label, _finish_reason_text(result),
-        )
+    while True:
         try:
             result = llm.invoke(
                 system=system,
@@ -643,36 +712,64 @@ def _invoke_and_parse(
             logger.warning("worker review failed for %s: %s", label, e)
             meta["error"] = f"{type(e).__name__}: {e}"
             meta["elapsed_ms"] = int((time.perf_counter() - t0) * 1000)
-            _write_trace_files(trace_dir, trace_label, system, user, None, meta)
+            _write_trace_files(trace_dir, trace_label, system, user, None, meta, attempts=attempts)
             return [], meta
-        _fold_retry_usage(meta, result)
+
+        if retries:
+            _fold_retry_usage(meta, result)
+        else:
+            meta["input_tokens"] = result.input_tokens
+            meta["output_tokens"] = result.output_tokens
+            meta["model"] = result.model
+            meta["cost_usd"], meta["cost_source"] = _result_cost(result)
+
         stop_reason = _budget_stop_reason(result)
+        parsed, problem, unparseable = _read_reply(result, require_findings=attempts is not None)
+        if stop_reason or not _may_retry(result, problem, retries, parse_retries):
+            break
+        retries += 1
+        if attempts is None:
+            logger.warning(
+                "%s: empty model reply (finish_reason=%s); retrying once",
+                label, _finish_reason_text(result),
+            )
+            continue
+        attempts.append(result.text)
+        meta["parse_retries"] = retries
+        meta.setdefault("first_error", problem)
+        if _is_empty_reply(result):
+            logger.warning(
+                "%s: empty model reply (finish_reason=%s); parse retry %d of %d",
+                label, _finish_reason_text(result), retries, parse_retries,
+            )
+        else:
+            logger.warning(
+                "%s: unusable model reply (%s); parse retry %d of %d",
+                label, problem, retries, parse_retries,
+            )
 
     truncated_error = _TRUNCATED_ERROR.format(budget=budget, reason=stop_reason)
 
-    try:
-        parsed = loads_lenient(result.text)
-    except Exception as e:  # noqa: BLE001
+    if unparseable:
         # A truncated completion and a model that simply refused to emit JSON
         # produce the same JSONDecodeError, and only one of them has a lever
         # the operator can pull. Say which one this is.
-        reason = truncated_error if stop_reason else f"{type(e).__name__}: {e}"
+        reason = truncated_error if stop_reason else problem
         logger.warning("worker review failed for %s: %s", label, reason)
         meta["error"] = reason
         meta["elapsed_ms"] = int((time.perf_counter() - t0) * 1000)
-        _write_trace_files(trace_dir, trace_label, system, user, result.text, meta)
+        _write_trace_files(trace_dir, trace_label, system, user, result.text, meta, attempts=attempts)
         return [], meta
 
     meta["elapsed_ms"] = int((time.perf_counter() - t0) * 1000)
 
-    if not isinstance(parsed, dict):
+    if problem:
         # Valid JSON of the wrong shape is just as unusable as none, so it gets
         # the same treatment: if the budget is why it came out that way, say so
         # rather than reporting the shape and leaving the cause unspoken.
-        detail = f"worker review JSON is not an object: {type(parsed).__name__}"
-        logger.warning(detail)
-        meta["error"] = truncated_error if stop_reason else detail
-        _write_trace_files(trace_dir, trace_label, system, user, result.text, meta)
+        logger.warning(problem)
+        meta["error"] = truncated_error if stop_reason else problem
+        _write_trace_files(trace_dir, trace_label, system, user, result.text, meta, attempts=attempts)
         return [], meta
 
     if stop_reason:
@@ -702,7 +799,7 @@ def _invoke_and_parse(
         raw_esc = []
     meta["escalations"] = [e for e in raw_esc if isinstance(e, dict)]
 
-    _write_trace_files(trace_dir, trace_label, system, user, result.text, meta)
+    _write_trace_files(trace_dir, trace_label, system, user, result.text, meta, attempts=attempts)
     return findings, meta
 
 
@@ -720,8 +817,9 @@ def review_chunk(
     trace_dir: str = "",
     trace_label: str = "",
     prompt_context: PromptContext = NO_PROMPT_CONTEXT,
+    parse_retries: int = 0,
 ) -> tuple[list[Finding], dict]:
-    """Review one chunk with a single LLM call, repeated once when the reply is empty.
+    """Review one chunk with a single LLM call, repeated when the reply cannot be used.
 
     Returns ``(findings, meta)`` where ``meta`` carries ``escalations`` plus
     cost telemetry (``input_tokens``, ``output_tokens``, ``model``,
@@ -731,22 +829,34 @@ def review_chunk(
     unfiltered — the quality gate normalizes and drops downstream. A missing
     ``confidence`` maps to 0.5. Any LLM or parse failure logs a warning and
     yields ``([], meta)`` with ``meta["error"]`` set to the failure reason;
-    this layer never raises, and the only retry it makes is one repeat of an
-    EMPTY reply with the same prompt (:func:`_invoke_and_parse`), so a chunk
-    costs at most 2 ``invoke`` calls here and at most 4 with the
-    orchestrator's timeout retry. ``meta["error"]`` is the empty string on
-    success.
+    this layer never raises, and the only retries it makes re-send the same
+    prompt for a reply that cannot be used (:func:`_invoke_and_parse`), so a
+    chunk costs at most ``1 + max(parse_retries, 1)`` ``invoke`` calls here
+    and twice that with the orchestrator's timeout retry. ``meta["error"]``
+    is the empty string on success.
 
     When the response cannot be parsed and the backend reported
     ``finish_reason == "length"``, ``meta["error"]`` names the budget that was
     in force and the variable that raises it — the operator's lever — instead
-    of a ``JSONDecodeError`` that looks like a model-quality problem, and an
-    empty one is not retried. A clean empty response (any other finish
-    reason) is retried once; when the retry is empty too, it keeps the parse
+    of a ``JSONDecodeError`` that looks like a model-quality problem, and it
+    is not retried, empty or not. A clean empty response (any other finish
+    reason) is retried; when the last retry is empty too, it keeps the parse
     error verbatim and is never mislabelled as truncation. A response that
     parses to the wrong SHAPE is treated the same way: unusable is unusable,
     and the budget is named when the budget is why.
 
+    ``parse_retries`` is how many extra calls a reply that cannot be used
+    may cost: an empty one, an unparseable one, one that is not a JSON
+    object, and, from 1 up, an object without a ``findings`` list, all
+    drawing on the one budget. ``0``, the library default, is 0.16.0's
+    behaviour exactly: only an empty reply is asked for again, once, and an
+    object without ``findings`` is a clean review. From 1 up, a reply that
+    lacks ``findings`` on the last call fails the chunk with ``worker review
+    JSON has no findings list``; whenever a retry ran, ``meta`` gains
+    ``parse_retries`` and ``first_error``, and a trace keeps each discarded
+    reply as ``<label>.attempt<K>.response.json``. Production callers pass
+    the run's ``PRXREF_LLM_PARSE_RETRIES``.
+
     ``max_tokens`` is the completion budget for the call; ``None`` keeps the
     module default :data:`MAX_TOKENS`, so direct callers are unaffected. The
     orchestrator always passes the keyword (``None`` included), so any test
@@ -807,6 +917,7 @@ def review_chunk(
         trace_dir=trace_dir, trace_label=trace_label,
         accept_scope=prompt_context.scope_active,
         accept_rule=prompt_context.rule_active,
+        parse_retries=parse_retries,
     )
 
 
@@ -822,8 +933,9 @@ def review_systemic(
     trace_dir: str = "",
     trace_label: str = "",
     prompt_context: PromptContext = NO_PROMPT_CONTEXT,
+    parse_retries: int = 0,
 ) -> tuple[list[Finding], dict]:
-    """Review the whole-PR systemic digest with a single LLM call, repeated once when the reply is empty.
+    """Review the whole-PR systemic digest with a single LLM call, repeated when the reply cannot be used.
 
     The second-order complement to :func:`review_chunk`: chunk workers each
     see one slice of the diff, so cross-file classes — an unauthenticated
@@ -842,9 +954,10 @@ def review_systemic(
 
     Returns ``(findings, meta)`` under exactly the :func:`review_chunk`
     contract — never raises, ``meta["error"]`` empty on success, truncation
-    named when the budget is why, an empty reply asked for once more — so
-    the orchestrator can treat the sweep as one more worker-style unit for
-    coverage accounting.
+    named when the budget is why, a reply that cannot be used asked for
+    again under ``parse_retries``, with the same errors, meta keys and
+    attempt files — so the orchestrator can treat the sweep as one more
+    worker-style unit for coverage accounting.
 
     ``trace_dir``/``trace_label`` work exactly as in :func:`review_chunk`;
     the orchestrator passes ``trace_label="sweep"`` so the sweep's prompt and
@@ -864,4 +977,5 @@ def review_systemic(
         trace_dir=trace_dir, trace_label=trace_label,
         accept_scope=prompt_context.scope_active,
         accept_rule=prompt_context.rule_active,
+        parse_retries=parse_retries,
     )
diff --git a/tests/test_parse_retry_reviewer.py b/tests/test_parse_retry_reviewer.py
new file mode 100644
index 0000000..5af48f8
--- /dev/null
+++ b/tests/test_parse_retry_reviewer.py
@@ -0,0 +1,560 @@
+"""A reply that cannot be used as a review is asked for again (#21).
+
+``parse_retries`` (N) is one budget shared by every kind of unusable reply:
+empty, unparseable, not a JSON object, and, at N of 1 or more, an object
+without a ``findings`` list. The same request is sent again while fewer than
+N retries have run; an empty reply keeps its single retry at N=0. A reply the
+provider stopped at the budget, and a call that raised, are never retried.
+N=0, the library default, behaves exactly as 0.16.0 did.
+
+Every behaviour is checked through both reviewers, ``review_chunk`` and
+``review_systemic``, which share one parse path.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import pytest
+
+from prxref.llm import InvokeResult
+from prxref.reviewer import _write_trace_files, review_chunk, review_systemic
+from prxref.triage import parse_unified_diff
+
+MINI_DIFF = """\
+diff --git a/src/app.py b/src/app.py
+--- a/src/app.py
++++ b/src/app.py
+@@ -1,3 +1,4 @@
+ import os
++import sys
+ def main():
+     print("hi")
+"""
+
+VALID = json.dumps({
+    "findings": [
+        {
+            "file": "src/app.py", "line": 2, "severity": "error",
+            "confidence": 0.9, "title": "Unused import",
+            "body": "sys is imported and never used.",
+        },
+    ],
+    "escalations": [],
+})
+
+GARBAGE = "I am not returning JSON."
+GARBAGE_ERROR = "JSONDecodeError: Expecting value: line 1 column 1 (char 0)"
+CUT_OFF = '{"findings": ['
+CUT_OFF_ERROR = "JSONDecodeError: Expecting value: line 1 column 15 (char 14)"
+STRAY_QUOTE = '{"findings":[{"file":"src/app.py","line":72","title":"x"}]}'
+STRAY_QUOTE_ERROR = "JSONDecodeError: Expecting ',' delimiter: line 1 column 44 (char 43)"
+EMPTY_ERROR = "JSONDecodeError: no parseable content: line 1 column 1 (char 0)"
+NO_FINDINGS_ERROR = "worker review JSON has no findings list"
+LIST_ERROR = "worker review JSON is not an object: list"
+BUDGET_ERROR = (
+    "response truncated at max_tokens=512 (finish_reason=length); "
+    "raise PRXREF_LLM_MAX_TOKENS"
+)
+
+BASE_META_KEYS = [
+    "escalations", "input_tokens", "output_tokens", "model", "elapsed_ms",
+    "error", "cost_usd", "cost_source",
+]
+BASE_META_JSON_KEYS = [
+    "unit", "model", "input_tokens", "output_tokens", "elapsed_ms",
+    "error", "cost_usd", "cost_source",
+]
+RETRY_KEYS = ["parse_retries", "first_error"]
+
+
+def reply(text, *, finish_reason="stop", input_tokens=100, output_tokens=50,
+          model="fake-model", cost_usd=None, cost_source=""):
+    return InvokeResult(
+        text=text, input_tokens=input_tokens, output_tokens=output_tokens,
+        model=model, backend="fake", elapsed_ms=1, finish_reason=finish_reason,
+        cost_usd=cost_usd, cost_source=cost_source,
+    )
+
+
+class ScriptedLLM:
+    """Answers each ``invoke`` with the next scripted step and records the call.
+
+    A step is an :class:`InvokeResult` to return or an exception to raise.
+    Running past the script fails the test loudly instead of inventing a reply.
+    """
+
+    def __init__(self, *script):
+        self._script = list(script)
+        self.calls: list[dict] = []
+        self._lock = threading.Lock()
+
+    def invoke(self, system, user, *, max_tokens=4096, json_mode=False, timeout_s=None):
+        with self._lock:
+            self.calls.append({
+                "system": system, "user": user,
+                "max_tokens": max_tokens, "json_mode": json_mode,
+            })
+            if not self._script:
+                raise AssertionError(f"unscripted call #{len(self.calls)}")
+            step = self._script.pop(0)
+        if isinstance(step, BaseException):
+            raise step
+        return step
+
+
+@dataclass(frozen=True)
+class Unit:
+    """One reviewer entry point, with the names it goes by in traces and logs."""
+
+    review: Callable[..., tuple]
+    trace_label: str
+    log_label: str
+
+
+def _review_chunk(llm, **kwargs):
+    return review_chunk(llm, parse_unified_diff(MINI_DIFF), **kwargs)
+
+
+def _review_sweep(llm, **kwargs):
+    return review_systemic(llm, "the whole-pr digest", **kwargs)
+
+
+@pytest.fixture(params=[
+    pytest.param(Unit(_review_chunk, "chunk0", "chunk of 1 files"), id="chunk"),
+    pytest.param(Unit(_review_sweep, "sweep", "systemic sweep"), id="sweep"),
+])
+def unit(request) -> Unit:
+    return request.param
+
+
+def _traced(unit: Unit, llm, tmp_path, **kwargs):
+    return unit.review(llm, trace_dir=str(tmp_path), trace_label=unit.trace_label, **kwargs)
+
+
+def _files(tmp_path) -> list[str]:
+    return sorted(p.name for p in tmp_path.iterdir())
+
+
+def _base_files(label: str) -> list[str]:
+    return sorted(f"{label}{s}" for s in (".system.md", ".user.md", ".response.json", ".meta.json"))
+
+
+def _response(tmp_path, name: str):
+    return json.loads((tmp_path / name).read_text(encoding="utf-8"))
+
+
+def _warnings(caplog) -> list[str]:
+    return [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+
+
+class TestMalformedThenValid:
+    def test_two_calls_and_the_second_replys_findings(self, unit):
+        llm = ScriptedLLM(reply(GARBAGE), reply(VALID))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert [f.title for f in findings] == ["Unused import"]
+        assert meta["error"] == ""
+        assert meta["parse_retries"] == 1
+        assert meta["first_error"] == GARBAGE_ERROR
+
+    def test_the_retry_resends_the_same_request(self, unit):
+        llm = ScriptedLLM(reply(GARBAGE), reply(VALID))
+        unit.review(llm, parse_retries=1, max_tokens=900)
+        first, second = llm.calls
+        assert second == first
+        assert first["max_tokens"] == 900
+        assert first["json_mode"] is True
+
+    def test_meta_gains_the_two_keys_after_the_eight_base_keys(self, unit):
+        llm = ScriptedLLM(reply(GARBAGE), reply(VALID))
+        _findings, meta = unit.review(llm, parse_retries=1)
+        assert list(meta) == BASE_META_KEYS + RETRY_KEYS
+
+    def test_the_trace_keeps_both_replies(self, unit, tmp_path):
+        llm = ScriptedLLM(reply(GARBAGE), reply(VALID))
+        _traced(unit, llm, tmp_path, parse_retries=1)
+        label = unit.trace_label
+        assert _files(tmp_path) == sorted(
+            _base_files(label) + [f"{label}.attempt1.response.json"],
+        )
+        assert _response(tmp_path, f"{label}.response.json") == VALID
+        assert _response(tmp_path, f"{label}.attempt1.response.json") == GARBAGE
+
+    def test_meta_json_records_the_retry_after_its_eight_keys(self, unit, tmp_path):
+        llm = ScriptedLLM(reply(GARBAGE), reply(VALID))
+        _traced(unit, llm, tmp_path, parse_retries=1)
+        traced = _response(tmp_path, f"{unit.trace_label}.meta.json")
+        assert list(traced) == BASE_META_JSON_KEYS + RETRY_KEYS
+        assert traced["parse_retries"] == 1
+        assert traced["first_error"] == GARBAGE_ERROR
+        assert traced["error"] == ""
+
+    def test_one_warning_names_the_error_and_the_count(self, unit, caplog):
+        llm = ScriptedLLM(reply(GARBAGE), reply(VALID))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            unit.review(llm, parse_retries=1)
+        assert _warnings(caplog) == [
+            f"{unit.log_label}: unusable model reply ({GARBAGE_ERROR}); parse retry 1 of 1",
+        ]
+
+
+class TestMalformedTwice:
+    def test_two_calls_and_the_last_error(self, unit):
+        assert CUT_OFF_ERROR != GARBAGE_ERROR
+        llm = ScriptedLLM(reply(GARBAGE), reply(CUT_OFF))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == CUT_OFF_ERROR
+        assert meta["first_error"] == GARBAGE_ERROR
+        assert meta["parse_retries"] == 1
+
+    def test_the_failure_is_logged_as_in_0_16(self, unit, caplog):
+        llm = ScriptedLLM(reply(GARBAGE), reply(CUT_OFF))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            unit.review(llm, parse_retries=1)
+        assert _warnings(caplog)[-1] == f"worker review failed for {unit.log_label}: {CUT_OFF_ERROR}"
+
+    def test_the_trace_uses_the_last_reply_and_keeps_the_first(self, unit, tmp_path):
+        llm = ScriptedLLM(reply(GARBAGE), reply(CUT_OFF))
+        _traced(unit, llm, tmp_path, parse_retries=1)
+        label = unit.trace_label
+        assert _response(tmp_path, f"{label}.response.json") == CUT_OFF
+        assert _response(tmp_path, f"{label}.attempt1.response.json") == GARBAGE
+        traced = _response(tmp_path, f"{label}.meta.json")
+        assert traced["error"] == CUT_OFF_ERROR
+        assert traced["first_error"] == GARBAGE_ERROR
+        assert traced["parse_retries"] == 1
+
+    def test_a_stray_quote_inside_the_object_is_retried(self, unit):
+        llm = ScriptedLLM(reply(STRAY_QUOTE), reply(VALID))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert len(findings) == 1
+        assert meta["first_error"] == STRAY_QUOTE_ERROR
+
+
+class TestWrongShape:
+    @pytest.mark.parametrize("text,error", [
+        pytest.param('[{"file": "src/app.py", "line": 2}]', LIST_ERROR, id="list"),
+        pytest.param("null", "worker review JSON is not an object: NoneType", id="null"),
+        pytest.param("{}", NO_FINDINGS_ERROR, id="empty-object"),
+        pytest.param('{"escalations": []}', NO_FINDINGS_ERROR, id="no-findings-key"),
+        pytest.param('{"findings": "none"}', NO_FINDINGS_ERROR, id="findings-not-a-list"),
+        pytest.param('{"findings": null}', NO_FINDINGS_ERROR, id="findings-null"),
+    ])
+    def test_is_retried_like_a_parse_failure(self, unit, text, error):
+        llm = ScriptedLLM(reply(text), reply(VALID))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert [f.title for f in findings] == ["Unused import"]
+        assert meta["error"] == ""
+        assert meta["parse_retries"] == 1
+        assert meta["first_error"] == error
+
+    def test_an_object_without_findings_twice_fails_the_unit(self, unit, caplog):
+        llm = ScriptedLLM(reply("{}"), reply('{"escalations": []}'))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == NO_FINDINGS_ERROR
+        assert meta["first_error"] == NO_FINDINGS_ERROR
+        assert _warnings(caplog)[-1] == NO_FINDINGS_ERROR
+
+    def test_a_list_twice_fails_the_unit_with_the_shape_error(self, unit):
+        llm = ScriptedLLM(reply("[]"), reply("[1, 2]"))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == LIST_ERROR
+
+    def test_an_empty_findings_list_is_a_clean_review_in_one_call(self, unit):
+        llm = ScriptedLLM(reply('{"findings": []}'))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 1
+        assert findings == []
+        assert list(meta) == BASE_META_KEYS
+        assert meta["error"] == ""
+
+
+class TestTheBudgetStopIsNeverRetried:
+    @pytest.mark.parametrize("text", [
+        pytest.param(CUT_OFF, id="unparseable"),
+        pytest.param("", id="empty"),
+        pytest.param("[1]", id="list"),
+        pytest.param("{}", id="no-findings"),
+    ])
+    def test_one_call_and_the_budget_message(self, unit, text, tmp_path):
+        llm = ScriptedLLM(reply(text, finish_reason="length"))
+        findings, meta = _traced(unit, llm, tmp_path, parse_retries=3, max_tokens=512)
+        assert len(llm.calls) == 1
+        assert findings == []
+        assert meta["error"] == BUDGET_ERROR
+        assert list(meta) == BASE_META_KEYS
+        assert _files(tmp_path) == _base_files(unit.trace_label)
+
+    def test_a_retry_stopped_at_the_budget_ends_the_retries(self, unit):
+        llm = ScriptedLLM(reply(GARBAGE), reply(CUT_OFF, finish_reason="length"))
+        findings, meta = unit.review(llm, parse_retries=3, max_tokens=512)
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == BUDGET_ERROR
+        assert meta["parse_retries"] == 1
+        assert meta["first_error"] == GARBAGE_ERROR
+
+    def test_a_truncated_usable_reply_is_kept_without_a_retry(self, unit):
+        llm = ScriptedLLM(reply(VALID, finish_reason="length"))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 1
+        assert len(findings) == 1
+        assert meta["error"] == ""
+
+
+class TestARaisingCallIsNeverRetried:
+    def test_a_first_call_that_raises_is_one_call(self, unit, tmp_path):
+        llm = ScriptedLLM(RuntimeError("upstream down"))
+        findings, meta = _traced(unit, llm, tmp_path, parse_retries=3)
+        assert len(llm.calls) == 1
+        assert findings == []
+        assert meta["error"] == "RuntimeError: upstream down"
+        assert list(meta) == BASE_META_KEYS
+        assert _files(tmp_path) == _base_files(unit.trace_label)
+
+    def test_a_retry_that_raises_fails_the_unit_and_keeps_the_first_reply(self, unit, tmp_path):
+        llm = ScriptedLLM(
+            reply(GARBAGE, input_tokens=100, output_tokens=7, model="first-model"),
+            RuntimeError("m: timeout (ReadTimeout)"),
+        )
+        findings, meta = _traced(unit, llm, tmp_path, parse_retries=3)
+        label = unit.trace_label
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == "RuntimeError: m: timeout (ReadTimeout)"
+        assert meta["input_tokens"] == 100
+        assert meta["output_tokens"] == 7
+        assert meta["model"] == "first-model"
+        assert meta["parse_retries"] == 1
+        assert meta["first_error"] == GARBAGE_ERROR
+        assert _response(tmp_path, f"{label}.response.json") is None
+        assert _response(tmp_path, f"{label}.attempt1.response.json") == GARBAGE
+
+
+class TestOneSharedBudget:
+    def test_an_empty_reply_draws_on_the_same_budget(self, unit, caplog):
+        llm = ScriptedLLM(reply(""), reply(GARBAGE))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == GARBAGE_ERROR
+        assert meta["parse_retries"] == 1
+        assert meta["first_error"] == EMPTY_ERROR
+        assert _warnings(caplog)[0] == (
+            f"{unit.log_label}: empty model reply (finish_reason=stop); parse retry 1 of 1"
+        )
+
+    def test_empty_twice_is_two_calls_and_the_empty_error(self, unit, tmp_path):
+        llm = ScriptedLLM(reply(""), reply(""))
+        findings, meta = _traced(unit, llm, tmp_path, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == EMPTY_ERROR
+        assert _response(tmp_path, f"{unit.trace_label}.attempt1.response.json") == ""
+
+    def test_an_empty_reply_after_a_malformed_one_is_not_a_third_call(self, unit):
+        llm = ScriptedLLM(reply(GARBAGE), reply(""))
+        findings, meta = unit.review(llm, parse_retries=1)
+        assert len(llm.calls) == 2
+        assert meta["error"] == EMPTY_ERROR
+        assert meta["first_error"] == GARBAGE_ERROR
+
+    def test_n_of_two_allows_three_calls_and_keeps_every_discarded_reply(self, unit, tmp_path, caplog):
+        llm = ScriptedLLM(reply(GARBAGE), reply("{}"), reply(CUT_OFF))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            findings, meta = _traced(unit, llm, tmp_path, parse_retries=2)
+        label = unit.trace_label
+        assert len(llm.calls) == 3
+        assert findings == []
+        assert meta["error"] == CUT_OFF_ERROR
+        assert meta["first_error"] == GARBAGE_ERROR
+        assert meta["parse_retries"] == 2
+        assert _files(tmp_path) == sorted(_base_files(label) + [
+            f"{label}.attempt1.response.json", f"{label}.attempt2.response.json",
+        ])
+        assert _response(tmp_path, f"{label}.attempt1.response.json") == GARBAGE
+        assert _response(tmp_path, f"{label}.attempt2.response.json") == "{}"
+        assert _response(tmp_path, f"{label}.response.json") == CUT_OFF
+        retry_lines = [m for m in _warnings(caplog) if "parse retry" in m]
+        assert retry_lines == [
+            f"{unit.log_label}: unusable model reply ({GARBAGE_ERROR}); parse retry 1 of 2",
+            f"{unit.log_label}: unusable model reply ({NO_FINDINGS_ERROR}); parse retry 2 of 2",
+        ]
+
+    def test_n_of_two_succeeds_on_the_third_call(self, unit):
+        llm = ScriptedLLM(reply("[]"), reply(""), reply(VALID))
+        findings, meta = unit.review(llm, parse_retries=2)
+        assert len(llm.calls) == 3
+        assert len(findings) == 1
+        assert meta["error"] == ""
+        assert meta["parse_retries"] == 2
+        assert meta["first_error"] == LIST_ERROR
+
+
+class TestUsageCoversEveryAttempt:
+    def test_tokens_are_summed_and_the_model_is_the_last_calls(self, unit):
+        llm = ScriptedLLM(
+            reply(GARBAGE, input_tokens=100, output_tokens=7, model="first-model"),
+            reply("{}", input_tokens=30, output_tokens=5, model="second-model"),
+            reply(VALID, input_tokens=20, output_tokens=50, model="third-model"),
+        )
+        _findings, meta = unit.review(llm, parse_retries=2)
+        assert meta["input_tokens"] == 150
+        assert meta["output_tokens"] == 62
+        assert meta["model"] == "third-model"
+
+    def test_reported_costs_are_summed_and_the_last_source_kept(self, unit):
+        llm = ScriptedLLM(
+            reply(GARBAGE, cost_usd=0.25, cost_source="usage.cost"),
+            reply(VALID, cost_usd=0.5, cost_source="x-litellm-response-cost"),
+        )
+        _findings, meta = unit.review(llm, parse_retries=1)
+        assert meta["cost_usd"] == 0.75
+        assert meta["cost_source"] == "x-litellm-response-cost"
+
+    def test_one_unreported_cost_makes_the_unit_cost_unknown(self, unit):
+        llm = ScriptedLLM(
+            reply(GARBAGE, cost_usd=0.25, cost_source="usage.cost"),
+            reply("{}"),
+            reply(VALID, cost_usd=0.5, cost_source="usage.cost"),
+        )
+        _findings, meta = unit.review(llm, parse_retries=2)
+        assert meta["cost_usd"] is None
+        assert meta["cost_source"] == ""
+
+    def test_the_trace_meta_carries_the_summed_tokens(self, unit, tmp_path):
+        llm = ScriptedLLM(
+            reply(GARBAGE, input_tokens=100, output_tokens=7),
+            reply(VALID, input_tokens=30, output_tokens=50),
+        )
+        _traced(unit, llm, tmp_path, parse_retries=1)
+        traced = _response(tmp_path, f"{unit.trace_label}.meta.json")
+        assert traced["input_tokens"] == 130
+        assert traced["output_tokens"] == 57
+
+
+class TestZeroIsTheOldBehaviour:
+    @pytest.fixture(params=[
+        pytest.param({}, id="default"),
+        pytest.param({"parse_retries": 0}, id="explicit-0"),
+    ])
+    def zero(self, request) -> dict:
+        return request.param
+
+    def test_garbage_is_one_call_and_the_parse_error(self, unit, zero, caplog):
+        llm = ScriptedLLM(reply(GARBAGE))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            findings, meta = unit.review(llm, **zero)
+        assert len(llm.calls) == 1
+        assert findings == []
+        assert meta["error"] == GARBAGE_ERROR
+        assert list(meta) == BASE_META_KEYS
+        assert _warnings(caplog) == [f"worker review failed for {unit.log_label}: {GARBAGE_ERROR}"]
+
+    def test_an_object_without_findings_is_a_clean_review(self, unit, zero):
+        llm = ScriptedLLM(reply("{}"))
+        findings, meta = unit.review(llm, **zero)
+        assert len(llm.calls) == 1
+        assert findings == []
+        assert meta["error"] == ""
+        assert list(meta) == BASE_META_KEYS
+
+    def test_a_list_is_one_call_and_the_shape_error(self, unit, zero):
+        llm = ScriptedLLM(reply("[]"))
+        findings, meta = unit.review(llm, **zero)
+        assert len(llm.calls) == 1
+        assert meta["error"] == LIST_ERROR
+
+    def test_the_trace_is_four_files_with_eight_meta_keys(self, unit, zero, tmp_path):
+        llm = ScriptedLLM(reply(GARBAGE))
+        _traced(unit, llm, tmp_path, **zero)
+        assert _files(tmp_path) == _base_files(unit.trace_label)
+        traced = _response(tmp_path, f"{unit.trace_label}.meta.json")
+        assert list(traced) == BASE_META_JSON_KEYS
+
+    def test_the_empty_retry_keeps_its_one_call_log_and_writes_no_attempt(self, unit, zero, tmp_path, caplog):
+        llm = ScriptedLLM(
+            reply("", input_tokens=100, output_tokens=7),
+            reply(VALID, input_tokens=30, output_tokens=50),
+        )
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            findings, meta = _traced(unit, llm, tmp_path, **zero)
+        assert len(llm.calls) == 2
+        assert len(findings) == 1
+        assert list(meta) == BASE_META_KEYS
+        assert meta["input_tokens"] == 130
+        assert _files(tmp_path) == _base_files(unit.trace_label)
+        assert list(_response(tmp_path, f"{unit.trace_label}.meta.json")) == BASE_META_JSON_KEYS
+        assert _warnings(caplog) == [
+            f"{unit.log_label}: empty model reply (finish_reason=stop); retrying once",
+        ]
+
+    def test_empty_twice_is_still_two_calls_and_the_empty_error(self, unit, zero):
+        llm = ScriptedLLM(reply(""), reply(""))
+        findings, meta = unit.review(llm, **zero)
+        assert len(llm.calls) == 2
+        assert meta["error"] == EMPTY_ERROR
+        assert list(meta) == BASE_META_KEYS
+
+    def test_an_empty_reply_then_an_object_without_findings_is_clean(self, unit, zero):
+        llm = ScriptedLLM(reply(""), reply("{}"))
+        findings, meta = unit.review(llm, **zero)
+        assert len(llm.calls) == 2
+        assert findings == []
+        assert meta["error"] == ""
+
+
+class TestStaleAttemptFiles:
+    def test_a_later_write_of_the_same_label_removes_attempts_it_did_not_make(self, unit, tmp_path):
+        label = unit.trace_label
+        _traced(unit, ScriptedLLM(reply(GARBAGE), reply("{}"), reply(VALID)), tmp_path, parse_retries=2)
+        assert f"{label}.attempt2.response.json" in _files(tmp_path)
+        _traced(unit, ScriptedLLM(reply(VALID)), tmp_path, parse_retries=2)
+        assert _files(tmp_path) == _base_files(label)
+        assert "parse_retries" not in _response(tmp_path, f"{label}.meta.json")
+
+    def test_only_the_attempts_beyond_the_new_count_are_removed(self, unit, tmp_path):
+        label = unit.trace_label
+        _traced(unit, ScriptedLLM(reply(GARBAGE), reply("{}"), reply(VALID)), tmp_path, parse_retries=2)
+        _traced(unit, ScriptedLLM(reply(CUT_OFF), reply(VALID)), tmp_path, parse_retries=2)
+        assert _files(tmp_path) == sorted(_base_files(label) + [f"{label}.attempt1.response.json"])
+        assert _response(tmp_path, f"{label}.attempt1.response.json") == CUT_OFF
+
+
+class TestWriteTraceFilesKeepsItsSignature:
+    def test_the_positional_call_writes_four_files_and_eight_meta_keys(self, tmp_path):
+        meta = {"model": "m", "input_tokens": 1, "output_tokens": 2, "elapsed_ms": 3, "error": ""}
+        _write_trace_files(str(tmp_path), "judge", "sys", "usr", "raw", meta)
+        assert _files(tmp_path) == _base_files("judge")
+        assert list(_response(tmp_path, "judge.meta.json")) == BASE_META_JSON_KEYS
+
+    def test_retry_keys_in_meta_and_attempts_are_written(self, tmp_path):
+        meta = {"model": "m", "error": "", "parse_retries": 2, "first_error": "boom"}
+        _write_trace_files(str(tmp_path), "judge", "sys", "usr", "raw", meta, attempts=["a", None])
+        assert _files(tmp_path) == sorted(_base_files("judge") + [
+            "judge.attempt1.response.json", "judge.attempt2.response.json",
+        ])
+        traced = _response(tmp_path, "judge.meta.json")
+        assert list(traced) == BASE_META_JSON_KEYS + RETRY_KEYS
+        assert traced["parse_retries"] == 2 and traced["first_error"] == "boom"
+        assert _response(tmp_path, "judge.attempt1.response.json") == "a"
+        assert _response(tmp_path, "judge.attempt2.response.json") is None
+
+    def test_an_empty_trace_dir_still_writes_nothing(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        _write_trace_files("", "judge", "sys", "usr", "raw", {}, attempts=["a"])
+        assert _files(tmp_path) == []

From 6186ece8b2fbdaee9750383bd47f9dd7a704ea4f Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:09:59 -0700
Subject: [PATCH 04/25] feat: parse Gradle build files and the version catalog
 for JVM dependency context (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add prxref/jvm_gradle.py, a stdlib leaf module (it imports nothing from
prxref) that reduces a build.gradle or build.gradle.kts, plus its version
catalog, to declared coordinates for the JVM dependency-version block.

- String notation "g:a:v" and "g:a" in either quote style, anywhere outside a
  comment, so every configuration call and calls wrapped across lines count.
  Comments are stripped by a string-aware scan, so a commented-out
  declaration never becomes a pin and a glob such as '**/*.java' never opens
  one. A classifier or @ext is dropped; an interpolated version stays literal.
- platform(), enforcedPlatform() and mavenBom are BOM owners, as a string or
  as a catalog accessor (platform(libs.spring.boot.bom)).
- group = "g" / group "g" on its own line sets the own group; exclude
  group: and exclude(group = ...) never do.
- gradle/libs.versions.toml (or libs.versions.toml beside the build file) via
  tomllib: [versions], and [libraries] in string, module and group/name form,
  with a string, rich, version.ref or { ref = } version. Every catalog
  library counts as declared. The catalog is probed only when the build file
  mentions libs. outside a comment: its own directory, then the root; the
  first non-empty read wins.
- All reads go through an injected read(path); broken TOML, an unparseable
  file or a raising read contributes nothing and never raises. Map notation
  is out of scope.

Tests: tests/test_jvm_gradle.py (39).

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/jvm_gradle.py | 298 +++++++++++++++++++++++
 tests/test_jvm_gradle.py | 502 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 800 insertions(+)
 create mode 100644 src/prxref/jvm_gradle.py
 create mode 100644 tests/test_jvm_gradle.py

diff --git a/src/prxref/jvm_gradle.py b/src/prxref/jvm_gradle.py
new file mode 100644
index 0000000..e089552
--- /dev/null
+++ b/src/prxref/jvm_gradle.py
@@ -0,0 +1,298 @@
+"""Gradle build files and the version catalog, reduced to declared dependencies (#20).
+
+A leaf module for the JVM dependency-version context: it imports nothing from
+prxref and performs no I/O of its own. Every read goes through an injected
+``read(path) -> str | None`` callable resolving a repository-relative path, the
+same contract :mod:`prxref.chunk_context` uses, so the caller owns caching and
+the forge.
+
+What is read:
+
+- ``build.gradle`` and ``build.gradle.kts`` string notation, ``"g:a:v"`` or
+  ``"g:a"`` in either quote style, wherever it appears outside a comment. That
+  covers every configuration call (``implementation(...)``, ``api "..."``,
+  ``testImplementation``, ``classpath`` and so on) and calls wrapped across
+  lines. A classifier (``"g:a:v:jdk8"``) or an extension (``"g:a:v@aar"``) is
+  dropped; an interpolated version (``"g:a:$ver"``) is kept literally.
+- ``platform(...)``, ``enforcedPlatform(...)`` and the dependency-management
+  plugin's ``mavenBom`` as BOM owners, either as a string or as a catalog
+  accessor (``platform(libs.spring.boot.bom)``).
+- ``group = "g"`` or ``group "g"`` on a line of its own: the project's own group.
+- The version catalog (``gradle/libs.versions.toml``, or ``libs.versions.toml``
+  beside the build file), probed only when the build file mentions ``libs.``.
+  ``[libraries]`` in string, ``module`` and ``group``/``name`` form, with a
+  version given as a string, ``version.ref`` or ``{ ref = ... }`` into
+  ``[versions]``. Every catalog library counts as declared.
+
+Not read: map notation (``group: 'g', name: 'a'``), catalogs under another name
+or location (``versionCatalogs { create(...) }``), versions set through
+variables or ``gradle.properties``, and ``[bundles]`` / ``[plugins]``.
+
+Nothing here raises: an unparseable build file or broken TOML contributes
+nothing.
+"""
+from __future__ import annotations
+
+import re
+import tomllib
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+BUILD_FILE_NAMES = ("build.gradle.kts", "build.gradle")
+CATALOG_FILE_NAME = "libs.versions.toml"
+
+_COORDINATE = (
+    r"(?P<group>[A-Za-z0-9_][A-Za-z0-9_.\-]*)"
+    r":(?P<artifact>[A-Za-z0-9_][A-Za-z0-9_.\-]*)"
+    r"(?::(?P<version>[^'\"\s:@]+))?"
+    r"(?::[^'\"\s:@]+)?"
+    r"(?:@[A-Za-z0-9_]+)?"
+)
+_COORDINATE_RE = re.compile(_COORDINATE)
+_DECLARATION_RE = re.compile(
+    r"(?:(?<![A-Za-z0-9_$.])(?P<bom>platform|enforcedPlatform|mavenBom)\s*(?:\(\s*|[ \t]+))?"
+    r"(?P<quote>['\"])" + _COORDINATE + r"(?P=quote)"
+)
+_PLATFORM_ACCESSOR_RE = re.compile(
+    r"(?<![A-Za-z0-9_$.])(?:platform|enforcedPlatform)\s*\(\s*libs\.(?P<accessor>[A-Za-z0-9_.]+)\s*\)"
+)
+_CATALOG_MENTION_RE = re.compile(r"(?<![A-Za-z0-9_$.])libs\.")
+_GROUP_RE = re.compile(
+    r"^[ \t]*(?:project\.)?group[ \t]*(?:=[ \t]*|[ \t]+)"
+    r"(?P<quote>['\"])(?P<group>[A-Za-z0-9_][A-Za-z0-9_.\-]*)(?P=quote)[ \t]*;?[ \t]*$",
+    re.M,
+)
+_LEXEME_RE = re.compile(
+    r"\"(?:\\.|[^\"\\\n])*\"|'(?:\\.|[^'\\\n])*'|//[^\n]*|/\*.*?(?:\*/|\Z)",
+    re.S,
+)
+_ALIAS_SEPARATOR_RE = re.compile(r"[-_]")
+_RICH_VERSION_KEYS = ("strictly", "require", "prefer")
+
+
+@dataclass(frozen=True)
+class GradleDependency:
+    """One declared coordinate: ``group:artifact`` and its version.
+
+    ``version`` is ``None`` when the declaration names none, for example
+    ``"com.fasterxml.jackson.core:jackson-databind"`` under a platform BOM, or a
+    catalog ``version.ref`` naming a missing ``[versions]`` key.
+    """
+
+    group: str
+    artifact: str
+    version: str | None = None
+
+
+@dataclass(frozen=True)
+class GradleBuild:
+    """What one Gradle build file, plus its catalog, declares.
+
+    ``group`` is the project's own group, or ``None`` when the file sets none.
+    ``dependencies`` holds ordinary declarations and every catalog library that
+    is not used as a platform; ``boms`` holds the ``platform``,
+    ``enforcedPlatform`` and ``mavenBom`` owners. Both are deduplicated and
+    keep declaration order, build file first. Which BOM manages a versionless
+    dependency is left to the caller. ``catalog_path`` names the catalog that
+    was read, or is ``None`` when none was probed or found.
+    """
+
+    group: str | None = None
+    dependencies: tuple[GradleDependency, ...] = ()
+    boms: tuple[GradleDependency, ...] = ()
+    catalog_path: str | None = None
+
+
+@dataclass(frozen=True)
+class _Scan:
+    group: str | None
+    dependencies: tuple[GradleDependency, ...]
+    boms: tuple[GradleDependency, ...]
+    platform_accessors: frozenset[str]
+    mentions_catalog: bool
+
+
+def _strip_comment(match: re.Match[str]) -> str:
+    token = match.group(0)
+    if token.startswith("/"):
+        return "\n" * token.count("\n")
+    return token
+
+
+def _unique(items: Iterable[GradleDependency]) -> tuple[GradleDependency, ...]:
+    return tuple(dict.fromkeys(items))
+
+
+def _scan(text: str) -> _Scan:
+    if not isinstance(text, str):
+        return _Scan(None, (), (), frozenset(), False)
+    code = _LEXEME_RE.sub(_strip_comment, text.replace("\r\n", "\n"))
+    dependencies: list[GradleDependency] = []
+    boms: list[GradleDependency] = []
+    for match in _DECLARATION_RE.finditer(code):
+        dependency = GradleDependency(match["group"], match["artifact"], match["version"])
+        (boms if match["bom"] else dependencies).append(dependency)
+    group_match = _GROUP_RE.search(code)
+    return _Scan(
+        group=group_match["group"] if group_match else None,
+        dependencies=_unique(dependencies),
+        boms=_unique(boms),
+        platform_accessors=frozenset(m["accessor"] for m in _PLATFORM_ACCESSOR_RE.finditer(code)),
+        mentions_catalog=_CATALOG_MENTION_RE.search(code) is not None,
+    )
+
+
+def _assemble(scan: _Scan, catalog: dict[str, GradleDependency], catalog_path: str | None) -> GradleBuild:
+    dependencies = list(scan.dependencies)
+    boms = list(scan.boms)
+    for alias, dependency in catalog.items():
+        accessor = _ALIAS_SEPARATOR_RE.sub(".", alias)
+        (boms if accessor in scan.platform_accessors else dependencies).append(dependency)
+    return GradleBuild(
+        group=scan.group,
+        dependencies=_unique(dependencies),
+        boms=_unique(boms),
+        catalog_path=catalog_path,
+    )
+
+
+def parse_build_file(text: str) -> GradleBuild:
+    """Parse one ``build.gradle`` or ``build.gradle.kts`` text, without the catalog.
+
+    Pure and total: a platform given as a catalog accessor stays unresolved,
+    and text that cannot be parsed yields an empty :class:`GradleBuild`.
+    """
+    try:
+        return _assemble(_scan(text), {}, None)
+    except Exception:  # noqa: BLE001 - a broken build file is not a review failure
+        return GradleBuild()
+
+
+def _rich_version(value: object) -> str | None:
+    if isinstance(value, str):
+        return value.strip() or None
+    if isinstance(value, dict):
+        for key in _RICH_VERSION_KEYS:
+            candidate = value.get(key)
+            if isinstance(candidate, str) and candidate.strip():
+                return candidate.strip()
+    return None
+
+
+def _catalog_version(value: object, versions: dict) -> str | None:
+    if isinstance(value, dict) and "ref" in value:
+        ref = value["ref"]
+        return _rich_version(versions.get(ref)) if isinstance(ref, str) else None
+    return _rich_version(value)
+
+
+def _catalog_library(spec: object, versions: dict) -> GradleDependency | None:
+    if isinstance(spec, str):
+        match = _COORDINATE_RE.fullmatch(spec.strip())
+        if not match:
+            return None
+        return GradleDependency(match["group"], match["artifact"], match["version"])
+    if not isinstance(spec, dict):
+        return None
+    module = spec.get("module")
+    if isinstance(module, str):
+        group, _, artifact = module.strip().partition(":")
+        if not group or not artifact or ":" in artifact:
+            return None
+    elif isinstance(spec.get("group"), str) and isinstance(spec.get("name"), str):
+        group, artifact = spec["group"].strip(), spec["name"].strip()
+        if not group or not artifact:
+            return None
+    else:
+        return None
+    return GradleDependency(group, artifact, _catalog_version(spec.get("version"), versions))
+
+
+def parse_catalog(text: str) -> dict[str, GradleDependency]:
+    """Map each ``[libraries]`` alias of a version catalog to its coordinate.
+
+    Accepts the string form ``"g:a:v"``, ``{ module = "g:a", ... }`` and
+    ``{ group = "g", name = "a", ... }``. A version is a string, a rich version
+    (``strictly``, then ``require``, then ``prefer``), or a ``version.ref`` /
+    ``{ ref = ... }`` into ``[versions]``; a ref to a missing key gives
+    ``None``. Entries keep catalog order. Broken TOML, or a catalog of the
+    wrong shape, yields ``{}``.
+    """
+    try:
+        data = tomllib.loads(text)
+        versions = data.get("versions")
+        if not isinstance(versions, dict):
+            versions = {}
+        libraries = data.get("libraries")
+        if not isinstance(libraries, dict):
+            return {}
+        out: dict[str, GradleDependency] = {}
+        for alias, spec in libraries.items():
+            dependency = _catalog_library(spec, versions)
+            if dependency is not None:
+                out[alias] = dependency
+        return out
+    except Exception:  # noqa: BLE001 - a broken catalog is not a review failure
+        return {}
+
+
+def _join(directory: str, name: str) -> str:
+    return f"{directory}/{name}" if directory else name
+
+
+def catalog_paths(build_path: str, root: str = "") -> tuple[str, ...]:
+    """The catalog paths probed for ``build_path``, in probe order.
+
+    First the build file's own directory (``gradle/libs.versions.toml``, then
+    ``libs.versions.toml``), then ``gradle/libs.versions.toml`` under ``root``.
+    ``root`` is a repository-relative directory; the default ``""`` is the
+    repository root, and a caller that knows where ``settings.gradle(.kts)``
+    lives may pass that directory instead. Duplicates are dropped, so a build
+    file at the root yields two paths.
+    """
+    directory = build_path.rsplit("/", 1)[0] if "/" in build_path else ""
+    base = root.strip("/")
+    candidates = (
+        _join(directory, f"gradle/{CATALOG_FILE_NAME}"),
+        _join(directory, CATALOG_FILE_NAME),
+        _join(base, f"gradle/{CATALOG_FILE_NAME}"),
+    )
+    return tuple(dict.fromkeys(candidates))
+
+
+def _safe_read(read: Callable[[str], str | None], path: str) -> str | None:
+    try:
+        text = read(path)
+    except Exception:  # noqa: BLE001 - a failed read is a read that returned None
+        return None
+    return text if isinstance(text, str) and text else None
+
+
+def gradle_build(
+    path: str,
+    text: str,
+    read: Callable[[str], str | None],
+    root: str = "",
+) -> GradleBuild:
+    """Parse the build file ``text`` found at ``path``, merging its version catalog.
+
+    The catalog is probed through ``read`` only when ``text`` mentions
+    ``libs.`` outside a comment, at :func:`catalog_paths` ``(path, root)`` in
+    order; the first path that reads non-empty is the catalog, even if its TOML
+    turns out to be broken. The build file itself is never read here: the
+    caller already holds ``text``. Never raises; a failure contributes nothing.
+    """
+    try:
+        scan = _scan(text)
+        catalog: dict[str, GradleDependency] = {}
+        found: str | None = None
+        if scan.mentions_catalog:
+            for candidate in catalog_paths(path, root):
+                content = _safe_read(read, candidate)
+                if content is not None:
+                    found = candidate
+                    catalog = parse_catalog(content)
+                    break
+        return _assemble(scan, catalog, found)
+    except Exception:  # noqa: BLE001 - a broken build file is not a review failure
+        return GradleBuild()
diff --git a/tests/test_jvm_gradle.py b/tests/test_jvm_gradle.py
new file mode 100644
index 0000000..e623076
--- /dev/null
+++ b/tests/test_jvm_gradle.py
@@ -0,0 +1,502 @@
+"""Unit tests for :mod:`prxref.jvm_gradle`, the Gradle half of #20's dependency versions.
+
+The module is pure: every test hands it text, or a ``read`` callable over a
+dict, so these pin the build-file scan, the platform owners, the own group, the
+three catalog forms and the catalog probe without a forge or a filesystem.
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import prxref.jvm_gradle as jvm_gradle
+from prxref.jvm_gradle import (
+    BUILD_FILE_NAMES,
+    GradleBuild,
+    GradleDependency,
+    catalog_paths,
+    gradle_build,
+    parse_build_file,
+    parse_catalog,
+)
+
+JACKSON = "com.fasterxml.jackson.core"
+BOOT_BOM = GradleDependency("org.springframework.boot", "spring-boot-dependencies", "3.3.4")
+
+
+def counting_reader(files: dict[str, str]):
+    calls: list[str] = []
+
+    def _read(path: str) -> str | None:
+        calls.append(path)
+        return files.get(path)
+
+    return _read, calls
+
+
+GROOVY_BUILD = """\
+plugins {
+    id 'java'
+}
+
+dependencies {
+    implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.0'
+    api "org.slf4j:slf4j-api:2.0.13"
+    testImplementation 'org.junit.jupiter:junit-jupiter'
+    compileOnly("com.example:annotations:1.0")
+}
+"""
+
+KOTLIN_BUILD = """\
+plugins {
+    kotlin("jvm") version "2.0.0"
+}
+
+dependencies {
+    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.0")
+    implementation(
+        "com.acme:billing-client:3.1.4"
+    )
+    testImplementation('org.junit.jupiter:junit-jupiter:5.10.2')
+    runtimeOnly("com.example:driver")
+}
+"""
+
+CATALOG = """\
+[versions]
+jackson = "2.17.0"
+boot = { strictly = "3.3.4" }
+
+[libraries]
+jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
+jackson-core = { group = "com.fasterxml.jackson.core", name = "jackson-core", version = { ref = "jackson" } }
+jackson-annotations = { group = "com.fasterxml.jackson.core", name = "jackson-annotations", version.ref = "jackson" }
+acme-client = "com.acme:client:1.4.2"
+acme-model = { module = "com.acme:model", version = "0.9.1" }
+acme-bare = { module = "com.acme:bare" }
+slf4j-api = { group = "org.slf4j", name = "slf4j-api", version = "2.0.13" }
+spring-boot-bom = { module = "org.springframework.boot:spring-boot-dependencies", version.ref = "boot" }
+
+[bundles]
+jackson = ["jackson-databind", "jackson-core"]
+
+[plugins]
+boot = { id = "org.springframework.boot", version.ref = "boot" }
+"""
+
+
+class TestBuildFileStrings:
+    def test_groovy_build_reads_both_quote_styles(self):
+        build = parse_build_file(GROOVY_BUILD)
+        assert build.dependencies == (
+            GradleDependency(JACKSON, "jackson-databind", "2.17.0"),
+            GradleDependency("org.slf4j", "slf4j-api", "2.0.13"),
+            GradleDependency("org.junit.jupiter", "junit-jupiter", None),
+            GradleDependency("com.example", "annotations", "1.0"),
+        )
+        assert build.boms == ()
+
+    def test_kotlin_build_reads_both_quote_styles_and_wrapped_calls(self):
+        build = parse_build_file(KOTLIN_BUILD)
+        assert build.dependencies == (
+            GradleDependency(JACKSON, "jackson-databind", "2.17.0"),
+            GradleDependency("com.acme", "billing-client", "3.1.4"),
+            GradleDependency("org.junit.jupiter", "junit-jupiter", "5.10.2"),
+            GradleDependency("com.example", "driver", None),
+        )
+
+    def test_gradle_build_reads_the_same_as_parse_build_file_for_both_dialects(self):
+        read, calls = counting_reader({})
+        assert gradle_build("build.gradle", GROOVY_BUILD, read) == parse_build_file(GROOVY_BUILD)
+        assert gradle_build("app/build.gradle.kts", KOTLIN_BUILD, read) == parse_build_file(KOTLIN_BUILD)
+        assert calls == []
+
+    def test_classifier_extension_and_interpolated_versions(self):
+        text = """\
+dependencies {
+    implementation "com.acme:native:1.2:linux-x86_64"
+    implementation 'com.acme:widget:4.0@aar'
+    implementation "com.acme:core:$coreVersion"
+    implementation("com.acme:util:${versions.util}")
+}
+"""
+        assert parse_build_file(text).dependencies == (
+            GradleDependency("com.acme", "native", "1.2"),
+            GradleDependency("com.acme", "widget", "4.0"),
+            GradleDependency("com.acme", "core", "$coreVersion"),
+            GradleDependency("com.acme", "util", "${versions.util}"),
+        )
+
+    def test_projects_urls_plugin_ids_and_class_names_are_not_coordinates(self):
+        text = """\
+plugins {
+    id("org.springframework.boot") version "3.3.4"
+}
+repositories {
+    maven { url = uri("https://repo.example.com/maven") }
+    maven { url 'https://repo.example.com/other' }
+}
+dependencies {
+    implementation(project(":core"))
+    implementation project(':lib:model')
+}
+application {
+    mainClass.set("com.acme.Main")
+}
+"""
+        assert parse_build_file(text).dependencies == ()
+
+    def test_commented_out_declarations_are_ignored(self):
+        text = """\
+sourceSets {
+    main { java { include '**/*.java' } }
+}
+dependencies {
+    // implementation "com.acme:old:1.0"
+    /* api 'com.acme:gone:2.0' */
+    /*
+     * testImplementation("com.acme:also-gone:3.0")
+     */
+    implementation "com.acme:kept:1.0" // pinned for #20
+}
+tasks.test {
+    exclude '**/Slow*'
+}
+"""
+        assert parse_build_file(text).dependencies == (GradleDependency("com.acme", "kept", "1.0"),)
+
+    def test_several_coordinates_in_one_call_and_duplicates_collapse_in_order(self):
+        text = """\
+dependencies {
+    implementation "com.acme:a:1", "com.acme:b:2"
+    testImplementation "com.acme:a:1"
+    add("implementation", "com.acme:c:3")
+}
+"""
+        assert parse_build_file(text).dependencies == (
+            GradleDependency("com.acme", "a", "1"),
+            GradleDependency("com.acme", "b", "2"),
+            GradleDependency("com.acme", "c", "3"),
+        )
+
+    def test_map_notation_is_out_of_scope(self):
+        text = """\
+dependencies {
+    implementation group: 'com.acme', name: 'legacy', version: '1.0'
+    implementation(
+        group: 'com.acme',
+        name: 'wrapped',
+    )
+}
+"""
+        build = parse_build_file(text)
+        assert build.dependencies == ()
+        assert build.group is None
+
+    def test_crlf_line_endings(self):
+        text = "group = 'com.acme'\r\ndependencies {\r\n    api 'org.slf4j:slf4j-api:2.0.13'\r\n}\r\n"
+        build = parse_build_file(text)
+        assert build.group == "com.acme"
+        assert build.dependencies == (GradleDependency("org.slf4j", "slf4j-api", "2.0.13"),)
+
+
+class TestPlatforms:
+    def test_platform_and_enforced_platform_are_bom_owners_in_kotlin(self):
+        text = """\
+dependencies {
+    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.3.4"))
+    implementation(enforcedPlatform("com.fasterxml.jackson:jackson-bom:2.17.0"))
+    implementation("com.fasterxml.jackson.core:jackson-databind")
+}
+"""
+        build = parse_build_file(text)
+        assert build.boms == (
+            BOOT_BOM,
+            GradleDependency("com.fasterxml.jackson", "jackson-bom", "2.17.0"),
+        )
+        assert build.dependencies == (GradleDependency(JACKSON, "jackson-databind", None),)
+
+    def test_platform_and_enforced_platform_are_bom_owners_in_groovy(self):
+        text = """\
+dependencies {
+    implementation platform('org.springframework.boot:spring-boot-dependencies:3.3.4')
+    testImplementation enforcedPlatform ("org.junit:junit-bom:5.10.2")
+    implementation 'com.fasterxml.jackson.core:jackson-databind'
+}
+"""
+        build = parse_build_file(text)
+        assert build.boms == (BOOT_BOM, GradleDependency("org.junit", "junit-bom", "5.10.2"))
+        assert build.dependencies == (GradleDependency(JACKSON, "jackson-databind", None),)
+
+    def test_dependency_management_plugin_maven_bom_is_a_bom_owner(self):
+        text = """\
+dependencyManagement {
+    imports {
+        mavenBom "org.springframework.boot:spring-boot-dependencies:3.3.4"
+    }
+}
+"""
+        build = parse_build_file(text)
+        assert build.boms == (BOOT_BOM,)
+        assert build.dependencies == ()
+
+    def test_platform_catalog_accessor_turns_the_catalog_library_into_a_bom(self):
+        text = """\
+dependencies {
+    implementation(platform(libs.spring.boot.bom))
+    implementation(libs.jackson.databind)
+}
+"""
+        read, _ = counting_reader({"gradle/libs.versions.toml": CATALOG})
+        build = gradle_build("build.gradle.kts", text, read)
+        assert build.boms == (BOOT_BOM,)
+        assert BOOT_BOM not in build.dependencies
+        assert GradleDependency(JACKSON, "jackson-databind", "2.17.0") in build.dependencies
+
+    def test_platform_catalog_accessor_without_a_catalog_names_nothing(self):
+        build = parse_build_file("dependencies { implementation(platform(libs.spring.boot.bom)) }\n")
+        assert build.boms == ()
+        assert build.dependencies == ()
+
+
+class TestOwnGroup:
+    def test_assignment_and_command_forms_in_either_quote_style(self):
+        assert parse_build_file('group = "com.acme"\n').group == "com.acme"
+        assert parse_build_file("group = 'com.acme'\n").group == "com.acme"
+        assert parse_build_file("group 'com.acme'\n").group == "com.acme"
+        assert parse_build_file('group "com.acme";\n').group == "com.acme"
+        assert parse_build_file('    project.group = "com.acme.billing"  // own\n').group == "com.acme.billing"
+
+    def test_first_group_wins_and_the_group_is_not_a_dependency(self):
+        text = """\
+allprojects {
+    group = "com.acme"
+}
+subprojects {
+    group = "com.example"
+}
+"""
+        build = parse_build_file(text)
+        assert build.group == "com.acme"
+        assert build.dependencies == ()
+
+    def test_exclusions_interpolation_and_comments_never_set_the_group(self):
+        text = """\
+// group = "com.commented"
+group = "$rootGroup"
+dependencies {
+    implementation('com.acme:web:1.0') {
+        exclude group: 'org.slf4j', module: 'slf4j-simple'
+    }
+    implementation("com.acme:api:1.0") {
+        exclude(group = "org.slf4j", module = "slf4j-simple")
+        exclude(
+            group = "commons-logging",
+            module = "commons-logging"
+        )
+    }
+}
+"""
+        build = parse_build_file(text)
+        assert build.group is None
+        assert build.dependencies == (
+            GradleDependency("com.acme", "web", "1.0"),
+            GradleDependency("com.acme", "api", "1.0"),
+        )
+
+    def test_no_group_is_none(self):
+        assert parse_build_file(KOTLIN_BUILD).group is None
+
+
+class TestCatalog:
+    def test_version_ref_resolves_through_versions(self):
+        libraries = parse_catalog(CATALOG)
+        assert libraries["jackson-databind"] == GradleDependency(JACKSON, "jackson-databind", "2.17.0")
+        assert libraries["jackson-annotations"] == GradleDependency(JACKSON, "jackson-annotations", "2.17.0")
+
+    def test_ref_table_form_resolves_the_same_as_version_ref(self):
+        assert parse_catalog(CATALOG)["jackson-core"] == GradleDependency(JACKSON, "jackson-core", "2.17.0")
+
+    def test_the_three_library_forms(self):
+        libraries = parse_catalog(CATALOG)
+        assert libraries["acme-client"] == GradleDependency("com.acme", "client", "1.4.2")
+        assert libraries["acme-model"] == GradleDependency("com.acme", "model", "0.9.1")
+        assert libraries["slf4j-api"] == GradleDependency("org.slf4j", "slf4j-api", "2.0.13")
+
+    def test_a_rich_version_behind_a_ref_resolves(self):
+        assert parse_catalog(CATALOG)["spring-boot-bom"] == BOOT_BOM
+
+    def test_every_library_is_listed_in_catalog_order_and_bundles_and_plugins_are_ignored(self):
+        assert list(parse_catalog(CATALOG)) == [
+            "jackson-databind", "jackson-core", "jackson-annotations", "acme-client",
+            "acme-model", "acme-bare", "slf4j-api", "spring-boot-bom",
+        ]
+
+    def test_missing_and_dangling_versions_are_none(self):
+        text = """\
+[libraries]
+bare = { module = "com.acme:bare" }
+dangling = { module = "com.acme:dangling", version.ref = "missing" }
+string-bare = "com.acme:string-bare"
+"""
+        assert parse_catalog(text) == {
+            "bare": GradleDependency("com.acme", "bare", None),
+            "dangling": GradleDependency("com.acme", "dangling", None),
+            "string-bare": GradleDependency("com.acme", "string-bare", None),
+        }
+
+    def test_rich_versions_take_strictly_then_require_then_prefer(self):
+        text = """\
+[libraries]
+strict = { module = "com.acme:strict", version = { strictly = "1.0", prefer = "1.1" } }
+required = { module = "com.acme:required", version = { require = "2.0", prefer = "2.1" } }
+preferred = { module = "com.acme:preferred", version = { prefer = "3.1" } }
+"""
+        libraries = parse_catalog(text)
+        assert libraries["strict"].version == "1.0"
+        assert libraries["required"].version == "2.0"
+        assert libraries["preferred"].version == "3.1"
+
+    def test_malformed_entries_are_skipped(self):
+        text = """\
+[libraries]
+number = 42
+no-colon = "com.acme.client"
+name-only = { name = "client", version = "1.0" }
+bad-module = { module = "com.acme", version = "1.0" }
+too-many = { module = "com.acme:a:b", version = "1.0" }
+good = "com.acme:good:1.0"
+"""
+        assert parse_catalog(text) == {"good": GradleDependency("com.acme", "good", "1.0")}
+
+    def test_broken_toml_contributes_nothing(self):
+        assert parse_catalog("[libraries\njackson = { module = ") == {}
+        assert parse_catalog('libraries = "not a table"\n') == {}
+        assert parse_catalog("") == {}
+
+
+class TestCatalogProbe:
+    def test_no_catalog_read_without_a_libs_mention(self):
+        read, calls = counting_reader({"gradle/libs.versions.toml": CATALOG})
+        build = gradle_build("build.gradle", GROOVY_BUILD, read)
+        assert calls == []
+        assert build.catalog_path is None
+        assert build == parse_build_file(GROOVY_BUILD)
+
+    def test_a_libs_mention_inside_a_comment_does_not_probe(self):
+        read, calls = counting_reader({"gradle/libs.versions.toml": CATALOG})
+        text = 'dependencies {\n    // implementation(libs.jackson.databind)\n    api("com.acme:a:1")\n}\n'
+        build = gradle_build("build.gradle.kts", text, read)
+        assert calls == []
+        assert build.dependencies == (GradleDependency("com.acme", "a", "1"),)
+
+    def test_probe_order_is_own_directory_then_root(self):
+        read, calls = counting_reader({})
+        build = gradle_build("services/api/build.gradle.kts", "dependencies { implementation(libs.acme.client) }", read)
+        assert calls == [
+            "services/api/gradle/libs.versions.toml",
+            "services/api/libs.versions.toml",
+            "gradle/libs.versions.toml",
+        ]
+        assert build == GradleBuild()
+
+    def test_first_hit_wins(self):
+        own = '[libraries]\nown = "com.acme:own:1.0"\n'
+        read, calls = counting_reader({
+            "services/api/libs.versions.toml": own,
+            "gradle/libs.versions.toml": CATALOG,
+        })
+        build = gradle_build("services/api/build.gradle", "dependencies { implementation libs.own }", read)
+        assert calls == ["services/api/gradle/libs.versions.toml", "services/api/libs.versions.toml"]
+        assert build.catalog_path == "services/api/libs.versions.toml"
+        assert build.dependencies == (GradleDependency("com.acme", "own", "1.0"),)
+
+    def test_root_catalog_resolves_the_jackson_import_through_version_ref(self):
+        text = """\
+group = "com.acme"
+
+dependencies {
+    implementation(libs.jackson.databind)
+    implementation("org.slf4j:slf4j-api:2.0.13")
+}
+"""
+        read, calls = counting_reader({"gradle/libs.versions.toml": CATALOG})
+        build = gradle_build("orders/build.gradle.kts", text, read)
+        assert calls[-1] == "gradle/libs.versions.toml"
+        assert build.catalog_path == "gradle/libs.versions.toml"
+        assert build.group == "com.acme"
+        assert GradleDependency(JACKSON, "jackson-databind", "2.17.0") in build.dependencies
+
+    def test_every_catalog_library_counts_as_declared(self):
+        read, _ = counting_reader({"gradle/libs.versions.toml": CATALOG})
+        text = "dependencies {\n    implementation(libs.jackson.databind)\n    api 'com.example:extra:1.0'\n}\n"
+        build = gradle_build("build.gradle.kts", text, read)
+        assert build.dependencies == (
+            GradleDependency("com.example", "extra", "1.0"),
+            GradleDependency(JACKSON, "jackson-databind", "2.17.0"),
+            GradleDependency(JACKSON, "jackson-core", "2.17.0"),
+            GradleDependency(JACKSON, "jackson-annotations", "2.17.0"),
+            GradleDependency("com.acme", "client", "1.4.2"),
+            GradleDependency("com.acme", "model", "0.9.1"),
+            GradleDependency("com.acme", "bare", None),
+            GradleDependency("org.slf4j", "slf4j-api", "2.0.13"),
+            BOOT_BOM,
+        )
+        assert build.boms == ()
+
+    def test_broken_catalog_contributes_nothing_and_stops_the_probe(self):
+        read, calls = counting_reader({
+            "gradle/libs.versions.toml": "[libraries\nbroken = {",
+            "libs.versions.toml": CATALOG,
+        })
+        text = "dependencies {\n    implementation(libs.jackson.databind)\n    api('com.acme:kept:1.0')\n}\n"
+        build = gradle_build("build.gradle.kts", text, read)
+        assert calls == ["gradle/libs.versions.toml"]
+        assert build.catalog_path == "gradle/libs.versions.toml"
+        assert build.dependencies == (GradleDependency("com.acme", "kept", "1.0"),)
+
+    def test_a_read_that_raises_is_a_miss(self):
+        calls: list[str] = []
+
+        def read(path: str) -> str | None:
+            calls.append(path)
+            if path.startswith("app/"):
+                raise OSError("forge unavailable")
+            return CATALOG if path == "gradle/libs.versions.toml" else None
+
+        build = gradle_build("app/build.gradle", "dependencies { implementation libs.acme.client }", read)
+        assert calls[-1] == "gradle/libs.versions.toml"
+        assert build.catalog_path == "gradle/libs.versions.toml"
+        assert GradleDependency("com.acme", "client", "1.4.2") in build.dependencies
+
+    def test_catalog_paths_for_a_root_build_and_an_explicit_root(self):
+        assert catalog_paths("build.gradle") == ("gradle/libs.versions.toml", "libs.versions.toml")
+        assert catalog_paths("modules/app/build.gradle.kts", root="modules/") == (
+            "modules/app/gradle/libs.versions.toml",
+            "modules/app/libs.versions.toml",
+            "modules/gradle/libs.versions.toml",
+        )
+
+    def test_non_text_input_contributes_nothing(self):
+        read, calls = counting_reader({})
+        assert gradle_build("build.gradle", None, read) == GradleBuild()
+        assert parse_build_file(None) == GradleBuild()
+        assert parse_catalog(None) == {}
+        assert calls == []
+
+
+class TestModuleShape:
+    def test_build_file_names_put_the_kotlin_dsl_first(self):
+        assert BUILD_FILE_NAMES == ("build.gradle.kts", "build.gradle")
+
+    def test_leaf_module_imports_nothing_from_prxref(self):
+        tree = ast.parse(Path(jvm_gradle.__file__).read_text(encoding="utf-8"))
+        imported: list[str] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom):
+                assert node.level == 0
+                imported.append(node.module or "")
+            elif isinstance(node, ast.Import):
+                imported.extend(alias.name for alias in node.names)
+        assert imported
+        assert not [name for name in imported if name == "prxref" or name.startswith("prxref.")]

From 9a328b496539c688c52c9ed0fdb66eb78b42b8e1 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:10:59 -0700
Subject: [PATCH 05/25] feat: safe pom.xml reader for JVM dependency context
 (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add src/prxref/jvm_maven.py, a stdlib-only leaf module that resolves one
pom.xml and its in-repository parents into groupId:artifactId coordinates
with a version, or with the owner that manages the version.

- Safety: text holding <!DOCTYPE or <!ENTITY (any case) or larger than
  MAX_POM_BYTES (512 KiB of UTF-8, equal to chunk_context.MAX_FILE_BYTES)
  is refused before xml.etree ever parses it. Namespaces are stripped. A
  parse error, a non-<project> root or a failing read contributes nothing,
  and resolve_pom never raises.
- Parents: <relativePath> (default ../pom.xml, a directory gets pom.xml
  appended) resolved against the child's directory; an empty
  <relativePath/>, a path outside the repository, an unreadable or
  mismatched artifactId, MAX_POM_PARENTS = 5 or a revisit stops the walk.
- Properties: ${name} from <properties> merged child-over-parent plus
  project.version, project.groupId and project.parent.version, in at most
  MAX_PROPERTY_PASSES = 5 passes; unresolved placeholders stay literal and
  a pass that would grow a value past MAX_INTERPOLATED_CHARS is abandoned.
- Dependencies and dependencyManagement are both read. A managed
  type=pom scope=import entry is a BOM owner. A versionless dependency
  takes the nearest managed version, else the first owner in Maven's own
  precedence (external parent, then imported BOMs nearest-first); with
  neither it renders no line. Lines are g:a@v or
  g:a@(managed by bg:ba@bv).

All I/O goes through an injected read(path) -> str | None. Covered by
tests/test_jvm_maven.py (50 tests, counting readers for the walk and a
parse spy for the refusals).

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/jvm_maven.py | 413 ++++++++++++++++++++++++++++
 tests/test_jvm_maven.py | 586 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 999 insertions(+)
 create mode 100644 src/prxref/jvm_maven.py
 create mode 100644 tests/test_jvm_maven.py

diff --git a/src/prxref/jvm_maven.py b/src/prxref/jvm_maven.py
new file mode 100644
index 0000000..5f5f211
--- /dev/null
+++ b/src/prxref/jvm_maven.py
@@ -0,0 +1,413 @@
+"""Safe, stdlib-only reading of Maven ``pom.xml`` files for JVM chunk context (#20).
+
+A Java or Kotlin chunk's dependency block needs the version of each declared
+artifact, and in Maven that version is often not in the file that declares the
+dependency: it comes from a ``<properties>`` entry, from a parent pom's
+``<dependencyManagement>``, or from a BOM the build imports. This module
+resolves one pom and its in-repository parents into plain coordinates.
+
+**Safety.** A pom is untrusted input from the pull request. Any text holding a
+``<!DOCTYPE`` or ``<!ENTITY`` declaration (any case) is refused before the XML
+parser ever sees it, so entity expansion, external entities and the
+billion-laughs payload are never evaluated. Text larger than
+:data:`MAX_POM_BYTES` (UTF-8) is refused the same way, and a parse error, a
+root other than ``<project>``, or a failing ``read`` contributes nothing.
+:func:`resolve_pom` never raises.
+
+**Parents.** ``<parent>`` is followed through ``<relativePath>``, which defaults
+to ``../pom.xml`` and resolves against the child pom's directory; a path naming
+a directory gets ``pom.xml`` appended. A parent is accepted only when its
+``<artifactId>`` equals the child's ``<parent><artifactId>``. The walk stops at
+an empty ``<relativePath/>``, a path outside the repository, an unreadable,
+refused or mismatched pom, after :data:`MAX_POM_PARENTS` parents, or on
+revisiting a path. The first parent it does not read (for any reason but a
+revisit) is the *external parent*.
+
+**Properties.** ``${name}`` resolves from ``<properties>`` merged over the whole
+chain (a child overrides its parents), plus ``project.version``,
+``project.groupId`` and ``project.parent.version`` of the resolved pom, in at
+most :data:`MAX_PROPERTY_PASSES` passes. An unresolved placeholder stays
+literal, and a pass that would grow a value past
+:data:`MAX_INTERPOLATED_CHARS` characters is abandoned, keeping the value as
+the previous pass left it.
+
+**Versions and owners.** ``<dependencies>`` and
+``<dependencyManagement><dependencies>`` are read in every pom of the chain,
+the nearest pom winning per ``groupId:artifactId``. A managed entry with
+``<type>pom</type>`` and ``<scope>import</scope>`` is a BOM owner, not a
+dependency. A dependency without a version takes the nearest managed version;
+failing that, its version is inherited from something this module cannot
+read, and its owner is the first candidate in Maven's own precedence order:
+the external parent (inherited management wins over imports), then the
+imported BOMs, nearest pom first and in declaration order. A dependency with
+neither a version nor an owner renders no line.
+
+All I/O goes through a caller-supplied ``read(path) -> str | None`` over
+repository-relative, ``/``-separated paths, so the caller owns fetching and
+caching.
+"""
+from __future__ import annotations
+
+import posixpath
+import re
+import xml.etree.ElementTree as ET
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+MAX_POM_BYTES = 512 * 1024
+MAX_POM_PARENTS = 5
+MAX_PROPERTY_PASSES = 5
+MAX_INTERPOLATED_CHARS = 1024
+
+_UNSAFE_RE = re.compile(r"<!\s*(?:DOCTYPE|ENTITY)", re.IGNORECASE)
+_PLACEHOLDER_RE = re.compile(r"\$\{([^${}]+)\}")
+_DEFAULT_RELATIVE_PATH = "../pom.xml"
+
+Reader = Callable[[str], str | None]
+
+
+@dataclass(frozen=True)
+class MavenCoordinate:
+    """A ``groupId:artifactId`` pair with an optional version, such as a BOM."""
+
+    group_id: str
+    artifact_id: str
+    version: str | None = None
+
+    @property
+    def name(self) -> str:
+        """``groupId:artifactId``."""
+        return f"{self.group_id}:{self.artifact_id}"
+
+    def render(self) -> str:
+        """``g:a@v``, or ``g:a`` when the version is unknown."""
+        return f"{self.name}@{self.version}" if self.version else self.name
+
+
+@dataclass(frozen=True)
+class MavenDependency:
+    """One declared or managed dependency after property resolution.
+
+    ``version`` is ``None`` when no pom in the chain states it; ``managed_by``
+    then names the owner whose management supplies it, or is ``None`` when
+    there is no candidate owner either.
+    """
+
+    group_id: str
+    artifact_id: str
+    version: str | None = None
+    managed_by: MavenCoordinate | None = None
+
+    @property
+    def name(self) -> str:
+        """``groupId:artifactId``."""
+        return f"{self.group_id}:{self.artifact_id}"
+
+    def line(self) -> str | None:
+        """``g:a@v``, ``g:a@(managed by bg:ba@bv)``, or ``None`` for neither."""
+        if self.version:
+            return f"{self.name}@{self.version}"
+        if self.managed_by is not None:
+            return f"{self.name}@(managed by {self.managed_by.render()})"
+        return None
+
+
+@dataclass(frozen=True)
+class MavenProject:
+    """The resolved view of one pom and the in-repository parents it inherits.
+
+    ``group_id``, ``artifact_id`` and ``version`` are the pom's own, falling
+    back to ``<parent>`` for the group and version. ``dependencies`` holds the
+    declared dependencies first, then the managed-only entries, each unique
+    by ``groupId:artifactId``. ``pom_paths`` lists every pom read, the given
+    one first.
+    """
+
+    path: str
+    group_id: str | None
+    artifact_id: str | None
+    version: str | None
+    dependencies: tuple[MavenDependency, ...] = ()
+    boms: tuple[MavenCoordinate, ...] = ()
+    external_parent: MavenCoordinate | None = None
+    pom_paths: tuple[str, ...] = ()
+
+    def lines(self) -> list[str]:
+        """Every renderable dependency line, sorted and deduplicated."""
+        return sorted({line for dep in self.dependencies if (line := dep.line())})
+
+
+@dataclass(frozen=True)
+class _Entry:
+    group_id: str
+    artifact_id: str
+    version: str
+    type: str
+    scope: str
+
+
+@dataclass(frozen=True)
+class _ParentRef:
+    group_id: str
+    artifact_id: str
+    version: str
+    relative_path: str | None
+
+
+@dataclass(frozen=True)
+class _Pom:
+    group_id: str
+    artifact_id: str
+    version: str
+    parent: _ParentRef | None
+    properties: tuple[tuple[str, str], ...]
+    dependencies: tuple[_Entry, ...]
+    managed: tuple[_Entry, ...]
+
+
+class _TooLong(Exception):
+    pass
+
+
+def _parse(text: str) -> ET.Element:
+    return ET.fromstring(text)
+
+
+def _safe_root(text: object) -> ET.Element | None:
+    if not isinstance(text, str) or not text.strip():
+        return None
+    if len(text) > MAX_POM_BYTES or len(text.encode("utf-8", "ignore")) > MAX_POM_BYTES:
+        return None
+    if _UNSAFE_RE.search(text):
+        return None
+    try:
+        root = _parse(text)
+    except Exception:  # noqa: BLE001 - a broken pom is not a review failure
+        return None
+    for element in root.iter():
+        if isinstance(element.tag, str) and element.tag.startswith("{"):
+            element.tag = element.tag.split("}", 1)[1]
+    return root if root.tag == "project" else None
+
+
+def _text(element: ET.Element, tag: str) -> str:
+    child = element.find(tag)
+    if child is None:
+        return ""
+    return (child.text or "").strip()
+
+
+def _entries(container: ET.Element | None) -> tuple[_Entry, ...]:
+    if container is None:
+        return ()
+    out: list[_Entry] = []
+    for dep in container.findall("dependency"):
+        group_id = _text(dep, "groupId")
+        artifact_id = _text(dep, "artifactId")
+        if not group_id or not artifact_id:
+            continue
+        out.append(_Entry(
+            group_id=group_id,
+            artifact_id=artifact_id,
+            version=_text(dep, "version"),
+            type=_text(dep, "type") or "jar",
+            scope=_text(dep, "scope"),
+        ))
+    return tuple(out)
+
+
+def _read_pom(text: object) -> _Pom | None:
+    root = _safe_root(text)
+    if root is None:
+        return None
+    parent: _ParentRef | None = None
+    parent_el = root.find("parent")
+    if parent_el is not None and _text(parent_el, "artifactId"):
+        relative_el = parent_el.find("relativePath")
+        parent = _ParentRef(
+            group_id=_text(parent_el, "groupId"),
+            artifact_id=_text(parent_el, "artifactId"),
+            version=_text(parent_el, "version"),
+            relative_path=None if relative_el is None else (relative_el.text or "").strip(),
+        )
+    properties: list[tuple[str, str]] = []
+    properties_el = root.find("properties")
+    if properties_el is not None:
+        for prop in properties_el:
+            if isinstance(prop.tag, str):
+                properties.append((prop.tag, (prop.text or "").strip()))
+    return _Pom(
+        group_id=_text(root, "groupId"),
+        artifact_id=_text(root, "artifactId"),
+        version=_text(root, "version"),
+        parent=parent,
+        properties=tuple(properties),
+        dependencies=_entries(root.find("dependencies")),
+        managed=_entries(root.find("dependencyManagement/dependencies")),
+    )
+
+
+def _safe_read(read: Reader, path: str) -> str | None:
+    try:
+        text = read(path)
+    except Exception:  # noqa: BLE001 - an unreadable pom is not a review failure
+        return None
+    return text if isinstance(text, str) else None
+
+
+def _parent_path(child_path: str, relative_path: str | None) -> str | None:
+    if relative_path == "":
+        return None
+    relative = (relative_path or _DEFAULT_RELATIVE_PATH).replace("\\", "/")
+    if relative.startswith("/"):
+        return None
+    joined = posixpath.join(posixpath.dirname(child_path), relative)
+    if not joined.endswith(".xml"):
+        joined = posixpath.join(joined, "pom.xml")
+    target = posixpath.normpath(joined)
+    if target == ".." or target.startswith("../"):
+        return None
+    return target
+
+
+def _expand_once(value: str, properties: Mapping[str, str]) -> str:
+    size = 0
+
+    def swap(match: re.Match[str]) -> str:
+        nonlocal size
+        replacement = properties.get(match.group(1), match.group(0))
+        size += len(replacement) - len(match.group(0))
+        if len(value) + size > MAX_INTERPOLATED_CHARS:
+            raise _TooLong
+        return replacement
+
+    return _PLACEHOLDER_RE.sub(swap, value)
+
+
+def _interpolate(value: str, properties: Mapping[str, str]) -> str:
+    for _ in range(MAX_PROPERTY_PASSES):
+        try:
+            expanded = _expand_once(value, properties)
+        except _TooLong:
+            return value
+        if expanded == value:
+            return value
+        value = expanded
+    return value
+
+
+def _chain(path: str, read: Reader, text: str | None) -> tuple[list[_Pom], list[str], _ParentRef | None] | None:
+    child = _read_pom(text if text is not None else _safe_read(read, path))
+    if child is None:
+        return None
+    chain = [child]
+    paths = [path]
+    current = posixpath.normpath(path)
+    visited = {current}
+    pom = child
+    while pom.parent is not None:
+        ref = pom.parent
+        if len(chain) - 1 >= MAX_POM_PARENTS:
+            return chain, paths, ref
+        target = _parent_path(current, ref.relative_path)
+        if target is None:
+            return chain, paths, ref
+        if target in visited:
+            return chain, paths, None
+        visited.add(target)
+        parent = _read_pom(_safe_read(read, target))
+        if parent is None or parent.artifact_id != ref.artifact_id:
+            return chain, paths, ref
+        chain.append(parent)
+        paths.append(target)
+        current = target
+        pom = parent
+    return chain, paths, None
+
+
+def _resolve(path: str, read: Reader, text: str | None) -> MavenProject | None:
+    walked = _chain(path, read, text)
+    if walked is None:
+        return None
+    chain, paths, external_ref = walked
+    child = chain[0]
+    own_parent = child.parent
+    group_id = child.group_id or (own_parent.group_id if own_parent else "")
+    version = child.version or (own_parent.version if own_parent else "")
+
+    properties: dict[str, str] = {}
+    for pom in reversed(chain):
+        properties.update(pom.properties)
+    if version:
+        properties["project.version"] = version
+    if group_id:
+        properties["project.groupId"] = group_id
+    if own_parent is not None and own_parent.version:
+        properties["project.parent.version"] = own_parent.version
+
+    def resolve(value: str) -> str:
+        return _interpolate(value, properties) if value else value
+
+    external = None
+    if external_ref is not None:
+        external = MavenCoordinate(
+            resolve(external_ref.group_id),
+            resolve(external_ref.artifact_id),
+            resolve(external_ref.version) or None,
+        )
+
+    boms: dict[tuple[str, str], MavenCoordinate] = {}
+    managed: dict[tuple[str, str], str] = {}
+    for pom in chain:
+        for entry in pom.managed:
+            key = (resolve(entry.group_id), resolve(entry.artifact_id))
+            if resolve(entry.scope) == "import" and resolve(entry.type) == "pom":
+                boms.setdefault(key, MavenCoordinate(key[0], key[1], resolve(entry.version) or None))
+                continue
+            if not managed.get(key):
+                managed[key] = resolve(entry.version)
+
+    owners = ([external] if external is not None else []) + list(boms.values())
+    owner = owners[0] if owners else None
+
+    def dependency(key: tuple[str, str], stated: str) -> MavenDependency:
+        resolved = stated or managed.get(key, "")
+        if resolved:
+            return MavenDependency(key[0], key[1], resolved)
+        return MavenDependency(key[0], key[1], None, owner)
+
+    dependencies: dict[tuple[str, str], MavenDependency] = {}
+    for pom in chain:
+        for entry in pom.dependencies:
+            key = (resolve(entry.group_id), resolve(entry.artifact_id))
+            if key not in dependencies and key not in boms:
+                dependencies[key] = dependency(key, resolve(entry.version))
+    for key in managed:
+        if key not in dependencies and key not in boms:
+            dependencies[key] = dependency(key, "")
+
+    return MavenProject(
+        path=path,
+        group_id=resolve(group_id) or None,
+        artifact_id=resolve(child.artifact_id) or None,
+        version=resolve(version) or None,
+        dependencies=tuple(dependencies.values()),
+        boms=tuple(boms.values()),
+        external_parent=external,
+        pom_paths=tuple(paths),
+    )
+
+
+def resolve_pom(path: str, read: Reader, text: str | None = None) -> MavenProject | None:
+    """Resolve the pom at ``path`` and its in-repository parents.
+
+    ``read`` maps a repository-relative path to its text, or ``None``. When
+    the caller already holds the pom's text it may pass it as ``text``, and
+    ``path`` is then not read again (parents still are). Returns ``None`` when
+    the pom itself is unreadable, refused, malformed or not a ``<project>``;
+    never raises.
+    """
+    try:
+        return _resolve(path, read, text)
+    except Exception:  # noqa: BLE001 - a broken pom is not a review failure
+        return None
diff --git a/tests/test_jvm_maven.py b/tests/test_jvm_maven.py
new file mode 100644
index 0000000..cbc529f
--- /dev/null
+++ b/tests/test_jvm_maven.py
@@ -0,0 +1,586 @@
+"""Unit tests for :mod:`prxref.jvm_maven`, the pom.xml reader behind #20.
+
+Every test supplies its own ``read`` callable, usually a counting one, so the
+refusals, the parent walk and its caps are pinned by exactly which paths were
+read, without a forge or a filesystem.
+"""
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+import pytest
+
+from prxref import chunk_context, jvm_maven
+from prxref.jvm_maven import (
+    MAX_INTERPOLATED_CHARS,
+    MAX_POM_BYTES,
+    MAX_POM_PARENTS,
+    MAX_PROPERTY_PASSES,
+    MavenCoordinate,
+    MavenDependency,
+    resolve_pom,
+)
+
+POM_NS = 'xmlns="http://maven.apache.org/POM/4.0.0"'
+SPRING_BOM = ("org.springframework.boot", "spring-boot-dependencies")
+DATABIND = ("com.fasterxml.jackson.core", "jackson-databind")
+
+
+def pom(body: str, *, xmlns: bool = True, prolog: str = "") -> str:
+    head = f"<project {POM_NS}>" if xmlns else "<project>"
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        f"{prolog}{head}\n  <modelVersion>4.0.0</modelVersion>\n{body}\n</project>\n"
+    )
+
+
+def dep(group: str, artifact: str, version: str | None = None, *, type_: str = "", scope: str = "") -> str:
+    parts = [f"<groupId>{group}</groupId>", f"<artifactId>{artifact}</artifactId>"]
+    if version is not None:
+        parts.append(f"<version>{version}</version>")
+    if type_:
+        parts.append(f"<type>{type_}</type>")
+    if scope:
+        parts.append(f"<scope>{scope}</scope>")
+    return "<dependency>" + "".join(parts) + "</dependency>"
+
+
+def deps(*items: str) -> str:
+    return "<dependencies>" + "".join(items) + "</dependencies>"
+
+
+def managed(*items: str) -> str:
+    return "<dependencyManagement>" + deps(*items) + "</dependencyManagement>"
+
+
+def props(**values: str) -> str:
+    return "<properties>" + "".join(f"<{k}>{v}</{k}>" for k, v in values.items()) + "</properties>"
+
+
+def parent(group: str, artifact: str, version: str, relative: str | None = None) -> str:
+    parts = [f"<groupId>{group}</groupId>", f"<artifactId>{artifact}</artifactId>", f"<version>{version}</version>"]
+    if relative == "":
+        parts.append("<relativePath/>")
+    elif relative is not None:
+        parts.append(f"<relativePath>{relative}</relativePath>")
+    return "<parent>" + "".join(parts) + "</parent>"
+
+
+def coords(group: str, artifact: str, version: str | None = None) -> str:
+    out = f"<groupId>{group}</groupId><artifactId>{artifact}</artifactId>"
+    return out + (f"<version>{version}</version>" if version else "")
+
+
+class CountingReader:
+    def __init__(self, files: dict[str, str]):
+        self.files = dict(files)
+        self.calls: list[str] = []
+
+    def __call__(self, path: str) -> str | None:
+        self.calls.append(path)
+        return self.files.get(path)
+
+
+def by_name(project) -> dict[str, MavenDependency]:
+    return {d.name: d for d in project.dependencies}
+
+
+@pytest.fixture
+def parse_calls(monkeypatch):
+    calls: list[str] = []
+    real = jvm_maven._parse
+
+    def spy(text: str):
+        calls.append(text)
+        return real(text)
+
+    monkeypatch.setattr(jvm_maven, "_parse", spy)
+    return calls
+
+
+PLAIN = pom(coords("com.acme", "app", "1.0.0") + deps(dep(*DATABIND, "2.17.1")))
+
+
+def billion_laughs() -> str:
+    entities = ['  <!ENTITY lol0 "lol">']
+    for level in range(1, 10):
+        entities.append(f'  <!ENTITY lol{level} "' + f"&lol{level - 1};" * 10 + '">')
+    return (
+        '<?xml version="1.0"?>\n<!DOCTYPE project [\n' + "\n".join(entities) + "\n]>\n"
+        "<project><groupId>com.acme</groupId><artifactId>&lol9;</artifactId></project>\n"
+    )
+
+
+class TestRefusal:
+    def test_the_size_cap_is_the_chunk_context_file_cap(self):
+        assert MAX_POM_BYTES == chunk_context.MAX_FILE_BYTES
+
+    def test_the_spy_sees_a_clean_pom_parse_exactly_once(self, parse_calls):
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": PLAIN}))
+        assert project is not None
+        assert project.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+        assert len(parse_calls) == 1
+
+    def test_a_doctype_is_refused_before_parsing(self, parse_calls):
+        text = pom(
+            coords("com.acme", "app", "1.0.0") + deps(dep(*DATABIND, "2.17.1")),
+            prolog='<!DOCTYPE project SYSTEM "http://example.com/project.dtd">\n',
+        )
+        assert "ENTITY" not in text.upper()
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": text})) is None
+        assert parse_calls == []
+
+    def test_a_lowercase_doctype_is_refused_before_parsing(self, parse_calls):
+        text = pom(coords("com.acme", "app", "1.0.0"), prolog="<!doctype project>\n")
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": text})) is None
+        assert parse_calls == []
+
+    def test_an_entity_declaration_anywhere_is_refused_before_parsing(self, parse_calls):
+        text = pom(coords("com.acme", "app", "1.0.0") + '<!-- <!Entity x "y"> -->' + deps(dep(*DATABIND, "2.17.1")))
+        assert "DOCTYPE" not in text.upper()
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": text})) is None
+        assert parse_calls == []
+
+    def test_a_billion_laughs_payload_returns_nothing_and_is_never_parsed(self, parse_calls):
+        payload = billion_laughs()
+        assert payload.count("<!ENTITY") == 10
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": payload})) is None
+        assert resolve_pom("pom.xml", CountingReader({}), text=payload) is None
+        assert parse_calls == []
+
+    def test_a_pom_at_the_byte_cap_parses_and_one_byte_over_is_refused(self, parse_calls):
+        def padded(size: int) -> str:
+            filler = size - len(PLAIN.encode("utf-8")) - len("<!--  -->")
+            return PLAIN + "<!-- " + "x" * filler + " -->"
+
+        at_cap, over_cap = padded(MAX_POM_BYTES), padded(MAX_POM_BYTES + 1)
+        assert len(at_cap.encode("utf-8")) == MAX_POM_BYTES
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": at_cap})) is not None
+        assert len(parse_calls) == 1
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": over_cap})) is None
+        assert len(parse_calls) == 1
+
+    def test_the_cap_counts_utf8_bytes_not_characters(self, parse_calls):
+        wide = "\N{LATIN SMALL LETTER E WITH ACUTE}"
+        filler = (MAX_POM_BYTES - len(PLAIN)) // 2 + 1
+        text = PLAIN + "<!-- " + wide * filler + " -->"
+        assert len(text) <= MAX_POM_BYTES < len(text.encode("utf-8"))
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": text})) is None
+        assert parse_calls == []
+
+    def test_a_refused_parent_is_external_and_the_child_still_resolves(self, parse_calls):
+        bad_parent = pom(coords("com.acme", "parent", "1.0.0"), prolog="<!DOCTYPE project>\n")
+        child = pom(parent("com.acme", "parent", "1.0.0") + coords("com.acme", "api") + deps(dep(*DATABIND)))
+        reader = CountingReader({"api/pom.xml": child, "pom.xml": bad_parent})
+        project = resolve_pom("api/pom.xml", reader)
+        assert project is not None
+        assert reader.calls == ["api/pom.xml", "pom.xml"]
+        assert project.pom_paths == ("api/pom.xml",)
+        assert project.external_parent == MavenCoordinate("com.acme", "parent", "1.0.0")
+        assert len(parse_calls) == 1
+
+
+class TestMalformed:
+    @pytest.mark.parametrize("text", [
+        pom(deps("<dependency><groupId>com.acme</groupId>")),
+        "<project><groupId>com.acme</groupId>",
+        "not xml at all",
+        "",
+        "   \n",
+    ])
+    def test_a_malformed_pom_contributes_nothing(self, text):
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": text})) is None
+
+    def test_a_root_other_than_project_contributes_nothing(self):
+        text = '<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"><localRepository/></settings>'
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": text})) is None
+
+    def test_a_missing_pom_contributes_nothing(self):
+        reader = CountingReader({})
+        assert resolve_pom("pom.xml", reader) is None
+        assert reader.calls == ["pom.xml"]
+
+    def test_a_raising_or_non_text_reader_never_raises(self):
+        def boom(path: str) -> str | None:
+            raise OSError("forge down")
+
+        assert resolve_pom("pom.xml", boom) is None
+        assert resolve_pom("pom.xml", lambda path: b"<project/>") is None
+
+    def test_a_malformed_parent_is_external_and_the_child_still_resolves(self):
+        child = pom(parent("com.acme", "parent", "1.0.0") + coords("com.acme", "api") + deps(dep(*DATABIND)))
+        reader = CountingReader({"api/pom.xml": child, "pom.xml": "<project><dependencies>"})
+        project = resolve_pom("api/pom.xml", reader)
+        assert project is not None
+        assert project.pom_paths == ("api/pom.xml",)
+        assert project.external_parent == MavenCoordinate("com.acme", "parent", "1.0.0")
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind@(managed by com.acme:parent@1.0.0)",
+        ]
+
+
+class TestProperties:
+    def test_nested_properties_resolve(self):
+        text = pom(
+            coords("com.acme", "app", "1.0.0")
+            + props(**{
+                "jackson.major": "2",
+                "jackson.minor": "${jackson.major}.17",
+                "jackson.version": "${jackson.minor}.1",
+            })
+            + deps(dep(*DATABIND, "${jackson.version}"))
+        )
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        assert project.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_a_child_property_overrides_its_parent(self):
+        parent_pom = pom(
+            coords("com.acme", "parent", "1.0.0")
+            + props(**{"jackson.version": "2.15.0", "slf4j.version": "2.0.13"})
+            + managed(dep(*DATABIND, "${jackson.version}"), dep("org.slf4j", "slf4j-api", "${slf4j.version}"))
+        )
+        child = pom(
+            parent("com.acme", "parent", "1.0.0")
+            + coords("com.acme", "api")
+            + props(**{"jackson.version": "2.17.1"})
+            + deps(dep(*DATABIND), dep("org.slf4j", "slf4j-api"))
+        )
+        project = resolve_pom("api/pom.xml", CountingReader({"api/pom.xml": child, "pom.xml": parent_pom}))
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+            "org.slf4j:slf4j-api@2.0.13",
+        ]
+
+    def test_project_version_group_and_parent_version_resolve(self):
+        parent_pom = pom(coords("com.acme", "parent", "3.1.0"))
+        child = pom(
+            parent("com.acme", "parent", "3.1.0")
+            + "<artifactId>api</artifactId>"
+            + deps(
+                dep("${project.groupId}", "core", "${project.version}"),
+                dep("com.example", "client", "${project.parent.version}"),
+            )
+        )
+        project = resolve_pom("api/pom.xml", CountingReader({"api/pom.xml": child, "pom.xml": parent_pom}))
+        assert (project.group_id, project.artifact_id, project.version) == ("com.acme", "api", "3.1.0")
+        assert project.lines() == ["com.acme:core@3.1.0", "com.example:client@3.1.0"]
+
+    def test_an_unresolved_placeholder_stays_literal(self):
+        text = pom(coords("com.acme", "app", "1.0.0") + deps(dep("com.example", "lib", "${x}")))
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        assert project.lines() == ["com.example:lib@${x}"]
+
+    def test_resolution_stops_after_the_pass_limit(self):
+        assert MAX_PROPERTY_PASSES == 5
+
+        def chain(depth: int) -> dict[str, str]:
+            values = {f"p{i}": f"${{p{i + 1}}}" for i in range(1, depth)}
+            values[f"p{depth}"] = "9.9.9"
+            return values
+
+        fits = pom(coords("com.acme", "app", "1") + props(**chain(5)) + deps(dep("com.example", "a", "${p1}")))
+        too_deep = pom(coords("com.acme", "app", "1") + props(**chain(6)) + deps(dep("com.example", "a", "${p1}")))
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": fits})).lines() == ["com.example:a@9.9.9"]
+        assert resolve_pom("pom.xml", CountingReader({"pom.xml": too_deep})).lines() == ["com.example:a@${p6}"]
+
+    def test_a_property_cycle_terminates_literal(self):
+        text = pom(coords("com.acme", "app", "1") + props(a="${b}", b="${a}") + deps(dep("com.example", "lib", "${a}")))
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        assert project.lines() in (["com.example:lib@${a}"], ["com.example:lib@${b}"])
+
+    def test_a_self_multiplying_property_stops_below_the_char_cap(self):
+        text = pom(
+            coords("com.acme", "app", "1")
+            + props(a="${a}" * 8, big="x" * 4000)
+            + deps(dep("com.example", "grow", "${a}"), dep("com.example", "huge", "${big}" * 50))
+        )
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        found = by_name(project)
+        assert found["com.example:grow"].version == "${a}" * 64
+        assert len("${a}" * 512) > MAX_INTERPOLATED_CHARS
+        assert found["com.example:huge"].version == "${big}" * 50
+
+
+class TestParentChain:
+    PARENT = pom(
+        coords("com.acme", "parent", "1.0.0")
+        + props(**{"jackson.version": "2.17.1"})
+        + managed(dep(*DATABIND, "${jackson.version}"))
+    )
+
+    def child(self, relative: str | None) -> str:
+        return pom(parent("com.acme", "parent", "1.0.0", relative) + coords("com.acme", "api") + deps(dep(*DATABIND)))
+
+    def test_a_parent_is_found_via_an_explicit_relative_path(self):
+        reader = CountingReader({"services/api/pom.xml": self.child("../../build/parent/pom.xml"),
+                                 "build/parent/pom.xml": self.PARENT})
+        project = resolve_pom("services/api/pom.xml", reader)
+        assert reader.calls == ["services/api/pom.xml", "build/parent/pom.xml"]
+        assert project.pom_paths == ("services/api/pom.xml", "build/parent/pom.xml")
+        assert project.external_parent is None
+        assert project.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_a_relative_path_naming_a_directory_gets_pom_xml_appended(self):
+        reader = CountingReader({"services/api/pom.xml": self.child("../../build/parent"),
+                                 "build/parent/pom.xml": self.PARENT})
+        project = resolve_pom("services/api/pom.xml", reader)
+        assert reader.calls == ["services/api/pom.xml", "build/parent/pom.xml"]
+        assert project.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_a_parent_is_found_via_the_default_relative_path(self):
+        reader = CountingReader({"api/pom.xml": self.child(None), "pom.xml": self.PARENT})
+        project = resolve_pom("api/pom.xml", reader)
+        assert reader.calls == ["api/pom.xml", "pom.xml"]
+        assert project.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_an_empty_relative_path_is_external_and_never_read(self):
+        reader = CountingReader({"api/pom.xml": self.child(""), "pom.xml": self.PARENT})
+        project = resolve_pom("api/pom.xml", reader)
+        assert reader.calls == ["api/pom.xml"]
+        assert project.external_parent == MavenCoordinate("com.acme", "parent", "1.0.0")
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind@(managed by com.acme:parent@1.0.0)",
+        ]
+
+    def test_an_artifact_id_mismatch_is_external(self):
+        impostor = pom(coords("com.acme", "other-parent", "1.0.0") + props(**{"jackson.version": "9.9.9"})
+                       + managed(dep(*DATABIND, "${jackson.version}")))
+        reader = CountingReader({"api/pom.xml": self.child(None), "pom.xml": impostor})
+        project = resolve_pom("api/pom.xml", reader)
+        assert reader.calls == ["api/pom.xml", "pom.xml"]
+        assert project.pom_paths == ("api/pom.xml",)
+        assert project.external_parent == MavenCoordinate("com.acme", "parent", "1.0.0")
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind@(managed by com.acme:parent@1.0.0)",
+        ]
+
+    def test_a_root_pom_default_parent_is_outside_the_repository_and_never_read(self):
+        root = pom(parent("org.springframework.boot", "spring-boot-starter-parent", "3.3.4")
+                   + coords("com.acme", "app") + deps(dep(*DATABIND)))
+        reader = CountingReader({"pom.xml": root})
+        project = resolve_pom("pom.xml", reader)
+        assert reader.calls == ["pom.xml"]
+        assert project.version == "3.3.4"
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind"
+            "@(managed by org.springframework.boot:spring-boot-starter-parent@3.3.4)",
+        ]
+
+    def test_an_absolute_relative_path_is_external_and_never_read(self):
+        reader = CountingReader({"api/pom.xml": self.child("/etc/pom.xml"), "etc/pom.xml": self.PARENT})
+        project = resolve_pom("api/pom.xml", reader)
+        assert reader.calls == ["api/pom.xml"]
+        assert project.external_parent == MavenCoordinate("com.acme", "parent", "1.0.0")
+
+    def test_a_cycle_reads_each_pom_once_and_stops(self):
+        a = pom(parent("com.acme", "b", "1", "../b/pom.xml") + coords("com.acme", "a", "1")
+                + props(**{"from.a": "1.1"}) + deps(dep("com.example", "x", "${from.b}")))
+        b = pom(parent("com.acme", "a", "1", "../a/pom.xml") + coords("com.acme", "b", "1")
+                + props(**{"from.b": "2.2"}) + deps(dep("com.example", "y", "${from.a}")))
+        reader = CountingReader({"a/pom.xml": a, "b/pom.xml": b})
+        project = resolve_pom("a/pom.xml", reader)
+        assert reader.calls == ["a/pom.xml", "b/pom.xml"]
+        assert project.pom_paths == ("a/pom.xml", "b/pom.xml")
+        assert project.external_parent is None
+        assert project.lines() == ["com.example:x@2.2", "com.example:y@1.1"]
+
+    def test_a_pom_naming_itself_as_parent_is_read_once(self):
+        text = pom(parent("com.acme", "app", "1", "pom.xml") + coords("com.acme", "app", "1"))
+        reader = CountingReader({"pom.xml": text})
+        project = resolve_pom("pom.xml", reader)
+        assert reader.calls == ["pom.xml"]
+        assert project.external_parent is None
+
+    @staticmethod
+    def ladder() -> dict[str, str]:
+        files: dict[str, str] = {}
+        for level in range(7):
+            path = "/".join(["m"] * (6 - level) + ["pom.xml"])
+            body = coords("com.acme", f"level{level}", "1.0.0")
+            if level < 6:
+                body = parent("com.acme", f"level{level + 1}", "1.0.0") + body
+            if level == 5:
+                body += props(five="5.0.0")
+            if level == 6:
+                body += props(six="6.0.0")
+            if level == 0:
+                body += deps(dep("com.example", "five", "${five}"), dep("com.example", "six", "${six}"))
+            files[path] = pom(body)
+        return files
+
+    def test_the_depth_cap_stops_after_five_parents(self):
+        assert MAX_POM_PARENTS == 5
+        reader = CountingReader(self.ladder())
+        project = resolve_pom("m/m/m/m/m/m/pom.xml", reader)
+        assert len(reader.calls) == 6
+        assert "pom.xml" not in reader.calls
+        assert project.pom_paths == tuple(reader.calls)
+        assert project.lines() == ["com.example:five@5.0.0", "com.example:six@${six}"]
+        assert project.external_parent == MavenCoordinate("com.acme", "level6", "1.0.0")
+
+    def test_a_sixth_parent_is_read_only_when_the_cap_allows_it(self, monkeypatch):
+        monkeypatch.setattr(jvm_maven, "MAX_POM_PARENTS", 6)
+        reader = CountingReader(self.ladder())
+        project = resolve_pom("m/m/m/m/m/m/pom.xml", reader)
+        assert reader.calls[-1] == "pom.xml"
+        assert project.lines() == ["com.example:five@5.0.0", "com.example:six@6.0.0"]
+        assert project.external_parent is None
+
+    def test_parent_dependencies_are_inherited_and_the_child_wins(self):
+        parent_pom = pom(coords("com.acme", "parent", "1.0.0")
+                         + deps(dep("org.slf4j", "slf4j-api", "2.0.13"), dep(*DATABIND, "2.15.0")))
+        child = pom(parent("com.acme", "parent", "1.0.0") + coords("com.acme", "api") + deps(dep(*DATABIND, "2.17.1")))
+        project = resolve_pom("api/pom.xml", CountingReader({"api/pom.xml": child, "pom.xml": parent_pom}))
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+            "org.slf4j:slf4j-api@2.0.13",
+        ]
+
+
+class TestDependencies:
+    def test_dependencies_and_dependency_management_are_both_read(self):
+        text = pom(
+            coords("com.acme", "app", "1.0.0")
+            + managed(dep(*DATABIND, "2.17.1"), dep("jakarta.persistence", "jakarta.persistence-api", "3.1.0"))
+            + deps(dep(*DATABIND), dep("org.slf4j", "slf4j-api", "2.0.13"))
+        )
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        assert [d.name for d in project.dependencies] == [
+            "com.fasterxml.jackson.core:jackson-databind",
+            "org.slf4j:slf4j-api",
+            "jakarta.persistence:jakarta.persistence-api",
+        ]
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+            "jakarta.persistence:jakarta.persistence-api@3.1.0",
+            "org.slf4j:slf4j-api@2.0.13",
+        ]
+
+    def test_plugin_and_profile_dependencies_are_not_read(self):
+        text = pom(
+            coords("com.acme", "app", "1.0.0")
+            + deps(dep("org.slf4j", "slf4j-api", "2.0.13"))
+            + "<build><plugins><plugin>" + coords("org.apache.maven.plugins", "maven-surefire-plugin", "3.2.5")
+            + deps(dep("com.example", "plugin-only", "1.0")) + "</plugin></plugins></build>"
+            + "<profiles><profile><id>extra</id>" + deps(dep("com.example", "profile-only", "1.0"))
+            + "</profile></profiles>"
+        )
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        assert project.lines() == ["org.slf4j:slf4j-api@2.0.13"]
+
+    def test_an_imported_bom_owns_versionless_dependencies(self):
+        text = pom(
+            coords("com.acme", "app", "1.0.0")
+            + props(**{"spring-boot.version": "3.3.4"})
+            + managed(dep(*SPRING_BOM, "${spring-boot.version}", type_="pom", scope="import"))
+            + deps(dep(*DATABIND), dep("com.example", "pinned", "1.2.3"))
+        )
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        spring_boot = MavenCoordinate(*SPRING_BOM, "3.3.4")
+        assert project.boms == (spring_boot,)
+        assert by_name(project)["com.fasterxml.jackson.core:jackson-databind"] == MavenDependency(
+            *DATABIND, None, spring_boot,
+        )
+        assert project.lines() == [
+            "com.example:pinned@1.2.3",
+            "com.fasterxml.jackson.core:jackson-databind"
+            "@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)",
+        ]
+        assert "org.springframework.boot:spring-boot-dependencies" not in by_name(project)
+
+    def test_a_bom_imported_by_a_parent_owns_the_child_dependency(self):
+        parent_pom = pom(coords("com.acme", "parent", "1.0.0")
+                         + managed(dep(*SPRING_BOM, "3.3.4", type_="pom", scope="import")))
+        child = pom(parent("com.acme", "parent", "1.0.0") + coords("com.acme", "api") + deps(dep(*DATABIND)))
+        project = resolve_pom("api/pom.xml", CountingReader({"api/pom.xml": child, "pom.xml": parent_pom}))
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind"
+            "@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)",
+        ]
+
+    def test_import_scope_without_pom_type_is_not_a_bom(self):
+        text = pom(coords("com.acme", "app", "1.0.0") + managed(dep(*SPRING_BOM, "3.3.4", scope="import"))
+                   + deps(dep(*DATABIND)))
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        assert project.boms == ()
+        assert by_name(project)["com.fasterxml.jackson.core:jackson-databind"].line() is None
+
+    def test_owner_precedence_is_external_parent_then_boms_nearest_first(self):
+        parent_pom = pom(
+            parent("com.example", "corporate-parent", "7", "") + coords("com.acme", "parent", "1.0.0")
+            + managed(dep("com.fasterxml.jackson", "jackson-bom", "2.17.1", type_="pom", scope="import"))
+        )
+        child = pom(parent("com.acme", "parent", "1.0.0") + coords("com.acme", "api")
+                    + managed(dep(*SPRING_BOM, "3.3.4", type_="pom", scope="import")) + deps(dep(*DATABIND)))
+        files = {"api/pom.xml": child, "pom.xml": parent_pom}
+        project = resolve_pom("api/pom.xml", CountingReader(files))
+        assert project.boms == (MavenCoordinate(*SPRING_BOM, "3.3.4"),
+                                MavenCoordinate("com.fasterxml.jackson", "jackson-bom", "2.17.1"))
+        assert project.external_parent == MavenCoordinate("com.example", "corporate-parent", "7")
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind@(managed by com.example:corporate-parent@7)",
+        ]
+        files["pom.xml"] = parent_pom.replace(parent("com.example", "corporate-parent", "7", ""), "")
+        project = resolve_pom("api/pom.xml", CountingReader(files))
+        assert project.external_parent is None
+        assert project.lines() == [
+            "com.fasterxml.jackson.core:jackson-databind"
+            "@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)",
+        ]
+
+    def test_a_managed_version_wins_over_every_owner(self):
+        text = pom(parent("com.example", "corporate-parent", "7", "") + coords("com.acme", "app")
+                   + managed(dep(*SPRING_BOM, "3.3.4", type_="pom", scope="import"), dep(*DATABIND, "2.17.1"))
+                   + deps(dep(*DATABIND)))
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        assert project.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_no_version_and_no_owner_renders_no_line(self):
+        text = pom(coords("com.acme", "app", "1.0.0") + deps(dep(*DATABIND), dep("org.slf4j", "slf4j-api", "2.0.13")))
+        project = resolve_pom("pom.xml", CountingReader({"pom.xml": text}))
+        orphan = by_name(project)["com.fasterxml.jackson.core:jackson-databind"]
+        assert (orphan.version, orphan.managed_by, orphan.line()) == (None, None, None)
+        assert project.lines() == ["org.slf4j:slf4j-api@2.0.13"]
+
+    def test_a_pom_without_a_namespace_reads_the_same(self):
+        body = coords("com.acme", "app", "1.0.0") + deps(dep(*DATABIND, "2.17.1"))
+        with_ns = resolve_pom("pom.xml", CountingReader({"pom.xml": pom(body)}))
+        without_ns = resolve_pom("pom.xml", CountingReader({"pom.xml": pom(body, xmlns=False)}))
+        assert with_ns == without_ns
+        assert with_ns.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_the_group_falls_back_to_the_parent_element(self):
+        child = pom(parent("com.acme", "parent", "2.0.0", "") + "<artifactId>api</artifactId>")
+        project = resolve_pom("api/pom.xml", CountingReader({"api/pom.xml": child}))
+        assert (project.group_id, project.artifact_id, project.version) == ("com.acme", "api", "2.0.0")
+
+    def test_supplied_text_is_not_read_again(self):
+        reader = CountingReader({})
+        project = resolve_pom("pom.xml", reader, text=PLAIN)
+        assert reader.calls == []
+        assert project.pom_paths == ("pom.xml",)
+        assert project.lines() == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_rendered_shapes(self):
+        owner = MavenCoordinate(*SPRING_BOM, "3.3.4")
+        assert owner.render() == "org.springframework.boot:spring-boot-dependencies@3.3.4"
+        assert MavenCoordinate("com.acme", "bom").render() == "com.acme:bom"
+        assert MavenDependency("com.acme", "core", "1.0").line() == "com.acme:core@1.0"
+        assert MavenDependency("com.acme", "core", None, owner).line() == (
+            "com.acme:core@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)"
+        )
+        assert MavenDependency("com.acme", "core").line() is None
+
+
+def test_the_module_imports_only_the_standard_library():
+    tree = ast.parse(Path(jvm_maven.__file__).read_text(encoding="utf-8"))
+    imported = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imported.update(alias.name.split(".")[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            assert node.level == 0
+            imported.add((node.module or "").split(".")[0])
+    assert imported <= set(sys.stdlib_module_names) | {"__future__"}

From f4b93b2775d0e97c9ab8eee2b57f01d1e21d03da Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:14:11 -0700
Subject: [PATCH 06/25] feat: jvm_lang, Java and Kotlin definition regexes,
 keywords and imports (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds src/prxref/jvm_lang.py, a stdlib-only leaf module that imports nothing
from prxref, so chunk_context can use it without the repo_context import
cycle. It holds:

- jvm_language(path): "java" for .java, "kotlin" for .kt and .kts.
- Java definition regexes in the order a caller tries them: types (the
  repo_context type pattern, copied byte for byte), methods, fields and
  constants, then enum constants. A statement-keyword lookahead at the type
  position keeps return/new/throw/else/assert lines out of the method and
  field regexes.
- Kotlin regexes for class (data, sealed, enum, value, annotation), interface,
  fun interface, object, typealias, fun (with extension receivers) and
  val/var, with modifier and annotation prefixes.
- The Java keyword and JDK name sets (equal to repo_context's) and a Kotlin
  keyword set.
- parse_import/parse_imports returning JvmImport(name, alias, static,
  wildcard) for any package, including static, wildcard and Kotlin `as`.
- annotation_start: the lookback to at most 2 directly preceding annotation
  lines, where a definition entry then starts.

tests/test_jvm_lang.py pins the equality with repo_context, the leaf-import
property, every regex against the hard negatives, and Spring and Kotlin
snippets end to end.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/jvm_lang.py | 302 ++++++++++++++++++++
 tests/test_jvm_lang.py | 620 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 922 insertions(+)
 create mode 100644 src/prxref/jvm_lang.py
 create mode 100644 tests/test_jvm_lang.py

diff --git a/src/prxref/jvm_lang.py b/src/prxref/jvm_lang.py
new file mode 100644
index 0000000..b885db5
--- /dev/null
+++ b/src/prxref/jvm_lang.py
@@ -0,0 +1,302 @@
+"""Java and Kotlin language facts for JVM chunk context (#20).
+
+A stdlib-only leaf module: it imports nothing from ``prxref``, so
+``chunk_context`` and ``repo_context`` can both build on it without an import
+cycle. It holds:
+
+- :func:`jvm_language`, which maps ``.java`` to ``"java"`` and ``.kt`` and
+  ``.kts`` to ``"kotlin"``;
+- the definition regexes of each language, in the order a caller tries them
+  (:data:`JAVA_DEFINITION_REGEXES`, :data:`KOTLIN_DEFINITION_REGEXES`). The
+  first regex that matches a line decides it, and group 1 of a match is the
+  defined name;
+- the keyword sets (:data:`JAVA_KEYWORDS`, :data:`KOTLIN_KEYWORDS`) that keep
+  ``public``, ``new``, ``return``, ``override`` and the like out of referenced
+  names, and :data:`JDK_NAMES`, common ``java.*`` types a repository never
+  defines;
+- import parsing (:func:`parse_import`, :func:`parse_imports`) for plain,
+  ``static``, wildcard and Kotlin ``as`` imports of ANY package, returned as
+  :class:`JvmImport`;
+- :func:`annotation_start`, the lookback that lets a definition entry begin at
+  the ``@X`` lines directly above it.
+
+:data:`JAVA_TYPE_RE` matches type declarations only (``class``, ``interface``,
+``record``, ``enum``, ``@interface``). :data:`JAVA_METHOD_RE` matches a method
+with a return type, so a constructor is left to its class's type declaration.
+:data:`JAVA_FIELD_RE` matches a declaration ending in ``=`` or ``;``, which a
+local variable also is; ``var`` locals are excluded because ``var`` cannot
+declare a field. :data:`JAVA_ENUM_CONSTANT_RE` matches an upper-case name,
+optionally with arguments or a body, followed by ``,``, ``;``, ``{`` or the end
+of the line; an upper-case constant alone on an argument or array-initializer
+line matches it too. The Kotlin regexes are led by ``class``, ``interface``,
+``object``, ``typealias``, ``fun``, ``val`` or ``var``, so a nameless
+``companion object`` matches none of them.
+
+Every regex works on one line: a declaration split across lines is recognised
+on its first line only, and a comment or string that spans lines is not known
+to be one.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+MAX_ANNOTATION_LINES = 2
+
+JAVA_TYPE_RE = re.compile(
+    r"^\s*(?:(?:@(?!interface\b)[A-Za-z_$][\w$.]*(?:\((?:[^()]|\([^()]*\))*\))?"
+    r"|public|protected|private|static|final|abstract|sealed|non-sealed|strictfp)\s+)*"
+    r"(?:class|interface|record|enum|@interface)\s+([A-Za-z_$][A-Za-z0-9_$]*)"
+)
+
+JAVA_KEYWORDS = frozenset({
+    "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char",
+    "class", "const", "continue", "default", "do", "double", "else", "enum",
+    "exports", "extends", "false", "final", "finally", "float", "for", "goto",
+    "if", "implements", "import", "instanceof", "int", "interface", "long",
+    "module", "native", "new", "non", "null", "open", "opens", "package",
+    "permits", "private", "protected", "provides", "public", "record",
+    "requires", "return", "sealed", "short", "static", "strictfp", "super",
+    "switch", "synchronized", "this", "throw", "throws", "to", "transient",
+    "transitive", "true", "try", "uses", "var", "void", "volatile", "when",
+    "while", "with", "yield",
+})
+
+JDK_NAMES = frozenset({
+    "AbstractMap", "ArithmeticException", "ArrayDeque", "ArrayIndexOutOfBoundsException",
+    "ArrayList", "Arrays", "AssertionError", "AtomicBoolean", "AtomicInteger",
+    "AtomicLong", "AtomicReference", "AutoCloseable", "Base64", "BigDecimal",
+    "BigInteger", "BiConsumer", "BiFunction", "BinaryOperator", "BiPredicate",
+    "Boolean", "Byte", "Callable", "CharSequence", "Character", "Charset",
+    "ChronoUnit", "Class", "ClassCastException", "Clock", "Cloneable",
+    "Collection", "Collections", "Collectors", "Comparable", "Comparator",
+    "CompletableFuture", "CompletionStage", "ConcurrentHashMap", "ConcurrentMap",
+    "Consumer", "CountDownLatch", "Date", "DateTimeFormatter", "Deprecated",
+    "Deque", "Double", "Duration", "Enum", "Error", "Exception", "ExecutorService",
+    "Executors", "File", "Files", "Float", "Function", "FunctionalInterface",
+    "Future", "HashMap", "HashSet", "IllegalArgumentException",
+    "IllegalStateException", "IndexOutOfBoundsException", "InputStream", "Instant",
+    "IntStream", "Integer", "InterruptedException", "IOException", "Iterable",
+    "Iterator", "LinkedHashMap", "LinkedHashSet", "LinkedList", "List",
+    "LocalDate", "LocalDateTime", "LocalTime", "Locale", "Long", "LongStream",
+    "Map", "Matcher", "Math", "NoSuchElementException", "NullPointerException",
+    "Number", "NumberFormatException", "Object", "Objects", "OffsetDateTime",
+    "Optional", "OptionalDouble", "OptionalInt", "OptionalLong", "OutputStream",
+    "Override", "Path", "Paths", "Pattern", "Period", "Predicate", "PriorityQueue",
+    "Queue", "Random", "Reader", "Record", "ReentrantLock", "Runnable", "Runtime",
+    "RuntimeException", "SafeVarargs", "Set", "Short", "SortedMap", "SortedSet",
+    "StandardCharsets", "Stream", "String", "StringBuilder", "StringJoiner",
+    "Supplier", "SuppressWarnings", "System", "Thread", "ThreadLocal", "Throwable",
+    "TimeUnit", "TreeMap", "TreeSet", "UUID", "UnaryOperator",
+    "UncheckedIOException", "UnsupportedOperationException", "URI", "URL", "Void",
+    "Writer", "ZoneId", "ZoneOffset", "ZonedDateTime",
+})
+
+KOTLIN_KEYWORDS = frozenset({
+    "abstract", "actual", "annotation", "as", "break", "by", "catch", "class",
+    "companion", "const", "constructor", "continue", "crossinline", "data",
+    "delegate", "do", "dynamic", "else", "enum", "expect", "external", "false",
+    "field", "file", "final", "finally", "for", "fun", "get", "if", "import",
+    "in", "infix", "init", "inline", "inner", "interface", "internal", "is",
+    "it", "lateinit", "noinline", "null", "object", "open", "operator", "out",
+    "override", "package", "param", "private", "property", "protected",
+    "public", "receiver", "reified", "return", "sealed", "set", "setparam",
+    "super", "suspend", "tailrec", "this", "throw", "true", "try", "typealias",
+    "typeof", "val", "value", "var", "vararg", "when", "where", "while",
+})
+
+_JAVA_PRIMITIVES = frozenset({"boolean", "byte", "char", "double", "float", "int", "long", "short", "void"})
+
+_JAVA_RESERVED = frozenset({
+    "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char",
+    "class", "const", "continue", "default", "do", "double", "else", "enum",
+    "extends", "false", "final", "finally", "float", "for", "goto", "if",
+    "implements", "import", "instanceof", "int", "interface", "long", "native",
+    "new", "null", "package", "private", "protected", "public", "return",
+    "short", "static", "strictfp", "super", "switch", "synchronized", "this",
+    "throw", "throws", "transient", "true", "try", "void", "volatile", "while",
+})
+
+_JAVA_MODIFIERS = (
+    "public", "protected", "private", "static", "final", "abstract", "sealed", "non-sealed",
+    "strictfp", "default", "synchronized", "native", "transient", "volatile",
+)
+
+_KOTLIN_MODIFIERS = (
+    "public", "private", "protected", "internal", "open", "final", "abstract", "sealed",
+    "override", "data", "enum", "annotation", "inner", "value", "companion", "const",
+    "lateinit", "inline", "suspend", "operator", "infix", "tailrec", "external", "expect",
+    "actual",
+)
+
+
+def _none_of(words: Iterable[str]) -> str:
+    return r"(?!(?:" + "|".join(re.escape(w) for w in sorted(words)) + r")(?![\w$]))"
+
+
+_GENERIC = r"<(?:[^<>;=(){}]|<(?:[^<>;=(){}]|<[^<>;=(){}]*>)*>)*>"
+_PARENS = r"\((?:[^()]|\([^()]*\))*\)"
+
+_JAVA_IDENT = r"[A-Za-z_$][\w$]*"
+_JAVA_ANNOTATION = r"@(?!interface\b)[A-Za-z_$][\w$.]*(?:" + _PARENS + r")?"
+_JAVA_PREFIX = r"^\s*(?:(?:" + _JAVA_ANNOTATION + "|" + "|".join(_JAVA_MODIFIERS) + r")\s+)*"
+_JAVA_TYPE = (
+    _JAVA_IDENT + r"(?:" + _GENERIC + r")?"
+    r"(?:\." + _JAVA_IDENT + r"(?:" + _GENERIC + r")?)*"
+    r"(?:\s*\[\s*\])*"
+)
+_JAVA_TYPED_NAME = (
+    _none_of(JAVA_KEYWORDS - _JAVA_PRIMITIVES) + _JAVA_TYPE + r"\s+"
+    + _none_of(_JAVA_RESERVED) + r"(" + _JAVA_IDENT + r")"
+)
+
+JAVA_METHOD_RE = re.compile(_JAVA_PREFIX + r"(?:" + _GENERIC + r"\s*)?" + _JAVA_TYPED_NAME + r"\s*\(")
+
+JAVA_FIELD_RE = re.compile(_JAVA_PREFIX + _JAVA_TYPED_NAME + r"\s*(?:\[\s*\]\s*)*(?:=(?!=)|;)")
+
+JAVA_ENUM_CONSTANT_RE = re.compile(
+    r"^\s*(?:" + _JAVA_ANNOTATION + r"\s+)*([A-Z][A-Z0-9_]*)(?![\w$])\s*"
+    r"(?:" + _PARENS + r"|\([^()]*$)?\s*(?:[,;{]|//|/\*|$)"
+)
+
+JAVA_DEFINITION_REGEXES = (JAVA_TYPE_RE, JAVA_METHOD_RE, JAVA_FIELD_RE, JAVA_ENUM_CONSTANT_RE)
+
+_KOTLIN_IDENT = r"[A-Za-z_][A-Za-z0-9_]*"
+_KOTLIN_ANNOTATION = r"@(?:[A-Za-z]+:)?[A-Za-z_][\w.]*(?:" + _PARENS + r")?"
+_KOTLIN_PREFIX = r"^\s*(?:(?:" + _KOTLIN_ANNOTATION + "|" + "|".join(_KOTLIN_MODIFIERS) + r")\s+)*"
+_KOTLIN_RECEIVER = (
+    r"(?:" + _KOTLIN_IDENT + r"(?:" + _GENERIC + r")?"
+    r"(?:\." + _KOTLIN_IDENT + r"(?:" + _GENERIC + r")?)*\??\.)?"
+)
+
+KOTLIN_TYPE_RE = re.compile(
+    _KOTLIN_PREFIX + r"(?:fun\s+)?(?:class|interface|object|typealias)\s+(" + _KOTLIN_IDENT + r")"
+)
+
+KOTLIN_FUN_RE = re.compile(
+    _KOTLIN_PREFIX + r"fun\s+(?:" + _GENERIC + r"\s*)?" + _KOTLIN_RECEIVER
+    + r"(" + _KOTLIN_IDENT + r")\s*\("
+)
+
+KOTLIN_PROPERTY_RE = re.compile(
+    _KOTLIN_PREFIX + r"(?:val|var)\s+(?:" + _GENERIC + r"\s*)?" + _KOTLIN_RECEIVER
+    + r"(" + _KOTLIN_IDENT + r")(?![\w.])"
+)
+
+KOTLIN_DEFINITION_REGEXES = (KOTLIN_TYPE_RE, KOTLIN_FUN_RE, KOTLIN_PROPERTY_RE)
+
+_IMPORT_RE = re.compile(
+    r"^\s*import\s+(static\s+)?(" + _JAVA_IDENT + r"(?:\." + _JAVA_IDENT + r")*)(\.\*)?"
+    r"(?:\s+as\s+(" + _JAVA_IDENT + r"))?\s*;?\s*(?://.*|/\*.*)?$"
+)
+
+_ANNOTATION_LINE_RE = re.compile(
+    r"^\s*(?:@(?!interface\b)(?:[A-Za-z]+:)?[A-Za-z_$][\w$.]*(?:" + _PARENS + r")?\s*)+"
+    r"(?://.*|/\*.*)?$"
+)
+
+
+def jvm_language(path: str) -> str:
+    """``"java"`` for a ``.java`` path, ``"kotlin"`` for ``.kt`` or ``.kts``, else ``""``.
+
+    The suffix check ignores case, as ``repo_context.language_of`` does.
+    """
+    lower = path.lower()
+    if lower.endswith(".java"):
+        return "java"
+    if lower.endswith((".kt", ".kts")):
+        return "kotlin"
+    return ""
+
+
+def definition_regexes(language: str) -> tuple[re.Pattern[str], ...]:
+    """The definition regexes of ``language`` in the order to try them; ``()`` for a non-JVM language.
+
+    Java: types, methods, fields and constants, enum constants. Kotlin: types
+    (``class`` in every flavour, ``interface``, ``object``, ``typealias``),
+    ``fun``, then ``val``/``var``. Group 1 of a match is the defined name.
+    """
+    if language == "java":
+        return JAVA_DEFINITION_REGEXES
+    if language == "kotlin":
+        return KOTLIN_DEFINITION_REGEXES
+    return ()
+
+
+def keywords(language: str) -> frozenset[str]:
+    """The keyword set of ``language``; an empty set for a non-JVM language."""
+    if language == "java":
+        return JAVA_KEYWORDS
+    if language == "kotlin":
+        return KOTLIN_KEYWORDS
+    return frozenset()
+
+
+@dataclass(frozen=True)
+class JvmImport:
+    """One parsed ``import`` line of a Java or Kotlin file.
+
+    ``name`` is the qualified name as written: a type (``a.b.C``), a static
+    member (``a.b.C.m``), or, for a wildcard import, the package or type before
+    ``.*``. ``alias`` is the Kotlin ``as`` name, or ``""``.
+    """
+
+    name: str
+    alias: str = ""
+    static: bool = False
+    wildcard: bool = False
+
+    @property
+    def segments(self) -> tuple[str, ...]:
+        """``name`` split on ``.``."""
+        return tuple(self.name.split("."))
+
+
+def parse_import(line: str) -> JvmImport | None:
+    """Parse one Java or Kotlin ``import`` line; ``None`` when the line is not one.
+
+    Accepts ``import a.b.C;``, ``import static a.b.C.m;``, ``import a.b.*;``,
+    ``import static a.b.C.*;``, the Kotlin forms without the semicolon, and
+    Kotlin ``import a.b.C as D``. Any package qualifies, not only the JDK's; a
+    trailing comment is allowed.
+    """
+    match = _IMPORT_RE.match(line)
+    if not match:
+        return None
+    return JvmImport(
+        name=match.group(2),
+        alias=match.group(4) or "",
+        static=bool(match.group(1)),
+        wildcard=bool(match.group(3)),
+    )
+
+
+def parse_imports(lines: Iterable[str]) -> list[JvmImport]:
+    """Every import among ``lines``, in order, one :class:`JvmImport` per import line."""
+    out: list[JvmImport] = []
+    for line in lines:
+        parsed = parse_import(line)
+        if parsed is not None:
+            out.append(parsed)
+    return out
+
+
+def annotation_start(lines: Sequence[str], index: int, *, max_annotations: int = MAX_ANNOTATION_LINES) -> int:
+    """The index a definition entry starts at: its first directly preceding annotation line.
+
+    Walks up from ``lines[index]`` over at most ``max_annotations`` contiguous
+    lines that hold only annotations (``@X``, ``@X(...)``, a Kotlin use-site
+    target such as ``@field:X``, several on one line, an optional trailing
+    comment) and returns the index of the topmost one. A blank line, a comment
+    or any other line stops the walk, and ``@interface`` is a declaration, not
+    an annotation. Returns ``index`` when nothing qualifies.
+    """
+    start = index
+    cursor = index - 1
+    while 0 <= cursor < len(lines) and index - cursor <= max_annotations:
+        if not _ANNOTATION_LINE_RE.match(lines[cursor]):
+            break
+        start = cursor
+        cursor -= 1
+    return start
diff --git a/tests/test_jvm_lang.py b/tests/test_jvm_lang.py
new file mode 100644
index 0000000..2de224c
--- /dev/null
+++ b/tests/test_jvm_lang.py
@@ -0,0 +1,620 @@
+"""Unit tests for :mod:`prxref.jvm_lang`, the Java and Kotlin facts behind #20.
+
+The module is a pure stdlib leaf, so these pin its definition regexes, word
+sets, import parsing and annotation lookback directly, over Spring and Kotlin
+snippets with placeholder names and without a forge, an LLM or a filesystem.
+"""
+from __future__ import annotations
+
+import ast
+import pathlib
+
+import pytest
+
+from prxref import jvm_lang, repo_context
+from prxref.jvm_lang import (
+    JAVA_DEFINITION_REGEXES,
+    JAVA_ENUM_CONSTANT_RE,
+    JAVA_FIELD_RE,
+    JAVA_KEYWORDS,
+    JAVA_METHOD_RE,
+    JAVA_TYPE_RE,
+    JDK_NAMES,
+    KOTLIN_DEFINITION_REGEXES,
+    KOTLIN_FUN_RE,
+    KOTLIN_KEYWORDS,
+    KOTLIN_PROPERTY_RE,
+    KOTLIN_TYPE_RE,
+    MAX_ANNOTATION_LINES,
+    JvmImport,
+    annotation_start,
+    definition_regexes,
+    jvm_language,
+    keywords,
+    parse_import,
+    parse_imports,
+)
+
+TYPE, METHOD, FIELD, ENUM_CONSTANT = range(4)
+KOTLIN_TYPE, KOTLIN_FUN, KOTLIN_PROPERTY = range(3)
+
+ALL_REGEXES = {
+    "java-type": JAVA_TYPE_RE,
+    "java-method": JAVA_METHOD_RE,
+    "java-field": JAVA_FIELD_RE,
+    "java-enum-constant": JAVA_ENUM_CONSTANT_RE,
+    "kotlin-type": KOTLIN_TYPE_RE,
+    "kotlin-fun": KOTLIN_FUN_RE,
+    "kotlin-property": KOTLIN_PROPERTY_RE,
+}
+
+HARD_NEGATIVES = [
+    " * must be set;",
+    "// int x;",
+    "import a.b.C;",
+    "package a.b;",
+    "return f(x);",
+    "new Foo(",
+    "} else if (x) {",
+    "throw new E(",
+    "a.b(c);",
+    "@RestController",
+    "}",
+    "",
+]
+
+
+def _first(line: str, language: str) -> tuple[int, str] | None:
+    for position, regex in enumerate(definition_regexes(language)):
+        match = regex.match(line)
+        if match:
+            return position, match.group(1)
+    return None
+
+
+def _scan(text: str, language: str) -> list[tuple[str, str, str]]:
+    lines = text.splitlines()
+    out = []
+    for index, line in enumerate(lines):
+        hit = _first(line, language)
+        if hit:
+            out.append((hit[1], line.strip(), lines[annotation_start(lines, index)].strip()))
+    return out
+
+
+class TestLeafModule:
+    def test_imports_only_the_standard_library(self):
+        tree = ast.parse(pathlib.Path(jvm_lang.__file__).read_text(encoding="utf-8"))
+        imported: set[str] = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom):
+                assert node.level == 0, "a relative import makes jvm_lang depend on prxref"
+                imported.add(node.module or "")
+            elif isinstance(node, ast.Import):
+                imported.update(alias.name for alias in node.names)
+        assert imported == {"__future__", "re", "collections.abc", "dataclasses"}
+
+
+class TestSharedWithRepoContext:
+    def test_type_regex_is_the_repo_context_pattern_byte_for_byte(self):
+        assert JAVA_TYPE_RE.pattern == repo_context._JAVA_DEF_RE.pattern
+        assert JAVA_TYPE_RE.flags == repo_context._JAVA_DEF_RE.flags
+
+    def test_keyword_set_equals_repo_context(self):
+        assert JAVA_KEYWORDS == repo_context._JAVA_KEYWORDS
+
+    def test_jdk_names_equal_repo_context(self):
+        assert JDK_NAMES == repo_context._JDK_NAMES
+
+    def test_reserved_words_are_all_keywords(self):
+        assert jvm_lang._JAVA_RESERVED <= JAVA_KEYWORDS
+
+
+class TestJvmLanguage:
+    @pytest.mark.parametrize("path, expected", [
+        ("src/main/java/com/acme/billing/InvoiceService.java", "java"),
+        ("Legacy.JAVA", "java"),
+        ("src/main/kotlin/com/acme/billing/Invoice.kt", "kotlin"),
+        ("build.gradle.kts", "kotlin"),
+        ("Script.KTS", "kotlin"),
+        ("build.gradle", ""),
+        ("pom.xml", ""),
+        ("Service.javax", ""),
+        ("notes.ktx", ""),
+        ("app/main.py", ""),
+        ("", ""),
+    ])
+    def test_suffix_decides(self, path, expected):
+        assert jvm_language(path) == expected
+
+
+class TestLanguageTables:
+    def test_java_regexes_in_the_order_a_caller_tries_them(self):
+        assert definition_regexes("java") == (JAVA_TYPE_RE, JAVA_METHOD_RE, JAVA_FIELD_RE, JAVA_ENUM_CONSTANT_RE)
+        assert definition_regexes("java") is JAVA_DEFINITION_REGEXES
+
+    def test_kotlin_regexes_in_the_order_a_caller_tries_them(self):
+        assert definition_regexes("kotlin") == (KOTLIN_TYPE_RE, KOTLIN_FUN_RE, KOTLIN_PROPERTY_RE)
+        assert definition_regexes("kotlin") is KOTLIN_DEFINITION_REGEXES
+
+    @pytest.mark.parametrize("language", ["js", "python", "go", "rust", "", "scala"])
+    def test_other_languages_get_nothing(self, language):
+        assert definition_regexes(language) == ()
+        assert keywords(language) == frozenset()
+
+    def test_keywords_by_language(self):
+        assert keywords("java") is JAVA_KEYWORDS
+        assert keywords("kotlin") is KOTLIN_KEYWORDS
+
+    def test_java_keywords_cover_modifiers_and_statements(self):
+        assert {"public", "final", "new", "return", "static", "throws", "var"} <= JAVA_KEYWORDS
+
+    def test_kotlin_keywords_cover_hard_soft_and_modifier_words(self):
+        assert {
+            "public", "final", "return", "override", "fun", "val", "var", "when",
+            "object", "typealias", "suspend", "data", "sealed", "lateinit", "by", "it",
+        } <= KOTLIN_KEYWORDS
+
+    def test_every_group_one_is_the_defined_name(self):
+        for regex in JAVA_DEFINITION_REGEXES + KOTLIN_DEFINITION_REGEXES:
+            assert regex.groups == 1
+
+
+class TestHardNegatives:
+    @pytest.mark.parametrize("line", HARD_NEGATIVES, ids=[repr(line) for line in HARD_NEGATIVES])
+    @pytest.mark.parametrize("regex_id", list(ALL_REGEXES))
+    def test_no_definition_regex_matches(self, regex_id, line):
+        assert ALL_REGEXES[regex_id].match(line) is None
+
+
+class TestJavaMethods:
+    @pytest.mark.parametrize("line, name", [
+        ("public static <T extends Comparable<T>> List<T> sortAll(Collection<? extends T> items) {", "sortAll"),
+        ("@Override public String toString() {", "toString"),
+        ('@GetMapping("/{id}") public ResponseEntity<InvoiceDto> get(@PathVariable String id) {', "get"),
+        ("    protected abstract Map<String, List<Integer>> index(", "index"),
+        ("public String[] names() {", "names"),
+        ("default Optional<Invoice> find(String id) {", "find"),
+        ("private synchronized void flush() throws IOException {", "flush"),
+        ("void run();", "run"),
+        ("<T> T identity(T value) {", "identity"),
+        ("public java.util.List<Map.Entry<String, Integer>> entries() {", "entries"),
+        ('String value() default "";', "value"),
+    ])
+    def test_declarations_match_as_methods(self, line, name):
+        assert _first(line, "java") == (METHOD, name)
+
+    @pytest.mark.parametrize("line", [
+        "public InvoiceService(String ledgerId) {",
+        "public TransportConfig {",
+        "Collections.<String>emptyList();",
+        "invoiceRepository.save(invoice);",
+        'String label = String.format("%s", id);',
+    ])
+    def test_constructors_and_calls_are_not_methods(self, line):
+        assert JAVA_METHOD_RE.match(line) is None
+
+
+class TestJavaFields:
+    @pytest.mark.parametrize("line, name", [
+        ("private static final int MAX_RETRIES = 3;", "MAX_RETRIES"),
+        ('public static final String DEFAULT_URL = "https://example.com";', "DEFAULT_URL"),
+        ("private final Map<String, List<Invoice>> invoicesByCustomer = new HashMap<>();", "invoicesByCustomer"),
+        ("private static final Logger LOG = LoggerFactory.getLogger(InvoiceService.class);", "LOG"),
+        ("@Autowired private AcmeClient client;", "client"),
+        ("protected volatile boolean running;", "running"),
+        ("private final @Nullable String nickname;", "nickname"),
+        ("int[] counts = new int[4];", "counts"),
+        ("int counts[] = new int[4];", "counts"),
+        ('String PREFIX = "acme";', "PREFIX"),
+    ])
+    def test_declarations_match_as_fields(self, line, name):
+        assert _first(line, "java") == (FIELD, name)
+
+    def test_a_typed_local_matches_too(self):
+        assert _first("        boolean hasUrl = url != null;", "java") == (FIELD, "hasUrl")
+
+
+class TestJavaEnumConstants:
+    @pytest.mark.parametrize("line, name", [
+        ("    DRAFT,", "DRAFT"),
+        ('    ISSUED("issued", 2),', "ISSUED"),
+        ("    @Deprecated VOID,", "VOID"),
+        ("    PENDING {", "PENDING"),
+        ("    CLOSED;", "CLOSED"),
+        ("    LAST", "LAST"),
+        ('    REFUNDED("refunded",', "REFUNDED"),
+        ("    ARCHIVED, // kept for old rows", "ARCHIVED"),
+    ])
+    def test_list_entries_match(self, line, name):
+        assert _first(line, "java") == (ENUM_CONSTANT, name)
+
+    @pytest.mark.parametrize("line", [
+        "MAX_RETRIES = 3;",
+        'LOG.info("x");',
+        "FOO.bar(x);",
+        "Draft,",
+        "ACTIVE_state,",
+        "case DRAFT -> run(x);",
+    ])
+    def test_non_entries_do_not_match(self, line):
+        assert JAVA_ENUM_CONSTANT_RE.match(line) is None
+
+
+class TestJavaTypesComeFirst:
+    @pytest.mark.parametrize("line, name", [
+        ("public class InvoiceService {", "InvoiceService"),
+        ("public record Pair(String a, String b) {", "Pair"),
+        ("enum Status {", "Status"),
+        ("@interface Audited {", "Audited"),
+    ])
+    def test_type_declarations_are_types(self, line, name):
+        assert _first(line, "java") == (TYPE, name)
+
+
+class TestJavaStatementsAreNotDeclarations:
+    @pytest.mark.parametrize("line", [
+        "return x;",
+        "yield x;",
+        "throw e;",
+        "else if (x) {",
+        "else foo(x);",
+        "assert check(x);",
+        "super(x);",
+        "this.ledgerId = ledgerId;",
+        "x = y;",
+        "var x = load();",
+        "foo.bar = baz;",
+        "requires transitive a.b;",
+        "synchronized (lock) {",
+        "for (int i = 0; i < n; i++) {",
+        "} catch (IOException e) {",
+        "return new Invoice() {",
+        "import static java.util.Objects.requireNonNull;",
+        "/* int x; */",
+    ])
+    def test_no_java_regex_matches(self, line):
+        assert _first(line, "java") is None
+
+
+class TestKotlinDefinitions:
+    @pytest.mark.parametrize("line, name", [
+        ("class Invoice", "Invoice"),
+        ("data class Point(val x: Int, val y: Int)", "Point"),
+        ("sealed class Outcome<out T> {", "Outcome"),
+        ("enum class Status(val label: String) {", "Status"),
+        ("interface Ledger {", "Ledger"),
+        ("object Defaults {", "Defaults"),
+        ("internal object Registry", "Registry"),
+        ("companion object Factory {", "Factory"),
+        ("data object Empty", "Empty"),
+        ("fun interface Callback {", "Callback"),
+        ("@JvmInline value class InvoiceId(val raw: String)", "InvoiceId"),
+        ("annotation class Audited", "Audited"),
+        ("private abstract class Base", "Base"),
+        ("typealias Handler<T> = (T) -> Unit", "Handler"),
+        ("private typealias CustomerId = String", "CustomerId"),
+    ])
+    def test_types(self, line, name):
+        assert _first(line, "kotlin") == (KOTLIN_TYPE, name)
+
+    @pytest.mark.parametrize("line, name", [
+        ("fun total(x: Int): Int = x", "total"),
+        ("fun Invoice.isEmpty(): Boolean = lines.isEmpty()", "isEmpty"),
+        ("fun <T> List<T>.second(): T = this[1]", "second"),
+        ('fun String?.orBlank(): String = this ?: ""', "orBlank"),
+        ("override suspend fun post(invoice: Invoice): Outcome {", "post"),
+        ("@JvmStatic fun create() = InvoiceService()", "create"),
+        ("private inline fun <reified T> load(): T {", "load"),
+        ("infix fun Int.times(label: String) = label.repeat(this)", "times"),
+    ])
+    def test_functions(self, line, name):
+        assert _first(line, "kotlin") == (KOTLIN_FUN, name)
+
+    @pytest.mark.parametrize("line, name", [
+        ("val total = 3", "total"),
+        ("var owner: String? = null", "owner"),
+        ("const val MAX_LINES = 50", "MAX_LINES"),
+        ("lateinit var repository: InvoiceRepository", "repository"),
+        ("override val name: String", "name"),
+        ("private val cache by lazy { mutableMapOf<String, Int>() }", "cache"),
+        ('@field:JsonProperty("ledger_id") val ledgerId: String,', "ledgerId"),
+        ("val <T> List<T>.lastIndex: Int get() = size - 1", "lastIndex"),
+        ("val Invoice.lineCount: Int", "lineCount"),
+    ])
+    def test_properties(self, line, name):
+        assert _first(line, "kotlin") == (KOTLIN_PROPERTY, name)
+
+    @pytest.mark.parametrize("line", [
+        "companion object {",
+        "object : Runnable {",
+        'println("class Invoice")',
+        "invoice.value = 3",
+        "listOf(1, 2).map { it * 2 }",
+        "when (status) {",
+        "if (x) return",
+        "return result",
+        "val (first, second) = pair",
+        "fun(x: Int) = x",
+        "init {",
+        "constructor(id: String) : this()",
+        "super.onCreate(state)",
+        "import org.example.ledger.Ledger as Book",
+        "package com.acme.billing",
+    ])
+    def test_non_declarations_do_not_match(self, line):
+        assert _first(line, "kotlin") is None
+
+
+class TestImports:
+    @pytest.mark.parametrize("line, expected", [
+        ("import com.fasterxml.jackson.databind.ObjectMapper;",
+         JvmImport("com.fasterxml.jackson.databind.ObjectMapper")),
+        ("import static org.assertj.core.api.Assertions.assertThat;",
+         JvmImport("org.assertj.core.api.Assertions.assertThat", static=True)),
+        ("import org.springframework.web.bind.annotation.*;",
+         JvmImport("org.springframework.web.bind.annotation", wildcard=True)),
+        ("import static org.example.Limits.*;", JvmImport("org.example.Limits", static=True, wildcard=True)),
+        ("import javax.servlet.http.HttpServletRequest;", JvmImport("javax.servlet.http.HttpServletRequest")),
+        ("import java.util.List;", JvmImport("java.util.List")),
+        ("    import com.acme.billing.Invoice; // moved in 2.0", JvmImport("com.acme.billing.Invoice")),
+        ("import com.acme.billing.Invoice", JvmImport("com.acme.billing.Invoice")),
+        ("import kotlinx.coroutines.flow.Flow as EventFlow",
+         JvmImport("kotlinx.coroutines.flow.Flow", alias="EventFlow")),
+        ("import org.example.ledger.*", JvmImport("org.example.ledger", wildcard=True)),
+    ])
+    def test_forms(self, line, expected):
+        assert parse_import(line) == expected
+
+    @pytest.mark.parametrize("line", [
+        "package com.acme.billing;",
+        "// import com.acme.billing.Invoice;",
+        " * import com.acme.billing.Invoice;",
+        "importantThing();",
+        "import",
+        "import a.b.*.C;",
+        "import x from 'y';",
+        "from acme import billing",
+        "",
+    ])
+    def test_non_imports(self, line):
+        assert parse_import(line) is None
+
+    def test_parse_imports_keeps_order_and_skips_other_lines(self):
+        lines = [
+            "package com.acme.billing;",
+            "",
+            "import com.fasterxml.jackson.annotation.JsonProperty;",
+            "import static java.util.Objects.requireNonNull;",
+            "public class InvoiceService {",
+            "import org.example.ledger.*;",
+        ]
+        assert parse_imports(lines) == [
+            JvmImport("com.fasterxml.jackson.annotation.JsonProperty"),
+            JvmImport("java.util.Objects.requireNonNull", static=True),
+            JvmImport("org.example.ledger", wildcard=True),
+        ]
+
+    def test_parse_imports_accepts_a_one_shot_iterable(self):
+        assert parse_imports(iter(["import a.b.C;"])) == [JvmImport("a.b.C")]
+
+    def test_segments(self):
+        assert parse_import("import com.acme.billing.Invoice;").segments == ("com", "acme", "billing", "Invoice")
+
+
+class TestAnnotationStart:
+    def test_cap_is_two(self):
+        assert MAX_ANNOTATION_LINES == 2
+
+    def test_no_annotation_starts_at_the_definition(self):
+        lines = ["", "    private final String ledgerId;"]
+        assert annotation_start(lines, 1) == 1
+
+    def test_one_annotation(self):
+        lines = ['    @JsonProperty("ledger_id")', "    private final String ledgerId;"]
+        assert annotation_start(lines, 1) == 0
+
+    def test_two_annotations(self):
+        lines = ["    }", "    @Transactional", "    @Override", "    public void issue() {"]
+        assert annotation_start(lines, 3) == 1
+
+    def test_a_third_annotation_is_left_out(self):
+        lines = ["@Service", "@Validated", "@RequiredArgsConstructor", "public class InvoiceService {"]
+        assert annotation_start(lines, 3) == 1
+
+    def test_a_blank_line_stops_the_walk(self):
+        lines = ["@Service", "", "@Validated", "public class InvoiceService {"]
+        assert annotation_start(lines, 3) == 2
+
+    def test_a_javadoc_end_stops_the_walk(self):
+        lines = ["/**", " * Issues invoices.", " */", "@Service", "public class InvoiceService {"]
+        assert annotation_start(lines, 4) == 3
+
+    @pytest.mark.parametrize("annotation", [
+        '@Table(name = "invoice", indexes = @Index(columnList = "customer_id"))',
+        "@Id @GeneratedValue(strategy = GenerationType.IDENTITY)",
+        '@field:JsonProperty("ledger_id")',
+        "@Deprecated // replaced by issueAll",
+        "@org.springframework.lang.Nullable",
+    ])
+    def test_annotation_shapes(self, annotation):
+        assert annotation_start(["    " + annotation, "    private String field;"], 1) == 0
+
+    @pytest.mark.parametrize("above", [
+        "@interface Audited {",
+        "@Override public String toString() { return id; }",
+        "// @Deprecated",
+        "}",
+    ])
+    def test_non_annotation_lines_stop_the_walk(self, above):
+        assert annotation_start([above, "    private String field;"], 1) == 1
+
+    def test_index_zero(self):
+        assert annotation_start(["public class InvoiceService {"], 0) == 0
+
+    def test_max_annotations_is_a_keyword(self):
+        lines = ["@Service", "@Validated", "public class InvoiceService {"]
+        assert annotation_start(lines, 2, max_annotations=1) == 1
+        assert annotation_start(lines, 2, max_annotations=0) == 2
+
+
+SPRING_SERVICE = """\
+package com.acme.billing;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Issues invoices for the example ledger. The ledger id
+ * must be set;
+ */
+@Service
+public class InvoiceService {
+
+    public static final int MAX_LINES = 50;
+
+    @JsonProperty("ledger_id")
+    private final String ledgerId;
+
+    private final Map<String, List<Invoice>> invoicesByCustomer = new HashMap<>();
+
+    public InvoiceService(String ledgerId) {
+        this.ledgerId = requireNonNull(ledgerId);
+    }
+
+    @Transactional
+    @Override
+    public <T extends Invoice> List<T> issue(String customerId, List<T> drafts) {
+        if (drafts.size() > MAX_LINES) {
+            throw new IllegalArgumentException("too many lines");
+        }
+        // int x;
+        return drafts;
+    }
+
+    enum Status {
+        DRAFT("draft"),
+        ISSUED("issued"),
+        @Deprecated
+        VOID("void");
+
+        private final String label;
+
+        Status(String label) {
+            this.label = label;
+        }
+    }
+}
+"""
+
+KOTLIN_SERVICE = """\
+package com.acme.billing
+
+import com.fasterxml.jackson.annotation.JsonProperty
+import kotlinx.coroutines.flow.Flow as EventFlow
+import org.example.ledger.*
+
+typealias CustomerId = String
+
+const val MAX_LINES = 50
+
+@Serializable
+data class Invoice(
+    @field:JsonProperty("ledger_id")
+    val ledgerId: String,
+    var total: Long = 0,
+)
+
+sealed class Outcome {
+    object Pending : Outcome()
+    data class Failed(val reason: String) : Outcome()
+}
+
+interface Ledger {
+    suspend fun post(invoice: Invoice): Outcome
+}
+
+fun Invoice.isEmpty(): Boolean = total == 0L
+
+class InvoiceService(private val ledger: Ledger) : Ledger by ledger {
+    override suspend fun post(invoice: Invoice): Outcome {
+        val result = ledger.post(invoice)
+        return result
+    }
+
+    companion object {
+        @JvmStatic
+        fun create(ledger: Ledger) = InvoiceService(ledger)
+    }
+}
+"""
+
+
+class TestSnippets:
+    def test_spring_service_definitions_and_entry_starts(self):
+        assert _scan(SPRING_SERVICE, "java") == [
+            ("InvoiceService", "public class InvoiceService {", "@Service"),
+            ("MAX_LINES", "public static final int MAX_LINES = 50;", "public static final int MAX_LINES = 50;"),
+            ("ledgerId", "private final String ledgerId;", '@JsonProperty("ledger_id")'),
+            (
+                "invoicesByCustomer",
+                "private final Map<String, List<Invoice>> invoicesByCustomer = new HashMap<>();",
+                "private final Map<String, List<Invoice>> invoicesByCustomer = new HashMap<>();",
+            ),
+            (
+                "issue",
+                "public <T extends Invoice> List<T> issue(String customerId, List<T> drafts) {",
+                "@Transactional",
+            ),
+            ("Status", "enum Status {", "enum Status {"),
+            ("DRAFT", 'DRAFT("draft"),', 'DRAFT("draft"),'),
+            ("ISSUED", 'ISSUED("issued"),', 'ISSUED("issued"),'),
+            ("VOID", 'VOID("void");', "@Deprecated"),
+            ("label", "private final String label;", "private final String label;"),
+        ]
+
+    def test_spring_service_imports(self):
+        assert parse_imports(SPRING_SERVICE.splitlines()) == [
+            JvmImport("com.fasterxml.jackson.annotation.JsonProperty"),
+            JvmImport("org.springframework.stereotype.Service"),
+            JvmImport("org.springframework.transaction.annotation.Transactional"),
+            JvmImport("java.util.Objects.requireNonNull", static=True),
+        ]
+
+    def test_kotlin_service_definitions_and_entry_starts(self):
+        assert _scan(KOTLIN_SERVICE, "kotlin") == [
+            ("CustomerId", "typealias CustomerId = String", "typealias CustomerId = String"),
+            ("MAX_LINES", "const val MAX_LINES = 50", "const val MAX_LINES = 50"),
+            ("Invoice", "data class Invoice(", "@Serializable"),
+            ("ledgerId", "val ledgerId: String,", '@field:JsonProperty("ledger_id")'),
+            ("total", "var total: Long = 0,", "var total: Long = 0,"),
+            ("Outcome", "sealed class Outcome {", "sealed class Outcome {"),
+            ("Pending", "object Pending : Outcome()", "object Pending : Outcome()"),
+            ("Failed", "data class Failed(val reason: String) : Outcome()",
+             "data class Failed(val reason: String) : Outcome()"),
+            ("Ledger", "interface Ledger {", "interface Ledger {"),
+            ("post", "suspend fun post(invoice: Invoice): Outcome", "suspend fun post(invoice: Invoice): Outcome"),
+            ("isEmpty", "fun Invoice.isEmpty(): Boolean = total == 0L", "fun Invoice.isEmpty(): Boolean = total == 0L"),
+            (
+                "InvoiceService",
+                "class InvoiceService(private val ledger: Ledger) : Ledger by ledger {",
+                "class InvoiceService(private val ledger: Ledger) : Ledger by ledger {",
+            ),
+            (
+                "post",
+                "override suspend fun post(invoice: Invoice): Outcome {",
+                "override suspend fun post(invoice: Invoice): Outcome {",
+            ),
+            ("result", "val result = ledger.post(invoice)", "val result = ledger.post(invoice)"),
+            ("create", "fun create(ledger: Ledger) = InvoiceService(ledger)", "@JvmStatic"),
+        ]
+
+    def test_kotlin_service_imports(self):
+        assert parse_imports(KOTLIN_SERVICE.splitlines()) == [
+            JvmImport("com.fasterxml.jackson.annotation.JsonProperty"),
+            JvmImport("kotlinx.coroutines.flow.Flow", alias="EventFlow"),
+            JvmImport("org.example.ledger", wildcard=True),
+        ]

From 01d1391fbb1dee77baafe804663bd40550cae014 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:16:44 -0700
Subject: [PATCH 07/25] feat: find readers of the shared state a chunk writes
 (#22)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add prxref.repo_readers, a pure module that finds the unchanged code
reading state a PR's added lines write to. shared_state_keys takes the
keys from subscript stores (recv[k] = v) and write calls
(recv.append/add/insert/save/put/push/store/write/extend/update/setdefault),
resolving a bare alias such as data = run.root().data to its attribute.
A key the added lines bind to a NEW value (a literal, a constructor or
any call) is skipped as a local; a plain name or attribute chain on the
right side (self.table = table) binds existing state and keeps the key,
which the #22 fixture needs for both of its keys.

reader_matches finds .key, ["key"] and key.<method>( reads that are not
stores, and excerpts each from the enclosing definition down to the read
in at most 8 lines, eliding the middle of a longer span. reader_candidates
ranks same-language non-diff listing files by shared directory depth, and
reader_entries walks them under MAX_READER_SCAN = 24 read attempts and
MAX_READER_ENTRIES = 6 entries, both read at call time, returning reader /
shared-state ContextEntry values. Wiring into repo_unit and registering
the kind and reason in repo_context are separate changes.

On the #22 fixture the progress.py chunk yields the keys table and data,
and entries for history.py model_history (table.recent) and
state_store.py load (f["data"]).

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/repo_readers.py | 411 +++++++++++++++++++++++++
 tests/test_repo_readers.py | 603 +++++++++++++++++++++++++++++++++++++
 2 files changed, 1014 insertions(+)
 create mode 100644 src/prxref/repo_readers.py
 create mode 100644 tests/test_repo_readers.py

diff --git a/src/prxref/repo_readers.py b/src/prxref/repo_readers.py
new file mode 100644
index 0000000..3e144e7
--- /dev/null
+++ b/src/prxref/repo_readers.py
@@ -0,0 +1,411 @@
+"""Readers of the shared state a chunk's added lines write to (#22).
+
+A PR can break code it never touches by writing something new into state that
+unchanged code reads: an object put into a scratch map that is later
+serialized, or a row appended to a table that another function reads with a
+row limit. The definitions context cannot find that code, because the diff
+never names it. This module finds it with a plain text search: it takes the
+keys the added lines WRITE, then looks in other files of the same language for
+lines that READ those keys, and returns short excerpts of the functions around
+them as :class:`prxref.repo_context.ContextEntry` values of kind ``"reader"``
+and reason ``"shared-state"``.
+
+Writes, found on a chunk file's added lines by :func:`shared_state_keys`:
+
+- a subscript store, ``<recv>[k] = v`` (also ``+=`` and the other augmented
+  assignments, and chained subscripts): the key is ``recv``, the last
+  identifier before the ``[``, so ``run.root().data[k] = v`` and
+  ``self.cache[k] = v`` give ``data`` and ``cache``;
+- a write call, ``<recv>.<verb>(`` with a verb from :data:`WRITE_VERBS`: the
+  key is the last segment of the receiver, so ``self.table.append(m)`` gives
+  ``table``; a receiver that is ``self``, ``this``, ``super`` or ``cls`` itself
+  gives nothing.
+
+A bare receiver the added lines bind to an attribute (``data =
+run.root().data``) is an alias, and the key is the attribute it names. A key
+the added lines assign a NEW value (``items = []``, ``self.cache = {}``,
+``self._lines: list[str] = []``, ``List<X> xs = new ArrayList<>()``,
+``ledger = Ledger(turn)``) is skipped: that is a new local or field, not state
+that exists outside the hunk. An assignment whose right side is a plain
+reference, a name or an attribute chain (``self.table = table``, ``data =
+run.root().data``), binds existing state and does not skip the key.
+
+Reads, found in a file's text by :func:`reader_matches`, on any line that is
+not a comment or an import:
+
+- ``.key`` used other than as a store;
+- ``["key"]`` or ``['key']`` used other than as a store;
+- ``key.<method>(`` where the method is not a write verb.
+
+A store is not a read: ``.key = v``, ``.key[k] = v``, ``["key"] = v`` and
+``.key.append(...)`` are other writers.
+
+Each read becomes one excerpt running from the enclosing definition's line
+(the nearest preceding definition line that is less indented than the read)
+down to the read's line, at most :data:`MAX_READER_LINES` lines; a longer span
+keeps the definition line, an ellipsis line, and the lines just above the read.
+The definition lines are the language's
+:func:`prxref.repo_context.definition_regexes` plus function and method
+patterns for js, java, kotlin, go and rust.
+
+:func:`reader_entries` runs the whole search for one chunk. The caps
+:data:`MAX_READER_ENTRIES` and :data:`MAX_READER_SCAN` are module constants
+read at call time, so patching ``MAX_READER_ENTRIES = 0`` turns readers off
+with no read at all. There is no configuration key.
+
+The module is pure: stdlib plus the repository-context modules, no I/O except
+through the ``read`` callable the caller passes, and no network.
+"""
+from __future__ import annotations
+
+import posixpath
+import re
+from collections.abc import Callable, Collection, Iterable, Sequence
+
+from . import chunk_context, repo_resolve
+from .repo_context import ContextEntry, definition_regexes, language_of
+
+MAX_READER_ENTRIES = 6
+MAX_READER_SCAN = 24
+MAX_READER_LINES = 8
+
+WRITE_VERBS = (
+    "append", "add", "insert", "save", "put", "push", "store", "write", "extend", "update", "setdefault",
+)
+
+_IDENT = r"[A-Za-z_$][\w$]*"
+_VERBS = "|".join(WRITE_VERBS)
+_STORE = r"(?:\*\*|//|>>>|<<|>>|\?\?|\|\||&&|[-+*/%&|^])?=(?![=>])"
+_SUBSCRIPT = r"\[(?:[^\[\]\n]|\[[^\[\]\n]*\])*\]"
+_MEMBER = r"(?:\?|!!)?\."
+
+_SUBSCRIPT_STORE_RE = re.compile(rf"(?<![\w$])({_IDENT})(?:\s*{_SUBSCRIPT})+\s*{_STORE}")
+_VERB_CALL_RE = re.compile(rf"(?<![\w$])({_IDENT})\s*{_MEMBER}\s*(?:{_VERBS})\s*\(")
+_ASSIGN_RE = re.compile(
+    rf"(?<![\w$])(?P<owner>(?:self|this)\s*\.\s*)?(?P<name>{_IDENT})\s*(?::[^=()]*)?(?<![!<>=])=(?![=>])"
+)
+_REFERENCE_RE = re.compile(rf"{_IDENT}(?:\s*(?:\(\s*\))?\s*{_MEMBER}\s*{_IDENT})*")
+_IDENT_RE = re.compile(_IDENT)
+_DECLARATION_TAIL_RE = re.compile(r"[\w$>\]?]$")
+_TRAILING_COMMENT_RE = re.compile(r"\s+(?:#|//)")
+_STORE_AFTER_RE = re.compile(
+    rf"(?:\s*{_SUBSCRIPT})*(?:\s*:[^=()\[\]]*)?\s*(?:{_STORE}|{_MEMBER}\s*(?:{_VERBS})\s*\()"
+)
+_SKIPPED_LINE_RE = re.compile(r"^\s*(?:#|//|/\*|\*|(?:import|from|package)\b)")
+_COMMENT_LINE_RE = re.compile(r"^\s*(?:#|//|/\*|\*)")
+
+_RECEIVER_KEYWORDS = frozenset({"self", "this", "super", "cls"})
+_LITERALS = frozenset({"True", "False", "None", "true", "false", "null", "nil", "undefined", "NaN"})
+
+_JS_DEFINITIONS = (
+    re.compile(r"^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\b"),
+    re.compile(r"^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\b"),
+    re.compile(
+        rf"^\s*(?:export\s+)?(?:const|let|var)\s+{_IDENT}\s*(?::[^=]*)?=\s*(?:async\s+)?"
+        rf"(?:function\b|(?:\([^)]*\)|{_IDENT})\s*(?::[^=]*)?=>)"
+    ),
+    re.compile(
+        r"^\s*(?:(?:public|private|protected|static|async|readonly|override|abstract|get|set)\s+)*\*?\s*"
+        r"(?!(?:if|for|while|switch|catch|with|return|function|new|typeof|await|yield|else|do|super|this)\b)"
+        rf"{_IDENT}\s*(?:<[^>]*>)?\s*\([^)]*\)\s*(?::\s*[^={{;]+)?\{{\s*$"
+    ),
+)
+_JAVA_METHOD = re.compile(
+    r"^\s*(?:@[\w$.]+(?:\([^)]*\))?\s+)*"
+    r"(?:(?:public|protected|private|static|final|abstract|synchronized|native|default|strictfp)\s+)*"
+    r"(?:<[^>]*>\s+)?"
+    r"(?!(?:return|new|throw|else|case|if|for|while|switch|catch|try|do|yield|assert)\b)"
+    rf"[\w$.<>\[\],? ]+?\s+{_IDENT}\s*\([^;=]*$"
+)
+_KOTLIN_DEFINITION = re.compile(
+    r"^\s*(?:@[\w$.]+(?:\([^)]*\))?\s+)*(?:[a-z]+\s+)*(?:fun|class|interface|object)\b"
+)
+_GO_DEFINITION = re.compile(r"^(?:func|type)\b")
+_RUST_DEFINITION = re.compile(
+    r'^\s*(?:pub(?:\([^)]*\))?\s+)?(?:(?:async|const|unsafe|extern(?:\s+"[^"]*")?)\s+)*'
+    r"(?:fn|struct|enum|trait|impl|mod)\b"
+)
+_EXTRA_DEFINITIONS: dict[str, tuple[re.Pattern[str], ...]] = {
+    "js": _JS_DEFINITIONS,
+    "java": (_JAVA_METHOD,),
+    "kotlin": (_KOTLIN_DEFINITION,),
+    "go": (_GO_DEFINITION,),
+    "rust": (_RUST_DEFINITION,),
+}
+
+
+def _statement_start(prefix: str) -> bool:
+    if not prefix.strip():
+        return True
+    return prefix[-1].isspace() and _DECLARATION_TAIL_RE.search(prefix.rstrip()) is not None
+
+
+def _right_side(rest: str) -> str:
+    value = _TRAILING_COMMENT_RE.split(rest.split(";", 1)[0], maxsplit=1)[0]
+    return value.strip().rstrip(",").strip()
+
+
+def _is_reference(value: str) -> bool:
+    return value not in _LITERALS and _REFERENCE_RE.fullmatch(value) is not None
+
+
+def _bindings(lines: Iterable[str]) -> tuple[set[str], dict[str, str]]:
+    fresh: set[str] = set()
+    aliases: dict[str, str] = {}
+    for text in lines:
+        for match in _ASSIGN_RE.finditer(text):
+            if not _statement_start(text[: match.start()]):
+                continue
+            name = match.group("name")
+            value = _right_side(text[match.end():])
+            if not _is_reference(value):
+                fresh.add(name)
+            elif match.group("owner") is None:
+                aliases.setdefault(name, _IDENT_RE.findall(value)[-1])
+    return fresh, aliases
+
+
+def _write_key(text: str, start: int, name: str, aliases: dict[str, str]) -> str | None:
+    if name in _RECEIVER_KEYWORDS:
+        return None
+    before = text[:start].rstrip()
+    if before.endswith("."):
+        return name
+    return aliases.get(name, name)
+
+
+def shared_state_keys(added: Sequence[str]) -> list[str]:
+    """The shared-state keys the added lines write, in first-appearance order, deduplicated.
+
+    ``added`` holds the text of one chunk file's ``+`` lines. A key comes from
+    a subscript store (``recv[k] = v``, the key ``recv``) or a write call
+    (``recv.<verb>(`` with a verb from :data:`WRITE_VERBS`, the key the last
+    segment of ``recv``); a bare receiver the added lines alias to an
+    attribute (``data = run.root().data``) gives that attribute's name.
+    Comment and import lines are ignored, and so is a subscript on a type
+    annotation (``x: list[str] = []``). A key the added lines assign a new
+    value, anything but a plain name or attribute chain, is dropped.
+    """
+    lines = [text for text in added if not _SKIPPED_LINE_RE.match(text)]
+    fresh, aliases = _bindings(lines)
+    keys: dict[str, None] = {}
+    for text in lines:
+        found: list[tuple[int, str]] = []
+        for match in _SUBSCRIPT_STORE_RE.finditer(text):
+            if text[: match.start()].rstrip().endswith(":"):
+                continue
+            key = _write_key(text, match.start(), match.group(1), aliases)
+            if key:
+                found.append((match.start(), key))
+        for match in _VERB_CALL_RE.finditer(text):
+            key = _write_key(text, match.start(), match.group(1), aliases)
+            if key:
+                found.append((match.start(), key))
+        for _, key in sorted(found):
+            if key not in fresh:
+                keys.setdefault(key, None)
+    return list(keys)
+
+
+def _read_patterns(key: str) -> tuple[re.Pattern[str], re.Pattern[str], re.Pattern[str]]:
+    escaped = re.escape(key)
+    return (
+        re.compile(rf"(?<!\.)\.\s*{escaped}(?![\w$])"),
+        re.compile(rf"""\[\s*(['"]){escaped}\1\s*\]"""),
+        re.compile(rf"(?<![\w$.]){escaped}\s*{_MEMBER}\s*({_IDENT})\s*\("),
+    )
+
+
+def _reads(text: str, patterns: tuple[re.Pattern[str], re.Pattern[str], re.Pattern[str]]) -> bool:
+    attribute, subscript, receiver = patterns
+    for match in attribute.finditer(text):
+        if not _STORE_AFTER_RE.match(text, match.end()):
+            return True
+    for match in subscript.finditer(text):
+        if not _STORE_AFTER_RE.match(text, match.end()):
+            return True
+    return any(match.group(1) not in WRITE_VERBS for match in receiver.finditer(text))
+
+
+def _indent(text: str) -> int:
+    expanded = text.expandtabs(4)
+    return len(expanded) - len(expanded.lstrip())
+
+
+def _is_definition(text: str, language: str) -> bool:
+    if any(regex.match(text) for regex in _EXTRA_DEFINITIONS.get(language, ())):
+        return True
+    if language == "js" and text[:1].isspace():
+        return False
+    return any(regex.match(text) for regex in definition_regexes(language))
+
+
+def _start_index(lines: Sequence[str], index: int, language: str) -> int:
+    if _is_definition(lines[index], language):
+        return index
+    limit = _indent(lines[index])
+    for cursor in range(index - 1, -1, -1):
+        text = lines[cursor]
+        stripped = text.strip()
+        if not stripped or _COMMENT_LINE_RE.match(text):
+            continue
+        width = _indent(text)
+        if width < limit and _is_definition(text, language):
+            return cursor
+        if width == 0 and not stripped.startswith((")", "]", "@")):
+            return index
+    return index
+
+
+def _excerpt(lines: Sequence[str], start: int, index: int) -> str:
+    cap = max(MAX_READER_LINES, 3)
+    if index - start < cap:
+        chosen = list(lines[start:index + 1])
+    else:
+        tail = list(lines[index - cap + 3:index + 1])
+        indent = tail[0][: len(tail[0]) - len(tail[0].lstrip())]
+        chosen = [lines[start], f"{indent}\N{HORIZONTAL ELLIPSIS}", *tail]
+    return "\n".join(text.rstrip() for text in chosen)
+
+
+def reader_matches(text: str, keys: Sequence[str], *, language: str) -> list[tuple[str, int, str]]:
+    """``(key, line, excerpt)`` for each place ``text`` reads one of ``keys``.
+
+    ``text`` is one file's content and ``language`` its
+    :func:`prxref.repo_context.language_of`. A line reads a key through
+    ``.key``, ``["key"]``/``['key']`` or ``key.<method>(`` when that use is not
+    a store; comment and import lines never read. Each reading line gives an
+    excerpt from its enclosing definition's line down to the reading line, at
+    most :data:`MAX_READER_LINES` lines, and ``line`` is the excerpt's 1-based
+    first line. When the span is longer, the excerpt keeps the definition
+    line, then an indented horizontal ellipsis, then the lines ending at the
+    read. With no enclosing definition the excerpt is the reading line alone.
+    The first key found on a line names it; reads that share an excerpt start
+    keep the first. Results are in reading-line order. Returns ``[]`` when
+    ``text`` is empty or larger than ``chunk_context.MAX_FILE_BYTES`` in UTF-8,
+    or when no key is given.
+    """
+    wanted = [key for key in dict.fromkeys(keys) if key]
+    if not wanted or not text:
+        return []
+    if len(text.encode("utf-8", "ignore")) > chunk_context.MAX_FILE_BYTES:
+        return []
+    patterns = {key: _read_patterns(key) for key in wanted}
+    lines = text.splitlines()
+    starts: set[int] = set()
+    out: list[tuple[str, int, str]] = []
+    for index, line in enumerate(lines):
+        if _SKIPPED_LINE_RE.match(line):
+            continue
+        key = next((key for key in wanted if key in line and _reads(line, patterns[key])), None)
+        if key is None:
+            continue
+        start = _start_index(lines, index, language)
+        if start in starts:
+            continue
+        starts.add(start)
+        out.append((key, start + 1, _excerpt(lines, start, index)))
+    return out
+
+
+def reader_candidates(
+    changed: Sequence[str],
+    listing: Iterable[str],
+    *,
+    diff_paths: Collection[str] = (),
+) -> list[str]:
+    """The listing files that may read state the ``changed`` files write, best first.
+
+    A candidate has the :func:`prxref.repo_context.language_of` of at least
+    one changed file (never ``""``), and is neither a changed file nor in
+    ``diff_paths``. Candidates are ordered by how many leading directories
+    they share with the nearest changed file of their language, most first,
+    then by path, the order the repository resolver's name search uses.
+    """
+    by_language: dict[str, list[str]] = {}
+    for path in changed:
+        language = language_of(path)
+        if language:
+            by_language.setdefault(language, []).append(posixpath.dirname(path))
+    skipped = set(changed) | set(diff_paths)
+    ranked: dict[str, int] = {}
+    for path in listing:
+        directories = by_language.get(language_of(path))
+        if not directories or path in skipped or path in ranked:
+            continue
+        home = posixpath.dirname(path)
+        ranked[path] = max(repo_resolve._shared_depth(home, directory) for directory in directories)
+    return sorted(ranked, key=lambda path: (-ranked[path], path))
+
+
+def _excluded(exclude: Callable[[str], bool] | None, path: str) -> bool:
+    if exclude is None:
+        return False
+    try:
+        return bool(exclude(path))
+    except Exception:  # noqa: BLE001
+        return True
+
+
+def reader_entries(
+    files: Sequence[object],
+    *,
+    listing: Collection[str] | None,
+    read: Callable[[str], str | None] | None,
+    diff_paths: Collection[str] = (),
+    exclude: Callable[[str], bool] | None = None,
+) -> list[ContextEntry]:
+    """The ``reader`` / ``shared-state`` entries for one worker chunk.
+
+    ``files`` holds the chunk's files, duck-typed on ``path`` and ``added``
+    (the text of its ``+`` lines) like :class:`prxref.chunk_context.ChunkFile`.
+    ``listing`` is the repository's file paths, ``read`` the chunk's reader
+    (each call may cost a read; None or a non-string answer is skipped),
+    ``diff_paths`` every path the PR changes, and ``exclude(path)`` true marks
+    a path that must never be read (an ``exclude`` that raises counts as true).
+
+    Each file's :func:`shared_state_keys` are gathered per language. The
+    :func:`reader_candidates` of the files that have keys are walked in order;
+    an excluded candidate is skipped without a read, and every other one is
+    read once, at most :data:`MAX_READER_SCAN` reads in all. Each text read
+    goes through :func:`reader_matches` with the keys of its language, and
+    every match becomes a ``ContextEntry`` whose ``symbol`` is the key read,
+    ``kind`` ``"reader"`` and ``reason`` ``"shared-state"``. The walk stops
+    once :data:`MAX_READER_ENTRIES` entries are kept. Both caps are read when
+    the function runs; with either at zero, ``read`` None, no listing or no
+    key, the result is ``[]`` and nothing is read.
+    """
+    max_entries = MAX_READER_ENTRIES
+    max_scan = MAX_READER_SCAN
+    if read is None or not listing or max_entries <= 0 or max_scan <= 0:
+        return []
+    keys: dict[str, dict[str, None]] = {}
+    writers: list[str] = []
+    for changed in files:
+        path = getattr(changed, "path", "") or ""
+        language = language_of(path)
+        if not language:
+            continue
+        found = shared_state_keys(tuple(getattr(changed, "added", ()) or ()))
+        if found:
+            keys.setdefault(language, {}).update(dict.fromkeys(found))
+            writers.append(path)
+    if not writers:
+        return []
+    entries: list[ContextEntry] = []
+    scanned = 0
+    for path in reader_candidates(writers, listing, diff_paths=diff_paths):
+        if scanned >= max_scan or len(entries) >= max_entries:
+            break
+        if _excluded(exclude, path):
+            continue
+        scanned += 1
+        text = read(path)
+        if not isinstance(text, str):
+            continue
+        language = language_of(path)
+        for key, line, body in reader_matches(text, list(keys[language]), language=language):
+            entries.append(ContextEntry(path, line, key, "reader", "shared-state", body))
+            if len(entries) >= max_entries:
+                break
+    return entries
diff --git a/tests/test_repo_readers.py b/tests/test_repo_readers.py
new file mode 100644
index 0000000..a143226
--- /dev/null
+++ b/tests/test_repo_readers.py
@@ -0,0 +1,603 @@
+"""Tests for the shared-state reader search (issue #22, readers of state the PR writes).
+
+Covers :mod:`prxref.repo_readers`: the write forms and the added-assignment
+skip in ``shared_state_keys``, the read forms and the excerpt window in
+``reader_matches``, candidate ordering in ``reader_candidates``, and in
+``reader_entries`` the caps read at call time, the scan order and the paths
+never read. The last test runs the #22 fixture's shape over trimmed inline
+copies of its files. No test touches the network.
+"""
+from __future__ import annotations
+
+import pytest
+
+from prxref import chunk_context, repo_readers
+from prxref.chunk_context import ChunkFile
+from prxref.repo_readers import (
+    WRITE_VERBS,
+    reader_candidates,
+    reader_entries,
+    reader_matches,
+    shared_state_keys,
+)
+
+ELLIPSIS = "\N{HORIZONTAL ELLIPSIS}"
+
+
+class _Recording:
+    """A ``read(path)`` over a dict that records every path asked for, in call order."""
+
+    def __init__(self, files: dict[str, str]):
+        self.files = files
+        self.calls: list[str] = []
+
+    def __call__(self, path: str) -> str | None:
+        self.calls.append(path)
+        return self.files.get(path)
+
+
+def _writer(path: str, *added: str) -> ChunkFile:
+    return ChunkFile(path=path, added=added)
+
+
+@pytest.mark.parametrize(
+    ("line", "key"),
+    [
+        ("    run.root().data[LEDGER_KEY] = ledger", "data"),
+        ("self.cache[key] = value", "cache"),
+        ("self.counts[key] += 1", "counts"),
+        ("this.index[a][b] = v;", "index"),
+        ("registry[name] = handler", "registry"),
+    ],
+)
+def test_subscript_store_writes_the_receiver(line, key):
+    assert shared_state_keys([line]) == [key]
+
+
+def test_subscript_comparison_and_annotation_are_not_writes():
+    assert shared_state_keys([
+        "assert self.cache[k] == v",
+        "if run.data[k] != v:",
+        "frames: list[Frame] = field(default_factory=list)",
+    ]) == []
+
+
+def test_bare_subscript_store_resolves_an_alias_to_its_attribute():
+    assert shared_state_keys(["data = run.root().data", "data[LEDGER_KEY] = ledger"]) == ["data"]
+    assert shared_state_keys(["rows = self.table", "rows[0] = row"]) == ["table"]
+
+
+@pytest.mark.parametrize("verb", WRITE_VERBS)
+def test_every_write_verb_writes_the_last_receiver_segment(verb):
+    assert shared_state_keys([f"self.table.{verb}(row)"]) == ["table"]
+
+
+@pytest.mark.parametrize(
+    ("line", "key"),
+    [
+        ("this.items.push(item);", "items"),
+        ("app.state.cache.save(entry)", "cache"),
+        ("repo.store(entry)", "repo"),
+        ("self.queue?.put(job)", "queue"),
+    ],
+)
+def test_write_call_forms(line, key):
+    assert shared_state_keys([line]) == [key]
+
+
+def test_write_call_on_self_or_with_another_method_gives_nothing():
+    assert shared_state_keys([
+        "self.save(run)",
+        "this.add(x);",
+        "super.update(x)",
+        "self.table.recent(5)",
+        "rows.addAll(more)",
+        "self.table.appendix(row)",
+        "get_table().append(row)",
+    ]) == []
+
+
+@pytest.mark.parametrize(
+    "added",
+    [
+        ["items = []", "items.append(1)"],
+        ["self._lines: list[str] = []", "self._lines.append(line)"],
+        ["self.cache = {}", "self.cache[key] = value"],
+        ["List<String> names = new ArrayList<>();", "names.add(name);"],
+        ["const seen = new Set();", "seen.add(id);"],
+        ["ledger = Ledger(turn)", "ledger.save()"],
+        ["buffer = []  # scratch", "buffer.extend(rows)"],
+    ],
+)
+def test_added_assignment_of_a_new_value_skips_the_key(added):
+    assert shared_state_keys(added) == []
+
+
+@pytest.mark.parametrize(
+    ("added", "keys"),
+    [
+        (["self.table = table", "self.table.append(row)"], ["table"]),
+        (["data = run.root().data", "data[KEY] = ledger"], ["data"]),
+        (["this.store = store;", "this.store.put(k, v);"], ["store"]),
+        (["announce(table=[])", "table.append(row)"], ["table"]),
+    ],
+)
+def test_assignment_of_existing_state_keeps_the_key(added, keys):
+    assert shared_state_keys(added) == keys
+
+
+def test_comment_and_import_lines_write_nothing():
+    assert shared_state_keys([
+        "# self.cache[k] = v",
+        "// this.items.push(x)",
+        " * registry.add(handler)",
+        "from app.data import update",
+    ]) == []
+
+
+def test_keys_are_in_first_appearance_order_and_deduplicated():
+    assert shared_state_keys(["self.b.add(1)", "self.a[k] = 1; self.c.put(k)", "self.b.add(2)"]) == ["b", "a", "c"]
+
+
+@pytest.mark.parametrize(
+    ("body", "key"),
+    [
+        ("    return run.data", "data"),
+        ("    return run.data == {}", "data"),
+        ("    return self.data()", "data"),
+        ('    return raw["data"]', "data"),
+        ("    return raw['data']", "data"),
+        ("    return table.recent(5)", "table"),
+        ("    return self.table.recent(5)", "table"),
+        ("    return table?.recent(5)", "table"),
+    ],
+)
+def test_read_forms(body, key):
+    text = f"def reader(run, raw, table):\n{body}\n"
+    assert reader_matches(text, ["data", "table"], language="python") == [
+        (key, 1, f"def reader(run, raw, table):\n{body}")
+    ]
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        "    run.data = 1",
+        "    run.data += 1",
+        "    run.data[k] = v",
+        "    run.data.append(v)",
+        "    self.data: dict = {}",
+        '    raw["data"] = v',
+        '    raw["data"]["k"] = v',
+        '    raw["data"].update(v)',
+        "    table.append(row)",
+        "    self.table.save(row)",
+    ],
+)
+def test_a_store_is_not_a_read(body):
+    text = f"def writer(run, raw, table):\n{body}\n"
+    assert reader_matches(text, ["data", "table"], language="python") == []
+
+
+def test_reads_are_word_bounded_and_skip_comments_and_imports():
+    text = "\n".join([
+        "from app.data import loader",
+        "# reads self.data",
+        "def f(x, raw, message_table):",
+        "    a = MessageTable.recent(1)",
+        "    b = message_table.recent(1)",
+        "    c = x.database",
+        '    d = raw["data2"]',
+    ])
+    assert reader_matches(text, ["data", "table"], language="python") == []
+
+
+STORE = """\
+class StateStore:
+    def save(self, run):
+        self._blobs[run.session_id] = dump(run)
+
+    def load(self, session_id):
+        blob = self._blobs.get(session_id)
+        raw = parse(blob)
+        return [f["data"] for f in raw["frames"]]
+"""
+
+
+def test_excerpt_starts_at_the_enclosing_definition_not_a_sibling():
+    ((key, line, text),) = reader_matches(STORE, ["data"], language="python")
+    assert (key, line) == ("data", 5)
+    assert text.splitlines()[0] == "    def load(self, session_id):"
+    assert text.splitlines()[-1] == '        return [f["data"] for f in raw["frames"]]'
+    assert len(text.splitlines()) == 4
+
+
+def test_excerpt_of_exactly_the_line_cap_is_whole():
+    body = [f"    step{n} = {n}" for n in range(6)]
+    text = "\n".join(["def f(run):", *body, "    return run.data"])
+    ((_, line, excerpt),) = reader_matches(text, ["data"], language="python")
+    assert line == 1
+    assert excerpt.splitlines() == text.splitlines()
+    assert len(excerpt.splitlines()) == repo_readers.MAX_READER_LINES
+
+
+def test_long_excerpt_keeps_the_definition_line_and_elides_the_middle():
+    body = [f"    step{n} = {n}" for n in range(20)]
+    lines = ["def f(run):", *body, "    return run.data"]
+    ((_, line, excerpt),) = reader_matches("\n".join(lines), ["data"], language="python")
+    assert line == 1
+    got = excerpt.splitlines()
+    assert len(got) == repo_readers.MAX_READER_LINES
+    assert got[0] == "def f(run):"
+    assert got[1] == f"    {ELLIPSIS}"
+    assert got[2:] == lines[-6:]
+
+
+def test_line_cap_is_read_at_call_time(monkeypatch):
+    monkeypatch.setattr(repo_readers, "MAX_READER_LINES", 4)
+    lines = ["def f(run):", "    a = 1", "    b = 2", "    c = 3", "    return run.data"]
+    ((_, _, excerpt),) = reader_matches("\n".join(lines), ["data"], language="python")
+    assert excerpt.splitlines() == ["def f(run):", f"    {ELLIPSIS}", "    c = 3", "    return run.data"]
+
+
+def test_module_level_read_starts_at_the_reading_line():
+    text = "import os\n\nLIMIT = 3\nprint(cfg.data)\n\ndef helper():\n    pass\n\nif ready:\n    show(cfg.data)\n"
+    assert reader_matches(text, ["data"], language="python") == [
+        ("data", 4, "print(cfg.data)"),
+        ("data", 10, "    show(cfg.data)"),
+    ]
+
+
+def test_one_entry_per_enclosing_definition():
+    text = "def a(x):\n    one = x.data\n    two = x.data\n\ndef b(x):\n    return x.data\n"
+    assert [(line, text.splitlines()[0]) for _, line, text in reader_matches(text, ["data"], language="python")] == [
+        (1, "def a(x):"),
+        (5, "def b(x):"),
+    ]
+
+
+def test_java_method_is_the_enclosing_definition():
+    text = """\
+package com.acme.store;
+
+import com.acme.data.Loader;
+
+public class Store {
+    private final Map<String, Object> data = new HashMap<>();
+
+    @Override
+    public Object load(String key) {
+        if (key == null) {
+            return null;
+        }
+        return cache.data.get(key);
+    }
+}
+"""
+    ((key, line, excerpt),) = reader_matches(text, ["data"], language="java")
+    assert (key, line) == ("data", 9)
+    assert excerpt.splitlines()[0] == "    public Object load(String key) {"
+    assert excerpt.splitlines()[-1] == "        return cache.data.get(key);"
+
+
+def test_js_method_is_the_enclosing_definition_not_a_local_const():
+    text = """\
+export class Store {
+  load(id) {
+    const raw = JSON.parse(this.blobs.get(id));
+    if (raw) {
+      return raw["data"];
+    }
+  }
+}
+"""
+    ((_, line, excerpt),) = reader_matches(text, ["data"], language="js")
+    assert line == 2
+    assert excerpt.splitlines()[0] == "  load(id) {"
+
+
+def test_kotlin_and_go_functions_are_enclosing_definitions():
+    kotlin = "class Store {\n    fun load(id: String): Any? {\n        return frames.data[id]\n    }\n}\n"
+    assert [line for _, line, _ in reader_matches(kotlin, ["data"], language="kotlin")] == [2]
+    go = "package store\n\nfunc (s *Store) Load(id string) string {\n\tvalue := s.data[id]\n\treturn value\n}\n"
+    assert [line for _, line, _ in reader_matches(go, ["data"], language="go")] == [3]
+
+
+def test_oversized_or_empty_text_or_no_key_gives_nothing():
+    big = "def f(x):\n    return x.data\n" + "#" * (chunk_context.MAX_FILE_BYTES + 1)
+    assert reader_matches(big, ["data"], language="python") == []
+    assert reader_matches("", ["data"], language="python") == []
+    assert reader_matches("def f(x):\n    return x.data\n", [], language="python") == []
+
+
+def test_candidates_are_ordered_by_shared_depth_then_path():
+    listing = [
+        "other/c.py",
+        "svc/b.py",
+        "svc/app/z.py",
+        "svc/app/core/sub/b.py",
+        "svc/app/core/a.py",
+        "svc/app/core/writer.py",
+        "svc/app/core/x.js",
+        "svc/app/diffed.py",
+        "README.md",
+        "svc/app/core/a.py",
+    ]
+    assert reader_candidates(["svc/app/core/writer.py"], listing, diff_paths={"svc/app/diffed.py"}) == [
+        "svc/app/core/a.py",
+        "svc/app/core/sub/b.py",
+        "svc/app/z.py",
+        "svc/b.py",
+        "other/c.py",
+    ]
+
+
+def test_candidates_rank_against_the_nearest_changed_file_of_their_language():
+    listing = ["b/c/z.py", "a/w.py", "b/c/v.ts", "a/u.ts", "a/doc.md"]
+    assert reader_candidates(["a/x.py", "b/c/y.ts"], listing) == ["b/c/v.ts", "a/w.py", "a/u.ts", "b/c/z.py"]
+
+
+def _many(count: int, body: str) -> dict[str, str]:
+    return {f"pkg/m{n:02}.py": body for n in range(count)}
+
+
+WRITER = _writer("pkg/writer.py", "self.data[key] = value")
+READS = "def f(x):\n    return x.data\n"
+
+
+def test_entry_cap_stops_the_walk():
+    read = _Recording(_many(10, READS))
+    entries = reader_entries([WRITER], listing=set(read.files), read=read)
+    assert len(entries) == repo_readers.MAX_READER_ENTRIES == 6
+    assert read.calls == sorted(read.files)[:6]
+
+
+def test_entry_cap_is_read_at_call_time(monkeypatch):
+    monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 2)
+    read = _Recording(_many(10, READS))
+    assert len(reader_entries([WRITER], listing=set(read.files), read=read)) == 2
+    assert len(read.calls) == 2
+
+
+def test_entry_cap_patched_to_zero_gives_nothing_and_reads_nothing(monkeypatch):
+    monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+    read = _Recording(_many(10, READS))
+    assert reader_entries([WRITER], listing=set(read.files), read=read) == []
+    assert read.calls == []
+
+
+def test_scan_cap_bounds_read_attempts():
+    read = _Recording(_many(30, "VALUE = 1\n"))
+    assert reader_entries([WRITER], listing=set(read.files), read=read) == []
+    assert read.calls == sorted(read.files)[: repo_readers.MAX_READER_SCAN]
+    assert repo_readers.MAX_READER_SCAN == 24
+
+
+def test_scan_cap_counts_reads_that_answer_none(monkeypatch):
+    monkeypatch.setattr(repo_readers, "MAX_READER_SCAN", 3)
+    read = _Recording({})
+    listing = set(_many(30, ""))
+    assert reader_entries([WRITER], listing=listing, read=read) == []
+    assert read.calls == sorted(listing)[:3]
+
+
+def test_excluded_candidates_are_neither_read_nor_counted(monkeypatch):
+    monkeypatch.setattr(repo_readers, "MAX_READER_SCAN", 4)
+    read = _Recording(_many(12, "VALUE = 1\n"))
+
+    def exclude(path: str) -> bool:
+        return int(path[-5:-3]) % 2 == 0
+
+    reader_entries([WRITER], listing=set(read.files), read=read, exclude=exclude)
+    assert read.calls == ["pkg/m01.py", "pkg/m03.py", "pkg/m05.py", "pkg/m07.py"]
+
+
+def test_an_exclude_that_raises_excludes():
+    def exclude(path: str) -> bool:
+        raise RuntimeError(path)
+
+    read = _Recording(_many(3, READS))
+    assert reader_entries([WRITER], listing=set(read.files), read=read, exclude=exclude) == []
+    assert read.calls == []
+
+
+def test_diff_files_and_other_languages_are_never_read():
+    files = {
+        "pkg/changed.py": READS,
+        "pkg/view.ts": "function f(x) {\n  return x.data;\n}\n",
+        "pkg/reader.py": READS,
+    }
+    read = _Recording(files)
+    entries = reader_entries([WRITER], listing=set(files), read=read, diff_paths={"pkg/changed.py"})
+    assert read.calls == ["pkg/reader.py"]
+    assert [(e.path, e.line, e.symbol, e.kind, e.reason) for e in entries] == [
+        ("pkg/reader.py", 1, "data", "reader", "shared-state")
+    ]
+
+
+def test_nothing_is_read_without_a_reader_listing_or_key():
+    read = _Recording(_many(3, READS))
+    assert reader_entries([WRITER], listing=None, read=read) == []
+    assert reader_entries([WRITER], listing=set(), read=read) == []
+    assert reader_entries([WRITER], listing=set(read.files), read=None) == []
+    assert reader_entries([_writer("pkg/writer.py", "x = 1")], listing=set(read.files), read=read) == []
+    assert reader_entries([_writer("notes.md", "self.data[k] = v")], listing=set(read.files), read=read) == []
+    assert read.calls == []
+
+
+PROGRESS = '''\
+"""Progress notes: a short user-facing line announced before each step runs."""
+from assistant.features import enabled
+from assistant.messages import Message, MessageTable
+from assistant.session import Run
+
+LEDGER_KEY = "progress.ledger"
+
+
+class ProgressLedger:
+    def __init__(self, turn_id: str) -> None:
+        self._turn_id = turn_id
+        self._lines: list[str] = []
+
+    def record(self, line: str) -> bool:
+        key = line.strip().lower()
+        if any(shown.strip().lower() == key for shown in self._lines):
+            return False
+        self._lines.append(line)
+        return True
+
+
+class ProgressAnnouncer:
+    def __init__(self, table: MessageTable) -> None:
+        self.table = table
+        self.active = enabled("progress_notes", default=True)
+
+    def announce(self, run: Run, text: str) -> None:
+        if not self.active:
+            return
+        if self._ledger(run).record(text):
+            self.table.append(Message(run.session_id, "progress", text))
+
+    def _ledger(self, run: Run) -> ProgressLedger:
+        data = run.root().data
+        ledger = data.get(LEDGER_KEY)
+        if not isinstance(ledger, ProgressLedger) or ledger.turn_id() != run.turn_id:
+            ledger = ProgressLedger(run.turn_id)
+            data[LEDGER_KEY] = ledger
+        return ledger
+'''
+
+ENGINE = '''\
+class Engine:
+    def __init__(self, table: MessageTable, store: StateStore) -> None:
+        self.table = table
+        self.store = store
+
+    def run_turn(self, run: Run, steps: list[Step]) -> str | None:
+        for step in steps:
+            if step.kind == "handoff":
+                self.store.save(run)
+                return None
+            self.table.append(Message(run.session_id, "assistant", step.execute(run)))
+'''
+
+HISTORY = '''\
+"""Builds the model's conversation history from the message table."""
+from assistant.messages import MessageTable
+
+HISTORY_WINDOW = 20
+
+_MODEL_ROLES = {"user": "user", "assistant": "assistant", "tool": "tool"}
+
+
+def model_history(table: MessageTable, session_id: str) -> list[dict]:
+    history = []
+    for m in table.recent(session_id, HISTORY_WINDOW):
+        role = _MODEL_ROLES.get(m.role)
+        if role is None:
+            continue
+        history.append({"role": role, "content": m.text})
+    return history
+'''
+
+MESSAGES = '''\
+"""Append-only message table for a session."""
+
+
+class MessageTable:
+    def __init__(self) -> None:
+        self._rows: list[Message] = []
+
+    def append(self, message: Message) -> None:
+        self._rows.append(message)
+
+    def recent(self, session_id: str, limit: int) -> list[Message]:
+        rows = [m for m in self._rows if m.session_id == session_id]
+        return rows[-limit:]
+'''
+
+SESSION = '''\
+@dataclass
+class Frame:
+    agent_id: str
+    # Scratch space any engine component can use for per-frame bookkeeping.
+    data: dict[str, Any] = field(default_factory=dict)
+'''
+
+STATE_STORE = '''\
+"""Saves a run so it can resume after a human handoff."""
+import json
+from dataclasses import asdict
+
+from assistant.session import Frame, Run
+
+
+class StateStore:
+    def __init__(self) -> None:
+        self._blobs: dict[str, str] = {}
+
+    def save(self, run: Run) -> None:
+        self._blobs[run.session_id] = json.dumps(asdict(run))
+
+    def load(self, session_id: str) -> Run | None:
+        blob = self._blobs.get(session_id)
+        if blob is None:
+            return None
+        raw = json.loads(blob)
+        frames = [Frame(f["agent_id"], f["data"]) for f in raw["frames"]]
+        return Run(raw["session_id"], raw["turn_id"], frames)
+'''
+
+TEST_ENGINE = '''\
+def test_handoff_parks_and_resumes():
+    store = StateStore()
+    engine = Engine(MessageTable(), store)
+    run = make_run()
+    run.root().data["attempts"] = 1
+    assert engine.run_turn(run, [Step("handoff", "human", lambda r: "")]) is None
+    assert store.load("s1").root().data == {"attempts": 1}
+'''
+
+
+def test_issue_22_fixture_readers_of_the_ledger_map_and_the_message_table():
+    files = {
+        "README.md": "# assistant\n",
+        "assistant/__init__.py": "",
+        "assistant/engine.py": ENGINE,
+        "assistant/history.py": HISTORY,
+        "assistant/messages.py": MESSAGES,
+        "assistant/progress.py": PROGRESS,
+        "assistant/session.py": SESSION,
+        "assistant/state_store.py": STATE_STORE,
+        "tests/conftest.py": "",
+        "tests/test_engine.py": TEST_ENGINE,
+    }
+    diff_paths = {"assistant/engine.py", "assistant/progress.py", "tests/conftest.py", "README.md"}
+    assert shared_state_keys(PROGRESS.splitlines()) == ["table", "data"]
+    read = _Recording(files)
+    entries = reader_entries(
+        [_writer("assistant/progress.py", *PROGRESS.splitlines())],
+        listing=set(files),
+        read=read,
+        diff_paths=diff_paths,
+    )
+    assert read.calls == [
+        "assistant/__init__.py",
+        "assistant/history.py",
+        "assistant/messages.py",
+        "assistant/session.py",
+        "assistant/state_store.py",
+        "tests/test_engine.py",
+    ]
+    assert [(e.path, e.line, e.symbol) for e in entries] == [
+        ("assistant/history.py", 9, "table"),
+        ("assistant/state_store.py", 15, "data"),
+        ("tests/test_engine.py", 1, "data"),
+    ]
+    assert {(e.kind, e.reason) for e in entries} == {("reader", "shared-state")}
+    history, store, _ = entries
+    assert history.text.splitlines()[0].startswith("def model_history(")
+    assert history.text.splitlines()[-1] == "    for m in table.recent(session_id, HISTORY_WINDOW):"
+    assert store.text.splitlines()[0] == "    def load(self, session_id: str) -> Run | None:"
+    assert store.text.splitlines()[-1].endswith('f["data"]) for f in raw["frames"]]')
+    assert store.rendered().startswith("assistant/state_store.py:15:     def load(")

From b9d0bf2705308b3e31e58ea54c6ffb3c5e7efff0 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:25:28 -0700
Subject: [PATCH 08/25] feat: retry a judge reply the parser rejects (#21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

judge_case gains a keyword-only parse_retries (N, library default 0).
When parse_judge_response raises JudgeParseError, for any reason (empty,
not JSON, not an object, no grades list, or a grades row that is not an
object, has no human_id or has an unknown grade), the same request is
sent again while fewer than N retries have run, so a case makes at most
1 + N calls. A raised call and a cache hit are never retried. When every
attempt is rejected, the case fails with the last attempt's reason,
worded as before.

Every attempt's usage is folded into the outcome's unit through
reviewer._fold_retry_usage before costs.run_cost, so tokens, time and
cost cover all of them, and a retry that raises keeps the billed earlier
attempts. llm_calls is 1 plus the retries made, and JudgeOutcome gains
parse_retries (last field, default 0). Only the graded reply is cached.
With a trace on at N >= 1, each discarded reply lands in
judge.attempt<K>.response.json, and once a retry ran the meta adds
parse_retries and first_error. At N=0 nothing changes from 0.16.0.

tests/test_judge_parse_retry.py covers each of the parser's seven
rejection kinds, retries running out, N=0, raised calls, usage and cost,
cache hits and the trace files.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/eval_judge.py        | 182 ++++++++-----
 tests/test_judge_parse_retry.py | 468 ++++++++++++++++++++++++++++++++
 2 files changed, 587 insertions(+), 63 deletions(-)
 create mode 100644 tests/test_judge_parse_retry.py

diff --git a/src/prxref/eval_judge.py b/src/prxref/eval_judge.py
index 8407735..6e06346 100644
--- a/src/prxref/eval_judge.py
+++ b/src/prxref/eval_judge.py
@@ -8,11 +8,12 @@
    ``prxref.llm_backends.create_llm_client`` factory the CLI looks up at call
    time. The judge therefore shares the review's backend, base URL and key
    path, and one test stub keyed on ``cfg["llm_models"]`` serves both.
-2. :func:`judge_case` grades one case with at most one single-shot
-   ``json_mode`` call. A cached grading makes no call. A response that
-   :func:`prxref.judge.parse_judge_response` rejects, and any exception the
-   client raises, make the case a judge error (:attr:`JudgeOutcome.error`),
-   never a score of 0.
+2. :func:`judge_case` grades one case with one single-shot ``json_mode``
+   call, sent again unchanged up to ``parse_retries`` times while
+   :func:`prxref.judge.parse_judge_response` rejects the reply (#21). A
+   cached grading makes no call. A response still rejected when the retries
+   run out, and any exception the client raises, make the case a judge
+   error (:attr:`JudgeOutcome.error`), never a score of 0.
 3. The cache is one JSON file per :func:`prxref.judge.judge_cache_key` under
    a directory the caller chooses; :func:`judge_cache_dir` names the
    conventional one, ``<out>/<label>/judge-cache/``. An entry holds the raw
@@ -62,7 +63,7 @@
 )
 from .llm import ConfigError, LLMClient
 from .orchestrator import _sampling
-from .reviewer import _write_trace_files
+from .reviewer import _fold_retry_usage, _write_trace_files
 
 logger = logging.getLogger("prxref")
 
@@ -83,8 +84,8 @@ class JudgeOutcome:
     carries no grades, so it can never be read as a score of 0. ``error`` is
     ``None`` on success, otherwise a one-line reason. ``cached`` is true when
     the grades came from the cache, and ``llm_calls`` is the number of judge
-    requests this call made (0 for a cache hit or a case with no labels, 1
-    otherwise).
+    requests this call made (0 for a cache hit or a case with no labels,
+    otherwise 1 plus ``parse_retries``).
 
     ``ref_index`` maps each judge ref (``A1``, ``A2``, ...) to the index of
     its row in the run record's ``findings`` list as written, dropped rows
@@ -92,13 +93,20 @@ class JudgeOutcome:
     finding.
 
     ``model``, ``input_tokens``, ``output_tokens`` and ``elapsed_ms`` describe
-    the live call (``model`` is the name the backend reported; a cache hit
-    keeps the stored one, with zero tokens and time). ``cost_usd`` is this
-    call's cost: ``0.0`` when no request was made, ``None`` when it is unknown
+    the live calls: tokens and time cover every request, and ``model`` is the
+    name the backend reported for the last one (a cache hit keeps the stored
+    one, with zero tokens and time). ``cost_usd`` is the cost of every
+    request: ``0.0`` when no request was made, ``None`` when it is unknown
     (never ``0``), and ``cost_estimated`` is true when the price table
     supplied it. ``cost_source`` is the backend's reported source, ``""``
     unless a reported figure was used. ``unit`` is the cost unit
-    :func:`judge_cost` totals, or ``None`` when no request was made.
+    :func:`judge_cost` totals, with every request's usage folded in, or
+    ``None`` when no request was made.
+
+    ``parse_retries`` is the number of times :func:`judge_case` sent the same
+    request again because :func:`prxref.judge.parse_judge_response` rejected
+    the reply (#21): 0 for a cache hit, a case with no labels, a first reply
+    that parsed, and any call made with ``parse_retries=0``.
     """
 
     case_id: str
@@ -116,6 +124,7 @@ class JudgeOutcome:
     cost_estimated: bool = False
     cost_source: str = ""
     unit: dict[str, Any] | None = None
+    parse_retries: int = 0
 
     @property
     def ok(self) -> bool:
@@ -208,6 +217,7 @@ def judge_case(
     max_tokens: int = 4096,
     timeout_s: float | None = None,
     trace_dir: str = "",
+    parse_retries: int = 0,
 ) -> JudgeOutcome:
     """Grade one case's human findings against its run record's AI findings.
 
@@ -220,16 +230,32 @@ def judge_case(
     - A case with no labels has nothing to grade: empty grades, no call.
     - With ``cache_dir`` set, a valid entry for this case's cache key is used
       without a call; a corrupt one is a miss with a WARNING.
-    - Otherwise one ``client.invoke(system, user, json_mode=True)`` call is
-      made with ``max_tokens`` and ``timeout_s``. Any exception it raises,
-      and a response :func:`prxref.judge.parse_judge_response` rejects, is a
-      judge error with a WARNING; neither is cached. A graded response is
-      written to the cache atomically; a failed write is a WARNING and keeps
-      the grades.
+    - Otherwise ``client.invoke(system, user, json_mode=True)`` is called
+      with ``max_tokens`` and ``timeout_s``. A response
+      :func:`prxref.judge.parse_judge_response` rejects, for any reason, is
+      asked for again with the same request while fewer than
+      ``parse_retries`` (N, default 0) retries have run, so a case makes at
+      most ``1 + N`` calls; each retry logs one WARNING ending ``parse retry
+      <k> of <N>``. An exception the client raises is never retried. A
+      response still rejected when the retries run out, and any exception,
+      is a judge error with a WARNING, whose reason is the last call's;
+      neither is cached. Only the graded response is written to the cache,
+      atomically; a failed write is a WARNING and keeps the grades.
+    - Every call counts. Its tokens, time and reported cost are folded into
+      the outcome's ``unit`` (through
+      :func:`prxref.reviewer._fold_retry_usage`) before
+      :func:`prxref.costs.run_cost` prices it, ``model`` is the last call's,
+      ``llm_calls`` is ``1`` plus the retries made, and
+      :attr:`JudgeOutcome.parse_retries` counts them. At N=0 nothing is
+      retried, exactly as in 0.16.0.
     - ``price_table`` is the parsed ``PRXREF_PRICE_TABLE``; ``None`` or
       ``{}`` estimates nothing.
-    - A non-empty ``trace_dir`` receives the live call's prompt, response and
-      meta as ``judge.*`` files, as a review unit's trace does.
+    - A non-empty ``trace_dir`` receives the prompt, the last response and
+      the meta as ``judge.*`` files, as a review unit's trace does. At N of 1
+      or more, each rejected response that was retried is kept as
+      ``judge.attempt<K>.response.json`` (K from 1), and once a retry ran the
+      meta adds ``parse_retries`` and ``first_error``, the reason the first
+      response was rejected.
 
     A label without an id, or a repeated id, raises ``ValueError`` from
     :func:`prxref.judge.human_files`; the case loader refuses both first.
@@ -252,50 +278,52 @@ def judge_case(
             return JudgeOutcome(**base, grades=grades, error=None, cached=True, llm_calls=0, model=stored_model)
     system, user = split_judge_prompt(build_judge_prompt(case, ai))
     t0 = time.perf_counter()
-    try:
-        result = client.invoke(system, user, max_tokens=max_tokens, json_mode=True, timeout_s=timeout_s)
-    except Exception as exc:  # noqa: BLE001 - a failed judge call is a judge error, never a failed run
+    unit: dict[str, Any] = {"model": "", "input_tokens": 0, "output_tokens": 0, "cost_usd": None, "cost_source": ""}
+    attempts: list[str | None] | None = [] if parse_retries >= 1 else None
+    retries = 0
+    first_error = ""
+    while True:
+        try:
+            result = client.invoke(system, user, max_tokens=max_tokens, json_mode=True, timeout_s=timeout_s)
+        except Exception as exc:  # noqa: BLE001 - a failed judge call is a judge error, never a failed run
+            elapsed = _elapsed_ms(t0)
+            reason = f"judge call failed: {type(exc).__name__}: {exc}"
+            logger.warning("judge error for case %r: %s", case_id, reason)
+            trace_meta = {**_trace_meta(unit, elapsed, retries, first_error), "error": reason}
+            _write_trace_files(trace_dir, JUDGE_TRACE_LABEL, system, user, None, trace_meta, attempts=attempts)
+            return JudgeOutcome(**_live(base, unit, elapsed, retries, price_table), grades=None, error=reason)
         elapsed = _elapsed_ms(t0)
-        reason = f"judge call failed: {type(exc).__name__}: {exc}"
-        logger.warning("judge error for case %r: %s", case_id, reason)
-        unit = {"model": "", "input_tokens": 0, "output_tokens": 0, "cost_usd": None, "cost_source": ""}
-        trace_meta = {**unit, "elapsed_ms": elapsed, "error": reason}
-        _write_trace_files(trace_dir, JUDGE_TRACE_LABEL, system, user, None, trace_meta)
-        return JudgeOutcome(
-            **base, grades=None, error=reason, cached=False, llm_calls=1, elapsed_ms=elapsed,
-            cost_usd=None, unit=unit,
-        )
-    elapsed = _elapsed_ms(t0)
-    unit = {
-        "model": result.model,
-        "input_tokens": result.input_tokens,
-        "output_tokens": result.output_tokens,
-        "cost_usd": result.cost_usd,
-        "cost_source": result.cost_source,
-    }
-    cost_usd, cost_estimated, _unpriced = costs.run_cost([unit], price_table)
-    live = {
-        **base,
-        "cached": False,
-        "llm_calls": 1,
-        "model": result.model,
-        "input_tokens": result.input_tokens,
-        "output_tokens": result.output_tokens,
-        "elapsed_ms": elapsed,
-        "cost_usd": cost_usd,
-        "cost_estimated": cost_estimated,
-        "cost_source": result.cost_source if costs.valid_usd(result.cost_usd) is not None else "",
-        "unit": unit,
-    }
-    trace_meta = {**unit, "elapsed_ms": elapsed}
-    try:
-        grades = tuple(parse_judge_response(result.text, humans, ai_ref_files(ai)))
-    except JudgeParseError as exc:
-        reason = f"judge response rejected: {exc}"
-        logger.warning("judge error for case %r: %s", case_id, reason)
-        _write_trace_files(trace_dir, JUDGE_TRACE_LABEL, system, user, result.text, {**trace_meta, "error": reason})
-        return JudgeOutcome(**live, grades=None, error=reason)
-    _write_trace_files(trace_dir, JUDGE_TRACE_LABEL, system, user, result.text, trace_meta)
+        if retries:
+            _fold_retry_usage(unit, result)
+        else:
+            unit = {
+                "model": result.model,
+                "input_tokens": result.input_tokens,
+                "output_tokens": result.output_tokens,
+                "cost_usd": result.cost_usd,
+                "cost_source": result.cost_source,
+            }
+        try:
+            grades = tuple(parse_judge_response(result.text, humans, ai_ref_files(ai)))
+        except JudgeParseError as exc:
+            reason = f"judge response rejected: {exc}"
+            if attempts is not None and retries < parse_retries:
+                retries += 1
+                attempts.append(result.text)
+                first_error = first_error or reason
+                logger.warning(
+                    "judge for case %r: unusable reply (%s); parse retry %d of %d",
+                    case_id, exc, retries, parse_retries,
+                )
+                continue
+            logger.warning("judge error for case %r: %s", case_id, reason)
+            trace_meta = {**_trace_meta(unit, elapsed, retries, first_error), "error": reason}
+            _write_trace_files(trace_dir, JUDGE_TRACE_LABEL, system, user, result.text, trace_meta, attempts=attempts)
+            return JudgeOutcome(**_live(base, unit, elapsed, retries, price_table), grades=None, error=reason)
+        break
+    live = _live(base, unit, elapsed, retries, price_table)
+    trace_meta = _trace_meta(unit, elapsed, retries, first_error)
+    _write_trace_files(trace_dir, JUDGE_TRACE_LABEL, system, user, result.text, trace_meta, attempts=attempts)
     if entry_path is not None:
         _write_entry(entry_path, {
             "version": JUDGE_CACHE_VERSION,
@@ -347,6 +375,34 @@ def _elapsed_ms(t0: float) -> int:
     return int((time.perf_counter() - t0) * 1000)
 
 
+def _live(
+    base: Mapping[str, Any], unit: dict[str, Any], elapsed: int, retries: int, price_table: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    cost_usd, cost_estimated, _unpriced = costs.run_cost([unit], price_table)
+    return {
+        **base,
+        "cached": False,
+        "llm_calls": 1 + retries,
+        "model": unit["model"],
+        "input_tokens": unit["input_tokens"],
+        "output_tokens": unit["output_tokens"],
+        "elapsed_ms": elapsed,
+        "cost_usd": cost_usd,
+        "cost_estimated": cost_estimated,
+        "cost_source": unit["cost_source"] if costs.valid_usd(unit["cost_usd"]) is not None else "",
+        "unit": unit,
+        "parse_retries": retries,
+    }
+
+
+def _trace_meta(unit: Mapping[str, Any], elapsed: int, retries: int, first_error: str) -> dict[str, Any]:
+    meta = {**unit, "elapsed_ms": elapsed}
+    if retries:
+        meta["parse_retries"] = retries
+        meta["first_error"] = first_error
+    return meta
+
+
 def _cached_grades(
     path: Path, key: str, judge_model: str, prompt_sha: str, humans: Mapping[str, str], ai: Sequence[Any],
 ) -> tuple[tuple[Grade, ...], str] | None:
diff --git a/tests/test_judge_parse_retry.py b/tests/test_judge_parse_retry.py
new file mode 100644
index 0000000..4998a76
--- /dev/null
+++ b/tests/test_judge_parse_retry.py
@@ -0,0 +1,468 @@
+"""A judge reply the parser rejects is asked for again (#21).
+
+``judge_case(..., parse_retries=N)`` sends the same request again while
+fewer than N retries have run, whenever :func:`prxref.judge.parse_judge_response`
+raises :class:`~prxref.judge.JudgeParseError`, whatever the reason: a
+superset of the issue's three cases. A call that raised and a cache hit are
+never retried, so a case makes at most 1 + N calls. Only the graded reply is
+cached, every attempt's usage counts toward the case's tokens and cost, and
+N=0, the library default, behaves exactly as 0.16.0 did.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import os
+import re
+import threading
+from pathlib import Path
+
+import pytest
+
+import prxref.judge
+from prxref import eval_judge
+from prxref.costs import parse_price_table
+from prxref.eval_cases import EvalCase, ExpectedFinding
+from prxref.eval_judge import JudgeOutcome, judge_case, judge_cost
+from prxref.judge import (
+    Grade,
+    JudgeParseError,
+    ai_ref_files,
+    assign_refs,
+    human_files,
+    judge_cache_key,
+    judge_prompt_sha,
+    parse_judge_response,
+)
+from prxref.llm import InvokeResult
+
+JUDGE = "judge-m"
+FALLBACK = "judge-m-fallback"
+
+CASE = EvalCase(
+    id="case-1",
+    expected=(
+        ExpectedFinding("H1", "src/a.py", 10, "error", text="Divides by zero when size is 0."),
+        ExpectedFinding("H2", "src/b.py", 5, "warning", text="Token logged in clear."),
+    ),
+    diff_file="case-1.patch",
+)
+
+RECORD = {
+    "findings": [
+        {"file": "src/a.py", "line": 10, "severity": "error", "title": "Divide by zero",
+         "body": "size may be 0.", "drop_reason": None},
+        {"file": "src/b.py", "line": 5, "severity": "error", "title": "Secret in log",
+         "body": "token is logged.", "drop_reason": None},
+    ],
+}
+
+GOOD_REPLY = json.dumps({"grades": [
+    {"human_id": "H1", "grade": "full", "ai_ref": "A1"},
+    {"human_id": "H2", "grade": "partial", "ai_ref": "A2"},
+]})
+GOOD_GRADES = (Grade("H1", "full", "A1"), Grade("H2", "partial", "A2"))
+
+NOT_JSON = "I think H1 is matched."
+NOT_JSON_ERROR = "judge response rejected: judge response is not JSON: Expecting value: line 1 column 1 (char 0)"
+BAD_GRADE = '{"grades": [{"human_id": "H1", "grade": "match", "ai_ref": "A1"}]}'
+BAD_GRADE_ERROR = "judge response rejected: grades[0] has grade 'match', not one of full, partial, none"
+
+KINDS = [
+    pytest.param("", "judge response is empty", id="empty"),
+    pytest.param(NOT_JSON, "judge response is not JSON: Expecting value: line 1 column 1 (char 0)", id="not-json"),
+    pytest.param("[]", "judge response is a JSON list, not an object", id="not-an-object"),
+    pytest.param('{"grades": "none"}', "judge response has no 'grades' list", id="no-grades-list"),
+    pytest.param('{"grades": [1]}', "grades[0] is not an object", id="row-not-an-object"),
+    pytest.param('{"grades": [{"grade": "full", "ai_ref": "A1"}]}', "grades[0] has no human_id", id="no-human-id"),
+    pytest.param(BAD_GRADE, "grades[0] has grade 'match', not one of full, partial, none", id="unknown-grade"),
+]
+
+BASE_META_JSON_KEYS = [
+    "unit", "model", "input_tokens", "output_tokens", "elapsed_ms",
+    "error", "cost_usd", "cost_source",
+]
+BASE_FILES = ["judge.meta.json", "judge.response.json", "judge.system.md", "judge.user.md"]
+
+
+def reply(text: str, *, model: str = JUDGE, input_tokens: int = 1000, output_tokens: int = 500,
+          cost_usd: float | None = None, cost_source: str = "") -> InvokeResult:
+    return InvokeResult(
+        text=text, model=model, backend="scripted",
+        input_tokens=input_tokens, output_tokens=output_tokens,
+        cost_usd=cost_usd, cost_source=cost_source,
+    )
+
+
+class ScriptedJudge:
+    """Answers each ``invoke`` with the next scripted step and records the call.
+
+    A step is an :class:`InvokeResult` to return or an exception to raise.
+    Running past the script raises ``AssertionError``, which ``judge_case``
+    reports as ``judge call failed: AssertionError: unscripted call #<n>``,
+    so an extra call shows up in both ``calls`` and the outcome's error.
+    """
+
+    def __init__(self, *script) -> None:
+        self.models = [JUDGE]
+        self.temperature = 0.0
+        self.seed = 7
+        self._script = list(script)
+        self.calls: list[dict] = []
+        self._lock = threading.Lock()
+
+    def invoke(self, system, user, *, max_tokens=4096, json_mode=False, timeout_s=None):
+        with self._lock:
+            self.calls.append({"system": system, "user": user, "max_tokens": max_tokens,
+                               "json_mode": json_mode, "timeout_s": timeout_s})
+            if not self._script:
+                raise AssertionError(f"unscripted call #{len(self.calls)}")
+            step = self._script.pop(0)
+        if isinstance(step, BaseException):
+            raise step
+        return step
+
+
+def _key() -> str:
+    return judge_cache_key(judge_prompt_sha(), JUDGE, CASE, assign_refs(RECORD["findings"]))
+
+
+def _cache_files(cache: Path) -> list[str]:
+    return sorted(p.name for p in cache.iterdir()) if cache.exists() else []
+
+
+def _entry(cache: Path) -> dict:
+    return json.loads((cache / f"{_key()}.json").read_text(encoding="utf-8"))
+
+
+def _files(trace: Path) -> list[str]:
+    return sorted(p.name for p in trace.iterdir())
+
+
+def _response(trace: Path, name: str):
+    return json.loads((trace / name).read_text(encoding="utf-8"))
+
+
+def _meta(trace: Path) -> dict:
+    return json.loads((trace / "judge.meta.json").read_text(encoding="utf-8"))
+
+
+def _warnings(caplog) -> list[str]:
+    return [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+
+
+def _retry_warnings(caplog) -> list[str]:
+    return [m for m in _warnings(caplog) if "parse retry" in m]
+
+
+def _error_warnings(caplog) -> list[str]:
+    return [m for m in _warnings(caplog) if m.startswith("judge error for case 'case-1'")]
+
+
+@pytest.fixture
+def cache_renames(monkeypatch):
+    """Record each ``os.replace`` whose destination is a judge cache entry."""
+    seen: list[str] = []
+    real_replace = os.replace
+
+    def spy(src, dst):
+        if str(dst).endswith(f"{_key()}.json"):
+            seen.append(str(dst))
+        real_replace(src, dst)
+
+    monkeypatch.setattr(eval_judge.os, "replace", spy)
+    return seen
+
+
+class TestEveryParseErrorKindIsRetried:
+    def test_the_kinds_cover_every_raise_site_in_the_parser(self):
+        source = Path(prxref.judge.__file__).read_text(encoding="utf-8")
+        assert len(re.findall(r"\braise JudgeParseError\(", source)) == len(KINDS)
+
+    @pytest.mark.parametrize(("text", "error"), KINDS)
+    def test_each_reply_reaches_its_own_raise_site(self, text, error):
+        with pytest.raises(JudgeParseError) as caught:
+            parse_judge_response(text, human_files(CASE), ai_ref_files(assign_refs(RECORD["findings"])))
+        assert str(caught.value) == error
+
+    @pytest.mark.parametrize(("text", "error"), KINDS)
+    def test_malformed_then_valid_grades_the_case(self, tmp_path, caplog, cache_renames, text, error):
+        cache = tmp_path / "cache"
+        client = ScriptedJudge(reply(text), reply(GOOD_REPLY))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, max_tokens=2048,
+                                 timeout_s=9.0, parse_retries=1)
+        assert len(client.calls) == 2
+        assert client.calls[0] == client.calls[1]
+        assert client.calls[0]["json_mode"] is True
+        assert (client.calls[0]["max_tokens"], client.calls[0]["timeout_s"]) == (2048, 9.0)
+        assert outcome.ok and outcome.error is None
+        assert outcome.grades == GOOD_GRADES
+        assert (outcome.llm_calls, outcome.parse_retries, outcome.cached) == (2, 1, False)
+        assert _cache_files(cache) == [f"{_key()}.json"]
+        assert _entry(cache)["response"] == GOOD_REPLY
+        assert cache_renames == [str(cache / f"{_key()}.json")]
+        assert _retry_warnings(caplog) == [
+            f"judge for case 'case-1': unusable reply ({error}); parse retry 1 of 1",
+        ]
+        assert _error_warnings(caplog) == []
+
+
+class TestMalformedEveryTime:
+    def test_malformed_twice_at_one_fails_with_the_last_reason_and_caches_nothing(
+        self, tmp_path, caplog, cache_renames,
+    ):
+        cache = tmp_path / "cache"
+        client = ScriptedJudge(reply(NOT_JSON), reply(BAD_GRADE))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, parse_retries=1)
+        assert len(client.calls) == 2
+        assert not outcome.ok and outcome.grades is None
+        assert outcome.error == BAD_GRADE_ERROR
+        assert (outcome.llm_calls, outcome.parse_retries, outcome.cached) == (2, 1, False)
+        assert _cache_files(cache) == []
+        assert cache_renames == []
+        assert _error_warnings(caplog) == [f"judge error for case 'case-1': {BAD_GRADE_ERROR}"]
+        assert len(_retry_warnings(caplog)) == 1
+
+    def test_malformed_three_times_at_two_makes_three_calls(self, tmp_path, caplog):
+        cache = tmp_path / "cache"
+        client = ScriptedJudge(reply(""), reply("[]"), reply(NOT_JSON))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, parse_retries=2)
+        assert len(client.calls) == 3
+        assert client.calls[0] == client.calls[1] == client.calls[2]
+        assert outcome.error == NOT_JSON_ERROR
+        assert (outcome.llm_calls, outcome.parse_retries) == (3, 2)
+        assert _cache_files(cache) == []
+        assert [m.rsplit("; ", 1)[1] for m in _retry_warnings(caplog)] == ["parse retry 1 of 2", "parse retry 2 of 2"]
+
+    def test_a_valid_third_reply_at_two_grades_the_case(self, tmp_path):
+        cache = tmp_path / "cache"
+        client = ScriptedJudge(reply(""), reply(BAD_GRADE), reply(GOOD_REPLY))
+        outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, parse_retries=2)
+        assert len(client.calls) == 3
+        assert outcome.ok and outcome.grades == GOOD_GRADES
+        assert (outcome.llm_calls, outcome.parse_retries) == (3, 2)
+        assert _entry(cache)["response"] == GOOD_REPLY
+
+    def test_the_next_score_judges_the_uncached_case_again(self, tmp_path):
+        cache = tmp_path / "cache"
+        judge_case(ScriptedJudge(reply(NOT_JSON), reply(NOT_JSON)), JUDGE, CASE, RECORD,
+                   cache_dir=cache, parse_retries=1)
+        client = ScriptedJudge(reply(GOOD_REPLY))
+        outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, parse_retries=1)
+        assert len(client.calls) == 1 and outcome.ok and not outcome.cached
+
+
+class TestAFirstReplyThatParses:
+    def test_makes_one_call_and_no_retry_at_one(self, tmp_path, caplog):
+        trace = tmp_path / "trace"
+        client = ScriptedJudge(reply(GOOD_REPLY))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            outcome = judge_case(client, JUDGE, CASE, RECORD, trace_dir=str(trace), parse_retries=1)
+        assert len(client.calls) == 1
+        assert outcome.ok and (outcome.llm_calls, outcome.parse_retries) == (1, 0)
+        assert _files(trace) == BASE_FILES
+        assert list(_meta(trace)) == BASE_META_JSON_KEYS
+        assert _warnings(caplog) == []
+
+
+class TestZeroIsTheOldBehaviour:
+    @pytest.mark.parametrize("kwargs", [pytest.param({}, id="default"), pytest.param({"parse_retries": 0}, id="zero")])
+    def test_a_malformed_reply_is_one_call_and_todays_reason(self, tmp_path, caplog, kwargs):
+        cache = tmp_path / "cache"
+        client = ScriptedJudge(reply(NOT_JSON, cost_usd=0.003, cost_source="usage.cost"))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, **kwargs)
+        assert len(client.calls) == 1
+        assert outcome.error == NOT_JSON_ERROR
+        assert outcome.grades is None
+        assert (outcome.llm_calls, outcome.parse_retries, outcome.cached) == (1, 0, False)
+        assert (outcome.model, outcome.input_tokens, outcome.output_tokens) == (JUDGE, 1000, 500)
+        assert (outcome.cost_usd, outcome.cost_estimated, outcome.cost_source) == (0.003, False, "usage.cost")
+        assert outcome.unit == {"model": JUDGE, "input_tokens": 1000, "output_tokens": 500,
+                                "cost_usd": 0.003, "cost_source": "usage.cost"}
+        assert _warnings(caplog) == [f"judge error for case 'case-1': {NOT_JSON_ERROR}"]
+        assert _cache_files(cache) == []
+
+    @pytest.mark.parametrize("text", ["", "[]", BAD_GRADE])
+    def test_no_kind_is_retried(self, text):
+        client = ScriptedJudge(reply(text))
+        outcome = judge_case(client, JUDGE, CASE, RECORD, parse_retries=0)
+        assert len(client.calls) == 1
+        assert outcome.error.startswith("judge response rejected: ")
+        assert outcome.parse_retries == 0
+
+    def test_a_negative_budget_retries_nothing(self):
+        client = ScriptedJudge(reply(NOT_JSON))
+        outcome = judge_case(client, JUDGE, CASE, RECORD, parse_retries=-1)
+        assert len(client.calls) == 1 and outcome.error == NOT_JSON_ERROR and outcome.parse_retries == 0
+
+    def test_the_trace_has_four_files_and_eight_meta_keys(self, tmp_path):
+        trace = tmp_path / "trace"
+        judge_case(ScriptedJudge(reply(NOT_JSON)), JUDGE, CASE, RECORD, trace_dir=str(trace))
+        assert _files(trace) == BASE_FILES
+        meta = _meta(trace)
+        assert list(meta) == BASE_META_JSON_KEYS
+        assert meta["error"] == NOT_JSON_ERROR
+        assert _response(trace, "judge.response.json") == NOT_JSON
+
+    def test_an_attempt_file_left_by_an_earlier_run_is_not_touched(self, tmp_path):
+        trace = tmp_path / "trace"
+        trace.mkdir()
+        (trace / "judge.attempt1.response.json").write_text('"old"', encoding="utf-8")
+        judge_case(ScriptedJudge(reply(GOOD_REPLY)), JUDGE, CASE, RECORD, trace_dir=str(trace))
+        assert (trace / "judge.attempt1.response.json").read_text(encoding="utf-8") == '"old"'
+
+
+class TestARaisingCallIsNeverRetried:
+    def test_a_raising_first_call_is_one_call(self, tmp_path):
+        cache = tmp_path / "cache"
+        client = ScriptedJudge(TimeoutError("late"), reply(GOOD_REPLY))
+        outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, parse_retries=1)
+        assert len(client.calls) == 1
+        assert outcome.error == "judge call failed: TimeoutError: late"
+        assert (outcome.llm_calls, outcome.parse_retries) == (1, 0)
+        assert (outcome.cost_usd, outcome.model, outcome.input_tokens) == (None, "", 0)
+        assert _cache_files(cache) == []
+
+    def test_a_raising_retry_fails_the_case_and_keeps_the_billed_attempt(self, tmp_path, caplog):
+        cache = tmp_path / "cache"
+        trace = tmp_path / "trace"
+        client = ScriptedJudge(reply(NOT_JSON, cost_usd=0.001, cost_source="usage.cost"), TimeoutError("late"))
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, trace_dir=str(trace),
+                                 parse_retries=2)
+        assert len(client.calls) == 2
+        assert outcome.error == "judge call failed: TimeoutError: late"
+        assert outcome.grades is None
+        assert (outcome.llm_calls, outcome.parse_retries) == (2, 1)
+        assert (outcome.model, outcome.input_tokens, outcome.output_tokens) == (JUDGE, 1000, 500)
+        assert outcome.cost_usd == 0.001
+        assert judge_cost([outcome], {}) == (0.001, False)
+        assert _cache_files(cache) == []
+        assert _error_warnings(caplog) == ["judge error for case 'case-1': judge call failed: TimeoutError: late"]
+        assert _response(trace, "judge.response.json") is None
+        assert _response(trace, "judge.attempt1.response.json") == NOT_JSON
+        meta = _meta(trace)
+        assert (meta["parse_retries"], meta["first_error"]) == (1, NOT_JSON_ERROR)
+        assert meta["error"] == "judge call failed: TimeoutError: late"
+
+
+class TestUsageCoversEveryAttempt:
+    def test_tokens_are_summed_and_the_model_is_the_last_calls(self):
+        client = ScriptedJudge(
+            reply(NOT_JSON, input_tokens=1000, output_tokens=500),
+            reply(GOOD_REPLY, model=FALLBACK, input_tokens=1200, output_tokens=700),
+        )
+        outcome = judge_case(client, JUDGE, CASE, RECORD, parse_retries=1)
+        assert (outcome.input_tokens, outcome.output_tokens, outcome.model) == (2200, 1200, FALLBACK)
+        assert (outcome.unit["input_tokens"], outcome.unit["output_tokens"], outcome.unit["model"]) == (
+            2200, 1200, FALLBACK)
+
+    def test_reported_costs_are_summed(self):
+        client = ScriptedJudge(
+            reply(NOT_JSON, cost_usd=0.001, cost_source="usage.cost"),
+            reply(GOOD_REPLY, cost_usd=0.002, cost_source="x-litellm-response-cost"),
+        )
+        outcome = judge_case(client, JUDGE, CASE, RECORD, parse_retries=1)
+        assert outcome.cost_usd == pytest.approx(0.003)
+        assert (outcome.cost_estimated, outcome.cost_source) == (False, "x-litellm-response-cost")
+        assert judge_cost([outcome], {})[0] == pytest.approx(0.003)
+
+    def test_a_failed_case_is_billed_for_every_attempt(self):
+        client = ScriptedJudge(
+            reply(NOT_JSON, cost_usd=0.001, cost_source="usage.cost"),
+            reply(BAD_GRADE, cost_usd=0.002, cost_source="usage.cost"),
+        )
+        outcome = judge_case(client, JUDGE, CASE, RECORD, parse_retries=1)
+        assert not outcome.ok
+        assert outcome.cost_usd == pytest.approx(0.003)
+        assert (outcome.input_tokens, outcome.output_tokens) == (2000, 1000)
+
+    def test_one_unreported_attempt_makes_the_cost_unknown_without_a_table(self):
+        client = ScriptedJudge(
+            reply(NOT_JSON, cost_usd=0.001, cost_source="usage.cost"),
+            reply(GOOD_REPLY, cost_usd=None),
+        )
+        outcome = judge_case(client, JUDGE, CASE, RECORD, price_table={}, parse_retries=1)
+        assert (outcome.cost_usd, outcome.cost_estimated, outcome.cost_source) == (None, False, "")
+        assert judge_cost([outcome], {}) == (None, False)
+
+    def test_the_price_table_prices_the_summed_tokens(self):
+        table = parse_price_table({JUDGE: {"input": 1.0, "output": 2.0}})
+        client = ScriptedJudge(reply(NOT_JSON), reply(GOOD_REPLY))
+        outcome = judge_case(client, JUDGE, CASE, RECORD, price_table=table, parse_retries=1)
+        assert (outcome.cost_usd, outcome.cost_estimated, outcome.cost_source) == (0.004, True, "")
+        assert judge_cost([outcome], table) == (0.004, True)
+
+
+class TestACacheHitIsNeverRetried:
+    def test_a_hit_makes_no_call_and_no_retry(self, tmp_path):
+        cache = tmp_path / "cache"
+        judge_case(ScriptedJudge(reply(NOT_JSON), reply(GOOD_REPLY)), JUDGE, CASE, RECORD,
+                   cache_dir=cache, parse_retries=1)
+        client = ScriptedJudge()
+        outcome = judge_case(client, JUDGE, CASE, RECORD, cache_dir=cache, parse_retries=1)
+        assert client.calls == []
+        assert outcome.ok and outcome.cached and outcome.grades == GOOD_GRADES
+        assert (outcome.llm_calls, outcome.parse_retries) == (0, 0)
+
+    def test_a_case_without_labels_makes_no_call(self):
+        client = ScriptedJudge()
+        outcome = judge_case(client, JUDGE, EvalCase(id="empty", expected=()), RECORD, parse_retries=3)
+        assert client.calls == []
+        assert (outcome.llm_calls, outcome.parse_retries) == (0, 0)
+
+
+class TestTheTraceKeepsEveryReply:
+    def test_the_discarded_reply_is_an_attempt_file_and_the_base_files_show_the_used_one(self, tmp_path):
+        trace = tmp_path / "trace"
+        client = ScriptedJudge(reply(NOT_JSON, cost_usd=0.001, cost_source="usage.cost"),
+                               reply(GOOD_REPLY, cost_usd=0.002, cost_source="usage.cost"))
+        judge_case(client, JUDGE, CASE, RECORD, trace_dir=str(trace), parse_retries=1)
+        assert _files(trace) == sorted([*BASE_FILES, "judge.attempt1.response.json"])
+        assert _response(trace, "judge.attempt1.response.json") == NOT_JSON
+        assert _response(trace, "judge.response.json") == GOOD_REPLY
+        assert (trace / "judge.user.md").read_text(encoding="utf-8") == client.calls[1]["user"]
+        meta = _meta(trace)
+        assert list(meta) == [*BASE_META_JSON_KEYS, "parse_retries", "first_error"]
+        assert (meta["parse_retries"], meta["first_error"], meta["error"]) == (1, NOT_JSON_ERROR, "")
+        assert (meta["input_tokens"], meta["output_tokens"]) == (2000, 1000)
+        assert meta["cost_usd"] == pytest.approx(0.003)
+
+    def test_malformed_twice_keeps_both_replies(self, tmp_path):
+        trace = tmp_path / "trace"
+        judge_case(ScriptedJudge(reply(NOT_JSON), reply(BAD_GRADE)), JUDGE, CASE, RECORD,
+                   trace_dir=str(trace), parse_retries=1)
+        assert _response(trace, "judge.attempt1.response.json") == NOT_JSON
+        assert _response(trace, "judge.response.json") == BAD_GRADE
+        meta = _meta(trace)
+        assert (meta["first_error"], meta["error"]) == (NOT_JSON_ERROR, BAD_GRADE_ERROR)
+
+    def test_two_retries_write_two_attempt_files_in_call_order(self, tmp_path):
+        trace = tmp_path / "trace"
+        judge_case(ScriptedJudge(reply(""), reply("[]"), reply(GOOD_REPLY)), JUDGE, CASE, RECORD,
+                   trace_dir=str(trace), parse_retries=2)
+        assert _response(trace, "judge.attempt1.response.json") == ""
+        assert _response(trace, "judge.attempt2.response.json") == "[]"
+        assert _response(trace, "judge.response.json") == GOOD_REPLY
+        assert _meta(trace)["parse_retries"] == 2
+
+    def test_a_later_run_with_fewer_retries_removes_the_stale_attempt_files(self, tmp_path):
+        trace = tmp_path / "trace"
+        judge_case(ScriptedJudge(reply(""), reply("[]"), reply(GOOD_REPLY)), JUDGE, CASE, RECORD,
+                   trace_dir=str(trace), parse_retries=2)
+        judge_case(ScriptedJudge(reply(GOOD_REPLY)), JUDGE, CASE, RECORD, trace_dir=str(trace), parse_retries=2)
+        assert _files(trace) == BASE_FILES
+        assert list(_meta(trace)) == BASE_META_JSON_KEYS
+
+
+class TestJudgeOutcomeField:
+    def test_parse_retries_is_the_last_field_and_defaults_to_zero(self):
+        assert dataclasses.fields(JudgeOutcome)[-1].name == "parse_retries"
+        outcome = JudgeOutcome(case_id="c", cache_key="k", grades=(), error=None, cached=False, llm_calls=0,
+                               ref_index={})
+        assert outcome.parse_retries == 0

From 268a99ceeffe84f6d57edf40eefa6644ee6a98a5 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:32:15 -0700
Subject: [PATCH 09/25] feat: JVM dependency lines for a changed Java or Kotlin
 file (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add prxref.jvm_deps.dependency_lines(path, added, read), which turns the
imports on a .java, .kt or .kts file's added lines into sorted, deduplicated
g:a@v and g:a@(managed by ...) lines, the same shape
chunk_context.dependency_versions returns for other languages. It imports
only the stdlib and the jvm_lang, jvm_maven and jvm_gradle leaf modules, so
chunk_context can import it without a cycle. Nothing calls it yet.

- Imports rooted at java, jdk, sun or kotlin are skipped (javax is kept);
  with nothing left, or on a non-JVM path, read is never called.
- The walk climbs from the file's directory to the repository root, trying
  pom.xml, build.gradle.kts, then build.gradle at each level. The first
  non-empty read wins and ends the walk even if it is unparseable, so a
  broken manifest contributes nothing. Every read goes through one per-call
  cache, so no path is read twice (a parent relativePath pointing back at a
  probed miss is not re-read), and a raising or non-text read is a miss.
- Imports under the project's own group (pom groupId, falling back to the
  parent's, or Gradle group) are skipped by segment prefix.
- Matching: a dependency is a candidate when its groupId has at least 2
  segments and prefixes the import, or shares at least 3 leading segments
  with it. The artifactId tokens (split on -._, minus groupId segments)
  that equal an import segment score the candidates; the best score wins
  and ties list every tied candidate, so a databind import picks
  jackson-databind over jackson-core and jackson-annotations.
- Maven renders through MavenDependency.line(), keeping jvm_maven's owner
  precedence. A versionless Gradle dependency is owned by the platform whose
  group shares the most leading segments with it, first declared on a tie,
  rendered through the same MavenDependency/MavenCoordinate code.
- Never raises; any failure yields [].

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/jvm_deps.py | 218 +++++++++++++++++
 tests/test_jvm_deps.py | 518 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 736 insertions(+)
 create mode 100644 src/prxref/jvm_deps.py
 create mode 100644 tests/test_jvm_deps.py

diff --git a/src/prxref/jvm_deps.py b/src/prxref/jvm_deps.py
new file mode 100644
index 0000000..ff9b2b9
--- /dev/null
+++ b/src/prxref/jvm_deps.py
@@ -0,0 +1,218 @@
+"""Dependency-version lines for one changed Java or Kotlin file (#20).
+
+Java and Kotlin imports name packages, not artifacts, so the version a changed
+file runs against is found in three steps:
+
+**Imports.** The file's added lines are parsed with
+:func:`prxref.jvm_lang.parse_imports`. Imports rooted at ``java``, ``jdk``,
+``sun`` or ``kotlin`` (:data:`SKIPPED_ROOTS`) are skipped; ``javax`` is kept,
+because part of it ships as separate artifacts. When nothing is left, no
+manifest is read at all.
+
+**Manifest.** The walk starts in the file's own directory and climbs to the
+repository root ``""``, trying :data:`MANIFEST_NAMES` (``pom.xml``, then
+``build.gradle.kts``, then ``build.gradle``) at each level. The first
+non-empty read wins and ends the walk, even when that file turns out to be
+unparseable, so a broken manifest contributes nothing rather than letting a
+farther one speak for the module. A pom is resolved by
+:func:`prxref.jvm_maven.resolve_pom` (properties, in-repository parents,
+imported BOMs) and a Gradle build file by
+:func:`prxref.jvm_gradle.gradle_build` (string notation, platforms, the
+version catalog). Every read goes through one per-call cache, so no path is
+read twice, and a read that raises or returns anything but non-empty text is a
+miss.
+
+**Matching.** Imports under the project's own group (the pom's ``groupId`` or
+the Gradle ``group``) are skipped. A declared dependency is a candidate for an
+import when its groupId has at least :data:`MIN_GROUP_PREFIX_SEGMENTS` segments
+and is a leading segment prefix of the import, or when the two share a leading
+prefix of at least :data:`MIN_SHARED_SEGMENTS` segments. Among the candidates,
+the ones whose artifactId has the most tokens (split on ``-``, ``.`` and
+``_``, ignoring tokens that are groupId segments) equal to an import segment
+win, and a tie keeps every tied candidate: ``com.fasterxml.jackson.databind``
+picks ``jackson-databind`` over ``jackson-core`` and ``jackson-annotations``.
+
+**Lines.** A Maven dependency renders through
+:meth:`prxref.jvm_maven.MavenDependency.line`, keeping the owner jvm_maven
+chose. A Gradle dependency renders as ``g:a@v``; without a version but with at
+least one platform it renders as ``g:a@(managed by bg:ba@bv)``, the owner being
+the platform whose group shares the most leading segments with the
+dependency's, the first declared on a tie. A winning dependency with neither a
+version nor an owner renders no line.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from prxref import jvm_gradle, jvm_maven
+from prxref.jvm_lang import jvm_language, parse_imports
+
+MANIFEST_NAMES: tuple[str, ...] = ("pom.xml", *jvm_gradle.BUILD_FILE_NAMES)
+CATALOG_FILE_NAME = jvm_gradle.CATALOG_FILE_NAME
+SKIPPED_ROOTS = frozenset({"java", "jdk", "sun", "kotlin"})
+MIN_GROUP_PREFIX_SEGMENTS = 2
+MIN_SHARED_SEGMENTS = 3
+
+_TOKEN_RE = re.compile(r"[-._]")
+
+Reader = Callable[[str], str | None]
+
+
+@dataclass(frozen=True)
+class _Declared:
+    group: str
+    artifact: str
+    line: str | None
+
+
+def _cached(read: Reader) -> Reader:
+    seen: dict[str, str | None] = {}
+
+    def cached(path: str) -> str | None:
+        if path not in seen:
+            try:
+                text = read(path)
+            except Exception:  # noqa: BLE001 - a failed read is a read that returned None
+                text = None
+            seen[path] = text if isinstance(text, str) and text else None
+        return seen[path]
+
+    return cached
+
+
+def _ancestor_dirs(path: str) -> list[str]:
+    parts = path.split("/")[:-1]
+    dirs = []
+    while parts:
+        dirs.append("/".join(parts))
+        parts = parts[:-1]
+    dirs.append("")
+    return dirs
+
+
+def _nearest_manifest(path: str, read: Reader) -> tuple[str, str] | None:
+    for directory in _ancestor_dirs(path):
+        for name in MANIFEST_NAMES:
+            candidate = f"{directory}/{name}" if directory else name
+            text = read(candidate)
+            if text:
+                return candidate, text
+    return None
+
+
+def _shared(left: Sequence[str], right: Sequence[str]) -> int:
+    count = 0
+    for a, b in zip(left, right, strict=False):
+        if a != b:
+            break
+        count += 1
+    return count
+
+
+def _under(group: str | None, segments: Sequence[str]) -> bool:
+    if not group:
+        return False
+    group_segments = group.split(".")
+    return _shared(group_segments, segments) == len(group_segments)
+
+
+def _is_candidate(group: str, segments: Sequence[str]) -> bool:
+    group_segments = group.split(".")
+    shared = _shared(group_segments, segments)
+    if len(group_segments) >= MIN_GROUP_PREFIX_SEGMENTS and shared == len(group_segments):
+        return True
+    return shared >= MIN_SHARED_SEGMENTS
+
+
+def _score(declared: _Declared, segments: Sequence[str]) -> int:
+    group_segments = set(declared.group.split("."))
+    present = set(segments)
+    return sum(
+        1 for token in _TOKEN_RE.split(declared.artifact)
+        if token not in group_segments and token in present
+    )
+
+
+def _matches(segments: Sequence[str], declared: Sequence[_Declared]) -> list[_Declared]:
+    candidates = [dep for dep in declared if _is_candidate(dep.group, segments)]
+    if not candidates:
+        return []
+    scores = [_score(dep, segments) for dep in candidates]
+    best = max(scores)
+    return [dep for dep, score in zip(candidates, scores, strict=True) if score == best]
+
+
+def _maven(path: str, text: str, read: Reader) -> tuple[str | None, list[_Declared]]:
+    project = jvm_maven.resolve_pom(path, read, text=text)
+    if project is None:
+        return None, []
+    return project.group_id, [
+        _Declared(dep.group_id, dep.artifact_id, dep.line()) for dep in project.dependencies
+    ]
+
+
+def _gradle_owner(
+    dependency: jvm_gradle.GradleDependency,
+    boms: Sequence[jvm_gradle.GradleDependency],
+) -> jvm_maven.MavenCoordinate:
+    segments = dependency.group.split(".")
+    bom = max(boms, key=lambda candidate: _shared(candidate.group.split("."), segments))
+    return jvm_maven.MavenCoordinate(bom.group, bom.artifact, bom.version)
+
+
+def _gradle_line(
+    dependency: jvm_gradle.GradleDependency,
+    boms: Sequence[jvm_gradle.GradleDependency],
+) -> str | None:
+    owner = _gradle_owner(dependency, boms) if dependency.version is None and boms else None
+    return jvm_maven.MavenDependency(dependency.group, dependency.artifact, dependency.version, owner).line()
+
+
+def _gradle(path: str, text: str, read: Reader) -> tuple[str | None, list[_Declared]]:
+    build = jvm_gradle.gradle_build(path, text, read, root="")
+    return build.group, [
+        _Declared(dep.group, dep.artifact, _gradle_line(dep, build.boms)) for dep in build.dependencies
+    ]
+
+
+def _dependency_lines(path: str, added: Sequence[str], read: Reader) -> list[str]:
+    if not jvm_language(path):
+        return []
+    imports = [item for item in parse_imports(added) if item.segments[0] not in SKIPPED_ROOTS]
+    if not imports:
+        return []
+    cached = _cached(read)
+    found = _nearest_manifest(path, cached)
+    if found is None:
+        return []
+    manifest_path, text = found
+    if manifest_path.rsplit("/", 1)[-1] == "pom.xml":
+        own_group, declared = _maven(manifest_path, text, cached)
+    else:
+        own_group, declared = _gradle(manifest_path, text, cached)
+    lines: set[str] = set()
+    for item in imports:
+        if _under(own_group, item.segments):
+            continue
+        lines.update(dep.line for dep in _matches(item.segments, declared) if dep.line)
+    return sorted(lines)
+
+
+def dependency_lines(path: str, added: Sequence[str], read: Reader) -> list[str]:
+    """Dependency-version lines for the imports on a Java or Kotlin file's added lines.
+
+    ``path`` is the changed file's repository-relative path (``.java``, ``.kt``
+    or ``.kts``; any other path yields ``[]``), ``added`` holds the text of its
+    added lines, and ``read`` maps a repository-relative path to its text or
+    ``None``. Returns ``g:a@v`` and ``g:a@(managed by ...)`` lines, sorted and
+    deduplicated, the same shape
+    :func:`prxref.chunk_context.dependency_versions` returns for other
+    languages. ``read`` is never called when every import is skipped, and never
+    twice for one path. Never raises: any failure yields ``[]``.
+    """
+    try:
+        return _dependency_lines(path, added, read)
+    except Exception:  # noqa: BLE001 - missing context is not a review failure
+        return []
diff --git a/tests/test_jvm_deps.py b/tests/test_jvm_deps.py
new file mode 100644
index 0000000..7d5a90d
--- /dev/null
+++ b/tests/test_jvm_deps.py
@@ -0,0 +1,518 @@
+"""Unit tests for :mod:`prxref.jvm_deps`, the JVM dependency lines behind #20.
+
+Every test reads through a counting fake repository, so the manifest walk's
+probe order, its first-hit stop, the skips that must not read at all, and the
+one-read-per-path rule are pinned by the exact list of paths asked for.
+"""
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+import pytest
+
+from prxref import jvm_deps
+from prxref.jvm_deps import (
+    CATALOG_FILE_NAME,
+    MANIFEST_NAMES,
+    MIN_GROUP_PREFIX_SEGMENTS,
+    MIN_SHARED_SEGMENTS,
+    SKIPPED_ROOTS,
+    dependency_lines,
+)
+
+DATABIND = ("com.fasterxml.jackson.core", "jackson-databind")
+JACKSON_CORE = ("com.fasterxml.jackson.core", "jackson-core")
+JACKSON_ANNOTATIONS = ("com.fasterxml.jackson.core", "jackson-annotations")
+SPRING_BOM = ("org.springframework.boot", "spring-boot-dependencies")
+SLF4J_API = ("org.slf4j", "slf4j-api")
+
+OBJECT_MAPPER = "import com.fasterxml.jackson.databind.ObjectMapper;"
+LOGGER = "import org.slf4j.Logger;"
+
+DATABIND_BY_SPRING = (
+    "com.fasterxml.jackson.core:jackson-databind"
+    "@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)"
+)
+
+
+class Repo:
+    """A fake repository reader that records every path it is asked for.
+
+    ``files`` maps a repository-relative path to its text; any other path reads
+    as ``None``. A path in ``raising`` raises instead.
+    """
+
+    def __init__(self, files: dict[str, object] | None = None, *, raising: frozenset[str] = frozenset()):
+        self.files = dict(files or {})
+        self.raising = raising
+        self.reads: list[str] = []
+
+    def __call__(self, path: str):
+        self.reads.append(path)
+        if path in self.raising:
+            raise OSError(f"cannot read {path}")
+        return self.files.get(path)
+
+
+def pom(*parts: str, prolog: str = "") -> str:
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        f'{prolog}<project xmlns="http://maven.apache.org/POM/4.0.0">\n'
+        "  <modelVersion>4.0.0</modelVersion>\n" + "\n".join(parts) + "\n</project>\n"
+    )
+
+
+def coords(group: str, artifact: str, version: str = "1.0.0") -> str:
+    return f"<groupId>{group}</groupId><artifactId>{artifact}</artifactId><version>{version}</version>"
+
+
+def parent(group: str, artifact: str, version: str, relative_path: str | None = None) -> str:
+    relative = "" if relative_path is None else f"<relativePath>{relative_path}</relativePath>"
+    return (
+        f"<parent><groupId>{group}</groupId><artifactId>{artifact}</artifactId>"
+        f"<version>{version}</version>{relative}</parent>"
+    )
+
+
+def dep(group: str, artifact: str, version: str | None = None, *, bom: bool = False) -> str:
+    parts = [f"<groupId>{group}</groupId>", f"<artifactId>{artifact}</artifactId>"]
+    if version is not None:
+        parts.append(f"<version>{version}</version>")
+    if bom:
+        parts.append("<type>pom</type><scope>import</scope>")
+    return "<dependency>" + "".join(parts) + "</dependency>"
+
+
+def deps(*items: str) -> str:
+    return "<dependencies>" + "".join(items) + "</dependencies>"
+
+
+def managed(*items: str) -> str:
+    return "<dependencyManagement>" + deps(*items) + "</dependencyManagement>"
+
+
+def props(**values: str) -> str:
+    return "<properties>" + "".join(f"<{k}>{v}</{k}>" for k, v in values.items()) + "</properties>"
+
+
+def simple_pom(*dependencies: str, group: str = "com.acme", artifact: str = "app") -> str:
+    return pom(coords(group, artifact), deps(*dependencies))
+
+
+def gradle(*lines: str) -> str:
+    return "dependencies {\n" + "".join(f"    {line}\n" for line in lines) + "}\n"
+
+
+def probes(*directories: str) -> list[str]:
+    return [
+        f"{directory}/{name}" if directory else name
+        for directory in directories
+        for name in ("pom.xml", "build.gradle.kts", "build.gradle")
+    ]
+
+
+class TestModuleSurface:
+    def test_the_manifest_names_are_probed_pom_first(self):
+        assert MANIFEST_NAMES == ("pom.xml", "build.gradle.kts", "build.gradle")
+        assert CATALOG_FILE_NAME == "libs.versions.toml"
+
+    def test_the_skipped_roots_and_the_matching_thresholds(self):
+        assert SKIPPED_ROOTS == frozenset({"java", "jdk", "sun", "kotlin"})
+        assert (MIN_GROUP_PREFIX_SEGMENTS, MIN_SHARED_SEGMENTS) == (2, 3)
+
+    def test_the_module_imports_only_the_stdlib_and_the_jvm_leaf_modules(self):
+        tree = ast.parse(Path(jvm_deps.__file__).read_text(encoding="utf-8"))
+        imported: set[str] = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                imported.update(alias.name for alias in node.names)
+            elif isinstance(node, ast.ImportFrom):
+                assert node.level == 0
+                if node.module == "prxref":
+                    imported.update(f"prxref.{alias.name}" for alias in node.names)
+                else:
+                    imported.add(node.module or "")
+        prxref_modules = {name for name in imported if name.split(".")[0] == "prxref"}
+        assert prxref_modules == {"prxref.jvm_lang", "prxref.jvm_maven", "prxref.jvm_gradle"}
+        others = {name.split(".")[0] for name in imported - prxref_modules}
+        assert others <= set(sys.stdlib_module_names) | {"__future__"}
+
+
+class TestMatching:
+    @pytest.mark.parametrize(("dependency", "line", "expected"), [
+        (("javax.servlet", "javax.servlet-api", "4.0.1"), "import javax.servlet.http.HttpServletRequest;",
+         "javax.servlet:javax.servlet-api@4.0.1"),
+        ((*SLF4J_API, "2.0.13"), LOGGER, "org.slf4j:slf4j-api@2.0.13"),
+    ])
+    def test_a_two_segment_group_that_prefixes_the_import_matches(self, dependency, line, expected):
+        repo = Repo({"pom.xml": simple_pom(dep(*dependency))})
+        assert dependency_lines("src/App.java", [line], repo) == [expected]
+
+    def test_the_jackson_tie_break_picks_databind_and_only_databind(self):
+        repo = Repo({"pom.xml": simple_pom(
+            dep(*JACKSON_CORE, "2.17.1"), dep(*DATABIND, "2.17.1"), dep(*JACKSON_ANNOTATIONS, "2.17.1"),
+        )})
+        assert dependency_lines("src/App.java", [OBJECT_MAPPER], repo) == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+        ]
+
+    def test_a_tie_lists_every_tied_candidate(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"), dep("org.slf4j", "jul-to-slf4j", "2.0.13"))})
+        assert dependency_lines("src/App.java", [LOGGER], repo) == [
+            "org.slf4j:jul-to-slf4j@2.0.13",
+            "org.slf4j:slf4j-api@2.0.13",
+        ]
+
+    def test_two_shared_segments_without_a_group_prefix_do_not_match(self):
+        repo = Repo({"pom.xml": simple_pom(
+            dep("org.springframework.boot", "spring-boot-starter-web", "3.3.4"),
+            dep("org.springframework", "spring-web", "6.1.13"),
+        )})
+        added = ["import org.springframework.web.bind.annotation.RestController;"]
+        assert dependency_lines("src/App.java", added, repo) == ["org.springframework:spring-web@6.1.13"]
+
+    def test_a_single_segment_group_never_matches(self):
+        repo = Repo({"pom.xml": simple_pom(dep("junit", "junit", "4.13.2"))})
+        assert dependency_lines("src/AppTest.java", ["import junit.framework.TestCase;"], repo) == []
+
+    def test_a_static_import_matches_through_its_member(self):
+        repo = Repo({"pom.xml": simple_pom(
+            dep("org.junit.jupiter", "junit-jupiter-engine", "5.10.2"),
+            dep("org.junit.jupiter", "junit-jupiter-api", "5.10.2"),
+        )})
+        added = ["import static org.junit.jupiter.api.Assertions.assertEquals;"]
+        assert dependency_lines("src/AppTest.java", added, repo) == ["org.junit.jupiter:junit-jupiter-api@5.10.2"]
+
+    def test_a_wildcard_import_equal_to_the_group_matches(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("src/App.java", ["import org.slf4j.*;"], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+
+    def test_a_kotlin_alias_import_matches_its_qualified_name(self):
+        text = gradle('implementation("com.fasterxml.jackson.core:jackson-databind:2.17.1")')
+        repo = Repo({"build.gradle.kts": text})
+        added = ["import com.fasterxml.jackson.databind.ObjectMapper as Mapper"]
+        assert dependency_lines("src/App.kt", added, repo) == ["com.fasterxml.jackson.core:jackson-databind@2.17.1"]
+
+    def test_lines_are_sorted_and_deduplicated(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"), dep(*DATABIND, "2.17.1"))})
+        added = [LOGGER, "import org.slf4j.LoggerFactory;", OBJECT_MAPPER, OBJECT_MAPPER]
+        assert dependency_lines("src/App.java", added, repo) == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+            "org.slf4j:slf4j-api@2.0.13",
+        ]
+
+
+class TestSkips:
+    @pytest.mark.parametrize("line", [
+        "import java.util.List;",
+        "import static java.util.Objects.requireNonNull;",
+        "import java.util.concurrent.*;",
+        "import jdk.internal.misc.Unsafe;",
+        "import sun.misc.Unsafe;",
+        "import kotlin.collections.List",
+        "import kotlin.math.max as maximum",
+    ])
+    def test_a_jdk_or_language_import_is_skipped_without_reading(self, line):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("src/App.java", [line], repo) == []
+        assert repo.reads == []
+
+    def test_a_file_whose_every_import_is_skipped_reads_nothing(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        added = ["package com.acme;", "import java.util.List;", "import sun.misc.Unsafe;", "import jdk.jfr.Event;",
+                 "import kotlin.io.println", "class App {}"]
+        assert dependency_lines("src/App.kt", added, repo) == []
+        assert repo.reads == []
+
+    def test_added_lines_without_an_import_read_nothing(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("src/App.java", ["    Logger log = null;", "}"], repo) == []
+        assert repo.reads == []
+
+    def test_kotlinx_is_not_skipped_as_kotlin(self):
+        text = gradle('implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")')
+        repo = Repo({"build.gradle.kts": text})
+        assert dependency_lines("App.kt", ["import kotlinx.coroutines.flow.Flow"], repo) == []
+        assert repo.reads == ["pom.xml", "build.gradle.kts"]
+
+    @pytest.mark.parametrize("path", ["app.py", "src/index.ts", "README.md", "src/App.scala"])
+    def test_a_non_jvm_path_reads_nothing(self, path):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines(path, ["import org.slf4j.Logger", "import os.path"], repo) == []
+        assert repo.reads == []
+
+    def test_imports_under_the_maven_group_are_skipped(self):
+        repo = Repo({"pom.xml": simple_pom(
+            dep("com.acme.app", "app-core", "1.0.0"), dep(*SLF4J_API, "2.0.13"), group="com.acme.app",
+        )})
+        added = ["import com.acme.app.util.Strings;", LOGGER]
+        assert dependency_lines("src/App.java", added, repo) == ["org.slf4j:slf4j-api@2.0.13"]
+
+    def test_imports_under_the_gradle_group_are_skipped(self):
+        text = 'group = "com.acme.app"\n' + gradle(
+            'implementation("com.acme.app:app-core:1.0.0")', 'implementation("org.slf4j:slf4j-api:2.0.13")',
+        )
+        repo = Repo({"build.gradle.kts": text})
+        added = ["import com.acme.app.util.Strings", "import org.slf4j.Logger"]
+        assert dependency_lines("src/App.kt", added, repo) == ["org.slf4j:slf4j-api@2.0.13"]
+
+    def test_the_maven_group_falls_back_to_the_parent_group(self):
+        text = pom(parent("com.acme.app", "acme-parent", "1.0.0", ""), "<artifactId>service</artifactId>",
+                   deps(dep("com.acme.app", "app-core", "1.0.0")))
+        repo = Repo({"pom.xml": text})
+        assert dependency_lines("App.java", ["import com.acme.app.util.Strings;"], repo) == []
+        assert repo.reads == ["pom.xml"]
+
+    def test_when_every_import_is_under_the_own_group_the_manifest_is_still_read(self):
+        repo = Repo({"pom.xml": simple_pom(dep("com.acme.app", "app-core", "1.0.0"), group="com.acme.app")})
+        assert dependency_lines("App.java", ["import com.acme.app.util.Strings;"], repo) == []
+        assert repo.reads == ["pom.xml"]
+
+    def test_the_own_group_is_a_segment_prefix_not_a_string_prefix(self):
+        repo = Repo({"pom.xml": simple_pom(dep("com.acmecorp.billing", "billing-api", "3.1.0"), group="com.acme")})
+        added = ["import com.acmecorp.billing.Invoice;"]
+        assert dependency_lines("App.java", added, repo) == ["com.acmecorp.billing:billing-api@3.1.0"]
+
+
+class TestWalk:
+    def test_probe_order_and_first_hit_stop(self):
+        repo = Repo({
+            "a/pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13")),
+            "pom.xml": simple_pom(dep(*SLF4J_API, "1.7.36")),
+            "build.gradle": gradle("implementation 'org.slf4j:slf4j-api:1.7.0'"),
+        })
+        assert dependency_lines("a/b/C.java", [LOGGER], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+        assert repo.reads == ["a/b/pom.xml", "a/b/build.gradle.kts", "a/b/build.gradle", "a/pom.xml"]
+
+    def test_the_walk_climbs_to_the_repository_root(self):
+        repo = Repo({"build.gradle": gradle("implementation 'org.slf4j:slf4j-api:2.0.13'")})
+        assert dependency_lines("src/main/java/com/acme/App.java", [LOGGER], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+        assert repo.reads == probes(
+            "src/main/java/com/acme", "src/main/java/com", "src/main/java", "src/main", "src", "",
+        )
+
+    def test_no_manifest_anywhere_reads_every_level_once_and_gives_nothing(self):
+        repo = Repo()
+        assert dependency_lines("a/b/C.java", [LOGGER], repo) == []
+        assert repo.reads == probes("a/b", "a", "")
+
+    def test_a_pom_wins_over_gradle_files_at_the_same_level(self):
+        repo = Repo({
+            "pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13")),
+            "build.gradle.kts": gradle('implementation("org.slf4j:slf4j-api:1.7.36")'),
+        })
+        assert dependency_lines("App.java", [LOGGER], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+        assert repo.reads == ["pom.xml"]
+
+    def test_the_kotlin_build_script_wins_over_the_groovy_one(self):
+        repo = Repo({
+            "build.gradle.kts": gradle('implementation("org.slf4j:slf4j-api:2.0.13")'),
+            "build.gradle": gradle("implementation 'org.slf4j:slf4j-api:1.7.36'"),
+        })
+        assert dependency_lines("App.java", [LOGGER], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+        assert repo.reads == ["pom.xml", "build.gradle.kts"]
+
+    def test_an_empty_manifest_is_a_miss_and_the_walk_continues(self):
+        repo = Repo({"a/pom.xml": "", "pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("a/C.java", [LOGGER], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+        assert repo.reads == probes("a") + ["pom.xml"]
+
+    def test_a_read_that_raises_is_a_miss_and_the_walk_continues(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))}, raising=frozenset({"a/pom.xml"}))
+        assert dependency_lines("a/C.java", [LOGGER], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+        assert repo.reads == probes("a") + ["pom.xml"]
+
+    def test_a_read_that_is_not_text_is_a_miss(self):
+        repo = Repo({"a/pom.xml": b"<project/>", "pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("a/C.java", [LOGGER], repo) == ["org.slf4j:slf4j-api@2.0.13"]
+
+    def test_a_reader_that_always_raises_gives_nothing(self):
+        repo = Repo(raising=frozenset(probes("a", "")))
+        assert dependency_lines("a/C.java", [LOGGER], repo) == []
+        assert repo.reads == probes("a", "")
+
+    def test_no_path_is_read_twice_when_a_parent_points_back_at_a_probed_miss(self):
+        child = pom(parent("com.acme", "acme-parent", "1.0.0", "b/pom.xml"), "<artifactId>a</artifactId>",
+                    deps(dep(*DATABIND)))
+        repo = Repo({"a/pom.xml": child})
+        assert dependency_lines("a/b/C.java", [OBJECT_MAPPER], repo) == [
+            "com.fasterxml.jackson.core:jackson-databind@(managed by com.acme:acme-parent@1.0.0)",
+        ]
+        assert repo.reads == ["a/b/pom.xml", "a/b/build.gradle.kts", "a/b/build.gradle", "a/pom.xml"]
+
+
+class TestBrokenManifests:
+    def test_a_malformed_pom_contributes_nothing_and_stops_the_walk(self):
+        repo = Repo({
+            "a/pom.xml": "<project><dependencies><dependency><groupId>org.slf4j",
+            "pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13")),
+        })
+        assert dependency_lines("a/C.java", [LOGGER], repo) == []
+        assert repo.reads == ["a/pom.xml"]
+
+    def test_a_doctype_pom_is_refused_and_stops_the_walk(self):
+        doctype = pom(coords("com.acme", "app"), deps(dep(*SLF4J_API, "2.0.13")), prolog="<!DOCTYPE project>\n")
+        control = Repo({"a/pom.xml": doctype.replace("<!DOCTYPE project>\n", "")})
+        assert dependency_lines("a/C.java", [LOGGER], control) == ["org.slf4j:slf4j-api@2.0.13"]
+        repo = Repo({"a/pom.xml": doctype, "pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("a/C.java", [LOGGER], repo) == []
+        assert repo.reads == ["a/pom.xml"]
+
+    def test_a_broken_catalog_contributes_nothing_and_stops_the_walk(self):
+        catalog = (
+            '[versions]\njackson = "2.17.1"\n[libraries]\n'
+            'jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }\n'
+        )
+        files = {
+            "a/build.gradle.kts": gradle("implementation(libs.jackson.databind)"),
+            "a/gradle/libs.versions.toml": catalog,
+            "build.gradle.kts": gradle('implementation("com.fasterxml.jackson.core:jackson-databind:2.16.0")'),
+        }
+        control = Repo(files)
+        assert dependency_lines("a/C.java", [OBJECT_MAPPER], control) == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+        ]
+        repo = Repo({**files, "a/gradle/libs.versions.toml": "[libraries\njackson-databind = "})
+        assert dependency_lines("a/C.java", [OBJECT_MAPPER], repo) == []
+        assert repo.reads == ["a/pom.xml", "a/build.gradle.kts", "a/gradle/libs.versions.toml"]
+
+    def test_an_unparseable_build_file_contributes_nothing_and_stops_the_walk(self):
+        repo = Repo({
+            "a/build.gradle": "plugins {{{ ((( 'org.slf4j:slf4j-api \x00\x01",
+            "build.gradle": gradle("implementation 'org.slf4j:slf4j-api:2.0.13'"),
+        })
+        assert dependency_lines("a/C.java", [LOGGER], repo) == []
+        assert repo.reads == probes("a")
+
+
+class TestGradle:
+    def test_a_version_ref_catalog_library_resolves(self):
+        catalog = (
+            '[versions]\njackson = "2.17.1"\n\n[libraries]\n'
+            'jackson-core = { module = "com.fasterxml.jackson.core:jackson-core", version.ref = "jackson" }\n'
+            'jackson-databind = { group = "com.fasterxml.jackson.core", name = "jackson-databind", '
+            'version.ref = "jackson" }\n'
+        )
+        repo = Repo({
+            "app/build.gradle.kts": gradle(
+                "implementation(libs.jackson.databind)", "implementation(libs.jackson.core)",
+            ),
+            "gradle/libs.versions.toml": catalog,
+        })
+        assert dependency_lines("app/Main.java", [OBJECT_MAPPER], repo) == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+        ]
+        assert repo.reads == [
+            "app/pom.xml", "app/build.gradle.kts",
+            "app/gradle/libs.versions.toml", "app/libs.versions.toml", "gradle/libs.versions.toml",
+        ]
+
+    def test_a_platform_owns_a_versionless_dependency(self):
+        repo = Repo({"build.gradle": gradle(
+            "implementation platform('org.springframework.boot:spring-boot-dependencies:3.3.4')",
+            "implementation 'com.fasterxml.jackson.core:jackson-databind'",
+        )})
+        assert dependency_lines("App.java", [OBJECT_MAPPER], repo) == [DATABIND_BY_SPRING]
+
+    def test_the_owner_is_the_platform_sharing_the_most_group_segments(self):
+        repo = Repo({"build.gradle.kts": gradle(
+            'implementation(platform("org.springframework.boot:spring-boot-dependencies:3.3.4"))',
+            'implementation(enforcedPlatform("com.fasterxml.jackson:jackson-bom:2.17.1"))',
+            'implementation("com.fasterxml.jackson.core:jackson-databind")',
+            'implementation("org.slf4j:slf4j-api")',
+            'implementation("io.micrometer:micrometer-core")',
+        )})
+        added = [OBJECT_MAPPER, LOGGER, "import io.micrometer.core.instrument.MeterRegistry;"]
+        assert dependency_lines("App.java", added, repo) == [
+            "com.fasterxml.jackson.core:jackson-databind@(managed by com.fasterxml.jackson:jackson-bom@2.17.1)",
+            "io.micrometer:micrometer-core@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)",
+            "org.slf4j:slf4j-api@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)",
+        ]
+
+    def test_a_platform_without_a_version_renders_without_one(self):
+        repo = Repo({"build.gradle.kts": gradle(
+            'implementation(platform("org.springframework.boot:spring-boot-dependencies"))',
+            'implementation("com.fasterxml.jackson.core:jackson-databind")',
+        )})
+        assert dependency_lines("App.java", [OBJECT_MAPPER], repo) == [
+            "com.fasterxml.jackson.core:jackson-databind"
+            "@(managed by org.springframework.boot:spring-boot-dependencies)",
+        ]
+
+    def test_a_catalog_platform_owns_a_versionless_dependency(self):
+        catalog = (
+            '[versions]\nboot = "3.3.4"\n[libraries]\n'
+            'spring-boot-bom = { module = "org.springframework.boot:spring-boot-dependencies", version.ref = "boot" }\n'
+        )
+        repo = Repo({
+            "build.gradle.kts": gradle(
+                "implementation(platform(libs.spring.boot.bom))",
+                'implementation("com.fasterxml.jackson.core:jackson-databind")',
+            ),
+            "gradle/libs.versions.toml": catalog,
+        })
+        assert dependency_lines("App.java", [OBJECT_MAPPER], repo) == [DATABIND_BY_SPRING]
+
+    def test_a_versionless_dependency_without_a_platform_gets_no_line(self):
+        repo = Repo({"build.gradle.kts": gradle('implementation("com.fasterxml.jackson.core:jackson-databind")')})
+        assert dependency_lines("App.java", [OBJECT_MAPPER], repo) == []
+
+
+class TestMaven:
+    def test_an_imported_bom_names_the_owner(self):
+        repo = Repo({"pom.xml": pom(
+            coords("com.acme", "app"),
+            props(**{"spring-boot.version": "3.3.4"}),
+            managed(dep(*SPRING_BOM, "${spring-boot.version}", bom=True)),
+            deps(dep(*DATABIND)),
+        )})
+        assert dependency_lines("App.java", [OBJECT_MAPPER], repo) == [DATABIND_BY_SPRING]
+
+    def test_a_property_in_an_in_repository_parent_resolves_the_version(self):
+        parent_pom = pom(
+            coords("com.acme", "acme-parent"),
+            props(**{"jackson.version": "2.17.1"}),
+            managed(dep(*DATABIND, "${jackson.version}")),
+        )
+        child = pom(parent("com.acme", "acme-parent", "1.0.0"), "<artifactId>api</artifactId>", deps(dep(*DATABIND)))
+        repo = Repo({"pom.xml": parent_pom, "api/pom.xml": child})
+        assert dependency_lines("api/src/Controller.java", [OBJECT_MAPPER], repo) == [
+            "com.fasterxml.jackson.core:jackson-databind@2.17.1",
+        ]
+        assert repo.reads == probes("api/src") + ["api/pom.xml", "pom.xml"]
+
+    def test_a_winning_dependency_with_no_version_and_no_owner_gets_no_line(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*DATABIND), dep(*JACKSON_CORE, "2.17.1"))})
+        assert dependency_lines("App.java", [OBJECT_MAPPER], repo) == []
+
+
+class TestLanguages:
+    @pytest.mark.parametrize(("path", "added"), [
+        ("src/App.java", [LOGGER]),
+        ("src/App.kt", ["import org.slf4j.Logger"]),
+        ("src/tool.main.kts", ["import org.slf4j.Logger"]),
+        ("src/App.KT", ["import org.slf4j.Logger"]),
+    ])
+    def test_java_kotlin_and_kotlin_script_files_behave_alike(self, path, added):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines(path, added, repo) == ["org.slf4j:slf4j-api@2.0.13"]
+        assert repo.reads == probes("src") + ["pom.xml"]
+
+
+class TestNeverRaises:
+    def test_a_non_text_added_line_gives_nothing(self):
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("App.java", [LOGGER, None], repo) == []
+
+    def test_a_reader_that_is_not_callable_gives_nothing(self):
+        assert dependency_lines("App.java", [LOGGER], None) == []
+
+    def test_a_failing_parser_gives_nothing(self, monkeypatch):
+        def explode(*args, **kwargs):
+            raise RuntimeError("boom")
+
+        monkeypatch.setattr(jvm_deps.jvm_maven, "resolve_pom", explode)
+        repo = Repo({"pom.xml": simple_pom(dep(*SLF4J_API, "2.0.13"))})
+        assert dependency_lines("App.java", [LOGGER], repo) == []

From 062ea2c195f775aaeca4d199dc79751e7e6ab8db Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:34:55 -0700
Subject: [PATCH 10/25] feat: add readers of shared state to repository context
 at repo (#22)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

At PRXREF_REPO_CONTEXT=repo, build_unit_context gains a fourth source
after the resolver: repo_readers.reader_entries over the chunk's files,
with the same guarded reader (so excluded paths are never read and the
readers get only the chunk reads the resolver left), every PR diff path
as diff_paths (a diff file is never a candidate), and the exclude
predicate. It runs only with a reader and a file listing, never at diff
or off, and reads repo_readers.MAX_READER_ENTRIES and MAX_READER_SCAN at
call time, so zeroing MAX_READER_ENTRIES switches readers off.

The entries have kind "reader" and reason "shared-state", both appended
last to KINDS and REASONS, so the budget cuts them first. They render in
their own last prompt block, "### Code elsewhere that reads state this
chunk writes": UnitContext gains a trailing reader_lines field, _admit
routes reader entries there (the omitted marker follows the first entry
left out, readers included), render_context_blocks takes reader_lines
last, and the orchestrator's _context_blocks passes it. With no reader
lines every prompt renders byte-identically to before.

docs/env-vars.md's PRXREF_REPO_CONTEXT row names the readers. The two
tests that pin REASONS and KINDS are re-pinned, and the admission-rank
test now includes a shared-state entry. New tests cover the levels, the
listing, exclusion, diff-file candidates, the shared chunk cap, the
runtime switch, the budget, record rows, rendering and the #22 shape.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 docs/env-vars.md                |   2 +-
 src/prxref/chunk_context.py     |  15 +-
 src/prxref/orchestrator.py      |  17 +-
 src/prxref/repo_context.py      |   4 +-
 src/prxref/repo_unit.py         |  69 ++-
 tests/test_repo_context_defs.py |   4 +-
 tests/test_repo_context_unit.py |   3 +-
 tests/test_repo_unit_readers.py | 754 ++++++++++++++++++++++++++++++++
 8 files changed, 833 insertions(+), 35 deletions(-)
 create mode 100644 tests/test_repo_unit_readers.py

diff --git a/docs/env-vars.md b/docs/env-vars.md
index 203b82c..9cc045b 100644
--- a/docs/env-vars.md
+++ b/docs/env-vars.md
@@ -56,7 +56,7 @@ Configuration is loaded from built-in defaults, overridden by environment variab
 | `PRXREF_PROMPTS_DIR` | *(empty — off)* | **Prompt template overrides (0.15.0).** Directory holding replacement `worker.md`, `systemic.md` and `summary.md` prompt templates; a file that is absent keeps the packaged one. Every template is validated before any network call: `worker.md` and `systemic.md` must keep the `## Review Context` marker and every packaged placeholder below it (the feature slots `{scope_example}` and `{rule_example}` are optional), and `summary.md` needs only `{findings}`. A missing directory, a failed check, or a template over 256 KiB raises `ConfigError` and `prxref review` exits `2`; an empty directory or an unknown placeholder only warns. The run record's `prompt_templates` stamps the directory and, for each template file present in it, edited or not, its path, SHA-256 and length; a template absent from the directory has no entry. `--prompts-dir DIR` wins for one run, and `prxref prompts export DIR [--force]` writes the packaged templates to start from. The judge prompt of `prxref eval` cannot be overridden. Read it from a trusted checkout: a PR that commits a template rewrites its own review. Unset uses the packaged templates, byte for byte. |
 | `PRXREF_TICKET_CONTEXT_FILE` | *(empty — off)* | Plain-text or Markdown file holding the ticket this PR implements. When set, every finding is marked in, out of, or of unknown ticket scope. An empty or whitespace-only file means "this PR has no ticket". A missing or non-UTF-8 file raises `ConfigError` and `prxref review` exits `2`. The webhook daemon ignores it (and says so once). `--context-file PATH` wins for one run, and `--context-file ""` turns it off. |
 | `PRXREF_TICKET_CONTEXT_MAX_CHARS` | `6000` | Characters of ticket text kept in the prompt; longer text is truncated with a visible marker. Must be **greater than 0**. |
-| `PRXREF_REPO_CONTEXT` | `off` | **Repository context (0.16.0).** `off` (the default) leaves every prompt, post, trace and default-verbosity log byte-identical to 0.15.0. `diff` adds definitions from the PR's own changed files (`cross-chunk` and `diff-file` entries, Java type declarations included): those files are read at the PR head through the forge's repository reader, or `--repo-dir`, when one is available, and without a reader the entries are built from the diff's hunk lines alone, with no warning. `repo` additionally reads files outside the diff — import, path-convention and name-search definitions, plus contract excerpts — through the same reader, and logs one WARNING when there is no reader or no file listing. Only the chunk workers' prompts carry repository context; the whole-PR sweep prompt is unchanged. Matching is exact and case-sensitive, like `PRXREF_FAIL_ON`: `Repo` or `REPO` is rejected. Any value outside `off`\|`diff`\|`repo` raises `ConfigError` and `prxref review` exits `2`. |
+| `PRXREF_REPO_CONTEXT` | `off` | **Repository context (0.16.0).** `off` (the default) leaves every prompt, post, trace and default-verbosity log byte-identical to 0.15.0. `diff` adds definitions from the PR's own changed files (`cross-chunk` and `diff-file` entries, Java type declarations included): those files are read at the PR head through the forge's repository reader, or `--repo-dir`, when one is available, and without a reader the entries are built from the diff's hunk lines alone, with no warning. `repo` additionally reads files outside the diff — import, path-convention and name-search definitions, contract excerpts and, since 0.17.0, readers (`shared-state` entries: excerpts from non-diff files that read state the chunk's added lines write, found only with a file listing and ranked last, so the budget cuts them first) — through the same reader, and logs one WARNING when there is no reader or no file listing. Only the chunk workers' prompts carry repository context; the whole-PR sweep prompt is unchanged. Matching is exact and case-sensitive, like `PRXREF_FAIL_ON`: `Repo` or `REPO` is rejected. Any value outside `off`\|`diff`\|`repo` raises `ConfigError` and `prxref review` exits `2`. |
 | `PRXREF_REPO_CONTEXT_MAX_CHARS` | `12000` | **Repository context (0.16.0).** Per-chunk character budget shared by the cross-chunk, contract and other repository-context entries admitted under `PRXREF_REPO_CONTEXT`. Must be **greater than 0**. |
 | `PRXREF_CONTEXT_CONTRACT_GLOBS` | the built-in set below | **Repository context (0.16.0).** Globs (matched like `PRXREF_SIZE_IGNORE_GLOBS`: case-sensitive `fnmatch`, `*` crosses `/`) selecting the contract files — OpenAPI, JSON Schema, Liquibase/SQL migrations — excerpted under `repo`. A set value **REPLACES** the built-in set below, rather than adding to it; an empty value reads as unset, so the built-in set stays. There is no way to turn contract excerpts off on their own in 0.16.0 — set `PRXREF_REPO_CONTEXT` to `off` or `diff` instead. Built-in set: `**/openapi*.y*ml`, `**/openapi*.json`, `**/openapi/**`, `**/swagger*`, `**/*.schema.json`, `**/db/changelog/**`, `**/db/migration/**`, `**/migrations/**`. |
 | `PRXREF_CONTEXT_EXCLUDE_GLOBS` | *(empty)* | **Repository context (0.16.0).** Globs (matched like `PRXREF_SIZE_IGNORE_GLOBS`) whose paths are never read for repository context, not even a diff file. **Added** to a floor that is always on: `**/expected.json`, `**/cases.json`, `**/case.json`, `**/prxref-eval/**`, `**/.env*`, `**/*.pem`, `**/*.key`. Empty (the default) adds nothing. |
diff --git a/src/prxref/chunk_context.py b/src/prxref/chunk_context.py
index 265ccc2..b9f6716 100644
--- a/src/prxref/chunk_context.py
+++ b/src/prxref/chunk_context.py
@@ -40,6 +40,7 @@
 DEFINITIONS_HEADER = "### Definitions referenced by this chunk"
 SIBLING_HEADER = "### Other files changed in this PR"
 CONTRACT_HEADER = "### Contract excerpts"
+READER_HEADER = "### Code elsewhere that reads state this chunk writes"
 
 _JS_SUFFIXES = (".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts")
 
@@ -450,6 +451,7 @@ def render_context_blocks(
     def_lines: Sequence[str],
     extra_def_lines: Sequence[str] = (),
     contract_lines: Sequence[str] = (),
+    reader_lines: Sequence[str] = (),
 ) -> str:
     """Render the prompt blocks, omitting each when it has no lines.
 
@@ -457,10 +459,13 @@ def render_context_blocks(
     ``def_lines`` followed by ``extra_def_lines`` (repository-context
     definitions) under one :data:`DEFINITIONS_HEADER`, and is present when
     either is non-empty. The contracts block, ``contract_lines`` under
-    :data:`CONTRACT_HEADER`, comes last. With the two optional arguments
-    empty, the output is exactly the two-block rendering repository context
-    predates. Returns the empty string when every list is empty, so the
-    prompt slot leaves no stray header behind.
+    :data:`CONTRACT_HEADER`, comes next, and the readers block,
+    ``reader_lines`` (code outside the diff that reads state the chunk
+    writes) under :data:`READER_HEADER`, comes last. With the three optional
+    arguments empty, the output is exactly the two-block rendering repository
+    context predates, and with ``reader_lines`` empty it is exactly the
+    rendering without a readers block. Returns the empty string when every
+    list is empty, so the prompt slot leaves no stray header behind.
     """
     blocks: list[str] = []
     if dep_lines:
@@ -470,6 +475,8 @@ def render_context_blocks(
         blocks.append(DEFINITIONS_HEADER + "\n\n" + "\n".join(definitions))
     if contract_lines:
         blocks.append(CONTRACT_HEADER + "\n\n" + "\n".join(contract_lines))
+    if reader_lines:
+        blocks.append(READER_HEADER + "\n\n" + "\n".join(reader_lines))
     return "\n\n".join(blocks)
 
 
diff --git a/src/prxref/orchestrator.py b/src/prxref/orchestrator.py
index 3715562..2cc1066 100644
--- a/src/prxref/orchestrator.py
+++ b/src/prxref/orchestrator.py
@@ -1878,17 +1878,18 @@ def read(path: str) -> str | None:
 def _context_blocks(
     chunk, reader, *, include_definitions: bool, unit: repo_unit.UnitContext | None = None,
 ) -> str:
-    """Render the chunk's dependency, definition and contract blocks; never raises.
+    """Render the chunk's dependency, definition, contract and reader blocks; never raises.
 
     ``unit`` is the chunk's repository context. Its definition lines follow
-    the same-file definitions under one header and its contract lines form
-    the contracts block; they render with no ``reader`` too, over empty
-    dependency and same-file lists. ``None``, or a unit with no lines, is
-    exactly the rendering without repository context.
+    the same-file definitions under one header, its contract lines form the
+    contracts block and its reader lines the last block; they render with no
+    ``reader`` too, over empty dependency and same-file lists. ``None``, or a
+    unit with no lines, is exactly the rendering without repository context.
     """
     extra = unit.definition_lines if unit is not None else ()
     contracts = unit.contract_lines if unit is not None else ()
-    if reader is None and not (extra or contracts):
+    readers = unit.reader_lines if unit is not None else ()
+    if reader is None and not (extra or contracts or readers):
         return ""
     deps: list[str] = []
     defs: list[str] = []
@@ -1902,12 +1903,12 @@ def _context_blocks(
             )
         except Exception as e:  # noqa: BLE001
             logger.debug("chunk context unavailable: %s", e)
-            if not (extra or contracts):
+            if not (extra or contracts or readers):
                 return ""
             deps, defs = [], []
     try:
         return chunk_context.render_context_blocks(
-            deps, defs, extra_def_lines=extra, contract_lines=contracts,
+            deps, defs, extra_def_lines=extra, contract_lines=contracts, reader_lines=readers,
         )
     except Exception as e:  # noqa: BLE001
         logger.debug("chunk context unavailable: %s", e)
diff --git a/src/prxref/repo_context.py b/src/prxref/repo_context.py
index 909bb73..4e39bca 100644
--- a/src/prxref/repo_context.py
+++ b/src/prxref/repo_context.py
@@ -28,8 +28,8 @@
 from . import chunk_context
 from .rules import match_globs
 
-REASONS = ("cross-chunk", "contract", "diff-file", "import", "path-convention", "name-search")
-KINDS = ("definition", "contract")
+REASONS = ("cross-chunk", "contract", "diff-file", "import", "path-convention", "name-search", "shared-state")
+KINDS = ("definition", "contract", "reader")
 
 _JAVA_DEF_RE = re.compile(
     r"^\s*(?:(?:@(?!interface\b)[A-Za-z_$][\w$.]*(?:\((?:[^()]|\([^()]*\))*\))?"
diff --git a/src/prxref/repo_unit.py b/src/prxref/repo_unit.py
index 374a91f..3e3d278 100644
--- a/src/prxref/repo_unit.py
+++ b/src/prxref/repo_unit.py
@@ -1,6 +1,6 @@
 """One worker chunk's repository context: sources, order, budget and exclusion (#17).
 
-:func:`build_unit_context` combines the three repository-context sources for
+:func:`build_unit_context` combines the four repository-context sources for
 one chunk into the lines its prompt carries:
 
 1. :func:`prxref.repo_crosschunk.diff_definitions`: definitions from the PR's
@@ -11,7 +11,10 @@
 3. the resolver, :func:`prxref.repo_resolve.resolve_candidates` plus
    :func:`prxref.repo_context.find_definitions` over the candidate files
    (``import``, ``path-convention``, ``name-search``), at the ``repo`` level
-   only.
+   only;
+4. :func:`prxref.repo_readers.reader_entries`: excerpts of code outside the
+   diff that reads shared state the chunk's added lines write
+   (``shared-state``, #22), at the ``repo`` level with a file listing only.
 
 The sources are called in that order, which is their admission rank, so under
 a capped reader the higher-ranked sources get their reads first. Every read
@@ -32,6 +35,7 @@
 from collections.abc import Callable, Collection, Sequence
 from dataclasses import dataclass
 
+from . import repo_readers
 from .chunk_context import chunk_files
 from .repo_context import (
     REASONS,
@@ -52,19 +56,23 @@
 class UnitContext:
     """The repository context admitted into one worker chunk's prompt.
 
-    ``definition_lines`` and ``contract_lines`` are the rendered admitted
-    entries of each kind, in admission order, ready for
-    :func:`prxref.chunk_context.render_context_blocks` as ``extra_def_lines``
-    and ``contract_lines``; when entries were left out, one omitted line (a
-    horizontal ellipsis, then ``N more context entries omitted``) ends the
-    list of the kind of the first entry left out. ``entries`` holds the admitted entries in
-    admission order, and ``omitted`` counts the entries the budget left out.
+    ``definition_lines``, ``contract_lines`` and ``reader_lines`` are the
+    rendered admitted entries of kind ``definition``, ``contract`` and
+    ``reader``, in admission order, ready for
+    :func:`prxref.chunk_context.render_context_blocks` as ``extra_def_lines``,
+    ``contract_lines`` and ``reader_lines``; when entries were left out, one
+    omitted line (a horizontal ellipsis, then ``N more context entries
+    omitted``) ends the list of the kind of the first entry left out.
+    ``entries`` holds the admitted entries in admission order, and
+    ``omitted`` counts the entries the budget left out. ``reader_lines`` comes
+    last and defaults to empty, so a unit built without it is unchanged.
     """
 
     definition_lines: tuple[str, ...]
     contract_lines: tuple[str, ...]
     entries: tuple[ContextEntry, ...]
     omitted: int
+    reader_lines: tuple[str, ...] = ()
 
     def record(self) -> dict:
         """The run-record row for this chunk: ``{"entries": [...], "omitted": N}``."""
@@ -158,6 +166,10 @@ def _merge(entries: list[ContextEntry], exclude: Callable[[str], bool] | None) -
     return out
 
 
+def _block(kind: str) -> str:
+    return kind if kind in ("definition", "reader") else "contract"
+
+
 def _admit(entries: list[ContextEntry], max_chars: int) -> UnitContext:
     admitted: list[ContextEntry] = []
     used = 0
@@ -168,15 +180,19 @@ def _admit(entries: list[ContextEntry], max_chars: int) -> UnitContext:
         admitted.append(entry)
         used += size
     omitted = len(entries) - len(admitted)
-    definition_lines = [entry.rendered() for entry in admitted if entry.kind == "definition"]
-    contract_lines = [entry.rendered() for entry in admitted if entry.kind != "definition"]
+    lines: dict[str, list[str]] = {"definition": [], "contract": [], "reader": []}
+    for entry in admitted:
+        lines[_block(entry.kind)].append(entry.rendered())
     if omitted:
         marker = f"\N{HORIZONTAL ELLIPSIS} {omitted} more context entries omitted"
-        if entries[len(admitted)].kind == "definition":
-            definition_lines.append(marker)
-        else:
-            contract_lines.append(marker)
-    return UnitContext(tuple(definition_lines), tuple(contract_lines), tuple(admitted), omitted)
+        lines[_block(entries[len(admitted)].kind)].append(marker)
+    return UnitContext(
+        tuple(lines["definition"]),
+        tuple(lines["contract"]),
+        tuple(admitted),
+        omitted,
+        tuple(lines["reader"]),
+    )
 
 
 def build_unit_context(
@@ -225,7 +241,16 @@ def build_unit_context(
        all found already, with no read. Each other path is read once, and
        :func:`prxref.repo_context.find_definitions` over it gives a
        ``definition`` entry whose reason is that name's candidate reason
-       there; its symbol then counts as found.
+       there; its symbol then counts as found;
+    4. at ``"repo"`` with a reader and a ``listing_paths`` that is not None,
+       :func:`prxref.repo_readers.reader_entries` over the chunk's files,
+       with the same guarded reader, so it gets only the reads the chunk's
+       cap has left after the resolver, every PR diff file's path as
+       ``diff_paths``, so a diff file is never a candidate, and ``exclude``.
+       It gives ``reader`` entries with reason ``shared-state``: excerpts of
+       non-diff files that read state the chunk's added lines write. Its
+       caps, :data:`prxref.repo_readers.MAX_READER_ENTRIES` and
+       :data:`prxref.repo_readers.MAX_READER_SCAN`, are read when it runs.
 
     ``"repo"`` with ``read`` None is exactly ``"diff"`` with ``read`` None.
 
@@ -263,4 +288,14 @@ def build_unit_context(
                 found=found,
             )
         )
+    if mode == "repo" and guarded is not None and listing_paths is not None:
+        entries.extend(
+            repo_readers.reader_entries(
+                chunk_files(chunk),
+                listing=listing_paths,
+                read=guarded,
+                diff_paths={getattr(f, "path", "") for f in all_files},
+                exclude=exclude,
+            )
+        )
     return _admit(_merge(entries, exclude), max_chars)
diff --git a/tests/test_repo_context_defs.py b/tests/test_repo_context_defs.py
index 0261a44..6fce2cd 100644
--- a/tests/test_repo_context_defs.py
+++ b/tests/test_repo_context_defs.py
@@ -40,11 +40,11 @@ def _java_match(line: str) -> str | None:
 class TestVocabulary:
     def test_reasons_order_is_the_admission_rank(self):
         assert REASONS == (
-            "cross-chunk", "contract", "diff-file", "import", "path-convention", "name-search",
+            "cross-chunk", "contract", "diff-file", "import", "path-convention", "name-search", "shared-state",
         )
 
     def test_kinds(self):
-        assert KINDS == ("definition", "contract")
+        assert KINDS == ("definition", "contract", "reader")
 
 
 class TestLanguageOf:
diff --git a/tests/test_repo_context_unit.py b/tests/test_repo_context_unit.py
index bbe5cf5..e813023 100644
--- a/tests/test_repo_context_unit.py
+++ b/tests/test_repo_context_unit.py
@@ -439,6 +439,7 @@ def test_reason_rank_beats_path(self, canned):
         canned.sources["diff"] = [_entry("a/x.java", 1, "diff-file"), _entry("z/y.java", 1, "cross-chunk")]
         canned.sources["contract"] = [_entry("y/spec.yaml", 1, "contract", kind="contract")]
         canned.sources["resolver"] = [
+            _entry("d/r.java", 1, "shared-state", kind="reader"),
             _entry("a/n.java", 1, "name-search"),
             _entry("b/p.java", 1, "path-convention"),
             _entry("c/i.java", 1, "import"),
@@ -448,7 +449,7 @@ def test_reason_rank_beats_path(self, canned):
 
         assert [e.reason for e in unit.entries] == list(REASONS)
         assert [e.path for e in unit.entries] == [
-            "z/y.java", "y/spec.yaml", "a/x.java", "c/i.java", "b/p.java", "a/n.java",
+            "z/y.java", "y/spec.yaml", "a/x.java", "c/i.java", "b/p.java", "a/n.java", "d/r.java",
         ]
 
     def test_within_a_reason_path_then_line(self, canned):
diff --git a/tests/test_repo_unit_readers.py b/tests/test_repo_unit_readers.py
new file mode 100644
index 0000000..ccf3a29
--- /dev/null
+++ b/tests/test_repo_unit_readers.py
@@ -0,0 +1,754 @@
+"""Tests for readers of shared state in the per-chunk repository context (issue #22).
+
+Covers the fourth source of :func:`prxref.repo_unit.build_unit_context`:
+:func:`prxref.repo_readers.reader_entries` runs at ``repo`` only, with a
+reader and a file listing, after the resolver and on the chunk reads the
+resolver left. Its ``reader`` / ``shared-state`` entries are ranked last,
+render under their own :data:`prxref.chunk_context.READER_HEADER` block, and
+reach the prompt through :func:`prxref.orchestrator._context_blocks`. The
+last class runs the #22 fixture's shape through the production reader over
+inline copies of the fixture's head files. No test touches the network.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from prxref import orchestrator, repo_readers
+from prxref.chunk_context import (
+    CONTRACT_HEADER,
+    DEFINITIONS_HEADER,
+    DEPENDENCY_HEADER,
+    READER_HEADER,
+    render_context_blocks,
+)
+from prxref.repo_context import REASONS, ContextEntry, exclude_predicate
+from prxref.repo_reader import RepoReader
+from prxref.repo_unit import EMPTY_UNIT, UnitContext, build_unit_context
+
+MAX_CHARS = 12000
+
+
+def _omitted(count: int) -> str:
+    return f"\N{HORIZONTAL ELLIPSIS} {count} more context entries omitted"
+
+
+class _Recording:
+    """Wraps a ``read(path)`` callable and records every path asked for, in call order."""
+
+    def __init__(self, read):
+        self.read = read
+        self.calls: list[str] = []
+
+    def __call__(self, path: str) -> str | None:
+        self.calls.append(path)
+        return self.read(path)
+
+
+def _file(path: str, text: str, *, added: set[int] | None = None, status: str = "modified") -> SimpleNamespace:
+    """A FileDiff stand-in with one hunk over all of ``text``; lines in ``added`` (1-based) are ``+``, all when None."""
+    lines = []
+    for number, line in enumerate(text.splitlines(), start=1):
+        kind = "+" if added is None or number in added else " "
+        lines.append(SimpleNamespace(kind=kind, text=line, new_line=number))
+    return SimpleNamespace(path=path, status=status, hunks=[SimpleNamespace(lines=lines)])
+
+
+def _readers(unit: UnitContext) -> list[ContextEntry]:
+    return [entry for entry in unit.entries if entry.kind == "reader"]
+
+
+def _keys(entries) -> list[tuple[str, int, str, str, str]]:
+    return [(e.path, e.line, e.symbol, e.kind, e.reason) for e in entries]
+
+
+WRITER = "pkg/writer.py"
+READER = "pkg/reader.py"
+OTHER = "pkg/other.py"
+
+WRITER_TEXT = """\
+class Writer:
+    def remember(self, k, v):
+        self.cache[k] = v
+"""
+
+READER_TEXT = """\
+def lookup(store, k):
+    return store.cache.get(k)
+"""
+
+FILES = {WRITER: WRITER_TEXT, READER: READER_TEXT, OTHER: READER_TEXT, "pkg/unrelated.py": "X = 1\n"}
+LISTING = frozenset(FILES)
+
+
+def _simple(mode: str, *, read=None, listing=LISTING, all_files=None, **overrides) -> UnitContext:
+    chunk = [_file(WRITER, WRITER_TEXT, added={3})]
+    kwargs = dict(
+        mode=mode,
+        read=read if read is not None else _Recording(FILES.get),
+        max_chars=MAX_CHARS,
+        listing_paths=listing,
+        listing_complete=True,
+    )
+    kwargs.update(overrides)
+    return build_unit_context(chunk, all_files if all_files is not None else chunk, **kwargs)
+
+
+class TestLevels:
+    def test_repo_with_a_listing_and_a_reader_gets_the_reader_entry(self):
+        unit = _simple("repo")
+
+        assert _keys(_readers(unit)) == [
+            (OTHER, 1, "cache", "reader", "shared-state"),
+            (READER, 1, "cache", "reader", "shared-state"),
+        ]
+        assert unit.reader_lines == tuple(entry.rendered() for entry in _readers(unit))
+        assert unit.reader_lines[0] == f"{OTHER}:1: def lookup(store, k):\n    return store.cache.get(k)"
+        assert unit.contract_lines == ()
+
+    @pytest.mark.parametrize("mode", ["diff", "off"])
+    def test_diff_and_off_have_no_readers_even_with_a_listing_and_a_reader(self, mode):
+        read = _Recording(FILES.get)
+        unit = _simple(mode, read=read)
+
+        assert _readers(unit) == []
+        assert unit.reader_lines == ()
+        assert READER not in read.calls and OTHER not in read.calls
+
+    def test_off_is_still_the_empty_unit(self):
+        read = _Recording(FILES.get)
+        assert _simple("off", read=read) is EMPTY_UNIT
+        assert read.calls == []
+
+    def test_repo_without_a_reader_has_no_readers(self):
+        unit = build_unit_context(
+            [_file(WRITER, WRITER_TEXT, added={3})], [_file(WRITER, WRITER_TEXT, added={3})],
+            mode="repo", read=None, max_chars=MAX_CHARS, listing_paths=LISTING, listing_complete=True,
+        )
+        assert _readers(unit) == []
+
+
+class TestListing:
+    def test_no_listing_gives_no_readers_and_no_extra_reads(self, monkeypatch):
+        without = _Recording(FILES.get)
+        unit = _simple("repo", read=without, listing=None)
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+        switched_off = _Recording(FILES.get)
+        _simple("repo", read=switched_off, listing=None)
+
+        assert _readers(unit) == []
+        assert without.calls == switched_off.calls
+
+    def test_control_the_listing_is_what_adds_the_reads(self):
+        with_listing = _Recording(FILES.get)
+        without = _Recording(FILES.get)
+        _simple("repo", read=with_listing)
+        _simple("repo", read=without, listing=None)
+
+        assert with_listing.calls[: len(without.calls)] == without.calls
+        assert with_listing.calls[len(without.calls):] == [OTHER, READER, "pkg/unrelated.py"]
+
+
+class TestPathsNeverRead:
+    def test_an_excluded_candidate_is_never_read(self):
+        read = _Recording(FILES.get)
+        unit = _simple("repo", read=read, exclude=lambda path: path == READER)
+
+        assert READER not in read.calls
+        assert [e.path for e in _readers(unit)] == [OTHER]
+
+    def test_an_exclude_that_raises_counts_as_excluded(self):
+        def exclude(path: str) -> bool:
+            if path == READER:
+                raise RuntimeError("cannot answer")
+            return False
+
+        read = _Recording(FILES.get)
+        unit = _simple("repo", read=read, exclude=exclude)
+
+        assert READER not in read.calls
+        assert [e.path for e in _readers(unit)] == [OTHER]
+
+    def test_a_diff_file_candidate_is_skipped(self, monkeypatch):
+        chunk_file = _file(WRITER, WRITER_TEXT, added={3})
+        other_diff = _file(OTHER, READER_TEXT, added={2})
+        all_files = [chunk_file, other_diff]
+        on = _Recording(FILES.get)
+        unit = _simple("repo", read=on, all_files=all_files)
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+        off = _Recording(FILES.get)
+        _simple("repo", read=off, all_files=all_files)
+
+        assert [e.path for e in _readers(unit)] == [READER]
+        assert on.calls[: len(off.calls)] == off.calls
+        assert OTHER not in on.calls[len(off.calls):]
+        assert READER in on.calls[len(off.calls):]
+
+
+class TestSwitch:
+    def test_zero_max_reader_entries_at_runtime_gives_no_reader_entries_and_no_reader_reads(self, monkeypatch):
+        on = _Recording(FILES.get)
+        assert _readers(_simple("repo", read=on)) != []
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+        off = _Recording(FILES.get)
+        unit = _simple("repo", read=off)
+
+        assert _readers(unit) == []
+        assert unit.reader_lines == ()
+        assert READER not in off.calls and OTHER not in off.calls
+
+    def test_zero_max_reader_scan_at_runtime_gives_no_reader_entries(self, monkeypatch):
+        monkeypatch.setattr(repo_readers, "MAX_READER_SCAN", 0)
+        assert _readers(_simple("repo")) == []
+
+    def test_the_entry_cap_is_read_at_call_time(self, monkeypatch):
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 1)
+        assert [e.path for e in _readers(_simple("repo"))] == [OTHER]
+
+
+class TestRecord:
+    def test_record_rows_carry_kind_reader_and_reason_shared_state(self):
+        unit = _simple("repo")
+        rows = [row for row in unit.record()["entries"] if row["kind"] == "reader"]
+
+        assert rows == [
+            {
+                "path": entry.path,
+                "line": entry.line,
+                "symbol": "cache",
+                "kind": "reader",
+                "reason": "shared-state",
+                "chars": len(entry.rendered()),
+            }
+            for entry in _readers(unit)
+        ]
+        assert len(rows) == 2
+
+
+IMPORTING = "pkg/importing.py"
+IMPORTING_TEXT = """\
+from pkg.alpha import Alpha
+from pkg.beta import Beta
+
+
+class Writer:
+    def remember(self, k, v):
+        Alpha.check(k)
+        Beta.check(v)
+        self.cache[k] = v
+"""
+ALPHA_TEXT = """\
+class Alpha:
+    @staticmethod
+    def check(value):
+        return value is not None
+"""
+BETA_TEXT = """\
+class Beta:
+    @staticmethod
+    def check(value):
+        return value is not None
+"""
+GAMMA_TEXT = """\
+def lookup(store, k):
+    return store.cache.get(k)
+"""
+CAP_FILES = {
+    IMPORTING: IMPORTING_TEXT,
+    "pkg/alpha.py": ALPHA_TEXT,
+    "pkg/beta.py": BETA_TEXT,
+    "pkg/gamma.py": GAMMA_TEXT,
+}
+
+
+def _capped(chunk_cap: int) -> tuple[UnitContext, RepoReader]:
+    """Build the importing file's unit through the production routed reader capped at ``chunk_cap``."""
+    chunk = [_file(IMPORTING, IMPORTING_TEXT, status="added")]
+    reader = RepoReader(CAP_FILES.get, None, kind="repo-dir", chunk_cap=chunk_cap)
+    read = orchestrator._routed_read(reader, frozenset({IMPORTING}))
+    unit = build_unit_context(
+        chunk, chunk, mode="repo", read=read, max_chars=MAX_CHARS,
+        listing_paths=frozenset(CAP_FILES), listing_complete=True,
+    )
+    return unit, reader
+
+
+class TestSharedChunkCap:
+    def test_the_resolver_alone_spends_exactly_two_capped_reads(self, monkeypatch):
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+        unit, reader = _capped(2)
+
+        assert [(e.path, e.reason) for e in unit.entries] == [
+            ("pkg/alpha.py", "import"),
+            ("pkg/beta.py", "import"),
+        ]
+        assert reader.stats()["read_cap_hit"] is False
+
+    def test_a_saturated_cap_leaves_the_resolver_unchanged_and_readers_add_nothing(self, monkeypatch):
+        on, on_reader = _capped(2)
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+        off, off_reader = _capped(2)
+
+        assert [e for e in on.entries if e.kind == "definition"] == list(off.entries)
+        assert on.definition_lines == off.definition_lines
+        assert _readers(on) == []
+        assert on.reader_lines == ()
+        assert on_reader.stats()["reads"] == off_reader.stats()["reads"]
+        assert on_reader.stats()["read_cap_hit"] is True
+
+    def test_control_one_more_read_lets_the_reader_in(self):
+        unit, reader = _capped(3)
+
+        assert _keys(_readers(unit)) == [("pkg/gamma.py", 1, "cache", "reader", "shared-state")]
+        assert reader.stats()["read_cap_hit"] is False
+
+
+class TestBudget:
+    def test_rank_puts_shared_state_last(self):
+        assert REASONS[-1] == "shared-state"
+
+    def test_shared_state_is_cut_first_under_a_tight_budget(self, monkeypatch):
+        full, _ = _capped(3)
+        definitions = [e for e in full.entries if e.kind == "definition"]
+        budget = sum(len(e.rendered()) for e in definitions)
+        chunk = [_file(IMPORTING, IMPORTING_TEXT, status="added")]
+        reader = RepoReader(CAP_FILES.get, None, kind="repo-dir", chunk_cap=3)
+        tight = build_unit_context(
+            chunk, chunk, mode="repo", read=orchestrator._routed_read(reader, frozenset({IMPORTING})),
+            max_chars=budget, listing_paths=frozenset(CAP_FILES), listing_complete=True,
+        )
+
+        assert list(tight.entries) == definitions
+        assert tight.omitted == 1
+        assert tight.definition_lines == full.definition_lines
+        assert tight.reader_lines == (_omitted(1),)
+        assert tight.contract_lines == ()
+
+    def test_the_omitted_line_follows_a_reader_left_out_after_admitted_readers(self):
+        unit = _simple("repo", max_chars=len(f"{OTHER}:1: ") + len(READER_TEXT.rstrip("\n")))
+
+        assert [e.path for e in _readers(unit)] == [OTHER]
+        assert unit.reader_lines == (_readers(unit)[0].rendered(), _omitted(1))
+        assert unit.definition_lines == ()
+        assert unit.contract_lines == ()
+
+
+class TestRender:
+    DEPS = ["effect@4.0.0"]
+    DEFS = ["a.py:1: def a():"]
+    EXTRA = ["b.java:9: record B() {"]
+    CONTRACTS = ["s.yaml:3: B:"]
+    READERS = ["c.py:4: def c(store):\n    return store.cache"]
+
+    def test_empty_reader_lines_equal_the_output_without_them_byte_for_byte(self):
+        without = render_context_blocks(self.DEPS, self.DEFS, self.EXTRA, self.CONTRACTS)
+
+        assert render_context_blocks(self.DEPS, self.DEFS, self.EXTRA, self.CONTRACTS, ()) == without
+        assert render_context_blocks(
+            self.DEPS, self.DEFS, extra_def_lines=self.EXTRA, contract_lines=self.CONTRACTS, reader_lines=[],
+        ) == without
+        assert render_context_blocks([], [], reader_lines=()) == ""
+
+    def test_reader_lines_render_last_under_their_own_header(self):
+        without = render_context_blocks(self.DEPS, self.DEFS, self.EXTRA, self.CONTRACTS)
+        out = render_context_blocks(self.DEPS, self.DEFS, self.EXTRA, self.CONTRACTS, self.READERS)
+
+        assert out == without + "\n\n" + READER_HEADER + "\n\n" + self.READERS[0]
+        order = [out.index(h) for h in (DEPENDENCY_HEADER, DEFINITIONS_HEADER, CONTRACT_HEADER, READER_HEADER)]
+        assert order == sorted(order)
+        assert out.count(READER_HEADER) == 1
+
+    def test_reader_lines_alone(self):
+        assert render_context_blocks([], [], reader_lines=self.READERS) == READER_HEADER + "\n\n" + self.READERS[0]
+
+    def test_the_header_names_what_the_block_holds(self):
+        assert READER_HEADER == "### Code elsewhere that reads state this chunk writes"
+
+
+class TestPromptBlocks:
+    CHUNK = [SimpleNamespace(path="pkg/writer.py", status="modified", hunks=[])]
+
+    def test_context_blocks_render_a_unit_with_only_reader_lines_without_a_reader(self):
+        unit = UnitContext((), (), (), 0, ("c.py:4: def c(store):",))
+
+        out = orchestrator._context_blocks(self.CHUNK, None, include_definitions=True, unit=unit)
+
+        assert out == READER_HEADER + "\n\nc.py:4: def c(store):"
+
+    def test_context_blocks_put_the_reader_block_after_the_contracts(self):
+        unit = UnitContext(("a.java:1: class A {}",), ("spec.yaml:2: /a:",), (), 0, ("c.py:4: def c(store):",))
+
+        out = orchestrator._context_blocks(self.CHUNK, None, include_definitions=True, unit=unit)
+
+        assert out == render_context_blocks(
+            [], [], extra_def_lines=unit.definition_lines, contract_lines=unit.contract_lines,
+            reader_lines=unit.reader_lines,
+        )
+        assert out.endswith(READER_HEADER + "\n\nc.py:4: def c(store):")
+
+    def test_a_unit_without_reader_lines_renders_as_before(self):
+        unit = UnitContext(("a.java:1: class A {}",), ("spec.yaml:2: /a:",), (), 0)
+
+        out = orchestrator._context_blocks(self.CHUNK, None, include_definitions=True, unit=unit)
+
+        assert out == render_context_blocks([], [], extra_def_lines=unit.definition_lines,
+                                            contract_lines=unit.contract_lines)
+        assert READER_HEADER not in out
+
+    def test_positional_construction_and_the_empty_unit_still_work(self):
+        assert EMPTY_UNIT == UnitContext((), (), (), 0) == UnitContext((), (), (), 0, ())
+        assert EMPTY_UNIT.reader_lines == ()
+
+
+PROGRESS = '''\
+"""Progress notes: a short user-facing line announced before each step runs.
+
+Each note is saved as a message (role "progress") so the transcript holds exactly what the
+user saw. A per-turn ledger on the root frame drops a note that repeats one already shown.
+"""
+from assistant.features import enabled
+from assistant.messages import Message, MessageTable
+from assistant.session import Run
+
+LEDGER_KEY = "progress.ledger"
+
+
+class ProgressLedger:
+    """Notes shown to the user during one turn."""
+
+    def __init__(self, turn_id: str) -> None:
+        self._turn_id = turn_id
+        self._lines: list[str] = []
+
+    def turn_id(self) -> str:
+        return self._turn_id
+
+    def record(self, line: str) -> bool:
+        key = line.strip().lower()
+        if any(shown.strip().lower() == key for shown in self._lines):
+            return False
+        self._lines.append(line)
+        return True
+
+
+class ProgressAnnouncer:
+    def __init__(self, table: MessageTable) -> None:
+        self.table = table
+        self.active = enabled("progress_notes", default=True)
+
+    def announce(self, run: Run, text: str) -> None:
+        if not self.active:
+            return
+        if self._ledger(run).record(text):
+            self.table.append(Message(run.session_id, "progress", text))
+
+    def _ledger(self, run: Run) -> ProgressLedger:
+        data = run.root().data
+        ledger = data.get(LEDGER_KEY)
+        if not isinstance(ledger, ProgressLedger) or ledger.turn_id() != run.turn_id:
+            ledger = ProgressLedger(run.turn_id)
+            data[LEDGER_KEY] = ledger
+        return ledger
+'''
+
+ENGINE = '''\
+"""Runs one user turn as a sequence of steps."""
+from dataclasses import dataclass
+from typing import Callable
+
+from assistant.messages import Message, MessageTable
+from assistant.progress import ProgressAnnouncer
+from assistant.session import Run
+from assistant.state_store import StateStore
+
+
+@dataclass(frozen=True)
+class Step:
+    kind: str  # "model" | "tool" | "handoff"
+    name: str
+    execute: Callable[[Run], str]
+
+
+class Engine:
+    def __init__(self, table: MessageTable, store: StateStore) -> None:
+        self.table = table
+        self.store = store
+        self.progress = ProgressAnnouncer(table)
+
+    def run_turn(self, run: Run, steps: list[Step]) -> str | None:
+        answer = None
+        for step in steps:
+            if step.kind == "handoff":
+                # A human takes over: park the run so it can resume later.
+                self.store.save(run)
+                return None
+            self.progress.announce(run, _note_for(step))
+            answer = step.execute(run)
+            self.table.append(Message(run.session_id, "tool" if step.kind == "tool" else "assistant", answer))
+        return answer
+
+
+def _note_for(step: Step) -> str:
+    if step.kind == "tool":
+        return f"Running {step.name.replace('_', ' ')}..."
+    return "Thinking about your request..."
+'''
+
+FEATURES = '''\
+"""Feature toggles, read from the environment at startup."""
+import os
+
+
+def enabled(name: str, default: bool) -> bool:
+    raw = os.environ.get(f"ASSISTANT_{name.upper()}")
+    return default if raw is None else raw.lower() == "true"
+'''
+
+HISTORY = '''\
+"""Builds the model's conversation history from the message table."""
+from assistant.messages import MessageTable
+
+HISTORY_WINDOW = 20
+
+_MODEL_ROLES = {"user": "user", "assistant": "assistant", "tool": "tool"}
+
+
+def model_history(table: MessageTable, session_id: str) -> list[dict]:
+    history = []
+    for m in table.recent(session_id, HISTORY_WINDOW):
+        role = _MODEL_ROLES.get(m.role)
+        if role is None:
+            continue
+        history.append({"role": role, "content": m.text})
+    return history
+'''
+
+MESSAGES = '''\
+"""Append-only message table for a session."""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Message:
+    session_id: str
+    role: str  # "user" | "assistant" | "tool"
+    text: str
+
+
+class MessageTable:
+    def __init__(self) -> None:
+        self._rows: list[Message] = []
+
+    def append(self, message: Message) -> None:
+        self._rows.append(message)
+
+    def recent(self, session_id: str, limit: int) -> list[Message]:
+        rows = [m for m in self._rows if m.session_id == session_id]
+        return rows[-limit:]
+'''
+
+SESSION = '''\
+"""Live state of one run."""
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Frame:
+    """One agent working on the request. The bottom frame is the root agent."""
+
+    agent_id: str
+    # Scratch space any engine component can use for per-frame bookkeeping.
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Run:
+    session_id: str
+    turn_id: str
+    frames: list[Frame] = field(default_factory=list)
+
+    def root(self) -> Frame:
+        return self.frames[0]
+
+    def current(self) -> Frame:
+        return self.frames[-1]
+'''
+
+STATE_STORE = '''\
+"""Saves a run so it can resume after a human handoff."""
+import json
+from dataclasses import asdict
+
+from assistant.session import Frame, Run
+
+
+class StateStore:
+    def __init__(self) -> None:
+        self._blobs: dict[str, str] = {}
+
+    def save(self, run: Run) -> None:
+        self._blobs[run.session_id] = json.dumps(asdict(run))
+
+    def load(self, session_id: str) -> Run | None:
+        blob = self._blobs.get(session_id)
+        if blob is None:
+            return None
+        raw = json.loads(blob)
+        frames = [Frame(f["agent_id"], f["data"]) for f in raw["frames"]]
+        return Run(raw["session_id"], raw["turn_id"], frames)
+'''
+
+CONFTEST = '''\
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _progress_notes_off(monkeypatch):
+    # Keep exact message-table assertions deterministic; progress tests opt in.
+    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")
+'''
+
+TEST_ENGINE = '''\
+from assistant.engine import Engine, Step
+from assistant.messages import MessageTable
+from assistant.session import Frame, Run
+from assistant.state_store import StateStore
+
+
+def make_run():
+    return Run("s1", "t1", [Frame("root")])
+
+
+def test_turn_returns_last_answer():
+    engine = Engine(MessageTable(), StateStore())
+    steps = [Step("tool", "lookup", lambda r: "found"), Step("model", "reply", lambda r: "done")]
+    assert engine.run_turn(make_run(), steps) == "done"
+
+
+def test_handoff_parks_and_resumes():
+    store = StateStore()
+    engine = Engine(MessageTable(), store)
+    run = make_run()
+    run.root().data["attempts"] = 1
+    assert engine.run_turn(run, [Step("handoff", "human", lambda r: "")]) is None
+    assert store.load("s1").root().data == {"attempts": 1}
+'''
+
+TEST_PROGRESS = '''\
+from assistant.engine import Engine, Step
+from assistant.messages import MessageTable
+from assistant.session import Frame, Run
+from assistant.state_store import StateStore
+
+
+def test_each_step_is_announced_once(monkeypatch):
+    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "true")
+    table = MessageTable()
+    engine = Engine(table, StateStore())
+    run = Run("s1", "t1", [Frame("root")])
+    steps = [
+        Step("tool", "find_order", lambda r: "order 7"),
+        Step("model", "reply", lambda r: "thinking"),
+        Step("model", "reply", lambda r: "your order shipped"),
+    ]
+    assert engine.run_turn(run, steps) == "your order shipped"
+    notes = [m.text for m in table.recent("s1", 50) if m.role == "progress"]
+    assert notes == ["Running find order...", "Thinking about your request..."]
+'''
+
+ISSUE_22_HEAD = {
+    "README.md": "# assistant\n",
+    ".gitignore": "__pycache__/\n.pytest_cache/\n",
+    "assistant/__init__.py": "",
+    "assistant/engine.py": ENGINE,
+    "assistant/features.py": FEATURES,
+    "assistant/history.py": HISTORY,
+    "assistant/messages.py": MESSAGES,
+    "assistant/progress.py": PROGRESS,
+    "assistant/session.py": SESSION,
+    "assistant/state_store.py": STATE_STORE,
+    "pyproject.toml": '[project]\nname = "assistant"\n',
+    "tests/conftest.py": CONFTEST,
+    "tests/test_engine.py": TEST_ENGINE,
+    "tests/test_progress.py": TEST_PROGRESS,
+}
+ENGINE_ADDED = {6, 22, 31, 35, 36, 37, 38, 39, 40}
+
+
+def _issue_22(mode: str) -> tuple[UnitContext, _Recording]:
+    """The progress.py chunk of the #22 PR, built the way a worker builds it, over the head tree."""
+    progress = _file("assistant/progress.py", PROGRESS, status="added")
+    all_files = [
+        _file(".gitignore", ISSUE_22_HEAD[".gitignore"], status="added"),
+        _file("README.md", ISSUE_22_HEAD["README.md"], added={1}),
+        _file("assistant/engine.py", ENGINE, added=ENGINE_ADDED),
+        progress,
+        _file("tests/conftest.py", CONFTEST, status="added"),
+        _file("tests/test_progress.py", TEST_PROGRESS, status="added"),
+    ]
+    exclude = exclude_predicate()
+    reader = RepoReader(ISSUE_22_HEAD.get, None, kind="repo-dir", exclude=exclude)
+    read = _Recording(orchestrator._routed_read(reader, frozenset(f.path for f in all_files)))
+    unit = build_unit_context(
+        [progress], all_files, mode=mode, read=read, max_chars=MAX_CHARS,
+        listing_paths=frozenset(ISSUE_22_HEAD), listing_complete=True, exclude=exclude,
+    )
+    return unit, read
+
+
+class TestIssue22Shape:
+    def test_the_progress_chunk_gets_the_state_store_and_history_readers(self):
+        unit, _ = _issue_22("repo")
+        readers = _readers(unit)
+
+        assert [(e.path, e.line, e.symbol) for e in readers] == [
+            ("assistant/history.py", 9, "table"),
+            ("assistant/state_store.py", 15, "data"),
+            ("tests/test_engine.py", 17, "data"),
+        ]
+        history, store, test_engine = readers
+        assert history.text.splitlines()[-1] == "    for m in table.recent(session_id, HISTORY_WINDOW):"
+        assert store.text.splitlines()[0] == "    def load(self, session_id: str) -> Run | None:"
+        assert store.text.splitlines()[-1].endswith('f["data"]) for f in raw["frames"]]')
+        assert test_engine.text.splitlines()[-1].endswith('.root().data == {"attempts": 1}')
+        assert unit.reader_lines == tuple(entry.rendered() for entry in readers)
+
+    def test_the_readers_reach_the_prompt_in_their_own_last_block(self):
+        unit, _ = _issue_22("repo")
+
+        out = orchestrator._context_blocks([], None, include_definitions=True, unit=unit)
+
+        block = out.split(READER_HEADER + "\n\n", 1)[1]
+        assert block.startswith("assistant/history.py:9: def model_history(")
+        assert "assistant/state_store.py:15:     def load(self, session_id: str) -> Run | None:" in block
+        assert CONTRACT_HEADER not in block and DEFINITIONS_HEADER not in block
+        assert "assistant/state_store.py" not in out.split(READER_HEADER, 1)[0]
+
+    def test_the_reader_source_walks_non_diff_files_only_after_the_other_sources(self, monkeypatch):
+        unit, on = _issue_22("repo")
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+        _, off = _issue_22("repo")
+
+        assert on.calls[: len(off.calls)] == off.calls
+        assert on.calls[len(off.calls):] == [
+            "assistant/__init__.py",
+            "assistant/features.py",
+            "assistant/history.py",
+            "assistant/messages.py",
+            "assistant/session.py",
+            "assistant/state_store.py",
+            "tests/test_engine.py",
+        ]
+        assert "tests/test_progress.py" in off.calls
+        assert not {e.path for e in _readers(unit)} & {"assistant/engine.py", "tests/test_progress.py"}
+
+    @pytest.mark.parametrize("mode", ["diff", "off"])
+    def test_diff_and_off_have_no_readers_and_never_read_them(self, mode):
+        unit, read = _issue_22(mode)
+
+        assert _readers(unit) == []
+        assert READER_HEADER not in orchestrator._context_blocks([], None, include_definitions=True, unit=unit)
+        assert "assistant/history.py" not in read.calls
+        assert "assistant/state_store.py" not in read.calls

From 0df600a4edcaa5dc68fdd59982fb861e994c79e3 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:35:00 -0700
Subject: [PATCH 11/25] feat: thread the parse retry through the orchestrator
 and CLI, and record its total (#21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

orchestrate_review gains a keyword-only llm_parse_retries (library default
0, which behaves as 0.16.0) and hands it to every review_chunk call, the
timeout retry's included, and to review_systemic as parse_retries=. The
CLI passes cfg["llm_parse_retries"], so a CLI run retries once by default.

_invoke_chunk, _run_worker and _run_sweep each rebuilt the unit result
from named keys and dropped the reviewer's parse_retries and first_error.
All three now carry both when the meta has them (_retry_meta) and neither
otherwise; a raised call and a crashed worker carry neither.

The run record gains parse_retries: None when N is not an int of 1 or
more, otherwise the sum over every chunk and the sweep (0 when nothing
retried, including exits before any review unit). It is stamped after the
sweep and before the total-failure exit, and every exit carries it through
_run_record. --format json emits it after repo_context, and the README key
list documents it. The timeout retry still replaces the first run's
counts, the known gap in docs/llm.md.

Test doubles for review_chunk/review_systemic with explicit keyword lists
accept parse_retries=0, and the pinned run-record and JSON key lists add
the new key. New tests in tests/test_parse_retry_orchestrator.py.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 README.md                              |   1 +
 src/prxref/cli.py                      |  16 +-
 src/prxref/orchestrator.py             |  89 +++++-
 tests/test_cli_output.py               |   4 +-
 tests/test_cli_repo_context.py         |   2 +-
 tests/test_cli_scoped_rules.py         |   2 +-
 tests/test_issue_67_cost.py            |   4 +-
 tests/test_orchestrator.py             |  23 +-
 tests/test_orchestrator_rule_cap.py    |   4 +-
 tests/test_parse_retry_orchestrator.py | 393 +++++++++++++++++++++++++
 tests/test_prompt_context.py           |   5 +-
 tests/test_prompt_inputs.py            |   5 +-
 tests/test_run_record.py               |   4 +-
 13 files changed, 514 insertions(+), 38 deletions(-)
 create mode 100644 tests/test_parse_retry_orchestrator.py

diff --git a/README.md b/README.md
index bf1a1b5..1449c0f 100644
--- a/README.md
+++ b/README.md
@@ -359,6 +359,7 @@ Before 0.14.0, `outofscope` findings rendered 🟦. They now render ⬜ on every
   - `scoped_rules`: the path-scoped rules in force (`entries` as configured; `files`, one row per loaded file in load order with its `path`, `sha256`, `chars`, `max_chars`, `truncated`, `severity_map` and `applies_to`; `max_chars`, the per-unit cap; and `units`, the `path` and `chars` of the files each chunk and the sweep received; never the rules text). Always present, and `null` when no scoped rules are configured. See [Path-scoped rules](docs/review-rules.md#path-scoped-rules);
   - `rule_counts`: the per-rule cap's tally, one `{"rule", "kind", "total", "kept"}` object for each rule (`kind` `rule`), or for each normalized title among findings that name no rule (`kind` `title`), that at least two chunk findings share: `total` of them, `kept` active, most findings first. A rule or title with one finding gets no row. Always present: `[]` when the cap ran and nothing repeated, and `null` when it did not run (no review rules file, `PRXREF_MAX_FINDINGS_PER_RULE=0`, or a run that ended before the quality passes). See [docs/quality.md](docs/quality.md);
   - `repo_context`: the repository context in force (`mode`, `max_chars`, `contract_globs` and `exclude_globs`; `reader`, which is `forge`, `repo-dir` or `null`; `listing`, `{"paths", "complete"}` or `null`; `reads` and `read_cap_hit`; and `units`, `{"chunks": [...]}` holding one `{"entries", "omitted", "retry_dropped"}` row per chunk in chunk order, whose entries carry `path`, `line`, `symbol`, `kind`, `reason` and `chars`; never the file text). Always present, and `null` when `PRXREF_REPO_CONTEXT` is `off`. See [docs/env-vars.md](docs/env-vars.md);
+  - `parse_retries`: how many times the run re-sent a request whose reply could not be used as a review (empty, not JSON, not a JSON object, or an object without a `findings` list), summed over every chunk and the whole-PR sweep. Always present: `0` when nothing was re-sent, and `null` when `PRXREF_LLM_PARSE_RETRIES` is `0`. With `--trace-dir`, each unit that retried has `parse_retries` and `first_error` in its meta file. See [docs/env-vars.md](docs/env-vars.md);
   - `sampling`: the `temperature`, `seed`, and `models` the run had in force (every review result carries it);
   - `replay`: the replay stamp (`base_sha`, `head_sha`, `threads`, `diff_file`, `description`, `as_of`, `as_of_source`), on replay runs only.
 
diff --git a/src/prxref/cli.py b/src/prxref/cli.py
index e5923af..d50132c 100644
--- a/src/prxref/cli.py
+++ b/src/prxref/cli.py
@@ -759,16 +759,20 @@ def _build_json_result(result: Any) -> dict:
     ``cost_usd``, ``cost_estimated``, ``posted``, ``review_rules``,
     ``ticket_context``, ``spec_grounding``, ``size_advisory``,
     ``prompt_templates``, ``scoped_rules``, ``rule_counts``,
-    ``repo_context``, then ``sampling`` and ``replay`` when present.
+    ``repo_context``, ``parse_retries``, then ``sampling`` and ``replay``
+    when present.
 
     Tolerates an error-shaped or partial result (a dict missing keys, as an
     incomplete or failed run may return): every always-present key defaults
     to ``None`` and ``findings`` defaults to ``[]`` rather than raising. The
     run-record keys new in 0.14 (``cost_usd`` through ``size_advisory``),
-    0.15's ``prompt_templates``, ``scoped_rules`` and ``rule_counts``, and
-    0.16's ``repo_context`` are always emitted and are ``null`` when their
-    feature is off (``rule_counts`` whenever the per-rule cap did not run,
-    ``repo_context`` whenever ``PRXREF_REPO_CONTEXT`` is ``off``);
+    0.15's ``prompt_templates``, ``scoped_rules`` and ``rule_counts``,
+    0.16's ``repo_context`` and 0.17's ``parse_retries`` are always emitted
+    and are ``null`` when their feature is off (``rule_counts`` whenever the
+    per-rule cap did not run, ``repo_context`` whenever
+    ``PRXREF_REPO_CONTEXT`` is ``off``, ``parse_retries`` whenever
+    ``PRXREF_LLM_PARSE_RETRIES`` is ``0``; otherwise it is the run's total
+    of parse retries over every chunk and the sweep, ``0`` when none ran);
     ``cost_usd`` is also ``null`` when no source could price the run, never
     ``0``. Every ``findings`` row, active or dropped, carries 0.15's ``rule``
     and ``locations`` the same way (see :func:`_finding_json`).
@@ -805,6 +809,7 @@ def _build_json_result(result: Any) -> dict:
         "scoped_rules": result.get("scoped_rules"),
         "rule_counts": result.get("rule_counts"),
         "repo_context": result.get("repo_context"),
+        "parse_retries": result.get("parse_retries"),
     }
     if "sampling" in result:
         payload["sampling"] = result["sampling"]
@@ -1430,6 +1435,7 @@ def _run_review(
         context_contract_globs=cfg["context_contract_globs"],
         context_exclude_globs=cfg["context_exclude_globs"],
         repo_dir=repo,
+        llm_parse_retries=cfg["llm_parse_retries"],
     )
 
 
diff --git a/src/prxref/orchestrator.py b/src/prxref/orchestrator.py
index 3715562..83ce938 100644
--- a/src/prxref/orchestrator.py
+++ b/src/prxref/orchestrator.py
@@ -438,6 +438,7 @@ def orchestrate_review(
     context_contract_globs: Sequence[str] = (),
     context_exclude_globs: Sequence[str] = (),
     repo_dir: RepoDir | None = None,
+    llm_parse_retries: int = 0,
 ) -> dict:
     """Run one full review pass over a PR and optionally post results.
 
@@ -445,11 +446,12 @@ def orchestrate_review(
     chunks_reviewed, chunks_failed, elapsed_ms, input_tokens, output_tokens,
     posted, sampling, cost_usd, cost_estimated, review_rules, ticket_context,
     spec_grounding, size_advisory, prompt_templates, scoped_rules,
-    rule_counts, repo_context}``, plus ``replay`` on a replay run only.
-    Every exit, error and empty-diff exits included, goes through
-    :func:`_run_record`, so the last ten keys are always present and are
+    rule_counts, repo_context, parse_retries}``, plus ``replay`` on a replay
+    run only. Every exit, error and empty-diff exits included, goes through
+    :func:`_run_record`, so the last eleven keys are always present and are
     ``None`` (``cost_usd``: ``0.0`` before any LLM request; ``cost_estimated``:
-    ``False``) when their feature is off or the run never reached it.
+    ``False``; ``parse_retries``: ``0`` before any review unit when the
+    parse retry is on) when their feature is off or the run never reached it.
     ``cost_usd`` is ``None`` when the cost is unknown, never ``0``.
     ``cost_api_equivalent`` (always ``True``) is added only when every
     reported unit cost came from claude-cli
@@ -722,6 +724,19 @@ def orchestrate_review(
     row. One ``chunk context`` trace event per chunk (``index``, ``total``,
     ``entries``, ``omitted``, ``chars``) and one ``repo_context ok`` event
     per run carry the same figures, only when on.
+
+    ``llm_parse_retries`` (``PRXREF_LLM_PARSE_RETRIES``, issue #21) is the
+    parse-retry budget N handed to every chunk worker and to the sweep as
+    ``parse_retries`` (see :func:`reviewer.review_chunk`). The library
+    default is ``0``, which behaves exactly as 0.16.0; the CLI passes the
+    config's default of ``1``. A unit whose reviewer meta carries
+    ``parse_retries`` and ``first_error`` (a retry ran at N of 1 or more)
+    keeps both in its worker result. The record's ``parse_retries`` is
+    ``None`` unless N is an ``int`` of 1 or more, and otherwise the sum of
+    those unit counts over every chunk and the sweep: ``0`` when nothing
+    was retried, including an exit reached before any review unit ran.
+    When the timeout retry re-runs a chunk, only the second run's count
+    survives.
     """
     if repo_context not in repo_unit.MODES:
         raise ValueError(
@@ -747,6 +762,9 @@ def orchestrate_review(
         "scoped_rules": None,
         "rule_counts": None,
         "repo_context": None,
+        "parse_retries": (
+            0 if isinstance(llm_parse_retries, int) and llm_parse_retries >= 1 else None
+        ),
     }
     # Resolved once, before the first exit, so every exit records them and the
     # empty-diff summary gets the ticket note. An inactive (empty) ticket is
@@ -1058,6 +1076,7 @@ def orchestrate_review(
         reader=reader, all_files=files, trace_dir=trace_dir,
         prompt_context=prompt_context, scoped_blocks=scoped_blocks,
         repo_plan=repo_plan, unit_records=unit_records,
+        parse_retries=llm_parse_retries,
     )
     if repo_plan is not None and unit_records is not None:
         run_inputs["repo_context"] = _repo_context_record(
@@ -1081,8 +1100,11 @@ def orchestrate_review(
             token_budget=token_budget, tracer=tracer, threads=threads,
             trace_dir=trace_dir,
             prompt_context=prompt_context, scoped_block=sweep_block,
+            parse_retries=llm_parse_retries,
         )
     )
+    if run_inputs["parse_retries"] is not None:
+        run_inputs["parse_retries"] = _parse_retry_total(results)
 
     # Priced once every review unit is final, and BEFORE the total-failure
     # exit below: requests went out, so that exit's record must say what they
@@ -1772,6 +1794,22 @@ def _stamp_run_cost(
     run_inputs["cost_api_equivalent"] = costs.api_equivalent_run(units)
 
 
+def _parse_retry_total(units: Sequence[Mapping[str, Any]]) -> int:
+    """The run record's ``parse_retries``: the sum of every unit's own count (issue #21).
+
+    Called once, after the sweep, with every review unit's result (the chunk
+    workers plus the sweep). A unit without the key made no parse retry and
+    adds 0, and so does a value that is not an ``int`` (a ``bool`` included),
+    so a malformed test double can never raise out of the review.
+    """
+    total = 0
+    for unit in units:
+        value = unit.get("parse_retries", 0)
+        if isinstance(value, int) and not isinstance(value, bool):
+            total += value
+    return total
+
+
 def _attribution(
     model: str, tokens: int, elapsed_ms: int, *, cost_label: str = "",
 ) -> str:
@@ -2128,6 +2166,7 @@ def _run_workers(
     scoped_blocks: Sequence[Any] | None = None,
     repo_plan: _RepoPlan | None = None,
     unit_records: list[dict[str, Any] | None] | None = None,
+    parse_retries: int = 0,
 ) -> list[dict]:
     # Never below 1: ThreadPoolExecutor rejects a zero-width pool, and a
     # library caller is not gated by config's range check.
@@ -2166,6 +2205,7 @@ def _heartbeat() -> None:
                 prompt_context=prompt_context,
                 scoped_block=scoped_blocks[i] if scoped_blocks is not None else None,
                 repo_plan=repo_plan, unit_records=unit_records,
+                parse_retries=parse_retries,
             )
             for i, chunk in enumerate(chunks)
         ]
@@ -2208,6 +2248,22 @@ def _is_timeout_error(error: str) -> bool:
 _TIMEOUT_RETRY_CONTEXT_LINES = 0
 
 
+def _retry_meta(meta: Mapping[str, Any]) -> dict[str, Any]:
+    """The parse-retry keys a worker result carries over from its reviewer meta (issue #21).
+
+    ``{"parse_retries", "first_error"}`` when ``meta`` has ``parse_retries``,
+    which the reviewer sets only when a parse retry ran at
+    ``parse_retries`` of 1 or more, and ``{}`` otherwise, so a result
+    without a retry keeps exactly its 0.16.0 keys.
+    """
+    if "parse_retries" not in meta:
+        return {}
+    return {
+        "parse_retries": meta["parse_retries"],
+        "first_error": meta.get("first_error", ""),
+    }
+
+
 def _invoke_chunk(
     llm: LLMClient, chunk, pr: PRData,
     max_tokens: int | None, context_lines: int | None,
@@ -2215,6 +2271,7 @@ def _invoke_chunk(
     trace_label: str = "", trace_dir: str | None = None,
     prompt_context: PromptContext = NO_PROMPT_CONTEXT,
     unit: repo_unit.UnitContext | None = None,
+    parse_retries: int = 0,
 ) -> dict:
     """One normalized :func:`reviewer.review_chunk` call; never raises.
 
@@ -2242,6 +2299,11 @@ def _invoke_chunk(
     ``cost_source`` beside the token counts; a call that raised, or a stub
     whose meta lacks them, gives ``None`` and ``""``. Pricing is left to
     :func:`_stamp_run_cost`, over the whole run.
+
+    ``parse_retries`` is passed to the reviewer unchanged (issue #21). When
+    its meta carries ``parse_retries`` and ``first_error``, the shape
+    carries both after ``cost_source`` (:func:`_retry_meta`); otherwise,
+    and always for a call that raised, it has neither.
     """
     blocks = _context_blocks(chunk, reader, include_definitions=include_definitions, unit=unit)
     try:
@@ -2250,7 +2312,7 @@ def _invoke_chunk(
             max_tokens=max_tokens, context_lines=context_lines,
             context_blocks=blocks, sibling_files=all_files or (),
             trace_label=trace_label, trace_dir=trace_dir or "",
-            prompt_context=prompt_context,
+            prompt_context=prompt_context, parse_retries=parse_retries,
         )
     except Exception as e:  # noqa: BLE001
         return {
@@ -2271,6 +2333,7 @@ def _invoke_chunk(
             "error": meta.get("error", ""),
             "cost_usd": meta.get("cost_usd"),
             "cost_source": meta.get("cost_source", ""),
+            **_retry_meta(meta),
         }
 
     findings = []
@@ -2291,6 +2354,7 @@ def _invoke_chunk(
         "elapsed_ms": res.get("elapsed_ms", 0),
         "cost_usd": res.get("cost_usd"),
         "cost_source": res.get("cost_source", ""),
+        **_retry_meta(res),
     }
 
 
@@ -2303,6 +2367,7 @@ def _run_worker(
     scoped_block: Any = None,
     repo_plan: _RepoPlan | None = None,
     unit_records: list[dict[str, Any] | None] | None = None,
+    parse_retries: int = 0,
 ) -> dict:
     tracer = tracer if tracer is not None else get_tracer()
     t0 = time.perf_counter()
@@ -2337,7 +2402,7 @@ def _run_worker(
     res = _invoke_chunk(
         llm, chunk, pr, max_tokens, context_lines, reader, all_files=all_files,
         trace_label=trace_label, trace_dir=trace_dir, prompt_context=unit_context,
-        unit=unit,
+        unit=unit, parse_retries=parse_retries,
     )
     if (
         res["error"]
@@ -2365,7 +2430,7 @@ def _run_worker(
             llm, chunk, pr, max_tokens, _TIMEOUT_RETRY_CONTEXT_LINES, reader,
             include_definitions=False, all_files=all_files,
             trace_label=trace_label, trace_dir=trace_dir,
-            prompt_context=unit_context,
+            prompt_context=unit_context, parse_retries=parse_retries,
         )
 
     error = res["error"]
@@ -2397,6 +2462,7 @@ def _run_worker(
         "elapsed_ms": _elapsed_ms(t0),
         "cost_usd": res["cost_usd"],
         "cost_source": res["cost_source"],
+        **_retry_meta(res),
     }
 
 
@@ -2409,6 +2475,7 @@ def _run_sweep(
     trace_dir: str | None = None,
     prompt_context: PromptContext = NO_PROMPT_CONTEXT,
     scoped_block: Any = None,
+    parse_retries: int = 0,
 ) -> dict:
     """Run the whole-PR systemic sweep as one worker-style review unit.
 
@@ -2427,7 +2494,10 @@ def _run_sweep(
     failed chunk in the caller's coverage accounting. ``scoped_block``, the
     sweep's path-scoped rules block, replaces ``rules_sweep`` in the context
     and its files ride the ``sweep start`` event as ``rules``; ``None`` (no
-    scoped rules) leaves both exactly as they were.
+    scoped rules) leaves both exactly as they were. ``parse_retries`` is
+    passed to the reviewer unchanged (issue #21), and the result carries
+    the meta's ``parse_retries`` and ``first_error`` exactly as a chunk's
+    does (:func:`_retry_meta`); a sweep that raised carries neither.
     """
     tracer = tracer if tracer is not None else get_tracer()
     t0 = time.perf_counter()
@@ -2450,7 +2520,7 @@ def _run_sweep(
             llm, digest, pr_title=pr.title, pr_description=pr.description,
             max_tokens=max_tokens, threads=discussion,
             trace_label="sweep", trace_dir=trace_dir or "",
-            prompt_context=prompt_context,
+            prompt_context=prompt_context, parse_retries=parse_retries,
         )
     except Exception as e:  # noqa: BLE001
         logger.error("[sweep] raised: %s", e)
@@ -2501,6 +2571,7 @@ def _run_sweep(
         "elapsed_ms": _elapsed_ms(t0),
         "cost_usd": meta.get("cost_usd"),
         "cost_source": meta.get("cost_source", ""),
+        **_retry_meta(meta),
     }
 
 
diff --git a/tests/test_cli_output.py b/tests/test_cli_output.py
index 4cfd7fa..db003a7 100644
--- a/tests/test_cli_output.py
+++ b/tests/test_cli_output.py
@@ -42,11 +42,11 @@
     "verdict", "findings", "chunk_count", "chunks_reviewed", "chunks_failed", "elapsed_ms",
     "input_tokens", "output_tokens", "cost_usd", "cost_estimated", "posted",
     "review_rules", "ticket_context", "spec_grounding", "size_advisory", "prompt_templates", "scoped_rules",
-    "rule_counts", "repo_context",
+    "rule_counts", "repo_context", "parse_retries",
 ]
 NEW_RECORD_KEYS = [
     "cost_usd", "cost_estimated", "review_rules", "ticket_context", "spec_grounding", "size_advisory",
-    "prompt_templates", "scoped_rules", "rule_counts", "repo_context",
+    "prompt_templates", "scoped_rules", "rule_counts", "repo_context", "parse_retries",
 ]
 FINDING_KEYS = [
     "file", "line", "severity", "confidence", "scope", "rule", "locations", "title", "body", "drop_reason",
diff --git a/tests/test_cli_repo_context.py b/tests/test_cli_repo_context.py
index 94c1096..dd24892 100644
--- a/tests/test_cli_repo_context.py
+++ b/tests/test_cli_repo_context.py
@@ -237,7 +237,7 @@ def test_repo_context_rides_right_after_rule_counts(self):
         keys = list(cli._build_json_result({"verdict": "Approved", "repo_context": SAMPLE,
                                             "sampling": {"seed": 1}, "replay": {}}))
         assert keys.index("repo_context") == keys.index("rule_counts") + 1
-        assert keys[keys.index("repo_context") + 1:] == ["sampling", "replay"]
+        assert keys[keys.index("repo_context") + 1:] == ["parse_retries", "sampling", "replay"]
 
     @pytest.mark.parametrize("result", [{}, None, {"verdict": "Approved"}, {"repo_context": None}])
     def test_a_result_without_it_emits_null(self, result):
diff --git a/tests/test_cli_scoped_rules.py b/tests/test_cli_scoped_rules.py
index 96386d9..9174360 100644
--- a/tests/test_cli_scoped_rules.py
+++ b/tests/test_cli_scoped_rules.py
@@ -310,7 +310,7 @@ def test_the_key_follows_prompt_templates_and_precedes_sampling(self):
         keys = list(payload)
         assert keys.index("scoped_rules") == keys.index("prompt_templates") + 1
         assert keys[keys.index("scoped_rules") + 1] == "rule_counts"
-        assert keys.index("sampling") == keys.index("scoped_rules") + 3
+        assert keys.index("sampling") == keys.index("scoped_rules") + 4
 
     def test_the_key_is_null_for_a_pre_0_15_result(self):
         assert cli._build_json_result({})["scoped_rules"] is None
diff --git a/tests/test_issue_67_cost.py b/tests/test_issue_67_cost.py
index dd1b13c..bc89a3f 100644
--- a/tests/test_issue_67_cost.py
+++ b/tests/test_issue_67_cost.py
@@ -97,7 +97,7 @@ def _with_cost(meta: dict, result) -> dict:
 def _cost_review_chunk(
     llm, files, *, pr_title="", pr_description="", repo_hint="",
     max_tokens=None, context_lines=None, context_blocks="", sibling_files=(),
-    trace_label="", trace_dir="", prompt_context=None,
+    trace_label="", trace_dir="", prompt_context=None, parse_retries=0,
 ):
     seen = []
 
@@ -117,7 +117,7 @@ def invoke(self, *args, **kwargs):
 
 def _cost_review_systemic(
     llm, digest, *, pr_title="", pr_description="", repo_hint="", max_tokens=None,
-    threads=(), trace_label="", trace_dir="", prompt_context=None,
+    threads=(), trace_label="", trace_dir="", prompt_context=None, parse_retries=0,
 ):
     result = llm.invoke(system=SWEEP_SYSTEM, user="[]")
     return [], _with_cost({
diff --git a/tests/test_orchestrator.py b/tests/test_orchestrator.py
index c1f9e56..5197d9f 100644
--- a/tests/test_orchestrator.py
+++ b/tests/test_orchestrator.py
@@ -38,7 +38,7 @@
 def _contract_review_chunk(
     llm, files, *, pr_title="", pr_description="", repo_hint="",
     max_tokens=None, context_lines=None, context_blocks="", sibling_files=(),
-    trace_label="", trace_dir="", prompt_context=None,
+    trace_label="", trace_dir="", prompt_context=None, parse_retries=0,
 ):
     result = llm.invoke(
         system="review the chunk",
@@ -70,7 +70,7 @@ def _contract_review_chunk(
 
 def _contract_review_systemic(
     llm, digest, *, pr_title="", pr_description="", repo_hint="", max_tokens=None,
-    threads=(), trace_label="", trace_dir="", prompt_context=None,
+    threads=(), trace_label="", trace_dir="", prompt_context=None, parse_retries=0,
 ):
     return [], {
         "escalations": [], "input_tokens": 0, "output_tokens": 0,
@@ -278,7 +278,7 @@ def test_posts_summary_and_inline_comments(self):
             "sampling",
             "cost_usd", "cost_estimated", "review_rules", "ticket_context",
             "spec_grounding", "size_advisory", "prompt_templates", "scoped_rules",
-            "rule_counts", "repo_context",
+            "rule_counts", "repo_context", "parse_retries",
         }
         assert res["verdict"] == "Request-Changes"
         assert len(res["findings_active"]) == 2
@@ -415,6 +415,7 @@ def barrier_review_chunk(
             llm, files, *, pr_title="", pr_description="", repo_hint="",
             max_tokens=None, context_lines=None, context_blocks="",
             sibling_files=(), trace_label="", trace_dir="", prompt_context=None,
+            parse_retries=0,
         ):
             barrier.wait()
             return [Finding(
@@ -747,7 +748,7 @@ def test_result_key_set_is_unchanged_by_the_new_knob(self):
             "sampling",
             "cost_usd", "cost_estimated", "review_rules", "ticket_context",
             "spec_grounding", "size_advisory", "prompt_templates", "scoped_rules",
-            "rule_counts", "repo_context",
+            "rule_counts", "repo_context", "parse_retries",
         }
 
 
@@ -1062,7 +1063,7 @@ def test_result_key_set_is_unchanged_by_the_new_knobs(self):
             "sampling",
             "cost_usd", "cost_estimated", "review_rules", "ticket_context",
             "spec_grounding", "size_advisory", "prompt_templates", "scoped_rules",
-            "rule_counts", "repo_context",
+            "rule_counts", "repo_context", "parse_retries",
         }
 
 
@@ -1072,7 +1073,7 @@ def test_result_key_set_is_unchanged_by_the_new_knobs(self):
     "elapsed_ms", "input_tokens", "output_tokens", "posted", "sampling",
     "cost_usd", "cost_estimated", "review_rules", "ticket_context",
     "spec_grounding", "size_advisory", "prompt_templates", "scoped_rules",
-    "rule_counts", "repo_context",
+    "rule_counts", "repo_context", "parse_retries",
 }
 
 
@@ -2540,7 +2541,7 @@ def _sweep_double(results: list, **meta_overrides):
     def _review_systemic(
         llm, digest, *, pr_title="", pr_description="", repo_hint="",
         max_tokens=None, threads=(), trace_label="", trace_dir="",
-        prompt_context=None,
+        prompt_context=None, parse_retries=0,
     ):
         calls.append({
             "digest": digest, "max_tokens": max_tokens,
@@ -2806,7 +2807,8 @@ def test_a_chunk_and_sweep_echo_never_drops_the_deterministic_finding(
         def _review_chunk(llm, files, *, pr_title="", pr_description="",
                            repo_hint="", max_tokens=None, context_lines=None,
                            context_blocks="", sibling_files=(),
-                           trace_label="", trace_dir="", prompt_context=None):
+                           trace_label="", trace_dir="", prompt_context=None,
+                           parse_retries=0):
             return [self._matching_finding("chunk worker restatement")], {
                 "input_tokens": 10, "output_tokens": 5, "model": "m",
                 "elapsed_ms": 1, "error": "",
@@ -2814,7 +2816,8 @@ def _review_chunk(llm, files, *, pr_title="", pr_description="",
 
         def _review_systemic(llm, digest, *, pr_title="", pr_description="",
                               repo_hint="", max_tokens=None, threads=(),
-                              trace_label="", trace_dir="", prompt_context=None):
+                              trace_label="", trace_dir="", prompt_context=None,
+                              parse_retries=0):
             return [self._matching_finding("sweep restatement")], {
                 "input_tokens": 7, "output_tokens": 3, "model": "sweep-model",
                 "elapsed_ms": 1, "error": "",
@@ -2948,7 +2951,7 @@ def _scripted_double(outcomes: list[dict]):
         def _rc(llm, files, *, pr_title="", pr_description="", repo_hint="",
                 max_tokens=None, context_lines=None, context_blocks="",
                 sibling_files=(), trace_label="", trace_dir="",
-                prompt_context=None):
+                prompt_context=None, parse_retries=0):
             calls.append({
                 "context_lines": context_lines,
                 "context_blocks": context_blocks,
diff --git a/tests/test_orchestrator_rule_cap.py b/tests/test_orchestrator_rule_cap.py
index 3b418c4..e70c759 100644
--- a/tests/test_orchestrator_rule_cap.py
+++ b/tests/test_orchestrator_rule_cap.py
@@ -605,11 +605,11 @@ def _pinned_clock(self, monkeypatch):
     def test_cap_zero_with_rules_is_byte_identical_to_base(self, name):
         text, res = rules_capture(name, max_findings_per_rule=0)
         assert _sha(text) == RULES_GOLDEN[name]
-        assert set(res) == set(A81_RECORD_KEYS) | {"rule_counts", "repo_context"}
+        assert set(res) == set(A81_RECORD_KEYS) | {"rule_counts", "repo_context", "parse_retries"}
         assert res["rule_counts"] is None
         assert res["repo_context"] is None
         payload = list(cli._build_json_result(res))
-        assert payload == [*A81_JSON_KEYS[:-1], "rule_counts", "repo_context", "sampling"]
+        assert payload == [*A81_JSON_KEYS[:-1], "rule_counts", "repo_context", "parse_retries", "sampling"]
 
     @pytest.mark.parametrize("name", ["rules", "scoped", "rules_grouping"])
     def test_the_golden_is_sensitive_to_the_default_cap(self, name):
diff --git a/tests/test_parse_retry_orchestrator.py b/tests/test_parse_retry_orchestrator.py
new file mode 100644
index 0000000..c22f664
--- /dev/null
+++ b/tests/test_parse_retry_orchestrator.py
@@ -0,0 +1,393 @@
+"""The parse retry through the orchestrator and the CLI (issue #21).
+
+``orchestrate_review(llm_parse_retries=N)`` hands N to every chunk worker and
+to the sweep as ``parse_retries``; the library default is 0 and the CLI
+passes ``PRXREF_LLM_PARSE_RETRIES`` (default 1). A unit whose reviewer meta
+carries ``parse_retries`` and ``first_error`` keeps both in its worker
+result, and the run record's ``parse_retries`` is ``None`` at N=0 and the
+sum over every chunk and the sweep otherwise.
+
+The retry itself is the real reviewer's (tests/test_parse_retry_reviewer.py
+covers it unit by unit); these tests drive it through ``orchestrate_review``
+with a scripted LLM, and read each unit's worker result where the run
+prices it (``_stamp_run_cost``, wrapped, not replaced).
+"""
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from prxref import cli, orchestrator
+from prxref.llm import InvokeResult
+from prxref.orchestrator import orchestrate_review
+from tests.test_integration import MockOpenAIServer, _CLIHarness, _completion, _good_content
+from tests.test_orchestrator import REF, FakeForge, _added_file_diff, multi_chunk_diff
+from tests.test_run_record import PATHS, SCOPED_PATHS, _run
+
+VALID = json.dumps({"findings": []})
+BAD = "not json at all"
+LIST = "[]"
+ONE_FINDING = json.dumps({"findings": [{
+    "file": "src/app.py", "line": 3, "severity": "warning", "confidence": 0.9,
+    "title": "Unchecked data write", "body": "The data line is written without validation.",
+}]})
+BAD_ERROR = "JSONDecodeError: Expecting value: line 1 column 1 (char 0)"
+LIST_ERROR = "worker review JSON is not an object: list"
+TIMEOUT = "LLMError: m1: timeout (ReadTimeout)"
+ONE_CHUNK_DIFF = _added_file_diff("src/app.py", 20)
+
+
+class ScriptedLLM:
+    """Returns one scripted reply text per ``invoke`` call, in call order."""
+
+    def __init__(self, texts: list[str]):
+        self.texts = list(texts)
+        self.calls = 0
+
+    def invoke(self, system, user, *, max_tokens=4096, json_mode=False, timeout_s=60.0):
+        self.calls += 1
+        return InvokeResult(
+            text=self.texts.pop(0), input_tokens=100, output_tokens=50,
+            model="test-model-1", backend="fake", elapsed_ms=1, finish_reason="stop",
+        )
+
+
+@pytest.fixture
+def units(monkeypatch):
+    """Every review unit's worker result, as the run prices it (chunks in order, then the sweep)."""
+    seen: list[dict] = []
+    real = orchestrator._stamp_run_cost
+
+    def spy(run_inputs, results, price_table):
+        seen.extend(dict(unit) for unit in results)
+        real(run_inputs, results, price_table)
+
+    monkeypatch.setattr(orchestrator, "_stamp_run_cost", spy)
+    return seen
+
+
+def _review(texts, *, diff=ONE_CHUNK_DIFF, **kw):
+    llm = ScriptedLLM(texts)
+    res = orchestrate_review(FakeForge(diff=diff), REF, llm, post=False, max_workers=1, **kw)
+    return res, llm
+
+
+def _meta_double(calls: list, name: str, outcomes: list[dict] | None = None, *, raises=None):
+    """A review_chunk / review_systemic double that records its ``parse_retries`` keyword.
+
+    It takes ``**kwargs``, so a keyword the orchestrator stopped passing is
+    recorded as ``"absent"`` rather than breaking the call. Each call pops
+    one dict from ``outcomes`` into its meta when given.
+    """
+    def double(llm, target, **kwargs):
+        calls.append((name, kwargs.get("parse_retries", "absent")))
+        if raises is not None:
+            raise raises
+        meta = {
+            "escalations": [], "input_tokens": 1, "output_tokens": 1,
+            "model": "m", "elapsed_ms": 1, "error": "",
+        }
+        if outcomes:
+            meta.update(outcomes.pop(0))
+        return [], meta
+
+    return double
+
+
+class TestLibraryDefault:
+    def test_the_record_is_null_and_a_bad_reply_is_not_retried(self, units):
+        res, llm = _review([BAD, VALID])
+        assert llm.calls == 2
+        assert res["parse_retries"] is None
+        assert res["chunks_failed"] == 1
+        assert res["verdict"] == "Error"
+        assert units[0]["error"] == BAD_ERROR
+        assert all("parse_retries" not in unit and "first_error" not in unit for unit in units)
+
+    def test_an_explicit_zero_is_the_default(self, units):
+        res, llm = _review([BAD, VALID], llm_parse_retries=0)
+        assert llm.calls == 2
+        assert res["parse_retries"] is None
+        assert all("parse_retries" not in unit for unit in units)
+
+    def test_a_negative_budget_records_null_like_zero(self):
+        res, llm = _review([BAD, VALID], llm_parse_retries=-1)
+        assert llm.calls == 2
+        assert res["parse_retries"] is None
+
+    def test_a_non_int_budget_is_an_error_run_not_a_raise(self):
+        """A degenerate library argument degrades the run, as ``max_chunks=0`` does."""
+        res, _ = _review([VALID, VALID], llm_parse_retries=None)
+        assert res["verdict"] == "Error"
+        assert res["parse_retries"] is None
+
+
+class TestOneRetry:
+    def test_a_malformed_then_valid_chunk_records_one_and_keeps_its_meta(self, units):
+        res, llm = _review([BAD, ONE_FINDING, VALID], llm_parse_retries=1)
+        assert llm.calls == 3
+        assert res["parse_retries"] == 1
+        assert res["chunks_failed"] == 0
+        chunk, sweep = units
+        assert chunk["error"] == ""
+        assert chunk["parse_retries"] == 1
+        assert chunk["first_error"] == BAD_ERROR
+        assert len(chunk["findings"]) == 1
+        assert list(chunk)[-2:] == ["parse_retries", "first_error"]
+        assert "parse_retries" not in sweep and "first_error" not in sweep
+
+    def test_both_calls_count_toward_the_units_tokens(self, units):
+        res, _ = _review([BAD, VALID, VALID], llm_parse_retries=1)
+        assert units[0]["input_tokens"] == 200
+        assert units[0]["output_tokens"] == 100
+        assert res["input_tokens"] == 300
+        assert res["output_tokens"] == 150
+
+    def test_a_clean_run_records_zero(self, units):
+        res, llm = _review([VALID, VALID], llm_parse_retries=1)
+        assert llm.calls == 2
+        assert res["parse_retries"] == 0
+        assert all("parse_retries" not in unit for unit in units)
+
+    def test_malformed_twice_fails_the_chunk_and_the_retry_still_counts(self, units):
+        res, llm = _review([BAD, BAD, VALID], llm_parse_retries=1)
+        assert llm.calls == 3
+        assert res["verdict"] == "Error"
+        assert res["chunks_failed"] == 1
+        assert res["parse_retries"] == 1
+        assert units[0]["error"] == BAD_ERROR
+        assert units[0]["parse_retries"] == 1
+
+    def test_the_sweep_keeps_its_meta_and_counts(self, units):
+        res, llm = _review([VALID, LIST, VALID], llm_parse_retries=1)
+        assert llm.calls == 3
+        assert res["parse_retries"] == 1
+        chunk, sweep = units
+        assert "parse_retries" not in chunk
+        assert sweep["parse_retries"] == 1
+        assert sweep["first_error"] == LIST_ERROR
+        assert sweep["error"] == ""
+
+
+class TestTheSum:
+    def test_chunks_and_the_sweep_add_up(self, units):
+        texts = [BAD, VALID, VALID, LIST, VALID]
+        res, llm = _review(texts, diff=multi_chunk_diff(2), llm_parse_retries=1)
+        assert llm.calls == 5
+        assert res["chunk_count"] == 3
+        assert res["parse_retries"] == 2
+        first, second, sweep = units
+        assert (first["parse_retries"], first["first_error"]) == (1, BAD_ERROR)
+        assert "parse_retries" not in second
+        assert (sweep["parse_retries"], sweep["first_error"]) == (1, LIST_ERROR)
+
+    def test_it_sums_retries_not_units(self, units):
+        texts = [BAD, LIST, VALID, BAD, VALID]
+        res, llm = _review(texts, llm_parse_retries=2)
+        assert llm.calls == 5
+        assert res["parse_retries"] == 3
+        assert units[0]["parse_retries"] == 2
+        assert units[0]["first_error"] == BAD_ERROR
+        assert units[1]["parse_retries"] == 1
+
+    def test_the_json_payload_carries_the_total(self):
+        res, _ = _review([BAD, VALID, VALID], llm_parse_retries=1)
+        payload = cli._build_json_result(res)
+        assert payload["parse_retries"] == 1
+        keys = list(payload)
+        assert keys.index("parse_retries") == keys.index("repo_context") + 1
+
+
+class TestThreading:
+    """Every worker and sweep call gets the budget as ``parse_retries=``, 0 included."""
+
+    def _doubles(self, monkeypatch, chunk_outcomes=None, sweep_outcomes=None):
+        calls: list = []
+        monkeypatch.setattr(
+            orchestrator.reviewer, "review_chunk", _meta_double(calls, "chunk", chunk_outcomes),
+        )
+        monkeypatch.setattr(
+            orchestrator.reviewer, "review_systemic", _meta_double(calls, "sweep", sweep_outcomes),
+        )
+        return calls
+
+    def test_the_default_passes_zero_explicitly(self, monkeypatch):
+        calls = self._doubles(monkeypatch)
+        orchestrate_review(FakeForge(diff=multi_chunk_diff(2)), REF, ScriptedLLM([]), post=False)
+        assert sorted(calls) == [("chunk", 0), ("chunk", 0), ("sweep", 0)]
+
+    def test_the_budget_reaches_every_chunk_and_the_sweep(self, monkeypatch):
+        calls = self._doubles(monkeypatch)
+        orchestrate_review(
+            FakeForge(diff=multi_chunk_diff(2)), REF, ScriptedLLM([]), post=False,
+            llm_parse_retries=3,
+        )
+        assert sorted(calls) == [("chunk", 3), ("chunk", 3), ("sweep", 3)]
+
+    def test_the_timeout_retry_gets_it_too(self, monkeypatch):
+        calls = self._doubles(monkeypatch, chunk_outcomes=[{"error": TIMEOUT}, {}])
+        res = orchestrate_review(
+            FakeForge(diff=ONE_CHUNK_DIFF), REF, ScriptedLLM([]), post=False,
+            llm_parse_retries=2,
+        )
+        assert calls == [("chunk", 2), ("chunk", 2), ("sweep", 2)]
+        assert res["chunks_failed"] == 0
+        assert res["parse_retries"] == 0
+
+
+class TestWhatCarriesNeither:
+    def test_a_timeout_retry_keeps_only_the_second_runs_count(self, monkeypatch, units):
+        """The documented gap: the timeout retry replaces the first run's result, counts included."""
+        calls: list = []
+        monkeypatch.setattr(orchestrator.reviewer, "review_chunk", _meta_double(calls, "chunk", [
+            {"error": TIMEOUT, "parse_retries": 1, "first_error": "first run"},
+            {"parse_retries": 1, "first_error": "second run"},
+        ]))
+        monkeypatch.setattr(orchestrator.reviewer, "review_systemic", _meta_double(calls, "sweep"))
+        res = orchestrate_review(
+            FakeForge(diff=ONE_CHUNK_DIFF), REF, ScriptedLLM([]), post=False,
+            llm_parse_retries=1,
+        )
+        assert res["parse_retries"] == 1
+        assert units[0]["first_error"] == "second run"
+
+    def test_a_raising_chunk_call_carries_neither(self, monkeypatch, units):
+        calls: list = []
+        monkeypatch.setattr(
+            orchestrator.reviewer, "review_chunk",
+            _meta_double(calls, "chunk", raises=RuntimeError("chunk boom")),
+        )
+        monkeypatch.setattr(orchestrator.reviewer, "review_systemic", _meta_double(calls, "sweep", [
+            {"parse_retries": 1, "first_error": LIST_ERROR},
+        ]))
+        res = orchestrate_review(
+            FakeForge(diff=ONE_CHUNK_DIFF), REF, ScriptedLLM([]), post=False,
+            llm_parse_retries=1,
+        )
+        assert res["verdict"] == "Error"
+        assert res["parse_retries"] == 1
+        assert units[0]["error"] == "chunk boom"
+        assert "parse_retries" not in units[0] and "first_error" not in units[0]
+
+    def test_a_raising_sweep_carries_neither(self, monkeypatch, units):
+        calls: list = []
+        monkeypatch.setattr(orchestrator.reviewer, "review_chunk", _meta_double(calls, "chunk", [
+            {"parse_retries": 1, "first_error": BAD_ERROR},
+        ]))
+        monkeypatch.setattr(
+            orchestrator.reviewer, "review_systemic",
+            _meta_double(calls, "sweep", raises=RuntimeError("sweep boom")),
+        )
+        res = orchestrate_review(
+            FakeForge(diff=ONE_CHUNK_DIFF), REF, ScriptedLLM([]), post=False,
+            llm_parse_retries=1,
+        )
+        assert res["parse_retries"] == 1
+        assert units[1]["error"] == "systemic sweep: sweep boom"
+        assert "parse_retries" not in units[1] and "first_error" not in units[1]
+
+    def test_a_crashed_worker_carries_neither(self, monkeypatch, units):
+        def crash(*args, **kwargs):
+            raise RuntimeError("worker boom")
+
+        monkeypatch.setattr(orchestrator, "_run_worker", crash)
+        res, _ = _review([VALID], llm_parse_retries=1)
+        assert res["verdict"] == "Error"
+        assert res["parse_retries"] == 0
+        assert units[0]["error"] == "worker crashed: worker boom"
+        assert "parse_retries" not in units[0] and "first_error" not in units[0]
+
+
+@pytest.mark.usefixtures("contract_stubs")
+class TestEveryExit:
+    """The key rides every exit through the run-record choke point."""
+
+    @pytest.mark.parametrize("path", PATHS + SCOPED_PATHS)
+    @pytest.mark.parametrize(("n", "expected"), [(0, None), (1, 0)])
+    def test_every_exit_carries_the_key(self, monkeypatch, tmp_path, path, n, expected):
+        res, _, _ = _run(monkeypatch, path, tmp_path, llm_parse_retries=n)
+        assert "parse_retries" in res
+        assert res["parse_retries"] == expected
+        assert type(res["parse_retries"]) is type(expected)
+        assert cli._build_json_result(res)["parse_retries"] == expected
+
+
+class TestHelpers:
+    def test_the_total_skips_units_without_an_int(self):
+        units = [
+            {"parse_retries": 2}, {}, {"parse_retries": True},
+            {"parse_retries": "3"}, {"parse_retries": None}, {"parse_retries": 1},
+        ]
+        assert orchestrator._parse_retry_total(units) == 3
+
+    def test_the_total_of_no_units_is_zero(self):
+        assert orchestrator._parse_retry_total([]) == 0
+
+    def test_retry_meta_is_empty_without_the_count(self):
+        assert orchestrator._retry_meta({"error": "", "first_error": "stray"}) == {}
+
+    def test_retry_meta_carries_both_keys(self):
+        meta = {"parse_retries": 2, "first_error": LIST_ERROR, "error": ""}
+        assert orchestrator._retry_meta(meta) == {"parse_retries": 2, "first_error": LIST_ERROR}
+
+    def test_retry_meta_defaults_a_missing_first_error(self):
+        assert orchestrator._retry_meta({"parse_retries": 1}) == {"parse_retries": 1, "first_error": ""}
+
+
+GARBAGE = "not json at all"
+
+
+def _counting_route(replies):
+    """An OpenAI route answering the Kth request with ``replies[K-1]``, then the last one forever."""
+    state = {"n": 0}
+
+    def route(payload):
+        state["n"] += 1
+        content = replies[min(state["n"], len(replies)) - 1]
+        return 200, _completion(content, "stop")
+
+    return route
+
+
+class TestTheCliPath:
+    """``cli._run_review`` with the integration harness: config default 1, real client and reviewer."""
+
+    def _review(self, monkeypatch, replies, env=None):
+        server = MockOpenAIServer(routes={"fast": _counting_route(replies)})
+        base_url = server.start()
+        try:
+            harness = _CLIHarness(monkeypatch, base_url, env or {})
+            result = harness.review(post=False)
+        finally:
+            server.stop()
+        return result, server
+
+    def test_the_default_makes_two_calls_on_a_garbage_reply(self, monkeypatch):
+        result, server = self._review(
+            monkeypatch, [GARBAGE, _good_content("src/auth.py"), VALID],
+        )
+        assert len(server.requests) == 3
+        assert result["chunks_failed"] == 0
+        assert result["parse_retries"] == 1
+        assert len(result["findings_active"]) == 1
+        assert result["input_tokens"] == 600
+        assert result["output_tokens"] == 240
+        assert cli._build_json_result(result)["parse_retries"] == 1
+
+    def test_garbage_twice_fails_the_chunk_after_two_calls(self, monkeypatch):
+        result, server = self._review(monkeypatch, [GARBAGE, GARBAGE, VALID])
+        assert len(server.requests) == 3
+        assert result["verdict"] == "Error"
+        assert result["parse_retries"] == 1
+
+    def test_zero_from_the_environment_makes_one_call_and_records_null(self, monkeypatch):
+        """Control: the same replies, the budget turned off."""
+        result, server = self._review(
+            monkeypatch, [GARBAGE, _good_content("src/auth.py"), VALID],
+            env={"PRXREF_LLM_PARSE_RETRIES": "0"},
+        )
+        assert len(server.requests) == 2
+        assert result["verdict"] == "Error"
+        assert result["parse_retries"] is None
+        assert cli._build_json_result(result)["parse_retries"] is None
diff --git a/tests/test_prompt_context.py b/tests/test_prompt_context.py
index 03409b6..fc82633 100644
--- a/tests/test_prompt_context.py
+++ b/tests/test_prompt_context.py
@@ -392,7 +392,8 @@ def test_a_finding_passes_through_untouched(self):
 def _recording_chunk_double(calls: list, *, outcomes: list[str] | None = None, item=None):
     def _rc(llm, files, *, pr_title="", pr_description="", repo_hint="",
             max_tokens=None, context_lines=None, context_blocks="",
-            sibling_files=(), trace_label="", trace_dir="", prompt_context=None):
+            sibling_files=(), trace_label="", trace_dir="", prompt_context=None,
+            parse_retries=0):
         calls.append({"prompt_context": prompt_context, "context_lines": context_lines})
         error = outcomes.pop(0) if outcomes else ""
         findings = [dict(item, file=files[0].path)] if item else []
@@ -407,7 +408,7 @@ def _rc(llm, files, *, pr_title="", pr_description="", repo_hint="",
 def _recording_sweep_double(calls: list, *, item=None):
     def _rs(llm, digest, *, pr_title="", pr_description="", repo_hint="",
             max_tokens=None, threads=(), trace_label="", trace_dir="",
-            prompt_context=None):
+            prompt_context=None, parse_retries=0):
         calls.append({"prompt_context": prompt_context})
         return ([dict(item)] if item else []), {
             "escalations": [], "input_tokens": 1, "output_tokens": 1,
diff --git a/tests/test_prompt_inputs.py b/tests/test_prompt_inputs.py
index d032a68..71fa5e8 100644
--- a/tests/test_prompt_inputs.py
+++ b/tests/test_prompt_inputs.py
@@ -141,7 +141,8 @@ def _meta():
 def _chunk_double(findings, calls=None):
     def _rc(llm, files, *, pr_title="", pr_description="", repo_hint="",
             max_tokens=None, context_lines=None, context_blocks="",
-            sibling_files=(), trace_label="", trace_dir="", prompt_context=None):
+            sibling_files=(), trace_label="", trace_dir="", prompt_context=None,
+            parse_retries=0):
         if calls is not None:
             calls.append(prompt_context)
         return list(findings), _meta()
@@ -152,7 +153,7 @@ def _rc(llm, files, *, pr_title="", pr_description="", repo_hint="",
 def _sweep_double(findings, calls=None):
     def _rs(llm, digest, *, pr_title="", pr_description="", repo_hint="",
             max_tokens=None, threads=(), trace_label="", trace_dir="",
-            prompt_context=None):
+            prompt_context=None, parse_retries=0):
         if calls is not None:
             calls.append(prompt_context)
         return list(findings), _meta()
diff --git a/tests/test_run_record.py b/tests/test_run_record.py
index 0a0e83b..6d8cb05 100644
--- a/tests/test_run_record.py
+++ b/tests/test_run_record.py
@@ -51,11 +51,11 @@
 RECORD_KEYS = {
     "cost_usd", "cost_estimated", "review_rules", "ticket_context",
     "spec_grounding", "size_advisory", "prompt_templates", "scoped_rules",
-    "rule_counts", "repo_context",
+    "rule_counts", "repo_context", "parse_retries",
 }
 NULL_WHEN_OFF = (
     "review_rules", "ticket_context", "spec_grounding", "size_advisory", "prompt_templates",
-    "scoped_rules", "rule_counts", "repo_context",
+    "scoped_rules", "rule_counts", "repo_context", "parse_retries",
 )
 
 REPLAY = {

From 1ae1335dc76d374f5f2ed94306192790727e035d Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:49:48 -0700
Subject: [PATCH 12/25] feat: repo context shares jvm_lang's Java facts and
 handles Kotlin types-only (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

repo_context's Java type regex, keyword set and JDK names are now the same
objects as prxref.jvm_lang's JAVA_TYPE_RE, JAVA_KEYWORDS and JDK_NAMES, so
there is one implementation; repo_contracts keeps importing _JAVA_KEYWORDS
unchanged. The java/javax-only Java import regex stays, because
jvm_lang.parse_import does not reproduce it exactly (it also accepts a
semicolon-less import and rejects two imports on one line).

Kotlin is answered here, before chunk_context is asked:
- language_of maps .kt and .kts, in any case, to "kotlin";
- definition_regexes("kotlin") is (jvm_lang.KOTLIN_TYPE_RE,), types only,
  like Java: class of any flavour, interface, named object, typealias;
- referenced_names for Kotlin uses the Kotlin keywords, drops JDK names and
  every segment (and the as-alias) of a kotlin.*, java.* or javax.* import
  on the added lines, and keeps only type-like names. kotlinx.* is kept.

The module docstring now says chunk_context handles Java and Kotlin itself
for the same-file context, and that this module keeps a types-only view for
repository context with the shared facts in prxref.jvm_lang.

A Kotlin file is therefore a same-language reader candidate for a Kotlin
chunk. New tests in tests/test_repo_context_kotlin.py.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/repo_context.py        | 157 +++++++++++----------
 tests/test_repo_context_kotlin.py | 219 ++++++++++++++++++++++++++++++
 2 files changed, 295 insertions(+), 81 deletions(-)
 create mode 100644 tests/test_repo_context_kotlin.py

diff --git a/src/prxref/repo_context.py b/src/prxref/repo_context.py
index 4e39bca..57a8e78 100644
--- a/src/prxref/repo_context.py
+++ b/src/prxref/repo_context.py
@@ -1,23 +1,33 @@
 """Repository context outside the diff: shared types and the definitions core.
 
 ``chunk_context`` answers what a referenced identifier IS only when its
-definition sits in the SAME changed file, and it knows no Java. This module
-holds the pieces the repository-context feature (``PRXREF_REPO_CONTEXT``)
-builds on: the :class:`ContextEntry` record every context source emits, the
-admission ranks in :data:`REASONS`, a language map and definition regexes that
-add Java, the names an added line references, a definition scan over the
-text of ANY file, and the exclude floor (:data:`EXCLUDE_FLOOR`,
+definition sits in the SAME changed file. This module holds the pieces the
+repository-context feature (``PRXREF_REPO_CONTEXT``) builds on: the
+:class:`ContextEntry` record every context source emits, the admission ranks
+in :data:`REASONS`, a language map and definition regexes that answer Java and
+Kotlin themselves, the names an added line references, a definition scan over
+the text of ANY file, and the exclude floor (:data:`EXCLUDE_FLOOR`,
 :func:`exclude_predicate`) that keeps label files and secrets out of every read.
 
-The module is pure. It is stdlib plus :mod:`prxref.chunk_context` and
-:func:`prxref.rules.match_globs`, performs no I/O and no network, and
-callers hand it file text they already read. It
+The module is pure. It is stdlib plus :mod:`prxref.chunk_context`,
+:mod:`prxref.jvm_lang` and :func:`prxref.rules.match_globs`, performs no I/O
+and no network, and callers hand it file text they already read. It
 imports ``chunk_context``'s underscore helpers (``_language``,
 ``_definition_regexes``, ``_keywords``, ``_entry_text``, ``_IDENT_RE``) on
 purpose, so both modules scan and render a definition the same way instead of
-drifting apart. Java lives here rather than in
-``chunk_context._definition_regexes`` because ``referenced_definitions`` runs
-with the feature off, and feature-off output must stay byte-identical.
+drifting apart.
+
+``chunk_context`` handles Java and Kotlin itself for the same-file context,
+with methods, fields, enum constants and more. This module keeps a TYPES-ONLY
+view of both for repository context, and answers them before
+``chunk_context`` is consulted: a Java ``class``, ``interface``, ``record``,
+``enum`` or ``@interface`` declaration, and a Kotlin ``class`` of any flavour,
+``interface``, ``object`` or ``typealias``. That keeps the names a repository
+search looks for to type names, the names a JVM source file is called after,
+and keeps their number small. The shared facts live in
+:mod:`prxref.jvm_lang`: ``_JAVA_DEF_RE``, ``_JAVA_KEYWORDS`` and ``_JDK_NAMES``
+here are the SAME objects as its ``JAVA_TYPE_RE``, ``JAVA_KEYWORDS`` and
+``JDK_NAMES``, so there is one implementation.
 """
 from __future__ import annotations
 
@@ -25,62 +35,21 @@
 from collections.abc import Callable, Iterable, Sequence
 from dataclasses import dataclass
 
-from . import chunk_context
+from . import chunk_context, jvm_lang
 from .rules import match_globs
 
 REASONS = ("cross-chunk", "contract", "diff-file", "import", "path-convention", "name-search", "shared-state")
 KINDS = ("definition", "contract", "reader")
 
-_JAVA_DEF_RE = re.compile(
-    r"^\s*(?:(?:@(?!interface\b)[A-Za-z_$][\w$.]*(?:\((?:[^()]|\([^()]*\))*\))?"
-    r"|public|protected|private|static|final|abstract|sealed|non-sealed|strictfp)\s+)*"
-    r"(?:class|interface|record|enum|@interface)\s+([A-Za-z_$][A-Za-z0-9_$]*)"
-)
+_JAVA_DEF_RE = jvm_lang.JAVA_TYPE_RE
 
 _JAVA_IMPORT_RE = re.compile(r"^\s*import\s+(?:static\s+)?((?:java|javax)\.[\w$.]*[\w$])(?:\.\*)?\s*;")
 
-_JAVA_KEYWORDS = frozenset({
-    "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char",
-    "class", "const", "continue", "default", "do", "double", "else", "enum",
-    "exports", "extends", "false", "final", "finally", "float", "for", "goto",
-    "if", "implements", "import", "instanceof", "int", "interface", "long",
-    "module", "native", "new", "non", "null", "open", "opens", "package",
-    "permits", "private", "protected", "provides", "public", "record",
-    "requires", "return", "sealed", "short", "static", "strictfp", "super",
-    "switch", "synchronized", "this", "throw", "throws", "to", "transient",
-    "transitive", "true", "try", "uses", "var", "void", "volatile", "when",
-    "while", "with", "yield",
-})
-
-_JDK_NAMES = frozenset({
-    "AbstractMap", "ArithmeticException", "ArrayDeque", "ArrayIndexOutOfBoundsException",
-    "ArrayList", "Arrays", "AssertionError", "AtomicBoolean", "AtomicInteger",
-    "AtomicLong", "AtomicReference", "AutoCloseable", "Base64", "BigDecimal",
-    "BigInteger", "BiConsumer", "BiFunction", "BinaryOperator", "BiPredicate",
-    "Boolean", "Byte", "Callable", "CharSequence", "Character", "Charset",
-    "ChronoUnit", "Class", "ClassCastException", "Clock", "Cloneable",
-    "Collection", "Collections", "Collectors", "Comparable", "Comparator",
-    "CompletableFuture", "CompletionStage", "ConcurrentHashMap", "ConcurrentMap",
-    "Consumer", "CountDownLatch", "Date", "DateTimeFormatter", "Deprecated",
-    "Deque", "Double", "Duration", "Enum", "Error", "Exception", "ExecutorService",
-    "Executors", "File", "Files", "Float", "Function", "FunctionalInterface",
-    "Future", "HashMap", "HashSet", "IllegalArgumentException",
-    "IllegalStateException", "IndexOutOfBoundsException", "InputStream", "Instant",
-    "IntStream", "Integer", "InterruptedException", "IOException", "Iterable",
-    "Iterator", "LinkedHashMap", "LinkedHashSet", "LinkedList", "List",
-    "LocalDate", "LocalDateTime", "LocalTime", "Locale", "Long", "LongStream",
-    "Map", "Matcher", "Math", "NoSuchElementException", "NullPointerException",
-    "Number", "NumberFormatException", "Object", "Objects", "OffsetDateTime",
-    "Optional", "OptionalDouble", "OptionalInt", "OptionalLong", "OutputStream",
-    "Override", "Path", "Paths", "Pattern", "Period", "Predicate", "PriorityQueue",
-    "Queue", "Random", "Reader", "Record", "ReentrantLock", "Runnable", "Runtime",
-    "RuntimeException", "SafeVarargs", "Set", "Short", "SortedMap", "SortedSet",
-    "StandardCharsets", "Stream", "String", "StringBuilder", "StringJoiner",
-    "Supplier", "SuppressWarnings", "System", "Thread", "ThreadLocal", "Throwable",
-    "TimeUnit", "TreeMap", "TreeSet", "UUID", "UnaryOperator",
-    "UncheckedIOException", "UnsupportedOperationException", "URI", "URL", "Void",
-    "Writer", "ZoneId", "ZoneOffset", "ZonedDateTime",
-})
+_JAVA_KEYWORDS = jvm_lang.JAVA_KEYWORDS
+
+_JDK_NAMES = jvm_lang.JDK_NAMES
+
+_KOTLIN_PLATFORM_ROOTS = frozenset({"kotlin", "java", "javax"})
 
 
 @dataclass(frozen=True)
@@ -119,26 +88,33 @@ def record(self) -> dict:
 
 
 def language_of(path: str) -> str:
-    """The definition language of ``path``: ``chunk_context``'s map plus ``"java"`` for ``.java``.
+    """The definition language of ``path``: ``"java"``, ``"kotlin"``, else ``chunk_context``'s map.
 
-    Returns ``""`` for a path no language claims.
+    ``.java`` gives ``"java"`` and ``.kt`` or ``.kts`` gives ``"kotlin"``, in
+    any case, before ``chunk_context`` is asked; a ``.kts`` build script is
+    Kotlin too. Returns ``""`` for a path no language claims.
     """
-    if path.lower().endswith(".java"):
-        return "java"
-    return chunk_context._language(path)
+    return jvm_lang.jvm_language(path) or chunk_context._language(path)
 
 
 def definition_regexes(language: str) -> tuple[re.Pattern[str], ...]:
     """The definition regexes for ``language``; group 1 of a match is the defined name.
 
-    ``"java"`` gets one regex for a type declaration (``class``, ``interface``,
-    ``record``, ``enum`` or ``@interface``, after optional modifiers and
-    same-line annotations); it never matches a method, a field or a local
-    variable. Every other language delegates to ``chunk_context``, which covers
-    js and python and returns ``()`` otherwise.
+    Java and Kotlin get one regex each, for a type declaration only.
+    ``"java"`` gets :data:`prxref.jvm_lang.JAVA_TYPE_RE` (``class``,
+    ``interface``, ``record``, ``enum`` or ``@interface``, after optional
+    modifiers and same-line annotations). ``"kotlin"`` gets
+    :data:`prxref.jvm_lang.KOTLIN_TYPE_RE` (``class`` in every flavour, such as
+    ``data class`` or ``enum class``, ``interface``, a named ``object`` and
+    ``typealias``). Neither ever matches a method or function, a field or
+    property, or a local variable. Every other language delegates to
+    ``chunk_context``, which covers js and python and returns ``()``
+    otherwise.
     """
     if language == "java":
         return (_JAVA_DEF_RE,)
+    if language == "kotlin":
+        return (jvm_lang.KOTLIN_TYPE_RE,)
     return chunk_context._definition_regexes(language)
 
 
@@ -151,6 +127,16 @@ def _jdk_imports(added: Iterable[str]) -> set[str]:
     return names
 
 
+def _kotlin_platform_imports(added: Iterable[str]) -> set[str]:
+    names: set[str] = set()
+    for parsed in jvm_lang.parse_imports(added):
+        if parsed.segments[0] in _KOTLIN_PLATFORM_ROOTS:
+            names.update(parsed.segments)
+            if parsed.alias:
+                names.add(parsed.alias)
+    return names
+
+
 def _type_like(name: str) -> bool:
     return name[:1].isupper() and any(c.islower() for c in name)
 
@@ -160,17 +146,24 @@ def referenced_names(added: Iterable[str], language: str) -> list[str]:
 
     Language keywords are removed, and so is every name a
     :func:`definition_regexes` match defines on the added lines themselves, as
-    ``chunk_context.referenced_definitions`` does. For Java, JDK names are also
-    removed (every segment of a ``java.*`` or ``javax.*`` import on the added
-    lines, plus a built-in set of common ``java.lang``, ``java.util``,
-    ``java.time`` and related types), and only type-like names are kept: an
-    uppercase first letter and at least one lowercase letter, since a Java
-    definition regex can only ever find a type. That drops constants, locals,
-    methods and single-letter type parameters.
+    ``chunk_context.referenced_definitions`` does. Java and Kotlin, whose
+    definition regexes here can only ever find a type, are filtered further:
+
+    - keywords are :func:`prxref.jvm_lang.keywords` of the language;
+    - JDK names are removed: the built-in set of common ``java.lang``,
+      ``java.util``, ``java.time`` and related types
+      (:data:`prxref.jvm_lang.JDK_NAMES`), plus every segment of a
+      ``java.*`` or ``javax.*`` import on the added lines. For Kotlin that
+      covers a ``kotlin.*`` import too, with or without a semicolon, and the
+      ``as`` alias of any of the three; ``kotlinx.*`` is a library, not the
+      platform, and is kept;
+    - only type-like names are kept: an uppercase first letter and at least
+      one lowercase letter. That drops constants, locals, methods and
+      functions, properties and single-letter type parameters.
     """
     lines = list(added)
-    java = language == "java"
-    keywords = _JAVA_KEYWORDS if java else chunk_context._keywords(language)
+    language_is_jvm = language in ("java", "kotlin")
+    keywords = jvm_lang.keywords(language) if language_is_jvm else chunk_context._keywords(language)
     defined: set[str] = set()
     for text in lines:
         for regex in definition_regexes(language):
@@ -178,14 +171,16 @@ def referenced_names(added: Iterable[str], language: str) -> list[str]:
             if match:
                 defined.add(match.group(1))
     dropped = keywords | defined
-    if java:
+    if language == "java":
         dropped = dropped | _JDK_NAMES | _jdk_imports(lines)
+    elif language == "kotlin":
+        dropped = dropped | _JDK_NAMES | _kotlin_platform_imports(lines)
     out: dict[str, None] = {}
     for text in lines:
         for name in chunk_context._IDENT_RE.findall(text):
             if name in dropped or name in out:
                 continue
-            if java and not _type_like(name):
+            if language_is_jvm and not _type_like(name):
                 continue
             out[name] = None
     return list(out)
diff --git a/tests/test_repo_context_kotlin.py b/tests/test_repo_context_kotlin.py
new file mode 100644
index 0000000..670d156
--- /dev/null
+++ b/tests/test_repo_context_kotlin.py
@@ -0,0 +1,219 @@
+"""Kotlin in repository context, and the Java facts shared with :mod:`prxref.jvm_lang` (#20).
+
+:mod:`prxref.repo_context` keeps a types-only view of Java and Kotlin for
+repository context. These pin that the Java regex, keywords and JDK names are
+``jvm_lang``'s own objects, that ``.kt`` and ``.kts`` paths are Kotlin, that the
+Kotlin definition regex finds types and nothing else, which names a Kotlin
+added line references, and that a Kotlin file is a same-language reader
+candidate for a Kotlin chunk. No test touches the network.
+"""
+from __future__ import annotations
+
+import pytest
+
+from prxref import jvm_lang, repo_context, repo_contracts
+from prxref.chunk_context import ChunkFile
+from prxref.repo_context import definition_regexes, language_of, referenced_names
+from prxref.repo_readers import reader_candidates, reader_entries
+
+
+class _Recording:
+    """A ``read(path)`` over a dict that records every path asked for, in call order."""
+
+    def __init__(self, files: dict[str, str]):
+        self.files = files
+        self.calls: list[str] = []
+
+    def __call__(self, path: str) -> str | None:
+        self.calls.append(path)
+        return self.files.get(path)
+
+
+def _kotlin_match(line: str) -> str | None:
+    for regex in definition_regexes("kotlin"):
+        match = regex.match(line)
+        if match:
+            return match.group(1)
+    return None
+
+
+class TestSharedJavaFacts:
+    def test_java_regex_keywords_and_jdk_names_are_the_jvm_lang_objects(self):
+        assert repo_context._JAVA_DEF_RE is jvm_lang.JAVA_TYPE_RE
+        assert repo_context._JAVA_KEYWORDS is jvm_lang.JAVA_KEYWORDS
+        assert repo_context._JDK_NAMES is jvm_lang.JDK_NAMES
+
+    def test_repo_contracts_keeps_importing_the_java_keywords(self):
+        assert repo_contracts._JAVA_KEYWORDS is jvm_lang.JAVA_KEYWORDS
+
+    def test_java_stays_types_only_here(self):
+        assert definition_regexes("java") == (jvm_lang.JAVA_TYPE_RE,)
+
+
+class TestLanguageOf:
+    @pytest.mark.parametrize(
+        ("path", "language"),
+        [
+            ("src/main/kotlin/com/acme/App.kt", "kotlin"),
+            ("src/main/kotlin/com/acme/App.KT", "kotlin"),
+            ("build.gradle.kts", "kotlin"),
+            ("scripts/tool.main.KTS", "kotlin"),
+            ("src/main/java/com/acme/App.java", "java"),
+            ("src/main/java/com/acme/App.JAVA", "java"),
+            ("pkg/mod.py", "python"),
+            ("web/app.ts", "js"),
+            ("notes/App.kt.md", ""),
+            ("res/App.ktx", ""),
+        ],
+    )
+    def test_suffix_gives_the_language(self, path, language):
+        assert language_of(path) == language
+
+
+class TestKotlinDefinitions:
+    def test_kotlin_gets_the_types_only_regex(self):
+        assert definition_regexes("kotlin") == (jvm_lang.KOTLIN_TYPE_RE,)
+        assert definition_regexes("kotlin")[0] is jvm_lang.KOTLIN_TYPE_RE
+
+    @pytest.mark.parametrize(
+        ("line", "name"),
+        [
+            ("class Widget(val id: String)", "Widget"),
+            ("data class Payload(val body: String)", "Payload"),
+            ("@Serializable data class Dto(", "Dto"),
+            ("sealed class Result<out T> {", "Result"),
+            ("enum class Mode { A, B }", "Mode"),
+            ("object Registry {", "Registry"),
+            ("    companion object Factory {", "Factory"),
+            ("interface Transport {", "Transport"),
+            ("fun interface Listener {", "Listener"),
+            ("typealias Handler = (String) -> Unit", "Handler"),
+        ],
+    )
+    def test_type_declarations_match(self, line, name):
+        assert _kotlin_match(line) == name
+
+    @pytest.mark.parametrize(
+        "line",
+        [
+            "fun f()",
+            "val x = 1",
+            "var y = 2",
+            "    override fun toString(): String = name",
+            "    private val cache = mutableMapOf<String, Int>()",
+            "suspend fun <T> List<T>.firstOrFail(): T {",
+            "    companion object {",
+            "import com.acme.Widget",
+            "package com.acme",
+        ],
+    )
+    def test_functions_properties_and_locals_match_nothing(self, line):
+        assert _kotlin_match(line) is None
+
+
+class TestKotlinReferencedNames:
+    def test_keeps_referenced_types_in_first_appearance_order(self):
+        added = [
+            "import kotlin.reflect.KClass",
+            "import java.time.Year",
+            "import javax.inject.Inject",
+            "import com.acme.billing.Invoice",
+            "class Widget @Inject constructor(private val store: Store) {",
+            "    override fun render(invoice: Invoice): Payload = Payload(store.load(invoice.id), Year.now())",
+            "    val kind: KClass<Order> = Order::class",
+            "}",
+        ]
+        assert referenced_names(added, "kotlin") == ["Invoice", "Store", "Payload", "Order"]
+
+    def test_the_kotlin_import_is_what_drops_an_unlisted_platform_type(self):
+        use = "    val kind: KClass<Widget> = Widget::class"
+        assert referenced_names([use], "kotlin") == ["KClass", "Widget"]
+        assert referenced_names(["import kotlin.reflect.KClass", use], "kotlin") == ["Widget"]
+
+    @pytest.mark.parametrize(
+        ("line", "name"),
+        [
+            ("import java.time.Year", "Year"),
+            ("import java.time.Year;", "Year"),
+            ("import javax.inject.Inject", "Inject"),
+            ("import kotlin.reflect.KClass", "KClass"),
+            ("import kotlin.reflect.KClass // reflection", "KClass"),
+        ],
+    )
+    def test_java_javax_and_kotlin_import_segments_are_dropped(self, line, name):
+        use = "val made = Year.of(1) + Inject() + KClass<Widget>()"
+        assert referenced_names([use], "kotlin") == ["Year", "Inject", "KClass", "Widget"]
+        expected = [kept for kept in ["Year", "Inject", "KClass", "Widget"] if kept != name]
+        assert referenced_names([line, use], "kotlin") == expected
+
+    def test_another_organizations_import_is_kept(self):
+        added = ["import com.acme.billing.Invoice", "val made = Invoice()"]
+        assert referenced_names(added, "kotlin") == ["Invoice"]
+
+    def test_the_alias_of_a_platform_import_is_dropped(self):
+        added = ["import kotlin.collections.ArrayDeque as Queue", "val q = Queue<Widget>()"]
+        assert referenced_names(added, "kotlin") == ["Widget"]
+
+    def test_kotlinx_is_a_library_not_the_platform(self):
+        added = ["import kotlinx.coroutines.flow.Flow", "fun stream(): Flow<Widget> = TODO()"]
+        assert referenced_names(added, "kotlin") == ["Flow", "Widget"]
+
+    def test_jdk_names_are_dropped(self):
+        assert referenced_names(["val m = HashMap<String, Widget>()"], "kotlin") == ["Widget"]
+
+    def test_only_type_like_names_are_kept(self):
+        added = ["val total = MAX_SIZE + X + widgetCount + Widget.DEFAULT + _Hidden + limit"]
+        assert referenced_names(added, "kotlin") == ["Widget"]
+
+    def test_types_declared_on_the_added_lines_are_dropped(self):
+        assert referenced_names(["data class Local(val remote: Remote)"], "kotlin") == ["Remote"]
+
+    def test_keywords_come_from_the_kotlin_keyword_set(self, monkeypatch):
+        added = ["override fun render(): Payload = Widget()"]
+        assert referenced_names(added, "kotlin") == ["Payload", "Widget"]
+        monkeypatch.setattr(jvm_lang, "KOTLIN_KEYWORDS", jvm_lang.KOTLIN_KEYWORDS | {"Payload"})
+        assert referenced_names(added, "kotlin") == ["Widget"]
+        assert referenced_names(["Payload p = new Widget();"], "java") == ["Payload", "Widget"]
+
+
+class TestKotlinReaders:
+    WRITER = ChunkFile(path="src/main/kotlin/com/acme/Ledger.kt", added=("        this.cache[key] = value",))
+
+    READER = "\n".join([
+        "package com.acme",
+        "",
+        "class Report(private val frames: Frames) {",
+        "    fun load(id: String): Any? {",
+        "        return frames.cache[id]",
+        "    }",
+        "}",
+    ])
+
+    def test_a_kotlin_file_is_a_same_language_candidate(self):
+        listing = ["src/b/Other.kt", "src/a/Reader.kt", "build.gradle.kts", "src/a/Legacy.java", "src/a/view.py"]
+        assert reader_candidates(["src/a/Writer.kt"], listing) == [
+            "src/a/Reader.kt",
+            "src/b/Other.kt",
+            "build.gradle.kts",
+        ]
+
+    def test_reader_entries_reads_kotlin_readers_of_a_kotlin_chunk(self):
+        java_reader = "class Legacy {\n    Object load(String id) {\n        return frames.cache.get(id);\n    }\n}\n"
+        files = {
+            "src/main/kotlin/com/acme/Report.kt": self.READER,
+            "src/main/kotlin/com/acme/Changed.kt": self.READER,
+            "src/main/java/com/acme/Legacy.java": java_reader,
+            "src/main/python/reader.py": "def f(x):\n    return x.cache\n",
+        }
+        read = _Recording(files)
+        entries = reader_entries(
+            [self.WRITER],
+            listing=set(files),
+            read=read,
+            diff_paths={"src/main/kotlin/com/acme/Changed.kt"},
+        )
+        assert read.calls == ["src/main/kotlin/com/acme/Report.kt"]
+        assert [(e.path, e.line, e.symbol, e.kind, e.reason) for e in entries] == [
+            ("src/main/kotlin/com/acme/Report.kt", 4, "cache", "reader", "shared-state"),
+        ]
+        assert entries[0].text == "    fun load(id: String): Any? {\n        return frames.cache[id]"

From 1cb74044aad8a77b370ec4ad4b841b278fe7263b Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:52:47 -0700
Subject: [PATCH 13/25] feat: record the parse retry in evals (#21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

eval run allowlists llm_parse_retries into run.json's config (seventeen
keys, placed after llm_max_tokens with the other LLM settings). eval
score passes the loaded PRXREF_LLM_PARSE_RETRIES to judge_case as
parse_retries, so the judge re-sends a rejected reply as the review does,
and score.json's judge block totals the retries as parse_retries, beside
llm_calls. score.md's judge cost line names the retries only when there
were any, so a scoring run without one renders byte-identically.

The review's own retries are not totalled in score.json: a record's
parse_retries is null at PRXREF_LLM_PARSE_RETRIES=0 on a healthy review,
which the metrics' total/missing shape would misreport as missing, and
each case's record.json already carries its count.

docs/evals.md documents the key, the judge's parse retries (a reply cut
short at the token limit included), its trace files and the judge block
key, and corrects the judge-cost wording for a retry that raised after a
billed reply. judge_cost's docstring says the same. Two judge-block key
order pins in the score and end-to-end tests gain the new key.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 docs/evals.md                    |  64 ++++++--
 src/prxref/eval_judge.py         |  12 +-
 src/prxref/evals.py              |  35 +++--
 tests/test_eval_end_to_end.py    |   2 +-
 tests/test_eval_parse_retries.py | 256 +++++++++++++++++++++++++++++++
 tests/test_eval_score.py         |   2 +-
 6 files changed, 339 insertions(+), 32 deletions(-)
 create mode 100644 tests/test_eval_parse_retries.py

diff --git a/docs/evals.md b/docs/evals.md
index 7840151..f3f822f 100644
--- a/docs/evals.md
+++ b/docs/evals.md
@@ -266,6 +266,12 @@ matter for a comparison are recorded in `run.json`. In particular:
   `trace/` directory.
 - `PRXREF_TRACE_FILE` is inherited, so every case appends to the same JSONL
   trace.
+- `PRXREF_LLM_PARSE_RETRIES` reaches every case's review, which re-sends a
+  chunk or sweep whose reply cannot be parsed, and the run records it under
+  `config.llm_parse_retries`. Each case's `record.json` carries the review's
+  own `parse_retries`. `eval score` reads the variable from its own
+  environment, not from `run.json`, to bound the judge's retries (see
+  [The judge](#the-judge)).
 
 So two arms that differ only in their scoped rules or prompt templates are
 set with these flags, and `run.json` and the `run` block of `score.json`
@@ -327,7 +333,7 @@ prxref-eval/                        --out
 | `sampling` | the reviewer's `temperature`, `seed` and `models` |
 | `review_rules` | the record's stamp of the rules file, or `null` |
 | `scoped_rules` | the record's stamp of the path-scoped rules (`entries`, `files`, `max_chars`, `units`; never the rules text), or `null` |
-| `config` | the settings `llm_backend`, `llm_models`, `llm_max_tokens`, `max_chunks`, `chunk_token_budget`, `chunk_max_files`, `dedup_similarity`, `group_findings`, `max_warning_findings`, `max_outofscope_findings`, `max_findings_per_rule`, `scoped_rules_max_chars`, `repo_context`, `repo_context_max_chars`, `context_contract_globs`, `context_exclude_globs` |
+| `config` | the settings `llm_backend`, `llm_models`, `llm_max_tokens`, `llm_parse_retries`, `max_chunks`, `chunk_token_budget`, `chunk_max_files`, `dedup_similarity`, `group_findings`, `max_warning_findings`, `max_outofscope_findings`, `max_findings_per_rule`, `scoped_rules_max_chars`, `repo_context`, `repo_context_max_chars`, `context_contract_globs`, `context_exclude_globs` |
 
 `prompts.sha256` always hashes the packaged templates, so an override shows
 only under `prompts.prompt_templates`. `prompt_templates`, `sampling`,
@@ -336,7 +342,7 @@ order, whose record's verdict is not `Error`. They are `null` when there is
 none, and `review_rules`, `scoped_rules` and `prompt_templates` are `null`
 when their input is off.
 
-**No credential is ever written.** `config` is an allowlist of the sixteen
+**No credential is ever written.** `config` is an allowlist of the seventeen
 settings above, and a record carries no credential. The traces do hold the
 prompts, and the prompts hold the diff, so treat a run directory like the
 code it reviewed.
@@ -420,8 +426,10 @@ is graded `full` (credit 1), `partial` (credit 0.5) or `none` (credit 0):
   `partial` or `none` per label, citing the AI finding that earns a credit.
   The code then checks every answer: a credit must name a real finding in
   the label's own file, or it becomes `none`; a label the judge left out is
-  `none`. A reply that cannot be read at all, or a call that fails, makes
-  every judge-tier label of that case `judge_error`.
+  `none`. A reply that cannot be read at all is asked for again (see
+  [The judge](#the-judge)); one still unreadable when the retries run out,
+  or a call that fails, makes every judge-tier label of that case
+  `judge_error`.
 
 `judge_error` is not `none`. A label the judge failed to grade is counted
 on its own and left out of every denominator, so a flaky judge lowers
@@ -465,8 +473,21 @@ which makes the run's review-cost total unknown too.
 - **Same backend, no separate key.** The judge runs on the review's own
   LLM backend, base URL, credentials, timeout, temperature and seed, with
   only the model changed to `--judge-model`. It is one model, not a chain:
-  an empty value or a comma-separated list exits `2`. There is no judge
-  setting other than the flag.
+  an empty value or a comma-separated list exits `2`. The flag is the
+  judge's only setting of its own; `PRXREF_LLM_PARSE_RETRIES` bounds its
+  retries as it bounds the review's.
+- **Parse retries.** A reply the judge parser rejects, for any reason (not
+  JSON, not an object, no `grades` list, or a grades row that is not an
+  object, has no `human_id` or names an unknown grade), is asked for again
+  with the same request while fewer than `PRXREF_LLM_PARSE_RETRIES`
+  (default `1`) retries have run, so a case makes at most one call more than
+  that number. A judge reply cut short at the token limit is retried like
+  any other rejected reply, where a review chunk's is not. Each retry logs a
+  WARNING ending `parse retry <k> of <N>`. A call that raises is never
+  retried, and `0` turns retries off. When the retries run out, the case is
+  a judge error carrying the last reply's reason. Every attempt's tokens
+  and cost count toward the case, including a rejected reply followed by a
+  retry that raised.
 - **The cache.** Each case's graded reply is cached under
   `<out>/<label>/judge-cache/`, keyed on the judge prompt's SHA-256, the
   judge model, and the labels and AI findings exactly as the judge sees
@@ -482,7 +503,12 @@ which makes the run's review-cost total unknown too.
   with a note that the grades may be inflated. It is not an error: the
   score is still written.
 - **Traces.** A live judge call writes `judge.system.md`, `judge.user.md`,
-  `judge.response.json` and `judge.meta.json` into the case's `trace/`.
+  `judge.response.json` and `judge.meta.json` into the case's `trace/`, for
+  its last call. With `PRXREF_LLM_PARSE_RETRIES` at `1` or more,
+  each rejected reply that was retried is kept as
+  `judge.attempt<K>.response.json` (`K` from 1), and once a retry ran
+  `judge.meta.json` adds `parse_retries` and `first_error`, the reason the
+  first reply was rejected.
 
 ### `score.json`
 
@@ -499,10 +525,14 @@ The keys, in order:
     version and SHA-256;
   - `self_judged`;
   - `cost_usd` and `cost_estimated`: the cost of this scoring's judge
-    calls. A cached case costs nothing, so a fully cached rescore reports
-    `0.0`. A call that raised adds nothing, unless every call raised,
-    which makes it `null`, and so does one reply nothing could price;
-  - `llm_calls`: the judge calls made;
+    calls, parse retries included. A cached case costs nothing, so a fully
+    cached rescore reports `0.0`. A case whose every call raised adds
+    nothing. It is `null` when every call made raised, or when nothing
+    could price one reply;
+  - `llm_calls`: the judge calls made, parse retries included;
+  - `parse_retries`: how many of those calls re-sent a request because the
+    reply before it was rejected, summed over the cases; `0` when nothing
+    was retried or `PRXREF_LLM_PARSE_RETRIES` is `0`;
   - `cached`: the cases answered from the cache;
   - `errors`: `[{"case_id", "error"}]` for each case the judge failed to
     grade, by case id.
@@ -558,9 +588,10 @@ The keys, in order:
   `priced`, `unpriced` and `estimated` (the cases whose cost came from
   `PRXREF_PRICE_TABLE`). **An unknown cost is never summed:** one unpriced
   case makes `total_usd` and `per_pr_usd` `null`, and `unpriced` says how
-  many. `judge_cost` sums the per-case judge costs, where a case whose judge
-  call raised is unpriced, so it can be `null` while `judge.cost_usd`, which
-  skips a raised call, is a number.
+  many. `judge_cost` sums the per-case judge costs, where a case whose
+  every judge call raised is unpriced, so it can be `null` while
+  `judge.cost_usd`, which skips such a case, is a number. A case whose
+  retry raised after a rejected reply is priced by that reply.
 
 ### `score.md`
 
@@ -571,7 +602,10 @@ severity`, `## Recall by category`, `## Accepted labels`, `## Unmatched AI
 findings`, `## Severity agreement`, `## Chunks failed`, `## Elapsed`,
 `## Cost` and `## Judge`. An empty section reads `None.` (or `No labels.`
 for a recall table), an unknown value reads `unknown`, and a recall with
-nothing scored reads `n/a`. It holds no wall-clock time of the scoring run.
+nothing scored reads `n/a`. The judge's cost line names its parse retries
+only when there were any, as in `- Judge: $0.0040, 2 call(s) (1 parse
+retry), 0 case(s) from the cache`. It holds no wall-clock time of the
+scoring run.
 
 This is the `score.md` of a three-case fixture run in the test suite, with a
 judge; case `c` failed:
diff --git a/src/prxref/eval_judge.py b/src/prxref/eval_judge.py
index 6e06346..a44c7f9 100644
--- a/src/prxref/eval_judge.py
+++ b/src/prxref/eval_judge.py
@@ -342,11 +342,13 @@ def judge_cost(outcomes: Iterable[JudgeOutcome], price_table: Mapping[str, Any]
     """Total a scoring run's judge cost: ``(cost_usd, cost_estimated)``.
 
     Totals the :attr:`JudgeOutcome.unit` of every outcome that made a request
-    with :func:`prxref.costs.run_cost`, the rule a review's cost follows: a
-    request that raised is skipped, and any received call without a reported
-    or estimated figure makes the whole total ``None``, never ``0`` and never
-    a partial sum. A run that made no request (every case cached or
-    unlabelled) costs a known ``0.0``.
+    with :func:`prxref.costs.run_cost`, the rule a review's cost follows. A
+    case's unit sums every attempt it made, parse retries included, so a case
+    is skipped only when none of its calls received a reply; a case whose
+    retry raised after a rejected reply still counts that reply. Any received
+    case without a reported or estimated figure makes the whole total
+    ``None``, never ``0`` and never a partial sum. A run that made no request
+    (every case cached or unlabelled) costs a known ``0.0``.
     """
     units = [outcome.unit for outcome in outcomes if outcome.unit is not None]
     if not units:
diff --git a/src/prxref/evals.py b/src/prxref/evals.py
index a39d4a5..8be98d7 100644
--- a/src/prxref/evals.py
+++ b/src/prxref/evals.py
@@ -55,6 +55,7 @@
     "llm_backend",
     "llm_models",
     "llm_max_tokens",
+    "llm_parse_retries",
     "max_chunks",
     "chunk_token_budget",
     "chunk_max_files",
@@ -382,10 +383,14 @@ def eval_score(args: argparse.Namespace) -> int:
       the line of the location credited. The code checks that
       the ref is real and in the label's file, and the judge's replies are
       cached under ``<out>/<label>/judge-cache/``; a live call's prompt and
-      reply are traced as ``judge.*`` in the case's ``trace/``. A judge call
-      that fails or whose reply is rejected makes every judge-tier label of
-      that case ``judge_error``, which is left out of every denominator and
-      never read as ``none``.
+      reply are traced as ``judge.*`` in the case's ``trace/``. A reply the
+      judge parser rejects, for any reason, is asked for again with the same
+      request up to ``llm_parse_retries`` times (``PRXREF_LLM_PARSE_RETRIES``,
+      passed to :func:`~prxref.eval_judge.judge_case` as ``parse_retries``;
+      #21). A judge call that fails, or a reply still rejected when the
+      retries run out, makes every judge-tier label of that case
+      ``judge_error``, which is left out of every denominator and never read
+      as ``none``.
     - One AI finding credits at most two labels, across both tiers: when the
       deterministic tier has already used a finding's slots, a judge credit
       to it becomes ``none`` with a WARNING (``full`` keeps its slot before
@@ -429,8 +434,11 @@ def eval_score(args: argparse.Namespace) -> int:
       :func:`prxref.eval_judge.judge_stamp` (``model``, ``sampling``,
       ``prompt_version``, ``prompt_sha256``, ``self_judged``) followed by
       ``cost_usd`` and ``cost_estimated`` (:func:`prxref.eval_judge.judge_cost`
-      over every judge request), ``llm_calls``, ``cached`` (cases served from
-      the cache) and ``errors`` (``[{"case_id", "error"}]``, by case id);
+      over every judge request), ``llm_calls``, ``parse_retries`` (the
+      calls that re-sent a request whose reply the judge parser rejected,
+      summed over the cases; ``PRXREF_LLM_PARSE_RETRIES`` bounds them per
+      case, #21), ``cached`` (cases served from the cache) and ``errors``
+      (``[{"case_id", "error"}]``, by case id);
     - ``failed``: ``[{"case_id", "error"}]`` for each case whose review
       failed, by case id;
     - ``metrics`` and ``cases``: :func:`prxref.eval_metrics.score_cases`.
@@ -443,7 +451,8 @@ def eval_score(args: argparse.Namespace) -> int:
     severity``, ``Recall by category``, ``Accepted labels``, ``Unmatched AI
     findings``, ``Severity agreement`` (a human ``minor`` counts as
     ``warning``), ``Chunks failed``, ``Elapsed``, ``Cost`` and ``Judge``. A
-    ``None`` cost is written as ``unknown`` and never summed. It holds no
+    ``None`` cost is written as ``unknown`` and never summed. The judge's
+    cost line names its parse retries only when there were any. It holds no
     wall-clock time of the scoring run.
 
     Standard output gets the headline line, then ``score: <path of
@@ -606,6 +615,7 @@ def _grade_case(
             price_table=cfg["price_table"],
             max_tokens=cfg["llm_max_tokens"],
             trace_dir=str(run_case.case_dir / "trace"),
+            parse_retries=cfg["llm_parse_retries"],
         )
         grades.update(_judge_grades(outcome, judged, judge_record["findings"], origin))
     else:
@@ -711,14 +721,15 @@ def _judge_block(
     outcomes: Sequence[eval_judge.JudgeOutcome],
     price_table: Any,
 ) -> dict[str, Any]:
-    """The ``judge`` stamp of ``score.json``: the judge stamp plus the run's judge cost and calls."""
+    """The ``judge`` stamp of ``score.json``: the judge stamp plus the run's judge cost, calls and retries."""
     cost_usd, cost_estimated = eval_judge.judge_cost(outcomes, price_table)
     return {
         **eval_judge.judge_stamp(client, judge_model, self_judged=self_judged),
         "cost_usd": cost_usd,
         "cost_estimated": cost_estimated,
         "llm_calls": sum(outcome.llm_calls for outcome in outcomes),
-        "cached": sum(1 for outcome in outcomes if outcome.cached),
+        "parse_retries": sum(outcome.parse_retries for outcome in outcomes),
+        "cached":sum(1 for outcome in outcomes if outcome.cached),
         "errors": [
             {"case_id": outcome.case_id, "error": outcome.error}
             for outcome in sorted(outcomes, key=lambda item: item.case_id)
@@ -864,7 +875,11 @@ def _judge_cost_line(judge: Mapping[str, Any] | None) -> str:
     text = f"- Judge: {_usd(judge['cost_usd'])}"
     if judge["cost_usd"] is not None and judge["cost_estimated"]:
         text += " (estimated)"
-    return text + f", {judge['llm_calls']} call(s), {judge['cached']} case(s) from the cache"
+    text += f", {judge['llm_calls']} call(s)"
+    retries = judge["parse_retries"]
+    if retries:
+        text += f" ({retries} parse {'retry' if retries == 1 else 'retries'})"
+    return text + f", {judge['cached']} case(s) from the cache"
 
 
 def _judge_lines(judge: Mapping[str, Any] | None) -> list[str]:
diff --git a/tests/test_eval_end_to_end.py b/tests/test_eval_end_to_end.py
index 64e2186..815c006 100644
--- a/tests/test_eval_end_to_end.py
+++ b/tests/test_eval_end_to_end.py
@@ -321,7 +321,7 @@ def pipeline(rig, tmp_path, capsys, caplog):
             "scoped_rules", "config"]
 SCORE_KEYS = ["version", "label", "run", "judge", "failed", "metrics", "cases"]
 JUDGE_KEYS = ["model", "sampling", "prompt_version", "prompt_sha256", "self_judged", "cost_usd", "cost_estimated",
-              "llm_calls", "cached", "errors"]
+              "llm_calls", "parse_retries", "cached", "errors"]
 METRIC_KEYS = ["case_count", "recall", "recall_by_severity", "recall_by_category", "recall_accepted",
                "unmatched_ai", "severity_agreement", "chunks_failed", "elapsed_ms", "review_cost", "judge_cost"]
 CASE_IDS = ["case-001-mcp-protocol-upgrade", "case-002-session-token-logging", "case-003-config-schema-pin",
diff --git a/tests/test_eval_parse_retries.py b/tests/test_eval_parse_retries.py
new file mode 100644
index 0000000..892c434
--- /dev/null
+++ b/tests/test_eval_parse_retries.py
@@ -0,0 +1,256 @@
+"""``prxref eval`` records the parse retry (#21).
+
+``eval run`` allowlists ``llm_parse_retries`` into ``run.json``'s
+``config``. ``eval score`` passes ``PRXREF_LLM_PARSE_RETRIES`` to
+:func:`prxref.eval_judge.judge_case` as ``parse_retries`` and totals the
+judge's retries into ``score.json``'s ``judge`` block, beside ``llm_calls``.
+``score.md`` names the retries only when there were any, so a scoring run
+without one renders exactly as it did before.
+
+The run directories are laid out by the helpers of ``tests/test_eval_run.py``
+and ``tests/test_eval_score.py``. The judge is a stub whose reply depends on
+how often it has seen the same prompt, so "malformed, then valid" holds per
+case; nothing reaches a network.
+"""
+from __future__ import annotations
+
+import copy
+from collections import Counter
+from collections.abc import Callable
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from prxref import config, eval_judge, evals
+from prxref.eval_judge import JudgeOutcome
+from prxref.judge import JUDGE_PROMPT_VERSION, judge_prompt_sha
+from tests import test_eval_run as run_helpers
+from tests import test_eval_score as score_helpers
+
+ENV = "PRXREF_LLM_PARSE_RETRIES"
+KEY = "llm_parse_retries"
+JUDGE = score_helpers.JUDGE
+MALFORMED = "not json at all"
+DOC = (Path(__file__).resolve().parents[1] / "docs" / "evals.md").read_text(encoding="utf-8")
+FLAT_DOC = " ".join(DOC.split())
+
+CASE_B = score_helpers.CASE_B
+RECORD_B = score_helpers.RECORD_B
+REPLY_B = score_helpers.REPLY_B
+CASE_D = score_helpers._case("d", score_helpers._label("L1", "src/d.py", 7, "error", text="Leaks a handle."))
+RECORD_D = score_helpers._record([score_helpers._row("src/d.py", 7, "Handle leak", severity="error")])
+REPLY_D = score_helpers._reply(("L1", "full", "A1"))
+
+
+def _malformed_first(valid: str, bad: int = 1) -> Callable[[str, int], str]:
+    """Answer the first ``bad`` calls of each prompt with an unparseable reply, then ``valid``."""
+    return lambda user, seen: MALFORMED if seen <= bad else valid
+
+
+@pytest.fixture
+def judge(monkeypatch):
+    """Patch the client factory with a stub judge; set ``state.answer(user, seen)`` before scoring.
+
+    ``seen`` counts the calls made so far with that same prompt, this one
+    included, so a reply can depend on whether the request is a retry.
+    """
+    state = SimpleNamespace(built=[], clients=[], answer=lambda user, seen: REPLY_B, seen=Counter())
+
+    def answer(user: str) -> str:
+        state.seen[user] += 1
+        return state.answer(user, state.seen[user])
+
+    def create(cfg=None, session=None):
+        state.built.append(copy.deepcopy(cfg))
+        client = score_helpers.StubJudge(cfg["llm_models"][0], answer)
+        state.clients.append(client)
+        return client
+
+    monkeypatch.setattr("prxref.llm_backends.create_llm_client", create)
+    state.calls = lambda: [call for client in state.clients for call in client.calls]
+    return state
+
+
+@pytest.fixture
+def forwarded(monkeypatch):
+    """Spy on ``eval_judge.judge_case``: record each call's keyword arguments, then call it."""
+    seen: list[dict] = []
+    real = eval_judge.judge_case
+
+    def spy(*args, **kwargs):
+        seen.append(kwargs)
+        return real(*args, **kwargs)
+
+    monkeypatch.setattr(eval_judge, "judge_case", spy)
+    return seen
+
+
+def _one_case(out: Path, case=CASE_B, record=RECORD_B) -> Path:
+    return score_helpers._write_run(out, [(case, record)])
+
+
+def _cost_line(markdown: str) -> str:
+    return next(line for line in markdown.splitlines() if line.startswith("- Judge: "))
+
+
+class TestTheRunRecordsTheSetting:
+    def test_the_allowlist_holds_the_key_after_the_token_cap(self):
+        keys = list(evals.RUN_CONFIG_KEYS)
+        assert KEY in keys
+        assert keys.index(KEY) == keys.index("llm_max_tokens") + 1
+        assert len(keys) == 17
+        assert KEY in config._DEFAULTS and KEY in config._INT_KEYS
+
+    @pytest.mark.parametrize("value,expected", [(None, 1), ("0", 0), ("3", 3)])
+    def test_run_json_config_records_the_loaded_value(self, tmp_path, monkeypatch, value, expected):
+        if value is not None:
+            monkeypatch.setenv(ENV, value)
+        cases = run_helpers._dataset(tmp_path)
+
+        run_helpers._run(run_helpers._args(cases, tmp_path / "out"), run_helpers.FakeReview())
+
+        run = run_helpers._read(tmp_path / "out" / "L" / "run.json")
+        assert run["config"][KEY] == expected
+        assert list(run["config"]) == list(evals.RUN_CONFIG_KEYS)
+
+    def test_the_documented_allowlist_names_the_key_in_place(self):
+        row = next(line for line in DOC.splitlines() if line.startswith("| `config` |"))
+        assert "`llm_max_tokens`, `llm_parse_retries`, `max_chunks`" in row
+        assert "`config` is an allowlist of the seventeen settings above" in FLAT_DOC
+
+
+class TestTheJudgeGetsTheBudget:
+    @pytest.mark.parametrize("value,expected", [(None, 1), ("0", 0), ("1", 1), ("3", 3)])
+    def test_judge_case_receives_the_config_value(self, tmp_path, judge, forwarded, monkeypatch, value, expected):
+        if value is not None:
+            monkeypatch.setenv(ENV, value)
+        _one_case(tmp_path / "out")
+
+        score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        assert [kwargs["parse_retries"] for kwargs in forwarded] == [expected]
+
+    def test_a_malformed_then_valid_reply_is_retried_and_counted(self, tmp_path, judge, forwarded, monkeypatch):
+        monkeypatch.setenv(ENV, "3")
+        _one_case(tmp_path / "out")
+        judge.answer = _malformed_first(REPLY_B)
+
+        score, markdown = score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        assert forwarded[0]["parse_retries"] == 3
+        assert len(judge.calls()) == 2
+        assert (score["judge"]["parse_retries"], score["judge"]["llm_calls"]) == (1, 2)
+        assert score["judge"]["errors"] == []
+        assert score["judge"]["cost_usd"] == pytest.approx(0.004)
+        assert score_helpers._finding(score, "b", "J1")["grade"] == "partial"
+        assert _cost_line(markdown) == "- Judge: $0.0040, 2 call(s) (1 parse retry), 0 case(s) from the cache"
+
+    def test_the_documented_cost_line_is_the_rendered_one(self, tmp_path, judge, monkeypatch):
+        _one_case(tmp_path / "out")
+        judge.answer = _malformed_first(REPLY_B)
+
+        _, markdown = score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        assert f"as in `{_cost_line(markdown)}`" in FLAT_DOC
+
+    def test_the_block_keeps_parse_retries_beside_llm_calls(self, tmp_path, judge):
+        _one_case(tmp_path / "out")
+        judge.answer = _malformed_first(REPLY_B)
+
+        score, _ = score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        keys = list(score["judge"])
+        assert keys.index("parse_retries") == keys.index("llm_calls") + 1
+
+    def test_the_retries_sum_over_the_cases(self, tmp_path, judge, monkeypatch):
+        monkeypatch.setenv(ENV, "2")
+        score_helpers._write_run(tmp_path / "out", [(CASE_B, RECORD_B), (CASE_D, RECORD_D)])
+        replies = {"b": _malformed_first(REPLY_B, bad=2), "d": _malformed_first(REPLY_D, bad=1)}
+        judge.answer = lambda user, seen: replies["b" if "src/b.py" in user else "d"](user, seen)
+
+        score, markdown = score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        assert (score["judge"]["parse_retries"], score["judge"]["llm_calls"]) == (3, 5)
+        assert score["judge"]["errors"] == []
+        assert "5 call(s) (3 parse retries), 0 case(s)" in _cost_line(markdown)
+
+    def test_a_reply_rejected_past_the_budget_is_a_judge_error_that_still_counts(self, tmp_path, judge):
+        _one_case(tmp_path / "out")
+        judge.answer = lambda user, seen: MALFORMED
+
+        score, markdown = score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        assert (score["judge"]["parse_retries"], score["judge"]["llm_calls"]) == (1, 2)
+        assert [error["case_id"] for error in score["judge"]["errors"]] == ["b"]
+        assert score["judge"]["errors"][0]["error"].startswith("judge response rejected:")
+        assert score_helpers._finding(score, "b", "J1")["grade"] == "judge_error"
+        assert "2 call(s) (1 parse retry)" in _cost_line(markdown)
+
+    def test_a_cached_rescore_counts_no_retry(self, tmp_path, judge):
+        _one_case(tmp_path / "out")
+        judge.answer = _malformed_first(REPLY_B)
+        score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        second, markdown = score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        assert (second["judge"]["parse_retries"], second["judge"]["llm_calls"], second["judge"]["cached"]) == (0, 0, 1)
+        assert _cost_line(markdown) == "- Judge: $0.0000, 0 call(s), 1 case(s) from the cache"
+
+
+class TestAtZeroNothingChanges:
+    def test_a_malformed_reply_is_not_retried_and_the_line_names_no_retry(self, tmp_path, judge, forwarded,
+                                                                         monkeypatch):
+        monkeypatch.setenv(ENV, "0")
+        _one_case(tmp_path / "out")
+        judge.answer = _malformed_first(REPLY_B)
+
+        score, markdown = score_helpers._score(tmp_path / "out", judge_model=JUDGE)
+
+        assert forwarded[0]["parse_retries"] == 0
+        assert len(judge.calls()) == 1
+        assert (score["judge"]["parse_retries"], score["judge"]["llm_calls"]) == (0, 1)
+        assert score_helpers._finding(score, "b", "J1")["grade"] == "judge_error"
+        assert _cost_line(markdown) == "- Judge: $0.0020, 1 call(s), 0 case(s) from the cache"
+        assert "retr" not in markdown
+
+    def test_the_golden_run_renders_the_golden_score_md_byte_for_byte(self, tmp_path, judge, monkeypatch):
+        monkeypatch.setenv(ENV, "0")
+        out = score_helpers._golden_run(tmp_path)
+        judge.answer = lambda user, seen: REPLY_B
+
+        score, markdown = score_helpers._score(out, judge_model=JUDGE)
+
+        assert score["judge"]["parse_retries"] == 0
+        assert markdown == score_helpers.GOLDEN.format(version=JUDGE_PROMPT_VERSION, sha=judge_prompt_sha())
+
+    def test_the_default_budget_with_a_clean_reply_renders_the_golden_too(self, tmp_path, judge):
+        out = score_helpers._golden_run(tmp_path)
+        judge.answer = lambda user, seen: REPLY_B
+
+        score, markdown = score_helpers._score(out, judge_model=JUDGE)
+
+        assert (score["judge"]["parse_retries"], score["judge"]["llm_calls"]) == (0, 1)
+        assert markdown == score_helpers.GOLDEN.format(version=JUDGE_PROMPT_VERSION, sha=judge_prompt_sha())
+
+
+class TestTheBlockTotal:
+    def _outcome(self, case_id: str, *, llm_calls: int, parse_retries: int, cached: bool = False) -> JudgeOutcome:
+        return JudgeOutcome(case_id=case_id, cache_key="k", grades=(), error=None, cached=cached,
+                            llm_calls=llm_calls, ref_index={}, parse_retries=parse_retries)
+
+    def test_it_sums_every_outcome_s_retries(self):
+        client = SimpleNamespace(models=[JUDGE], temperature=0.0, seed=1)
+        outcomes = [
+            self._outcome("a", llm_calls=3, parse_retries=2),
+            self._outcome("b", llm_calls=0, parse_retries=0, cached=True),
+            self._outcome("c", llm_calls=1, parse_retries=0),
+        ]
+
+        block = evals._judge_block(client, JUDGE, False, outcomes, None)
+
+        assert (block["llm_calls"], block["parse_retries"], block["cached"]) == (4, 2, 1)
+
+    def test_no_outcome_gives_zero(self):
+        client = SimpleNamespace(models=[JUDGE], temperature=0.0, seed=1)
+        assert evals._judge_block(client, JUDGE, False, [], None)["parse_retries"] == 0
diff --git a/tests/test_eval_score.py b/tests/test_eval_score.py
index b9dcb70..7bc63d9 100644
--- a/tests/test_eval_score.py
+++ b/tests/test_eval_score.py
@@ -262,7 +262,7 @@ def test_score_json_keeps_its_key_order_and_stamps(self, tmp_path, judge):
                                 "scoped_rules": None, "config": RUN_CONFIG}
         assert list(score["judge"]) == [
             "model", "sampling", "prompt_version", "prompt_sha256", "self_judged",
-            "cost_usd", "cost_estimated", "llm_calls", "cached", "errors",
+            "cost_usd", "cost_estimated", "llm_calls", "parse_retries", "cached", "errors",
         ]
         assert score["judge"]["model"] == JUDGE
         assert score["judge"]["sampling"] == {"temperature": 0.0, "seed": 5, "models": [JUDGE]}

From f51effdcd22172ea8034140a3030283a1f6e8c02 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:53:45 -0700
Subject: [PATCH 14/25] test: make the Kotlin import-alias test able to fail
 (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The alias test used `Queue`, which the JDK name set already drops, so it
stayed green with the alias drop removed. It now aliases to a name no set
covers, checks the name is kept without the import, and checks that an
alias of another organization's import is kept.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 tests/test_repo_context_kotlin.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/tests/test_repo_context_kotlin.py b/tests/test_repo_context_kotlin.py
index 670d156..d728ffd 100644
--- a/tests/test_repo_context_kotlin.py
+++ b/tests/test_repo_context_kotlin.py
@@ -151,8 +151,10 @@ def test_another_organizations_import_is_kept(self):
         assert referenced_names(added, "kotlin") == ["Invoice"]
 
     def test_the_alias_of_a_platform_import_is_dropped(self):
-        added = ["import kotlin.collections.ArrayDeque as Queue", "val q = Queue<Widget>()"]
-        assert referenced_names(added, "kotlin") == ["Widget"]
+        use = "val q = Ring<Widget>()"
+        assert referenced_names([use], "kotlin") == ["Ring", "Widget"]
+        assert referenced_names(["import kotlin.collections.ArrayDeque as Ring", use], "kotlin") == ["Widget"]
+        assert referenced_names(["import com.acme.collections.Deque as Ring", use], "kotlin") == ["Ring", "Widget"]
 
     def test_kotlinx_is_a_library_not_the_platform(self):
         added = ["import kotlinx.coroutines.flow.Flow", "fun stream(): Flow<Widget> = TODO()"]

From 6d9afce7f611ed7a7d60e8a242e22b3e412ae026 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:55:12 -0700
Subject: [PATCH 15/25] feat: wire the pinned-off toggle check into the review
 (#22)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Calls heuristics.toggle_pinned_off_findings(files) at both sites where
release_shape_findings(files) already runs: the main path, where it is
spliced in at the chunk/sweep boundary alongside release_shape (moving
sweep_start with it, so it stays a CHUNK-side finding to
apply_sweep_dedup), and the summary-only (no-chunk) path, for symmetry,
threaded through _summary_only_run's new toggle_findings parameter.

Unlike release_shape, the toggle finding sits on a real line (> 0), so
the long comment above the main-path splice site is updated: the
reworded tier of apply_sweep_dedup (on with dedup_similarity) now can
compare the toggle finding against a chunk worker's own restatement on
the same line, keeping only the higher-ranked one of the two, instead
of never comparing it the way a line-0 finding is exempted. The
orchestrator module docstring and quality.py's module docstring (the
seventeenth-check sentence, now also naming the toggle check as the
eighteenth) are extended to match.

🤖 Authored with Claude Code

— Claude Sonnet 5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/orchestrator.py        | 114 +++++++++++++++++---------
 src/prxref/quality.py             |  12 +--
 tests/test_orchestrator_toggle.py | 132 ++++++++++++++++++++++++++++++
 3 files changed, 213 insertions(+), 45 deletions(-)
 create mode 100644 tests/test_orchestrator_toggle.py

diff --git a/src/prxref/orchestrator.py b/src/prxref/orchestrator.py
index 084e599..37af63b 100644
--- a/src/prxref/orchestrator.py
+++ b/src/prxref/orchestrator.py
@@ -6,9 +6,12 @@
    ``parse_unified_diff`` → files. An empty or unchunkable diff (every file
    binary, or no files at all) short-circuits to a summary-only run with
    verdict ``Approved`` — no chunk worker or sweep ever runs, but
-   ``heuristics.release_shape_findings`` still does, gated the same as on
+   ``heuristics.release_shape_findings`` and
+   ``heuristics.toggle_pinned_off_findings`` still do, gated the same as on
    the normal path, so a release-shaped diff with no reviewable text still
-   gets its deterministic finding instead of a silent approval.
+   gets its deterministic finding instead of a silent approval, and so does
+   a toggle/pin pair on a diff that otherwise chunks to nothing — though a
+   toggle needs an added line to match against, so it rarely fires here.
 2. ``build_chunks`` risk-ranked chunking (≤ ``max_chunks``, each chunk
    sized to ``token_budget`` and capped at ``max_files_per_chunk`` files).
 3. Parallel worker fan-out: one ``reviewer.review_chunk(llm, files, pr)``
@@ -46,14 +49,22 @@
    to ``None`` unless finding grouping or the per-rule cap is on
    (``_enforce_rule``), then gain
    ``heuristics.release_shape_findings(files)`` (a pure, no-LLM finding
-   about a PR that is ≥80% release machinery yet also touches source),
-   folded in BEFORE the passes so it is filtered like any other finding,
-   and spliced in at the chunk/sweep boundary — before the sweep's own
-   findings, never after — so it is always a CHUNK-side finding to
-   ``apply_sweep_dedup``, whose exact tier drops only sweep findings, and
-   being file-level (line 0) it is never compared by that pass's reworded
-   tier either. It can never be dropped as a duplicate of a chunk worker's
-   own restatement:
+   about a PR that is ≥80% release machinery yet also touches source) and
+   ``heuristics.toggle_pinned_off_findings(files)`` (a pure, no-LLM finding
+   about a toggle this PR adds with a default of on that this PR's own
+   test setup pins off), both folded in BEFORE the passes so each is
+   filtered like any other finding, and both spliced in at the chunk/sweep
+   boundary — before the sweep's own findings, never after — so each is
+   always a CHUNK-side finding to ``apply_sweep_dedup``, whose exact tier
+   drops only sweep findings and never one chunk-side finding for another.
+   Being file-level (line 0), a release-shape finding is also never
+   compared by that pass's reworded tier, so it can never be dropped as a
+   duplicate of a chunk worker's own restatement; a toggle finding instead
+   sits on the toggle's own real line, so with ``dedup_similarity`` set it
+   IS compared by that tier against any other chunk-side finding sharing
+   its file and line — a chunk worker's own restatement of the same toggle
+   included — and only the higher-ranked one of the two (severity, then
+   confidence, then content) survives, same as any other same-side pair:
 
    ``apply_severity_map`` (only when the team review rules declare a
    severity map: a team word such as ``blocker`` becomes the prxref tier it
@@ -886,20 +897,26 @@ def orchestrate_review(
 
     if not chunks:
         # No chunk survived build_chunks — an empty diff, or every file
-        # binary — but the release-shape heuristic is pure and needs no
-        # chunk to fire on: computed here so a release PR whose only
-        # non-machinery file is binary still gets the deterministic finding
-        # instead of a silent Approved (issue #29 residual, concern #2).
+        # binary — but the release-shape and pinned-toggle heuristics are
+        # pure and need no chunk to fire on: computed here so a release PR
+        # whose only non-machinery file is binary still gets the
+        # deterministic finding instead of a silent Approved (issue #29
+        # residual, concern #2), and so does a toggle/pin pair on a diff
+        # that otherwise chunks to nothing (issue #22) — though a toggle
+        # needs an added, non-binary line, so it rarely fires on this path.
         release_shape = heuristics.release_shape_findings(files)
+        toggle_findings = heuristics.toggle_pinned_off_findings(files)
+        deterministic_findings = release_shape + toggle_findings
         tracer.event(
-            "run", "ok", chunks_reviewed=0, findings=len(release_shape),
+            "run", "ok", chunks_reviewed=0, findings=len(deterministic_findings),
             **_cost_meta(run_inputs),
-            **(_scope_counts(release_shape) if ticket_active else {}),
+            **(_scope_counts(deterministic_findings) if ticket_active else {}),
         )
         return _run_record(_summary_only_run(
             forge, ref, pr, files, post, t0,
             post_mode=post_mode, post_verdict=post_verdict, tracer=tracer,
             sampling=sampling, release_shape_findings=release_shape,
+            toggle_findings=toggle_findings,
             confidence_floor=confidence_floor, max_errors=max_errors,
             max_warning_findings=max_warning_findings,
             max_outofscope_findings=max_outofscope_findings,
@@ -1166,23 +1183,34 @@ def orchestrate_review(
     if results[-1]["error"]:
         failed_chunks.append((results[-1]["error"], []))
 
-    # A deterministic, non-LLM finding folded in before the quality passes so
-    # it flows through every one of them exactly like a model finding (issue
-    # #10): file-level (line=0) survives apply_line_align untouched, and
-    # warning/1.0 clears apply_quality_gate trivially. Folded in AT the
+    # Two deterministic, non-LLM findings folded in before the quality passes
+    # so each flows through every one of them exactly like a model finding
+    # (issues #10 and #22): warning/1.0 clears apply_quality_gate trivially
+    # for both. release_shape is file-level (line=0), so it survives
+    # apply_line_align untouched; the toggle finding sits on the toggle's
+    # own real line (> 0) instead, so apply_line_align's content pass
+    # re-corroborates it like any model anchor — the body quotes the
+    # toggle call itself, so the anchor holds. Both are folded in AT the
     # chunk/sweep boundary — before the sweep's own findings, not after —
-    # and sweep_start moves with it: apply_sweep_dedup never drops a
+    # and sweep_start moves with them: apply_sweep_dedup never drops a
     # CHUNK-side finding for a sweep-side one (its exact tier drops only
-    # sweep findings; its reworded tier, on with dedup_similarity, can drop
-    # one chunk copy for another on the same line, but never compares line
-    # 0, which this finding always sits on). Appending this after the
+    # sweep findings). Its reworded tier, on with dedup_similarity, never
+    # compares release_shape (line 0 is never compared), but DOES compare
+    # the toggle finding against any other chunk-side finding sharing its
+    # file and line — a chunk worker's own restatement of the same toggle
+    # included — keeping only the higher-ranked one of the two (severity,
+    # then confidence, then content). Appending either finding after the
     # sweep's findings would put it on the sweep side of that boundary,
     # where a chunk worker's own finding sharing its file and normalized
     # title could drop the deterministic finding as "duplicate of chunk
     # finding" and keep the model's restatement instead.
     release_shape = heuristics.release_shape_findings(files)
-    findings = findings[:sweep_start] + release_shape + findings[sweep_start:]
-    sweep_start += len(release_shape)
+    toggle_findings = heuristics.toggle_pinned_off_findings(files)
+    deterministic_findings = release_shape + toggle_findings
+    findings = (
+        findings[:sweep_start] + deterministic_findings + findings[sweep_start:]
+    )
+    sweep_start += len(deterministic_findings)
 
     # FIRST among the passes: a team word the map knows ("blocker") would
     # otherwise die at the gate as an invalid severity, and consistency and
@@ -2933,6 +2961,7 @@ def _summary_only_run(
     *, post_mode: str = "summary+inline", post_verdict: bool = True,
     tracer: Tracer | None = None, sampling: dict | None = None,
     release_shape_findings: list[Finding] | None = None,
+    toggle_findings: list[Finding] | None = None,
     confidence_floor: float | None = None, max_errors: int | None = None,
     max_warning_findings: int | None = None,
     max_outofscope_findings: int | None = None,
@@ -2941,19 +2970,24 @@ def _summary_only_run(
 ) -> dict:
     """The no-chunk exit: an empty diff, or every file binary.
 
-    No worker ever ran, but the release-shape heuristic
-    (:func:`heuristics.release_shape_findings`) is pure and needs no chunk
-    to fire on, so its findings — passed in by the caller, already computed
-    over the full file list — are put through the same location and
-    quality passes a chunk-sourced finding gets (:func:`apply_location_validation`,
-    :func:`apply_quality_gate`) before they reach ``findings_active`` /
-    ``verdict`` / the summary. An empty diff still yields
-    ``release_shape_findings=[]`` (fewer than 2 files can never be
-    release-shaped), so this degrades to exactly the prior empty-diff
-    behaviour: ``Approved``, no findings, no banner. ``confidence_floor``,
-    ``max_errors``, ``max_warning_findings`` and ``max_outofscope_findings``
-    are that gate's knobs, threaded from :func:`orchestrate_review`. No
-    grouping pass runs here: there is no chunk finding to group.
+    No worker ever ran, but the release-shape and pinned-toggle heuristics
+    (:func:`heuristics.release_shape_findings`,
+    :func:`heuristics.toggle_pinned_off_findings`) are pure and need no
+    chunk to fire on, so their findings — passed in by the caller, already
+    computed over the full file list — are put through the same location
+    and quality passes a chunk-sourced finding gets
+    (:func:`apply_location_validation`, :func:`apply_quality_gate`) before
+    they reach ``findings_active`` / ``verdict`` / the summary. No
+    :func:`apply_line_align` call here: both heuristics already anchor on a
+    real diff line and there is no worker-supplied anchor to re-corroborate.
+    An empty diff still yields ``release_shape_findings=[]`` and
+    ``toggle_findings=[]`` (fewer than 2 files can never be release-shaped,
+    and no file has an added line for a toggle or a pin to match), so this
+    degrades to exactly the prior empty-diff behaviour: ``Approved``, no
+    findings, no banner. ``confidence_floor``, ``max_errors``,
+    ``max_warning_findings`` and ``max_outofscope_findings`` are that
+    gate's knobs, threaded from :func:`orchestrate_review`. No grouping
+    pass runs here: there is no chunk finding to group.
 
     ``ticket_note``, ``cost_label``, ``size_advisory_line`` and
     ``summary_template`` are handed to :func:`_render_summary` unchanged; all
@@ -2964,7 +2998,7 @@ def _summary_only_run(
     elapsed_ms = _elapsed_ms(t0)
     posted = False
 
-    findings = list(release_shape_findings or [])
+    findings = list(release_shape_findings or []) + list(toggle_findings or [])
     if findings:
         findings = apply_location_validation(findings, [f.path for f in files])
         findings = apply_quality_gate(
diff --git a/src/prxref/quality.py b/src/prxref/quality.py
index fdc9bb9..e79dda0 100644
--- a/src/prxref/quality.py
+++ b/src/prxref/quality.py
@@ -5,11 +5,13 @@
 severity map, pass 12 only when ``PRXREF_GROUP_FINDINGS`` turns
 finding grouping on, and pass 13 only when a team rules file is loaded
 and ``PRXREF_MAX_FINDINGS_PER_RULE`` is above 0. A seventeenth
-deterministic check, the release-shaped-PR
-heuristic, is not a pass at all: ``heuristics.release_shape_findings``
-ADDS a finding before pass 1 and it then flows through every pass below
-exactly like a model finding. Every ``drop_reason`` prefix these passes
-emit is tabulated for operators in ``docs/quality.md``.
+deterministic check, the release-shaped-PR heuristic, and an eighteenth,
+the pinned-toggle heuristic, are not passes at all:
+``heuristics.release_shape_findings`` and
+``heuristics.toggle_pinned_off_findings`` each ADDS its own finding
+before pass 1, and each then flows through every pass below exactly like
+a model finding. Every ``drop_reason`` prefix these passes emit is
+tabulated for operators in ``docs/quality.md``.
 
 1. ``apply_severity_map``: when the team review rules declare a severity
    map, rewrite a team severity word (``blocker``) to the prxref tier the
diff --git a/tests/test_orchestrator_toggle.py b/tests/test_orchestrator_toggle.py
new file mode 100644
index 0000000..bbe9f7c
--- /dev/null
+++ b/tests/test_orchestrator_toggle.py
@@ -0,0 +1,132 @@
+"""Orchestrator wiring for ``heuristics.toggle_pinned_off_findings`` (issue #22).
+
+The heuristic itself (its supported toggle/pin shapes, its body text, its
+sorting) is covered by ``tests/test_toggle_pinned_off.py``. This file covers
+only the wiring: that ``orchestrate_review`` actually calls it, folds the
+result in at the chunk/sweep boundary next to ``release_shape``, and that the
+finding survives the quality passes exactly once even when a chunk worker
+reports something similar on the same line.
+
+The fixture diff reuses the #22 fixture lines from
+``tests/test_toggle_pinned_off.py`` (``PROGRESS_PY``, ``CONFTEST_PY``):
+``assistant/progress.py`` adds the toggle at line
+:data:`tests.test_toggle_pinned_off.TOGGLE_LINE`, ``tests/conftest.py`` pins
+it off for the whole suite.
+"""
+from __future__ import annotations
+
+import pytest
+
+from prxref import heuristics
+from prxref.orchestrator import orchestrate_review
+from prxref.triage import Finding
+from tests.test_orchestrator import REF, FakeForge, FakeLLM
+from tests.test_toggle_pinned_off import CONFTEST_PY, PROGRESS_PY, TOGGLE_LINE, _added_file
+
+pytestmark = pytest.mark.usefixtures("contract_stubs")
+
+PROGRESS_PATH = "assistant/progress.py"
+CONFTEST_PATH = "tests/conftest.py"
+
+# A reworded restatement of the deterministic finding's own title: it shares
+# five tokens with "Toggle \"progress_notes\" defaults on but the test setup
+# pins it off" (progress, notes, toggle, test, setup) for a Jaccard of 0.45,
+# well past TITLE_MIN_SHARED_TOKENS (3) and the 0.4 threshold the same-line
+# test below turns on.
+MODEL_TITLE = "Progress notes toggle stays on though test setup disables it"
+MODEL_BODY = (
+    'The `enabled("progress_notes", default=True)` call ships the toggle on '
+    "by default; the review flags the same toggle as a duplicate finding."
+)
+
+
+def _diff(*, pin_value: str = "false") -> str:
+    """The #22 fixture diff: adds the toggle, and pins it to ``pin_value``."""
+    conftest = (
+        CONFTEST_PY if pin_value == "false"
+        else [ln.replace('"false"', f'"{pin_value}"') for ln in CONFTEST_PY]
+    )
+    return _added_file(PROGRESS_PATH, PROGRESS_PY) + _added_file(CONFTEST_PATH, conftest)
+
+
+def _all_findings(res: dict) -> list[Finding]:
+    """Every finding the run recorded, active or dropped, quality-gate order."""
+    return list(res["findings_active"]) + list(res["findings_dropped"])
+
+
+def _toggle_findings(res: dict) -> list[Finding]:
+    """The subset of recorded findings the deterministic toggle check made."""
+    return [f for f in _all_findings(res) if f.body.endswith(heuristics._BODY_SUFFIX)]
+
+
+class TestSurvivesOnce:
+    """The toggle finding reaches the review exactly once, undropped."""
+
+    def test_the_toggle_finding_reaches_the_review_exactly_once(self):
+        forge = FakeForge(diff=_diff())
+        res = orchestrate_review(forge, REF, FakeLLM(), post=False)
+
+        found = _toggle_findings(res)
+        assert len(found) == 1
+        f = found[0]
+        assert f.file == PROGRESS_PATH
+        assert f.line == TOGGLE_LINE
+        assert f.drop_reason is None
+        assert f.body.endswith(heuristics._BODY_SUFFIX)
+
+
+class TestModelFindingOnTheSameLine:
+    """A chunk worker also reports on the toggle line, with a similar title.
+
+    ``dedup_similarity`` turns on ``apply_sweep_dedup``'s reworded tier, the
+    only pass that compares two CHUNK-side findings against each other on the
+    same line (the exact tier drops only sweep-side duplicates). Both the
+    deterministic finding and the chunk worker's finding are chunk-side here
+    (the deterministic one is spliced in at the chunk/sweep boundary), so the
+    reworded tier keeps only the higher-ranked one of the two: severity ties
+    (both ``warning``), so confidence decides, and the deterministic finding's
+    confidence is 1.0 against the model's 0.9. The model's copy is dropped as
+    ``duplicate of chunk finding (reworded, similarity 0.45)``.
+    """
+
+    def test_exactly_one_finding_survives_the_toggle_line(self):
+        forge = FakeForge(diff=_diff())
+        llm = FakeLLM(findings_by_path={
+            PROGRESS_PATH: [{
+                "file": PROGRESS_PATH,
+                "line": TOGGLE_LINE,
+                "severity": "warning",
+                "confidence": 0.9,
+                "title": MODEL_TITLE,
+                "body": MODEL_BODY,
+            }],
+        })
+        res = orchestrate_review(forge, REF, llm, post=False, dedup_similarity=0.4)
+
+        same_line = [
+            f for f in _all_findings(res)
+            if f.file == PROGRESS_PATH and f.line == TOGGLE_LINE
+        ]
+        assert len(same_line) == 2, "both the deterministic and the model copy were recorded"
+
+        survivors = [f for f in same_line if f.drop_reason is None]
+        assert len(survivors) == 1
+        assert survivors[0].body.endswith(heuristics._BODY_SUFFIX), (
+            "the deterministic finding (confidence 1.0) outranks the model's "
+            "restatement (confidence 0.9) in the reworded tier's keep order"
+        )
+
+        dropped = [f for f in same_line if f.drop_reason is not None]
+        assert len(dropped) == 1
+        assert not dropped[0].body.endswith(heuristics._BODY_SUFFIX)
+        assert dropped[0].drop_reason.startswith("duplicate of chunk finding (reworded")
+
+
+class TestNegativeControl:
+    """The same diff, pin value flipped to ``\"true\"``: no toggle finding."""
+
+    def test_a_pin_set_to_true_yields_no_toggle_finding(self):
+        forge = FakeForge(diff=_diff(pin_value="true"))
+        res = orchestrate_review(forge, REF, FakeLLM(), post=False)
+
+        assert _toggle_findings(res) == []

From 70512fe2e8d7c984ef5684d70d8cf86cc6918b64 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:55:34 -0700
Subject: [PATCH 16/25] test: accept the parse retry end to end through the CLI
 path (#21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drives every #21 acceptance bullet through cli._run_review (and cli.main
for the exit code) on a two-chunk fixture patch read by the local-diff
forge, with the real openai-compat client, reviewer and orchestrator
against a local MockOpenAIServer. The server answers each review unit
(two chunks and the sweep) from its own script of canned replies and
counts that unit's calls, so counts do not depend on worker order, and
an unscripted extra call is an HTTP 500 that shows up as a wrong count.

Covered with PRXREF_LLM_PARSE_RETRIES unset (default 1), 0 and 2:
malformed then valid (2 calls, findings kept, run record and JSON 1,
meta parse_retries and first_error, the discarded reply in
chunk0.attempt1.response.json, the same request resent); malformed
twice (2 calls, the last of two different errors wins, exit 0 on a
partial and a total failure, exit 1 only with PRXREF_FAIL_ON=error);
{} twice (the no-findings error); a list, {} and an object without
findings retried; the issue's own stray-quote reply; a length stop
(1 call, the budget message, 8 meta keys) against the same bytes with
an honest stop (retried); 0 (a {} reply is clean, garbage costs 1 call,
record null, no attempt file, 8 meta keys, the empty-reply retry kept);
2 (3 calls); the sweep; and tokens and reported cost summed over every
attempt.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 tests/fixtures/issue21/pr.diff      |  32 ++
 tests/fixtures/issue21/replies.json |  47 +++
 tests/test_issue_21_acceptance.py   | 486 ++++++++++++++++++++++++++++
 3 files changed, 565 insertions(+)
 create mode 100644 tests/fixtures/issue21/pr.diff
 create mode 100644 tests/fixtures/issue21/replies.json
 create mode 100644 tests/test_issue_21_acceptance.py

diff --git a/tests/fixtures/issue21/pr.diff b/tests/fixtures/issue21/pr.diff
new file mode 100644
index 0000000..607a354
--- /dev/null
+++ b/tests/fixtures/issue21/pr.diff
@@ -0,0 +1,32 @@
+diff --git a/billing/ledger.py b/billing/ledger.py
+new file mode 100644
+--- /dev/null
++++ b/billing/ledger.py
+@@ -0,0 +1,12 @@
++"""Ledger entries for the acme billing service."""
++
++
++def post_entry(ledger, account, amount):
++    """Append one entry and return the new balance."""
++    balance = ledger.get(account, 0)
++    balance = balance + amount
++    ledger[account] = balance
++    return balance
++
++
++LEDGER_VERSION = 2
+diff --git a/billing/export.py b/billing/export.py
+new file mode 100644
+--- /dev/null
++++ b/billing/export.py
+@@ -0,0 +1,10 @@
++"""CSV export of ledger balances for the example.com reports."""
++import csv
++
++
++def export_balances(ledger, path):
++    """Write one row per account."""
++    with open(path, "w", newline="") as handle:
++        writer = csv.writer(handle)
++        for account, balance in ledger.items():
++            writer.writerow([account, balance])
diff --git a/tests/fixtures/issue21/replies.json b/tests/fixtures/issue21/replies.json
new file mode 100644
index 0000000..5baf56c
--- /dev/null
+++ b/tests/fixtures/issue21/replies.json
@@ -0,0 +1,47 @@
+{
+ "_about": "Canned worker and sweep replies for tests/test_issue_21_acceptance.py. A string is the reply text verbatim; any other value is sent as its JSON encoding. The findings cite added lines of pr.diff, so location validation keeps them.",
+ "ledger_finding": {
+  "findings": [
+   {
+    "file": "billing/ledger.py",
+    "line": 7,
+    "severity": "error",
+    "confidence": 0.95,
+    "title": "Amount is added without validation",
+    "body": "post_entry adds amount to the balance without checking its type or sign, so a negative or string amount corrupts the ledger."
+   }
+  ],
+  "escalations": []
+ },
+ "export_finding": {
+  "findings": [
+   {
+    "file": "billing/export.py",
+    "line": 7,
+    "severity": "error",
+    "confidence": 0.95,
+    "title": "Export file is written without an encoding",
+    "body": "open(path, \"w\") uses the platform default encoding, so the same ledger exports different bytes on different hosts."
+   }
+  ],
+  "escalations": []
+ },
+ "clean": {
+  "findings": [],
+  "escalations": []
+ },
+ "stray_quote": "{\"findings\":[{\"file\":\"billing/ledger.py\",\"line\":7\",\"severity\":\"error\",\"confidence\":0.95,\"title\":\"Amount is added without validation\",\"body\":\"post_entry adds amount without a check.\"}],\"escalations\":[]}",
+ "prose": "I reviewed the chunk and found nothing worth reporting.",
+ "list": [
+  {
+   "file": "billing/ledger.py",
+   "line": 7
+  }
+ ],
+ "no_findings": {},
+ "escalations_only": {
+  "escalations": []
+ },
+ "empty": "",
+ "truncated": "{\"findings\": [{\"file\": \"billing/ledger.py\", \"line\": 7, \"sev"
+}
diff --git a/tests/test_issue_21_acceptance.py b/tests/test_issue_21_acceptance.py
new file mode 100644
index 0000000..0043daa
--- /dev/null
+++ b/tests/test_issue_21_acceptance.py
@@ -0,0 +1,486 @@
+"""Issue #21 acceptance: a worker reply that cannot be used is asked for again.
+
+Every run here takes the production path. ``cli._run_review`` reviews
+``tests/fixtures/issue21/pr.diff`` through the local-diff forge (the
+``--diff-file`` path), the real openai-compat client, reviewer and
+orchestrator, against a local ``MockOpenAIServer``; ``cli.main`` stands in
+where the exit code is the point. With ``PRXREF_CHUNK_MAX_FILES=1`` the
+patch is two chunks, ``chunk0`` for ``billing/ledger.py`` and ``chunk1`` for
+``billing/export.py``, plus the systemic sweep.
+
+The server answers each of those three review units from its own script of
+canned replies (``replies.json``) and counts that unit's requests, so every
+call count below is per unit and does not depend on worker order. A request
+past the end of a unit's script gets an HTTP 500 and still counts, so an
+extra retry shows up as a wrong count, never as a silently accepted reply.
+Every reply reports 200 prompt tokens, 80 completion tokens and a cost of
+$0.001.
+
+Configuration arrives through the environment, the way a user sets it:
+``PRXREF_LLM_PARSE_RETRIES`` unset (the default, 1), ``0`` or ``2``. The
+judge's retry is tested in tests/test_judge_parse_retry.py.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+from prxref import cli
+from tests.test_integration import MockOpenAIServer, _completion
+
+FIXTURE = Path(__file__).resolve().parent / "fixtures" / "issue21"
+DIFF = FIXTURE / "pr.diff"
+REPLIES = {
+    name: value if isinstance(value, str) else json.dumps(value)
+    for name, value in json.loads((FIXTURE / "replies.json").read_text(encoding="utf-8")).items()
+    if not name.startswith("_")
+}
+
+LEDGER = "billing/ledger.py"
+EXPORT = "billing/export.py"
+LABELS = {"ledger": "chunk0", "export": "chunk1", "sweep": "sweep"}
+UNSET = None
+
+IN_TOKENS = 200
+OUT_TOKENS = 80
+COST = 0.001
+
+BASE_META_KEYS = [
+    "unit", "model", "input_tokens", "output_tokens",
+    "elapsed_ms", "error", "cost_usd", "cost_source",
+]
+RETRY_META_KEYS = [*BASE_META_KEYS, "parse_retries", "first_error"]
+BASE_UNIT_FILES = {".system.md", ".user.md", ".response.json", ".meta.json"}
+
+PROSE_ERROR = "JSONDecodeError: Expecting value: line 1 column 1 (char 0)"
+LIST_ERROR = "worker review JSON is not an object: list"
+NO_FINDINGS_ERROR = "worker review JSON has no findings list"
+BUDGET_ERROR = (
+    "response truncated at max_tokens=4096 (finish_reason=length); "
+    "raise PRXREF_LLM_MAX_TOKENS"
+)
+LEDGER_FINDING = (LEDGER, "Amount is added without validation")
+EXPORT_FINDING = (EXPORT, "Export file is written without an encoding")
+
+
+def _unit_of(payload: dict) -> str:
+    """Which review unit a chat request is for: ``ledger``, ``export``, ``sweep`` or ``unknown``."""
+    system = payload["messages"][0]["content"]
+    user = payload["messages"][-1]["content"]
+    if "systemic sweep" in system:
+        return "sweep"
+    if f"+++ b/{LEDGER}" in user:
+        return "ledger"
+    if f"+++ b/{EXPORT}" in user:
+        return "export"
+    return "unknown"
+
+
+class UnitScript:
+    """An OpenAI route that answers each review unit from its own reply queue.
+
+    ``ledger``, ``export`` and ``sweep`` list reply names from replies.json,
+    each optionally paired with a finish reason (``stop`` when bare).
+    ``calls`` counts every unit's requests and ``payloads`` keeps them in
+    order. A request past the end of its unit's queue gets an HTTP 500.
+    """
+
+    def __init__(self, *, ledger=("clean",), export=("clean",), sweep=("clean",)):
+        self.queues = {"ledger": list(ledger), "export": list(export), "sweep": list(sweep)}
+        self.calls = dict.fromkeys(self.queues, 0)
+        self.payloads: dict[str, list[dict]] = {unit: [] for unit in self.queues}
+
+    def __call__(self, payload: dict) -> tuple[int, dict]:
+        unit = _unit_of(payload)
+        self.calls[unit] = self.calls.get(unit, 0) + 1
+        self.payloads.setdefault(unit, []).append(payload)
+        queue = self.queues.get(unit, [])
+        if not queue:
+            return 500, {"error": f"no reply scripted for {unit} call {self.calls[unit]}"}
+        reply = queue.pop(0)
+        name, reason = reply if isinstance(reply, tuple) else (reply, "stop")
+        body = _completion(REPLIES[name], reason)
+        body["usage"]["cost"] = COST
+        return 200, body
+
+
+@dataclass
+class Run:
+    """One review's result dict, its script and its trace directory."""
+
+    result: dict
+    script: UnitScript
+    trace: Path
+
+    @property
+    def calls(self) -> dict[str, int]:
+        return self.script.calls
+
+    @property
+    def payload(self) -> dict:
+        """The ``--format json`` payload the CLI prints for this result."""
+        return cli._build_json_result(self.result)
+
+    def meta(self, unit: str) -> dict:
+        return json.loads((self.trace / f"{LABELS[unit]}.meta.json").read_text(encoding="utf-8"))
+
+    def response(self, unit: str, attempt: int | None = None) -> str | None:
+        suffix = ".response.json" if attempt is None else f".attempt{attempt}.response.json"
+        return json.loads((self.trace / f"{LABELS[unit]}{suffix}").read_text(encoding="utf-8"))
+
+    def attempt_files(self) -> list[str]:
+        return sorted(p.name for p in self.trace.iterdir() if ".attempt" in p.name)
+
+    def findings(self) -> list[tuple[str, str]]:
+        return sorted((f.file, f.title) for f in self.result["findings_active"])
+
+
+@pytest.fixture(scope="module")
+def llm_server():
+    """One local OpenAI server for the module; each run installs its script as the route.
+
+    Shared because stopping a server waits out its poll interval, about half
+    a second per test.
+    """
+    route: dict[str, UnitScript] = {}
+    server = MockOpenAIServer(routes={"fast": lambda payload: route["script"](payload)})
+    base_url = server.start()
+    yield base_url, route
+    server.stop()
+
+
+@pytest.fixture
+def configure(monkeypatch, llm_server):
+    """Point the environment at the shared server and install ``script``; returns nothing."""
+    base_url, route = llm_server
+
+    def apply(script: UnitScript, retries: str | None, env: dict[str, str] | None) -> None:
+        route["script"] = script
+        monkeypatch.setenv("PRXREF_LLM_BACKEND", "openai-compat")
+        monkeypatch.setenv("PRXREF_LLM_BASE_URL", base_url)
+        monkeypatch.setenv("PRXREF_LLM_MODELS", "fast")
+        monkeypatch.setenv("PRXREF_CHUNK_MAX_FILES", "1")
+        monkeypatch.setenv("PRXREF_MAX_WORKERS", "1")
+        if retries is not None:
+            monkeypatch.setenv("PRXREF_LLM_PARSE_RETRIES", retries)
+        for name, value in (env or {}).items():
+            monkeypatch.setenv(name, value)
+
+    return apply
+
+
+@pytest.fixture
+def review(configure, tmp_path):
+    """``review(script, retries=...)``: ``cli._run_review`` on the fixture patch, traced.
+
+    ``retries=UNSET`` leaves ``PRXREF_LLM_PARSE_RETRIES`` out of the
+    environment; a string sets it.
+    """
+    def run(script: UnitScript, *, retries: str | None, env=None) -> Run:
+        configure(script, retries, env)
+        trace = tmp_path / "trace"
+        result = cli._run_review(None, post=False, diff_file=str(DIFF), trace_dir=str(trace))
+        return Run(result, script, trace)
+
+    return run
+
+
+@pytest.fixture
+def review_cli(configure, tmp_path, capsys):
+    """``review_cli(script, retries=...)``: ``prxref review --diff-file ... --format json``; ``(rc, payload)``."""
+    def run(script: UnitScript, *, retries: str | None, env=None) -> tuple[int, dict]:
+        configure(script, retries, env)
+        rc = cli.main([
+            "review", "--diff-file", str(DIFF), "--format", "json",
+            "--trace-dir", str(tmp_path / "trace"),
+        ])
+        return rc, json.loads(capsys.readouterr().out)
+
+    return run
+
+
+class TestTheFixture:
+    def test_the_patch_is_two_chunks_and_a_sweep_with_stable_labels(self, review):
+        run = review(UnitScript(), retries=UNSET)
+        assert run.calls == {"ledger": 1, "export": 1, "sweep": 1}
+        assert run.result["chunk_count"] == 3
+        assert run.result["chunks_failed"] == 0
+        assert f"+++ b/{LEDGER}" in (run.trace / "chunk0.user.md").read_text(encoding="utf-8")
+        assert f"+++ b/{EXPORT}" in (run.trace / "chunk1.user.md").read_text(encoding="utf-8")
+
+    def test_a_clean_run_at_the_default_records_zero_and_writes_no_attempt_file(self, review):
+        run = review(UnitScript(), retries=UNSET)
+        assert run.result["parse_retries"] == 0
+        assert run.payload["parse_retries"] == 0
+        assert run.attempt_files() == []
+        for unit in LABELS:
+            assert list(run.meta(unit)) == BASE_META_KEYS
+
+    @pytest.mark.parametrize(("name", "error"), [
+        ("stray_quote", LIST_ERROR),
+        ("prose", PROSE_ERROR),
+        ("list", LIST_ERROR),
+        ("no_findings", NO_FINDINGS_ERROR),
+        ("escalations_only", NO_FINDINGS_ERROR),
+        ("truncated", BUDGET_ERROR),
+    ])
+    def test_each_bad_reply_fails_the_chunk_with_its_own_error(self, review, name, error):
+        """Pins what each canned reply means, so the retry tests below are about the retry.
+
+        ``stray_quote`` is the issue's own example: one stray quote inside
+        the object, which the lenient parser turns into its inner list.
+        """
+        reason = "length" if name == "truncated" else "stop"
+        run = review(UnitScript(ledger=[(name, reason), (name, reason)]), retries="1")
+        assert run.meta("ledger")["error"] == error
+        assert run.result["chunks_failed"] == 1
+
+
+class TestMalformedThenValid:
+    def test_two_calls_keep_the_findings_and_the_record_counts_one(self, review):
+        run = review(UnitScript(ledger=["stray_quote", "ledger_finding"]), retries=UNSET)
+        assert run.calls == {"ledger": 2, "export": 1, "sweep": 1}
+        assert run.result["chunks_failed"] == 0
+        assert run.findings() == [LEDGER_FINDING]
+        assert run.result["verdict"] == "Request-Changes"
+        assert run.result["parse_retries"] == 1
+        assert run.payload["parse_retries"] == 1
+
+    def test_the_retry_resends_the_same_request(self, review):
+        script = UnitScript(ledger=["prose", "ledger_finding"])
+        review(script, retries=UNSET)
+        first, second = script.payloads["ledger"]
+        assert second == first
+
+    def test_the_trace_keeps_both_replies_and_meta_names_the_first_error(self, review):
+        run = review(UnitScript(ledger=["stray_quote", "ledger_finding"]), retries=UNSET)
+        meta = run.meta("ledger")
+        assert list(meta) == RETRY_META_KEYS
+        assert meta["parse_retries"] == 1
+        assert meta["first_error"] == LIST_ERROR
+        assert meta["error"] == ""
+        assert run.response("ledger", attempt=1) == REPLIES["stray_quote"]
+        assert run.response("ledger") == REPLIES["ledger_finding"]
+        assert run.attempt_files() == ["chunk0.attempt1.response.json"]
+
+    def test_control_a_unit_that_parsed_first_time_keeps_the_old_meta(self, review):
+        """Inside the same run, the export chunk and the sweep never retried."""
+        run = review(UnitScript(ledger=["prose", "ledger_finding"]), retries=UNSET)
+        assert list(run.meta("export")) == BASE_META_KEYS
+        assert list(run.meta("sweep")) == BASE_META_KEYS
+        assert run.meta("ledger")["first_error"] == PROSE_ERROR
+
+    def test_the_retry_is_logged_once_and_nothing_is_reported_failed(self, review, caplog):
+        with caplog.at_level(logging.WARNING, logger="prxref"):
+            review(UnitScript(ledger=["prose", "ledger_finding"]), retries=UNSET)
+        messages = [r.getMessage() for r in caplog.records]
+        assert messages.count(
+            f"chunk of 1 files: unusable model reply ({PROSE_ERROR}); parse retry 1 of 1"
+        ) == 1
+        assert not [m for m in messages if m.startswith("worker review failed")]
+
+
+class TestWhenTheRetryAlsoFails:
+    @pytest.mark.parametrize(("replies", "first_error", "last_error"), [
+        (["prose", "list"], PROSE_ERROR, LIST_ERROR),
+        (["list", "prose"], LIST_ERROR, PROSE_ERROR),
+    ], ids=["then-a-list", "then-prose"])
+    def test_malformed_twice_makes_two_calls_and_fails_with_the_last_error(
+        self, review, replies, first_error, last_error,
+    ):
+        run = review(UnitScript(ledger=replies, export=["export_finding"]), retries=UNSET)
+        assert run.calls == {"ledger": 2, "export": 1, "sweep": 1}
+        assert run.result["chunks_failed"] == 1
+        meta = run.meta("ledger")
+        assert meta["error"] == last_error
+        assert meta["first_error"] == first_error
+        assert meta["parse_retries"] == 1
+        assert run.result["parse_retries"] == 1
+        assert run.response("ledger", attempt=1) == REPLIES[replies[0]]
+        assert run.response("ledger") == REPLIES[replies[1]]
+
+    def test_the_other_chunk_still_reports_its_findings(self, review):
+        run = review(UnitScript(ledger=["prose", "prose"], export=["export_finding"]), retries=UNSET)
+        assert run.findings() == [EXPORT_FINDING]
+        assert run.result["verdict"] == "Request-Changes"
+
+    def test_an_empty_object_twice_fails_with_no_findings_list(self, review):
+        run = review(UnitScript(ledger=["no_findings", "no_findings"]), retries=UNSET)
+        assert run.calls == {"ledger": 2, "export": 1, "sweep": 1}
+        assert run.result["chunks_failed"] == 1
+        assert run.meta("ledger")["error"] == NO_FINDINGS_ERROR
+        assert run.meta("ledger")["first_error"] == NO_FINDINGS_ERROR
+        assert run.result["parse_retries"] == 1
+
+    def test_review_still_exits_zero_when_one_chunk_fails(self, review_cli, tmp_path):
+        script = UnitScript(ledger=["prose", "prose"])
+        rc, payload = review_cli(script, retries=UNSET)
+        assert rc == 0
+        assert script.calls == {"ledger": 2, "export": 1, "sweep": 1}
+        assert payload["chunks_failed"] == 1
+        assert payload["parse_retries"] == 1
+        attempt = tmp_path / "trace" / "chunk0.attempt1.response.json"
+        assert json.loads(attempt.read_text(encoding="utf-8")) == REPLIES["prose"]
+
+    def test_review_still_exits_zero_when_every_unit_fails(self, review_cli):
+        bad = ["prose", "prose"]
+        script = UnitScript(ledger=bad, export=bad, sweep=bad)
+        rc, payload = review_cli(script, retries=UNSET)
+        assert rc == 0
+        assert script.calls == {"ledger": 2, "export": 2, "sweep": 2}
+        assert payload["verdict"] == "Error"
+        assert payload["parse_retries"] == 3
+
+    def test_control_the_same_failure_exits_one_when_the_gate_is_opted_into(self, review_cli):
+        """PRXREF_FAIL_ON=error is the one opt-in gate; it proves the zero above is the doctrine."""
+        bad = ["prose", "prose"]
+        rc, payload = review_cli(
+            UnitScript(ledger=bad, export=bad, sweep=bad),
+            retries=UNSET, env={"PRXREF_FAIL_ON": "error"},
+        )
+        assert rc == 1
+        assert payload["verdict"] == "Error"
+
+
+class TestTheWrongShapeRetriesTheSameWay:
+    @pytest.mark.parametrize(("name", "error"), [
+        ("list", LIST_ERROR),
+        ("no_findings", NO_FINDINGS_ERROR),
+        ("escalations_only", NO_FINDINGS_ERROR),
+    ])
+    def test_valid_json_of_the_wrong_shape_is_asked_for_again(self, review, name, error):
+        run = review(UnitScript(ledger=[name, "ledger_finding"]), retries=UNSET)
+        assert run.calls == {"ledger": 2, "export": 1, "sweep": 1}
+        assert run.findings() == [LEDGER_FINDING]
+        assert run.meta("ledger")["first_error"] == error
+        assert run.response("ledger", attempt=1) == REPLIES[name]
+
+
+class TestTruncationIsNotRetried:
+    def test_a_length_stop_makes_one_call_and_names_the_budget(self, review):
+        run = review(UnitScript(ledger=[("truncated", "length")]), retries=UNSET)
+        assert run.calls == {"ledger": 1, "export": 1, "sweep": 1}
+        assert run.result["chunks_failed"] == 1
+        meta = run.meta("ledger")
+        assert meta["error"] == BUDGET_ERROR
+        assert list(meta) == BASE_META_KEYS
+        assert run.attempt_files() == []
+        assert run.result["parse_retries"] == 0
+
+    def test_control_the_same_bytes_with_an_honest_stop_are_retried(self, review):
+        run = review(UnitScript(ledger=[("truncated", "stop"), "ledger_finding"]), retries=UNSET)
+        assert run.calls == {"ledger": 2, "export": 1, "sweep": 1}
+        assert run.meta("ledger")["first_error"].startswith("JSONDecodeError: Unterminated string")
+        assert run.findings() == [LEDGER_FINDING]
+
+
+class TestZeroIsTheOldBehaviour:
+    """``PRXREF_LLM_PARSE_RETRIES=0``: 0.16.0's behaviour, with the record key null."""
+
+    def test_an_empty_object_is_a_clean_review(self, review):
+        script = UnitScript(ledger=["no_findings"], export=["no_findings"], sweep=["no_findings"])
+        run = review(script, retries="0")
+        assert run.calls == {"ledger": 1, "export": 1, "sweep": 1}
+        assert run.result["chunks_failed"] == 0
+        assert run.result["verdict"] == "Approved"
+        assert run.meta("ledger")["error"] == ""
+
+    def test_garbage_costs_one_call_and_fails_the_chunk(self, review):
+        run = review(UnitScript(ledger=["prose"]), retries="0")
+        assert run.calls == {"ledger": 1, "export": 1, "sweep": 1}
+        assert run.result["chunks_failed"] == 1
+        assert run.meta("ledger")["error"] == PROSE_ERROR
+        assert run.result["input_tokens"] == 3 * IN_TOKENS
+
+    def test_the_record_is_null_and_no_attempt_file_or_retry_key_is_written(self, review):
+        run = review(
+            UnitScript(ledger=["prose"], export=["list"], sweep=["no_findings"]), retries="0",
+        )
+        assert run.result["parse_retries"] is None
+        assert run.payload["parse_retries"] is None
+        assert run.attempt_files() == []
+        names = {p.name for p in run.trace.iterdir()}
+        assert names == {label + suffix for label in LABELS.values() for suffix in BASE_UNIT_FILES}
+        for unit in LABELS:
+            assert list(run.meta(unit)) == BASE_META_KEYS
+
+    def test_an_empty_reply_still_gets_its_one_retry(self, review):
+        """The empty-reply retry predates the parse retry and stays at 0, with no new trace."""
+        run = review(UnitScript(ledger=["empty", "ledger_finding"]), retries="0")
+        assert run.calls == {"ledger": 2, "export": 1, "sweep": 1}
+        assert run.findings() == [LEDGER_FINDING]
+        assert run.result["parse_retries"] is None
+        assert run.attempt_files() == []
+        assert list(run.meta("ledger")) == BASE_META_KEYS
+
+    def test_control_the_default_asks_again_for_the_same_replies(self, review):
+        """The same first replies with the variable unset: the retry is what zero turned off."""
+        script = UnitScript(ledger=["prose", "ledger_finding"], export=["no_findings", "clean"])
+        run = review(script, retries=UNSET)
+        assert run.calls == {"ledger": 2, "export": 2, "sweep": 1}
+        assert run.result["parse_retries"] == 2
+
+
+class TestTwoRetries:
+    def test_repeated_garbage_makes_three_calls(self, review):
+        run = review(UnitScript(ledger=["prose", "list", "prose"]), retries="2")
+        assert run.calls == {"ledger": 3, "export": 1, "sweep": 1}
+        assert run.result["chunks_failed"] == 1
+        meta = run.meta("ledger")
+        assert meta["error"] == PROSE_ERROR
+        assert meta["first_error"] == PROSE_ERROR
+        assert meta["parse_retries"] == 2
+        assert run.result["parse_retries"] == 2
+        assert run.attempt_files() == [
+            "chunk0.attempt1.response.json", "chunk0.attempt2.response.json",
+        ]
+        assert run.response("ledger", attempt=2) == REPLIES["list"]
+
+    def test_the_third_call_can_still_succeed(self, review):
+        run = review(UnitScript(ledger=["prose", "no_findings", "ledger_finding"]), retries="2")
+        assert run.calls == {"ledger": 3, "export": 1, "sweep": 1}
+        assert run.findings() == [LEDGER_FINDING]
+        assert run.result["parse_retries"] == 2
+
+
+class TestTheSweep:
+    def test_the_sweep_retries_the_same_way(self, review):
+        run = review(UnitScript(sweep=["stray_quote", "clean"]), retries=UNSET)
+        assert run.calls == {"ledger": 1, "export": 1, "sweep": 2}
+        assert run.result["chunks_failed"] == 0
+        meta = run.meta("sweep")
+        assert list(meta) == RETRY_META_KEYS
+        assert meta["first_error"] == LIST_ERROR
+        assert run.response("sweep", attempt=1) == REPLIES["stray_quote"]
+        assert run.attempt_files() == ["sweep.attempt1.response.json"]
+        assert run.result["parse_retries"] == 1
+
+
+class TestEveryCallIsCounted:
+    def test_tokens_and_cost_cover_every_attempt(self, review):
+        script = UnitScript(
+            ledger=["prose", "ledger_finding"],
+            export=["list", "export_finding"],
+            sweep=["no_findings", "clean"],
+        )
+        run = review(script, retries=UNSET)
+        calls = sum(run.calls.values())
+        assert calls == 6
+        assert run.result["input_tokens"] == calls * IN_TOKENS
+        assert run.result["output_tokens"] == calls * OUT_TOKENS
+        assert run.result["cost_usd"] == pytest.approx(calls * COST)
+        assert run.result["cost_estimated"] is False
+        assert run.result["parse_retries"] == 3
+        for unit in LABELS:
+            assert run.meta(unit)["input_tokens"] == 2 * IN_TOKENS
+            assert run.meta(unit)["cost_usd"] == pytest.approx(2 * COST)
+
+    def test_control_a_clean_run_bills_one_call_per_unit(self, review):
+        run = review(UnitScript(), retries=UNSET)
+        assert run.result["input_tokens"] == 3 * IN_TOKENS
+        assert run.result["output_tokens"] == 3 * OUT_TOKENS
+        assert run.result["cost_usd"] == pytest.approx(3 * COST)

From a7d79e1c460aeb5e3a9236ca692563b648dcb6e3 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 21:01:19 -0700
Subject: [PATCH 17/25] feat: Java and Kotlin in chunk context: definitions,
 annotations, dependencies (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire the jvm_lang and jvm_deps leaf modules into chunk_context, so a chunk
that touches .java, .kt or .kts files gets the same definitions and
dependencies blocks the js and python chunks already get.

- _language maps .java to "java" and .kt/.kts to "kotlin" through
  jvm_lang.jvm_language; _definition_regexes and _keywords return the
  jvm_lang tables for those two languages. Every other language is
  unchanged.
- referenced_definitions starts a Java or Kotlin entry at the annotation
  lines directly above the definition (at most MAX_ANNOTATION_LINES, clamped
  so the definition line always fits in max_lines_per_entry), reports the
  first annotation's line number, and counts the annotation lines toward the
  line cap. js and python decorators are not included, and non-JVM output is
  byte-identical.
- dependency_versions hands a JVM file to jvm_deps.dependency_lines before
  the manifest lookup and merges its g:a@v lines into the same sorted,
  deduplicated result. build.gradle.kts and settings.gradle.kts are skipped
  with no read.
- repo_crosschunk._SAME_FILE_LANGUAGES gains java and kotlin, so with a
  reader diff_definitions leaves a chunk's own JVM files to chunk context
  instead of repeating their definitions as diff-file entries.

Tests: a new tests/test_chunk_context_jvm.py, the Java/Kotlin rows of
test_repo_context_crosschunk.py re-pinned, and the chunk-context Java pin in
test_repo_context_defs.py flipped.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/chunk_context.py           |  51 ++-
 src/prxref/repo_crosschunk.py         |   2 +-
 tests/test_chunk_context_jvm.py       | 478 ++++++++++++++++++++++++++
 tests/test_repo_context_crosschunk.py |  47 ++-
 tests/test_repo_context_defs.py       |   5 +-
 5 files changed, 559 insertions(+), 24 deletions(-)
 create mode 100644 tests/test_chunk_context_jvm.py

diff --git a/src/prxref/chunk_context.py b/src/prxref/chunk_context.py
index 265ccc2..409eb90 100644
--- a/src/prxref/chunk_context.py
+++ b/src/prxref/chunk_context.py
@@ -24,6 +24,8 @@
 from collections.abc import Callable, Iterable, Sequence
 from dataclasses import dataclass
 
+from . import jvm_deps, jvm_lang
+
 # Caps are constants, not configuration: they bound prompt growth, and an
 # operator who wants a different prompt shape has no lever here worth exposing.
 MAX_DEFINITION_ENTRIES = 40
@@ -93,6 +95,9 @@
     "rust": "Cargo.toml",
 }
 
+_JVM_LANGUAGES = frozenset({"java", "kotlin"})
+_GRADLE_SCRIPTS = frozenset({"build.gradle.kts", "settings.gradle.kts"})
+
 
 @dataclass(frozen=True)
 class ChunkFile:
@@ -144,7 +149,7 @@ def _language(path: str) -> str:
         return "go"
     if lower.endswith(".rs"):
         return "rust"
-    return ""
+    return jvm_lang.jvm_language(path)
 
 
 def _js_package(specifier: str) -> str:
@@ -319,13 +324,27 @@ def dependency_versions(
     For each changed file the nearest manifest — ``package.json``,
     ``pyproject.toml``, ``go.mod`` or ``Cargo.toml`` — is located by walking up
     from the file's directory to the repository root via ``read``. Only
-    packages actually imported on the chunk's added lines are reported. The
-    result is sorted and deduplicated; an unreadable or unparseable manifest
-    contributes nothing.
+    packages actually imported on the chunk's added lines are reported.
+
+    A Java or Kotlin file (``.java``, ``.kt``, ``.kts``) is handed to
+    :func:`prxref.jvm_deps.dependency_lines` instead, which finds the nearest
+    ``pom.xml``, ``build.gradle.kts`` or ``build.gradle`` and reports
+    ``groupId:artifactId@version`` lines, or ``groupId:artifactId@(managed by
+    ...)`` when a BOM or platform owns the version, for the imports on the
+    added lines. The Gradle scripts ``build.gradle.kts`` and
+    ``settings.gradle.kts`` are skipped without a read, because their imports
+    name the Gradle API rather than a declared dependency.
+
+    The result is every language's lines together, sorted and deduplicated; an
+    unreadable or unparseable manifest contributes nothing.
     """
     lines: set[str] = set()
     for entry in files:
         language = _language(entry.path)
+        if language in _JVM_LANGUAGES:
+            if entry.path.rsplit("/", 1)[-1] not in _GRADLE_SCRIPTS:
+                lines.update(jvm_deps.dependency_lines(entry.path, entry.added, read))
+            continue
         manifest = _MANIFESTS.get(language)
         if not manifest:
             continue
@@ -352,12 +371,14 @@ def _definition_regexes(language: str) -> tuple[re.Pattern[str], ...]:
         return (_JS_DEF_RE,)
     if language == "python":
         return (_PY_DEF_RE, _PY_ASSIGN_RE)
-    return ()
+    return jvm_lang.definition_regexes(language)
 
 
 def _keywords(language: str) -> frozenset[str]:
     if language == "python":
         return _PY_KEYWORDS
+    if language in _JVM_LANGUAGES:
+        return jvm_lang.keywords(language)
     return _JS_KEYWORDS
 
 
@@ -390,13 +411,25 @@ def referenced_definitions(
     ``max_lines_per_entry``. Order is deterministic (path, then line). Files
     larger than 512 KiB are skipped. When the entry or character cap trims the
     list, a final ``… N more definitions omitted`` line says so.
+
+    Languages with definition regexes are js, python, Java and Kotlin. Java
+    matches types, methods, fields and constants, and enum constants; Kotlin
+    matches types, ``fun`` and ``val``/``var``. The first regex that matches a
+    line decides it. A Java or Kotlin entry also starts at the annotation lines
+    directly above the definition (at most
+    :data:`prxref.jvm_lang.MAX_ANNOTATION_LINES`, and never so many that the
+    definition line itself would not fit in ``max_lines_per_entry``), and its
+    ``<line>`` is the first annotation's; those lines count toward
+    ``max_lines_per_entry``.
     """
     collected: list[tuple[str, int, str]] = []
+    max_annotations = max(0, min(jvm_lang.MAX_ANNOTATION_LINES, max_lines_per_entry - 1))
     for entry in chunk_files:
         language = _language(entry.path)
         regexes = _definition_regexes(language)
         if not regexes:
             continue
+        jvm = language in _JVM_LANGUAGES
         content = read(entry.path)
         if not content or len(content.encode("utf-8", "ignore")) > MAX_FILE_BYTES:
             continue
@@ -427,9 +460,13 @@ def referenced_definitions(
                 name = match.group(1)
                 if name in referenced and name not in seen:
                     seen.add(name)
-                    collected.append(
-                        (entry.path, number, _entry_text(lines, idx, max_lines_per_entry))
+                    start = (
+                        jvm_lang.annotation_start(lines, idx, max_annotations=max_annotations)
+                        if jvm else idx
                     )
+                    body = [above.rstrip() for above in lines[start:idx]]
+                    body.append(_entry_text(lines, idx, max_lines_per_entry - (idx - start)))
+                    collected.append((entry.path, start + 1, "\n".join(body)))
                 break
 
     collected.sort(key=lambda item: (item[0], item[1]))
diff --git a/src/prxref/repo_crosschunk.py b/src/prxref/repo_crosschunk.py
index 3bd1b21..3228ae4 100644
--- a/src/prxref/repo_crosschunk.py
+++ b/src/prxref/repo_crosschunk.py
@@ -33,7 +33,7 @@
 
 MAX_CHANGE_LINES = 12
 
-_SAME_FILE_LANGUAGES = frozenset({"js", "python"})
+_SAME_FILE_LANGUAGES = frozenset({"js", "python", "java", "kotlin"})
 
 
 def _diff_lines(f: object) -> list[object]:
diff --git a/tests/test_chunk_context_jvm.py b/tests/test_chunk_context_jvm.py
new file mode 100644
index 0000000..e3910f5
--- /dev/null
+++ b/tests/test_chunk_context_jvm.py
@@ -0,0 +1,478 @@
+"""Java and Kotlin in :mod:`prxref.chunk_context` (#20).
+
+A ``.java``, ``.kt`` or ``.kts`` file now gets the two blocks every other
+language already had: definitions referenced from its added lines, found
+outside its hunks in the same file and led by up to two annotation lines, and
+dependency versions from the nearest ``pom.xml`` or Gradle build. Every other
+language must behave exactly as before, so the last class pins js, python, go
+and rust against output captured from the code before this change.
+"""
+from __future__ import annotations
+
+import pytest
+
+from prxref import chunk_context, jvm_deps, jvm_lang
+from prxref.chunk_context import (
+    MAX_LINES_PER_DEFINITION,
+    ChunkFile,
+    dependency_versions,
+    referenced_definitions,
+)
+
+ELLIPSIS = "\N{HORIZONTAL ELLIPSIS}"
+
+
+class Reader:
+    """A ``read(path)`` callable over a dict that records every path asked for."""
+
+    def __init__(self, texts: dict[str, str]):
+        self.texts = texts
+        self.calls: list[str] = []
+
+    def __call__(self, path: str) -> str | None:
+        self.calls.append(path)
+        return self.texts.get(path)
+
+
+def _text(lines: list[str]) -> str:
+    return "\n".join(lines) + "\n"
+
+
+def _entry(path: str, lines: list[str], first: int, last: int) -> str:
+    """The rendered entry for 1-based source lines ``first`` through ``last``."""
+    return f"{path}:{first}: " + "\n".join(lines[first - 1:last])
+
+
+ORDER_SERVICE = "src/main/java/com/acme/orders/OrderService.java"
+ORDER_SERVICE_LINES = [
+    "package com.acme.orders;",
+    "",
+    "import com.fasterxml.jackson.annotation.JsonProperty;",
+    "",
+    "public class OrderService {",
+    "",
+    "    @Deprecated",
+    "    public static final int MAX_ITEMS = 50;",
+    "",
+    '    @JsonProperty("customer_id")',
+    "    @Nullable",
+    "    private String customerId;",
+    "",
+    "    @Transactional",
+    "    @Override",
+    "    public Order place(Order order, int count) {",
+    "        return repository.save(order);",
+    "    }",
+    "",
+    "    public void process(Order order) {",
+    "        if (order.items() > MAX_ITEMS) {",
+    "            log(customerId);",
+    "        }",
+    "        place(order, 1);",
+    "    }",
+    "}",
+]
+ORDER_SERVICE_CHUNK = ChunkFile(
+    ORDER_SERVICE, tuple(ORDER_SERVICE_LINES[20:24]), frozenset(range(20, 27)),
+)
+
+
+class TestJavaDefinitions:
+    def test_a_constant_a_field_and_a_method_outside_the_hunks_come_with_their_annotations(self):
+        read = Reader({ORDER_SERVICE: _text(ORDER_SERVICE_LINES)})
+        out = referenced_definitions([ORDER_SERVICE_CHUNK], read)
+        assert out == [
+            _entry(ORDER_SERVICE, ORDER_SERVICE_LINES, 7, 8),
+            _entry(ORDER_SERVICE, ORDER_SERVICE_LINES, 10, 12),
+            _entry(ORDER_SERVICE, ORDER_SERVICE_LINES, 14, 18),
+        ]
+        assert out[0].endswith("    @Deprecated\n    public static final int MAX_ITEMS = 50;")
+        assert out[2].split("\n")[:3] == [
+            f"{ORDER_SERVICE}:14:     @Transactional",
+            "    @Override",
+            "    public Order place(Order order, int count) {",
+        ]
+        assert all(len(entry.split("\n")) <= MAX_LINES_PER_DEFINITION for entry in out)
+        assert read.calls == [ORDER_SERVICE]
+
+    @pytest.mark.parametrize(("above", "first"), [
+        (["    @A", "    @B", "    @C"], 3),
+        (["    @A", "", "    @B"], 4),
+        (["    // @A", "    @B"], 3),
+        ([], 2),
+    ], ids=["three-annotations-keep-the-nearest-two", "a-blank-line-stops-the-walk", "a-comment-stops-the-walk",
+            "no-annotation"])
+    def test_the_entry_starts_at_the_nearest_two_contiguous_annotation_lines(self, above, first):
+        lines = ["public class Limits {", *above, "    int limit = 3;", "}", *["    // pad"] * 20]
+        definition = 2 + len(above)
+        files = [ChunkFile("p/Limits.java", ("        return limit;",), frozenset({30}))]
+        out = referenced_definitions(files, Reader({"p/Limits.java": _text(lines)}))
+        assert out == [_entry("p/Limits.java", lines, first, definition)]
+
+    CALC = [
+        "public class Calc {",
+        "    @A",
+        "    @B",
+        "    public int compute(int a,",
+        "            int b) {",
+        "        return a + b;",
+        "    }",
+        "}",
+        *["    // pad"] * 20,
+    ]
+
+    @pytest.mark.parametrize(("cap", "first", "last"), [
+        (1, 4, 4), (2, 3, 4), (3, 2, 4), (4, 2, 5), (6, 2, 7), (7, 2, 7),
+    ])
+    def test_annotation_lines_count_toward_the_line_cap_and_never_push_out_the_definition(self, cap, first, last):
+        files = [ChunkFile("p/Calc.java", ("        compute(1, 2);",), frozenset({25}))]
+        out = referenced_definitions(
+            files, Reader({"p/Calc.java": _text(self.CALC)}), max_lines_per_entry=cap,
+        )
+        assert out == [_entry("p/Calc.java", self.CALC, first, last)]
+        assert len(out[0].split("\n")) <= cap
+        assert "public int compute(int a," in out[0]
+
+    def test_a_keyword_is_never_a_referenced_name(self):
+        lines = [
+            "public class Holder {",
+            "    private String module;",
+            "    int record = 0;",
+            "    private String name;",
+            "}",
+            *["    // pad"] * 20,
+        ]
+        files = [ChunkFile("p/Holder.java", ("        return module + record + name;",), frozenset({20}))]
+        out = referenced_definitions(files, Reader({"p/Holder.java": _text(lines)}))
+        assert out == [_entry("p/Holder.java", lines, 4, 4)]
+        assert {"module", "record", "return"} <= jvm_lang.JAVA_KEYWORDS
+
+    def test_a_name_defined_on_an_added_line_is_not_looked_up(self):
+        lines = ["public class Box {", "    int size = 1;", "}", *["    // pad"] * 20]
+        added = ("    int size = 2;", "    return size;")
+        files = [ChunkFile("p/Box.java", added, frozenset({20, 21}))]
+        assert referenced_definitions(files, Reader({"p/Box.java": _text(lines)})) == []
+
+
+class TestJavaCaps:
+    CONSTANTS = [
+        "public class Consts {",
+        *[f"    static final int LIMIT_{i} = {i};" for i in range(6)],
+        "}",
+        *["    // pad"] * 10,
+    ]
+    ADDED = ("        return " + " + ".join(f"LIMIT_{i}" for i in range(6)) + ";",)
+
+    def test_the_entry_cap_appends_the_omitted_line(self):
+        files = [ChunkFile("p/Consts.java", self.ADDED, frozenset({30}))]
+        out = referenced_definitions(files, Reader({"p/Consts.java": _text(self.CONSTANTS)}), max_entries=2)
+        assert out == [
+            _entry("p/Consts.java", self.CONSTANTS, 2, 2),
+            _entry("p/Consts.java", self.CONSTANTS, 3, 3),
+            f"{ELLIPSIS} 4 more definitions omitted",
+        ]
+
+    def test_the_character_cap_appends_the_omitted_line(self):
+        files = [ChunkFile("p/Consts.java", self.ADDED, frozenset({30}))]
+        out = referenced_definitions(files, Reader({"p/Consts.java": _text(self.CONSTANTS)}), max_chars=100)
+        assert out == [
+            _entry("p/Consts.java", self.CONSTANTS, 2, 2),
+            _entry("p/Consts.java", self.CONSTANTS, 3, 3),
+            f"{ELLIPSIS} 4 more definitions omitted",
+        ]
+
+    def test_annotation_lines_count_toward_the_character_cap(self):
+        lines = ["public class A {", "    @Nullable", "    String value;", "}", *["    // pad"] * 10]
+        files = [ChunkFile("p/A.java", ("        return value;",), frozenset({20}))]
+        entry = _entry("p/A.java", lines, 2, 3)
+        read = Reader({"p/A.java": _text(lines)})
+        assert referenced_definitions(files, read, max_chars=len(entry)) == [entry]
+        assert referenced_definitions(files, read, max_chars=len(entry) - 1) == [
+            f"{ELLIPSIS} 1 more definitions omitted",
+        ]
+
+    def test_a_file_over_512_kib_is_skipped(self):
+        text = "public class Big {\n    static final int BIG = 1;\n" + "    // pad\n" * 60_000
+        assert len(text.encode("utf-8")) > chunk_context.MAX_FILE_BYTES
+        files = [ChunkFile("p/Big.java", ("        return BIG;",), frozenset({70_000}))]
+        assert referenced_definitions(files, Reader({"p/Big.java": text})) == []
+
+
+ORDERS_KT = "src/main/kotlin/com/acme/orders/Orders.kt"
+ORDERS_KT_LINES = [
+    "package com.acme.orders",
+    "",
+    "@Serializable",
+    "data class Order(val id: String, val count: Int)",
+    "",
+    '@field:JsonProperty("limit")',
+    "val limit: Int = 10",
+    "",
+    "@Throws(IOException::class)",
+    "fun load(id: String): Order {",
+    "    return Order(id, limit)",
+    "}",
+    "",
+    "fun process(id: String) {",
+    "    val order = load(id)",
+    "    println(limit + Order(id, 1).count)",
+    "}",
+]
+
+
+class TestKotlinDefinitions:
+    def test_a_class_a_val_and_a_fun_come_with_their_annotations(self):
+        files = [ChunkFile(ORDERS_KT, tuple(ORDERS_KT_LINES[14:16]), frozenset(range(14, 18)))]
+        out = referenced_definitions(files, Reader({ORDERS_KT: _text(ORDERS_KT_LINES)}))
+        assert out == [
+            _entry(ORDERS_KT, ORDERS_KT_LINES, 3, 4),
+            _entry(ORDERS_KT, ORDERS_KT_LINES, 6, 7),
+            _entry(ORDERS_KT, ORDERS_KT_LINES, 9, 12),
+        ]
+
+    def test_a_kotlin_keyword_is_never_a_referenced_name(self):
+        lines = [
+            "class Holder {",
+            "    val data = load()",
+            "    val value = 2",
+            '    val name = "x"',
+            "}",
+            *["    // pad"] * 20,
+        ]
+        files = [ChunkFile("p/Holder.kt", ("    println(data + value + name)",), frozenset({20}))]
+        out = referenced_definitions(files, Reader({"p/Holder.kt": _text(lines)}))
+        assert out == [_entry("p/Holder.kt", lines, 4, 4)]
+
+    def test_a_gradle_script_is_searched_as_kotlin(self):
+        lines = [
+            "import org.gradle.api.tasks.Exec",
+            "",
+            'val releaseVersion = "1.2.3"',
+            "",
+            'tasks.register<Exec>("release") {',
+            '    commandLine("git", "tag", releaseVersion)',
+            "}",
+        ]
+        files = [ChunkFile("build.gradle.kts", (lines[5],), frozenset({5, 6, 7}))]
+        out = referenced_definitions(files, Reader({"build.gradle.kts": _text(lines)}))
+        assert out == [_entry("build.gradle.kts", lines, 3, 3)]
+
+
+class TestAnnotationsAreJvmOnly:
+    @pytest.mark.parametrize(("path", "lines", "added", "first", "last"), [
+        (
+            "web/foo.ts",
+            ["import { Injectable } from '@angular/core';", "", "@Injectable()", "export class Foo {",
+             "  run() {}", "}", *["// pad"] * 20],
+            "  return new Foo();", 4, 6,
+        ),
+        (
+            "app/widget.py",
+            ["import dataclasses", "", "@dataclasses.dataclass", "class Widget:", "    size: int",
+             *["# pad"] * 20],
+            "    return Widget(1)", 4, 4,
+        ),
+    ], ids=["ts-decorator", "python-decorator"])
+    def test_a_decorator_above_a_js_or_python_definition_is_not_included(self, path, lines, added, first, last):
+        assert jvm_lang.annotation_start(lines, first - 1) == first - 2
+        files = [ChunkFile(path, (added,), frozenset({40}))]
+        out = referenced_definitions(files, Reader({path: _text(lines)}))
+        assert out == [_entry(path, lines, first, last)]
+
+
+def _pom(*dependencies: tuple[str, str, str]) -> str:
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<project xmlns="http://maven.apache.org/POM/4.0.0">\n'
+        "  <modelVersion>4.0.0</modelVersion>\n"
+        "  <groupId>com.acme</groupId><artifactId>orders</artifactId><version>1.0.0</version>\n"
+        "  <dependencies>\n"
+        + "".join(
+            f"    <dependency><groupId>{g}</groupId><artifactId>{a}</artifactId>"
+            f"<version>{v}</version></dependency>\n"
+            for g, a, v in dependencies
+        )
+        + "  </dependencies>\n</project>\n"
+    )
+
+
+JACKSON_POM = _pom(
+    ("com.fasterxml.jackson.core", "jackson-core", "2.17.1"),
+    ("com.fasterxml.jackson.core", "jackson-databind", "2.17.1"),
+)
+DATABIND_LINE = "com.fasterxml.jackson.core:jackson-databind@2.17.1"
+MAPPER = "orders/src/main/java/com/acme/orders/OrderMapper.java"
+MAPPER_ADDED = (
+    "import com.fasterxml.jackson.databind.ObjectMapper;",
+    "import java.util.List;",
+    "import com.acme.orders.model.Order;",
+)
+
+
+class TestJvmDependencies:
+    def test_a_java_chunk_importing_databind_gets_the_databind_line_from_the_pom_beside_it(self):
+        texts = {"orders/pom.xml": JACKSON_POM}
+        files = [ChunkFile(MAPPER, MAPPER_ADDED)]
+        assert dependency_versions(files, Reader(texts)) == [DATABIND_LINE]
+        assert dependency_versions(files, Reader(texts)) == jvm_deps.dependency_lines(
+            MAPPER, MAPPER_ADDED, Reader(texts),
+        )
+
+    def test_a_kotlin_chunk_reads_its_gradle_build(self):
+        texts = {
+            "build.gradle.kts": (
+                'dependencies {\n    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.1")\n}\n'
+            ),
+        }
+        files = [ChunkFile("app/src/main/kotlin/App.kt", ("import com.fasterxml.jackson.databind.ObjectMapper",))]
+        assert dependency_versions(files, Reader(texts)) == [DATABIND_LINE]
+
+    def test_jvm_lines_merge_with_other_languages_sorted_and_deduplicated(self):
+        texts = {
+            "orders/pom.xml": JACKSON_POM,
+            "package.json": '{"dependencies": {"effect": "4.0.0"}}',
+        }
+        files = [
+            ChunkFile("web/a.ts", ("import { E } from 'effect';",)),
+            ChunkFile(MAPPER, MAPPER_ADDED),
+            ChunkFile("orders/src/main/java/com/acme/orders/Other.java", MAPPER_ADDED[:1]),
+        ]
+        assert dependency_versions(files, Reader(texts)) == [DATABIND_LINE, "effect@4.0.0"]
+
+    @pytest.mark.parametrize("path", ["build.gradle.kts", "app/build.gradle.kts", "settings.gradle.kts"])
+    def test_a_gradle_script_is_skipped_without_a_read(self, path):
+        read = Reader({"build.gradle.kts": "plugins { java }\n"})
+        files = [ChunkFile(path, ("import org.gradle.api.tasks.Exec",))]
+        assert dependency_versions(files, read) == []
+        assert read.calls == []
+
+    def test_control_the_same_import_in_a_kotlin_source_file_walks_for_a_manifest(self):
+        read = Reader({})
+        files = [ChunkFile("app/Tasks.kt", ("import org.gradle.api.tasks.Exec",))]
+        assert dependency_versions(files, read) == []
+        assert read.calls == [
+            "app/pom.xml", "app/build.gradle.kts", "app/build.gradle",
+            "pom.xml", "build.gradle.kts", "build.gradle",
+        ]
+
+
+def _ts_file() -> str:
+    body = [f"// filler {i}" for i in range(1, 10)]
+    body += ["const Positive = check(", "  isInt(),", ");"]
+    body += [f"// filler {i}" for i in range(13, 30)]
+    return "\n".join(body) + "\n"
+
+
+PY_SOURCE = (
+    "LIMIT = 10\n"
+    "\n"
+    "def helper(x):\n"
+    "    return x\n"
+    "\n"
+    "class Widget:\n"
+    "    pass\n"
+) + "".join(f"# pad {i}\n" for i in range(8, 40))
+
+BASE_CASES = {
+    "js": (
+        [
+            ChunkFile("src/a.ts", ("import { E } from 'effect';", "import { t } from 'vitest';")),
+            ChunkFile("src/b.ts", ("  limit: Positive,",), frozenset({25, 26})),
+        ],
+        {
+            "package.json": (
+                '{"dependencies": {"effect": "4.0.0-rc.110", "unused": "1.0.0"},'
+                ' "devDependencies": {"vitest": "^2.1.0"}}'
+            ),
+            "src/b.ts": _ts_file(),
+        },
+    ),
+    "python": (
+        [
+            ChunkFile("src/a.py", ("import requests",)),
+            ChunkFile("m.py", ("    return helper(LIMIT) or Widget()",), frozenset({50})),
+        ],
+        {
+            "pyproject.toml": '[project]\nname = "x"\ndependencies = ["requests>=2.31", "rich"]\n',
+            "m.py": PY_SOURCE,
+        },
+    ),
+    "go": (
+        [ChunkFile("cmd/a.go", ('import "github.com/pkg/errors"',))],
+        {"go.mod": "module x\n\nrequire (\n\tgithub.com/pkg/errors v0.9.1\n)\n"},
+    ),
+    "rust": (
+        [ChunkFile("src/a.rs", ("use serde::Serialize;", "use tokio::spawn;"))],
+        {
+            "Cargo.toml": (
+                '[dependencies]\nserde = "1.0.203"\n'
+                'tokio = { version = "1.38", features = ["full"] }\n'
+            ),
+        },
+    ),
+}
+
+BASE_OUTPUT = {
+    "js": {
+        "deps": ["effect@4.0.0-rc.110", "vitest@^2.1.0"],
+        "deps_reads": ["src/package.json", "package.json"],
+        "defs": ["src/b.ts:10: const Positive = check(\n  isInt(),\n);"],
+        "defs_reads": ["src/a.ts", "src/b.ts"],
+    },
+    "python": {
+        "deps": ["requests@>=2.31"],
+        "deps_reads": ["src/pyproject.toml", "pyproject.toml"],
+        "defs": ["m.py:1: LIMIT = 10", "m.py:3: def helper(x):", "m.py:6: class Widget:"],
+        "defs_reads": ["src/a.py", "m.py"],
+    },
+    "go": {"deps": [], "deps_reads": [], "defs": [], "defs_reads": []},
+    "rust": {
+        "deps": ["serde@1.0.203", "tokio@1.38"],
+        "deps_reads": ["src/Cargo.toml", "Cargo.toml"],
+        "defs": [],
+        "defs_reads": [],
+    },
+}
+
+
+class TestOtherLanguagesAreUnchanged:
+    """Output and reads captured from the code before #20, for one existing input per language."""
+
+    @pytest.mark.parametrize("language", sorted(BASE_CASES))
+    def test_output_and_reads_equal_the_pre_jvm_capture(self, language):
+        files, texts = BASE_CASES[language]
+        deps_read, defs_read = Reader(texts), Reader(texts)
+        observed = {
+            "deps": dependency_versions(files, deps_read),
+            "deps_reads": deps_read.calls,
+            "defs": referenced_definitions(files, defs_read),
+            "defs_reads": defs_read.calls,
+        }
+        assert observed == BASE_OUTPUT[language]
+
+    @pytest.mark.parametrize(("path", "language"), [
+        ("a.ts", "js"), ("a.py", "python"), ("a.go", "go"), ("a.rs", "rust"),
+        ("a.scala", ""), ("README.md", ""), ("build.gradle", ""), ("Service.javax", ""),
+        ("A.java", "java"), ("B.JAVA", "java"), ("a.kt", "kotlin"), ("build.gradle.kts", "kotlin"),
+    ])
+    def test_the_language_map(self, path, language):
+        assert chunk_context._language(path) == language
+
+    @pytest.mark.parametrize("language", ["go", "rust", "", "scala"])
+    def test_languages_without_regexes_keep_none_and_the_js_keywords(self, language):
+        assert chunk_context._definition_regexes(language) == ()
+        assert chunk_context._keywords(language) is chunk_context._JS_KEYWORDS
+
+    def test_js_and_python_keep_their_own_regexes_and_keywords(self):
+        assert chunk_context._definition_regexes("js") == (chunk_context._JS_DEF_RE,)
+        assert chunk_context._definition_regexes("python") == (chunk_context._PY_DEF_RE, chunk_context._PY_ASSIGN_RE)
+        assert chunk_context._keywords("js") is chunk_context._JS_KEYWORDS
+        assert chunk_context._keywords("python") is chunk_context._PY_KEYWORDS
+
+    @pytest.mark.parametrize(("language", "regexes", "keywords"), [
+        ("java", jvm_lang.JAVA_DEFINITION_REGEXES, jvm_lang.JAVA_KEYWORDS),
+        ("kotlin", jvm_lang.KOTLIN_DEFINITION_REGEXES, jvm_lang.KOTLIN_KEYWORDS),
+    ])
+    def test_java_and_kotlin_use_the_jvm_tables(self, language, regexes, keywords):
+        assert chunk_context._definition_regexes(language) is regexes
+        assert chunk_context._keywords(language) is keywords
diff --git a/tests/test_repo_context_crosschunk.py b/tests/test_repo_context_crosschunk.py
index fdb7459..d5480b0 100644
--- a/tests/test_repo_context_crosschunk.py
+++ b/tests/test_repo_context_crosschunk.py
@@ -14,7 +14,7 @@
 
 import pytest
 
-from prxref import repo_crosschunk
+from prxref import chunk_context, repo_crosschunk
 from prxref.repo_context import REASONS, ContextEntry
 from prxref.repo_crosschunk import MAX_CHANGE_LINES, diff_definitions
 from prxref.triage import build_chunks, parse_unified_diff
@@ -126,7 +126,7 @@ def test_reads_only_the_files_a_definition_regex_covers(self):
         files, chunks = _fixture()
         read = _RepoReader()
         diff_definitions(_chunk_holding(chunks, CONNECTOR_SERVICE), files, read)
-        assert read.calls == [TRANSPORT_CONFIG, CONNECTOR_SERVICE]
+        assert read.calls == [TRANSPORT_CONFIG]
 
     @pytest.mark.parametrize("read", [None, lambda path: None], ids=["no-reader", "reader-returns-none"])
     def test_without_file_text_the_entries_come_from_hunks(self, read):
@@ -170,17 +170,29 @@ def test_a_changed_file_outside_the_chunk_is_cross_chunk_even_when_the_definitio
         entries = diff_definitions([CALLER], [CALLER, limits], read)
         assert _keys(entries) == [("app/Limits.java", 3, "Limits", "definition", "cross-chunk")]
 
-    def test_java_definition_in_the_chunks_own_file_outside_its_hunks_is_diff_file(self):
-        widget = _file(
+    @pytest.mark.parametrize(("path", "hunk", "text"), [
+        (
             "p/Widget.java",
-            (7, ["     Widget copy() {", "+        return new Widget();", "     }"]),
-        )
-        text = (
+            ["     Widget copy() {", "+        return new Widget();", "     }"],
             "package p;\n\npublic class Widget {\n\n    private int size;\n\n"
-            "    Widget copy() {\n        return new Widget();\n    }\n}\n"
-        )
-        entries = diff_definitions([widget], [widget], _Reader({"p/Widget.java": text}))
-        assert _keys(entries) == [("p/Widget.java", 3, "Widget", "definition", "diff-file")]
+            "    Widget copy() {\n        return new Widget();\n    }\n}\n",
+        ),
+        (
+            "p/Widget.kt",
+            ["     fun copy(): Widget {", "+        return Widget()", "     }"],
+            "package p\n\nclass Widget {\n\n    private val size = 0\n\n"
+            "    fun copy(): Widget {\n        return Widget()\n    }\n}\n",
+        ),
+    ], ids=["java", "kotlin"])
+    def test_a_jvm_definition_in_the_chunks_own_file_is_left_to_chunk_context(self, path, hunk, text):
+        widget = _file(path, (7, hunk))
+        read = _Reader({path: text})
+        assert diff_definitions([widget], [widget], read) == []
+        assert read.calls == []
+        lines = text.splitlines()
+        assert chunk_context.referenced_definitions(chunk_context.chunk_files([widget]), read) == [
+            f"{path}:3: " + "\n".join(lines[2:8]),
+        ]
 
 
 class TestSkips:
@@ -189,10 +201,17 @@ def test_lines_inside_the_chunks_own_hunks_are_skipped(self):
             "p/Widget.java",
             (3, [" public class Widget {", "+    Widget copy() { return new Widget(); }", " }"]),
         )
-        text = "package p;\n\npublic class Widget {\n    Widget copy() { return new Widget(); }\n}\n"
-        read = _Reader({"p/Widget.java": text})
+        assert diff_definitions([widget], [widget], None) == []
+
+    @pytest.mark.parametrize(("path", "line"), [
+        ("p/Widget.java", "+    Widget copy() { return new Widget(); }"),
+        ("p/Widget.kt", "+    fun copy(): Widget = Widget()"),
+    ], ids=["java", "kotlin"])
+    def test_a_jvm_file_in_the_chunk_is_skipped_when_a_reader_is_given(self, path, line):
+        widget = _file(path, (3, [" class Widget {", line, " }"]))
+        read = _Reader({path: "package p\n\nclass Widget {\n" + line[1:] + "\n}\n"})
         assert diff_definitions([widget], [widget], read) == []
-        assert read.calls == ["p/Widget.java"]
+        assert read.calls == []
 
     def test_a_python_file_in_the_chunk_is_skipped_when_a_reader_is_given(self):
         service = _file("app/service.py", (20, [" def handle(req):", "+    return build_reply(req)"]))
diff --git a/tests/test_repo_context_defs.py b/tests/test_repo_context_defs.py
index 0261a44..1896c6e 100644
--- a/tests/test_repo_context_defs.py
+++ b/tests/test_repo_context_defs.py
@@ -80,8 +80,9 @@ def test_js_and_python_delegate_to_chunk_context(self):
     def test_languages_without_regexes_get_none(self, language):
         assert definition_regexes(language) == ()
 
-    def test_java_is_not_added_to_chunk_context(self):
-        assert chunk_context._definition_regexes("java") == ()
+    def test_java_is_added_to_chunk_context(self):
+        assert chunk_context._definition_regexes("java") is chunk_context.jvm_lang.JAVA_DEFINITION_REGEXES
+        assert len(chunk_context._definition_regexes("java")) == 4
         assert len(definition_regexes("java")) == 1
 
 

From 136b8db2f880f37bd84c0100a01ab38aa87adf9b Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 21:14:04 -0700
Subject: [PATCH 18/25] test: issue #22 acceptance over the issue's own
 fixture, end to end
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds tests/fixtures/issue22: the issue's make-fixture.sh, the PR as
pr.patch (format-patch main..feature/progress-notes under a fixed
placeholder identity and date, byte-reproducible), the PR head tree as
repo/, and the issue's description as desc.md.

tests/test_issue_22_acceptance.py drives the production local path,
cli._run_review with --diff-file, --repo-dir and --description-file,
against the real openai-compat client and a local scripted server that
answers every prompt with no findings, and asserts on the --format json
payload and the recorded prompts:

- at repo, the progress.py chunk's reader block lists
  assistant/history.py:9, assistant/state_store.py:15 and
  tests/test_engine.py:17, in that order, and nothing else in the prompt
  names either source file; the run record carries the same three
  shared-state reader rows;
- at diff and off, no prompt carries the reader block;
- at every level there is exactly one finding, the pinned-off toggle at
  assistant/progress.py:34, undropped and with the deterministic suffix;
  deleting the conftest pin, or setting it to "true", removes it;
- repo_readers.MAX_READER_ENTRIES = 0 removes exactly the reader block
  and nothing else from the prompts, and no reader row from the record;
- repo/ matches both the generator's head tree and the patch's
  post-image, and the patch carries only dev@example.com.

repo/ holds the fixture project's own tests and code that the project's
lint rules reject, so tests/fixtures/issue22/conftest.py keeps pytest
out of it (collect_ignore) and tests/fixtures/issue22/ruff.toml keeps
ruff out of it, while inheriting the project's settings.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 tests/fixtures/issue22/conftest.py            |  10 +
 tests/fixtures/issue22/desc.md                |   1 +
 tests/fixtures/issue22/make-fixture.sh        | 317 ++++++++++++++++++
 tests/fixtures/issue22/pr.patch               | 167 +++++++++
 tests/fixtures/issue22/repo/.gitignore        |   2 +
 tests/fixtures/issue22/repo/README.md         |   8 +
 .../issue22/repo/assistant/__init__.py        |   0
 .../fixtures/issue22/repo/assistant/engine.py |  40 +++
 .../issue22/repo/assistant/features.py        |   7 +
 .../issue22/repo/assistant/history.py         |  16 +
 .../issue22/repo/assistant/messages.py        |  21 ++
 .../issue22/repo/assistant/progress.py        |  48 +++
 .../issue22/repo/assistant/session.py         |  25 ++
 .../issue22/repo/assistant/state_store.py     |  21 ++
 tests/fixtures/issue22/repo/pyproject.toml    |   7 +
 tests/fixtures/issue22/repo/tests/conftest.py |   7 +
 .../issue22/repo/tests/test_engine.py         |  23 ++
 .../issue22/repo/tests/test_progress.py       |  19 ++
 tests/fixtures/issue22/ruff.toml              |   7 +
 tests/test_issue_22_acceptance.py             | 261 ++++++++++++++
 20 files changed, 1007 insertions(+)
 create mode 100644 tests/fixtures/issue22/conftest.py
 create mode 100644 tests/fixtures/issue22/desc.md
 create mode 100644 tests/fixtures/issue22/make-fixture.sh
 create mode 100644 tests/fixtures/issue22/pr.patch
 create mode 100644 tests/fixtures/issue22/repo/.gitignore
 create mode 100644 tests/fixtures/issue22/repo/README.md
 create mode 100644 tests/fixtures/issue22/repo/assistant/__init__.py
 create mode 100644 tests/fixtures/issue22/repo/assistant/engine.py
 create mode 100644 tests/fixtures/issue22/repo/assistant/features.py
 create mode 100644 tests/fixtures/issue22/repo/assistant/history.py
 create mode 100644 tests/fixtures/issue22/repo/assistant/messages.py
 create mode 100644 tests/fixtures/issue22/repo/assistant/progress.py
 create mode 100644 tests/fixtures/issue22/repo/assistant/session.py
 create mode 100644 tests/fixtures/issue22/repo/assistant/state_store.py
 create mode 100644 tests/fixtures/issue22/repo/pyproject.toml
 create mode 100644 tests/fixtures/issue22/repo/tests/conftest.py
 create mode 100644 tests/fixtures/issue22/repo/tests/test_engine.py
 create mode 100644 tests/fixtures/issue22/repo/tests/test_progress.py
 create mode 100644 tests/fixtures/issue22/ruff.toml
 create mode 100644 tests/test_issue_22_acceptance.py

diff --git a/tests/fixtures/issue22/conftest.py b/tests/fixtures/issue22/conftest.py
new file mode 100644
index 0000000..5ee08a7
--- /dev/null
+++ b/tests/fixtures/issue22/conftest.py
@@ -0,0 +1,10 @@
+"""Keep pytest out of the issue #22 fixture project's own tree.
+
+``repo/`` is the fixture project's PR head, checked in as plain files. It
+carries that project's own ``tests/conftest.py`` and ``test_*.py`` modules,
+which import an ``assistant`` package that is not installed here. They are
+review input for the repository-context readers, not tests of prxref, so the
+suite never collects them.
+"""
+
+collect_ignore = ["repo"]
diff --git a/tests/fixtures/issue22/desc.md b/tests/fixtures/issue22/desc.md
new file mode 100644
index 0000000..55e70f1
--- /dev/null
+++ b/tests/fixtures/issue22/desc.md
@@ -0,0 +1 @@
+the tests pin the toggle off and all tests are green
diff --git a/tests/fixtures/issue22/make-fixture.sh b/tests/fixtures/issue22/make-fixture.sh
new file mode 100644
index 0000000..98459e5
--- /dev/null
+++ b/tests/fixtures/issue22/make-fixture.sh
@@ -0,0 +1,317 @@
+#!/usr/bin/env bash
+# Builds the fixture: branch main (base) and feature/progress-notes (the PR). Usage: make-fixture.sh [dir]
+set -euo pipefail; D=${1:-shared-sink}; rm -rf "$D"; mkdir -p "$D"; cd "$D"; git init -q -b main
+git config user.name fixture; git config user.email fixture@example.invalid
+mkdir -p "$(dirname 'README.md')"; cat > 'README.md' <<'__EOF__'
+# assistant
+
+A tiny chat assistant engine: a user message runs a loop of steps (model calls and tool calls).
+A run that needs a human hands off: its state is saved to the state store and resumed later.
+__EOF__
+mkdir -p "$(dirname 'assistant/__init__.py')"; cat > 'assistant/__init__.py' <<'__EOF__'
+__EOF__
+mkdir -p "$(dirname 'assistant/engine.py')"; cat > 'assistant/engine.py' <<'__EOF__'
+"""Runs one user turn as a sequence of steps."""
+from dataclasses import dataclass
+from typing import Callable
+
+from assistant.messages import Message, MessageTable
+from assistant.session import Run
+from assistant.state_store import StateStore
+
+
+@dataclass(frozen=True)
+class Step:
+    kind: str  # "model" | "tool" | "handoff"
+    name: str
+    execute: Callable[[Run], str]
+
+
+class Engine:
+    def __init__(self, table: MessageTable, store: StateStore) -> None:
+        self.table = table
+        self.store = store
+
+    def run_turn(self, run: Run, steps: list[Step]) -> str | None:
+        answer = None
+        for step in steps:
+            if step.kind == "handoff":
+                # A human takes over: park the run so it can resume later.
+                self.store.save(run)
+                return None
+            answer = step.execute(run)
+            self.table.append(Message(run.session_id, "tool" if step.kind == "tool" else "assistant", answer))
+        return answer
+__EOF__
+mkdir -p "$(dirname 'assistant/features.py')"; cat > 'assistant/features.py' <<'__EOF__'
+"""Feature toggles, read from the environment at startup."""
+import os
+
+
+def enabled(name: str, default: bool) -> bool:
+    raw = os.environ.get(f"ASSISTANT_{name.upper()}")
+    return default if raw is None else raw.lower() == "true"
+__EOF__
+mkdir -p "$(dirname 'assistant/history.py')"; cat > 'assistant/history.py' <<'__EOF__'
+"""Builds the model's conversation history from the message table."""
+from assistant.messages import MessageTable
+
+HISTORY_WINDOW = 20
+
+_MODEL_ROLES = {"user": "user", "assistant": "assistant", "tool": "tool"}
+
+
+def model_history(table: MessageTable, session_id: str) -> list[dict]:
+    history = []
+    for m in table.recent(session_id, HISTORY_WINDOW):
+        role = _MODEL_ROLES.get(m.role)
+        if role is None:
+            continue
+        history.append({"role": role, "content": m.text})
+    return history
+__EOF__
+mkdir -p "$(dirname 'assistant/messages.py')"; cat > 'assistant/messages.py' <<'__EOF__'
+"""Append-only message table for a session."""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Message:
+    session_id: str
+    role: str  # "user" | "assistant" | "tool"
+    text: str
+
+
+class MessageTable:
+    def __init__(self) -> None:
+        self._rows: list[Message] = []
+
+    def append(self, message: Message) -> None:
+        self._rows.append(message)
+
+    def recent(self, session_id: str, limit: int) -> list[Message]:
+        rows = [m for m in self._rows if m.session_id == session_id]
+        return rows[-limit:]
+__EOF__
+mkdir -p "$(dirname 'assistant/session.py')"; cat > 'assistant/session.py' <<'__EOF__'
+"""Live state of one run."""
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Frame:
+    """One agent working on the request. The bottom frame is the root agent."""
+
+    agent_id: str
+    # Scratch space any engine component can use for per-frame bookkeeping.
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Run:
+    session_id: str
+    turn_id: str
+    frames: list[Frame] = field(default_factory=list)
+
+    def root(self) -> Frame:
+        return self.frames[0]
+
+    def current(self) -> Frame:
+        return self.frames[-1]
+__EOF__
+mkdir -p "$(dirname 'assistant/state_store.py')"; cat > 'assistant/state_store.py' <<'__EOF__'
+"""Saves a run so it can resume after a human handoff."""
+import json
+from dataclasses import asdict
+
+from assistant.session import Frame, Run
+
+
+class StateStore:
+    def __init__(self) -> None:
+        self._blobs: dict[str, str] = {}
+
+    def save(self, run: Run) -> None:
+        self._blobs[run.session_id] = json.dumps(asdict(run))
+
+    def load(self, session_id: str) -> Run | None:
+        blob = self._blobs.get(session_id)
+        if blob is None:
+            return None
+        raw = json.loads(blob)
+        frames = [Frame(f["agent_id"], f["data"]) for f in raw["frames"]]
+        return Run(raw["session_id"], raw["turn_id"], frames)
+__EOF__
+mkdir -p "$(dirname 'pyproject.toml')"; cat > 'pyproject.toml' <<'__EOF__'
+[project]
+name = "assistant"
+version = "0.1.0"
+requires-python = ">=3.11"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+__EOF__
+mkdir -p "$(dirname 'tests/test_engine.py')"; cat > 'tests/test_engine.py' <<'__EOF__'
+from assistant.engine import Engine, Step
+from assistant.messages import MessageTable
+from assistant.session import Frame, Run
+from assistant.state_store import StateStore
+
+
+def make_run():
+    return Run("s1", "t1", [Frame("root")])
+
+
+def test_turn_returns_last_answer():
+    engine = Engine(MessageTable(), StateStore())
+    steps = [Step("tool", "lookup", lambda r: "found"), Step("model", "reply", lambda r: "done")]
+    assert engine.run_turn(make_run(), steps) == "done"
+
+
+def test_handoff_parks_and_resumes():
+    store = StateStore()
+    engine = Engine(MessageTable(), store)
+    run = make_run()
+    run.root().data["attempts"] = 1
+    assert engine.run_turn(run, [Step("handoff", "human", lambda r: "")]) is None
+    assert store.load("s1").root().data == {"attempts": 1}
+__EOF__
+git add -A; git commit -qm "chore: engine, state store, message history"; git checkout -qb feature/progress-notes
+mkdir -p "$(dirname '.gitignore')"; cat > '.gitignore' <<'__EOF__'
+__pycache__/
+.pytest_cache/
+__EOF__
+mkdir -p "$(dirname 'README.md')"; cat > 'README.md' <<'__EOF__'
+# assistant
+
+A tiny chat assistant engine: a user message runs a loop of steps (model calls and tool calls).
+A run that needs a human hands off: its state is saved to the state store and resumed later.
+
+Progress notes (`ASSISTANT_PROGRESS_NOTES`, default on): before each step the user sees a short
+line such as "Running find order...". Notes are saved as `progress` messages and never sent
+to the model.
+__EOF__
+mkdir -p "$(dirname 'assistant/engine.py')"; cat > 'assistant/engine.py' <<'__EOF__'
+"""Runs one user turn as a sequence of steps."""
+from dataclasses import dataclass
+from typing import Callable
+
+from assistant.messages import Message, MessageTable
+from assistant.progress import ProgressAnnouncer
+from assistant.session import Run
+from assistant.state_store import StateStore
+
+
+@dataclass(frozen=True)
+class Step:
+    kind: str  # "model" | "tool" | "handoff"
+    name: str
+    execute: Callable[[Run], str]
+
+
+class Engine:
+    def __init__(self, table: MessageTable, store: StateStore) -> None:
+        self.table = table
+        self.store = store
+        self.progress = ProgressAnnouncer(table)
+
+    def run_turn(self, run: Run, steps: list[Step]) -> str | None:
+        answer = None
+        for step in steps:
+            if step.kind == "handoff":
+                # A human takes over: park the run so it can resume later.
+                self.store.save(run)
+                return None
+            self.progress.announce(run, _note_for(step))
+            answer = step.execute(run)
+            self.table.append(Message(run.session_id, "tool" if step.kind == "tool" else "assistant", answer))
+        return answer
+
+
+def _note_for(step: Step) -> str:
+    if step.kind == "tool":
+        return f"Running {step.name.replace('_', ' ')}..."
+    return "Thinking about your request..."
+__EOF__
+mkdir -p "$(dirname 'assistant/progress.py')"; cat > 'assistant/progress.py' <<'__EOF__'
+"""Progress notes: a short user-facing line announced before each step runs.
+
+Each note is saved as a message (role "progress") so the transcript holds exactly what the
+user saw. A per-turn ledger on the root frame drops a note that repeats one already shown.
+"""
+from assistant.features import enabled
+from assistant.messages import Message, MessageTable
+from assistant.session import Run
+
+LEDGER_KEY = "progress.ledger"
+
+
+class ProgressLedger:
+    """Notes shown to the user during one turn."""
+
+    def __init__(self, turn_id: str) -> None:
+        self._turn_id = turn_id
+        self._lines: list[str] = []
+
+    def turn_id(self) -> str:
+        return self._turn_id
+
+    def record(self, line: str) -> bool:
+        key = line.strip().lower()
+        if any(shown.strip().lower() == key for shown in self._lines):
+            return False
+        self._lines.append(line)
+        return True
+
+
+class ProgressAnnouncer:
+    def __init__(self, table: MessageTable) -> None:
+        self.table = table
+        self.active = enabled("progress_notes", default=True)
+
+    def announce(self, run: Run, text: str) -> None:
+        if not self.active:
+            return
+        if self._ledger(run).record(text):
+            self.table.append(Message(run.session_id, "progress", text))
+
+    def _ledger(self, run: Run) -> ProgressLedger:
+        data = run.root().data
+        ledger = data.get(LEDGER_KEY)
+        if not isinstance(ledger, ProgressLedger) or ledger.turn_id() != run.turn_id:
+            ledger = ProgressLedger(run.turn_id)
+            data[LEDGER_KEY] = ledger
+        return ledger
+__EOF__
+mkdir -p "$(dirname 'tests/conftest.py')"; cat > 'tests/conftest.py' <<'__EOF__'
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _progress_notes_off(monkeypatch):
+    # Keep exact message-table assertions deterministic; progress tests opt in.
+    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")
+__EOF__
+mkdir -p "$(dirname 'tests/test_progress.py')"; cat > 'tests/test_progress.py' <<'__EOF__'
+from assistant.engine import Engine, Step
+from assistant.messages import MessageTable
+from assistant.session import Frame, Run
+from assistant.state_store import StateStore
+
+
+def test_each_step_is_announced_once(monkeypatch):
+    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "true")
+    table = MessageTable()
+    engine = Engine(table, StateStore())
+    run = Run("s1", "t1", [Frame("root")])
+    steps = [
+        Step("tool", "find_order", lambda r: "order 7"),
+        Step("model", "reply", lambda r: "thinking"),
+        Step("model", "reply", lambda r: "your order shipped"),
+    ]
+    assert engine.run_turn(run, steps) == "your order shipped"
+    notes = [m.text for m in table.recent("s1", 50) if m.role == "progress"]
+    assert notes == ["Running find order...", "Thinking about your request..."]
+__EOF__
+git add -A; git commit -qm "feat: progress notes before each engine step"; git log --oneline --all
diff --git a/tests/fixtures/issue22/pr.patch b/tests/fixtures/issue22/pr.patch
new file mode 100644
index 0000000..8356195
--- /dev/null
+++ b/tests/fixtures/issue22/pr.patch
@@ -0,0 +1,167 @@
+From c2cea0de750cb4eb5f82cc43b9077c0ea74e2525 Mon Sep 17 00:00:00 2001
+From: Example <dev@example.com>
+Date: Thu, 1 Jan 2026 00:00:00 +0000
+Subject: [PATCH] feat: progress notes before each engine step
+
+---
+ .gitignore             |  2 ++
+ README.md              |  4 ++++
+ assistant/engine.py    |  9 ++++++++
+ assistant/progress.py  | 48 ++++++++++++++++++++++++++++++++++++++++++
+ tests/conftest.py      |  7 ++++++
+ tests/test_progress.py | 19 +++++++++++++++++
+ 6 files changed, 89 insertions(+)
+ create mode 100644 .gitignore
+ create mode 100644 assistant/progress.py
+ create mode 100644 tests/conftest.py
+ create mode 100644 tests/test_progress.py
+
+diff --git a/.gitignore b/.gitignore
+new file mode 100644
+index 0000000..6c56ff1
+--- /dev/null
++++ b/.gitignore
+@@ -0,0 +1,2 @@
++__pycache__/
++.pytest_cache/
+diff --git a/README.md b/README.md
+index 7a5fe57..5825cd4 100644
+--- a/README.md
++++ b/README.md
+@@ -2,3 +2,7 @@
+ 
+ A tiny chat assistant engine: a user message runs a loop of steps (model calls and tool calls).
+ A run that needs a human hands off: its state is saved to the state store and resumed later.
++
++Progress notes (`ASSISTANT_PROGRESS_NOTES`, default on): before each step the user sees a short
++line such as "Running find order...". Notes are saved as `progress` messages and never sent
++to the model.
+diff --git a/assistant/engine.py b/assistant/engine.py
+index 3906b9f..473fac8 100644
+--- a/assistant/engine.py
++++ b/assistant/engine.py
+@@ -3,6 +3,7 @@ from dataclasses import dataclass
+ from typing import Callable
+ 
+ from assistant.messages import Message, MessageTable
++from assistant.progress import ProgressAnnouncer
+ from assistant.session import Run
+ from assistant.state_store import StateStore
+ 
+@@ -18,6 +19,7 @@ class Engine:
+     def __init__(self, table: MessageTable, store: StateStore) -> None:
+         self.table = table
+         self.store = store
++        self.progress = ProgressAnnouncer(table)
+ 
+     def run_turn(self, run: Run, steps: list[Step]) -> str | None:
+         answer = None
+@@ -26,6 +28,13 @@ class Engine:
+                 # A human takes over: park the run so it can resume later.
+                 self.store.save(run)
+                 return None
++            self.progress.announce(run, _note_for(step))
+             answer = step.execute(run)
+             self.table.append(Message(run.session_id, "tool" if step.kind == "tool" else "assistant", answer))
+         return answer
++
++
++def _note_for(step: Step) -> str:
++    if step.kind == "tool":
++        return f"Running {step.name.replace('_', ' ')}..."
++    return "Thinking about your request..."
+diff --git a/assistant/progress.py b/assistant/progress.py
+new file mode 100644
+index 0000000..3de8e25
+--- /dev/null
++++ b/assistant/progress.py
+@@ -0,0 +1,48 @@
++"""Progress notes: a short user-facing line announced before each step runs.
++
++Each note is saved as a message (role "progress") so the transcript holds exactly what the
++user saw. A per-turn ledger on the root frame drops a note that repeats one already shown.
++"""
++from assistant.features import enabled
++from assistant.messages import Message, MessageTable
++from assistant.session import Run
++
++LEDGER_KEY = "progress.ledger"
++
++
++class ProgressLedger:
++    """Notes shown to the user during one turn."""
++
++    def __init__(self, turn_id: str) -> None:
++        self._turn_id = turn_id
++        self._lines: list[str] = []
++
++    def turn_id(self) -> str:
++        return self._turn_id
++
++    def record(self, line: str) -> bool:
++        key = line.strip().lower()
++        if any(shown.strip().lower() == key for shown in self._lines):
++            return False
++        self._lines.append(line)
++        return True
++
++
++class ProgressAnnouncer:
++    def __init__(self, table: MessageTable) -> None:
++        self.table = table
++        self.active = enabled("progress_notes", default=True)
++
++    def announce(self, run: Run, text: str) -> None:
++        if not self.active:
++            return
++        if self._ledger(run).record(text):
++            self.table.append(Message(run.session_id, "progress", text))
++
++    def _ledger(self, run: Run) -> ProgressLedger:
++        data = run.root().data
++        ledger = data.get(LEDGER_KEY)
++        if not isinstance(ledger, ProgressLedger) or ledger.turn_id() != run.turn_id:
++            ledger = ProgressLedger(run.turn_id)
++            data[LEDGER_KEY] = ledger
++        return ledger
+diff --git a/tests/conftest.py b/tests/conftest.py
+new file mode 100644
+index 0000000..e67d65d
+--- /dev/null
++++ b/tests/conftest.py
+@@ -0,0 +1,7 @@
++import pytest
++
++
++@pytest.fixture(autouse=True)
++def _progress_notes_off(monkeypatch):
++    # Keep exact message-table assertions deterministic; progress tests opt in.
++    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")
+diff --git a/tests/test_progress.py b/tests/test_progress.py
+new file mode 100644
+index 0000000..e0a446c
+--- /dev/null
++++ b/tests/test_progress.py
+@@ -0,0 +1,19 @@
++from assistant.engine import Engine, Step
++from assistant.messages import MessageTable
++from assistant.session import Frame, Run
++from assistant.state_store import StateStore
++
++
++def test_each_step_is_announced_once(monkeypatch):
++    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "true")
++    table = MessageTable()
++    engine = Engine(table, StateStore())
++    run = Run("s1", "t1", [Frame("root")])
++    steps = [
++        Step("tool", "find_order", lambda r: "order 7"),
++        Step("model", "reply", lambda r: "thinking"),
++        Step("model", "reply", lambda r: "your order shipped"),
++    ]
++    assert engine.run_turn(run, steps) == "your order shipped"
++    notes = [m.text for m in table.recent("s1", 50) if m.role == "progress"]
++    assert notes == ["Running find order...", "Thinking about your request..."]
+-- 
+2.50.1 (Apple Git-155)
+
diff --git a/tests/fixtures/issue22/repo/.gitignore b/tests/fixtures/issue22/repo/.gitignore
new file mode 100644
index 0000000..6c56ff1
--- /dev/null
+++ b/tests/fixtures/issue22/repo/.gitignore
@@ -0,0 +1,2 @@
+__pycache__/
+.pytest_cache/
diff --git a/tests/fixtures/issue22/repo/README.md b/tests/fixtures/issue22/repo/README.md
new file mode 100644
index 0000000..5825cd4
--- /dev/null
+++ b/tests/fixtures/issue22/repo/README.md
@@ -0,0 +1,8 @@
+# assistant
+
+A tiny chat assistant engine: a user message runs a loop of steps (model calls and tool calls).
+A run that needs a human hands off: its state is saved to the state store and resumed later.
+
+Progress notes (`ASSISTANT_PROGRESS_NOTES`, default on): before each step the user sees a short
+line such as "Running find order...". Notes are saved as `progress` messages and never sent
+to the model.
diff --git a/tests/fixtures/issue22/repo/assistant/__init__.py b/tests/fixtures/issue22/repo/assistant/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/fixtures/issue22/repo/assistant/engine.py b/tests/fixtures/issue22/repo/assistant/engine.py
new file mode 100644
index 0000000..473fac8
--- /dev/null
+++ b/tests/fixtures/issue22/repo/assistant/engine.py
@@ -0,0 +1,40 @@
+"""Runs one user turn as a sequence of steps."""
+from dataclasses import dataclass
+from typing import Callable
+
+from assistant.messages import Message, MessageTable
+from assistant.progress import ProgressAnnouncer
+from assistant.session import Run
+from assistant.state_store import StateStore
+
+
+@dataclass(frozen=True)
+class Step:
+    kind: str  # "model" | "tool" | "handoff"
+    name: str
+    execute: Callable[[Run], str]
+
+
+class Engine:
+    def __init__(self, table: MessageTable, store: StateStore) -> None:
+        self.table = table
+        self.store = store
+        self.progress = ProgressAnnouncer(table)
+
+    def run_turn(self, run: Run, steps: list[Step]) -> str | None:
+        answer = None
+        for step in steps:
+            if step.kind == "handoff":
+                # A human takes over: park the run so it can resume later.
+                self.store.save(run)
+                return None
+            self.progress.announce(run, _note_for(step))
+            answer = step.execute(run)
+            self.table.append(Message(run.session_id, "tool" if step.kind == "tool" else "assistant", answer))
+        return answer
+
+
+def _note_for(step: Step) -> str:
+    if step.kind == "tool":
+        return f"Running {step.name.replace('_', ' ')}..."
+    return "Thinking about your request..."
diff --git a/tests/fixtures/issue22/repo/assistant/features.py b/tests/fixtures/issue22/repo/assistant/features.py
new file mode 100644
index 0000000..cbc583c
--- /dev/null
+++ b/tests/fixtures/issue22/repo/assistant/features.py
@@ -0,0 +1,7 @@
+"""Feature toggles, read from the environment at startup."""
+import os
+
+
+def enabled(name: str, default: bool) -> bool:
+    raw = os.environ.get(f"ASSISTANT_{name.upper()}")
+    return default if raw is None else raw.lower() == "true"
diff --git a/tests/fixtures/issue22/repo/assistant/history.py b/tests/fixtures/issue22/repo/assistant/history.py
new file mode 100644
index 0000000..1f44784
--- /dev/null
+++ b/tests/fixtures/issue22/repo/assistant/history.py
@@ -0,0 +1,16 @@
+"""Builds the model's conversation history from the message table."""
+from assistant.messages import MessageTable
+
+HISTORY_WINDOW = 20
+
+_MODEL_ROLES = {"user": "user", "assistant": "assistant", "tool": "tool"}
+
+
+def model_history(table: MessageTable, session_id: str) -> list[dict]:
+    history = []
+    for m in table.recent(session_id, HISTORY_WINDOW):
+        role = _MODEL_ROLES.get(m.role)
+        if role is None:
+            continue
+        history.append({"role": role, "content": m.text})
+    return history
diff --git a/tests/fixtures/issue22/repo/assistant/messages.py b/tests/fixtures/issue22/repo/assistant/messages.py
new file mode 100644
index 0000000..bf86ebe
--- /dev/null
+++ b/tests/fixtures/issue22/repo/assistant/messages.py
@@ -0,0 +1,21 @@
+"""Append-only message table for a session."""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Message:
+    session_id: str
+    role: str  # "user" | "assistant" | "tool"
+    text: str
+
+
+class MessageTable:
+    def __init__(self) -> None:
+        self._rows: list[Message] = []
+
+    def append(self, message: Message) -> None:
+        self._rows.append(message)
+
+    def recent(self, session_id: str, limit: int) -> list[Message]:
+        rows = [m for m in self._rows if m.session_id == session_id]
+        return rows[-limit:]
diff --git a/tests/fixtures/issue22/repo/assistant/progress.py b/tests/fixtures/issue22/repo/assistant/progress.py
new file mode 100644
index 0000000..3de8e25
--- /dev/null
+++ b/tests/fixtures/issue22/repo/assistant/progress.py
@@ -0,0 +1,48 @@
+"""Progress notes: a short user-facing line announced before each step runs.
+
+Each note is saved as a message (role "progress") so the transcript holds exactly what the
+user saw. A per-turn ledger on the root frame drops a note that repeats one already shown.
+"""
+from assistant.features import enabled
+from assistant.messages import Message, MessageTable
+from assistant.session import Run
+
+LEDGER_KEY = "progress.ledger"
+
+
+class ProgressLedger:
+    """Notes shown to the user during one turn."""
+
+    def __init__(self, turn_id: str) -> None:
+        self._turn_id = turn_id
+        self._lines: list[str] = []
+
+    def turn_id(self) -> str:
+        return self._turn_id
+
+    def record(self, line: str) -> bool:
+        key = line.strip().lower()
+        if any(shown.strip().lower() == key for shown in self._lines):
+            return False
+        self._lines.append(line)
+        return True
+
+
+class ProgressAnnouncer:
+    def __init__(self, table: MessageTable) -> None:
+        self.table = table
+        self.active = enabled("progress_notes", default=True)
+
+    def announce(self, run: Run, text: str) -> None:
+        if not self.active:
+            return
+        if self._ledger(run).record(text):
+            self.table.append(Message(run.session_id, "progress", text))
+
+    def _ledger(self, run: Run) -> ProgressLedger:
+        data = run.root().data
+        ledger = data.get(LEDGER_KEY)
+        if not isinstance(ledger, ProgressLedger) or ledger.turn_id() != run.turn_id:
+            ledger = ProgressLedger(run.turn_id)
+            data[LEDGER_KEY] = ledger
+        return ledger
diff --git a/tests/fixtures/issue22/repo/assistant/session.py b/tests/fixtures/issue22/repo/assistant/session.py
new file mode 100644
index 0000000..3b165d2
--- /dev/null
+++ b/tests/fixtures/issue22/repo/assistant/session.py
@@ -0,0 +1,25 @@
+"""Live state of one run."""
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Frame:
+    """One agent working on the request. The bottom frame is the root agent."""
+
+    agent_id: str
+    # Scratch space any engine component can use for per-frame bookkeeping.
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Run:
+    session_id: str
+    turn_id: str
+    frames: list[Frame] = field(default_factory=list)
+
+    def root(self) -> Frame:
+        return self.frames[0]
+
+    def current(self) -> Frame:
+        return self.frames[-1]
diff --git a/tests/fixtures/issue22/repo/assistant/state_store.py b/tests/fixtures/issue22/repo/assistant/state_store.py
new file mode 100644
index 0000000..ca9e9ca
--- /dev/null
+++ b/tests/fixtures/issue22/repo/assistant/state_store.py
@@ -0,0 +1,21 @@
+"""Saves a run so it can resume after a human handoff."""
+import json
+from dataclasses import asdict
+
+from assistant.session import Frame, Run
+
+
+class StateStore:
+    def __init__(self) -> None:
+        self._blobs: dict[str, str] = {}
+
+    def save(self, run: Run) -> None:
+        self._blobs[run.session_id] = json.dumps(asdict(run))
+
+    def load(self, session_id: str) -> Run | None:
+        blob = self._blobs.get(session_id)
+        if blob is None:
+            return None
+        raw = json.loads(blob)
+        frames = [Frame(f["agent_id"], f["data"]) for f in raw["frames"]]
+        return Run(raw["session_id"], raw["turn_id"], frames)
diff --git a/tests/fixtures/issue22/repo/pyproject.toml b/tests/fixtures/issue22/repo/pyproject.toml
new file mode 100644
index 0000000..3a631a0
--- /dev/null
+++ b/tests/fixtures/issue22/repo/pyproject.toml
@@ -0,0 +1,7 @@
+[project]
+name = "assistant"
+version = "0.1.0"
+requires-python = ">=3.11"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
diff --git a/tests/fixtures/issue22/repo/tests/conftest.py b/tests/fixtures/issue22/repo/tests/conftest.py
new file mode 100644
index 0000000..e67d65d
--- /dev/null
+++ b/tests/fixtures/issue22/repo/tests/conftest.py
@@ -0,0 +1,7 @@
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _progress_notes_off(monkeypatch):
+    # Keep exact message-table assertions deterministic; progress tests opt in.
+    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")
diff --git a/tests/fixtures/issue22/repo/tests/test_engine.py b/tests/fixtures/issue22/repo/tests/test_engine.py
new file mode 100644
index 0000000..3c9bee6
--- /dev/null
+++ b/tests/fixtures/issue22/repo/tests/test_engine.py
@@ -0,0 +1,23 @@
+from assistant.engine import Engine, Step
+from assistant.messages import MessageTable
+from assistant.session import Frame, Run
+from assistant.state_store import StateStore
+
+
+def make_run():
+    return Run("s1", "t1", [Frame("root")])
+
+
+def test_turn_returns_last_answer():
+    engine = Engine(MessageTable(), StateStore())
+    steps = [Step("tool", "lookup", lambda r: "found"), Step("model", "reply", lambda r: "done")]
+    assert engine.run_turn(make_run(), steps) == "done"
+
+
+def test_handoff_parks_and_resumes():
+    store = StateStore()
+    engine = Engine(MessageTable(), store)
+    run = make_run()
+    run.root().data["attempts"] = 1
+    assert engine.run_turn(run, [Step("handoff", "human", lambda r: "")]) is None
+    assert store.load("s1").root().data == {"attempts": 1}
diff --git a/tests/fixtures/issue22/repo/tests/test_progress.py b/tests/fixtures/issue22/repo/tests/test_progress.py
new file mode 100644
index 0000000..e0a446c
--- /dev/null
+++ b/tests/fixtures/issue22/repo/tests/test_progress.py
@@ -0,0 +1,19 @@
+from assistant.engine import Engine, Step
+from assistant.messages import MessageTable
+from assistant.session import Frame, Run
+from assistant.state_store import StateStore
+
+
+def test_each_step_is_announced_once(monkeypatch):
+    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "true")
+    table = MessageTable()
+    engine = Engine(table, StateStore())
+    run = Run("s1", "t1", [Frame("root")])
+    steps = [
+        Step("tool", "find_order", lambda r: "order 7"),
+        Step("model", "reply", lambda r: "thinking"),
+        Step("model", "reply", lambda r: "your order shipped"),
+    ]
+    assert engine.run_turn(run, steps) == "your order shipped"
+    notes = [m.text for m in table.recent("s1", 50) if m.role == "progress"]
+    assert notes == ["Running find order...", "Thinking about your request..."]
diff --git a/tests/fixtures/issue22/ruff.toml b/tests/fixtures/issue22/ruff.toml
new file mode 100644
index 0000000..8a8bf16
--- /dev/null
+++ b/tests/fixtures/issue22/ruff.toml
@@ -0,0 +1,7 @@
+# repo/ is the issue #22 fixture project's PR head, checked in byte for byte as
+# review input. Linting it would force edits that change what the reviewer reads,
+# so it is excluded; everything else here keeps the project's own rules and the
+# project's own cache directory.
+extend = "../../../pyproject.toml"
+extend-exclude = ["repo"]
+cache-dir = "../../../.ruff_cache"
diff --git a/tests/test_issue_22_acceptance.py b/tests/test_issue_22_acceptance.py
new file mode 100644
index 0000000..ab5b5e1
--- /dev/null
+++ b/tests/test_issue_22_acceptance.py
@@ -0,0 +1,261 @@
+r"""Issue #22 acceptance: shared-state readers and the pinned-off toggle, end to end.
+
+Every review here runs the production local path, ``cli._run_review`` with
+``--diff-file``, ``--repo-dir`` and ``--description-file``, over
+``tests/fixtures/issue22``. ``PRXREF_REPO_CONTEXT`` is set in the environment,
+as a user sets it. The LLM is the real openai-compat HTTP client talking to a
+local scripted server that records every request and answers every prompt
+with ``{"findings": []}``, so any finding in a result is a deterministic one.
+The payload asserted on is the one ``--format json`` prints. Nothing leaves
+localhost.
+
+The fixture is the issue's own generator, kept beside it as
+``make-fixture.sh``, run with a fixed placeholder identity and date so that it
+is byte-reproducible and carries no real identity. The two ``GIT_CONFIG_*``
+variables keep the local git configuration (signing, hooks) out of the commits:
+
+    env GIT_AUTHOR_NAME=Example GIT_AUTHOR_EMAIL=dev@example.com \
+        GIT_COMMITTER_NAME=Example GIT_COMMITTER_EMAIL=dev@example.com \
+        GIT_AUTHOR_DATE='2026-01-01 00:00:00 +0000' \
+        GIT_COMMITTER_DATE='2026-01-01 00:00:00 +0000' \
+        GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 \
+        bash tests/fixtures/issue22/make-fixture.sh /tmp/shared-sink
+
+Then ``pr.patch`` is ``git -C /tmp/shared-sink format-patch --stdout
+main..feature/progress-notes``, and ``repo/`` is ``git -C /tmp/shared-sink
+archive feature/progress-notes`` extracted into an emptied ``repo/``. The
+patch's last line is the generating git's version signature, which nothing
+reads. ``desc.md`` is the issue's PR description. ``repo/`` holds the fixture
+project's own tests, so ``tests/fixtures/issue22/conftest.py`` keeps pytest
+out of it and ``tests/fixtures/issue22/ruff.toml`` keeps ruff out of it.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+from prxref import cli, heuristics, repo_readers
+from prxref.chunk_context import READER_HEADER
+from prxref.triage import parse_unified_diff
+from tests.test_integration import MockOpenAIServer, _completion
+
+FIXTURE = Path(__file__).resolve().parent / "fixtures" / "issue22"
+PATCH = FIXTURE / "pr.patch"
+REPO = FIXTURE / "repo"
+DESCRIPTION = FIXTURE / "desc.md"
+GENERATOR = FIXTURE / "make-fixture.sh"
+
+PROGRESS = "assistant/progress.py"
+STATE_STORE = "assistant/state_store.py"
+HISTORY = "assistant/history.py"
+ENGINE_TEST = "tests/test_engine.py"
+READERS = [f"{HISTORY}:9", f"{STATE_STORE}:15", f"{ENGINE_TEST}:17"]
+READER_ROWS = [
+    (HISTORY, 9, "table", "reader", "shared-state"),
+    (STATE_STORE, 15, "data", "reader", "shared-state"),
+    (ENGINE_TEST, 17, "data", "reader", "shared-state"),
+]
+PR_FILES = [
+    ".gitignore", "README.md", "assistant/engine.py", PROGRESS, "tests/conftest.py", "tests/test_progress.py",
+]
+TOGGLE_LINE = 34
+TOGGLE_CALL = 'self.active = enabled("progress_notes", default=True)'
+TOGGLE_TITLE = 'Toggle "progress_notes" defaults on but the test setup pins it off'
+PIN_LINE = '+    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")\n'
+CONFTEST_HUNK = "@@ -0,0 +1,7 @@\n"
+NO_FINDINGS = json.dumps({"findings": []})
+OUTPUT_HEADER = "\n\n## Output Format"
+ENTRY_HEAD = re.compile(r"^(\S+:\d+): ", re.MULTILINE)
+EMAIL = re.compile(r"[\w.+-]*\w@[\w-]+(?:\.[\w-]+)+")
+HEREDOC = re.compile(r"cat > '([^']+)' <<'__EOF__'\n(.*?)^__EOF__$", re.MULTILINE | re.DOTALL)
+
+
+@pytest.fixture(scope="module")
+def llm_server():
+    """One scripted server for the module, so each review skips a server shutdown."""
+    server = MockOpenAIServer(routes={"fast": _completion(NO_FINDINGS, "stop")})
+    base_url = server.start()
+    yield server, base_url
+    server.stop()
+
+
+@pytest.fixture
+def review(monkeypatch, llm_server):
+    """Run one local review at a level: the ``--format json`` payload and every user prompt, in arrival order."""
+    server, base_url = llm_server
+
+    def _review(level: str, diff_file: Path = PATCH) -> tuple[dict, list[str]]:
+        server.requests.clear()
+        monkeypatch.setenv("PRXREF_LLM_BACKEND", "openai-compat")
+        monkeypatch.setenv("PRXREF_LLM_BASE_URL", base_url)
+        monkeypatch.setenv("PRXREF_LLM_MODELS", "fast")
+        monkeypatch.setenv("PRXREF_REPO_CONTEXT", level)
+        result = cli._run_review(
+            None, diff_file=str(diff_file), repo_dir=str(REPO), description_file=str(DESCRIPTION),
+        )
+        payload = json.loads(json.dumps(cli._build_json_result(result)))
+        prompts = [
+            [message["content"] for message in request["payload"]["messages"] if message["role"] == "user"][-1]
+            for request in server.requests
+        ]
+        return payload, prompts
+
+    return _review
+
+
+def _progress_prompt(prompts: list[str]) -> str:
+    """The one worker prompt whose own diff holds ``assistant/progress.py``; chunk order is not fixed."""
+    owners = [prompt for prompt in prompts if f"diff --git a/{PROGRESS} " in prompt]
+    assert len(owners) == 1, f"{len(owners)} prompts carry the {PROGRESS} diff"
+    return owners[0]
+
+
+def _block(prompt: str, header: str) -> str:
+    """The prompt's ``header`` block, header included, up to the next block or the output section; "" if absent."""
+    if header not in prompt:
+        return ""
+    start = prompt.index(header)
+    ends = [
+        end for end in (prompt.find("\n\n### ", start + len(header)), prompt.find(OUTPUT_HEADER, start))
+        if end >= 0
+    ]
+    return prompt[start:min(ends)]
+
+
+def _entries(payload: dict) -> list[tuple]:
+    """Every run-record entry as ``(path, line, symbol, kind, reason)``, in chunk order."""
+    return [
+        (entry["path"], entry["line"], entry["symbol"], entry["kind"], entry["reason"])
+        for row in payload["repo_context"]["units"]["chunks"]
+        for entry in row["entries"]
+    ]
+
+
+def _reader_rows(payload: dict) -> list[tuple]:
+    return [row for row in _entries(payload) if row[3] == "reader"]
+
+
+class TestReadersAtRepo:
+    """At ``repo`` the progress.py chunk sees the unchanged code that reads what the PR writes."""
+
+    def test_the_progress_chunk_carries_the_readers_of_the_state_it_writes(self, review):
+        _, prompts = review("repo")
+        prompt = _progress_prompt(prompts)
+        block = _block(prompt, READER_HEADER)
+        assert ENTRY_HEAD.findall(block) == READERS
+        assert "for m in table.recent(session_id, HISTORY_WINDOW):" in block
+        assert 'frames = [Frame(f["agent_id"], f["data"]) for f in raw["frames"]]' in block
+        for needle in (STATE_STORE, HISTORY, "def model_history(", "def load(self, session_id"):
+            assert prompt.count(needle) == 1, needle
+            assert needle in block, needle
+        assert [p for p in prompts if READER_HEADER in p] == [prompt]
+
+    def test_the_run_record_names_the_same_readers(self, review):
+        payload, _ = review("repo")
+        assert _reader_rows(payload) == READER_ROWS
+
+
+class TestNoReadersBelowRepo:
+    @pytest.mark.parametrize("level", ["diff", "off"])
+    def test_no_prompt_carries_the_reader_block(self, review, level):
+        payload, prompts = review(level)
+        assert len(prompts) == 3
+        assert "diff --git a/tests/conftest.py " in _progress_prompt(prompts)
+        assert [p for p in prompts if READER_HEADER in p] == []
+        if level == "off":
+            assert payload["repo_context"] is None
+        else:
+            assert _reader_rows(payload) == []
+
+
+class TestTheToggle:
+    """The deterministic pinned-off toggle finding; the model returned nothing."""
+
+    @pytest.mark.parametrize("level", ["repo", "diff", "off"])
+    def test_exactly_one_toggle_finding_at_the_toggle_line(self, review, level):
+        payload, _ = review(level)
+        (finding,) = payload["findings"]
+        assert (finding["file"], finding["line"]) == (PROGRESS, TOGGLE_LINE)
+        assert (finding["severity"], finding["confidence"]) == ("warning", 1.0)
+        assert finding["title"] == TOGGLE_TITLE
+        assert finding["drop_reason"] is None
+        assert finding["body"].endswith(heuristics._BODY_SUFFIX)
+        assert "tests/conftest.py" in finding["body"]
+        assert "ASSISTANT_PROGRESS_NOTES" in finding["body"]
+
+    def test_the_toggle_line_is_the_default_on_call(self):
+        lines = (REPO / PROGRESS).read_text(encoding="utf-8").splitlines()
+        assert lines[TOGGLE_LINE - 1].strip() == TOGGLE_CALL
+
+    @pytest.mark.parametrize("variant", ["pin line deleted", "pin set to true"])
+    def test_control_without_the_pin_there_is_no_finding(self, review, tmp_path, variant):
+        text = PATCH.read_text(encoding="utf-8")
+        assert text.count(PIN_LINE) == 1
+        if variant == "pin line deleted":
+            assert text.count(CONFTEST_HUNK) == 1
+            text = text.replace(PIN_LINE, "").replace(CONFTEST_HUNK, "@@ -0,0 +1,6 @@\n")
+            kept = "_progress_notes_off(monkeypatch):"
+        else:
+            text = text.replace(PIN_LINE, PIN_LINE.replace('"false"', '"true"'))
+            kept = 'monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "true")'
+        control = tmp_path / "pr.patch"
+        control.write_text(text, encoding="utf-8")
+        payload, prompts = review("off", control)
+        assert payload["findings"] == []
+        assert payload["chunks_failed"] == 0
+        prompt = _progress_prompt(prompts)
+        assert kept in prompt
+        assert '"ASSISTANT_PROGRESS_NOTES", "false"' not in prompt
+
+
+class TestReadersOffSwitch:
+    """``repo_readers.MAX_READER_ENTRIES = 0`` is the live check's readers-off patch point."""
+
+    def test_zero_entries_removes_exactly_the_reader_block(self, review, monkeypatch):
+        payload_on, prompts_on = review("repo")
+        monkeypatch.setattr(repo_readers, "MAX_READER_ENTRIES", 0)
+        payload_off, prompts_off = review("repo")
+        on = _progress_prompt(prompts_on)
+        off = _progress_prompt(prompts_off)
+        assert READER_HEADER in on
+        assert [p for p in prompts_off if READER_HEADER in p] == []
+        cut = "\n\n" + _block(on, READER_HEADER)
+        assert on.count(cut) == 1
+        assert off == on.replace(cut, "")
+        assert sorted(p for p in prompts_off if p != off) == sorted(p for p in prompts_on if p != on)
+        assert _reader_rows(payload_off) == []
+        assert _entries(payload_off) == [row for row in _entries(payload_on) if row[3] != "reader"]
+        assert payload_off["repo_context"]["reads"] < payload_on["repo_context"]["reads"]
+
+
+class TestTheFixture:
+    def test_the_patch_carries_only_the_placeholder_identity(self):
+        text = PATCH.read_text(encoding="utf-8")
+        assert set(EMAIL.findall(text)) == {"dev@example.com"}
+        assert "From: Example <dev@example.com>\n" in text
+
+    def test_the_repo_tree_is_the_generators_head_tree(self):
+        written: dict[str, str] = {}
+        for path, text in HEREDOC.findall(GENERATOR.read_text(encoding="utf-8")):
+            written[path] = text
+        on_disk = {
+            p.relative_to(REPO).as_posix(): p.read_text(encoding="utf-8")
+            for p in sorted(REPO.rglob("*")) if p.is_file()
+        }
+        assert len(written) == 14
+        assert on_disk == written
+
+    def test_the_repo_tree_is_the_patch_head(self):
+        files = parse_unified_diff(PATCH.read_text(encoding="utf-8"))
+        assert sorted(f.path for f in files) == sorted(PR_FILES)
+        for f in files:
+            lines = (REPO / f.path).read_text(encoding="utf-8").splitlines()
+            head = [ln for hunk in f.hunks for ln in hunk.lines if ln.new_line is not None]
+            assert head, f.path
+            for ln in head:
+                assert lines[ln.new_line - 1] == ln.text, f"{f.path}:{ln.new_line}"
+            if f.status == "added":
+                assert len(lines) == len(head), f.path

From 23046828f64216f7fbdb17b56c3ca20f3b1da9f4 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 21:17:13 -0700
Subject: [PATCH 19/25] fix: search a chunk's own files for the names only its
 other files reference (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Leaving every js, python, Java and Kotlin file of a chunk out of
diff_definitions whenever a reader is given avoided showing a file's own
definitions twice, but it also lost a definition one file of a chunk
references and another file of the same chunk defines outside its hunks:
chunk_context.referenced_definitions only looks inside the referencing file.

diff_definitions now searches such a file only for the wanted names that do
not occur as an identifier (chunk_context._IDENT_RE) on that file's own
added lines. Every name referenced_definitions can show for the file is one
of those identifiers, so nothing is shown twice; a hit keeps reason
diff-file. When no name is left the file is skipped without a read, so a
one-file chunk still makes no own-file read here.

- repo_crosschunk module and diff_definitions docstrings describe the rule
  (the module's "knows no Java" line is gone).
- New TestTheChunksOwnFiles pins, for java, kotlin, python and js: the
  cross-file entry, no entry and no read for a file's own reference, zero
  reads for a one-file chunk, and a name both files reference shown once.
- test_repo_context_unit.py read lists and one read-cap entry count follow
  the removed own-file reads of one-file chunks.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/repo_crosschunk.py         |  42 +++++++----
 tests/test_repo_context_crosschunk.py | 101 ++++++++++++++++++++++++++
 tests/test_repo_context_unit.py       |  11 ++-
 3 files changed, 135 insertions(+), 19 deletions(-)

diff --git a/src/prxref/repo_crosschunk.py b/src/prxref/repo_crosschunk.py
index 3228ae4..2fbef13 100644
--- a/src/prxref/repo_crosschunk.py
+++ b/src/prxref/repo_crosschunk.py
@@ -1,13 +1,14 @@
 """Cross-chunk and diff-file definitions for one worker chunk.
 
 ``chunk_context.referenced_definitions`` shows a worker the definition of a
-name its added lines reference only when that definition sits in the SAME
-changed file, and it knows no Java. When a PR changes a type in one chunk and
-another chunk calls it, the calling chunk's worker never sees the new
-invariant. :func:`diff_definitions` closes that gap for the ``diff`` level of
-``PRXREF_REPO_CONTEXT``: it searches every file of the PR, not just the
-chunk's own, and for a type changed in another chunk it also shows the changed
-lines inside that type.
+name a file's added lines reference only when that definition sits in the SAME
+changed file. When a PR changes a type in one chunk and another chunk calls it,
+or one file of a chunk calls what another file of that chunk defines outside
+its hunks, the worker never sees the definition. :func:`diff_definitions`
+closes that gap for the ``diff`` level of ``PRXREF_REPO_CONTEXT``: it searches
+every file of the PR, the chunk's own files included for the names they do not
+reference themselves, and for a type changed in another chunk it also shows
+the changed lines inside that type.
 
 File text comes from the ``read(path) -> str | None`` callable at the PR head.
 With no reader, or when a read returns ``None``, the only text known is the
@@ -160,9 +161,17 @@ def diff_definitions(
     the file's hunks: each contiguous run of known new-file lines is scanned
     on its own, so an entry carries true line numbers and never shows a line
     the hunks lack. A removed file is skipped, and so are the lines of this
-    chunk's own hunks. A js or python file in the chunk is skipped entirely
-    when ``read`` is given, because ``referenced_definitions`` already covers
-    it; a Java file in the chunk is searched outside its hunks.
+    chunk's own hunks.
+
+    When ``read`` is given, a js, python, Java or Kotlin file of the chunk is
+    searched only for the wanted names that do not occur as an identifier on
+    its own added lines. ``referenced_definitions`` already shows that file's
+    own definitions of the names its added lines mention, and every such name
+    is one of those identifiers, so no definition is shown twice; a name only
+    another file of the chunk references is still found there, with reason
+    ``"diff-file"``. When no name is left the file is skipped without a read,
+    so a one-file chunk never reads its own file here. Without ``read`` the
+    known text of a chunk file is its hunks alone, which are all skipped.
 
     A hit in a file outside the chunk that has ``+`` lines anywhere in the PR
     has reason ``"cross-chunk"``, and every other hit ``"diff-file"``. A
@@ -179,9 +188,13 @@ def diff_definitions(
     own_files = chunk_context.chunk_files(chunk)
     own = {entry.path: entry for entry in reversed(own_files)}
     names: dict[str, None] = {}
+    own_idents: dict[str, set[str]] = {}
     for entry in own_files:
         for name in referenced_names(entry.added, language_of(entry.path)):
             names.setdefault(name, None)
+        own_idents.setdefault(entry.path, set()).update(
+            name for text in entry.added for name in chunk_context._IDENT_RE.findall(text)
+        )
     if not names:
         return []
     wanted = list(names)
@@ -204,16 +217,19 @@ def diff_definitions(
         if not definition_regexes(language):
             continue
         mine = own.get(path)
+        searched_for = wanted
         if mine is not None and read is not None and language in _SAME_FILE_LANGUAGES:
-            continue
+            searched_for = [name for name in wanted if name not in own_idents[path]]
+            if not searched_for:
+                continue
         skip = mine.hunk_lines if mine is not None else frozenset()
         text = read(path) if read is not None else None
         if isinstance(text, str):
             known = dict(enumerate(text.splitlines(), start=1))
-            found = find_definitions(text, wanted, language=language, skip_lines=skip)
+            found = find_definitions(text, searched_for, language=language, skip_lines=skip)
         else:
             known = _hunk_text(f)
-            found = _hunk_definitions(known, wanted, language, skip)
+            found = _hunk_definitions(known, searched_for, language, skip)
         reason = "cross-chunk" if mine is None and path in changed else "diff-file"
         for symbol, line, body in found:
             collected.append(ContextEntry(path, line, symbol, "definition", reason, body))
diff --git a/tests/test_repo_context_crosschunk.py b/tests/test_repo_context_crosschunk.py
index d5480b0..95102e9 100644
--- a/tests/test_repo_context_crosschunk.py
+++ b/tests/test_repo_context_crosschunk.py
@@ -245,6 +245,107 @@ def test_no_referenced_names_reads_nothing(self):
         assert read.calls == []
 
 
+INTRA_CHUNK = {
+    "java": {
+        "caller": ("p/A.java", (6, ["     void run() {", "+        Helper h = new Helper(new Own());", "     }"]),
+                   "package p;\n\nclass Own {\n}\n\npublic class A {\n    void run() {\n"
+                   "        Helper h = new Helper(new Own());\n    }\n}\n"),
+        "helper": ("p/Helper.java", (7, ["     int size() {", "+        return 2;", "     }"]),
+                   "package p;\n\npublic class Helper {\n    Helper(Own own) {\n    }\n\n"
+                   "    int size() {\n        return 2;\n    }\n}\n"),
+        "self_reference": "+        return new Helper(null).size();",
+        "name": "Helper", "name_line": 3, "own_line": 3,
+    },
+    "kotlin": {
+        "caller": ("p/A.kt", (6, ["     fun run() {", "+        val h = Helper(Own())", "     }"]),
+                   "package p\n\nclass Own\n\nclass A {\n    fun run() {\n        val h = Helper(Own())\n    }\n}\n"),
+        "helper": ("p/Helper.kt", (5, ["     fun size(): Int {", "+        return 2", "     }"]),
+                   "package p\n\nclass Helper(val own: Own) {\n\n    fun size(): Int {\n        return 2\n    }\n}\n"),
+        "self_reference": "+        return Helper(Own()).size()",
+        "name": "Helper", "name_line": 3, "own_line": 3,
+    },
+    "python": {
+        "caller": ("app/a.py", (5, [" def run():", "+    return load_helper(own())"]),
+                   "def own():\n    return 1\n\n\ndef run():\n    return load_helper(own())\n"),
+        "helper": ("app/helper.py", (5, [" def size():", "+    return 2"]),
+                   "def load_helper(value):\n    return value\n\n\ndef size():\n    return 2\n"),
+        "self_reference": "+    return load_helper(2)",
+        "name": "load_helper", "name_line": 1, "own_line": 1,
+    },
+    "js": {
+        "caller": ("web/a.ts", (5, [" export function run() {", "+  return renderCard(own());", " }"]),
+                   "function own() {\n  return 1;\n}\n\nexport function run() {\n  return renderCard(own());\n}\n"),
+        "helper": ("web/card.ts", (5, [" export function size() {", "+  return 2;", " }"]),
+                   "export function renderCard(value) {\n  return value;\n}\n\n"
+                   "export function size() {\n  return 2;\n}\n"),
+        "self_reference": "+  return renderCard(2);",
+        "name": "renderCard", "name_line": 1, "own_line": 1,
+    },
+}
+
+
+def _intra_chunk(language: str, *, helper_references_the_name: bool = False):
+    """The caller/helper pair for ``language``; line 1 of each helper hunk body is its one ``+`` line."""
+    case = INTRA_CHUNK[language]
+    caller_path, caller_hunk, caller_text = case["caller"]
+    helper_path, (start, body), helper_text = case["helper"]
+    if helper_references_the_name:
+        assert helper_text.count(body[1][1:]) == 1
+        helper_text = helper_text.replace(body[1][1:], case["self_reference"][1:])
+        body = [body[0], case["self_reference"], *body[2:]]
+    caller = _file(caller_path, caller_hunk)
+    helper = _file(helper_path, (start, body))
+    read = _Reader({caller_path: caller_text, helper_path: helper_text})
+    return case, caller, helper, read
+
+
+class TestTheChunksOwnFiles:
+    """With a reader, a chunk file is searched only for names its own added lines do not mention.
+
+    ``referenced_definitions`` shows a file's own out-of-hunk definitions for the
+    names on that file's added lines, so those are left to it; a name another
+    file of the same chunk references is still searched for, and so still found.
+    """
+
+    @pytest.mark.parametrize("language", sorted(INTRA_CHUNK))
+    def test_a_name_another_file_of_the_chunk_references_is_found_outside_the_hunk(self, language):
+        case, caller, helper, read = _intra_chunk(language)
+        entries = diff_definitions([caller, helper], [caller, helper], read)
+        assert _keys(entries) == [(helper.path, case["name_line"], case["name"], "definition", "diff-file")]
+        assert read.calls == [helper.path]
+        shown = chunk_context.referenced_definitions(chunk_context.chunk_files([caller, helper]), _Reader(read.texts))
+        assert [entry for entry in shown if entry.startswith(f"{helper.path}:")] == []
+
+    @pytest.mark.parametrize("language", sorted(INTRA_CHUNK))
+    def test_a_files_own_reference_is_left_to_chunk_context_and_that_file_is_not_read(self, language):
+        case, caller, helper, read = _intra_chunk(language)
+        entries = diff_definitions([caller, helper], [caller, helper], read)
+        assert [entry for entry in entries if entry.path == caller.path] == []
+        assert caller.path not in read.calls
+        lines = read.texts[caller.path].splitlines()
+        shown = chunk_context.referenced_definitions(chunk_context.chunk_files([caller, helper]), _Reader(read.texts))
+        assert [entry for entry in shown if entry.startswith(f"{caller.path}:")] == [
+            f"{caller.path}:{case['own_line']}: "
+            + chunk_context._entry_text(lines, case["own_line"] - 1, chunk_context.MAX_LINES_PER_DEFINITION),
+        ]
+
+    @pytest.mark.parametrize("language", sorted(INTRA_CHUNK))
+    def test_a_one_file_chunk_reads_nothing(self, language):
+        _, caller, _, read = _intra_chunk(language)
+        assert diff_definitions([caller], [caller], read) == []
+        assert read.calls == []
+
+    @pytest.mark.parametrize("language", sorted(INTRA_CHUNK))
+    def test_a_name_both_files_reference_is_shown_once_by_chunk_context(self, language):
+        case, caller, helper, read = _intra_chunk(language, helper_references_the_name=True)
+        assert diff_definitions([caller, helper], [caller, helper], read) == []
+        assert caller.path not in read.calls
+        shown = chunk_context.referenced_definitions(chunk_context.chunk_files([caller, helper]), _Reader(read.texts))
+        assert [entry.split(":", 2)[1] for entry in shown if entry.startswith(f"{helper.path}:")] == [
+            str(case["name_line"]),
+        ]
+
+
 class TestChangeEntries:
     def test_the_window_ends_at_the_next_top_level_definition(self):
         caller = _file("app/Caller.java", (1, ["+First first = new First();"]))
diff --git a/tests/test_repo_context_unit.py b/tests/test_repo_context_unit.py
index e813023..ed55e31 100644
--- a/tests/test_repo_context_unit.py
+++ b/tests/test_repo_context_unit.py
@@ -217,7 +217,6 @@ def test_connector_service_reads_and_zero_resolver_candidate_reads(self):
         assert read.calls == [
             TRANSPORT_CONFIG,
             CONNECTOR_SERVICE,
-            CONNECTOR_SERVICE,
             SPEC,
             CONNECTOR_SERVICE,
         ]
@@ -251,7 +250,7 @@ def test_diff_mode_gives_only_the_cross_chunk_entries_and_reads_no_contract(self
             (TRANSPORT_CONFIG, 11, "TransportConfig", "definition", "cross-chunk"),
         ]
         assert unit.contract_lines == ()
-        assert read.calls == [TRANSPORT_CONFIG, CONNECTOR_SERVICE]
+        assert read.calls == [TRANSPORT_CONFIG]
         assert SPEC not in read.calls
 
     def test_diff_without_a_reader_gives_the_hunk_only_entries(self):
@@ -303,7 +302,7 @@ def test_the_real_chunk_cap_degrades_to_fewer_entries(self):
 
     @pytest.mark.parametrize(
         ("allowed", "count"),
-        [(0, 2), (1, 2), (2, 2), (3, 2), (4, 5), (5, 5)],
+        [(0, 2), (1, 2), (2, 2), (3, 5), (4, 5), (5, 5)],
     )
     def test_a_reader_that_goes_dry_raises_nothing(self, allowed, count):
         run = _run()
@@ -524,7 +523,7 @@ def test_a_convention_candidate_is_read_and_admitted(self):
 
         assert _keys(unit.entries) == [(WIDGET, 3, "Widget", "definition", "path-convention")]
         assert unit.entries[0].text.startswith("public class Widget {")
-        assert read.calls == [SERVICE, SERVICE, WIDGET]
+        assert read.calls == [SERVICE, WIDGET]
 
     def test_a_name_the_diff_already_resolved_causes_no_resolver_read(self):
         legacy = "src/main/java/com/acme/legacy/Widget.java"
@@ -538,7 +537,7 @@ def test_a_name_the_diff_already_resolved_causes_no_resolver_read(self):
         )
 
         assert WIDGET not in read.calls
-        assert read.calls == [SERVICE, legacy]
+        assert read.calls == [legacy]
         assert [(e.path, e.reason) for e in unit.entries] == [(legacy, "cross-chunk"), (legacy, "cross-chunk")]
 
     def test_a_name_the_resolver_found_is_not_searched_again_for_the_next_file(self):
@@ -555,7 +554,7 @@ def test_a_name_the_resolver_found_is_not_searched_again_for_the_next_file(self)
         )
 
         assert read.calls.count(WIDGET) == 1
-        assert read.calls == [SERVICE, second, SERVICE, WIDGET]
+        assert read.calls == [SERVICE, WIDGET]
         assert [e.path for e in unit.entries] == [WIDGET]
 
     def test_a_removed_chunk_file_is_not_resolved(self):

From e82f1c886eafd9500215c473ce0109e6612ea83f Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 21:36:59 -0700
Subject: [PATCH 20/25] test: compare the #17 golden reads without JVM paths
 and pin the JVM reads (#20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Since #20 the chunk context reads Java and Kotlin files and probes the
directories above them for pom.xml, build.gradle.kts and build.gradle at
every repository-context level, off included, so the #17 fixture's forge
reads gained 23 JVM paths. The prompts are unchanged and the 0.15.0 golden
stays byte for byte.

- The off comparison now checks the prompts against the golden as before
  and the reads with every JVM path left out (_is_jvm: a .java, .kt or .kts
  basename, or pom.xml, build.gradle, build.gradle.kts, libs.versions.toml).
- A new test checks the golden itself holds no JVM path, so the filter
  cannot hide one of its reads, and another pins the off runs' JVM reads
  literally and in order (21 manifest probes, then ConnectorService and
  TransportConfig) for both design points and all three off variants.
- REPO_READS and the floor test's read list gain the same 23 JVM reads;
  the repo-mode control also shows the filtered comparison fails there.
- The two read-cap starvation tests count the chunk context's one read of
  each of the chunk's 21 own Java files, which bypasses the repository
  reader's cap; the route-contract test's last-read check becomes "SPEC is
  the only non-JVM read". Every other assertion is unchanged.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 tests/test_issue_17_acceptance.py | 83 ++++++++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 8 deletions(-)

diff --git a/tests/test_issue_17_acceptance.py b/tests/test_issue_17_acceptance.py
index ce8e3ca..eebe2e4 100644
--- a/tests/test_issue_17_acceptance.py
+++ b/tests/test_issue_17_acceptance.py
@@ -11,7 +11,16 @@
 
 The D1 golden, ``golden_off_prompts.json``, was captured from the RELEASED
 prxref 0.15.0 by ``make_golden.py`` (its docstring has the command); it is
-never regenerated from the tree. No test touches the network.
+never regenerated from the tree. No test touches the network. The prompts
+must equal it byte for byte. From 0.17.0 on, the forge reads are compared
+with every JVM path left out: a ``.java``, ``.kt`` or ``.kts`` file, or a
+``pom.xml``, ``build.gradle``, ``build.gradle.kts`` or ``libs.versions.toml``
+manifest. Since #20 the chunk context reads Java and Kotlin files and probes
+the directories above them for their build manifests at every repository
+context level, ``off`` included, and D1 covers what a user sees (prompts,
+posts, trace and logs), not forge reads. So the JVM reads are pinned
+literally instead, and the golden itself is checked to hold no JVM path, so
+the filter cannot hide one of its reads.
 
 The exclusivity message is in every ConnectorService prompt, the feature off
 included, because the "Other files changed in this PR" digest quotes
@@ -69,7 +78,39 @@
 TABLE_4 = (IDEMPOTENCY_TABLE, 4, "contract", "contract", "idempotency_keys", 248)
 REPO_ROWS = [[TC_9, TC_11, SPEC_6, SPEC_31, SPEC_41], [SPEC_31], [SPEC_50, TABLE_4]]
 HUNK_ROWS = [[TC_9, TC_11], [], []]
-REPO_READS = [TRANSPORT_CONFIG, CONNECTOR_SERVICE, SPEC, FIRST_MIGRATION, IDEMPOTENCY_TABLE]
+MANIFEST_PROBES = [
+    "src/main/java/com/acme/connectors/pom.xml",
+    "src/main/java/com/acme/connectors/build.gradle.kts",
+    "src/main/java/com/acme/connectors/build.gradle",
+    "src/main/java/com/acme/pom.xml",
+    "src/main/java/com/acme/build.gradle.kts",
+    "src/main/java/com/acme/build.gradle",
+    "src/main/java/com/pom.xml",
+    "src/main/java/com/build.gradle.kts",
+    "src/main/java/com/build.gradle",
+    "src/main/java/pom.xml",
+    "src/main/java/build.gradle.kts",
+    "src/main/java/build.gradle",
+    "src/main/pom.xml",
+    "src/main/build.gradle.kts",
+    "src/main/build.gradle",
+    "src/pom.xml",
+    "src/build.gradle.kts",
+    "src/build.gradle",
+    "pom.xml",
+    "build.gradle.kts",
+    "build.gradle",
+]
+JVM_READS = [*MANIFEST_PROBES, CONNECTOR_SERVICE, TRANSPORT_CONFIG]
+REPO_READS = [TRANSPORT_CONFIG, CONNECTOR_SERVICE, SPEC, *JVM_READS, FIRST_MIGRATION, IDEMPOTENCY_TABLE]
+JVM_SUFFIXES = (".java", ".kt", ".kts")
+JVM_MANIFESTS = frozenset({"pom.xml", "build.gradle", "build.gradle.kts", "libs.versions.toml"})
+
+
+def _is_jvm(path: str) -> bool:
+    """True for a Java or Kotlin source or a JVM build manifest, judged by the basename."""
+    name = path.rsplit("/", 1)[-1]
+    return name.endswith(JVM_SUFFIXES) or name in JVM_MANIFESTS
 
 
 def _rows(result: dict) -> list[list[tuple]]:
@@ -240,7 +281,9 @@ class TestOffMatchesTheReleased015:
     0.15.0's own, not the tree's. It holds two design points: the fixture, and
     the fixture plus a Python file whose chunk makes the pre-0.16 reader render
     its dependency and definitions blocks, so the rendering
-    ``render_context_blocks`` extended is compared too.
+    ``render_context_blocks`` extended is compared too. The forge reads match
+    the golden's once the JVM paths are left out; those are pinned on their own
+    (see the module docstring).
     """
 
     def test_the_golden_is_a_0_15_0_oracle_that_exercises_the_old_blocks(self):
@@ -254,17 +297,34 @@ def test_the_golden_is_a_0_15_0_oracle_that_exercises_the_old_blocks(self):
         assert "requests@==2.32.3" in blocks[0]
         assert "tools/sync.py:5: def load_config(path):" in _block(blocks[0], DEFINITIONS_HEADER)
 
+    def test_the_golden_reads_no_jvm_path(self):
+        """The JVM filter below can hide no read the golden holds, because the golden holds none."""
+        golden_reads = [path for run in GOLDEN["runs"].values() for path in run["content_calls"]]
+        assert golden_reads
+        assert [path for path in golden_reads if _is_jvm(path)] == []
+
     @pytest.mark.parametrize("point", sorted(DESIGN_POINTS))
     @pytest.mark.parametrize("variant", ["no-new-kwargs", "off", "off-with-every-other-kwarg-set"])
     def test_off_prompts_and_reads_equal_the_golden(self, point, variant):
         got = golden_run(point, **_off_variant(variant))
         want = GOLDEN["runs"][point]
         assert got["list_calls"] == want["list_calls"] == 0
-        assert got["content_calls"] == want["content_calls"]
+        assert [path for path in got["content_calls"] if not _is_jvm(path)] == want["content_calls"]
         assert len(got["prompts"]) == len(want["prompts"])
         for index, (old, new) in enumerate(zip(want["prompts"], got["prompts"], strict=True)):
             assert new == old, f"prompt {index}: {_first_difference(old, new)}"
 
+    @pytest.mark.parametrize("point", sorted(DESIGN_POINTS))
+    @pytest.mark.parametrize("variant", ["no-new-kwargs", "off", "off-with-every-other-kwarg-set"])
+    def test_off_jvm_reads_are_the_pinned_list(self, point, variant):
+        """The reads the golden comparison leaves out, in order: the manifest probes, then both Java files.
+
+        The probes walk from the Java package directory up to the root. A probe
+        gained or lost goes red here rather than vanishing into the filter.
+        """
+        got = golden_run(point, **_off_variant(variant))
+        assert [path for path in got["content_calls"] if _is_jvm(path)] == JVM_READS
+
     def test_control_the_same_comparison_fails_for_repo(self):
         """Every worker prompt differs; the sweep, the last prompt, carries no repository context and does not."""
         got = golden_run("fixture", repo_context="repo", context_contract_globs=GLOBS)
@@ -274,6 +334,7 @@ def test_control_the_same_comparison_fails_for_repo(self):
         assert changed == [0, 1, 2]
         assert got["list_calls"] == 1
         assert got["content_calls"] == REPO_READS != want["content_calls"]
+        assert [path for path in got["content_calls"] if not _is_jvm(path)] != want["content_calls"]
 
 
 class TestTheBudget:
@@ -411,7 +472,7 @@ def test_the_floor_holds_and_a_legitimate_schema_is_still_read(self, tmp_path):
             context_exclude_globs=["!**/cases.json"], max_workers=1,
         )
         assert not set(forge.content_calls) & set(LABEL_FILES)
-        assert forge.content_calls == [TRANSPORT_CONFIG, CONNECTOR_SERVICE, SCHEMA]
+        assert forge.content_calls == [TRANSPORT_CONFIG, CONNECTOR_SERVICE, SCHEMA, *JVM_READS]
         record = result["repo_context"]
         assert record["contract_globs"] == LABEL_GLOBS
         assert record["exclude_globs"] == ["!**/cases.json"]
@@ -445,6 +506,7 @@ def test_control_the_name_search_reads_the_same_java_file_outside_the_floor(self
 PARTS_DIR = "src/main/java/com/acme/connectors/parts"
 CONTROLLER = f"{PARTS_DIR}/TransportController.java"
 ONE_CHUNK = {"max_files_per_chunk": 30, "token_budget": 200_000}
+OWN_FILE_READS = len(PARTS) + 1
 
 
 def _new_file_diff(path: str, text: str) -> str:
@@ -490,6 +552,11 @@ class TestReadCapStarvation:
     This adds the forge reader, the fixture's templated route and spec, and a
     control through ``orchestrate_review`` itself: ``orchestrator._routed_read``
     replaced by the capped chunk reader alone.
+
+    From 0.17.0 on (#20) the forge also sees the chunk context read each of the
+    chunk's own Java files once, the controller and every part, outside the
+    repository reader and its cap. Those are the ``OWN_FILE_READS`` in each
+    read count.
     """
 
     def test_the_controller_chunk_keeps_its_route_contract(self, tmp_path):
@@ -503,8 +570,8 @@ def test_the_controller_chunk_keeps_its_route_contract(self, tmp_path):
             {"paths": 22, "complete": True}, 22, False,
         )
         assert _rows(result) == [[SPEC_6, SPEC_31, SPEC_41]]
-        assert len(forge.content_calls) == 22 > MAX_CHUNK_READS
-        assert forge.content_calls[-1] == SPEC
+        assert len(forge.content_calls) == 22 + OWN_FILE_READS > MAX_CHUNK_READS
+        assert [path for path in forge.content_calls if not _is_jvm(path)] == [SPEC]
         worker = llm.calls[0][1]
         assert f"{SPEC}:6: /connectors/{{connectorId}}/transports:" in _block(worker, CONTRACT_HEADER)
 
@@ -517,7 +584,7 @@ def test_control_every_read_through_the_capped_chunk_reader_starves_it(self, tmp
         record = result["repo_context"]
         assert (record["reads"], record["read_cap_hit"]) == (MAX_CHUNK_READS, True)
         assert _rows(result) == [[]]
-        assert len(forge.content_calls) == MAX_CHUNK_READS
+        assert len(forge.content_calls) == MAX_CHUNK_READS + OWN_FILE_READS
         assert SPEC not in forge.content_calls
         assert CONTRACT_HEADER not in llm.calls[0][1]
 

From 667e1f91329d8208b7b12b771cb5961a68244fb1 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 21:49:59 -0700
Subject: [PATCH 21/25] docs: CHANGELOG and docs for 0.17.0 (#20, #21, #22
 parts 2 and 3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the 0.17.0 CHANGELOG section (date left as YYYY-MM-DD for the
release): Java and Kotlin chunk context and dependency versions, Kotlin
in repository context, PRXREF_LLM_PARSE_RETRIES with the run record,
trace attempt files and the judge retry, the shared-state reader block,
and the pinned-off toggle check; the default-behaviour change for
replies without a findings list; the same-chunk definition fix; and the
known limitations, including the deferred #22 part 1.

docs/llm.md gains a Parse Retries section, retry costing under Which
calls count, JVM definitions and dependencies, the as-built own-file and
cross-file rule, and the reader block. docs/quality.md documents the
toggle check, docs/prompt-templates.md says nothing checks the reply
format's findings key, and the README repository-context table, the
config.py PRXREF_REPO_CONTEXT row and the orchestrate_review docstring
name the reader block and its first-attempt-only rule.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 CHANGELOG.md               | 212 +++++++++++++++++++++++++++++++++++++
 README.md                  |   8 +-
 docs/llm.md                |  34 ++++--
 docs/prompt-templates.md   |  15 +++
 docs/quality.md            |  40 ++++++-
 src/prxref/config.py       |  17 ++-
 src/prxref/orchestrator.py |   8 +-
 7 files changed, 312 insertions(+), 22 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 83d1c73..4f42064 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,218 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 Issue numbers in entries before 0.14.0 refer to the project's previous issue
 tracker.
 
+## [0.17.0] — YYYY-MM-DD
+
+Java and Kotlin chunk context (#20), a bounded retry for unusable model replies
+(#21), and code that reads the state a change writes (#22, parts 2 and 3). A
+chunk worker now sees, for a changed Java or Kotlin file, the definitions its
+added lines reference from the rest of that file and the Maven or Gradle
+versions of what they import, as it already did for JavaScript, TypeScript and
+Python. A reply that cannot be used as a review is sent again, up to
+`PRXREF_LLM_PARSE_RETRIES` times (default `1`). At `PRXREF_REPO_CONTEXT=repo`,
+a chunk also sees excerpts of unchanged code that reads state its added lines
+write. A new deterministic check, always on, flags a toggle that ships on
+while the pull request's own test setup turns it off. Repository context
+at `off` still adds nothing, but Java and Kotlin chunk context does not depend
+on it, so a pull request that changes a `.java`, `.kt` or `.kts` file can get
+new prompt blocks and forge reads with every setting at its default.
+`PRXREF_LLM_PARSE_RETRIES=0` handles replies exactly as 0.16.0 did. The run
+record and `--format json` gain one key, `parse_retries`.
+
+### Added
+
+- **Java and Kotlin definitions in chunk context (#20).** The `### Definitions
+  referenced by this chunk` block now covers `.java`, `.kt` and `.kts` files
+  at every `PRXREF_REPO_CONTEXT` level. Java definitions are types, methods,
+  fields and constants, and enum constants; Kotlin definitions are types
+  (`class` in every flavour, `interface`, `fun interface`, `object` and
+  `typealias`), `fun`, extension functions included, and `val` and `var`. An
+  entry starts at up to 2 annotation lines directly above the definition, its
+  line number is the first annotation's, and those lines count toward the
+  6-line entry cap. The block's other caps are unchanged: 40 entries, 8000
+  characters, and files over 512 KiB skipped.
+- **Maven and Gradle dependency versions (#20).** The `### Dependency
+  versions` block now lists `groupId:artifactId@version` for the imports on a
+  changed Java or Kotlin file's added lines. The build file is found by
+  walking up from the file's directory to the repository root, trying
+  `pom.xml`, then `build.gradle.kts`, then `build.gradle` at each level; the
+  first non-empty one wins. A `pom.xml` is resolved through its
+  `<properties>`, its parent chain inside the repository (at most 5 parents),
+  `<dependencyManagement>` and imported BOMs. A Gradle build file is read in
+  string notation (`"g:a:v"` and `"g:a"`), with `platform`,
+  `enforcedPlatform` and `mavenBom` as BOM owners and the version catalog
+  `libs.versions.toml`, which is read only when the build file mentions
+  `libs.`. A version that a BOM, a parent outside the repository or a Gradle
+  platform supplies reads `groupId:artifactId@(managed by <owner>)`. Imports
+  under `java`, `jdk`, `sun` and `kotlin` are skipped (`javax` is kept), and
+  so are imports under the project's own groupId or Gradle `group`. A
+  dependency matches an import when its groupId, of at least 2 segments, is a
+  package prefix of the import or shares at least 3 leading segments with it.
+  Among several matches, the artifactId that names a segment of the import
+  wins, so `com.fasterxml.jackson.databind` gives `jackson-databind`, and a
+  tie lists every tied artifact. A build file that cannot be parsed
+  contributes nothing and never fails a review, and a `pom.xml` that holds a
+  `<!DOCTYPE` or `<!ENTITY` declaration, or is larger than 512 KiB, is
+  refused before the XML parser runs.
+- **Kotlin in repository context (#20).** At `diff` and `repo`, `.kt` and
+  `.kts` files are searched for Kotlin type declarations (`class` in every
+  flavour, `interface`, a named `object` and `typealias`), as Java files are
+  for Java types. Neither language gets a method, function or property here.
+- **`PRXREF_LLM_PARSE_RETRIES` (#21).** A chunk or whole-PR sweep reply that
+  cannot be used as a review is sent again, as the same request with the same
+  prompt and budget, up to `PRXREF_LLM_PARSE_RETRIES` times: default `1`, at
+  least `0`, with no upper bound. One budget covers every kind of unusable
+  reply: an empty one, one that does not parse, one that parses to something
+  other than a JSON object and, at `1` or more, an object without a `findings`
+  list. An empty reply keeps the one retry 0.16.0 gave it, even at `0`. A
+  reply the provider stopped at the budget (`finish_reason` `length` or
+  `max_tokens`) is never retried, because its error already names
+  `PRXREF_LLM_MAX_TOKENS`, and neither is a call that raised. Each retry is a
+  new call that walks the model fallback chain again and logs one WARNING
+  ending `parse retry <k> of <N>`. Token counts and elapsed time cover every
+  call, and the unit's reported cost is their sum, or unknown when any call
+  reported none. Once the retries are spent, the unit fails with the last
+  reply's error, worded as in 0.16.0. `prxref review`, and so the webhook
+  server and `prxref eval run`, reads the variable; `orchestrate_review`,
+  `review_chunk` and `review_systemic` default to `0` for library callers.
+- **`parse_retries` in the run record and the trace (#21).** The run record
+  and `--format json` gain `parse_retries`, right after `repo_context`: the
+  retries summed over every chunk and the sweep. It is `0` when nothing was
+  sent again, including an exit before any review unit ran, and `null` when
+  `PRXREF_LLM_PARSE_RETRIES` is `0`. With `PRXREF_TRACE_DIR` set and the
+  variable at `1` or more, a unit that retried keeps each discarded reply as
+  `<unit>.attempt<K>.response.json` (K from 1) beside its four trace files,
+  which still show the reply that was used, and its `<unit>.meta.json` gains
+  `parse_retries` and `first_error`, the error the first reply would have
+  failed the unit with.
+- **A parse retry for the `prxref eval` judge (#21).** `prxref eval score`
+  reads `PRXREF_LLM_PARSE_RETRIES` (default `1`) from its own environment. A
+  judge reply the parser rejects for any reason (empty, not JSON, not an
+  object, no `grades` list, or a grades row that is not an object, has no
+  `human_id` or has an unknown grade) is sent again, the same request, up to
+  that many times. Unlike a review unit's, a truncated judge reply is
+  retried, and an empty one gets no retry at `0`. A call that raised and a
+  cache hit are never retried, and only the graded reply is cached.
+  `score.json`'s `judge` block gains `parse_retries` after `llm_calls`, which
+  counts every attempt, and `score.md`'s judge cost line adds `(1 parse
+  retry)` or `(<n> parse retries)` only when there were any. The judge's
+  `cost_usd` and the `judge_cost` metric count every attempt, and a case
+  whose retry raised after a rejected reply is priced by that reply. A traced
+  judge keeps each rejected reply as `judge.attempt<K>.response.json`, and
+  `judge.meta.json` gains `parse_retries` and `first_error`. `prxref eval
+  run` records `llm_parse_retries` in `run.json`'s `config`, which now holds
+  17 settings.
+- **Code elsewhere that reads state this chunk writes (#22).** At
+  `PRXREF_REPO_CONTEXT=repo`, with a repository reader and a file listing, a
+  chunk worker also gets excerpts of unchanged code that reads state the
+  chunk's added lines write, such as a map the change stores a new object in,
+  or a table it appends rows to. The keys come from subscript stores
+  (`recv[k] = v`, key `recv`) and from calls of `append`, `add`, `insert`,
+  `save`, `put`, `push`, `store`, `write`, `extend`, `update` or `setdefault`
+  (key: the receiver's last segment); a local alias such as `data =
+  run.root().data` resolves to its attribute, and a key the added lines
+  assign a new value is skipped. A read is `.key` or `["key"]` used other
+  than as a store, or `key.<method>(` with a method that is not one of those
+  verbs, in a listed file of the same language that the pull request does not
+  change; files sharing the most leading directories with the change come
+  first. Each excerpt runs from the enclosing definition to the read, at most
+  8 lines. A chunk gets at most 6 such entries and tries at most 24 files,
+  within the same 16-read chunk cap and 200-read run cap, and only after the
+  other sources have made their reads. The entries form a new last prompt
+  block, `### Code elsewhere that reads state this chunk writes`, share the
+  chunk's `PRXREF_REPO_CONTEXT_MAX_CHARS` budget, and rank last, so the
+  budget cuts them first. An excluded path is never read. In the run record
+  their kind is `reader` and their reason `shared-state`. `off` and `diff`
+  get no such block.
+- **Default-on toggles pinned off in tests (#22).** A new deterministic check,
+  always on, posts one `warning` at confidence 1.0 when the pull request adds
+  a toggle whose default is on and also adds a line to a suite-wide test
+  setup file (`conftest.py`, `setupTests.*`, `jest.setup.*` or
+  `vitest.setup.*`) that turns it off: the passing suite then never runs the
+  shipped default. The finding sits on the toggle's line, names every file
+  that pins it, and ends with `(deterministic check, no model)`. See
+  `docs/quality.md`.
+
+### Changed
+
+- **An object without `findings` is no longer a clean review (#21).** At the
+  default `PRXREF_LLM_PARSE_RETRIES=1`, a reply such as `{}` costs a second
+  call, and if that reply has no `findings` list either, the unit fails with
+  `worker review JSON has no findings list`, where 0.16.0 counted it as a
+  review with no findings. A reply that does not parse, or is not a JSON
+  object, also gets a second call, and the unit fails only when that reply
+  cannot be used either. A custom worker or systemic template whose reply
+  format drops `findings` fails every unit this way, and no template check
+  catches it (see `docs/prompt-templates.md`). `0` restores the 0.16.0
+  handling.
+- **Java and Kotlin files are read at every level (#20).** Chunk context can
+  read each changed Java or Kotlin file, and the build files its dependency
+  walk tries, through the forge at the PR head whenever the forge can read
+  files and the pull request has a head sha, with `PRXREF_REPO_CONTEXT` at
+  `off` too. These reads are cached per run and are not counted against the
+  repository-context read caps.
+- **A Java file's own definitions are shown once (#20).** With a repository
+  reader, the definitions a Java file of the chunk holds for the names its own
+  added lines mention now come from chunk context only, and are no longer
+  repeated as `diff-file` repository-context entries; Kotlin files work the
+  same way. A Java or Kotlin file of the chunk whose own added lines mention
+  every name the cross-chunk search wants is no longer read by that search.
+- **`read_cap_hit` can be true in more runs (#22).** At `repo`, the
+  shared-state search spends the reads the other sources leave, and a read the
+  cap refuses counts, so `read_cap_hit` in the run record, the `repo_context`
+  trace event and `cap_hit=yes` on the `-v` line can be true in a run where
+  the definitions and contract excerpts alone fit the cap.
+
+### Fixed
+
+- **A definition from another file of the same chunk.** With a
+  repository reader, repository context at `diff` and `repo` now finds a
+  definition that one Python or JavaScript/TypeScript file of a chunk
+  references and another file of the same chunk defines outside its hunks.
+  0.16.0 left the chunk's own Python and JavaScript/TypeScript files out of
+  that search entirely.
+
+### Known limitations
+
+- **The follow-up lookup of #22 is not built.** Part 1 of #22, one bounded
+  extra call that looks up the symbol a below-floor finding says it could not
+  see, is deferred, and #22 stays open.
+- **A Java or Kotlin file can be fetched twice.** Chunk context and
+  repository context keep separate readers with no shared cache, so a file
+  both of them read costs two requests per run, as 0.16.0's dependency and
+  same-file blocks already did for other languages.
+- **Kotlin standard-library names cost lookups.** Names such as `Int`, `Unit`
+  or `Pair` are not in the built-in list of platform names repository context
+  ignores, so at `repo` each one a chunk mentions is looked for by the
+  file-name search, as a project type would be. Repository context has no
+  Kotlin import or path rules: outside the diff, a Kotlin type is found by the
+  file-name search alone.
+- **Precompiled Gradle script plugins are treated as Kotlin.** Only
+  `build.gradle.kts` and `settings.gradle.kts` are skipped by the dependency
+  lookup; another `*.gradle.kts` file is handled like any Kotlin source, so its
+  Gradle API imports cost a walk for the nearest build file.
+- **Some dependencies are not matched or not resolved.** An artifact whose
+  groupId is not a prefix of its packages gets no line: Guava, Lombok, JUnit 4,
+  Spring Boot starters and kotlinx among them. Gradle map notation
+  (`group: 'g', name: 'a'`) is not read, and a version set through a variable
+  or `gradle.properties` is not resolved.
+- **A truncated review reply is not retried.** A reply stopped at
+  `PRXREF_LLM_MAX_TOKENS` that cannot be used fails the unit on the first
+  call, with the budget named, whatever `PRXREF_LLM_PARSE_RETRIES` says.
+- **The timeout retry records its own parse retries only.** When a chunk is
+  run again after a timeout, only the second run's `parse_retries` is
+  counted, the same gap its token counts and cost have.
+- **`score.json` does not total the reviews' parse retries.** It counts the
+  judge's; each case's own run record carries its review's `parse_retries`.
+- **The shared-state search matches names, not types.** A reader is any line
+  that reads a key of the same name in a file of the same language, so an
+  unrelated `.data` or `table` elsewhere can fill an entry, and a reader in
+  another language is never found.
+- **The toggle check needs both lines in the pull request.** A new pin on a
+  toggle that already existed, or a new toggle that an existing setup line
+  pins, is not reported, and neither is a pin outside the four suite-wide
+  setup file names.
+
 ## [0.16.0] — 2026-09-25
 
 The repository-context release (#17). A chunk worker can now see code outside
diff --git a/README.md b/README.md
index 1449c0f..fe1e702 100644
--- a/README.md
+++ b/README.md
@@ -299,13 +299,13 @@ PRXREF_REPO_CONTEXT=repo prxref review --diff-file pr.diff --repo-dir ./widget
 
 | `PRXREF_REPO_CONTEXT` | What each chunk worker also sees |
 |---|---|
-| `off` (default) | Nothing: prompts, posts, traces and logs are byte-identical to 0.15.0. |
-| `diff` | Definitions from the PR's other changed files, and, for a type another chunk changes, the lines changed inside it. Java type declarations are found as well as JavaScript, TypeScript and Python ones. |
-| `repo` | Also definitions from files outside the diff, found through imports, Java's same-package file convention, and a search of file names; and a `### Contract excerpts` block with the OpenAPI operation or schema, JSON Schema, or earlier migration that a changed route, table or name matches. |
+| `off` (default) | Nothing from repository context: no entry, no repository read, no `repo_context` trace event. The same-file definitions and dependency versions, Java and Kotlin ones included since 0.17.0, do not depend on this setting. |
+| `diff` | Definitions from the PR's other changed files, and, for a type another chunk changes, the lines changed inside it. Java and Kotlin type declarations are found as well as JavaScript, TypeScript and Python ones. With a reader, a definition one file of the chunk references and another file of the same chunk holds outside its hunks is found too. |
+| `repo` | Also definitions from files outside the diff, found through imports, Java's same-package file convention, and a search of file names; a `### Contract excerpts` block with the OpenAPI operation or schema, JSON Schema, or earlier migration that a changed route, table or name matches; and, with a file listing, a last block, `### Code elsewhere that reads state this chunk writes`: short excerpts of unchanged code in the same language that reads a map, table or other state the chunk's added lines write to (at most 6 per chunk, ranked last in the budget). |
 
 - **Where it reads.** Files are read at the PR head through the forge (every forge adapter can read and list files, see [docs/forges.md](docs/forges.md)), or from `--repo-dir` when given. With neither, `diff` builds its entries from the diff's hunk lines, and `repo` does the same with a WARNING. At `repo` the repository's file listing is read once per run; without one, a WARNING says the name search and the contract files outside the PR are off.
 - **What it never reads.** A floor that is always on keeps `**/expected.json`, `**/cases.json`, `**/case.json`, `**/prxref-eval/**`, `**/.env*`, `**/*.pem` and `**/*.key` out of every listing, read and repository-context entry. `PRXREF_CONTEXT_EXCLUDE_GLOBS` adds globs to it, and cannot take a floor path back out. Neither hides a changed file's hunks, which reach the prompt as the diff. `PRXREF_CONTEXT_CONTRACT_GLOBS` replaces the built-in set of contract globs.
-- **Budget.** `PRXREF_REPO_CONTEXT_MAX_CHARS` (default `12000`) caps each chunk's entries, admitted in rank order until one does not fit, and a closing line counts the rest. Reads of files outside the PR are capped at 16 per chunk and 200 per run. The timeout retry, which follows a chunk call that outlasts `PRXREF_LLM_TIMEOUT`, drops all of it to shrink the prompt.
+- **Budget.** `PRXREF_REPO_CONTEXT_MAX_CHARS` (default `12000`) caps each chunk's entries, admitted in rank order until one does not fit, and a closing line counts the rest. Reads of files outside the PR are capped at 16 per chunk and 200 per run. The timeout retry, which follows a chunk call that outlasts `PRXREF_LLM_TIMEOUT`, drops all of it, the reader block included, to shrink the prompt.
 - **Workers only.** The whole-PR sweep prompt is unchanged.
 - **Recorded.** `--format json` and the run record carry `repo_context`: the reader, the listing size, the read counts, and each admitted entry's path, line and reason, never file text. The JSONL trace gains a `chunk context` event per chunk, and in text output `-v` prints a `repo context:` line.
 
diff --git a/docs/llm.md b/docs/llm.md
index b825d61..6036bc5 100644
--- a/docs/llm.md
+++ b/docs/llm.md
@@ -5,7 +5,7 @@
 ## Key Architectural Principles
 
 1. **No Provider Credentials in `prxref`:** `prxref` never looks up, stores, or uses a provider credential (no AWS IAM keys, no OpenAI keys, no Google Cloud keys, and no Anthropic API keys), and its own settings are provider-neutral `PRXREF_*` names. The one key it sends is `PRXREF_LLM_API_KEY`, as a bearer token to the `openai-compat` endpoint you configured. Every provider key lives behind that endpoint, in the provider SDK's own environment (`litellm`), or inside your own logged-in CLI (`claude-cli`, `kiro-cli`). A CLI backend hands its CLI the environment `prxref` was started with; `claude-cli` first removes a fixed list of credential-routing variable *names*, so the CLI falls back to its subscription login, and never reads their values.
-2. **Fast Caller-Side Failover:** Fallback is implemented as a fast sequential loop over the model list. If a model encounters HTTP 429 (rate limit), HTTP >= 500 (server/upstream error), connection failures, or timeouts, the client immediately advances to the next model in the chain without same-model retries. Above the backends, the reviewer asks once more when a reply comes back empty (no text, or whitespace only, and not stopped at the token budget): the same prompt goes out as a new call, which walks the fallback chain like any other, so no backend ever retries a model in place.
+2. **Fast Caller-Side Failover:** Fallback is implemented as a fast sequential loop over the model list. If a model encounters HTTP 429 (rate limit), HTTP >= 500 (server/upstream error), connection failures, or timeouts, the client immediately advances to the next model in the chain without same-model retries. Above the backends, the reviewer sends a request again when its reply cannot be used as a review, up to `PRXREF_LLM_PARSE_RETRIES` times, and an empty reply once even at `0` (see [Parse Retries](#parse-retries)): the same prompt goes out as a new call, which walks the fallback chain like any other, so no backend ever retries a model in place.
 
 ---
 
@@ -60,6 +60,23 @@ The client iterates through `PRXREF_LLM_MODELS` in left-to-right priority order
 - If all configured models fail, `LLMError` is raised containing the per-model failure reasons.
 - A 4xx body that names a model as permanently gone (deprovisioned, renamed, not supported, or never enabled for this integrator) is cached for the life of the client: every later call skips that model outright — no request, no per-call log — with a single WARNING logged the one time it is marked. `LiteLLMClient` mirrors the same cache, keyed on the exception litellm raises (a 4xx-shaped error naming a model) instead of an HTTP status; it filters the unavailable model out of both the primary `model` and its native `fallbacks` before calling litellm, and raises `LLMError` without calling litellm at all once every configured model has been marked. A 5xx, a timeout, or a connection error is never cached — only a 4xx carrying that phrasing is treated as permanent.
 
+### Parse Retries
+
+Failover handles a model that did not answer. A model that answered with something prxref cannot use as a review is handled one level up, by the reviewer, under one retry budget per review unit (a chunk worker, or the whole-PR sweep): `PRXREF_LLM_PARSE_RETRIES`, default `1`, at least `0`, with no upper bound. After each call the reviewer decides:
+
+- **A reply stopped at the budget** (`finish_reason` `length` or `max_tokens`) is never retried. If it cannot be used, the unit fails with the truncation error described under [Reasoning Models Share the Budget](#reasoning-models-share-the-budget), which names `PRXREF_LLM_MAX_TOKENS`; if it can, it is used, with a WARNING that its findings may be incomplete.
+- **An empty reply** (no text, or whitespace only) is retried while fewer than `max(N, 1)` retries have run, so it gets one retry even at `0`, as in 0.16.0.
+- **A reply that does not parse**, one that parses to something other than a JSON object, and, at `1` or more only, **an object without a `findings` list** are retried while fewer than `N` retries have run. At `0`, an object without `findings` is a review with no findings, as in 0.16.0.
+- **A call that raised**, for example because every model in the chain failed, is never retried: the unit fails with that error.
+
+A retry sends the same request, with the same prompt and the same `max_tokens`, as a new call. That call walks `PRXREF_LLM_MODELS` exactly like a first call, starting at the first model rather than at the one that answered, and a model marked permanently gone stays skipped. A reply that came back is never handed to the next model in the chain.
+
+At `1` or more, each retry logs one WARNING, `<unit>: empty model reply (finish_reason=<reason>); parse retry <k> of <N>` or `<unit>: unusable model reply (<error>); parse retry <k> of <N>`; at `0`, the one empty-reply retry logs `<unit>: empty model reply (finish_reason=<reason>); retrying once`, as in 0.16.0. Once the budget is spent, the last reply is handled exactly like a first one: if it still cannot be used, the unit fails with that reply's error, worded as in 0.16.0, or with `worker review JSON has no findings list`. A retry that raises fails the unit with that exception, and the earlier calls still count.
+
+A chunk makes at most `1 + max(N, 1)` calls per run, and the timeout retry can run it a second time, so 4 at the default; the sweep, which has no timeout retry, makes at most `1 + max(N, 1)`, 2 at the default. Each call may still try several models. Every call counts toward the unit's tokens, time and cost (see [Which calls count](#which-calls-count)). With `PRXREF_TRACE_DIR` set and `N` at `1` or more, the unit's four trace files show the reply that was used, each discarded reply is kept as `<unit>.attempt<K>.response.json` (K from 1), and `<unit>.meta.json` gains `parse_retries` and `first_error` after its eight keys. The run record and `--format json` carry `parse_retries`, the retries summed over the run: `0` when nothing was sent again, and `null` when `PRXREF_LLM_PARSE_RETRIES` is `0`. The `prxref eval` judge retries under the same variable, with its own rules; see [evals.md](evals.md).
+
+A custom worker or systemic template whose reply format leaves out `findings` fails every unit at `1` or more; see [prompt-templates.md](prompt-templates.md#what-is-checked).
+
 ---
 
 ## Optional Backend: `litellm`
@@ -281,8 +298,8 @@ A review is its chunk workers plus the systemic sweep, and the total covers the
 - A run that sent requests and got no response back at all is unknown (`null`).
 - A run that made no LLM request (an empty diff, or a forge or diff error before the review) costs a known `0.0`.
 - Inside one `openai-compat` call, truncated completions that the fallback chain moved past were billed too, so they are added to that call's figure. Its token counts still cover only the answering model. If any of those completions came back without a figure, the call's figure is unknown.
-- The timeout retry (the one re-run with `context_lines=0`) replaces the first attempt's result, cost included, exactly as it replaces its tokens.
-- The empty-reply retry adds to the first call instead: both calls were billed, so their tokens are summed, and the unit's reported cost is the sum of both figures, or unknown when either call reported none.
+- The timeout retry (the one re-run with `context_lines=0`) replaces the first attempt's result, cost included, exactly as it replaces its tokens, and the run record's `parse_retries` counts only the re-run's parse retries.
+- A [parse retry](#parse-retries), the empty-reply retry included, adds to the calls before it instead: every call was billed, so their tokens and time are summed, and the unit's reported cost is the sum of every call's figure, or unknown when any call reported none. A retry that raised adds nothing, and the calls before it still count.
 - If the total cannot be computed at all, for example because a library caller passed a malformed table object, the run logs a WARNING and its cost is unknown. Cost accounting never fails a review.
 
 ### Where the cost shows
@@ -304,17 +321,18 @@ A review is its chunk workers plus the systemic sweep, and the total covers the
 
 ## Worker Prompt Context
 
-Each worker sees one chunk's unified diff, trimmed to `PRXREF_CHUNK_CONTEXT_LINES` lines around every change. Two optional blocks are appended after the diff to answer the questions the diff alone cannot.
+Each worker sees one chunk's unified diff, trimmed to `PRXREF_CHUNK_CONTEXT_LINES` lines around every change. Two optional blocks are appended after the diff to answer the questions the diff alone cannot, and repository context can add two more after them.
 
 ### Dependency versions and definitions
 
 - **`### Dependency versions`** — `name@version` for each third-party package the chunk's *added* lines import, resolved from the nearest manifest walking up from each changed file to the repository root: `package.json` (`dependencies` + `devDependencies`), `pyproject.toml` (`[project] dependencies` and `[tool.poetry.dependencies]`), `go.mod` `require` lines, and `Cargo.toml` `[dependencies]`. Only imported packages appear. Relative and `node:` specifiers, Python stdlib modules, and relative Python imports are excluded. Without this block a reviewer answers library semantics from whichever major dominates its training data.
-- **`### Definitions referenced by this chunk`** — for identifiers used on added lines whose definition sits in the same file but *outside* the rendered hunk, one `path:line: definition` entry each, taken from the file as served at the PR head. The entry is the defining line plus continuation lines up to a balanced bracket or 6 lines. Caps: at most 40 entries and 8000 characters, with a trailing `… N more definitions omitted` when trimmed; files over 512 KiB are skipped. Definitions the chunk itself adds are never repeated.
+  - **Java and Kotlin** (`.java`, `.kt`, `.kts`, since 0.17.0) list `groupId:artifactId@version` for the imports on the added lines. The walk tries `pom.xml`, then `build.gradle.kts`, then `build.gradle` at each level, and the first non-empty file wins, even one that cannot be parsed, which then contributes nothing. A `pom.xml` is resolved through `<properties>`, its parent chain inside the repository (at most 5 parents), `<dependencyManagement>` and imported BOMs, and one holding a `<!DOCTYPE` or `<!ENTITY` declaration, or larger than 512 KiB, is refused before it is parsed. A Gradle build file is read in string notation (`"g:a:v"`, `"g:a"`), with `platform`, `enforcedPlatform` and `mavenBom` as BOM owners and the version catalog `libs.versions.toml` when the build file mentions `libs.`; map notation, variables and `gradle.properties` are not resolved. A version owned by a BOM, a parent outside the repository or a Gradle platform reads `groupId:artifactId@(managed by <owner>)`. Imports under `java`, `jdk`, `sun` and `kotlin` (not `javax`) and under the project's own groupId or Gradle `group` are skipped. A dependency matches an import when its groupId, of at least 2 segments, is a package prefix of the import, or the two share at least 3 leading segments; among several matches, the artifactId naming a segment of the import wins, and a tie lists every tied artifact. A changed `build.gradle.kts` or `settings.gradle.kts` gets no dependency lines, and the lookup reads nothing for it.
+- **`### Definitions referenced by this chunk`** — for identifiers used on added lines whose definition sits in the same file but *outside* the rendered hunk, one `path:line: definition` entry each, taken from the file as served at the PR head. The entry is the defining line plus continuation lines up to a balanced bracket or 6 lines. Caps: at most 40 entries and 8000 characters, with a trailing `… N more definitions omitted` when trimmed; files over 512 KiB are skipped. Definitions the chunk itself adds are never repeated. The languages are JavaScript and TypeScript, Python, and, since 0.17.0, Java (types, methods, fields and constants, and enum constants) and Kotlin (types, including `fun interface`, `object` and `typealias`, then `fun`, extension functions included, and `val`/`var`). A Java or Kotlin entry starts at up to 2 annotation lines directly above the definition, its line number is the first annotation's, and those lines count toward the 6.
 
-Both blocks are **best effort**. They are built from an optional forge method, `get_file_content(ref, path, *, sha) -> str | None`, resolved with `getattr` and always called at the PR head sha (`pr.source_sha`). Every read is cached per run, so one manifest is fetched once no matter how many chunks want it, and any exception from the adapter degrades to no block. A forge that does not implement the method — and a PR with no head sha — reviews exactly as before, with no header and no extra requests, unless repository context (below) is on. Nothing here can fail a review.
+Both blocks are **best effort**. They are built from an optional forge method, `get_file_content(ref, path, *, sha) -> str | None`, resolved with `getattr` and always called at the PR head sha (`pr.source_sha`). Every read is cached per run, so one manifest is fetched once no matter how many chunks want it, and any exception from the adapter degrades to no block. A forge that does not implement the method — and a PR with no head sha — reviews exactly as before, with no header and no extra requests, unless repository context (below) is on. Nothing here can fail a review. Both blocks are built at every `PRXREF_REPO_CONTEXT` level, `off` included, so since 0.17.0 a PR that changes a Java or Kotlin file can cost reads of that file and of the build files the walk tries, on this reader and not under the repository-context read caps.
 
-**Repository context (0.16.0).** With `PRXREF_REPO_CONTEXT` at `diff` or `repo`, the `### Definitions referenced by this chunk` block also carries definitions from other files, after the same-file entries: from the PR's other changed files at `diff`, Java type declarations included, and at `repo` also from files outside the diff that the chunk's imports, the Java path convention or a file-name search point at. At `repo`, a `### Contract excerpts` block of OpenAPI, JSON Schema and migration slices follows it. These entries share the per-chunk `PRXREF_REPO_CONTEXT_MAX_CHARS` budget instead of the caps above, and come from one run-wide reader over the forge or `--repo-dir`, not from the reader above; with neither, only the definitions from the PR's own files are left, built from the diff's hunk lines. Only chunk workers receive them; the whole-PR sweep prompt is unchanged. See `PRXREF_REPO_CONTEXT` in [env-vars.md](env-vars.md).
+**Repository context (0.16.0; readers since 0.17.0).** With `PRXREF_REPO_CONTEXT` at `diff` or `repo`, the `### Definitions referenced by this chunk` block also carries definitions from other files, after the same-file entries: from the PR's other changed files at `diff`, Java and Kotlin type declarations included, and at `repo` also from files outside the diff that the chunk's imports, the Java path convention or a file-name search point at. With a reader, a file of the chunk itself is searched only for the names its own added lines do not mention, so a definition that one file of the chunk references and another file of the same chunk holds outside its hunks is found, and a file's own definitions, which the same-file entries already show, are not repeated. At `repo`, a `### Contract excerpts` block of OpenAPI, JSON Schema and migration slices follows. Last, at `repo` with a file listing, the `### Code elsewhere that reads state this chunk writes` block holds excerpts of files the PR does not change that read state the chunk's added lines write, such as a map the change stores an object in or a table it appends rows to, found by name in files of the same language as the writing file: at most 6 entries of at most 8 lines each, from at most 24 files tried, using only the reads the other sources leave under the chunk's read cap. These entries share the per-chunk `PRXREF_REPO_CONTEXT_MAX_CHARS` budget instead of the caps above, with the reader excerpts ranked last so the budget cuts them first, and come from one run-wide reader over the forge or `--repo-dir`, not from the reader above; with neither, only the definitions from the PR's own files are left, built from the diff's hunk lines. Only chunk workers receive them; the whole-PR sweep prompt is unchanged. See `PRXREF_REPO_CONTEXT` in [env-vars.md](env-vars.md).
 
 The worker prompt also carries two confidence rules tied to these blocks: a finding that depends on third-party runtime semantics whose version is not listed, or on the semantics of a symbol whose definition is not shown, must cap confidence at 0.5 and be phrased as a question.
 
-On the timeout retry — the one deterministic re-run with `context_lines=0` — the dependency block is kept and the definitions block is dropped, because shrinking the prompt is the entire point of that retry. Repository context goes with it: the retry carries neither the other-file definitions nor the contract excerpts, and the run record marks the chunk `retry_dropped`. The retry follows a chunk call that timed out (`PRXREF_LLM_TIMEOUT`, default `45` seconds), so a model slower than that reviews the chunk without its repository context.
+On the timeout retry — the one deterministic re-run with `context_lines=0` — the dependency block is kept and the definitions block is dropped, because shrinking the prompt is the entire point of that retry. Repository context goes with it: the retry carries none of the other-file definitions, the contract excerpts and the reader block, and the run record marks the chunk `retry_dropped`. The retry follows a chunk call that timed out (`PRXREF_LLM_TIMEOUT`, default `45` seconds), so a model slower than that reviews the chunk without its repository context.
diff --git a/docs/prompt-templates.md b/docs/prompt-templates.md
index d085b9a..0313b7d 100644
--- a/docs/prompt-templates.md
+++ b/docs/prompt-templates.md
@@ -124,6 +124,21 @@ These only warn, and the run goes on:
 - a directory that holds none of the three, which reviews with the packaged
   templates.
 
+Nothing checks the reply format a worker or systemic template asks for. The
+only content rule beyond the marker and the placeholders is that
+`summary.md` keeps `{findings}`; no check reads the `"findings"` key of the
+example reply under `## Output Format`. That key matters since 0.17.0: with
+`PRXREF_LLM_PARSE_RETRIES` at `1` or more (the default is `1`), a reply
+that is a JSON object without a `findings` list is sent again, and when the
+retries run out the unit fails with `worker review JSON has no findings
+list`. So a template whose reply format drops or renames `findings` fails
+every chunk and the sweep, each after its retries, and the review ends as an
+`Error` review, which exits `0` under the default `PRXREF_FAIL_ON=never`.
+At `0`, such a reply counts as a review
+with no findings, as it did in 0.16.0, so the template silently reports
+nothing. Keep the `findings` list in the reply format. See
+[Parse Retries](llm.md#parse-retries).
+
 ## What is recorded
 
 The run record's `prompt_templates` names the directory and fingerprints each
diff --git a/docs/quality.md b/docs/quality.md
index 5cc242a..762fbfa 100644
--- a/docs/quality.md
+++ b/docs/quality.md
@@ -34,6 +34,42 @@ yields zero chunks (every file binary, or an empty diff): the heuristic
 needs no chunk to fire on, so it is computed and gated on that path too,
 not only when at least one chunk survives `build_chunks`.
 
+**Pinned-off toggles.** When a PR adds a toggle whose default is on and also
+adds a line to a suite-wide test setup file that turns the same toggle off,
+the toggle's line gets a `warning` at confidence 1.0: the passing suite runs
+with the toggle off, so it never exercises the default the PR ships. Both
+sides must be ADDED lines of this PR; a toggle or a pin on a context or
+removed line is never reported. The toggle side is a call named by a string
+literal whose default is a literal true, with exactly those two arguments —
+`f("name", default=True)`, `f("name", True)` or `f("name", true)`, where `f`
+is any call but a setter (a last name segment that is `set` or `put`, or
+starts with one and goes on with anything but a lowercase letter, such as
+`setFlag`, `set_flag` or `putBoolean`) — or `getenv`, `environ.get` or
+`getProperty` called as `("NAME", "true")`, or `process.env.NAME ?? "true"`
+or `|| "true"`. The pin side is a line in a file named `conftest.py`, or
+whose name starts with `setupTests.`, `jest.setup.` or `vitest.setup.`, that
+sets a name to `"false"`, `"0"` or `"off"` (any case, either quote): through
+`setenv`, `stubEnv` or `setProperty` called as `("NAME", value)`, through
+`process.env.NAME = value` or `process.env["NAME"] = value`, or through
+`os.environ["NAME"] = value`. A pin names a toggle when the pin name's
+tokens, lowercased and split on `_`, `.` and `-`, END with the toggle name's
+tokens, so `ASSISTANT_PROGRESS_NOTES` names `progress_notes`. The title reads
+`Toggle "<name>" defaults on but the test setup pins it off`, and the body
+quotes the toggle call, names every file that pins it, and ends with
+`(deterministic check, no model)`. The check is always on and has no knob.
+
+Like the release-shape finding, it is folded in at the chunk/sweep boundary,
+so it is a CHUNK-side finding, it also runs on a diff that yields zero
+chunks, and it goes through every pass below like a model finding. Unlike
+that finding, it sits on a real line, so line alignment and the
+reworded-duplicate tier both reach it. When a chunk worker also reports the
+toggle on the same line, both findings are kept at the default
+(`PRXREF_DEDUP_SIMILARITY` unset), as for any two chunk findings on one
+line. With the similarity set and titles similar enough, the reworded tier
+keeps one copy, the more severe, then the more confident: on a severity tie
+the check's 1.0 outranks a model's lower confidence, and the model's copy is
+dropped as `duplicate of chunk finding (reworded, similarity <s>)`.
+
 ## The passes, in the order they run
 
 `orchestrate_review` applies these in a fixed order; several of them depend on
@@ -297,8 +333,8 @@ text.
   one rule may produce across the review in `apply_rule_cap`, and `0` turns
   it off. These seven are the only knobs here. See
   [Tuning for Your Team](env-vars.md#tuning-for-your-team).
-- The hedge gate, the manifest checks, and the removal-claim check have **no
-  knob**. They are correctness checks against the diff itself, not noise
+- The hedge gate, the manifest checks, the removal-claim check, and the
+  pinned-off toggle check have **no knob**. They are correctness checks against the diff itself, not noise
   levers. The example-echo check has none either: a finding that repeats the
   prompt's own example was never found in the diff. To change what it drops,
   change the example in an overridden template. A hedged finding is unverified by its own admission; the escape hatch
diff --git a/src/prxref/config.py b/src/prxref/config.py
index 1339652..6d19638 100644
--- a/src/prxref/config.py
+++ b/src/prxref/config.py
@@ -256,17 +256,24 @@
                                 prompt; longer is truncated with a visible
                                 marker; positive int (default 6000)
   PRXREF_REPO_CONTEXT           Repository context (0.16.0): "off" (default) |
-                                "diff" | "repo". "off" leaves every prompt,
-                                post, trace and default-verbosity log
-                                byte-identical to 0.15.0. "diff" adds
+                                "diff" | "repo". "off" adds no repository
+                                context entry, read, trace event or log line;
+                                the same-file definitions and dependency
+                                versions, Java and Kotlin ones included since
+                                0.17.0, do not depend on it. "diff" adds
                                 cross-chunk definitions from other files
                                 already in the diff, plus diff-file entries,
                                 all read from the diff itself; no repository
                                 reader is needed. "repo" also reads files
                                 outside the diff — import, path-convention and
                                 name-search definitions, plus contract excerpts
-                                — through the forge's repository reader when
-                                one is available, or --repo-dir. Matching is
+                                and, with a file listing, readers (since
+                                0.17.0: excerpts of unchanged code that reads
+                                state the chunk's added lines write, in a last
+                                "Code elsewhere that reads state this chunk
+                                writes" block) — through the forge's
+                                repository reader when one is available, or
+                                --repo-dir. Matching is
                                 exact and case-sensitive, like PRXREF_FAIL_ON;
                                 any other value is a configuration error
   PRXREF_REPO_CONTEXT_MAX_CHARS Repository context (0.16.0): per-chunk
diff --git a/src/prxref/orchestrator.py b/src/prxref/orchestrator.py
index 37af63b..325f4bb 100644
--- a/src/prxref/orchestrator.py
+++ b/src/prxref/orchestrator.py
@@ -712,9 +712,11 @@ def orchestrate_review(
     through a fresh ``chunk_reader()``, so the per-chunk read cap is spent
     on the paths outside the diff alone, and the entries do not depend on
     which chunk reads a shared diff file first. The context's definition
-    lines extend the definitions block and its contract lines form a
-    ``### Contract excerpts`` block, on the first attempt only: the timeout
-    retry carries neither. A build that raises gives that chunk no context
+    lines extend the definitions block, its contract lines form a
+    ``### Contract excerpts`` block and its reader lines a last
+    ``### Code elsewhere that reads state this chunk writes`` block, on the
+    first attempt only: the timeout retry passes no unit, so it carries none
+    of the three. A build that raises gives that chunk no context
     and one WARNING naming the chunk; the review goes on. The dependency and
     same-file definition blocks keep their own reader in every mode, so a
     diff file can be fetched once by each reader.

From 82648890e742cc5c8c13460992ea90d703d5dc67 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 21:55:02 -0700
Subject: [PATCH 22/25] test: issue #20 acceptance for JVM chunk context, end
 to end against 0.16.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drives the real orchestrate_review over a new fixture monorepo: a Maven
multi-module build (parent properties plus a BOM import, a versionless
module dependency, a malformed module pom), a Gradle build with a
version catalog reached through version.ref and a garbage subproject
build.gradle, and a Python control, seven files, one per chunk.

Asserts the literal dependency lines (property-resolved, BOM-managed,
catalog), the skipped java.* and own-group imports, the annotated
definitions entries from their first annotation line, the Kotlin fun
and class, no keyword-named definition, the broken builds (no line, a
completed run in the record, the trace and the log, and a control that
reaches the enclosing build without them), one rendering per own-file
definition at diff and repo with a live cross-chunk control, and the
40-entry cap.

The regression golden was captured from the released prxref 0.16.0
installed from PyPI, never from the tree: the Python control and the
sweep prompts are byte-identical, and every JVM chunk prompt differs
only by the added dependency and definition blocks.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 tests/fixtures/issue20/golden_0_16_0.json     |  48 +++
 tests/fixtures/issue20/harness.py             | 218 ++++++++++
 tests/fixtures/issue20/make_golden.py         |  82 ++++
 tests/fixtures/issue20/pr.diff                | 145 +++++++
 .../issue20/repo/inventory/build.gradle.kts   |  16 +
 .../repo/inventory/gradle/libs.versions.toml  |   5 +
 .../repo/inventory/reports/build.gradle       |   3 +
 .../com/example/reports/ReportWriter.java     |  12 +
 .../com/example/inventory/StockClient.java    |  17 +
 .../com/example/inventory/StockReport.kt      |  26 ++
 tests/fixtures/issue20/repo/shop/pom.xml      |  35 ++
 .../issue20/repo/shop/shop-api/pom.xml        |  26 ++
 .../com/example/shop/api/OrderMapper.java     |  23 +
 .../example/shop/pricing/PriceCalculator.java |  38 ++
 .../issue20/repo/shop/shop-legacy/pom.xml     |  16 +
 .../com/example/shop/legacy/LegacyExport.java |  12 +
 .../issue20/repo/tools/export_orders.py       |  18 +
 .../issue20/repo/tools/pyproject.toml         |   4 +
 tests/test_issue_20_acceptance.py             | 400 ++++++++++++++++++
 19 files changed, 1144 insertions(+)
 create mode 100644 tests/fixtures/issue20/golden_0_16_0.json
 create mode 100644 tests/fixtures/issue20/harness.py
 create mode 100644 tests/fixtures/issue20/make_golden.py
 create mode 100644 tests/fixtures/issue20/pr.diff
 create mode 100644 tests/fixtures/issue20/repo/inventory/build.gradle.kts
 create mode 100644 tests/fixtures/issue20/repo/inventory/gradle/libs.versions.toml
 create mode 100644 tests/fixtures/issue20/repo/inventory/reports/build.gradle
 create mode 100644 tests/fixtures/issue20/repo/inventory/reports/src/main/java/com/example/reports/ReportWriter.java
 create mode 100644 tests/fixtures/issue20/repo/inventory/src/main/java/com/example/inventory/StockClient.java
 create mode 100644 tests/fixtures/issue20/repo/inventory/src/main/kotlin/com/example/inventory/StockReport.kt
 create mode 100644 tests/fixtures/issue20/repo/shop/pom.xml
 create mode 100644 tests/fixtures/issue20/repo/shop/shop-api/pom.xml
 create mode 100644 tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java
 create mode 100644 tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java
 create mode 100644 tests/fixtures/issue20/repo/shop/shop-legacy/pom.xml
 create mode 100644 tests/fixtures/issue20/repo/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java
 create mode 100644 tests/fixtures/issue20/repo/tools/export_orders.py
 create mode 100644 tests/fixtures/issue20/repo/tools/pyproject.toml
 create mode 100644 tests/test_issue_20_acceptance.py

diff --git a/tests/fixtures/issue20/golden_0_16_0.json b/tests/fixtures/issue20/golden_0_16_0.json
new file mode 100644
index 0000000..17a78ec
--- /dev/null
+++ b/tests/fixtures/issue20/golden_0_16_0.json
@@ -0,0 +1,48 @@
+{
+ "command": "cd /tmp && uv run --isolated --no-project --with prxref==0.16.0 python tests/fixtures/issue20/make_golden.py golden_0_16_0.json (both paths absolute)",
+ "generated_from": "installed distribution",
+ "prxref_version": "0.16.0",
+ "runs": {
+  "fixture": {
+   "content_calls": [
+    "tools/pyproject.toml",
+    "tools/export_orders.py"
+   ],
+   "list_calls": 0,
+   "prompts": [
+    {
+     "system": "You are a senior code reviewer. You review one chunk of a pull-request diff per call. You see the diff text plus any context blocks supplied below it \u2014 no repository checkout, no call graph, no history. Review what the diff and those blocks show; do not speculate about code you cannot see.\n\n## Mission\n\nVerify every claim against the diff itself. Every finding must cite a file and line that exist in the diff \u2014 if you cannot point at the exact added line, do not emit the finding. Prefer zero findings over one speculative finding.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the diff line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this diff alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the diff text alone.\n\nA finding that depends on a third-party library's runtime semantics must cap confidence at 0.5 and be phrased as a question when that library version is not listed under a \"Dependency versions\" heading below. Different majors behave differently; without the pin you are guessing which one this code runs against.\n\nIf a finding turns on the semantics of a named symbol whose definition is not shown \u2014 neither in the diff nor under a \"Definitions referenced by this chunk\" heading below \u2014 cap confidence at 0.5 and phrase it as a question. The identifier's name is not evidence of its behavior.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. If you suspect an issue but the diff lacks the evidence to support it, do not emit it and do not escalate it \u2014 either find the evidence in the diff or drop the concern. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list. A finding whose truth depends on a precondition you could not establish from the diff (\"if X is still mounted\", \"unless the migration already ran\", \"if they are members of the root workspaces\") must not be reported as a defect: either phrase it as a question with `confidence` at or below 0.5, or omit it.\n\nBefore asserting that something is absent, unsupported, undocumented, or contradicted, check the `### Other files changed in this PR` summary below the diff \u2014 the refuting evidence may sit in a sibling file the chunk split moved out of view. If a sibling file plausibly refutes the claim, drop the finding or lower it to a question with `confidence` at or below 0.5.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the diff evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe diff below is the complete chunk.\n\n### Diff\n\n```diff\ndiff --git a/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java b/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java\n--- a/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java\n+++ b/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java\n@@ -1,8 +1,23 @@\n package com.example.shop.api;\n \n+import com.example.shop.core.Money;\n+import com.fasterxml.jackson.databind.ObjectMapper;\n+import java.util.List;\n+import org.slf4j.Logger;\n+import org.slf4j.LoggerFactory;\n+\n public class OrderMapper {\n+\n+    private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n+\n+    private final ObjectMapper mapper = new ObjectMapper();\n \n     public String describe(int count) {\n         return \"orders: \" + count;\n     }\n+\n+    public String toJson(List<Money> totals) throws Exception {\n+        LOG.debug(\"mapping {} totals\", totals.size());\n+        return mapper.writeValueAsString(totals);\n+    }\n }\n```\n\n### Other files changed in this PR\n\n- shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java (modified, +7/-1):\n   import com.fasterxml.jackson.annotation.JsonProperty;\n   import jakarta.annotation.Nullable;\n   import java.math.BigDecimal;\n  +import java.util.Objects;\n   import org.springframework.transaction.annotation.Transactional;\n   \n   public class PriceCalculator {\n       }\n   \n       public BigDecimal total(BigDecimal unit, int items) {\n  +        Objects.requireNonNull(unit, \"unit\");\n  +        if (!open || items > MAX_ITEMS) {\n  +            throw new IllegalStateException(\"closed or too many items\");\n  +        }\n  +        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n  +        return gross.add(gross.multiply(taxRate));\n       }\n   }\n- shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java (modified, +6/-2):\n   package com.example.shop.legacy;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class LegacyExport {\n   \n  +    private final ObjectMapper writer = new ObjectMapper();\n  +\n  +    public String export(Object order) throws Exception {\n  +        return writer.writeValueAsString(order);\n       }\n   }\n- inventory/src/main/java/com/example/inventory/StockClient.java (modified, +11/-2):\n   package com.example.inventory;\n  +\n  +import com.example.inventory.model.Sku;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class StockClient {\n   \n  +    private final ObjectMapper json = new ObjectMapper();\n  +\n  +    public String fetch(Sku sku) throws Exception {\n  +        return json.writeValueAsString(sku);\n  +    }\n  +\n  +    public StockLevel parse(String body) throws Exception {\n  +        return json.readValue(body, StockLevel.class);\n       }\n   }\n- inventory/src/main/kotlin/com/example/inventory/StockReport.kt (modified, +3/-1):\n   package com.example.inventory\n   \n  +import com.fasterxml.jackson.databind.ObjectMapper\n   import java.time.LocalDate\n   \n   /**\n       fun title(): String = \"Stock on $day\"\n   \n       fun render(levels: List<StockLevel>): String {\n  +        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n  +        return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n       }\n   }\n- inventory/reports/src/main/java/com/example/reports/ReportWriter.java (modified, +6/-2):\n   package com.example.reports;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class ReportWriter {\n   \n  +    private final ObjectMapper output = new ObjectMapper();\n  +\n  +    public String write(Object report) throws Exception {\n  +        return output.writeValueAsString(report);\n       }\n   }\n- tools/export_orders.py (modified, +3/-1):\n   \"\"\"Export orders to the reporting service.\"\"\"\n  +import requests\n   \n   TIMEOUT_SECONDS = 10\n   \n   \n   \n   def export(orders, url):\n  +    payload = build_payload(orders)\n  +    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Divide by zero when size is unset\",\n      \"body\": \"size defaults to None and is used as a divisor on line 42; the diff adds no guard.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the diff headers. `line` is the 1-based line number in the NEW file: take it from the `@@` header of the hunk containing the cited code \u2014 that header's `+` start counted forward past context and `+` lines only \u2014 never from another hunk's header. Emit `\"findings\": []` when the chunk is clean."
+    },
+    {
+     "system": "You are a senior code reviewer. You review one chunk of a pull-request diff per call. You see the diff text plus any context blocks supplied below it \u2014 no repository checkout, no call graph, no history. Review what the diff and those blocks show; do not speculate about code you cannot see.\n\n## Mission\n\nVerify every claim against the diff itself. Every finding must cite a file and line that exist in the diff \u2014 if you cannot point at the exact added line, do not emit the finding. Prefer zero findings over one speculative finding.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the diff line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this diff alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the diff text alone.\n\nA finding that depends on a third-party library's runtime semantics must cap confidence at 0.5 and be phrased as a question when that library version is not listed under a \"Dependency versions\" heading below. Different majors behave differently; without the pin you are guessing which one this code runs against.\n\nIf a finding turns on the semantics of a named symbol whose definition is not shown \u2014 neither in the diff nor under a \"Definitions referenced by this chunk\" heading below \u2014 cap confidence at 0.5 and phrase it as a question. The identifier's name is not evidence of its behavior.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. If you suspect an issue but the diff lacks the evidence to support it, do not emit it and do not escalate it \u2014 either find the evidence in the diff or drop the concern. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list. A finding whose truth depends on a precondition you could not establish from the diff (\"if X is still mounted\", \"unless the migration already ran\", \"if they are members of the root workspaces\") must not be reported as a defect: either phrase it as a question with `confidence` at or below 0.5, or omit it.\n\nBefore asserting that something is absent, unsupported, undocumented, or contradicted, check the `### Other files changed in this PR` summary below the diff \u2014 the refuting evidence may sit in a sibling file the chunk split moved out of view. If a sibling file plausibly refutes the claim, drop the finding or lower it to a question with `confidence` at or below 0.5.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the diff evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe diff below is the complete chunk.\n\n### Diff\n\n```diff\ndiff --git a/inventory/src/main/java/com/example/inventory/StockClient.java b/inventory/src/main/java/com/example/inventory/StockClient.java\n--- a/inventory/src/main/java/com/example/inventory/StockClient.java\n+++ b/inventory/src/main/java/com/example/inventory/StockClient.java\n@@ -1,8 +1,17 @@\n package com.example.inventory;\n+\n+import com.example.inventory.model.Sku;\n+import com.fasterxml.jackson.databind.ObjectMapper;\n \n public class StockClient {\n \n-    public String fetch(String sku) {\n-        return sku;\n+    private final ObjectMapper json = new ObjectMapper();\n+\n+    public String fetch(Sku sku) throws Exception {\n+        return json.writeValueAsString(sku);\n+    }\n+\n+    public StockLevel parse(String body) throws Exception {\n+        return json.readValue(body, StockLevel.class);\n     }\n }\n```\n\n### Other files changed in this PR\n\n- shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java (modified, +15/-0):\n   package com.example.shop.api;\n   \n  +import com.example.shop.core.Money;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n  +import java.util.List;\n  +import org.slf4j.Logger;\n  +import org.slf4j.LoggerFactory;\n  +\n   public class OrderMapper {\n  +\n  +    private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n  +\n  +    private final ObjectMapper mapper = new ObjectMapper();\n   \n       public String describe(int count) {\n           return \"orders: \" + count;\n       }\n  +\n  +    public String toJson(List<Money> totals) throws Exception {\n  +        LOG.debug(\"mapping {} totals\", totals.size());\n  +        return mapper.writeValueAsString(totals);\n  +    }\n   }\n- shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java (modified, +7/-1):\n   import com.fasterxml.jackson.annotation.JsonProperty;\n   import jakarta.annotation.Nullable;\n   import java.math.BigDecimal;\n  +import java.util.Objects;\n   import org.springframework.transaction.annotation.Transactional;\n   \n   public class PriceCalculator {\n       }\n   \n       public BigDecimal total(BigDecimal unit, int items) {\n  +        Objects.requireNonNull(unit, \"unit\");\n  +        if (!open || items > MAX_ITEMS) {\n  +            throw new IllegalStateException(\"closed or too many items\");\n  +        }\n  +        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n  +        return gross.add(gross.multiply(taxRate));\n       }\n   }\n- shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java (modified, +6/-2):\n   package com.example.shop.legacy;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class LegacyExport {\n   \n  +    private final ObjectMapper writer = new ObjectMapper();\n  +\n  +    public String export(Object order) throws Exception {\n  +        return writer.writeValueAsString(order);\n       }\n   }\n- inventory/src/main/kotlin/com/example/inventory/StockReport.kt (modified, +3/-1):\n   package com.example.inventory\n   \n  +import com.fasterxml.jackson.databind.ObjectMapper\n   import java.time.LocalDate\n   \n   /**\n       fun title(): String = \"Stock on $day\"\n   \n       fun render(levels: List<StockLevel>): String {\n  +        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n  +        return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n       }\n   }\n- inventory/reports/src/main/java/com/example/reports/ReportWriter.java (modified, +6/-2):\n   package com.example.reports;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class ReportWriter {\n   \n  +    private final ObjectMapper output = new ObjectMapper();\n  +\n  +    public String write(Object report) throws Exception {\n  +        return output.writeValueAsString(report);\n       }\n   }\n- tools/export_orders.py (modified, +3/-1):\n   \"\"\"Export orders to the reporting service.\"\"\"\n  +import requests\n   \n   TIMEOUT_SECONDS = 10\n   \n   \n   \n   def export(orders, url):\n  +    payload = build_payload(orders)\n  +    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Divide by zero when size is unset\",\n      \"body\": \"size defaults to None and is used as a divisor on line 42; the diff adds no guard.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the diff headers. `line` is the 1-based line number in the NEW file: take it from the `@@` header of the hunk containing the cited code \u2014 that header's `+` start counted forward past context and `+` lines only \u2014 never from another hunk's header. Emit `\"findings\": []` when the chunk is clean."
+    },
+    {
+     "system": "You are a senior code reviewer. You review one chunk of a pull-request diff per call. You see the diff text plus any context blocks supplied below it \u2014 no repository checkout, no call graph, no history. Review what the diff and those blocks show; do not speculate about code you cannot see.\n\n## Mission\n\nVerify every claim against the diff itself. Every finding must cite a file and line that exist in the diff \u2014 if you cannot point at the exact added line, do not emit the finding. Prefer zero findings over one speculative finding.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the diff line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this diff alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the diff text alone.\n\nA finding that depends on a third-party library's runtime semantics must cap confidence at 0.5 and be phrased as a question when that library version is not listed under a \"Dependency versions\" heading below. Different majors behave differently; without the pin you are guessing which one this code runs against.\n\nIf a finding turns on the semantics of a named symbol whose definition is not shown \u2014 neither in the diff nor under a \"Definitions referenced by this chunk\" heading below \u2014 cap confidence at 0.5 and phrase it as a question. The identifier's name is not evidence of its behavior.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. If you suspect an issue but the diff lacks the evidence to support it, do not emit it and do not escalate it \u2014 either find the evidence in the diff or drop the concern. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list. A finding whose truth depends on a precondition you could not establish from the diff (\"if X is still mounted\", \"unless the migration already ran\", \"if they are members of the root workspaces\") must not be reported as a defect: either phrase it as a question with `confidence` at or below 0.5, or omit it.\n\nBefore asserting that something is absent, unsupported, undocumented, or contradicted, check the `### Other files changed in this PR` summary below the diff \u2014 the refuting evidence may sit in a sibling file the chunk split moved out of view. If a sibling file plausibly refutes the claim, drop the finding or lower it to a question with `confidence` at or below 0.5.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the diff evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe diff below is the complete chunk.\n\n### Diff\n\n```diff\ndiff --git a/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java b/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java\n--- a/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java\n+++ b/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java\n@@ -3,6 +3,7 @@\n import com.fasterxml.jackson.annotation.JsonProperty;\n import jakarta.annotation.Nullable;\n import java.math.BigDecimal;\n+import java.util.Objects;\n import org.springframework.transaction.annotation.Transactional;\n \n public class PriceCalculator {\n@@ -27,6 +28,11 @@\n     }\n \n     public BigDecimal total(BigDecimal unit, int items) {\n-        return unit.multiply(BigDecimal.valueOf(items));\n+        Objects.requireNonNull(unit, \"unit\");\n+        if (!open || items > MAX_ITEMS) {\n+            throw new IllegalStateException(\"closed or too many items\");\n+        }\n+        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n+        return gross.add(gross.multiply(taxRate));\n     }\n }\n```\n\n### Other files changed in this PR\n\n- shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java (modified, +15/-0):\n   package com.example.shop.api;\n   \n  +import com.example.shop.core.Money;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n  +import java.util.List;\n  +import org.slf4j.Logger;\n  +import org.slf4j.LoggerFactory;\n  +\n   public class OrderMapper {\n  +\n  +    private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n  +\n  +    private final ObjectMapper mapper = new ObjectMapper();\n   \n       public String describe(int count) {\n           return \"orders: \" + count;\n       }\n  +\n  +    public String toJson(List<Money> totals) throws Exception {\n  +        LOG.debug(\"mapping {} totals\", totals.size());\n  +        return mapper.writeValueAsString(totals);\n  +    }\n   }\n- shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java (modified, +6/-2):\n   package com.example.shop.legacy;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class LegacyExport {\n   \n  +    private final ObjectMapper writer = new ObjectMapper();\n  +\n  +    public String export(Object order) throws Exception {\n  +        return writer.writeValueAsString(order);\n       }\n   }\n- inventory/src/main/java/com/example/inventory/StockClient.java (modified, +11/-2):\n   package com.example.inventory;\n  +\n  +import com.example.inventory.model.Sku;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class StockClient {\n   \n  +    private final ObjectMapper json = new ObjectMapper();\n  +\n  +    public String fetch(Sku sku) throws Exception {\n  +        return json.writeValueAsString(sku);\n  +    }\n  +\n  +    public StockLevel parse(String body) throws Exception {\n  +        return json.readValue(body, StockLevel.class);\n       }\n   }\n- inventory/src/main/kotlin/com/example/inventory/StockReport.kt (modified, +3/-1):\n   package com.example.inventory\n   \n  +import com.fasterxml.jackson.databind.ObjectMapper\n   import java.time.LocalDate\n   \n   /**\n       fun title(): String = \"Stock on $day\"\n   \n       fun render(levels: List<StockLevel>): String {\n  +        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n  +        return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n       }\n   }\n- inventory/reports/src/main/java/com/example/reports/ReportWriter.java (modified, +6/-2):\n   package com.example.reports;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class ReportWriter {\n   \n  +    private final ObjectMapper output = new ObjectMapper();\n  +\n  +    public String write(Object report) throws Exception {\n  +        return output.writeValueAsString(report);\n       }\n   }\n- tools/export_orders.py (modified, +3/-1):\n   \"\"\"Export orders to the reporting service.\"\"\"\n  +import requests\n   \n   TIMEOUT_SECONDS = 10\n   \n   \n   \n   def export(orders, url):\n  +    payload = build_payload(orders)\n  +    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Divide by zero when size is unset\",\n      \"body\": \"size defaults to None and is used as a divisor on line 42; the diff adds no guard.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the diff headers. `line` is the 1-based line number in the NEW file: take it from the `@@` header of the hunk containing the cited code \u2014 that header's `+` start counted forward past context and `+` lines only \u2014 never from another hunk's header. Emit `\"findings\": []` when the chunk is clean."
+    },
+    {
+     "system": "You are a senior code reviewer. You review one chunk of a pull-request diff per call. You see the diff text plus any context blocks supplied below it \u2014 no repository checkout, no call graph, no history. Review what the diff and those blocks show; do not speculate about code you cannot see.\n\n## Mission\n\nVerify every claim against the diff itself. Every finding must cite a file and line that exist in the diff \u2014 if you cannot point at the exact added line, do not emit the finding. Prefer zero findings over one speculative finding.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the diff line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this diff alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the diff text alone.\n\nA finding that depends on a third-party library's runtime semantics must cap confidence at 0.5 and be phrased as a question when that library version is not listed under a \"Dependency versions\" heading below. Different majors behave differently; without the pin you are guessing which one this code runs against.\n\nIf a finding turns on the semantics of a named symbol whose definition is not shown \u2014 neither in the diff nor under a \"Definitions referenced by this chunk\" heading below \u2014 cap confidence at 0.5 and phrase it as a question. The identifier's name is not evidence of its behavior.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. If you suspect an issue but the diff lacks the evidence to support it, do not emit it and do not escalate it \u2014 either find the evidence in the diff or drop the concern. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list. A finding whose truth depends on a precondition you could not establish from the diff (\"if X is still mounted\", \"unless the migration already ran\", \"if they are members of the root workspaces\") must not be reported as a defect: either phrase it as a question with `confidence` at or below 0.5, or omit it.\n\nBefore asserting that something is absent, unsupported, undocumented, or contradicted, check the `### Other files changed in this PR` summary below the diff \u2014 the refuting evidence may sit in a sibling file the chunk split moved out of view. If a sibling file plausibly refutes the claim, drop the finding or lower it to a question with `confidence` at or below 0.5.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the diff evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe diff below is the complete chunk.\n\n### Diff\n\n```diff\ndiff --git a/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java b/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java\n--- a/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java\n+++ b/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java\n@@ -1,8 +1,12 @@\n package com.example.shop.legacy;\n+\n+import com.fasterxml.jackson.databind.ObjectMapper;\n \n public class LegacyExport {\n \n-    public String export(Object order) {\n-        return String.valueOf(order);\n+    private final ObjectMapper writer = new ObjectMapper();\n+\n+    public String export(Object order) throws Exception {\n+        return writer.writeValueAsString(order);\n     }\n }\n```\n\n### Other files changed in this PR\n\n- shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java (modified, +15/-0):\n   package com.example.shop.api;\n   \n  +import com.example.shop.core.Money;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n  +import java.util.List;\n  +import org.slf4j.Logger;\n  +import org.slf4j.LoggerFactory;\n  +\n   public class OrderMapper {\n  +\n  +    private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n  +\n  +    private final ObjectMapper mapper = new ObjectMapper();\n   \n       public String describe(int count) {\n           return \"orders: \" + count;\n       }\n  +\n  +    public String toJson(List<Money> totals) throws Exception {\n  +        LOG.debug(\"mapping {} totals\", totals.size());\n  +        return mapper.writeValueAsString(totals);\n  +    }\n   }\n- shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java (modified, +7/-1):\n   import com.fasterxml.jackson.annotation.JsonProperty;\n   import jakarta.annotation.Nullable;\n   import java.math.BigDecimal;\n  +import java.util.Objects;\n   import org.springframework.transaction.annotation.Transactional;\n   \n   public class PriceCalculator {\n       }\n   \n       public BigDecimal total(BigDecimal unit, int items) {\n  +        Objects.requireNonNull(unit, \"unit\");\n  +        if (!open || items > MAX_ITEMS) {\n  +            throw new IllegalStateException(\"closed or too many items\");\n  +        }\n  +        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n  +        return gross.add(gross.multiply(taxRate));\n       }\n   }\n- inventory/src/main/java/com/example/inventory/StockClient.java (modified, +11/-2):\n   package com.example.inventory;\n  +\n  +import com.example.inventory.model.Sku;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class StockClient {\n   \n  +    private final ObjectMapper json = new ObjectMapper();\n  +\n  +    public String fetch(Sku sku) throws Exception {\n  +        return json.writeValueAsString(sku);\n  +    }\n  +\n  +    public StockLevel parse(String body) throws Exception {\n  +        return json.readValue(body, StockLevel.class);\n       }\n   }\n- inventory/src/main/kotlin/com/example/inventory/StockReport.kt (modified, +3/-1):\n   package com.example.inventory\n   \n  +import com.fasterxml.jackson.databind.ObjectMapper\n   import java.time.LocalDate\n   \n   /**\n       fun title(): String = \"Stock on $day\"\n   \n       fun render(levels: List<StockLevel>): String {\n  +        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n  +        return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n       }\n   }\n- inventory/reports/src/main/java/com/example/reports/ReportWriter.java (modified, +6/-2):\n   package com.example.reports;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class ReportWriter {\n   \n  +    private final ObjectMapper output = new ObjectMapper();\n  +\n  +    public String write(Object report) throws Exception {\n  +        return output.writeValueAsString(report);\n       }\n   }\n- tools/export_orders.py (modified, +3/-1):\n   \"\"\"Export orders to the reporting service.\"\"\"\n  +import requests\n   \n   TIMEOUT_SECONDS = 10\n   \n   \n   \n   def export(orders, url):\n  +    payload = build_payload(orders)\n  +    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Divide by zero when size is unset\",\n      \"body\": \"size defaults to None and is used as a divisor on line 42; the diff adds no guard.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the diff headers. `line` is the 1-based line number in the NEW file: take it from the `@@` header of the hunk containing the cited code \u2014 that header's `+` start counted forward past context and `+` lines only \u2014 never from another hunk's header. Emit `\"findings\": []` when the chunk is clean."
+    },
+    {
+     "system": "You are a senior code reviewer. You review one chunk of a pull-request diff per call. You see the diff text plus any context blocks supplied below it \u2014 no repository checkout, no call graph, no history. Review what the diff and those blocks show; do not speculate about code you cannot see.\n\n## Mission\n\nVerify every claim against the diff itself. Every finding must cite a file and line that exist in the diff \u2014 if you cannot point at the exact added line, do not emit the finding. Prefer zero findings over one speculative finding.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the diff line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this diff alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the diff text alone.\n\nA finding that depends on a third-party library's runtime semantics must cap confidence at 0.5 and be phrased as a question when that library version is not listed under a \"Dependency versions\" heading below. Different majors behave differently; without the pin you are guessing which one this code runs against.\n\nIf a finding turns on the semantics of a named symbol whose definition is not shown \u2014 neither in the diff nor under a \"Definitions referenced by this chunk\" heading below \u2014 cap confidence at 0.5 and phrase it as a question. The identifier's name is not evidence of its behavior.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. If you suspect an issue but the diff lacks the evidence to support it, do not emit it and do not escalate it \u2014 either find the evidence in the diff or drop the concern. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list. A finding whose truth depends on a precondition you could not establish from the diff (\"if X is still mounted\", \"unless the migration already ran\", \"if they are members of the root workspaces\") must not be reported as a defect: either phrase it as a question with `confidence` at or below 0.5, or omit it.\n\nBefore asserting that something is absent, unsupported, undocumented, or contradicted, check the `### Other files changed in this PR` summary below the diff \u2014 the refuting evidence may sit in a sibling file the chunk split moved out of view. If a sibling file plausibly refutes the claim, drop the finding or lower it to a question with `confidence` at or below 0.5.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the diff evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe diff below is the complete chunk.\n\n### Diff\n\n```diff\ndiff --git a/inventory/reports/src/main/java/com/example/reports/ReportWriter.java b/inventory/reports/src/main/java/com/example/reports/ReportWriter.java\n--- a/inventory/reports/src/main/java/com/example/reports/ReportWriter.java\n+++ b/inventory/reports/src/main/java/com/example/reports/ReportWriter.java\n@@ -1,8 +1,12 @@\n package com.example.reports;\n+\n+import com.fasterxml.jackson.databind.ObjectMapper;\n \n public class ReportWriter {\n \n-    public String write(Object report) {\n-        return String.valueOf(report);\n+    private final ObjectMapper output = new ObjectMapper();\n+\n+    public String write(Object report) throws Exception {\n+        return output.writeValueAsString(report);\n     }\n }\n```\n\n### Other files changed in this PR\n\n- shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java (modified, +15/-0):\n   package com.example.shop.api;\n   \n  +import com.example.shop.core.Money;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n  +import java.util.List;\n  +import org.slf4j.Logger;\n  +import org.slf4j.LoggerFactory;\n  +\n   public class OrderMapper {\n  +\n  +    private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n  +\n  +    private final ObjectMapper mapper = new ObjectMapper();\n   \n       public String describe(int count) {\n           return \"orders: \" + count;\n       }\n  +\n  +    public String toJson(List<Money> totals) throws Exception {\n  +        LOG.debug(\"mapping {} totals\", totals.size());\n  +        return mapper.writeValueAsString(totals);\n  +    }\n   }\n- shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java (modified, +7/-1):\n   import com.fasterxml.jackson.annotation.JsonProperty;\n   import jakarta.annotation.Nullable;\n   import java.math.BigDecimal;\n  +import java.util.Objects;\n   import org.springframework.transaction.annotation.Transactional;\n   \n   public class PriceCalculator {\n       }\n   \n       public BigDecimal total(BigDecimal unit, int items) {\n  +        Objects.requireNonNull(unit, \"unit\");\n  +        if (!open || items > MAX_ITEMS) {\n  +            throw new IllegalStateException(\"closed or too many items\");\n  +        }\n  +        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n  +        return gross.add(gross.multiply(taxRate));\n       }\n   }\n- shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java (modified, +6/-2):\n   package com.example.shop.legacy;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class LegacyExport {\n   \n  +    private final ObjectMapper writer = new ObjectMapper();\n  +\n  +    public String export(Object order) throws Exception {\n  +        return writer.writeValueAsString(order);\n       }\n   }\n- inventory/src/main/java/com/example/inventory/StockClient.java (modified, +11/-2):\n   package com.example.inventory;\n  +\n  +import com.example.inventory.model.Sku;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class StockClient {\n   \n  +    private final ObjectMapper json = new ObjectMapper();\n  +\n  +    public String fetch(Sku sku) throws Exception {\n  +        return json.writeValueAsString(sku);\n  +    }\n  +\n  +    public StockLevel parse(String body) throws Exception {\n  +        return json.readValue(body, StockLevel.class);\n       }\n   }\n- inventory/src/main/kotlin/com/example/inventory/StockReport.kt (modified, +3/-1):\n   package com.example.inventory\n   \n  +import com.fasterxml.jackson.databind.ObjectMapper\n   import java.time.LocalDate\n   \n   /**\n       fun title(): String = \"Stock on $day\"\n   \n       fun render(levels: List<StockLevel>): String {\n  +        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n  +        return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n       }\n   }\n- tools/export_orders.py (modified, +3/-1):\n   \"\"\"Export orders to the reporting service.\"\"\"\n  +import requests\n   \n   TIMEOUT_SECONDS = 10\n   \n   \n   \n   def export(orders, url):\n  +    payload = build_payload(orders)\n  +    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Divide by zero when size is unset\",\n      \"body\": \"size defaults to None and is used as a divisor on line 42; the diff adds no guard.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the diff headers. `line` is the 1-based line number in the NEW file: take it from the `@@` header of the hunk containing the cited code \u2014 that header's `+` start counted forward past context and `+` lines only \u2014 never from another hunk's header. Emit `\"findings\": []` when the chunk is clean."
+    },
+    {
+     "system": "You are a senior code reviewer. You review one chunk of a pull-request diff per call. You see the diff text plus any context blocks supplied below it \u2014 no repository checkout, no call graph, no history. Review what the diff and those blocks show; do not speculate about code you cannot see.\n\n## Mission\n\nVerify every claim against the diff itself. Every finding must cite a file and line that exist in the diff \u2014 if you cannot point at the exact added line, do not emit the finding. Prefer zero findings over one speculative finding.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the diff line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this diff alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the diff text alone.\n\nA finding that depends on a third-party library's runtime semantics must cap confidence at 0.5 and be phrased as a question when that library version is not listed under a \"Dependency versions\" heading below. Different majors behave differently; without the pin you are guessing which one this code runs against.\n\nIf a finding turns on the semantics of a named symbol whose definition is not shown \u2014 neither in the diff nor under a \"Definitions referenced by this chunk\" heading below \u2014 cap confidence at 0.5 and phrase it as a question. The identifier's name is not evidence of its behavior.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. If you suspect an issue but the diff lacks the evidence to support it, do not emit it and do not escalate it \u2014 either find the evidence in the diff or drop the concern. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list. A finding whose truth depends on a precondition you could not establish from the diff (\"if X is still mounted\", \"unless the migration already ran\", \"if they are members of the root workspaces\") must not be reported as a defect: either phrase it as a question with `confidence` at or below 0.5, or omit it.\n\nBefore asserting that something is absent, unsupported, undocumented, or contradicted, check the `### Other files changed in this PR` summary below the diff \u2014 the refuting evidence may sit in a sibling file the chunk split moved out of view. If a sibling file plausibly refutes the claim, drop the finding or lower it to a question with `confidence` at or below 0.5.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the diff evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe diff below is the complete chunk.\n\n### Diff\n\n```diff\ndiff --git a/inventory/src/main/kotlin/com/example/inventory/StockReport.kt b/inventory/src/main/kotlin/com/example/inventory/StockReport.kt\n--- a/inventory/src/main/kotlin/com/example/inventory/StockReport.kt\n+++ b/inventory/src/main/kotlin/com/example/inventory/StockReport.kt\n@@ -1,5 +1,6 @@\n package com.example.inventory\n \n+import com.fasterxml.jackson.databind.ObjectMapper\n import java.time.LocalDate\n \n /**\n@@ -19,6 +20,7 @@\n     fun title(): String = \"Stock on $day\"\n \n     fun render(levels: List<StockLevel>): String {\n-        return title()\n+        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n+        return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n     }\n }\n```\n\n### Other files changed in this PR\n\n- shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java (modified, +15/-0):\n   package com.example.shop.api;\n   \n  +import com.example.shop.core.Money;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n  +import java.util.List;\n  +import org.slf4j.Logger;\n  +import org.slf4j.LoggerFactory;\n  +\n   public class OrderMapper {\n  +\n  +    private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n  +\n  +    private final ObjectMapper mapper = new ObjectMapper();\n   \n       public String describe(int count) {\n           return \"orders: \" + count;\n       }\n  +\n  +    public String toJson(List<Money> totals) throws Exception {\n  +        LOG.debug(\"mapping {} totals\", totals.size());\n  +        return mapper.writeValueAsString(totals);\n  +    }\n   }\n- shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java (modified, +7/-1):\n   import com.fasterxml.jackson.annotation.JsonProperty;\n   import jakarta.annotation.Nullable;\n   import java.math.BigDecimal;\n  +import java.util.Objects;\n   import org.springframework.transaction.annotation.Transactional;\n   \n   public class PriceCalculator {\n       }\n   \n       public BigDecimal total(BigDecimal unit, int items) {\n  +        Objects.requireNonNull(unit, \"unit\");\n  +        if (!open || items > MAX_ITEMS) {\n  +            throw new IllegalStateException(\"closed or too many items\");\n  +        }\n  +        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n  +        return gross.add(gross.multiply(taxRate));\n       }\n   }\n- shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java (modified, +6/-2):\n   package com.example.shop.legacy;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class LegacyExport {\n   \n  +    private final ObjectMapper writer = new ObjectMapper();\n  +\n  +    public String export(Object order) throws Exception {\n  +        return writer.writeValueAsString(order);\n       }\n   }\n- inventory/src/main/java/com/example/inventory/StockClient.java (modified, +11/-2):\n   package com.example.inventory;\n  +\n  +import com.example.inventory.model.Sku;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class StockClient {\n   \n  +    private final ObjectMapper json = new ObjectMapper();\n  +\n  +    public String fetch(Sku sku) throws Exception {\n  +        return json.writeValueAsString(sku);\n  +    }\n  +\n  +    public StockLevel parse(String body) throws Exception {\n  +        return json.readValue(body, StockLevel.class);\n       }\n   }\n- inventory/reports/src/main/java/com/example/reports/ReportWriter.java (modified, +6/-2):\n   package com.example.reports;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class ReportWriter {\n   \n  +    private final ObjectMapper output = new ObjectMapper();\n  +\n  +    public String write(Object report) throws Exception {\n  +        return output.writeValueAsString(report);\n       }\n   }\n- tools/export_orders.py (modified, +3/-1):\n   \"\"\"Export orders to the reporting service.\"\"\"\n  +import requests\n   \n   TIMEOUT_SECONDS = 10\n   \n   \n   \n   def export(orders, url):\n  +    payload = build_payload(orders)\n  +    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Divide by zero when size is unset\",\n      \"body\": \"size defaults to None and is used as a divisor on line 42; the diff adds no guard.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the diff headers. `line` is the 1-based line number in the NEW file: take it from the `@@` header of the hunk containing the cited code \u2014 that header's `+` start counted forward past context and `+` lines only \u2014 never from another hunk's header. Emit `\"findings\": []` when the chunk is clean."
+    },
+    {
+     "system": "You are a senior code reviewer. You review one chunk of a pull-request diff per call. You see the diff text plus any context blocks supplied below it \u2014 no repository checkout, no call graph, no history. Review what the diff and those blocks show; do not speculate about code you cannot see.\n\n## Mission\n\nVerify every claim against the diff itself. Every finding must cite a file and line that exist in the diff \u2014 if you cannot point at the exact added line, do not emit the finding. Prefer zero findings over one speculative finding.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the diff line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this diff alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the diff text alone.\n\nA finding that depends on a third-party library's runtime semantics must cap confidence at 0.5 and be phrased as a question when that library version is not listed under a \"Dependency versions\" heading below. Different majors behave differently; without the pin you are guessing which one this code runs against.\n\nIf a finding turns on the semantics of a named symbol whose definition is not shown \u2014 neither in the diff nor under a \"Definitions referenced by this chunk\" heading below \u2014 cap confidence at 0.5 and phrase it as a question. The identifier's name is not evidence of its behavior.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. If you suspect an issue but the diff lacks the evidence to support it, do not emit it and do not escalate it \u2014 either find the evidence in the diff or drop the concern. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list. A finding whose truth depends on a precondition you could not establish from the diff (\"if X is still mounted\", \"unless the migration already ran\", \"if they are members of the root workspaces\") must not be reported as a defect: either phrase it as a question with `confidence` at or below 0.5, or omit it.\n\nBefore asserting that something is absent, unsupported, undocumented, or contradicted, check the `### Other files changed in this PR` summary below the diff \u2014 the refuting evidence may sit in a sibling file the chunk split moved out of view. If a sibling file plausibly refutes the claim, drop the finding or lower it to a question with `confidence` at or below 0.5.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the diff evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe diff below is the complete chunk.\n\n### Diff\n\n```diff\ndiff --git a/tools/export_orders.py b/tools/export_orders.py\n--- a/tools/export_orders.py\n+++ b/tools/export_orders.py\n@@ -1,4 +1,5 @@\n \"\"\"Export orders to the reporting service.\"\"\"\n+import requests\n \n TIMEOUT_SECONDS = 10\n \n@@ -13,4 +14,5 @@\n \n \n def export(orders, url):\n-    return {\"orders\": orders, \"url\": url}\n+    payload = build_payload(orders)\n+    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n```\n\n### Other files changed in this PR\n\n- shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java (modified, +15/-0):\n   package com.example.shop.api;\n   \n  +import com.example.shop.core.Money;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n  +import java.util.List;\n  +import org.slf4j.Logger;\n  +import org.slf4j.LoggerFactory;\n  +\n   public class OrderMapper {\n  +\n  +    private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n  +\n  +    private final ObjectMapper mapper = new ObjectMapper();\n   \n       public String describe(int count) {\n           return \"orders: \" + count;\n       }\n  +\n  +    public String toJson(List<Money> totals) throws Exception {\n  +        LOG.debug(\"mapping {} totals\", totals.size());\n  +        return mapper.writeValueAsString(totals);\n  +    }\n   }\n- shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java (modified, +7/-1):\n   import com.fasterxml.jackson.annotation.JsonProperty;\n   import jakarta.annotation.Nullable;\n   import java.math.BigDecimal;\n  +import java.util.Objects;\n   import org.springframework.transaction.annotation.Transactional;\n   \n   public class PriceCalculator {\n       }\n   \n       public BigDecimal total(BigDecimal unit, int items) {\n  +        Objects.requireNonNull(unit, \"unit\");\n  +        if (!open || items > MAX_ITEMS) {\n  +            throw new IllegalStateException(\"closed or too many items\");\n  +        }\n  +        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n  +        return gross.add(gross.multiply(taxRate));\n       }\n   }\n- shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java (modified, +6/-2):\n   package com.example.shop.legacy;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class LegacyExport {\n   \n  +    private final ObjectMapper writer = new ObjectMapper();\n  +\n  +    public String export(Object order) throws Exception {\n  +        return writer.writeValueAsString(order);\n       }\n   }\n- inventory/src/main/java/com/example/inventory/StockClient.java (modified, +11/-2):\n   package com.example.inventory;\n  +\n  +import com.example.inventory.model.Sku;\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class StockClient {\n   \n  +    private final ObjectMapper json = new ObjectMapper();\n  +\n  +    public String fetch(Sku sku) throws Exception {\n  +        return json.writeValueAsString(sku);\n  +    }\n  +\n  +    public StockLevel parse(String body) throws Exception {\n  +        return json.readValue(body, StockLevel.class);\n       }\n   }\n- inventory/src/main/kotlin/com/example/inventory/StockReport.kt (modified, +3/-1):\n   package com.example.inventory\n   \n  +import com.fasterxml.jackson.databind.ObjectMapper\n   import java.time.LocalDate\n   \n   /**\n       fun title(): String = \"Stock on $day\"\n   \n       fun render(levels: List<StockLevel>): String {\n  +        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n  +        return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n       }\n   }\n- inventory/reports/src/main/java/com/example/reports/ReportWriter.java (modified, +6/-2):\n   package com.example.reports;\n  +\n  +import com.fasterxml.jackson.databind.ObjectMapper;\n   \n   public class ReportWriter {\n   \n  +    private final ObjectMapper output = new ObjectMapper();\n  +\n  +    public String write(Object report) throws Exception {\n  +        return output.writeValueAsString(report);\n       }\n   }\n\n### Dependency versions\n\nrequests@==2.32.3\n\n### Definitions referenced by this chunk\n\ntools/export_orders.py:7: def build_payload(orders):\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Divide by zero when size is unset\",\n      \"body\": \"size defaults to None and is used as a divisor on line 42; the diff adds no guard.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the diff headers. `line` is the 1-based line number in the NEW file: take it from the `@@` header of the hunk containing the cited code \u2014 that header's `+` start counted forward past context and `+` lines only \u2014 never from another hunk's header. Emit `\"findings\": []` when the chunk is clean."
+    },
+    {
+     "system": "You are a senior code reviewer running a systemic sweep over a pull request. You see a compact digest of the WHOLE diff \u2014 every changed file with its hunk headers, plus the added/removed lines that matched high-signal patterns (entry points, secrets, auth checks, error handling, migrations, logging, timers, repo config) or, for short files and migrations, the file's full added content. You see no repository checkout, no call graph, no history. Review what the digest shows; do not speculate about code you cannot see.\n\n## Mission\n\nPer-chunk reviewers each see one slice of the diff and reliably miss classes that only look wrong in aggregate. You look ONLY for these systemic classes:\n\n- An entry point (serverless handler, route, AJAX action, webhook) that reaches a paid or privileged API \u2014 a billable third-party call, a database write, an admin operation \u2014 with no authentication, nonce, or referer check visible in the digest.\n- A secret or server-side credential assigned to a client-exposed variable (`VITE_*`, `NEXT_PUBLIC_*`, anything bundled for the browser) or otherwise committed in plain text.\n- A swallowed error \u2014 a caught exception reduced to a log line or a bare return \u2014 on a code path that bills money or persists state.\n- A migration (DDL) that creates or alters a table without row level security or policies: a `CREATE TABLE` with no `ENABLE ROW LEVEL SECURITY` and no `CREATE POLICY` anywhere in the same migration file is itself the finding. Migration files appear in the digest with their full added content, so the absence of those statements is a fact you can assert, not a guess.\n- A destructive operation (drop, delete, overwrite, force-push style cleanup) with no guard or confirmation.\n- A recurring timer or poll (`setInterval`, `setTimeout`, `while (true)`) with no attempt cap, deadline, or termination on its failure path \u2014 e.g. a 404 response that resets status and re-queues the poll forever.\n- A removed guard: a deleted numeric limit constant (`MAX_*_LENGTH`, `*_SIZE`, `*_BYTES`, `*_TIMEOUT`) or a deleted validator/sanitiser definition (`isValid*`, `validate*`, `sanitize*`, `check*`, `assert*`, `escape*`) on a path that consumes remote or third-party input. The digest shows these as `-` lines; the code that remains says nothing about the bound that is gone, so the deletion itself is the finding.\n- Repo-config drift: two lockfiles for one package manager root \u2014 a lockfile newly added while another lockfile or a `packageManager` pin also appears in the PR. The digest states this collision on a `! repo-config:` line.\n\nNothing else. Per-file bugs inside one chunk are the chunk workers' job; repeating them here only duplicates their findings, which are deduplicated away. One cross-file addition: with the whole-diff digest plus any spec constraints in view, this sweep is the natural seat for cross-file spec classes \u2014 naming rules, version pins, and `no component may` rules \u2014 while per-chunk seats catch line-local violations.\n\nDo not raise a subject the reviewers already argued out under `### Existing discussion` \u2014 that decision was made with more context than the digest carries. If you raise it anyway, say in the body why the discussion's conclusion is wrong.\n\n## Severity Vocabulary\n\n- `error` \u2014 the change will break at runtime or is a real bug: crash, wrong result, data loss, security hole, broken contract.\n- `warning` \u2014 risk or smell the diff introduces or worsens: race-prone pattern, resource leak, missing error handling, load-bearing duplication.\n- `spec` \u2014 the diff violates a constraint quoted in the Spec constraints block below: a MUST/SHALL/required behaviour not implemented, a forbidden behaviour implemented, a version pin or naming rule broken. Only when specs were provided. Quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n- `outofscope` \u2014 minor: misleading naming, a TODO without context, dead code the diff adds.\n\n## Spec-grounded rules\n\nEmit `spec` only for a conflict between the diff and a constraint quoted in the Spec constraints block \u2014 never for a generic best practice not present in the block. This prompt's built-in classes (RLS, secrets, \u2026) are never spec constraints. When the only basis for a finding is a constraint quoted in the Spec constraints block, its severity is `spec`. When the block reads `(no specs provided for this review)`, `spec` is not a legal severity. Cite the digest line that violates it \u2014 the same `file`/`line` contract as every finding \u2014 and quote the violated constraint verbatim in the body, prefixed `Spec: \"`.\n\n## Confidence\n\nEach finding carries a confidence from 0.0 to 1.0 \u2014 how certain you are from this digest alone. Findings below the quality floor (default 0.6) are dropped downstream. 0.5 means \"plausible but unverified\". Reserve 0.9+ for defects provable from the digest text alone; an entry point with no visible auth check on a line that also names a paid API qualifies, a handler you merely suspect reaches a paid API does not.\n\n## No Speculation\n\nThere is no downstream investigation pass that will confirm your suspicions. Every finding must cite a line shown in the digest \u2014 the digest carries only matched lines, so if the evidence is not in it, do not emit the finding and do not escalate it. The `escalations` array exists in the output schema for forward compatibility only: always emit it as an empty list.\n\n## Style\n\nTerse. Title under 80 characters, imperative. Body: what breaks or risks, plus the digest evidence, in 1-4 sentences. No praise, no restating what the diff does, no style-guide nits that change neither behavior nor risk. A finding that asserts a throw, panic, crash, or unhandled rejection must name its containment boundary: the enclosing catch, or state that it is uncaught and name the caller it propagates to.",
+     "user": "## Review Context\n\nPR title: Serialize orders and stock levels as JSON\n\nPR description:\nAdds Jackson to the shop and inventory modules and tightens the price total.\n\nRepo: (unspecified)\n\n### Spec constraints\n\n(no specs provided for this review)\n\nThe digest below lists every changed file (`## path`) with its hunk headers (`@@`), then its lines: a short file (or any file the migration DDL pattern touches) shows its FULL added content \u2014 every `+` line \u2014 so a statement you would expect and do not see inside such a file is evidence of absence; larger files show only the added (`+<new-line>|`) and removed (`-<old-line>|`) lines that matched a high-signal pattern, with secret, auth, and entry-point lines listed ahead of noisier matches in a capped file. A `! repo-config:` line is a synthetic note, not a diff line \u2014 cite it as a file-level finding (`line: 0`). `[full content omitted: ...]` means that file degraded to pattern lines only. `[digest truncated: token budget reached]` means the cap cut the text short; there is no more.\n\n### Digest\n\n```\nPR changes 7 file(s); each file lists its hunk headers, then its full added content when the file is short or a migration, otherwise only its high-signal added/removed lines.\n\n## shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java\n@@ -1,8 +1,23 @@\n+3| import com.example.shop.core.Money;\n+4| import com.fasterxml.jackson.databind.ObjectMapper;\n+5| import java.util.List;\n+6| import org.slf4j.Logger;\n+7| import org.slf4j.LoggerFactory;\n+8| \n+10| \n+11|     private static final Logger LOG = LoggerFactory.getLogger(\"orders\");\n+12| \n+13|     private final ObjectMapper mapper = new ObjectMapper();\n+18| \n+19|     public String toJson(List<Money> totals) throws Exception {\n+20|         LOG.debug(\"mapping {} totals\", totals.size());\n+21|         return mapper.writeValueAsString(totals);\n+22|     }\n\n## shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java\n@@ -3,6 +3,7 @@\n@@ -27,6 +28,11 @@\n+6| import java.util.Objects;\n+31|         Objects.requireNonNull(unit, \"unit\");\n+32|         if (!open || items > MAX_ITEMS) {\n+33|             throw new IllegalStateException(\"closed or too many items\");\n+34|         }\n+35|         var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);\n+36|         return gross.add(gross.multiply(taxRate));\n\n## shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java\n@@ -1,8 +1,12 @@\n+2| \n+3| import com.fasterxml.jackson.databind.ObjectMapper;\n+7|     private final ObjectMapper writer = new ObjectMapper();\n+8| \n+9|     public String export(Object order) throws Exception {\n+10|         return writer.writeValueAsString(order);\n\n## inventory/src/main/java/com/example/inventory/StockClient.java\n@@ -1,8 +1,17 @@\n+2| \n+3| import com.example.inventory.model.Sku;\n+4| import com.fasterxml.jackson.databind.ObjectMapper;\n+8|     private final ObjectMapper json = new ObjectMapper();\n+9| \n+10|     public String fetch(Sku sku) throws Exception {\n+11|         return json.writeValueAsString(sku);\n+12|     }\n+13| \n+14|     public StockLevel parse(String body) throws Exception {\n+15|         return json.readValue(body, StockLevel.class);\n\n## inventory/src/main/kotlin/com/example/inventory/StockReport.kt\n@@ -1,5 +1,6 @@\n@@ -19,6 +20,7 @@\n+3| import com.fasterxml.jackson.databind.ObjectMapper\n+23|         val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }\n+24|         return ObjectMapper().writeValueAsString(listOf(title()) + lines)\n\n## inventory/reports/src/main/java/com/example/reports/ReportWriter.java\n@@ -1,8 +1,12 @@\n+2| \n+3| import com.fasterxml.jackson.databind.ObjectMapper;\n+7|     private final ObjectMapper output = new ObjectMapper();\n+8| \n+9|     public String write(Object report) throws Exception {\n+10|         return output.writeValueAsString(report);\n\n## tools/export_orders.py\n@@ -1,4 +1,5 @@\n@@ -13,4 +14,5 @@\n+2| import requests\n+17|     payload = build_payload(orders)\n+18|     return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)\n```\n\n## Output Format\n\nReturn exactly one JSON object, no prose, no fences:\n\n```json\n{\n  \"findings\": [\n    {\n      \"file\": \"src/example/main.py\",\n      \"line\": 42,\n      \"severity\": \"error\",\n      \"confidence\": 0.9,\n      \"title\": \"Paid API handler has no auth check\",\n      \"body\": \"The digest shows the handler on line 42 reaching the billing API; no nonce or auth line for it appears anywhere in the digest.\"\n    }\n  ],\n  \"escalations\": []\n}\n```\n\n`file` is a path from the digest headers. `line` is the number shown on the digest line you are citing \u2014 prefer a `+` (added) line; use `0` for a file-level finding. Emit `\"findings\": []` when nothing systemic is visible."
+    }
+   ]
+  }
+ }
+}
diff --git a/tests/fixtures/issue20/harness.py b/tests/fixtures/issue20/harness.py
new file mode 100644
index 0000000..43a5a40
--- /dev/null
+++ b/tests/fixtures/issue20/harness.py
@@ -0,0 +1,218 @@
+"""The issue #20 acceptance harness: a read-and-list fake forge, a capturing LLM, one review.
+
+It is version-neutral on purpose. ``make_golden.py`` runs it against the
+RELEASED prxref 0.16.0 and ``tests/test_issue_20_acceptance.py`` runs it
+against the tree, so it imports only API that exists in both:
+``orchestrate_review``, ``PRRef``, ``PRData`` and ``InvokeResult``.
+``FixtureForge.list_paths`` imports ``PathListing`` only when it is called.
+
+The fixture is a small monorepo under ``repo/``. ``shop/`` is a Maven build: a
+parent ``pom.xml`` with properties and a BOM import, a ``shop-api`` module
+whose ``jackson-databind`` dependency has no version, and a ``shop-legacy``
+module whose ``pom.xml`` is malformed. ``inventory/`` is a Gradle build with a
+``libs.versions.toml`` catalog and a ``reports`` subproject whose
+``build.gradle`` is garbage. ``tools/`` is a Python control. ``pr.diff``
+changes seven source files, one per chunk.
+
+The forge serves the diff over the tree plus an optional in-memory overlay and
+records every ``get_file_content`` path and every ``list_paths`` call. The LLM
+records every ``(system, user)`` prompt, worker and sweep alike, and returns no
+findings.
+"""
+from __future__ import annotations
+
+import difflib
+import os
+import threading
+from pathlib import Path
+
+from prxref.forges.base import PRData, PRRef
+from prxref.llm import InvokeResult
+from prxref.orchestrator import orchestrate_review
+
+FIXTURE = Path(__file__).resolve().parent
+REPO = FIXTURE / "repo"
+DIFF = (FIXTURE / "pr.diff").read_text(encoding="utf-8")
+HEAD_SHA = "5eed20c0ffee20c0ffee20c0ffee20c0ffee2020"
+BASE_SHA = "ba5e20c0ffee20c0ffee20c0ffee20c0ffee2020"
+NO_FINDINGS = '{"findings": []}'
+MAX_CHUNKS = 32
+
+REF = PRRef(
+    forge="fake", host="example.com", owner="example", repo="shop",
+    number=20, url="https://example.com/example/shop/pull/20",
+)
+
+ORDER_MAPPER = "shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java"
+PRICE_CALCULATOR = "shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java"
+LEGACY_EXPORT = "shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java"
+STOCK_CLIENT = "inventory/src/main/java/com/example/inventory/StockClient.java"
+STOCK_REPORT = "inventory/src/main/kotlin/com/example/inventory/StockReport.kt"
+REPORT_WRITER = "inventory/reports/src/main/java/com/example/reports/ReportWriter.java"
+EXPORT_ORDERS = "tools/export_orders.py"
+CHANGED = (
+    ORDER_MAPPER, PRICE_CALCULATOR, LEGACY_EXPORT, STOCK_CLIENT, STOCK_REPORT, REPORT_WRITER, EXPORT_ORDERS,
+)
+
+DESIGN_POINTS = {
+    "fixture": (DIFF, {}),
+}
+
+CAPS_PATH = "caps/src/main/java/com/example/caps/Limits.java"
+CAPS_CONSTANTS = 45
+
+
+def _caps_text(body: list[str]) -> str:
+    lines = ["package com.example.caps;", "", "public class Limits {", ""]
+    for n in range(1, CAPS_CONSTANTS + 1):
+        lines += ["    @Deprecated", f"    public static final int LIMIT_{n:02d} = {n};", ""]
+    lines += ["    /**", "     * The sum of every limit.", "     */", "    public int sum() {"]
+    lines += body
+    lines += ["    }", "}"]
+    return "\n".join(lines) + "\n"
+
+
+def caps_design() -> tuple[str, dict[str, str]]:
+    """A one-file diff whose added lines reference ``CAPS_CONSTANTS`` annotated constants outside the hunk.
+
+    Returns ``(diff, overlay)``: the overlay serves the new ``Limits.java``.
+    """
+    names = [f"LIMIT_{n:02d}" for n in range(1, CAPS_CONSTANTS + 1)]
+    body = ["        int total = 0;"]
+    for start in range(0, len(names), 5):
+        body.append("        total += " + " + ".join(names[start:start + 5]) + ";")
+    body.append("        return total;")
+    base = _caps_text(["        return 0;"])
+    head = _caps_text(body)
+    lines = difflib.unified_diff(
+        base.splitlines(keepends=True), head.splitlines(keepends=True),
+        fromfile=f"a/{CAPS_PATH}", tofile=f"b/{CAPS_PATH}", n=3,
+    )
+    return f"diff --git a/{CAPS_PATH} b/{CAPS_PATH}\n" + "".join(lines), {CAPS_PATH: head}
+
+
+def make_pr() -> PRData:
+    """The fixture PR: fixed title, description, author, branches and 40-hex shas."""
+    return PRData(
+        title="Serialize orders and stock levels as JSON",
+        description="Adds Jackson to the shop and inventory modules and tightens the price total.",
+        author="example-dev",
+        source_branch="feature/json-export",
+        target_branch="main",
+        source_sha=HEAD_SHA,
+        target_sha=BASE_SHA,
+        raw={},
+    )
+
+
+class FixtureForge:
+    """A read-and-list forge over ``root`` plus ``overlay`` (path to text), recording every read and listing."""
+
+    name = "fake"
+
+    def __init__(
+        self, diff: str = DIFF, root: str | os.PathLike[str] = REPO, overlay: dict[str, str] | None = None,
+    ):
+        self.diff = diff
+        self.root = Path(root)
+        self.overlay = dict(overlay or {})
+        self.content_calls: list[str] = []
+        self.content_shas: set[str] = set()
+        self.list_calls = 0
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def parse_pr_url(url: str) -> PRRef | None:
+        """Never recognizes a URL."""
+        return None
+
+    def get_pr(self, ref: PRRef) -> PRData:
+        """The fixture PR."""
+        return make_pr()
+
+    def get_diff(self, ref: PRRef) -> str:
+        """The diff text, unmodified."""
+        return self.diff
+
+    def get_file_content(self, ref: PRRef, path: str, *, sha: str) -> str | None:
+        """The overlay's text for ``path``, else the tree's, else None; every call is recorded."""
+        with self._lock:
+            self.content_calls.append(path)
+            self.content_shas.add(sha)
+        if path in self.overlay:
+            return self.overlay[path]
+        target = self.root / path
+        return target.read_text(encoding="utf-8") if target.is_file() else None
+
+    def all_paths(self) -> tuple[str, ...]:
+        """Every file under ``root`` (dot files included) plus the overlay's paths, sorted."""
+        found = set(self.overlay)
+        for folder, _dirs, names in os.walk(self.root):
+            for name in names:
+                found.add(Path(folder, name).relative_to(self.root).as_posix())
+        return tuple(sorted(found))
+
+    def list_paths(self, ref: PRRef, *, sha: str):
+        """A complete ``PathListing`` of :meth:`all_paths`; every call is counted."""
+        from prxref.forges.base import PathListing
+
+        with self._lock:
+            self.list_calls += 1
+        return PathListing(paths=self.all_paths(), complete=True)
+
+    def list_threads(self, ref: PRRef) -> list:
+        """Always empty."""
+        return []
+
+    def post_summary(self, ref: PRRef, body: str) -> None:
+        """Always raises: the harness never posts."""
+        raise RuntimeError("the issue #20 harness never posts")
+
+    def post_inline_comments(self, ref: PRRef, comments) -> int:
+        """Always raises: the harness never posts."""
+        raise RuntimeError("the issue #20 harness never posts")
+
+
+class CapturingLLM:
+    """Records every ``(system, user)`` prompt, worker and sweep, and returns no findings."""
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, str]] = []
+        self._lock = threading.Lock()
+
+    def invoke(self, system, user, *, max_tokens=4096, json_mode=False, timeout_s=None):
+        """Record the prompt and answer ``{"findings": []}``."""
+        with self._lock:
+            self.calls.append((system, user))
+        return InvokeResult(
+            text=NO_FINDINGS, input_tokens=10, output_tokens=5,
+            model="fake-model", backend="fake", elapsed_ms=1,
+        )
+
+
+def review(forge=None, llm=None, *, ref: PRRef = REF, **kwargs):
+    """One ``orchestrate_review`` with ``post=False``, one file per chunk and ``MAX_CHUNKS`` unless overridden.
+
+    Returns ``(result, forge, llm)``.
+    """
+    forge = forge if forge is not None else FixtureForge()
+    llm = llm if llm is not None else CapturingLLM()
+    kwargs.setdefault("max_files_per_chunk", 1)
+    kwargs.setdefault("max_chunks", MAX_CHUNKS)
+    result = orchestrate_review(forge, ref, llm, post=False, **kwargs)
+    return result, forge, llm
+
+
+def golden_run(point: str, **kwargs) -> dict:
+    """One design point's ordered prompts and forge traffic, with ``max_workers=1``.
+
+    ``{"prompts": [{"system", "user"}, ...], "content_calls": [...], "list_calls": int}``
+    """
+    diff, overlay = DESIGN_POINTS[point]
+    forge = FixtureForge(diff, overlay=overlay)
+    _result, forge, llm = review(forge, max_workers=1, **kwargs)
+    return {
+        "prompts": [{"system": system, "user": user} for system, user in llm.calls],
+        "content_calls": list(forge.content_calls),
+        "list_calls": forge.list_calls,
+    }
diff --git a/tests/fixtures/issue20/make_golden.py b/tests/fixtures/issue20/make_golden.py
new file mode 100644
index 0000000..7999780
--- /dev/null
+++ b/tests/fixtures/issue20/make_golden.py
@@ -0,0 +1,82 @@
+"""Capture the issue #20 golden: the ordered worker and sweep prompts of the fixture review under 0.16.0.
+
+Run it against the RELEASED prxref 0.16.0 from PyPI, in an isolated
+environment and from a directory OUTSIDE the repository, so the tree's
+``src/`` is never on ``sys.path``::
+
+    cd /tmp && uv run --isolated --no-project --with prxref==0.16.0 \\
+        python /abs/path/to/tests/fixtures/issue20/make_golden.py /abs/path/to/golden_0_16_0.json
+
+It refuses to write anything unless ``prxref.__version__`` is ``0.16.0`` AND
+``prxref.__file__`` lies under ``site-packages``: the tree reports the same
+version until the release bumps it, so the version alone cannot tell an
+installed release from the source tree.
+
+It drives ``harness.py`` beside it, which uses only API that exists in both
+0.16.0 and the tip, once per design point with ``max_workers=1``, and writes
+the prompts plus the forge's read and listing calls as ASCII JSON. The file
+records the version and the fact that an installed distribution ran, never
+the path itself.
+
+``tests/test_issue_20_acceptance.py`` replays the same harness at the tip and
+compares: the Python control chunk and the sweep byte for byte, and every JVM
+chunk after removing the dependency and definition blocks 0.16.0 never
+rendered. Never regenerate the golden from the tree: a difference is a
+regression finding, not a stale file.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+RELEASE = "0.16.0"
+COMMAND = (
+    "cd /tmp && uv run --isolated --no-project --with prxref==0.16.0 "
+    "python tests/fixtures/issue20/make_golden.py golden_0_16_0.json (both paths absolute)"
+)
+
+
+def _harness():
+    path = Path(__file__).resolve().parent / "harness.py"
+    spec = importlib.util.spec_from_file_location("issue20_harness", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def main(argv: list[str]) -> int:
+    """Write the golden to ``argv[1]``; returns the exit status."""
+    if len(argv) != 2:
+        print("usage: make_golden.py OUT.json", file=sys.stderr)
+        return 2
+    for name in [name for name in os.environ if name.startswith("PRXREF_")]:
+        del os.environ[name]
+    import prxref
+
+    print(f"prxref.__version__ = {prxref.__version__}")
+    print(f"prxref.__file__ = {prxref.__file__}")
+    if prxref.__version__ != RELEASE:
+        raise SystemExit(f"refusing: prxref {prxref.__version__} is not the {RELEASE} release")
+    if "/site-packages/" not in prxref.__file__:
+        raise SystemExit("refusing: prxref was not imported from an installed distribution")
+    harness = _harness()
+    golden = {
+        "prxref_version": prxref.__version__,
+        "generated_from": "installed distribution",
+        "command": COMMAND,
+        "runs": {point: harness.golden_run(point) for point in harness.DESIGN_POINTS},
+    }
+    Path(argv[1]).write_text(
+        json.dumps(golden, indent=1, sort_keys=True, ensure_ascii=True) + "\n", encoding="utf-8",
+    )
+    for point, run in golden["runs"].items():
+        prompts, reads, lists = len(run["prompts"]), run["content_calls"], run["list_calls"]
+        print(f"{point}: {prompts} prompts, content_calls={reads}, list_calls={lists}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))
diff --git a/tests/fixtures/issue20/pr.diff b/tests/fixtures/issue20/pr.diff
new file mode 100644
index 0000000..bcfdb7d
--- /dev/null
+++ b/tests/fixtures/issue20/pr.diff
@@ -0,0 +1,145 @@
+diff --git a/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java b/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java
+--- a/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java
++++ b/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java
+@@ -1,8 +1,23 @@
+ package com.example.shop.api;
+ 
++import com.example.shop.core.Money;
++import com.fasterxml.jackson.databind.ObjectMapper;
++import java.util.List;
++import org.slf4j.Logger;
++import org.slf4j.LoggerFactory;
++
+ public class OrderMapper {
++
++    private static final Logger LOG = LoggerFactory.getLogger("orders");
++
++    private final ObjectMapper mapper = new ObjectMapper();
+ 
+     public String describe(int count) {
+         return "orders: " + count;
+     }
++
++    public String toJson(List<Money> totals) throws Exception {
++        LOG.debug("mapping {} totals", totals.size());
++        return mapper.writeValueAsString(totals);
++    }
+ }
+diff --git a/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java b/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java
+--- a/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java
++++ b/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java
+@@ -3,6 +3,7 @@
+ import com.fasterxml.jackson.annotation.JsonProperty;
+ import jakarta.annotation.Nullable;
+ import java.math.BigDecimal;
++import java.util.Objects;
+ import org.springframework.transaction.annotation.Transactional;
+ 
+ public class PriceCalculator {
+@@ -27,6 +28,11 @@
+     }
+ 
+     public BigDecimal total(BigDecimal unit, int items) {
+-        return unit.multiply(BigDecimal.valueOf(items));
++        Objects.requireNonNull(unit, "unit");
++        if (!open || items > MAX_ITEMS) {
++            throw new IllegalStateException("closed or too many items");
++        }
++        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);
++        return gross.add(gross.multiply(taxRate));
+     }
+ }
+diff --git a/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java b/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java
+--- a/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java
++++ b/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java
+@@ -1,8 +1,12 @@
+ package com.example.shop.legacy;
++
++import com.fasterxml.jackson.databind.ObjectMapper;
+ 
+ public class LegacyExport {
+ 
+-    public String export(Object order) {
+-        return String.valueOf(order);
++    private final ObjectMapper writer = new ObjectMapper();
++
++    public String export(Object order) throws Exception {
++        return writer.writeValueAsString(order);
+     }
+ }
+diff --git a/inventory/src/main/java/com/example/inventory/StockClient.java b/inventory/src/main/java/com/example/inventory/StockClient.java
+--- a/inventory/src/main/java/com/example/inventory/StockClient.java
++++ b/inventory/src/main/java/com/example/inventory/StockClient.java
+@@ -1,8 +1,17 @@
+ package com.example.inventory;
++
++import com.example.inventory.model.Sku;
++import com.fasterxml.jackson.databind.ObjectMapper;
+ 
+ public class StockClient {
+ 
+-    public String fetch(String sku) {
+-        return sku;
++    private final ObjectMapper json = new ObjectMapper();
++
++    public String fetch(Sku sku) throws Exception {
++        return json.writeValueAsString(sku);
++    }
++
++    public StockLevel parse(String body) throws Exception {
++        return json.readValue(body, StockLevel.class);
+     }
+ }
+diff --git a/inventory/src/main/kotlin/com/example/inventory/StockReport.kt b/inventory/src/main/kotlin/com/example/inventory/StockReport.kt
+--- a/inventory/src/main/kotlin/com/example/inventory/StockReport.kt
++++ b/inventory/src/main/kotlin/com/example/inventory/StockReport.kt
+@@ -1,5 +1,6 @@
+ package com.example.inventory
+ 
++import com.fasterxml.jackson.databind.ObjectMapper
+ import java.time.LocalDate
+ 
+ /**
+@@ -19,6 +20,7 @@
+     fun title(): String = "Stock on $day"
+ 
+     fun render(levels: List<StockLevel>): String {
+-        return title()
++        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }
++        return ObjectMapper().writeValueAsString(listOf(title()) + lines)
+     }
+ }
+diff --git a/inventory/reports/src/main/java/com/example/reports/ReportWriter.java b/inventory/reports/src/main/java/com/example/reports/ReportWriter.java
+--- a/inventory/reports/src/main/java/com/example/reports/ReportWriter.java
++++ b/inventory/reports/src/main/java/com/example/reports/ReportWriter.java
+@@ -1,8 +1,12 @@
+ package com.example.reports;
++
++import com.fasterxml.jackson.databind.ObjectMapper;
+ 
+ public class ReportWriter {
+ 
+-    public String write(Object report) {
+-        return String.valueOf(report);
++    private final ObjectMapper output = new ObjectMapper();
++
++    public String write(Object report) throws Exception {
++        return output.writeValueAsString(report);
+     }
+ }
+diff --git a/tools/export_orders.py b/tools/export_orders.py
+--- a/tools/export_orders.py
++++ b/tools/export_orders.py
+@@ -1,4 +1,5 @@
+ """Export orders to the reporting service."""
++import requests
+ 
+ TIMEOUT_SECONDS = 10
+ 
+@@ -13,4 +14,5 @@
+ 
+ 
+ def export(orders, url):
+-    return {"orders": orders, "url": url}
++    payload = build_payload(orders)
++    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)
diff --git a/tests/fixtures/issue20/repo/inventory/build.gradle.kts b/tests/fixtures/issue20/repo/inventory/build.gradle.kts
new file mode 100644
index 0000000..ed9125f
--- /dev/null
+++ b/tests/fixtures/issue20/repo/inventory/build.gradle.kts
@@ -0,0 +1,16 @@
+plugins {
+    java
+    kotlin("jvm") version "2.0.20"
+}
+
+group = "com.example.inventory"
+version = "1.4.0"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation(libs.jackson.databind)
+    implementation("com.example.inventory:inventory-model:1.4.0")
+}
diff --git a/tests/fixtures/issue20/repo/inventory/gradle/libs.versions.toml b/tests/fixtures/issue20/repo/inventory/gradle/libs.versions.toml
new file mode 100644
index 0000000..9b26a72
--- /dev/null
+++ b/tests/fixtures/issue20/repo/inventory/gradle/libs.versions.toml
@@ -0,0 +1,5 @@
+[versions]
+jackson = "2.16.1"
+
+[libraries]
+jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
diff --git a/tests/fixtures/issue20/repo/inventory/reports/build.gradle b/tests/fixtures/issue20/repo/inventory/reports/build.gradle
new file mode 100644
index 0000000..d9f36e7
--- /dev/null
+++ b/tests/fixtures/issue20/repo/inventory/reports/build.gradle
@@ -0,0 +1,3 @@
+this is not a build script (((
+dependencies {{{ implementation
+  ]]] >>> <<< ::: ;;;
diff --git a/tests/fixtures/issue20/repo/inventory/reports/src/main/java/com/example/reports/ReportWriter.java b/tests/fixtures/issue20/repo/inventory/reports/src/main/java/com/example/reports/ReportWriter.java
new file mode 100644
index 0000000..c5cf935
--- /dev/null
+++ b/tests/fixtures/issue20/repo/inventory/reports/src/main/java/com/example/reports/ReportWriter.java
@@ -0,0 +1,12 @@
+package com.example.reports;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public class ReportWriter {
+
+    private final ObjectMapper output = new ObjectMapper();
+
+    public String write(Object report) throws Exception {
+        return output.writeValueAsString(report);
+    }
+}
diff --git a/tests/fixtures/issue20/repo/inventory/src/main/java/com/example/inventory/StockClient.java b/tests/fixtures/issue20/repo/inventory/src/main/java/com/example/inventory/StockClient.java
new file mode 100644
index 0000000..837efdb
--- /dev/null
+++ b/tests/fixtures/issue20/repo/inventory/src/main/java/com/example/inventory/StockClient.java
@@ -0,0 +1,17 @@
+package com.example.inventory;
+
+import com.example.inventory.model.Sku;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public class StockClient {
+
+    private final ObjectMapper json = new ObjectMapper();
+
+    public String fetch(Sku sku) throws Exception {
+        return json.writeValueAsString(sku);
+    }
+
+    public StockLevel parse(String body) throws Exception {
+        return json.readValue(body, StockLevel.class);
+    }
+}
diff --git a/tests/fixtures/issue20/repo/inventory/src/main/kotlin/com/example/inventory/StockReport.kt b/tests/fixtures/issue20/repo/inventory/src/main/kotlin/com/example/inventory/StockReport.kt
new file mode 100644
index 0000000..acbd25c
--- /dev/null
+++ b/tests/fixtures/issue20/repo/inventory/src/main/kotlin/com/example/inventory/StockReport.kt
@@ -0,0 +1,26 @@
+package com.example.inventory
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import java.time.LocalDate
+
+/**
+ * Stock level reporting for the inventory service.
+ *
+ * Levels are rendered one per line, lowest stock first.
+ */
+
+data class StockLevel(val sku: String, val onHand: Int)
+
+fun formatLevel(level: StockLevel): String {
+    return "${level.sku}: ${level.onHand}"
+}
+
+class StockReport(private val day: LocalDate) {
+
+    fun title(): String = "Stock on $day"
+
+    fun render(levels: List<StockLevel>): String {
+        val lines = levels.sortedBy(StockLevel::onHand).map { formatLevel(it) }
+        return ObjectMapper().writeValueAsString(listOf(title()) + lines)
+    }
+}
diff --git a/tests/fixtures/issue20/repo/shop/pom.xml b/tests/fixtures/issue20/repo/shop/pom.xml
new file mode 100644
index 0000000..8eb20d0
--- /dev/null
+++ b/tests/fixtures/issue20/repo/shop/pom.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.example.shop</groupId>
+  <artifactId>shop-parent</artifactId>
+  <version>1.0.0</version>
+  <packaging>pom</packaging>
+
+  <modules>
+    <module>shop-api</module>
+    <module>shop-legacy</module>
+  </modules>
+
+  <properties>
+    <jackson.version>2.17.2</jackson.version>
+    <spring-boot.version>3.3.4</spring-boot.version>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>com.fasterxml.jackson.core</groupId>
+        <artifactId>jackson-databind</artifactId>
+        <version>${jackson.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-dependencies</artifactId>
+        <version>${spring-boot.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+</project>
diff --git a/tests/fixtures/issue20/repo/shop/shop-api/pom.xml b/tests/fixtures/issue20/repo/shop/shop-api/pom.xml
new file mode 100644
index 0000000..6408c58
--- /dev/null
+++ b/tests/fixtures/issue20/repo/shop/shop-api/pom.xml
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>com.example.shop</groupId>
+    <artifactId>shop-parent</artifactId>
+    <version>1.0.0</version>
+  </parent>
+  <artifactId>shop-api</artifactId>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.example.shop</groupId>
+      <artifactId>shop-core</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+    </dependency>
+  </dependencies>
+</project>
diff --git a/tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java b/tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java
new file mode 100644
index 0000000..543a921
--- /dev/null
+++ b/tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/api/OrderMapper.java
@@ -0,0 +1,23 @@
+package com.example.shop.api;
+
+import com.example.shop.core.Money;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.List;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class OrderMapper {
+
+    private static final Logger LOG = LoggerFactory.getLogger("orders");
+
+    private final ObjectMapper mapper = new ObjectMapper();
+
+    public String describe(int count) {
+        return "orders: " + count;
+    }
+
+    public String toJson(List<Money> totals) throws Exception {
+        LOG.debug("mapping {} totals", totals.size());
+        return mapper.writeValueAsString(totals);
+    }
+}
diff --git a/tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java b/tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java
new file mode 100644
index 0000000..c8225d1
--- /dev/null
+++ b/tests/fixtures/issue20/repo/shop/shop-api/src/main/java/com/example/shop/pricing/PriceCalculator.java
@@ -0,0 +1,38 @@
+package com.example.shop.pricing;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.annotation.Nullable;
+import java.math.BigDecimal;
+import java.util.Objects;
+import org.springframework.transaction.annotation.Transactional;
+
+public class PriceCalculator {
+
+    @Deprecated
+    public static final int MAX_ITEMS = 50;
+
+    @Nullable
+    @JsonProperty("rate")
+    private BigDecimal taxRate;
+
+    private boolean open;
+
+    @Transactional
+    public BigDecimal applyDiscount(BigDecimal amount, int items) {
+        BigDecimal factor = items > 10 ? new BigDecimal("0.95") : BigDecimal.ONE;
+        return amount.multiply(factor);
+    }
+
+    public void setOpen(boolean value) {
+        this.open = value;
+    }
+
+    public BigDecimal total(BigDecimal unit, int items) {
+        Objects.requireNonNull(unit, "unit");
+        if (!open || items > MAX_ITEMS) {
+            throw new IllegalStateException("closed or too many items");
+        }
+        var gross = applyDiscount(unit.multiply(BigDecimal.valueOf(items)), items);
+        return gross.add(gross.multiply(taxRate));
+    }
+}
diff --git a/tests/fixtures/issue20/repo/shop/shop-legacy/pom.xml b/tests/fixtures/issue20/repo/shop/shop-legacy/pom.xml
new file mode 100644
index 0000000..0fa5978
--- /dev/null
+++ b/tests/fixtures/issue20/repo/shop/shop-legacy/pom.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>com.example.shop</groupId>
+    <artifactId>shop-parent</artifactId>
+    <version>1.0.0</version>
+  </parent>
+  <artifactId>shop-legacy</artifactId>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+  </dependencies>
+</project>
diff --git a/tests/fixtures/issue20/repo/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java b/tests/fixtures/issue20/repo/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java
new file mode 100644
index 0000000..04eae1d
--- /dev/null
+++ b/tests/fixtures/issue20/repo/shop/shop-legacy/src/main/java/com/example/shop/legacy/LegacyExport.java
@@ -0,0 +1,12 @@
+package com.example.shop.legacy;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public class LegacyExport {
+
+    private final ObjectMapper writer = new ObjectMapper();
+
+    public String export(Object order) throws Exception {
+        return writer.writeValueAsString(order);
+    }
+}
diff --git a/tests/fixtures/issue20/repo/tools/export_orders.py b/tests/fixtures/issue20/repo/tools/export_orders.py
new file mode 100644
index 0000000..3e9b5e3
--- /dev/null
+++ b/tests/fixtures/issue20/repo/tools/export_orders.py
@@ -0,0 +1,18 @@
+"""Export orders to the reporting service."""
+import requests
+
+TIMEOUT_SECONDS = 10
+
+
+def build_payload(orders):
+    """Shape the orders for the reporting endpoint."""
+    return {"orders": list(orders)}
+
+
+def unused_helper():
+    return None
+
+
+def export(orders, url):
+    payload = build_payload(orders)
+    return requests.post(url, json=payload, timeout=TIMEOUT_SECONDS)
diff --git a/tests/fixtures/issue20/repo/tools/pyproject.toml b/tests/fixtures/issue20/repo/tools/pyproject.toml
new file mode 100644
index 0000000..ca15b0f
--- /dev/null
+++ b/tests/fixtures/issue20/repo/tools/pyproject.toml
@@ -0,0 +1,4 @@
+[project]
+name = "shop-tools"
+version = "0.1.0"
+dependencies = ["requests==2.32.3"]
diff --git a/tests/test_issue_20_acceptance.py b/tests/test_issue_20_acceptance.py
new file mode 100644
index 0000000..ebad9e7
--- /dev/null
+++ b/tests/test_issue_20_acceptance.py
@@ -0,0 +1,400 @@
+"""Issue #20 acceptance: JVM chunk context through the real ``orchestrate_review``, end to end.
+
+Every test drives ``orchestrate_review`` over ``tests/fixtures/issue20`` through
+the version-neutral harness in ``tests/fixtures/issue20/harness.py``: a
+read-and-list fake forge that records every ``get_file_content`` and
+``list_paths`` call, and an LLM that captures every worker and sweep prompt and
+answers with no findings. The reviewer is the real one, ``post`` is false and
+every changed file is its own chunk. Each test asserts on what a user sees: the
+prompts, the forge's reads, the run record and the trace.
+
+The fixture holds a Maven build (``shop/``: a parent with a property and a BOM
+import, a module whose ``jackson-databind`` has no version, and a module whose
+``pom.xml`` is malformed), a Gradle build (``inventory/``: a version catalog
+reached through ``version.ref``, and a ``reports`` subproject whose
+``build.gradle`` is garbage) and a Python control (``tools/``).
+
+The regression golden, ``golden_0_16_0.json``, was captured from the RELEASED
+prxref 0.16.0 by ``make_golden.py`` (its docstring has the command); it is
+never regenerated from the tree. No test touches the network.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from pathlib import Path
+
+import pytest
+
+from prxref import jvm_lang
+from prxref.chunk_context import (
+    DEFINITIONS_HEADER,
+    DEPENDENCY_HEADER,
+    MAX_DEFINITION_CHARS,
+    MAX_DEFINITION_ENTRIES,
+    chunk_files,
+)
+from prxref.triage import build_chunks, parse_unified_diff
+from tests.fixtures.issue20.harness import (
+    CAPS_CONSTANTS,
+    CAPS_PATH,
+    CHANGED,
+    DIFF,
+    EXPORT_ORDERS,
+    FIXTURE,
+    LEGACY_EXPORT,
+    MAX_CHUNKS,
+    ORDER_MAPPER,
+    PRICE_CALCULATOR,
+    REPO,
+    REPORT_WRITER,
+    STOCK_CLIENT,
+    STOCK_REPORT,
+    FixtureForge,
+    caps_design,
+    golden_run,
+    review,
+)
+
+GOLDEN = json.loads((FIXTURE / "golden_0_16_0.json").read_text(encoding="utf-8"))
+OUTPUT_HEADER = "\n\n## Output Format"
+ELLIPSIS = "\N{HORIZONTAL ELLIPSIS}"
+JVM_CHANGED = (ORDER_MAPPER, PRICE_CALCULATOR, LEGACY_EXPORT, STOCK_CLIENT, STOCK_REPORT, REPORT_WRITER)
+BUILD_FILES = ("pom.xml", "build.gradle", "build.gradle.kts", "libs.versions.toml")
+
+JACKSON_MAVEN = "com.fasterxml.jackson.core:jackson-databind@2.17.2"
+SLF4J_MANAGED = "org.slf4j:slf4j-api@(managed by org.springframework.boot:spring-boot-dependencies@3.3.4)"
+JACKSON_GRADLE = "com.fasterxml.jackson.core:jackson-databind@2.16.1"
+
+PRICE_ENTRIES = [
+    f"{PRICE_CALCULATOR}:11:     @Deprecated\n"
+    "    public static final int MAX_ITEMS = 50;",
+    f"{PRICE_CALCULATOR}:14:     @Nullable\n"
+    '    @JsonProperty("rate")\n'
+    "    private BigDecimal taxRate;",
+    f"{PRICE_CALCULATOR}:20:     @Transactional\n"
+    "    public BigDecimal applyDiscount(BigDecimal amount, int items) {\n"
+    '        BigDecimal factor = items > 10 ? new BigDecimal("0.95") : BigDecimal.ONE;\n'
+    "        return amount.multiply(factor);\n"
+    "    }",
+]
+KOTLIN_ENTRIES = [
+    f"{STOCK_REPORT}:12: data class StockLevel(val sku: String, val onHand: Int)",
+    f"{STOCK_REPORT}:14: fun formatLevel(level: StockLevel): String {{\n"
+    '    return "${level.sku}: ${level.onHand}"\n'
+    "}",
+]
+OWN_FILE_DEFINITIONS = [(PRICE_CALCULATOR, 11), (PRICE_CALCULATOR, 14), (PRICE_CALCULATOR, 20),
+                        (STOCK_REPORT, 12), (STOCK_REPORT, 14)]
+
+
+def _owner(user: str) -> str:
+    (owner,) = [path for path in CHANGED if f"diff --git a/{path} " in user]
+    return owner
+
+
+def _worker_prompts(calls) -> dict[str, tuple[str, str]]:
+    """Each chunk's one worker ``(system, user)``, keyed by the chunk's file; the sweep (always last) is left out."""
+    *workers, _sweep = calls
+    prompts: dict[str, tuple[str, str]] = {}
+    for system, user in workers:
+        owner = _owner(user)
+        assert owner not in prompts, f"{owner} was prompted twice"
+        prompts[owner] = (system, user)
+    assert set(prompts) == set(CHANGED)
+    return prompts
+
+
+def _users(llm) -> dict[str, str]:
+    return {path: user for path, (_system, user) in _worker_prompts(llm.calls).items()}
+
+
+def _block(prompt: str, header: str) -> str:
+    """The prompt's ``header`` block, header included, up to the next block or the output section; "" if absent."""
+    if header not in prompt:
+        return ""
+    start = prompt.index(header)
+    ends = [
+        end for end in (prompt.find("\n\n### ", start + len(header)), prompt.find(OUTPUT_HEADER, start))
+        if end >= 0
+    ]
+    return prompt[start:min(ends)]
+
+
+def _dependency_lines(prompt: str) -> list[str]:
+    block = _block(prompt, DEPENDENCY_HEADER)
+    return block.split("\n\n", 1)[1].split("\n") if block else []
+
+
+def _definitions(prompt: str) -> str:
+    block = _block(prompt, DEFINITIONS_HEADER)
+    return block.split("\n\n", 1)[1] if block else ""
+
+
+def _events(path: Path) -> list[dict]:
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def _is_jvm_read(path: str) -> bool:
+    return path.endswith((".java", ".kt")) or path.rsplit("/", 1)[-1] in BUILD_FILES
+
+
+def _file_line(path: str, number: int) -> str:
+    return (REPO / path).read_text(encoding="utf-8").splitlines()[number - 1]
+
+
+def _added(path: str) -> tuple[str, ...]:
+    (entry,) = [f for f in chunk_files(parse_unified_diff(DIFF)) if f.path == path]
+    return entry.added
+
+
+@pytest.fixture(scope="module")
+def regression_runs() -> tuple[dict, dict]:
+    """``(golden, tip)``: the 0.16.0 fixture run from the golden file and the same run at the tip."""
+    return GOLDEN["runs"]["fixture"], golden_run("fixture")
+
+
+class TestChunking:
+    """The fixture chunks one file per chunk, and no expected definition sits inside a hunk."""
+
+    def test_each_changed_file_is_its_own_chunk(self):
+        chunks = build_chunks(parse_unified_diff(DIFF), max_chunks=MAX_CHUNKS, max_files_per_chunk=1)
+        assert len(chunks) == len(CHANGED) == 7
+        assert sorted(f.path for chunk in chunks for f in chunk) == sorted(CHANGED)
+        assert all(len(chunk) == 1 for chunk in chunks)
+
+    def test_the_review_prompts_every_chunk_once_plus_the_sweep(self):
+        _result, _forge, llm = review(max_workers=1)
+        assert len(llm.calls) == len(CHANGED) + 1
+        _worker_prompts(llm.calls)
+
+    def test_every_expected_definition_lies_outside_its_hunks(self):
+        hunks = {f.path: f.hunk_lines for f in chunk_files(parse_unified_diff(DIFF))}
+        for path, line in OWN_FILE_DEFINITIONS + [(PRICE_CALCULATOR, 18), (EXPORT_ORDERS, 7)]:
+            assert line not in hunks[path], (path, line)
+
+
+class TestMavenDependencyVersions:
+    """A versionless module dependency resolves through the parent's property; a BOM-managed one names the BOM."""
+
+    def test_the_module_prompt_carries_the_resolved_and_the_managed_line(self):
+        _result, forge, llm = review(max_workers=1)
+        assert _dependency_lines(_users(llm)[ORDER_MAPPER]) == [JACKSON_MAVEN, SLF4J_MANAGED]
+        assert {"shop/shop-api/pom.xml", "shop/pom.xml"} <= set(forge.content_calls)
+
+    def test_the_module_pom_declares_jackson_without_a_version(self):
+        child = (REPO / "shop/shop-api/pom.xml").read_text(encoding="utf-8")
+        jackson = child.split("<artifactId>jackson-databind</artifactId>", 1)[1].split("</dependency>", 1)[0]
+        assert "<version>" not in jackson
+        parent = (REPO / "shop/pom.xml").read_text(encoding="utf-8")
+        assert "<jackson.version>2.17.2</jackson.version>" in parent
+        assert "<type>pom</type>" in parent and "<scope>import</scope>" in parent
+
+
+class TestGradleDependencyVersions:
+    """A catalog alias resolves through ``version.ref``, for a Java and a Kotlin file of the module."""
+
+    def test_the_java_and_kotlin_prompts_carry_the_catalog_version(self):
+        _result, forge, llm = review(max_workers=1)
+        users = _users(llm)
+        assert _dependency_lines(users[STOCK_CLIENT]) == [JACKSON_GRADLE]
+        assert _dependency_lines(users[STOCK_REPORT]) == [JACKSON_GRADLE]
+        assert "inventory/gradle/libs.versions.toml" in forge.content_calls
+
+    def test_the_catalog_uses_version_ref(self):
+        catalog = (REPO / "inventory/gradle/libs.versions.toml").read_text(encoding="utf-8")
+        assert 'version.ref = "jackson"' in catalog
+        assert "libs.jackson.databind" in (REPO / "inventory/build.gradle.kts").read_text(encoding="utf-8")
+
+
+class TestSkippedImports:
+    """A JDK import and an import of the build's own group yield no dependency line, though both are declared."""
+
+    def test_the_maven_module_skips_java_util_and_its_own_group(self):
+        assert "import java.util.List;" in _added(ORDER_MAPPER)
+        assert "import com.example.shop.core.Money;" in _added(ORDER_MAPPER)
+        assert "<artifactId>shop-core</artifactId>" in (REPO / "shop/shop-api/pom.xml").read_text(encoding="utf-8")
+        _result, _forge, llm = review(max_workers=1)
+        lines = _dependency_lines(_users(llm)[ORDER_MAPPER])
+        assert not [line for line in lines if line.startswith(("java.", "com.example.shop:"))]
+
+    def test_the_gradle_module_skips_its_own_group(self):
+        assert "import com.example.inventory.model.Sku;" in _added(STOCK_CLIENT)
+        build = (REPO / "inventory/build.gradle.kts").read_text(encoding="utf-8")
+        assert 'group = "com.example.inventory"' in build and "com.example.inventory:inventory-model" in build
+        _result, _forge, llm = review(max_workers=1)
+        assert not [line for line in _dependency_lines(_users(llm)[STOCK_CLIENT]) if "com.example.inventory" in line]
+
+    def test_a_file_adding_only_a_jdk_import_reads_no_build_file(self):
+        assert "import java.util.Objects;" in _added(PRICE_CALCULATOR)
+        _result, forge, llm = review(max_workers=1)
+        assert DEPENDENCY_HEADER not in _users(llm)[PRICE_CALCULATOR]
+        folder = PRICE_CALCULATOR.rsplit("/", 1)[0]
+        assert not [path for path in forge.content_calls if path.startswith(folder + "/") and path != PRICE_CALCULATOR]
+
+
+class TestDefinitions:
+    """A constant, a field and a method outside the hunks, each from its first annotation line; no keyword."""
+
+    def test_the_java_prompt_carries_all_three_entries_from_the_first_annotation(self):
+        for line, annotation in ((11, "@Deprecated"), (14, "@Nullable"), (20, "@Transactional")):
+            assert _file_line(PRICE_CALCULATOR, line).strip() == annotation
+        _result, _forge, llm = review(max_workers=1)
+        assert _definitions(_users(llm)[PRICE_CALCULATOR]) == "\n".join(PRICE_ENTRIES)
+
+    def test_a_keyword_named_field_is_never_a_referenced_name(self):
+        assert _file_line(PRICE_CALCULATOR, 18).strip() == "private boolean open;"
+        assert any("!open" in text for text in _added(PRICE_CALCULATOR))
+        assert "open" in jvm_lang.JAVA_KEYWORDS and jvm_lang.JAVA_FIELD_RE.match(_file_line(PRICE_CALCULATOR, 18))
+        _result, _forge, llm = review(max_workers=1)
+        prompt = _users(llm)[PRICE_CALCULATOR]
+        assert f"{PRICE_CALCULATOR}:18: " not in prompt
+        assert "private boolean open;" not in _definitions(prompt)
+
+
+class TestKotlinDefinitions:
+    """A Kotlin added line referencing a ``fun`` and a ``class`` outside its hunk gets both."""
+
+    def test_the_kotlin_prompt_carries_the_class_and_the_fun(self):
+        _result, _forge, llm = review(max_workers=1)
+        assert _definitions(_users(llm)[STOCK_REPORT]) == "\n".join(KOTLIN_ENTRIES)
+
+
+class TestBrokenBuilds:
+    """A malformed ``pom.xml`` and a garbage ``build.gradle`` yield no dependency line, and the review completes."""
+
+    def test_no_dependency_line_and_the_broken_build_files_were_read(self):
+        _result, forge, llm = review(max_workers=1)
+        users = _users(llm)
+        assert DEPENDENCY_HEADER not in users[LEGACY_EXPORT]
+        assert DEPENDENCY_HEADER not in users[REPORT_WRITER]
+        assert {"shop/shop-legacy/pom.xml", "inventory/reports/build.gradle"} <= set(forge.content_calls)
+
+    def test_the_run_record_the_trace_and_the_log_show_a_completed_review(self, tmp_path, caplog):
+        trace = tmp_path / "trace.jsonl"
+        with caplog.at_level(logging.DEBUG, logger="prxref"):
+            result, _forge, _llm = review(max_workers=1, trace_file=str(trace))
+        assert result["chunks_failed"] == 0
+        events = _events(trace)
+        steps = [(e["node"], e["phase"]) for e in events]
+        assert ("chunk", "fail") not in steps
+        assert steps.count(("run", "ok")) == 1
+        chunk_events = [(e["phase"], e["meta"]) for e in events if e["node"] == "chunk"]
+        started = {meta["index"]: meta["files"] for phase, meta in chunk_events if phase == "start"}
+        finished = [meta["index"] for phase, meta in chunk_events if phase == "ok"]
+        assert sorted(finished) == sorted(started) == list(range(1, len(CHANGED) + 1))
+        assert sorted(path for files in started.values() for path in files) == sorted(CHANGED)
+        records = [r for r in caplog.records if r.name.startswith("prxref")]
+        assert not [r.getMessage() for r in records if r.levelno >= logging.WARNING]
+        assert not [r.getMessage() for r in records if "chunk context unavailable" in r.getMessage()]
+
+    def test_control_without_the_broken_files_the_walk_reaches_the_enclosing_build(self, tmp_path):
+        root = tmp_path / "repo"
+        shutil.copytree(REPO, root)
+        (root / "shop/shop-legacy/pom.xml").unlink()
+        (root / "inventory/reports/build.gradle").unlink()
+        _result, _forge, llm = review(FixtureForge(root=root), max_workers=1)
+        users = _users(llm)
+        assert _dependency_lines(users[LEGACY_EXPORT]) == [JACKSON_MAVEN]
+        assert _dependency_lines(users[REPORT_WRITER]) == [JACKSON_GRADLE]
+
+
+class TestNoRegressionAgainstTheReleased016:
+    """Against the 0.16.0 golden: the Python control and the sweep are byte-identical; JVM chunks only gain blocks."""
+
+    EXPECTED_BLOCKS = {
+        ORDER_MAPPER: {DEPENDENCY_HEADER},
+        PRICE_CALCULATOR: {DEFINITIONS_HEADER},
+        LEGACY_EXPORT: set(),
+        STOCK_CLIENT: {DEPENDENCY_HEADER},
+        STOCK_REPORT: {DEPENDENCY_HEADER, DEFINITIONS_HEADER},
+        REPORT_WRITER: set(),
+    }
+
+    def test_the_golden_came_from_the_installed_release(self):
+        assert GOLDEN["prxref_version"] == "0.16.0"
+        assert GOLDEN["generated_from"] == "installed distribution"
+
+    def test_the_python_control_and_the_sweep_are_byte_identical(self, regression_runs):
+        golden, tip = regression_runs
+        golden_calls = [(p["system"], p["user"]) for p in golden["prompts"]]
+        tip_calls = [(p["system"], p["user"]) for p in tip["prompts"]]
+        assert len(tip_calls) == len(golden_calls) == len(CHANGED) + 1
+        assert [_owner(user) for _s, user in tip_calls[:-1]] == [_owner(user) for _s, user in golden_calls[:-1]]
+        assert _worker_prompts(tip_calls)[EXPORT_ORDERS] == _worker_prompts(golden_calls)[EXPORT_ORDERS]
+        assert DEPENDENCY_HEADER in _worker_prompts(golden_calls)[EXPORT_ORDERS][1]
+        assert DEFINITIONS_HEADER in _worker_prompts(golden_calls)[EXPORT_ORDERS][1]
+        assert tip_calls[-1] == golden_calls[-1]
+
+    @pytest.mark.parametrize("path", JVM_CHANGED)
+    def test_a_jvm_chunk_differs_only_by_the_added_blocks(self, regression_runs, path):
+        golden, tip = regression_runs
+        golden_system, golden_user = _worker_prompts([(p["system"], p["user"]) for p in golden["prompts"]])[path]
+        tip_system, tip_user = _worker_prompts([(p["system"], p["user"]) for p in tip["prompts"]])[path]
+        assert tip_system == golden_system
+        assert DEPENDENCY_HEADER not in golden_user and DEFINITIONS_HEADER not in golden_user
+        stripped = tip_user
+        removed = set()
+        for header in (DEPENDENCY_HEADER, DEFINITIONS_HEADER):
+            block = _block(tip_user, header)
+            if block:
+                assert stripped.count("\n\n" + block) == 1
+                stripped = stripped.replace("\n\n" + block, "", 1)
+                removed.add(header)
+        assert removed == self.EXPECTED_BLOCKS[path]
+        assert stripped == golden_user
+
+    def test_every_read_0_16_0_made_is_made_again_and_the_rest_are_jvm(self, regression_runs):
+        golden, tip = regression_runs
+        assert [path for path in tip["content_calls"] if not _is_jvm_read(path)] == golden["content_calls"]
+        assert not [path for path in golden["content_calls"] if _is_jvm_read(path)]
+        assert tip["list_calls"] == golden["list_calls"]
+
+
+@pytest.mark.parametrize("mode", ["diff", "repo"])
+class TestNoDuplicatesAcrossSources:
+    """With repository context on, each own-file JVM definition is rendered once, while a cross-chunk one appears."""
+
+    def test_each_own_file_definition_appears_exactly_once(self, mode):
+        _result, _forge, llm = review(max_workers=1, repo_context=mode)
+        users = _users(llm)
+        counts = {(path, line): users[path].count(f"{path}:{line}: ") for path, line in OWN_FILE_DEFINITIONS}
+        assert counts == {key: 1 for key in OWN_FILE_DEFINITIONS}
+        assert _definitions(users[PRICE_CALCULATOR]) == "\n".join(PRICE_ENTRIES)
+        assert _definitions(users[STOCK_REPORT]) == "\n".join(KOTLIN_ENTRIES)
+
+    def test_control_the_cross_chunk_source_is_live_and_renders_once(self, mode):
+        entry = f"{STOCK_REPORT}:12: "
+        _result, _forge, off = review(max_workers=1)
+        assert entry not in _users(off)[STOCK_CLIENT]
+        _result, _forge, llm = review(max_workers=1, repo_context=mode)
+        assert _users(llm)[STOCK_CLIENT].count(entry) == 1
+
+
+@pytest.mark.parametrize("mode", ["off", "diff", "repo"])
+class TestTheDefinitionCapHolds:
+    """A Java file referencing more annotated constants than the entry cap renders the cap plus an omission line."""
+
+    def test_the_cap_and_the_omission_line(self, mode):
+        assert CAPS_CONSTANTS > MAX_DEFINITION_ENTRIES == 40
+        diff, overlay = caps_design()
+        _result, _forge, llm = review(FixtureForge(diff, overlay=overlay), max_workers=1, repo_context=mode)
+        (_system, user), _sweep = llm.calls
+        lines = _definitions(user).split("\n")
+        heads = [line for line in lines if line.startswith(f"{CAPS_PATH}:")]
+        assert len(heads) == MAX_DEFINITION_ENTRIES
+        assert heads == [f"{CAPS_PATH}:{5 + 3 * n}:     @Deprecated" for n in range(MAX_DEFINITION_ENTRIES)]
+        assert lines[-1] == f"{ELLIPSIS} {CAPS_CONSTANTS - MAX_DEFINITION_ENTRIES} more definitions omitted"
+        assert "LIMIT_40 = 40;" in user.split(DEFINITIONS_HEADER, 1)[1]
+        assert "LIMIT_41 = 41;" not in user.split(DEFINITIONS_HEADER, 1)[1]
+        assert len(_definitions(user)) < MAX_DEFINITION_CHARS
+
+    def test_every_constant_is_referenced_on_an_added_line(self, mode):
+        diff, _overlay = caps_design()
+        (entry,) = chunk_files(parse_unified_diff(diff))
+        referenced = {
+            name for text in entry.added for name in text.replace(";", " ").replace("+", " ").split()
+            if name.startswith("LIMIT_")
+        }
+        assert sorted(referenced) == [f"LIMIT_{n:02d}" for n in range(1, CAPS_CONSTANTS + 1)]

From 4553cef18c00d57c74d08c3c93486cf3a1c382af Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 22:20:12 -0700
Subject: [PATCH 23/25] release: 0.17.0 version bump, CHANGELOG date and
 handoff
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bump pyproject.toml, prxref.__version__ and the uv.lock prxref stanza to
0.17.0. Date the [0.17.0] CHANGELOG section 2026-09-25, point [Unreleased]
at v0.17.0...HEAD and add the [0.17.0] link.

Correct the PRXREF_REPO_CONTEXT row of docs/env-vars.md: off adds no
repository context, but chunk context's Java and Kotlin definitions and
dependency versions do not depend on it, so off is no longer byte-identical
to 0.15.0; and diff finds Kotlin type declarations as well as Java ones.

Rewrite HANDOFF.md for 0.17.0: the module map for Java and Kotlin chunk
context (#20), the parse retry (#21) and the shared-state readers and
pinned-off toggle check (#22, parts 2 and 3), the lessons, the config key
counts (68 keys, 69 accepted names), the release shape, the live check,
and what is still open, including #22 part 1.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 CHANGELOG.md           |   5 +-
 HANDOFF.md             | 717 ++++++++++++++++++++++-------------------
 docs/env-vars.md       |   2 +-
 pyproject.toml         |   2 +-
 src/prxref/__init__.py |   2 +-
 uv.lock                |   2 +-
 6 files changed, 387 insertions(+), 343 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f42064..cb09607 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 Issue numbers in entries before 0.14.0 refer to the project's previous issue
 tracker.
 
-## [0.17.0] — YYYY-MM-DD
+## [0.17.0] — 2026-09-25
 
 Java and Kotlin chunk context (#20), a bounded retry for unusable model replies
 (#21), and code that reads the state a change writes (#22, parts 2 and 3). A
@@ -1949,7 +1949,8 @@ Development baseline. Never published to PyPI and never tagged; superseded by
 - Diff content is sent to whichever OpenAI-compatible endpoint you configure.
 - Requires Python 3.12+. Tested on 3.12 and 3.13.
 
-[Unreleased]: https://github.com/sblattj/prxref/compare/v0.16.0...HEAD
+[Unreleased]: https://github.com/sblattj/prxref/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/sblattj/prxref/releases/tag/v0.17.0
 [0.16.0]: https://github.com/sblattj/prxref/releases/tag/v0.16.0
 [0.15.0]: https://github.com/sblattj/prxref/releases/tag/v0.15.0
 [0.14.0]: https://github.com/sblattj/prxref/releases/tag/v0.14.0
diff --git a/HANDOFF.md b/HANDOFF.md
index a8d6a30..3a3b12b 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -1,193 +1,204 @@
-# HANDOFF — v0.16.0 shipped: repository context
+# HANDOFF — v0.17.0 shipped: JVM chunk context, parse retry, shared-state readers
 
 **Repo:** `sblattj/prxref` (public) · **Released:** 2026-09-25 · **Supersedes** the
-v0.15.0 handoff.
-
-0.16.0 lets a chunk worker see code outside its own hunks (#17): definitions
-from the pull request's other files and from files the diff never touches, and
-excerpts of the API and database contracts a change points at.
-`PRXREF_REPO_CONTEXT` turns it on at `diff` or `repo`. It is off by default,
-and at `off` the prompts, posted comments, trace and logs are byte-identical to
-0.15.0. The release also retries an empty model reply once. The user-facing
-account is the `[0.16.0]` section of `CHANGELOG.md`. This file is for whoever
-cuts the next release. The v0.15.0 handoff is in git history.
+v0.16.0 handoff.
+
+0.17.0 gives a chunk worker Java and Kotlin chunk context (#20): for a changed
+`.java`, `.kt` or `.kts` file, the definitions its added lines reference from
+the rest of that file and the Maven or Gradle versions of what they import, at
+every `PRXREF_REPO_CONTEXT` level. A model reply that cannot be used as a
+review is sent again, up to `PRXREF_LLM_PARSE_RETRIES` times, default 1 (#21).
+At `PRXREF_REPO_CONTEXT=repo` a chunk also sees unchanged code that reads the
+state its added lines write, and a new deterministic check, always on, flags a
+toggle that ships on while the pull request's own test setup pins it off (#22,
+parts 2 and 3). `off` still adds no repository context, but a pull request with
+Java or Kotlin files gets new prompt blocks and forge reads with every setting
+at its default, and a `{}` reply now costs a second call. The user-facing
+account is the `[0.17.0]` section of `CHANGELOG.md`. This file is for whoever
+cuts the next release. The v0.16.0 handoff is in git history.
 
 ## What landed
 
-- **#17 Repository context, as a module map.** The first five modules below
-  do no I/O and import nothing from `prxref.forges`: they take a
-  `read(path)` callable plus plain data.
-  - `repo_unit.build_unit_context` is the place to start. It builds one
-    chunk's `UnitContext` from the sources below, ranks the entries by
-    `repo_context.REASONS` (`cross-chunk`, `contract`, `diff-file`, `import`,
-    `path-convention`, `name-search`), admits them into
-    `PRXREF_REPO_CONTEXT_MAX_CHARS`, and writes the `… N more context entries
-    omitted` line. `repo_unit.MODES` is the vocabulary: `off`, `diff`, `repo`.
-  - `repo_context`: `ContextEntry`, `find_definitions`, `language_of`
-    (`chunk_context`'s map plus `.java`, with `_JAVA_DEF_RE` for type
-    declarations), and the exclude floor, `EXCLUDE_FLOOR` and
-    `exclude_predicate`.
-  - `repo_crosschunk.diff_definitions`: definitions from the pull request's
-    other files, and, for a type another chunk changes, up to
-    `MAX_CHANGE_LINES` of its changed lines.
-  - `repo_resolve.resolve_candidates`: files outside the diff, found through
-    imports (Java, Python, TypeScript and JavaScript), Java's same-package
-    path convention, and the name search over the listing.
-  - `repo_contracts`: `contract_triggers` reads routes, operation ids, tables
-    and schema names off the added lines; `select_contract_files` and
-    `earlier_migrations` pick the files; `contract_excerpts` dispatches to the
-    OpenAPI, JSON Schema, SQL and Liquibase excerpters.
-  - `repo_reader.RepoReader` is the one reader a run shares, built by
-    `forge_reader` or `repo_dir_reader`. It fetches each path and the listing
-    at most once, single-flight across threads, and keeps the counters behind
-    the record's `reads` and `read_cap_hit`.
-  - `forges/repo_dir.RepoDir` reads and lists a `--repo-dir` checkout.
-  - `forges/base.PathListing(paths, complete)` and the optional
-    `Forge.list_paths(ref, *, sha)`, implemented by all five adapters.
-    `forges/replay.ReplayForge.list_paths` delegates at the pinned head.
-  - `orchestrator`: `_plan_repo_context` builds the run's reader, takes the
-    listing and selects the contract files once, and logs `repo`'s one
-    WARNING; `_routed_read` routes each read (lesson 3); each
-    chunk worker calls `repo_unit.build_unit_context`; `_repo_context_record`
-    and `_unit_row` build the record, `retry_dropped` included; and the
-    `chunk context` and `repo_context ok` trace events.
-  - `chunk_context.render_context_blocks` takes `extra_def_lines` and
-    `contract_lines`, the second under the new `CONTRACT_HEADER`
-    (`### Contract excerpts`). With both empty its output is unchanged.
-  - `cli`: `--repo-dir` (`_open_repo_dir`, which exits 2 before any network
-    call), the `repo_context` JSON key after `rule_counts`, and the `-v` line
-    (`_repo_context_line`).
-  - `eval_cases` and `evals`: a case's `repo_dir` field or `case-*/repo/`
-    directory, and four more `evals.RUN_CONFIG_KEYS` (16 in all).
-- **Entry points and caps.**
-  - `orchestrate_review` takes `repo_context="off"`,
-    `repo_context_max_chars=12000`, `context_contract_globs=()`,
-    `context_exclude_globs=()` and `repo_dir=None`. `cli._run_review` passes
-    the four config values by name, and `repo_dir` from `--repo-dir` or the
-    eval case.
-  - Reads: `repo_reader.MAX_CHUNK_READS` (16) and `MAX_RUN_READS` (200) cap
-    the reads of paths outside the pull request; its own files are uncapped.
-  - Listing: `forges/base.MAX_LISTING_PAGES` (20) pages; `RepoDir` lists at
-    most 100,000 files (`forges/repo_dir._MAX_LISTED_FILES`); Bitbucket Cloud
-    walks at `max_depth=64` (`forges/bitbucket._LISTING_MAX_DEPTH`).
-  - Contracts: `repo_contracts.MAX_SPEC_FILES` (6), `MAX_EARLIER_MIGRATIONS`
-    (4), `MAX_CONTRACT_LINES` (40) and `MAX_CONTRACT_CHARS` (2,000).
-  - Definitions: `repo_resolve.MAX_NAME_SEARCH_PER_NAME` (3) and
-    `repo_crosschunk.MAX_CHANGE_LINES` (12).
-  - Files over 512 KiB read as missing, on every forge and in `--repo-dir`
-    (`forges/repo_dir._MAX_FILE_CONTENT_BYTES`).
-- **GitLab lists through GraphQL.** `forges/gitlab.py` `list_paths` walks
-  `project.repository.tree(recursive: true).blobs`, 100 files a page
-  (`_list_paths_graphql`). It falls back to the REST
-  `repository/tree?recursive=true` walk (`_list_paths_rest`) only when the
-  first GraphQL page is unusable, including the empty page GraphQL answers
-  for a sha it cannot resolve. A later GraphQL page that fails returns the
-  paths read so far with `complete=False`. Lesson 1 says why.
-- **An empty model reply is retried once.** `reviewer._invoke_and_parse` asks
-  again, with the same prompt and budget, when `_is_empty_reply` holds and the
-  provider did not stop at the budget (`finish_reason` `length` or
-  `max_tokens`). Chunks and the sweep share the path. `_fold_retry_usage` sums
-  both calls' tokens and costs, and the unit's `model` is the second call's. A
-  retry that raises fails the unit and keeps the first call's usage. The worst
-  case is 4 `llm.invoke` calls for a chunk (this retry times the
-  orchestrator's one timeout retry) and 2 for the sweep.
-- **Config went from 63 to 67 keys.** The four new keys:
-  - `PRXREF_REPO_CONTEXT` (`off`, `diff` or `repo`; default `off`)
-  - `PRXREF_REPO_CONTEXT_MAX_CHARS` (default 12,000; must be above 0)
-  - `PRXREF_CONTEXT_CONTRACT_GLOBS` (default the built-in set; a set value
-    replaces it)
-  - `PRXREF_CONTEXT_EXCLUDE_GLOBS` (default empty; adds to the always-on
-    floor)
-
-  The last three do nothing while `PRXREF_REPO_CONTEXT` is `off`, its
-  default. No existing config default changed.
+- **#20 Java and Kotlin chunk context, as a module map.** Four new modules,
+  stdlib only, that do no I/O except through a `read(path)` callable:
+  - `jvm_lang`: `jvm_language` (`.java` gives `java`, `.kt` and `.kts` give
+    `kotlin`, in any case), `definition_regexes` (Java types, methods, fields
+    and constants, and enum constants; Kotlin types, `fun`, and `val` and
+    `var`), `annotation_start`, `parse_imports`, `keywords` and `JDK_NAMES`.
+  - `jvm_maven.resolve_pom`: a `pom.xml` through its `<properties>`, its
+    parent chain inside the repository, `<dependencyManagement>` and imported
+    BOMs.
+  - `jvm_gradle.gradle_build`: string-notation dependencies, `platform`,
+    `enforcedPlatform` and `mavenBom` as BOM owners, and the
+    `libs.versions.toml` catalog, probed at `catalog_paths` only when the
+    build file mentions `libs.`.
+  - `jvm_deps.dependency_lines`: finds the nearest build file
+    (`_nearest_manifest`, trying `MANIFEST_NAMES` at each level from the
+    file's directory up to the root), then matches the added lines' imports
+    to its dependencies, skipping `SKIPPED_ROOTS` and the project's own group.
+
+  How they reach the prompt: `chunk_context._language` now asks
+  `jvm_lang.jvm_language`; `chunk_context.dependency_versions` hands a Java or
+  Kotlin file to `jvm_deps.dependency_lines`, and skips `build.gradle.kts` and
+  `settings.gradle.kts` (`_GRADLE_SCRIPTS`) without a read; and
+  `chunk_context.referenced_definitions` uses `jvm_lang`'s regexes and starts
+  an entry at the annotation lines above a definition. Both run in
+  `orchestrator._context_blocks`, over the reader that
+  `orchestrator._make_file_reader` builds. `orchestrate_review` builds that
+  reader before, and outside, its `repo_context != "off"` gate, so these
+  blocks and their reads happen at every level, `off` included, whenever the
+  forge has `get_file_content` and the pull request has a head sha. The
+  reader is cached per run and is not counted against the repository-context
+  read caps.
+- **#20 in repository context.** `repo_context.language_of` claims `.kt` and
+  `.kts` as `kotlin`, and `repo_context.definition_regexes` gives Kotlin one
+  regex, `jvm_lang.KOTLIN_TYPE_RE`, for type declarations only, as Java has
+  one for its types. Methods, functions and properties stay with chunk
+  context. `repo_context` keeps the 0.16.0 Java names (`_JAVA_DEF_RE`,
+  `_JAVA_KEYWORDS`, `_JDK_NAMES`) as aliases of `jvm_lang`'s objects.
+- **Who shows a chunk file's own definitions.** Chunk context and repository
+  context both serve definitions, and they split by name, not by file
+  (lesson 3). `repo_crosschunk._SAME_FILE_LANGUAGES` is `js`, `python`,
+  `java` and `kotlin`. With a reader, `repo_crosschunk.diff_definitions`
+  searches a chunk file in one of those languages only for the wanted names
+  that are not identifiers on that file's own added lines, because
+  `chunk_context.referenced_definitions` already shows those. A name that
+  only another file of the chunk references is still found there, as a
+  `diff-file` entry, and a file with no name left is skipped without a read.
+- **#21 `PRXREF_LLM_PARSE_RETRIES`.** `reviewer._invoke_and_parse` holds the
+  whole mechanism, for chunks and the sweep alike.
+  - `_read_reply` classifies a reply and `_may_retry` spends one shared
+    budget, N. Retried: an empty reply, one that does not parse, one that is
+    not a JSON object and, at N of 1 or more only, an object without a
+    `findings` list (`_NO_FINDINGS_ERROR`). An empty reply keeps 0.16.0's one
+    retry even at N = 0.
+  - Never retried: a reply the provider stopped at the budget
+    (`_TRUNCATION_FINISH_REASONS`, `length` or `max_tokens`) and a call that
+    raised.
+  - A unit makes at most `1 + max(N, 1)` calls, so with the orchestrator's
+    timeout retry a chunk tops out at `2 * (1 + max(N, 1))`: 4 at the
+    default, as in 0.16.0.
+  - `_fold_retry_usage` sums every call's tokens and time, and the unit's
+    `model` is the last call's. A traced unit that retried keeps
+    `<label>.attempt<K>.response.json` for each discarded reply, and its meta
+    gains `parse_retries` and `first_error`, which `orchestrator._retry_meta`
+    carries into the worker result.
+  - `orchestrate_review` (`llm_parse_retries`), `review_chunk` and
+    `review_systemic` default to 0 for library callers. `cli._run_review`
+    passes the config value, so `prxref review`, the webhook server and
+    `prxref eval run` get 1.
+- **#21 recording and the judge.**
+  - The run record and `--format json` gain `parse_retries`, right after
+    `repo_context` (`cli._build_json_result`): `null` at N = 0, otherwise
+    `orchestrator._parse_retry_total` over every chunk and the sweep.
+  - `eval_judge.judge_case` retries on any `JudgeParseError`, truncation
+    included, up to N times, and `JudgeOutcome.parse_retries` counts them. At
+    N = 0 an empty judge reply gets no retry. `score.json`'s `judge` block
+    gains `parse_retries` after `llm_calls`, and `score.md`'s cost line names
+    the retries only when there were any.
+  - `evals.RUN_CONFIG_KEYS` gains `llm_parse_retries`, 17 keys in all.
+- **#22 part 2, shared-state readers.** `repo_readers` is new and pure.
+  - `shared_state_keys` takes the keys the added lines write: subscript
+    stores, and calls of a `WRITE_VERBS` verb, through a local alias. A key
+    the added lines assign a new value is skipped.
+  - `reader_candidates` orders the listed, unchanged, same-language files by
+    shared leading directories; `reader_matches` finds the reads (`.key`,
+    `["key"]`, or `key.<method>(` with a method that is not a write verb);
+    `reader_entries` runs the search and cuts each excerpt from the enclosing
+    definition down to the read.
+  - `repo_unit.build_unit_context` calls it at `repo` only, with a file
+    listing, after the resolver, on the reads the other sources leave.
+    `repo_context.KINDS` gains `reader`, and `REASONS` gains `shared-state`,
+    ranked last so the budget cuts it first.
+  - `chunk_context.render_context_blocks` takes `reader_lines` and renders
+    them last, under `READER_HEADER` (`### Code elsewhere that reads state
+    this chunk writes`). With it empty, the output is unchanged.
+- **#22 part 3, the pinned-off toggle.**
+  `heuristics.toggle_pinned_off_findings(files)` is pure and always on. It
+  posts one `warning` at confidence 1.0 on a toggle the pull request adds
+  with a default of on, when the pull request also adds a line to
+  `conftest.py`, `setupTests.*`, `jest.setup.*` or `vitest.setup.*` that pins
+  it off. The body ends `(deterministic check, no model)`. `orchestrate_review`
+  folds it in beside the release-shape finding, on the main path and on the
+  path for a diff with no chunks, so it goes through every quality pass.
+- **Caps**, each read from its constant.
+  - Chunk context, unchanged: `chunk_context.MAX_DEFINITION_ENTRIES` (40),
+    `MAX_LINES_PER_DEFINITION` (6, annotation lines included),
+    `MAX_DEFINITION_CHARS` (8,000) and `MAX_FILE_BYTES` (512 KiB).
+    `jvm_lang.MAX_ANNOTATION_LINES` (2) bounds the annotation lines an entry
+    starts at.
+  - Maven: `jvm_maven.MAX_POM_BYTES` (512 KiB), `MAX_POM_PARENTS` (5),
+    `MAX_PROPERTY_PASSES` (5) and `MAX_INTERPOLATED_CHARS` (1,024). A
+    `pom.xml` that holds `<!DOCTYPE` or `<!ENTITY` is refused before the XML
+    parser runs.
+  - Dependency matching: `jvm_deps.MIN_GROUP_PREFIX_SEGMENTS` (2) and
+    `MIN_SHARED_SEGMENTS` (3).
+  - Readers: `repo_readers.MAX_READER_ENTRIES` (6), `MAX_READER_SCAN` (24)
+    and `MAX_READER_LINES` (8), within `repo_reader.MAX_CHUNK_READS` (16) and
+    `MAX_RUN_READS` (200). They are module constants with no config key, and
+    setting `MAX_READER_ENTRIES` to 0 turns readers off with no read.
+- **Config went from 67 to 68 keys.** The one new key is
+  `PRXREF_LLM_PARSE_RETRIES` (integer, at least 0, no upper bound, default 1).
+  No existing config default changed.
 
 ## What this release taught
 
 Written down because each one cost real time.
 
-1. **A live listing check found what the fakes could not.** GitLab's REST
-   `repository/tree?recursive=true` returns every directory before any file,
-   across the whole recursive walk. On gitlab-org/gitlab, all 2,100 entries
-   read (the 20-page cap plus one probe page) were directories, so the capped
-   walk listed 0 files. GraphQL's `tree.blobs` lists files only, and the same
-   project now lists 2,000 files. A fake built from the documented response
-   shape carries no ordering; record a real response past the page cap before
-   trusting a paged walk.
-2. **"Off is byte-identical" is proven against the previous release, never
-   the tree.** `tests/fixtures/issue17/golden_off_prompts.json` was captured
-   by `make_golden.py` under `uv run --no-project --with prxref==0.15.0`, from
-   outside the repository. `TestOffMatchesTheReleased015` compares the tip's
-   `off` prompts and reads with it byte for byte, over two design points and
-   three keyword-argument variants.
-   - `test_the_golden_is_a_0_15_0_oracle_that_exercises_the_old_blocks` pins
-     the golden's provenance: `prxref_version` and `generated_from:
-     installed distribution`.
-   - `test_control_the_same_comparison_fails_for_repo` shows the comparison
-     can fail.
-   - A golden written from the tree would only compare the tree with itself.
-     When a later release changes an `off` prompt on purpose, capture the
-     golden again the same way, from the release the claim is now made
-     against, and move the version the provenance test pins.
-3. **Reads of the pull request's own files are uncapped.** With one per-chunk
-   cap for every read, a chunk with many diff files spent its 16 reads before
-   it reached its contract file. `orchestrator._routed_read` now sends diff
-   paths to the uncapped `RepoReader.read`, and only other paths to the
-   capped `chunk_reader`. `TestReadCapStarvation` in
-   `tests/test_issue_17_acceptance.py` pins it, with a control that routes
-   every read through the capped reader and loses the spec. It also removed a
-   dependence on thread scheduling: which chunk reads a shared diff file first
-   no longer changes any chunk's entries.
-4. **A thinking model needs more than prxref's defaults.** GLM 5.3 Flash with
-   thinking on, reached through a reasoning lane in llm-ferry, did not fit
-   `PRXREF_LLM_MAX_TOKENS` 4096 and `PRXREF_LLM_TIMEOUT` 45.
-   - At 4,096 tokens a smoke call stopped with `finish_reason=length`: one
-     spent 4,094 tokens on reasoning and returned no answer, another spent
-     3,902 and returned a cut-off one.
-   - On the #17 eval fixture, 16,384 tokens and a 600 s timeout completed
-     every call. The largest reply used 11,433 completion tokens.
-   - On a larger pull request, 16,384 tokens was not enough: a chunk of
-     11,161 input tokens ran out of room after 357 s. At 32,768 tokens and a
-     900 s timeout the same chunk completed in 345 s, with 15,265 output
-     tokens.
-   - Single calls took 90 to 390 s.
-
-   The timeout retry drops the repository-context blocks, so a timeout that
-   is too short quietly removes the feature. One small probe, 4 calls a
-   point, is an observation, not a measurement: `reasoning_effort` `low` and
-   unset gave overlapping reasoning-token ranges (212 to 800 and 496 to
-   1,054), and a request with thinking disabled was answered by a different
-   model.
-5. **`-v` summary lines are text output only.** With `--format json`,
-   `cli._cmd_review` prints the JSON object and skips `_print_summary`, as
-   0.15.0 already did for every `-v` line. A live check scripted against
-   `--format json -v` found no `repo context:` line. Read the `repo_context`
-   key instead, or check the line through `cli._repo_context_line`
-   (`TestVerboseLine` in `tests/test_cli_repo_context.py`).
-6. **Know what repository context cannot reach.**
-   - The name search matches a file name in the same language (ignoring
-     case, and also in snake case for Python), never file content. A type
-     declared in a differently named file is not found (`TestNameSearch` in
-     `tests/test_repo_context_resolve.py`).
-   - Only chunk workers get repository context. The sweep prompt is the same
-     at every level: `test_control_the_same_comparison_fails_for_repo` finds
-     every worker prompt changed at `repo` and the sweep's unchanged.
-
-   A check that looks for either finds nothing, by design.
-7. **A new run-record or JSON key moves twelve test pins in five files.**
-   0.15.0's count of eight in three files was already short: the #12 and #18
-   tests pin the key order too.
-   - `tests/test_orchestrator.py`: three `set(res) == {...}` literals and
-     `RESULT_KEYS`.
-   - `tests/test_run_record.py`: `RECORD_KEYS` and `NULL_WHEN_OFF`.
-   - `tests/test_cli_output.py`: `JSON_KEYS` and `NEW_RECORD_KEYS`.
-   - `tests/test_orchestrator_rule_cap.py`: `TestJsonOutput`'s next-key
-     assertion, and `TestOffPathMatchesBase`'s key set and JSON key list.
-   - `tests/test_cli_scoped_rules.py`: `TestJson`'s `sampling` offset.
-
-   A keyword argument that the CLI builds rather than reads from config, as
-   `repo_dir` is, must also be named in
-   `test_run_review_passes_every_configured_orchestrate_kwarg`.
+1. **A golden "from the released version" can silently be the tree.** Run
+   inside the checkout, `uv run --no-project --with prxref==0.16.0` imported
+   the working tree's prxref, whose `__version__` read 0.16.0 until this
+   commit bumped it. The first cross-check of the parse retry against 0.16.0
+   therefore compared the tree with itself, and its 0 differences meant
+   nothing. Only `prxref.__file__`, `src/` rather than `site-packages`,
+   showed it. The fix is in `tests/fixtures/issue20/make_golden.py`: run from
+   outside the repository with `uv run --isolated --no-project --with
+   prxref==0.16.0`, and refuse to write unless `prxref.__file__` is under
+   `/site-packages/` as well as the version matching. Assert where the module
+   came from, never only its version string.
+2. **"Off is byte-identical" was a claim about prompts, and #17's test also
+   pinned forge reads.** Java and Kotlin chunk context added 23 `off` reads
+   to the #17 fixture, 21 build-file probes over 7 directory levels and its
+   two Java files, while every `off` prompt stayed byte-identical to
+   0.15.0's. `TestOffMatchesTheReleased015` in
+   `tests/test_issue_17_acceptance.py` went red 12 times, on the read pins
+   alone. It now compares the prompts with the 0.15.0 golden byte for byte
+   and the reads only after leaving out JVM paths (`_is_jvm`);
+   `test_off_jvm_reads_are_the_pinned_list` pins those reads literally
+   (`JVM_READS`), and `test_the_golden_reads_no_jvm_path` proves the filter
+   hides nothing the golden holds. When a feature adds reads on purpose,
+   split the pin by what changed; regenerating the golden would stop it
+   being a 0.15.0 oracle.
+3. **Two sources that serve definitions must split by name, not by file.**
+   Chunk context now shows a Java or Kotlin file's own definitions, so
+   repository context had to stop repeating them. Leaving every chunk file in
+   a same-file language out of `repo_crosschunk.diff_definitions` did that,
+   but it also lost a definition that one file of a chunk references and
+   another file of the same chunk holds outside its hunks, and 7 tests beyond
+   the #17 read pins went red. The rule that shipped leaves out only the
+   names on a file's own added lines (What landed). `TestTheChunksOwnFiles`
+   in `tests/test_repo_context_crosschunk.py` pins it for Java, Kotlin,
+   Python and JavaScript, and it fixed the same gap in 0.16.0's Python and
+   JavaScript handling (CHANGELOG `[0.17.0]`, Fixed).
+4. **The parse retry changes behaviour at its default, and `0` is exactly
+   0.16.0.** At `PRXREF_LLM_PARSE_RETRIES=1` a `{}` reply costs a second call,
+   and the unit fails if that reply has no `findings` list either, where
+   0.16.0 counted a clean review. `TestZeroIsTheOldBehaviour` in
+   `tests/test_issue_21_acceptance.py` pins `0`. A one-off cross-check ran 6
+   reply scenarios through the tree at `0` and through the released 0.16.0,
+   installed as lesson 1 says, and found 0 differences in exit code, calls
+   per unit, request bodies and JSON output. The control, the tree at `1`,
+   differed in 5 of the 6. A custom worker or systemic template whose reply
+   drops `findings` now fails every unit, and no template check catches it.
+5. **The reader block made a missed bug an asserted one, once.** On issue
+   #22's own fixture through GLM 5.3 Flash (N=3 per arm, interleaved, one
+   factor varied), the shared-state reader block turned the serialization
+   bug from absent or dropped under the confidence floor (0 of 3 active)
+   into an active error-severity finding (3 of 3), for 216 more input tokens
+   per review. The history-window bug surfaced in 3 of 3 runs with readers,
+   but always under the 0.60 floor. The toggle check fired in all 6 runs.
+   Three runs an arm on one fixture is a first measurement, not a verdict on
+   the feature (Live checks).
 
 ## The coupling that will catch the next person adding a config key
 
@@ -209,55 +220,61 @@ together:
 A key that feeds `orchestrate_review` needs one more step. `tests/test_cli.py`
 (`test_run_review_passes_every_configured_orchestrate_kwarg`) requires
 `cli._run_review` to pass every orchestrator kwarg whose name equals a config
-key. All 4 keys 0.16.0 added feed it this way. Current values: **67** keys,
-**1** legacy alias, **68** accepted names.
+key. The one key 0.17.0 added, `llm_parse_retries`, feeds it this way, and
+`prxref eval score` also reads it for the judge. Current values: **68** keys,
+**1** legacy alias, **69** accepted names.
 
 ## Release shape (follow this next time)
 
-How 0.16.0 was built:
-
-1. **One map and one decisions file first.** #17 got a read-only map of the
-   code it would touch. A decisions file then settled every open question
-   before any code was written: off by default, `diff` without a reader
-   still adds its hunk-based entries, `list_paths` on all five adapters,
-   `--repo-dir` and the eval field, the contract glob set, the 512 KiB
-   ceiling and the 12,000-character budget. It also gave each new module one
-   owner and fixed the shared interface names, so parallel tasks merged
-   clean.
-2. **Foundation.** One task landed all four config keys on every surface,
-   off by default, before any feature work started.
+How 0.17.0 was built:
+
+1. **One survey and one decisions file first.** A read-only survey of the
+   code #20, #21 and #22 would touch came first, down to the test pins each
+   change would move. A decisions file then settled every open question
+   before any code was written: keep the 0.15.0 `off` golden and re-scope
+   its read check rather than regenerate it; put the JVM parsing in new
+   stdlib leaf modules, because `chunk_context` cannot import `repo_context`
+   without a cycle; the groupId matching rule; one shared parse-retry budget
+   that keeps 0.16.0's empty-reply retry, with library callers at 0; readers
+   inside repository context, at `repo` only and ranked last; the toggle as a
+   deterministic check rather than a prompt hint; and #22 part 1 deferred.
+   It also gave each new module one owner.
+2. **Foundation.** One task landed `PRXREF_LLM_PARSE_RETRIES` on every config
+   surface, and it merged first, before the wiring that reads it.
 3. **Pure modules first, wiring last.** Tasks ran in rounds of parallel
    agents, each agent in its own worktree against a pinned base commit. Each
-   task was rated at most 5 of 10 for complexity and brought its own new
-   test file. 20 tasks merged in seven rounds:
-   - 6: the config keys, the definitions core, the contract excerpters, the
-     `list_paths` Protocol with GitHub's listing, the `--repo-dir` reader,
-     and the acceptance fixture repository
-   - 5: the resolver, the cross-chunk definitions, the run reader, and the
-     listings of the other four forges
-   - 2: the contract triggers and file selection, and the eval case field
-   - 1: the per-chunk unit context
-   - 2: the orchestrator wiring, and the GitLab GraphQL listing that the
-     listing check brought in
-   - 3: the CLI and eval wiring, the acceptance tests through
-     `orchestrate_review`, and the empty-reply retry
-   - 1: the user documentation and the CHANGELOG section
+   task was rated at most 5 of 10 for complexity, and each code task brought
+   its own tests. 20 tasks merged in five rounds:
+   - 7: the config key, the JVM language module, the Maven parser, the Gradle
+     parser, the reviewer's parse retry, the shared-state reader search, and
+     the toggle check
+   - 4: the JVM dependency matcher, the orchestrator and CLI threading of the
+     retry budget with its record key, the judge's retry, and the reader
+     wiring into the unit context
+   - 5: the chunk-context JVM wiring with the own-file rule, Kotlin in
+     repository context, the eval recording, the #21 acceptance tests, and
+     the toggle wiring
+   - 1: the #22 acceptance tests over the issue's own fixture
+   - 3: the #17 acceptance re-scope (lesson 2), the #20 acceptance tests
+     against a golden from the released 0.16.0 (lesson 1), and the user
+     documentation with the CHANGELOG section
 4. **One integration gate per merge.** Each branch merged into `release/X.Y.Z`
-   on its own. A merge stayed only if the full `uv run pytest` and
-   `uv run ruff check src tests` passed on the merged tree. Over the 20
-   merges the passing count rose from 6,797 at 0.15.0 to 7,675 and never
-   fell; the documentation merge, the last, added no tests.
-5. **Read-only live checks.** They ran against public repositories and pull
-   requests, with a guard that blocked forge writes, and reviews used one
-   model through one lane. Three ran: the listing on four live forges once
-   the listing tasks merged, then, once the wiring merged, `prxref eval` on
-   the #17 fixture and the bundled cases, and a review of one public pull
-   request end to end. The listing check found the GitLab ordering of lesson
-   1, which brought in the GraphQL walk before release, and GitLab was
-   checked again after it.
-6. **Release.** This commit bumps the version, dates the CHANGELOG and
-   rewrites this file, after the documentation task wrote the CHANGELOG
-   section.
+   on its own, and the 0.16.0 release commit was merged in after the first.
+   A merge stayed only if the full `uv run pytest` and
+   `uv run ruff check src tests` passed on the merged tree, with one
+   exception. The chunk-context JVM wiring was first held at 19 failures
+   (lesson 3), came back with 12, every one an `off` read pin in
+   `tests/test_issue_17_acceptance.py` with every prompt intact (lesson 2),
+   and merged with those 12 known, because the next round's re-scope owned
+   them. That re-scope turned them green: 8,660 passed, 0 failed. Over the 20
+   merges the passing count rose from 7,675 at 0.16.0 to 8,695 and never
+   fell; the documentation merge added no tests.
+5. **One read-only live check**, once the reader and toggle wiring merged:
+   the reader block against no reader on #22's fixture, through one model
+   and one lane, with a guard that blocked forge writes (Live checks).
+6. **Release.** This commit bumps the version, dates the CHANGELOG, corrects
+   the `PRXREF_REPO_CONTEXT` row of `docs/env-vars.md` and rewrites this
+   file, after the documentation task wrote the CHANGELOG section.
 
 Cutting the release:
 
@@ -283,9 +300,9 @@ pattern does not match GitHub's auto-generated source archive.
 ## Verified at release
 
 ```
-7675 passed                                   uv run pytest -q
+8695 passed                                   uv run pytest -q
 All checks passed!                            uv run ruff check src tests
-0.16.0                                        uv run prxref --version
+0.17.0                                        uv run prxref --version
 ```
 
 These counts come from the release branch, measured at the commit that last
@@ -293,113 +310,136 @@ updated this file.
 
 ### Live checks
 
-- **`list_paths` on four live forges.** 19 of 19 checks passed, with no LLM
-  call. Each listing matched a raw walk exactly: sblattj/prxref on GitHub
-  (229 paths), gitlab-org/gitlab-test on GitLab (40, its 3 submodules
-  dropped), atlassian/forge-bitbucket-related-prs on Bitbucket Cloud (20),
-  and dnceng-public/public's dotnet-public-wiki on Azure DevOps (5). An
-  all-zero sha gave `None` on all four, reads were pinned to the head, and
-  torvalds/linux's truncated tree came back `complete=False` (67,498 of
-  71,638 entries). Before the GraphQL walk, gitlab-org/gitlab listed 0 files
-  (lesson 1). Bitbucket Server has no public instance to check.
-- **GitLab after the GraphQL walk.** Without a token, gitlab-org/gitlab-test
-  listed 40 paths, complete, in 0.4 s, and gitlab-org/gitlab listed 2,000
-  paths in 57.4 s, stopped at the 20-page cap and marked incomplete. GitLab's
-  GraphQL endpoint honours `PRIVATE-TOKEN`: an invalid token gets 401, and no
-  header gets 200.
-- **`prxref eval` on the #17 fixture and the bundled cases**, GLM 5.3 Flash
-  through `domestic.flash`, which served every call (19 of 19 header probes,
-  0 fallbacks). 9 runs made 28 LLM calls with no failed case, at
-  `PRXREF_LLM_MAX_TOKENS=16384` and `PRXREF_LLM_TIMEOUT=600`; at prxref's
-  default of 4,096 tokens a smoke call was cut off (lesson 4).
-  - The fixture ran 3 times at `off` and 3 times at `repo`, reading its
-    `repo_dir`. Within each level the prompts were byte-identical. Between
-    the levels only the chunk prompt differed, by the added
-    repository-context block (62 lines, `### Contract excerpts` among them).
-  - The reader, the contract entries and the `off` null held in every run.
-    Each `repo` record named the `repo-dir` reader, its one chunk carried
-    both the `connectors.yaml` OpenAPI excerpt for the Java service and the
-    earlier migration for the SQL file, and every `off` record held
-    `repo_context: null`. The fixture's three files fit in one chunk at
-    default chunking, and the cross-chunk link needs two chunks: a run with
-    one file per chunk (3 chunks) confirmed it, with each contract entry in
-    its own file's chunk.
-  - An HTTP 201 status code that exists only in the injected OpenAPI excerpt
-    appeared in the findings of all 3 `repo` runs and of none of the 3 `off`
-    runs. The labels could not separate the levels: one matched in 0 of 3
-    runs at `off` and 1 of 3 at `repo`, the other in none at either.
-  - On the three bundled cases, `diff` added no entry (single-file diffs, no
-    reader) and sent byte-identical prompts. Recall was 7 of 8 at both
-    levels, with two labels flipping in opposite directions.
-  - Each `run.json` recorded all 16 `RUN_CONFIG_KEYS`, the four new ones
-    included.
-- **End to end on sblattj/multi-auto-claude-sub#5** (9 files, TypeScript),
-  GLM 5.3 Flash through `domestic.flash`, which served every call (8 of 8
-  header probes, 0 fallbacks).
-  - `off` gave `repo_context: null`.
-  - `repo`, through the GitHub forge and through `--repo-dir`, built the same
-    110 entries over 2 chunks, from a complete 64-path listing, with 22 reads
-    and no cap hit. 26 definitions from outside the diff reached the prompts,
-    25 through imports and 1 through the name search. 1 entry was left out
-    under the 12,000-character budget, with its marker line.
-  - It needed `PRXREF_LLM_MAX_TOKENS=32768` and `PRXREF_LLM_TIMEOUT=900`
-    (lesson 4); at 16,384 an `off` run lost one of its two chunks.
-  - Findings: 2 at `off`, 3 through the forge and 0 through `--repo-dir`. The
-    last two runs sent identical prompts (27,466 input tokens each), so a
-    single run's finding count cannot measure the feature's effect.
-  - The forge run made 28 content reads for 22 paths: the double fetch in the
-    CHANGELOG's known limitations. The repository has no contract files, so
-    contract excerpts were not exercised live, and the empty-reply retry did
-    not fire.
+- **Shared-state readers on issue #22's own fixture**, GLM 5.3 Flash through
+  llm-ferry (`domestic.flash`), on the local CLI path (`--diff-file`,
+  `--repo-dir`, `--description-file`) at `PRXREF_REPO_CONTEXT=repo`,
+  `PRXREF_LLM_MAX_TOKENS=32768` and `PRXREF_LLM_TIMEOUT=900`. One factor
+  varied: arm A set `repo_readers.MAX_READER_ENTRIES` to 0, and arm B kept
+  the default of 6. The runs were interleaved, A B A B A B, N=3 per arm, with
+  no re-rolls.
+  - The reader block reached a prompt only in B: 1 of each run's 3 prompts,
+    the chunk holding `progress.py`.
+  - The serialization bug went from absent or dropped under the 0.60
+    confidence floor (0 of 3 active in A; dropped at 0.50 in 2) to an active
+    error-severity finding in 3 of 3 B runs.
+  - The history-window bug surfaced in 3 of 3 B runs and in none of A's,
+    always dropped at 0.50 under the 0.60 floor: the block made the model see
+    it, not assert it (Still open).
+  - The toggle check fired in all 6 runs, on the same line.
+  - Cost: 216 more input tokens per review (+2.8%). Output tokens overlap
+    between the arms.
+  - The parse retry never fired: 0 retries and 0 failed chunks in 6 runs,
+    with no malformed reply seen.
+  - GLM served every run. llm-ferry's log shows no fallback in the run
+    window, and a probe after the runs reported 0 attempted fallbacks. No
+    probe was taken before the runs; the log window stands in for it.
+  - The write guard was active in all 6 runs.
 
 ## Still open — not part of this release
 
-- **#20 JVM chunk context.** `chunk_context._language` still gives `.java` and
-  `.kt` no language, so the dependency-versions and same-file definitions
-  blocks skip JVM files at every level. Repository context adds Java type
-  declarations only (`repo_context.language_of`, `_JAVA_DEF_RE`). Methods,
-  fields, constants, Kotlin, and Maven or Gradle versions are open.
-- **#21 A reply that does not parse is not retried.** The reviewer retries
-  only an empty reply (`reviewer._invoke_and_parse`, `_is_empty_reply`). A
-  reply that fails to parse, parses to a non-object, or has no `findings`
-  list still fails its unit.
-- **Repository context's effect on findings is unmeasured.**
-  - On the #17 fixture, at 3 runs a level, one label matched in 0 of 3 runs
-    at `off` and 1 of 3 at `repo`, and the other in none. Sampling noise
-    explains that as well as the context does. The defect the second label
-    targets was raised as an active finding in 3 of 3 `off` runs and 1 of 3
-    `repo` runs, never in the wording its predicate requires.
-  - The clearest sign that the model reads the context: an HTTP 201 status
-    code that exists only in the injected OpenAPI excerpt appeared in the
-    findings of all 3 `repo` runs and of none of the `off` runs.
+- **#22 part 1 is not built, and #22 stays open.** Its follow-up lookup, one
+  bounded extra call that looks up the symbol a below-floor finding says it
+  could not see, is deferred. It would be the first time a model's output
+  chooses the next input, which crosses the project's single-shot,
+  pre-gathered-context rule, so it needs a decision on that rule first.
+- **The history-window bug stays under the floor.** With readers, #22's
+  second bug surfaced in 3 of 3 live runs, always at confidence 0.50 under
+  the 0.60 floor, so it was never posted. Nothing in 0.17.0 raises it.
+- **Repository context's effect on findings is measured for readers only.**
+  - The reader block has one single-factor measurement, at N=3 per arm on one
+    fixture (Live checks).
+  - #17's definitions and contract excerpts are still unmeasured. On the #17
+    fixture, at 3 runs a level, one label matched in 0 of 3 runs at `off` and
+    1 of 3 at `repo`, and the other in none; sampling noise explains that as
+    well as the context does. An HTTP 201 status code that exists only in the
+    injected OpenAPI excerpt appeared in the findings of all 3 `repo` runs
+    and of none of the `off` runs, which shows the model reads the context.
   - On sblattj/multi-auto-claude-sub#5, identical prompts gave 3 findings and
     0, so a single run's count cannot measure it.
 
   Measure with `prxref eval` over more runs a level before changing the
   default from `off`.
 
-The known limitations, in full in the CHANGELOG:
+0.17.0's known limitations, in full in its CHANGELOG section:
+
+- **Java and Kotlin files cost forge reads at every level.** For a changed
+  JVM file with an import outside `jvm_deps.SKIPPED_ROOTS`, the dependency
+  walk tries 3 build-file names at each directory level up to the root: up
+  to `3 * (d + 1)` reads for a file `d` directories deep. A Gradle build file
+  that mentions `libs.` adds up to 3 catalog probes, and a `pom.xml` up to 5
+  parents. The reads are cached per run and uncapped; on the #17 fixture
+  they were 21 probes over 7 levels.
+- **Kotlin names and paths.** Kotlin standard-library names such as `Int`,
+  `Unit` or `Pair` are not in `jvm_lang.JDK_NAMES`, so at `repo` each one a
+  chunk mentions is looked for by the file-name search. `repo_resolve` has no
+  Kotlin import or path rules: outside the diff, a Kotlin type is found by
+  the file-name search alone.
+- **Precompiled Gradle script plugins are walked.** Only `build.gradle.kts`
+  and `settings.gradle.kts` are skipped (`chunk_context._GRADLE_SCRIPTS`).
+  Another `*.gradle.kts` file is a Kotlin source, so its Gradle API imports
+  cost a walk for the nearest build file.
+- **Some dependencies are not matched or not resolved.** An artifact whose
+  groupId is not a package prefix of its imports gets no line (Guava,
+  Lombok, JUnit 4, Spring Boot starters and kotlinx among them). Gradle map
+  notation is not read, and a version set through a variable or
+  `gradle.properties` is not resolved.
+- **A truncated review reply is not retried**, by design: its error already
+  names `PRXREF_LLM_MAX_TOKENS`, whatever `PRXREF_LLM_PARSE_RETRIES` says.
+- **`score.json` does not total the reviews' parse retries.** It counts the
+  judge's; each case's own run record carries its review's.
+- **The shared-state search matches names, not types.** Any line that reads
+  a key of the same name, in a file of the same language, is a reader, so an
+  unrelated `.data` or `table` can fill an entry, and a reader in another
+  language is never found.
+- **The toggle check needs both lines in the pull request**, and only the
+  four suite-wide setup file names count as pins.
+
+Found while building 0.17.0, not in the CHANGELOG:
+
+- **A model finding on the toggle's line survives beside the check's.** At
+  the default `PRXREF_DEDUP_SIMILARITY` (unset), both are kept, as any two
+  chunk findings on one line are. With the similarity set, the reworded tier
+  keeps one copy (`docs/quality.md`).
+- **The toggle finding's posted severity varied live.** The check emits
+  `warning`, but the live check recorded its finding at `error` in 2 of the
+  3 reader runs. The pass that raised it was not traced.
+- **A status-added chunk file is read for nothing.** With a reader,
+  `repo_crosschunk.diff_definitions` still reads an added chunk file when
+  another file of the chunk wants a name the added file's own lines lack.
+  Every line of an added file sits inside its hunks, which the search skips,
+  so that read can never yield an entry.
+
+0.16.0's repository-context limitations, still true:
 
 - **Read caps cut the lowest-ranked sources first.** Contract files are read
-  before import, path-convention and name-search files, so those definitions
-  go first once a chunk has made 16 reads or the run 200. Which chunk meets
-  the run cap first depends on thread scheduling.
+  before import, path-convention and name-search files, and the shared-state
+  search spends only the reads those leave, so readers go first, then the
+  other definitions, once a chunk has made 16 reads or the run 200. Which
+  chunk meets the run cap first depends on thread scheduling.
 - **No content search.** Outside the pull request, a definition is found
   only through an import, the Java path convention, or a same-language file
   named after it.
 - **Files over 512 KiB read as missing**, so a large OpenAPI spec gives no
   excerpt.
 - **A large repository is listed only in part.** A paged listing stops at 20
-  pages and GitHub truncates a very large tree, so the name search and the
-  contract globs see only the files listed. A large GitLab project's listing
-  takes about a minute, once per run, at `repo` only.
+  pages and GitHub truncates a very large tree, so the name search, the
+  contract globs and the shared-state search see only the files listed. A
+  large GitLab project's listing takes about a minute, once per run, at
+  `repo` only.
 - **The Bitbucket Server listing is untested live.** It is built from the
   Data Center REST documentation and tested against fakes of that shape.
   Whether it returns submodules is unverified.
-- **A chunk that times out loses its repository context**, because the
-  timeout retry drops the definitions and contract blocks (lesson 4).
-- **A pull request's file can be fetched twice.** The 0.15.0 dependency and
-  same-file definition blocks keep their own reader.
+- **A chunk that times out loses most of its context.** The timeout retry in
+  `orchestrator._run_worker` renders with `include_definitions=False` and no
+  repository-context unit, so it drops the same-file definitions, Java and
+  Kotlin ones included, and every repository-context block: definitions,
+  contract excerpts and readers. The record marks the unit `retry_dropped`.
+  The dependency block, JVM lines included, survives.
+- **A pull request's file can be fetched twice.** Chunk context's reader
+  (`orchestrator._make_file_reader`) and the repository reader
+  (`repo_reader.RepoReader`) share no cache, so a file both of them read
+  costs two requests per run. Java and Kotlin files now read through both at
+  `diff` and `repo`, as other languages' files already did.
 
 Listing, retry and cost notes:
 
@@ -416,21 +456,22 @@ Listing, retry and cost notes:
   (`allowed_methods` in `forges/gitlab.py`), and the listing is a `POST`. A
   failed first page falls back to the REST walk; a failed later page gives a
   partial listing.
-- **An empty-reply retry followed by a timeout retry loses tokens.** When the
-  retry of an empty reply times out, `_run_worker`'s timeout retry replaces
-  the chunk's result, so the billed empty call's tokens drop out of the run
-  totals.
-- **The retry's cost estimate uses the second call's model.** When either
-  call reports no cost, the unit's cost is unknown, and `costs.run_cost`
+- **A parse retry followed by a timeout retry loses tokens and retries.**
+  When a chunk's retried call times out, `_run_worker`'s timeout retry
+  replaces the chunk's result, so the billed earlier calls' tokens drop out
+  of the run totals, and only the second run's `parse_retries` is counted.
+- **The retry's cost estimate uses the last call's model.** When any call
+  reports no cost, the unit's cost is unknown, and `costs.run_cost`
   estimates it from the summed tokens at the rate of the unit's `model`,
-  the second call's, even when another model in the fallback chain answered
-  the first call.
+  the last call's, even when another model in the fallback chain answered
+  an earlier call.
 - **prxref's defaults are too small for a thinking model.**
   `PRXREF_LLM_MAX_TOKENS` 4096 and `PRXREF_LLM_TIMEOUT` 45 lost chunks to a
-  thinking model in the live checks (lesson 4). Neither default changed in
-  0.16.0; raise both for such a model. The recipe under "Measuring repository
-  context" in `tests/evals/README.md` sets neither, so run verbatim against
-  such a model it cuts the replies off.
+  thinking model in 0.16.0's live checks (lesson 4 of the v0.16.0 handoff),
+  and 0.17.0's live check ran at 32,768 tokens and 900 s. Neither default
+  changed in 0.16.0 or 0.17.0; raise both for such a model. The recipe under
+  "Measuring repository context" in `tests/evals/README.md` sets neither, so
+  run verbatim against such a model it cuts the replies off.
 
 Sizing, recall and GitHub notes:
 
@@ -561,11 +602,11 @@ Carried over from 0.15.0 and earlier, still true:
     a public project. Without one, thread dedup runs against no threads.
 - **Replay from a diff file.** A `--diff-file` run without `--pr-url` has no
   file context and no threads. `--repo-dir` gives it repository context,
-  but the dependency-versions and same-file definitions blocks still read
-  only through the forge (`orchestrator._make_file_reader`), so they stay
-  empty. The title comes from the patch mail or the file name. The
-  description comes from the mail, `--description-file` or
-  `--no-description`.
+  but the dependency-versions and same-file definitions blocks, Java and
+  Kotlin ones included, still read only through the forge
+  (`orchestrator._make_file_reader`), so they stay empty. The title comes
+  from the patch mail or the file name. The description comes from the
+  mail, `--description-file` or `--no-description`.
 - **Azure DevOps.**
   - Only anonymous reads are verified live: the forge reads, the dry-run output
     shape, the pinned-range compare diff, a pinned-range replay, and, new in
@@ -614,23 +655,25 @@ Follow-ups a maintainer can act on:
 - **Duplicated code in `rules.py`.** `rules._read_scoped_file` duplicates the
   read block of `load_review_rules`. A `_reason` helper exists in both
   `rules.py` and `prompt_templates.py`.
-- **Missing definitions at `off`.** With repository context off,
-  `chunk_context.referenced_definitions` still looks only in the same file,
-  and only for JavaScript, TypeScript and Python. `diff` and `repo`
-  add other files and Java types; the rest of the JVM gap is #20.
+- **Missing definitions at `off`, and for Go and Rust.** With repository
+  context off, `chunk_context.referenced_definitions` still looks only in the
+  same file, for JavaScript, TypeScript, Python, Java and Kotlin. `diff` and
+  `repo` add other files, with Java and Kotlin types only. Go and Rust get
+  dependency versions but no definitions at any level:
+  `chunk_context._definition_regexes` has no regex for them.
 - **The history read is untraced.** The replay's history read is outside the
   trace, and only the `replay` stamp records its outcome.
 - **The sweep's example is always in force.** `orchestrator._example_titles`
   always reads the systemic template. So the sweep's example title is in force
   even on a run whose sweep never runs.
 
-The v0.15.0 handoff's #17 bullet is **done**, and so is its empty-reply
-bullet (the empty-reply retry).
+The v0.16.0 handoff's #20 bullet is **done** (Java and Kotlin chunk context),
+and so is its #21 bullet (the parse retry).
 
 | Item | Value |
 |---|---|
-| Released version | `0.16.0` (minor: repository context behind four new config keys, all off by default; one new CLI flag, `--repo-dir`; one new run-record and `--format json` key, `repo_context`, `null` when off; an empty model reply is retried once; no existing config default changed) |
-| Registration points | forges: the tuple in `forges/base.py` (`detect_forge`) and the `impls` dict in `config.py` (`make_forge`); repository listing: the optional `Forge.list_paths` in `forges/base.py`, on every adapter; LLM backends: `llm_backends.BACKENDS`; glyphs: `prxref.markers`; subcommands: `cli._build_parser`; prompt templates: `prompt_templates.TEMPLATE_NAMES` and `OPTIONAL_PLACEHOLDERS` |
+| Released version | `0.17.0` (minor: Java and Kotlin chunk context, at every level; one new config key, `PRXREF_LLM_PARSE_RETRIES`, default `1`, which changes behaviour: a `{}` reply now costs a second call and can fail its unit, and `0` restores 0.16.0; one new run-record and `--format json` key, `parse_retries`, `null` at `0`; a new context block at `repo`, `### Code elsewhere that reads state this chunk writes`; one new always-on deterministic check, the pinned-off toggle; no new CLI flag; no existing config default changed) |
+| Registration points | forges: the tuple in `forges/base.py` (`detect_forge`) and the `impls` dict in `config.py` (`make_forge`); repository listing: the optional `Forge.list_paths` in `forges/base.py`, on every adapter; repository-context entries: `repo_context.KINDS` and `REASONS`, whose order is the budget's rank; LLM backends: `llm_backends.BACKENDS`; glyphs: `prxref.markers`; subcommands: `cli._build_parser`; prompt templates: `prompt_templates.TEMPLATE_NAMES` and `OPTIONAL_PLACEHOLDERS` |
 | Version strings | `pyproject.toml`, `src/prxref/__init__.py`, and `uv.lock` |
 | Test command | `uv run pytest` (dev tools are a `[dependency-groups]` group, not an extra) |
 | Release assets | wheel **and** sdist attached by `release.yml`; PyPI by OIDC trusted publishing |
diff --git a/docs/env-vars.md b/docs/env-vars.md
index 9cc045b..93db83c 100644
--- a/docs/env-vars.md
+++ b/docs/env-vars.md
@@ -56,7 +56,7 @@ Configuration is loaded from built-in defaults, overridden by environment variab
 | `PRXREF_PROMPTS_DIR` | *(empty — off)* | **Prompt template overrides (0.15.0).** Directory holding replacement `worker.md`, `systemic.md` and `summary.md` prompt templates; a file that is absent keeps the packaged one. Every template is validated before any network call: `worker.md` and `systemic.md` must keep the `## Review Context` marker and every packaged placeholder below it (the feature slots `{scope_example}` and `{rule_example}` are optional), and `summary.md` needs only `{findings}`. A missing directory, a failed check, or a template over 256 KiB raises `ConfigError` and `prxref review` exits `2`; an empty directory or an unknown placeholder only warns. The run record's `prompt_templates` stamps the directory and, for each template file present in it, edited or not, its path, SHA-256 and length; a template absent from the directory has no entry. `--prompts-dir DIR` wins for one run, and `prxref prompts export DIR [--force]` writes the packaged templates to start from. The judge prompt of `prxref eval` cannot be overridden. Read it from a trusted checkout: a PR that commits a template rewrites its own review. Unset uses the packaged templates, byte for byte. |
 | `PRXREF_TICKET_CONTEXT_FILE` | *(empty — off)* | Plain-text or Markdown file holding the ticket this PR implements. When set, every finding is marked in, out of, or of unknown ticket scope. An empty or whitespace-only file means "this PR has no ticket". A missing or non-UTF-8 file raises `ConfigError` and `prxref review` exits `2`. The webhook daemon ignores it (and says so once). `--context-file PATH` wins for one run, and `--context-file ""` turns it off. |
 | `PRXREF_TICKET_CONTEXT_MAX_CHARS` | `6000` | Characters of ticket text kept in the prompt; longer text is truncated with a visible marker. Must be **greater than 0**. |
-| `PRXREF_REPO_CONTEXT` | `off` | **Repository context (0.16.0).** `off` (the default) leaves every prompt, post, trace and default-verbosity log byte-identical to 0.15.0. `diff` adds definitions from the PR's own changed files (`cross-chunk` and `diff-file` entries, Java type declarations included): those files are read at the PR head through the forge's repository reader, or `--repo-dir`, when one is available, and without a reader the entries are built from the diff's hunk lines alone, with no warning. `repo` additionally reads files outside the diff — import, path-convention and name-search definitions, contract excerpts and, since 0.17.0, readers (`shared-state` entries: excerpts from non-diff files that read state the chunk's added lines write, found only with a file listing and ranked last, so the budget cuts them first) — through the same reader, and logs one WARNING when there is no reader or no file listing. Only the chunk workers' prompts carry repository context; the whole-PR sweep prompt is unchanged. Matching is exact and case-sensitive, like `PRXREF_FAIL_ON`: `Repo` or `REPO` is rejected. Any value outside `off`\|`diff`\|`repo` raises `ConfigError` and `prxref review` exits `2`. |
+| `PRXREF_REPO_CONTEXT` | `off` | **Repository context (0.16.0).** `off` (the default) adds no repository context entry, read, trace event or log line; the same-file definitions and dependency versions of chunk context, Java and Kotlin ones included since 0.17.0, do not depend on it. `diff` adds definitions from the PR's own changed files (`cross-chunk` and `diff-file` entries, Java and Kotlin type declarations included): those files are read at the PR head through the forge's repository reader, or `--repo-dir`, when one is available, and without a reader the entries are built from the diff's hunk lines alone, with no warning. `repo` additionally reads files outside the diff — import, path-convention and name-search definitions, contract excerpts and, since 0.17.0, readers (`shared-state` entries: excerpts from non-diff files that read state the chunk's added lines write, found only with a file listing and ranked last, so the budget cuts them first) — through the same reader, and logs one WARNING when there is no reader or no file listing. Only the chunk workers' prompts carry repository context; the whole-PR sweep prompt is unchanged. Matching is exact and case-sensitive, like `PRXREF_FAIL_ON`: `Repo` or `REPO` is rejected. Any value outside `off`\|`diff`\|`repo` raises `ConfigError` and `prxref review` exits `2`. |
 | `PRXREF_REPO_CONTEXT_MAX_CHARS` | `12000` | **Repository context (0.16.0).** Per-chunk character budget shared by the cross-chunk, contract and other repository-context entries admitted under `PRXREF_REPO_CONTEXT`. Must be **greater than 0**. |
 | `PRXREF_CONTEXT_CONTRACT_GLOBS` | the built-in set below | **Repository context (0.16.0).** Globs (matched like `PRXREF_SIZE_IGNORE_GLOBS`: case-sensitive `fnmatch`, `*` crosses `/`) selecting the contract files — OpenAPI, JSON Schema, Liquibase/SQL migrations — excerpted under `repo`. A set value **REPLACES** the built-in set below, rather than adding to it; an empty value reads as unset, so the built-in set stays. There is no way to turn contract excerpts off on their own in 0.16.0 — set `PRXREF_REPO_CONTEXT` to `off` or `diff` instead. Built-in set: `**/openapi*.y*ml`, `**/openapi*.json`, `**/openapi/**`, `**/swagger*`, `**/*.schema.json`, `**/db/changelog/**`, `**/db/migration/**`, `**/migrations/**`. |
 | `PRXREF_CONTEXT_EXCLUDE_GLOBS` | *(empty)* | **Repository context (0.16.0).** Globs (matched like `PRXREF_SIZE_IGNORE_GLOBS`) whose paths are never read for repository context, not even a diff file. **Added** to a floor that is always on: `**/expected.json`, `**/cases.json`, `**/case.json`, `**/prxref-eval/**`, `**/.env*`, `**/*.pem`, `**/*.key`. Empty (the default) adds nothing. |
diff --git a/pyproject.toml b/pyproject.toml
index ca6d170..c5a2fe0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "prxref"
-version = "0.16.0"
+version = "0.17.0"
 description = "Fast automated AI code review for Bitbucket, GitLab, GitHub, and Azure DevOps"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/src/prxref/__init__.py b/src/prxref/__init__.py
index d241cb0..4782f3b 100644
--- a/src/prxref/__init__.py
+++ b/src/prxref/__init__.py
@@ -1,3 +1,3 @@
 """prxref — fast automated AI code review for Bitbucket, GitLab, GitHub, and Azure DevOps."""
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"
diff --git a/uv.lock b/uv.lock
index b2498c7..95394ba 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1153,7 +1153,7 @@ wheels = [
 
 [[package]]
 name = "prxref"
-version = "0.16.0"
+version = "0.17.0"
 source = { editable = "." }
 dependencies = [
     { name = "requests" },

From 099a7ced26cfdd046c1d406b04e3c2ada885fdc8 Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 22:43:21 -0700
Subject: [PATCH 24/25] fix: a deterministic check's finding keeps its own
 severity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Severity consistency ran over every finding, the release-shape and
pinned-off toggle findings included, so a model finding in the same file
that shared a rare code token with one (or any finding with its normalized
title) could raise it. The live check on #22's fixture saw the toggle
finding, which has no model behind it, posted as an error in two of three
runs and as a warning in the third.

heuristics.is_deterministic marks a finding whose body ends with the
checks' "(deterministic check, no model)" suffix, and
apply_severity_consistency now leaves such a finding out the way it leaves
out a dropped one: it is never raised, never raises another finding, and
its text does not count toward a token's rarity. No other pass changes.

Tests: a new class in tests/test_quality.py covers the token rule, the
title rule, the finding as a would-be source, a transitive link and the
rarity count, with a control whose unmarked body is raised; a new
tests/test_deterministic_severity.py runs #22's fixture through the local
review path with a scripted model error on assistant/progress.py and
checks the toggle stays a warning, with a control that patches the helper
off and sees it raised to error.

Docs: the CHANGELOG Fixed entry; docs/quality.md's consistency row names
both grouping rules and the exclusion, and the deterministic-checks section
says which passes can still touch these findings (finding grouping can
still raise one); a HANDOFF lesson and the verified count. Also rewrites
the .env.example PRXREF_REPO_CONTEXT paragraph to match docs/env-vars.md,
and corrects the HANDOFF registration row: only REASONS' order ranks
repository-context entries.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 .env.example                         |  26 ++++--
 CHANGELOG.md                         |   9 ++
 HANDOFF.md                           |  19 +++-
 docs/quality.md                      |  19 +++-
 src/prxref/heuristics.py             |  13 +++
 src/prxref/quality.py                |  22 +++--
 tests/test_deterministic_severity.py |  93 ++++++++++++++++++++
 tests/test_quality.py                | 126 +++++++++++++++++++++++++++
 8 files changed, 306 insertions(+), 21 deletions(-)
 create mode 100644 tests/test_deterministic_severity.py

diff --git a/.env.example b/.env.example
index d4ab7fc..7ac5e5f 100644
--- a/.env.example
+++ b/.env.example
@@ -285,15 +285,23 @@ PRXREF_MAX_CHUNKS=8
 # a visible marker. Must be > 0.
 # PRXREF_TICKET_CONTEXT_MAX_CHARS=6000
 
-# Repository context (0.16.0): off (default) | diff | repo. off leaves every
-# prompt, post, trace and default-verbosity log byte-identical to 0.15.0.
-# diff adds cross-chunk definitions from other files already in the diff,
-# plus diff-file entries, all read from the diff itself -- no repository
-# reader is needed. repo also reads files outside the diff (import,
-# path-convention and name-search definitions, plus contract excerpts)
-# through the forge's repository reader when one is available, or
-# --repo-dir. Matching is exact and case-sensitive, like PRXREF_FAIL_ON; any
-# other value is a configuration error (exit 2).
+# Repository context (0.16.0): off (default) | diff | repo. off adds no
+# repository-context entry, read, trace event or log line; chunk context's
+# same-file definitions and dependency versions, Java and Kotlin ones
+# included since 0.17.0, do not depend on it. diff adds definitions from the
+# PR's own changed files (cross-chunk and diff-file entries, Java and Kotlin
+# type declarations included): those files are read at the PR head through
+# the forge's repository reader, or --repo-dir, when one is available, and
+# without a reader the entries are built from the diff's hunk lines alone,
+# with no warning. repo also reads files outside the diff -- import,
+# path-convention and name-search definitions, contract excerpts and, since
+# 0.17.0, readers (shared-state entries: excerpts of files outside the diff
+# that read state the chunk's added lines write, found only with a file
+# listing and ranked last, so the budget cuts them first) -- through the same
+# reader, and logs one WARNING when there is no reader or no file listing.
+# Only the chunk workers' prompts carry repository context; the whole-PR
+# sweep prompt is unchanged. Matching is exact and case-sensitive, like
+# PRXREF_FAIL_ON; any other value is a configuration error (exit 2).
 # PRXREF_REPO_CONTEXT=off
 
 # Repository context (0.16.0): per-chunk character budget shared by the
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cb09607..580aa53 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -178,6 +178,15 @@ record and `--format json` gain one key, `parse_retries`.
   references and another file of the same chunk defines outside its hunks.
   0.16.0 left the chunk's own Python and JavaScript/TypeScript files out of
   that search entirely.
+- **A deterministic check's finding keeps its own severity.** Severity
+  consistency could raise the release-shape or pinned-off toggle finding to
+  the severity of a model finding in the same file that shared a rare code
+  token with it, or of a model finding with the same normalized title, so a
+  finding that ends `(deterministic check, no model)` could post at a
+  severity a model chose. The toggle finding was seen posted as an `error`
+  that way. Both checks' findings now take no part in severity consistency:
+  they are never raised, never raise another finding, and their text no
+  longer counts toward a code token's rarity.
 
 ### Known limitations
 
diff --git a/HANDOFF.md b/HANDOFF.md
index 3a3b12b..f63a140 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -199,6 +199,21 @@ Written down because each one cost real time.
    but always under the 0.60 floor. The toggle check fired in all 6 runs.
    Three runs an arm on one fixture is a first measurement, not a verdict on
    the feature (Live checks).
+6. **A pass that runs over every finding runs over the deterministic ones
+   too.** The toggle check has no model, yet its finding was posted as an
+   `error` in 2 of arm B's 3 live runs and as a `warning` in the third
+   (Live checks). Severity consistency had raised it: a model `error` in the
+   same file shared a rare code token with it. Those two runs logged
+   `severity consistency: raised 1 finding(s) via shared rare code
+   token(s)`, binding on `true` in one and on `assistant_progress_notes` in
+   the other, and the third run logged no such line. Only the variation gave
+   it away, because a check with no model should post the same severity on
+   every run. A finding that `heuristics.is_deterministic` marks now takes no
+   part in severity consistency. `TestDeterministicFindingsKeepTheirSeverity`
+   in `tests/test_quality.py` and `tests/test_deterministic_severity.py`,
+   through the local review path on #22's fixture, pin it, each with a
+   control that shows the raise without the exemption. Finding grouping,
+   which is opt-in, can still raise one (`docs/quality.md`).
 
 ## The coupling that will catch the next person adding a config key
 
@@ -300,7 +315,7 @@ pattern does not match GitHub's auto-generated source archive.
 ## Verified at release
 
 ```
-8695 passed                                   uv run pytest -q
+8703 passed                                   uv run pytest -q
 All checks passed!                            uv run ruff check src tests
 0.17.0                                        uv run prxref --version
 ```
@@ -673,7 +688,7 @@ and so is its #21 bullet (the parse retry).
 | Item | Value |
 |---|---|
 | Released version | `0.17.0` (minor: Java and Kotlin chunk context, at every level; one new config key, `PRXREF_LLM_PARSE_RETRIES`, default `1`, which changes behaviour: a `{}` reply now costs a second call and can fail its unit, and `0` restores 0.16.0; one new run-record and `--format json` key, `parse_retries`, `null` at `0`; a new context block at `repo`, `### Code elsewhere that reads state this chunk writes`; one new always-on deterministic check, the pinned-off toggle; no new CLI flag; no existing config default changed) |
-| Registration points | forges: the tuple in `forges/base.py` (`detect_forge`) and the `impls` dict in `config.py` (`make_forge`); repository listing: the optional `Forge.list_paths` in `forges/base.py`, on every adapter; repository-context entries: `repo_context.KINDS` and `REASONS`, whose order is the budget's rank; LLM backends: `llm_backends.BACKENDS`; glyphs: `prxref.markers`; subcommands: `cli._build_parser`; prompt templates: `prompt_templates.TEMPLATE_NAMES` and `OPTIONAL_PLACEHOLDERS` |
+| Registration points | forges: the tuple in `forges/base.py` (`detect_forge`) and the `impls` dict in `config.py` (`make_forge`); repository listing: the optional `Forge.list_paths` in `forges/base.py`, on every adapter; repository-context entries: `repo_context.KINDS`, where an entry's kind picks the prompt block it renders in and the tuple's order ranks nothing, and `REASONS`, whose order is the budget's rank; LLM backends: `llm_backends.BACKENDS`; glyphs: `prxref.markers`; subcommands: `cli._build_parser`; prompt templates: `prompt_templates.TEMPLATE_NAMES` and `OPTIONAL_PLACEHOLDERS` |
 | Version strings | `pyproject.toml`, `src/prxref/__init__.py`, and `uv.lock` |
 | Test command | `uv run pytest` (dev tools are a `[dependency-groups]` group, not an extra) |
 | Release assets | wheel **and** sdist attached by `release.yml`; PyPI by OIDC trusted publishing |
diff --git a/docs/quality.md b/docs/quality.md
index 762fbfa..7d27f8a 100644
--- a/docs/quality.md
+++ b/docs/quality.md
@@ -23,7 +23,7 @@ ratio is exact rational arithmetic, never a float. This catches a release cut
 from an unmerged branch, or a hand edit smuggled into a release.
 
 The finding is folded into the raw results **before** the passes below, so it
-is validated, aligned, deduplicated and gated exactly like a model finding.
+is validated, aligned, deduplicated and gated like a model finding.
 It is spliced in at the chunk/sweep boundary — before the systemic sweep's
 own findings, never after — so `apply_sweep_dedup` always treats it as a
 CHUNK-side finding and can never drop it as a duplicate of a chunk worker's
@@ -60,7 +60,7 @@ quotes the toggle call, names every file that pins it, and ends with
 
 Like the release-shape finding, it is folded in at the chunk/sweep boundary,
 so it is a CHUNK-side finding, it also runs on a diff that yields zero
-chunks, and it goes through every pass below like a model finding. Unlike
+chunks, and it goes through the passes below like a model finding. Unlike
 that finding, it sits on a real line, so line alignment and the
 reworded-duplicate tier both reach it. When a chunk worker also reports the
 toggle on the same line, both findings are kept at the default
@@ -70,6 +70,19 @@ keeps one copy, the more severe, then the more confident: on a severity tie
 the check's 1.0 outranks a model's lower confidence, and the model's copy is
 dropped as `duplicate of chunk finding (reworded, similarity <s>)`.
 
+**Both checks keep their own severity.** A finding whose body ends with
+`(deterministic check, no model)` takes no part in severity consistency
+(pass 7): it joins no group, so no model finding raises it or is raised by
+it, and its text does not count toward a code token's rarity. One other pass
+can still change its severity or confidence: finding grouping (pass 10,
+opt-in). When a chunk worker's finding in the same file names no rule and
+has the same normalized title, the group's anchor takes the highest severity
+and confidence, so a deterministic anchor can be raised, and a deterministic
+finding that does not anchor is dropped as `grouped into <file>:<line>`.
+Every other pass leaves its severity and confidence alone, and several can
+still drop it, among them the thread passes, the per-rule cap, the gate's
+caps and, for the toggle finding, the reworded-duplicate tier.
+
 ## The passes, in the order they run
 
 `orchestrate_review` applies these in a fixed order; several of them depend on
@@ -83,7 +96,7 @@ it (noted in the table).
 | 4 | `apply_line_align` | Re-anchors a cited line to a real added line of that file, or demotes it to file-level. |
 | 5 | `apply_thread_dedup` | Drops a finding an existing PR thread already makes (path + line window + shared distinctive tokens). |
 | 6 | `apply_settled_thread_suppression` | Drops a finding that re-litigates a subject a thread already argued out. Line-independent by design. A thread with no path — a general, unanchored PR comment — is ignored by this pass, since it cannot be "same path" as any finding. |
-| 7 | `apply_severity_consistency` | Rewrites only: findings sharing a normalized title are all raised to the group's maximum severity. |
+| 7 | `apply_severity_consistency` | Rewrites only: groups findings and raises every member to the group's maximum severity. Two rules group findings, and a group binds transitively: a shared normalized title, in any file; or a shared rare code token (one in the text of at most 2 findings) when the two sit in the same file or their titles name a common problem class. A deterministic finding (see [Deterministic checks](#deterministic-checks-findings-prxref-computes-itself)) is left out: it is never raised, never raises another finding, and its text does not count toward a token's rarity. |
 | 8 | `apply_removal_claim_check` | Drops a claim that a **named** path was removed when the post-image still carries it. The removal verb must **govern** that path (`removed src/app.py`, `src/app.py was removed`); a bare "removed" elsewhere in the body is not a removal claim. |
 | 9 | `apply_hedge_gate` | Drops a finding whose own text conditions the defect on a precondition never established from the diff. One part of the body is not read, in any finding whatever its severity: after a `Spec:` marker (that exact spelling; the opening quote is optional), the text the finding copies verbatim from the injected spec digest, compared case-insensitively, up to a closing quote. A condition inside a real constraint belongs to the spec, not the model. Everything else is read: text the digest does not hold, so a made-up `Spec: "…"` hides nothing; every quote when no digest was injected (no spec sources, or an ungrounded run); and the title. Known limitation: a quote with no closing quote after its verbatim text, or one that departs from the digest before its closing quote, is exempt only up to the last quote mark inside its verbatim part (an apostrophe counts), and not at all when there is none. |
 | 10 | `apply_rule_grouping` | Opt-in: runs only with `PRXREF_GROUP_FINDINGS` set to `1`. Folds chunk findings in one file that name the same rule (compared case-insensitively), or that name no rule and share a normalized title, into one finding. The finding with the smallest positive line anchors the group; a file-level (line 0) finding anchors only when no member has a line. The anchor takes the group's highest severity and highest confidence, and its body gains `Also at:` followed by each other line of the group as a backticked `<file>:<line>`. Every other member is dropped as `grouped into <file>:<line>`. Only active findings at or above the confidence floor are grouped, and whole-PR sweep findings are never grouped. The same rule in two files makes two groups. Runs **after** the thread, removal and hedge passes, so a dropped finding is never listed as a location, and **before** the gate, so the error cap counts groups, not lines. |
diff --git a/src/prxref/heuristics.py b/src/prxref/heuristics.py
index a4ab204..aeb9d14 100644
--- a/src/prxref/heuristics.py
+++ b/src/prxref/heuristics.py
@@ -76,6 +76,19 @@
 _BODY_SUFFIX = " (deterministic check, no model)"
 
 
+def is_deterministic(finding: Finding) -> bool:
+    """True when ``finding`` came from a check in this module, not a model.
+
+    Every finding this module makes ends its body with " (deterministic
+    check, no model)", and that ending is the mark: a finding whose ``body``
+    is a string ending with it is deterministic. Its severity and
+    confidence are the check's own, so
+    :func:`prxref.quality.apply_severity_consistency` leaves it out.
+    """
+    body = finding.body
+    return isinstance(body, str) and body.endswith(_BODY_SUFFIX)
+
+
 def _is_release_machinery(path: str) -> bool:
     """True when ``path`` is release machinery under the frozen contract.
 
diff --git a/src/prxref/quality.py b/src/prxref/quality.py
index e79dda0..ec36d71 100644
--- a/src/prxref/quality.py
+++ b/src/prxref/quality.py
@@ -9,9 +9,9 @@
 the pinned-toggle heuristic, are not passes at all:
 ``heuristics.release_shape_findings`` and
 ``heuristics.toggle_pinned_off_findings`` each ADDS its own finding
-before pass 1, and each then flows through every pass below exactly like
-a model finding. Every ``drop_reason`` prefix these passes emit is
-tabulated for operators in ``docs/quality.md``.
+before pass 1, and each then flows through every pass below like a model
+finding, except that pass 9 leaves it out. Every ``drop_reason`` prefix
+these passes emit is tabulated for operators in ``docs/quality.md``.
 
 1. ``apply_severity_map``: when the team review rules declare a severity
    map, rewrite a team severity word (``blocker``) to the prxref tier the
@@ -78,7 +78,8 @@
    maximum severity, so per-chunk workers cannot disagree about how
    serious the same pattern is. Findings phrased differently but bound
    by a shared rare code token, with a shared problem class or file,
-   join the same group (issue #30).
+   join the same group (issue #30). A deterministic finding joins no
+   group, so it keeps the severity its check gave it.
 10. ``apply_removal_claim_check``: drop findings whose removal verb governs
     a path — ``removed src/app.py``, ``src/app.py was removed`` — when every
     path the claim names is still present in the diff's post-image — the false positive a ``copy from``/``copy to``
@@ -155,6 +156,7 @@
 from dataclasses import replace
 from pathlib import PurePosixPath
 
+from . import heuristics
 from .forges.base import Thread
 from .triage import DiffLine, FileDiff, Finding, Hunk
 
@@ -1501,14 +1503,20 @@ def apply_severity_consistency(findings: Sequence[Finding]) -> list[Finding]:
     (error > warning > spec > outofscope). A rewritten finding keeps
     its own file, line, body, and confidence; only severity changes.
     Findings carrying a ``drop_reason`` or a severity outside the
-    vocabulary pass through untouched. One summary line is logged when
-    token-driven rewrites happen, naming the count and the binding
-    tokens; silent otherwise.
+    vocabulary pass through untouched. So does a deterministic finding
+    (:func:`prxref.heuristics.is_deterministic`: its body ends with
+    " (deterministic check, no model)"), whose severity is the check's
+    own rather than a model's call: it joins no group under either rule,
+    so it is never raised and never raises another finding, and its
+    claim does not count toward a token's rarity. One summary line is
+    logged when token-driven rewrites happen, naming the count and the
+    binding tokens; silent otherwise.
     """
     idx = [
         i for i, f in enumerate(findings)
         if f.drop_reason is None
         and (f.severity or "").strip().lower() in _SEVERITY_RANK
+        and not heuristics.is_deterministic(f)
     ]
     if not idx:
         return list(findings)
diff --git a/tests/test_deterministic_severity.py b/tests/test_deterministic_severity.py
new file mode 100644
index 0000000..f896728
--- /dev/null
+++ b/tests/test_deterministic_severity.py
@@ -0,0 +1,93 @@
+"""A deterministic finding keeps its own severity, end to end.
+
+Issue #22's fixture, reviewed through the production local path
+(``cli._run_review`` with ``--diff-file``, ``--repo-dir`` and
+``--description-file``), against a local scripted openai-compat server. The
+model answers the one prompt that holds ``assistant/progress.py``'s diff with
+an ``error`` finding in that file whose body names
+``ASSISTANT_PROGRESS_NOTES``, the rare code token the pinned-off toggle
+finding's body also carries, and answers every other prompt with no
+finding. That is the shape the live check saw posting the toggle as an
+``error``. The payload asserted on is the one ``--format json`` prints.
+Nothing leaves localhost.
+"""
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from prxref import cli, heuristics
+from tests.test_integration import MockOpenAIServer, _completion
+from tests.test_issue_22_acceptance import DESCRIPTION, PATCH, PROGRESS, REPO, TOGGLE_LINE, TOGGLE_TITLE
+
+MODEL_TITLE = "Progress notes vanish when the notes flag is off"
+MODEL_FINDING = {
+    "file": PROGRESS,
+    "line": 37,
+    "severity": "error",
+    "confidence": 0.9,
+    "title": MODEL_TITLE,
+    "body": "`announce` returns early whenever `ASSISTANT_PROGRESS_NOTES` is false, so no note is stored.",
+}
+NO_FINDINGS = json.dumps({"findings": []})
+
+
+def _holds_progress_diff(payload: dict) -> bool:
+    """True when the request's last user prompt holds ``assistant/progress.py``'s own diff."""
+    user = [message["content"] for message in payload["messages"] if message["role"] == "user"][-1]
+    return f"diff --git a/{PROGRESS} " in user
+
+
+def _answer(payload: dict) -> tuple[int, dict]:
+    """The model finding for the prompt holding the progress.py diff, no finding for any other."""
+    if _holds_progress_diff(payload):
+        return 200, _completion(json.dumps({"findings": [MODEL_FINDING]}), "stop")
+    return 200, _completion(NO_FINDINGS, "stop")
+
+
+@pytest.fixture
+def review(monkeypatch):
+    """Run the fixture review once: the ``--format json`` payload and the requests the server saw."""
+    server = MockOpenAIServer(routes={"fast": _answer})
+    base_url = server.start()
+
+    def _review() -> tuple[dict, list[dict]]:
+        monkeypatch.setenv("PRXREF_LLM_BACKEND", "openai-compat")
+        monkeypatch.setenv("PRXREF_LLM_BASE_URL", base_url)
+        monkeypatch.setenv("PRXREF_LLM_MODELS", "fast")
+        monkeypatch.setenv("PRXREF_REPO_CONTEXT", "off")
+        result = cli._run_review(
+            None, diff_file=str(PATCH), repo_dir=str(REPO), description_file=str(DESCRIPTION),
+        )
+        return json.loads(json.dumps(cli._build_json_result(result))), list(server.requests)
+
+    yield _review
+    server.stop()
+
+
+def _titled(payload: dict, title: str) -> dict:
+    (finding,) = [f for f in payload["findings"] if f["title"] == title]
+    return finding
+
+
+class TestTheToggleKeepsItsSeverity:
+    def test_the_toggle_stays_a_warning_beside_the_models_error(self, review):
+        payload, requests = review()
+        assert len([r for r in requests if _holds_progress_diff(r["payload"])]) == 1
+        toggle = _titled(payload, TOGGLE_TITLE)
+        assert (toggle["file"], toggle["line"]) == (PROGRESS, TOGGLE_LINE)
+        assert (toggle["severity"], toggle["confidence"]) == ("warning", 1.0)
+        assert toggle["drop_reason"] is None
+        assert toggle["body"].endswith(heuristics._BODY_SUFFIX)
+        model = _titled(payload, MODEL_TITLE)
+        assert model["file"] == PROGRESS
+        assert (model["severity"], model["drop_reason"]) == ("error", None)
+
+    def test_control_without_the_exemption_the_toggle_is_raised_to_error(self, review, monkeypatch):
+        monkeypatch.setattr(heuristics, "is_deterministic", lambda finding: False)
+        payload, _ = review()
+        toggle = _titled(payload, TOGGLE_TITLE)
+        assert (toggle["file"], toggle["line"]) == (PROGRESS, TOGGLE_LINE)
+        assert (toggle["severity"], toggle["drop_reason"]) == ("error", None)
+        assert _titled(payload, MODEL_TITLE)["severity"] == "error"
diff --git a/tests/test_quality.py b/tests/test_quality.py
index 7aa3111..46fd943 100644
--- a/tests/test_quality.py
+++ b/tests/test_quality.py
@@ -3,9 +3,11 @@
 
 import itertools
 import logging
+from dataclasses import replace
 
 import pytest
 
+from prxref import heuristics
 from prxref.forges.base import Thread
 from prxref.quality import (
     CONTAINMENT_NOTE_SUFFIX,
@@ -572,6 +574,130 @@ def test_no_token_rewrites_logs_nothing(self, caplog):
         assert not [r for r in caplog.records if r.name == quality_logger.name]
 
 
+TOGGLE_DIFF = """\
+diff --git a/assistant/progress.py b/assistant/progress.py
+new file mode 100644
+--- /dev/null
++++ b/assistant/progress.py
+@@ -0,0 +1,2 @@
++class ProgressAnnouncer:
++    active = enabled("progress_notes", default=True)
+diff --git a/tests/conftest.py b/tests/conftest.py
+new file mode 100644
+--- /dev/null
++++ b/tests/conftest.py
+@@ -0,0 +1,2 @@
++def _off(monkeypatch):
++    monkeypatch.setenv("ASSISTANT_PROGRESS_NOTES", "false")
+"""
+
+
+def _toggle_finding() -> Finding:
+    """The pinned-off toggle check's own finding over ``TOGGLE_DIFF``.
+
+    Its claim carries the code tokens ``enabled``, ``progress_notes``,
+    ``true`` and ``assistant_progress_notes``.
+    """
+    (finding,) = heuristics.toggle_pinned_off_findings(parse_unified_diff(TOGGLE_DIFF))
+    assert heuristics.is_deterministic(finding)
+    assert (finding.file, finding.severity, finding.confidence) == (
+        "assistant/progress.py", "warning", 1.0,
+    )
+    return finding
+
+
+class TestDeterministicFindingsKeepTheirSeverity:
+    """A deterministic finding takes no part in severity consistency.
+
+    The live shape: the pinned-off toggle finding and a model ``error`` in
+    the same file shared the rare token ``assistant_progress_notes``, and
+    the toggle was posted as an ``error``.
+    """
+
+    def test_a_shared_rare_token_in_the_same_file_raises_neither(self, caplog):
+        from prxref.quality import logger as quality_logger
+
+        toggle = _toggle_finding()
+        model = _f(
+            file="assistant/progress.py", line=2, severity="error", confidence=0.9,
+            title="Progress notes vanish when the notes flag is off",
+            body="`announce` returns early whenever `ASSISTANT_PROGRESS_NOTES` is false, so no note is stored.",
+        )
+        with caplog.at_level(logging.INFO, logger=quality_logger.name):
+            result = apply_severity_consistency([toggle, model])
+        assert result[0] is toggle
+        assert result[0].severity == "warning"
+        assert result[1].severity == "error"
+        assert not [r for r in caplog.records if r.name == quality_logger.name]
+
+    def test_control_the_same_pair_without_the_mark_is_raised(self):
+        toggle = _toggle_finding()
+        unmarked = replace(toggle, body=toggle.body.removesuffix(heuristics._BODY_SUFFIX))
+        assert not heuristics.is_deterministic(unmarked)
+        model = _f(
+            file="assistant/progress.py", line=2, severity="error", confidence=0.9,
+            title="Progress notes vanish when the notes flag is off",
+            body="`announce` returns early whenever `ASSISTANT_PROGRESS_NOTES` is false, so no note is stored.",
+        )
+        result = apply_severity_consistency([unmarked, model])
+        assert [f.severity for f in result] == ["error", "error"]
+
+    def test_a_shared_normalized_title_raises_neither(self):
+        toggle = _toggle_finding()
+        model = _f(
+            file="assistant/engine.py", line=5, severity="error", confidence=0.9,
+            title="toggle `progress_notes` defaults on but the test setup pins it off.",
+            body="The suite never runs the default.",
+        )
+        assert normalize_title(model.title) == normalize_title(toggle.title)
+        result = apply_severity_consistency([toggle, model])
+        assert result[0] is toggle
+        assert [f.severity for f in result] == ["warning", "error"]
+
+    def test_a_deterministic_warning_never_raises_a_model_finding(self):
+        toggle = _toggle_finding()
+        spec = _f(
+            file="assistant/progress.py", line=2, severity="spec", confidence=0.8,
+            title="Notes stay off for the whole session",
+            body="The `ASSISTANT_PROGRESS_NOTES` value is read at import time.",
+        )
+        result = apply_severity_consistency([toggle, spec])
+        assert result[1] is spec
+        assert [f.severity for f in result] == ["warning", "spec"]
+
+    def test_two_model_findings_linked_only_through_it_stay_apart(self):
+        toggle = _toggle_finding()
+        a = _f(
+            file="assistant/progress.py", line=2, severity="error", confidence=0.9,
+            title="Announcer reads the flag once",
+            body="`enabled` is called only in the constructor, so a later change is never seen.",
+        )
+        b = _f(
+            file="assistant/progress.py", line=1, severity="warning", confidence=0.8,
+            title="Notes stay off for the whole session",
+            body="The `ASSISTANT_PROGRESS_NOTES` value is read at import time.",
+        )
+        result = apply_severity_consistency([a, toggle, b])
+        assert result[1] is toggle
+        assert result[2] is b
+        assert [f.severity for f in result] == ["error", "warning", "warning"]
+
+    def test_its_claim_does_not_count_toward_a_tokens_rarity(self):
+        toggle = _toggle_finding()
+        a = _f(
+            file="assistant/progress.py", line=2, severity="error", confidence=0.9,
+            title="Progress notes vanish when the notes flag is off",
+            body="`announce` returns early whenever `ASSISTANT_PROGRESS_NOTES` is false.",
+        )
+        b = _f(
+            file="assistant/progress.py", line=1, severity="warning", confidence=0.8,
+            title="Notes stay off for the whole session",
+            body="The `ASSISTANT_PROGRESS_NOTES` value is read at import time.",
+        )
+        result = apply_severity_consistency([a, toggle, b])
+        assert [f.severity for f in result] == ["error", "warning", "error"]
+
+
 class TestSpecSeverity:
     """The ``spec`` severity: gate vocabulary, rank order, and cap exemption."""
 

From bbd595590e1138bef2643de5e454241caed2249c Mon Sep 17 00:00:00 2001
From: Stephen Blatt <5125883+sblattj@users.noreply.github.com>
Date: Thu, 24 Sep 2026 22:50:51 -0700
Subject: [PATCH 25/25] docs: say where deterministic findings leave the model
 path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The orchestrator comment and the heuristics module docstring still said a
deterministic finding flows through the quality passes exactly like a model
finding. Severity consistency now leaves them out, so both say so and name
heuristics.is_deterministic.

🤖 Authored with Claude Code

— Claude Opus 5.5 via Claude Code

Claude-Session-Id: f915b0ff-b27c-46f3-bc7c-430dca61d459
---
 src/prxref/heuristics.py   | 3 ++-
 src/prxref/orchestrator.py | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/prxref/heuristics.py b/src/prxref/heuristics.py
index aeb9d14..b8dc4fd 100644
--- a/src/prxref/heuristics.py
+++ b/src/prxref/heuristics.py
@@ -6,7 +6,8 @@
 opposite: pure, computed once over the parsed diff's ``FileDiff`` list, no
 model in the loop, so its output can be concatenated onto the LLM-sourced
 findings list before the quality passes run and survive them the same way a
-model finding would.
+model finding would, except that severity consistency never regroups them
+(``is_deterministic``).
 """
 from __future__ import annotations
 
diff --git a/src/prxref/orchestrator.py b/src/prxref/orchestrator.py
index 325f4bb..f44b7e6 100644
--- a/src/prxref/orchestrator.py
+++ b/src/prxref/orchestrator.py
@@ -1186,7 +1186,8 @@ def orchestrate_review(
         failed_chunks.append((results[-1]["error"], []))
 
     # Two deterministic, non-LLM findings folded in before the quality passes
-    # so each flows through every one of them exactly like a model finding
+    # so each flows through them like a model finding, except that
+    # apply_severity_consistency leaves them out (heuristics.is_deterministic)
     # (issues #10 and #22): warning/1.0 clears apply_quality_gate trivially
     # for both. release_shape is file-level (line=0), so it survives
     # apply_line_align untouched; the toggle finding sits on the toggle's