feat: --target-reduction-ratio is a real target (audit H4, deferred half)

[ojassug]

Closes audit H4's deferred half. Full reasoning in DECISIONS §48.

--target-reduction-ratio was an on/off switch: the planner read it as > 0 to pick knapsack mode, nothing else read it, so 0.01 and 0.99 produced byte-identical output.

Two things were broken, not one

• It never reached the machinery. pruning:topology-pruner gated on maxInputTokens and bypassed itself entirely when only a ratio was set — visible in every ratio-only trace as "maxInputTokens not specified in budget; topology pruning bypassed".
• It never stopped. Compression ran to exhaustion: 44.62%, later 69.09%, for every target on the same file. Overshooting isn't a bonus — each extra elision spends fidelity, raises drift, and is irreversible on the CLI.

resolveTokenCeiling reads the ratio as a statement about the input ("remove 30%" = "keep at most 70%") and resolves it against the bundle. Once absolute it's an ordinary token ceiling, which the pruner and knapsack already solve against. Both ceilings are caps, so the tighter wins.

Granularity — both steps found by measuring

The stop rule was first written between items and did nothing on the commonest CLI shape: optimize one-file.ts is a single-item bundle, so it checks once before anything is elided and the item then loses every region at once — 0.1, 0.3, 0.5, 0.7 all gave 69.09%. A ceiling must bind where the compression happens.

Then region order mattered. Positional order still overshot (0.1–0.5 all gave 55.2%) because regions are extremely uneven:

file	regions	each as % of file
core/planner/index.ts	3	58%, 9%, 9%
core/engine/index.ts	5	61%, 1%, 4%, 10%, 2%
core/validation/index.ts	2	83%, 4%

Every file has one dominant region and it comes first positionally. Selection is now smallest-first when a ceiling is set, re-sorted into positional order before splicing (elideRegions walks a forward cursor).

What it achieves — a distribution, not a claim

Frozen corpus, target 30%, 66 reducing files:

achieved	files
25–35% (on target)	21
35–50%	13
>50% (overshoot)	23
under 25%	9

The flag binds — it is no longer a switch — but adherence is partial and the limit is structural: elision's smallest unit is one region. Sub-region elision closes it; not attempted here. The test pins this as a documented limit and deliberately does not assert achieved <= target.

⚠ The corpus aggregate fell, and that is the feature

The harness measures at ratio 0.3, so runs that used to overshoot now stop near 30%:

bucket	before	after	reduced	fallbacks
python file	23.14%	20.26%	30 → 31	14 → 13
typescript file	23.03%	17.57%	rose	—

Each contributing file contributes less, and more files survive validation because less aggressive elision means less drift. Third time in this project a headline aggregate moved for a non-regression reason (§45 line endings, §46 corpus growth, this).

Roadmap and CLAUDE.md — written for a fresh session

• Renumbered. The roadmap's "v1.2.0 — Context Selection Quality" collided with the shipped remediation release; feature releases are now v1.3.0 / v1.4.0 / v1.5.0.
• Recorded that both of v1.3.0's headline deliverables fail their preconditions, measured before writing any of it: BM25 has no query source anywhere in src/, and MMR found 0 of 1,486 real pairs above its 0.90 threshold (maxima 0.296 and 0.500; the similarity instrument was validated first — identical 1.000, one-line edit 0.998, disjoint prose 0.000). Built as specified, both would be ~1,000 LOC with no observable effect — the H5 condition again.
• CLAUDE.md gains a "Where the project actually is" section with that disposition and the alternatives whose preconditions do hold (widen elision beyond TS/JS/Python; sub-region elision; per-item drift).

Verification

614 tests passing, typecheck and lint clean. The two behavioural tests fail against the pre-change engine (byte-identical output for different ratios) and pass now.

🤖 Generated with Claude Code