[Hessesian]

Why

Review of #329 showed an agent reusing every primitive named in AGENTS.md and reinventing most of the ones that are not: about 340 lines of line-text parsing next to an existing CST walker, direct indexer.definitions reads, and copies of named_arg_label and param_names_from_sig. The catalogue exists, but nothing an agent reads by default names it, and nothing fails when feature code reaches around it.

What

• tests/architecture_ratchet.rs scans src/features, src/semantic_tokens and src/inlay_hints.rs (production files, non-comment lines) for literal reaches into resolver::infer* and the raw index maps, and compares each count with a baseline taken from main today. Any drift fails: more means a new bypass, fewer means the baseline must be lowered in the same change. The failure message lists every site.
• AGENTS.md: Key Files entries for CstQuery, NodeExt and StrExt, phrased as the question each answers, plus one Code Quality rule stating what the test enforces.
• docs/agent-reference.md §12: a private helper needed by a second feature moves next to its input type; an almost-right primitive gets its return type widened rather than a sibling.

Baselines

Pattern	Count
resolver::infer::	7
resolver::infer_lines::	0
infer_variable_type	2
infer_type_in_lines	0
.definitions. / .jar_definitions.	0 / 0
.files. / .jar_files.	2 / 2
.live_lines	2
.extension_by_receiver	1

Limits

The scan is literal text. A reach spelled through a re-export (use crate::resolver::{infer_variable_type_raw} is caught by name, other re-exports are not) or split across lines escapes it. The durable fix is to make resolver::infer private once its count reaches zero; the file header says so.

Verification

• cargo test: 2103 passed, 0 failed.
• cargo clippy --all-targets -- -D warnings: clean.
• Confirmed the test fails: appending an indexer.definitions.get(..) call to a feature file reports .definitions.: baseline 0, found 1 with the file and line.

No behaviour change. #329 as currently written will fail this test once it is rebased.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Aggregate counts allow replacement bypasses, and missing scan roots can silently reduce coverage.

2 open findings

• Fail when configured source roots are missing or renamed · New
• Compare bypass sites against an allowlist, not just total count · New

What changed in this PR

Adds an architecture ratchet preventing feature code from bypassing resolution APIs.

Changes:

• Scans feature sources for raw resolver/index access.
• Documents preferred resolution primitives and extension practices.

File	Description
tests/​architecture_ratchet.rs	Adds bypass-count enforcement.
AGENTS.md	Adds architectural guidance.
docs/​agent-reference.md	Documents reuse and extension patterns.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.