fix(deps): regenerate lock, fix ruff 0.16.6 findings, guard against future drift

[cdeust]

Summary

Fixes #39. CI installed ruff==0.15.20 from requirements-dev.lock while
requirements-dev.txt declared ruff==0.16.6 (dependabot #22, #32), so every
dependabot pip bump since #22 merged green without the declared linter ever
running in CI.

• Fixed every ruff check plugins tests finding under 0.16.6 (SIM115,
  PLW1510, I001, RUF100, FURB122, EXE001), root cause each time. No
  blanket noqa, no rule disabling in config. Two fixes (subagent_usage.py,
  measure_refine_overhead.py) needed a small extraction to stay under the
  nesting-depth cap once fixed.
• ruff format (0.16.6) applied to the files this PR touches. AST identity
  (ast.dump() sha256, before and after) verified for every one of them.
  Note: because of a scratch-reconstruction sequencing mistake, the format
  output for 9 of 11 files landed in the same commit as their lint fixes
  (0d992fe) rather than in the dedicated format commit (28d42d6), which
  only reformats the 2 files that had no lint findings. AST identity was
  verified regardless.
• Fixed the drift at its source rather than only guarding against it.
  requirements-dev.txt (human-edited manifest) is now requirements-dev.in;
  the old requirements-dev.lock (uv-compiled, hash-locked) is now
  requirements-dev.txt, recompiled with
  uv pip compile requirements-dev.in --generate-hashes --universal
  --python-version 3.11 --output-file=requirements-dev.txt, which embeds
  a --output-file= pragma naming itself. This is the exact pair
  dependabot-core's uv ecosystem matcher requires
  (uv/lib/dependabot/uv/requirements_file_matcher.rb, pinned at
  https://github.com/dependabot/dependabot-core/blob/f3a79fa0711aca171b2174b855d9f21b16237961/uv/lib/dependabot/uv/requirements_file_matcher.rb):
  a .txt lockfile matches its manifest via either that pragma or a
  same-basename .in file; requirements-dev.txt now has both.
  .github/dependabot.yml's pip entry is now package-ecosystem: "uv" (its
  own file_fetcher.rb confirms a plain .in/.txt pair needs no
  pyproject.toml or uv.lock: "Repo must contain a requirements.txt,
  uv.lock, requirements.in, or pyproject.toml"). Dependabot can now
  regenerate requirements-dev.txt itself.
• Added a "ruff format --check plugins tests" CI step next to the existing
  "ruff check" step, and tools/check-lock-drift.py, now a belt-and-
  suspenders guard between a hand edit and the next dependabot run rather
  than a substitute for one. Covered by tests/test_check_lock_drift.py.
• Every --require-hashes install site touched by this PR now also carries
  --no-deps, per this repo's own no-deps-gate hook (ADR-1062): a fully
  hash-pinned closure should not ask pip to re-derive dependencies.
• Every reference to the old filenames updated: .github/workflows/ci.yml
  and release.yml install steps, tools/check-lock-drift.py and its test,
  README.md, CONTRIBUTING.md, .bestpractices.json. Grepped the tree
  afterward; the only remaining hit is a historical sentence in
  check-lock-drift.py's own docstring describing the bug this fixes.

PR #40 status (measured, not assumed)

Checked PR #40 (fix/context-guard-smoke-and-structure) at its current tip
aec0f18 directly under ruff 0.16.6: ruff check and ruff format --check are
both clean on all three files this PR excludes
(plugins/context-guard/hooks/stop-context-guard.py, subagent-tracker.py,
tests/test_context_guard_hooks.py). The 4 findings measured in an earlier
push (tests/test_context_guard_hooks.py: 1 I001, 3 PLW1510) are gone.
Rebasing this branch onto main after #40 merges should be mechanical;
neither #40's diff nor its ruff state should require anything further
here.

Dependabot PRs #37/#38

Both (dependabot/pip/coverage-7.16.1, dependabot/pip/ruff-0.16.8) touch
only the old requirements-dev.txt path under the old "pip" ecosystem
entry. After this PR merges, requirements-dev.txt no longer plays that
role (it's the compiled lock) and the pip ecosystem entry is gone, so
these two PRs cannot be rebased; they need to be closed. Dependabot will
propose equivalent updates against requirements-dev.in under the new "uv"
ecosystem entry on its next scheduled run. No comment posted on either
PR per instructions.

Test plan

• Fresh-venv install from the new requirements-dev.txt with
  --require-hashes --no-deps prints the versions requirements-dev.in
  declares
• tools/check-lock-drift.py fails on a deliberately desynced scratch
  copy and passes on the real .in/.txt pair (raw output in the commit
  messages)
• ruff check plugins tests and ruff format --check plugins tests
  clean under 0.16.6 on every file this PR touches
• Full suite: 80 passed, coverage 93% (fail_under 80)
• CI green after rebase onto main once fix(context-guard): repair README smoke test, decompose oversized hooks, bump 2.0.2 #40 merges (orchestrator to
  verify and re-engage)

🤖 Generated with Claude Code

[cdeust]

Summary

Verified at the source (not from the PR description): the rebased tip (6c359f3) fixes #39 correctly; the .in/.txt rename genuinely enables dependabot's uv ecosystem to manage the compiled lock (confirmed against dependabot-core@f3a79fa0 RequiremenstFileMatcher#compiled_file?, Uv::FileFetcher, and Python::SharedFileFetcher#required_files_in?/#requirements_file?), the pure-format commit is independently AST-identical (ast.dump() sha256 recomputed from scratch, matches the disclosed hashes for all 10 files), --no-deps installs cleanly with pip check reporting no broken requirements, and no stale requirements-dev.lock reference remains outside a docstring's historical description of the bug. However, one commit labeled as a mechanical lint fix silently changed exception-handling behavior in a way that turns a loud crash into a silently-zeroed cost report, and the new CI drift guard has two real parsing gaps; one of which is exactly the "guard silently passes a real drift" failure mode this review was asked to hunt for, confirmed by mutation testing against the shipped test suite. Verdict: REQUEST CHANGES.

Stakes classification (Move 7)

High. Touches .github/workflows/ci.yml/release.yml (hash-locked supply chain), .github/dependabot.yml, and a 24-file / ~1300-line diff. Not requesting a split: the pure-format commit is independently verified AST-identical, and the format-in-lint-commit mixing is disclosed in both the commit message and PR body.

Move 0: Ledger reconciliation and seen-defect check

• PR body enumerates every commit's scope and rationale; the exclusion of plugins/context-guard/hooks/{stop-context-guard.py,subagent-tracker.py} and tests/test_context_guard_hooks.py is not a bare "out of scope"; it cites PR #40 owning those files and reports an independent re-check of PR #40's tip (aec0f18) confirming ruff check/ruff format --check are clean there. That's a verified scope boundary, not a bypass. No un-issued "pre-existing/unrelated" rationalization found.
• One material omission: the PR body describes the 8a53bd8 lint commit purely in terms of ruff rule IDs (SIM115, PLW1510, I001, RUF100, FURB122, EXE001) with no mention that the SIM115 rewrite in subagent_usage.py changed what exceptions are caught (see Blocking #1). This isn't a dismissed defect (the author likely didn't notice it), so it doesn't trigger the hard REFUSED path, but it must be fixed before merge.
• Verdict short-circuit: N/A, proceeding to Moves 1-6.

Layer check (Move 1)

No layer violations. tools/check-lock-drift.py is a standalone CLI script with no imports into plugins/; the plugin-side lint fixes don't cross any plugin boundary.

SOLID audit (Move 2)

• subagent_usage.py: _keyed_usage_record/_dedupe_by_message extraction (boy-scout, to stay under the nesting-depth cap) is a clean SRP split; parsing vs. folding. No objection to the refactor shape itself.
• measure_refine_overhead.py: _extract_prompt extraction is the same pattern, same verdict.
• No OCP/LSP/ISP/DIP issues found in the diff.

Wiring & contract drift (Move 3)

• New public-ish symbols _keyed_usage_record, _dedupe_by_message, _extract_prompt are all wired (called from parse_transcript_usage/collect_prompts respectively).
• tools/check-lock-drift.py is new and wired into ci.yml (Verify requirements-dev.txt matches requirements-dev.in step).
• No dead code, no bare TODOs, no debug prints found in the diff.
• Contract drift: see Blocking #1; parse_transcript_usage's documented postcondition ("zeroed if the file is missing/unreadable") no longer matches its actual behavior (also zeroed on malformed per-record usage data), and no caller/test was updated to reflect it.

Test adequacy (Move 4)

• tests/test_check_lock_drift.py covers the happy path, a version mismatch, a missing pin, comment/hash-line skipping, and both main() exit codes; good baseline coverage of stated behavior.
• Mutation-tested tools/check-lock-drift.py in a scratch copy (4 targeted mutants + 1 probe) against the actual shipped tests/test_check_lock_drift.py:
• != → == at the mismatch comparison: killed (4 tests fail).
• delete the is None branch: killed (test_pin_missing_from_lock_is_reported fails).
• return 1 → return 0 on drift: killed (test_main_exits_nonzero_on_drift fails).
• drop .lower() in _parse_pins: SURVIVED; zero tests fail. The shipped suite never exercises case-insensitive or separator-normalized matching; this is exactly the mutation-testing signal that names a missing test (Move 4 §3.2 suite-strength requirement).
• No test exists for subagent_usage.py's new exception-scope behavior (Blocking #1); the change is both undisclosed and untested.

Complexity & structure (Move 5)

No size-limit violations. All extracted helpers are well under the 50-line function cap; check-lock-drift.py is 92 lines total. No over-engineering smells.

Security & hygiene (Move 6)

• No security smells. --no-deps addition on every --require-hashes install site is a genuine hardening (matches ADR-1062 cited in the commit message) and was verified: fresh venv install from the new requirements-dev.txt with --require-hashes --no-deps succeeds and pip check reports no broken requirements (macOS/arm64/py3.14 used as a proxy for CI's ubuntu/py3.11; a missing transitive under --no-deps fails loudly at import/resolve time rather than silently, so this is a reasonable proxy, not a gap).
• Commit hygiene: conventional prefixes throughout, each commit independently gated and disclosed, no secrets, no stray binaries.

Issues

Blocking

• plugins/context-guard/tools/subagent_usage.py (introduced in 8a53bd8, parse_transcript_usage); the "mechanical" SIM115 fix (moving open() into a with statement) also merged the exception scope: previously try: fh = open(...) except (OSError, TypeError, ValueError): return Usage() guarded only the open call, and the record loop ran under a separate bare try/finally that let a ValueError/TypeError from int() inside _ctx_magnitude (e.g. a transcript record with "input_tokens": "abc") propagate. Now both are under one except (OSError, TypeError, ValueError), so that same malformed record silently produces a zeroed Usage() for the entire transcript instead of raising. Reproduced directly: old code raises ValueError: invalid literal for int() with base 10: 'abc'; new code returns Usage(input_tokens=0, ...) with no error. This contradicts the function's own docstring postcondition ("zeroed if the file is missing/unreadable"; not "if a record is malformed") and turns a detectable data-quality bug into a silent cost-under-report. Not covered by any test in tests/test_subagent_usage.py. Required change: either narrow the except back to wrapping only the open() call (restore the crash-on-malformed-data behavior), or if the wider swallow is intentional, document the new postcondition explicitly and add a test asserting it.

• tools/check-lock-drift.py:31,42 (_PIN_RE, _parse_pins); extras syntax (pkg[extra]==1.0) is not matched by _PIN_RE ([ breaks the name-character class), so such a line is silently dropped from both the manifest and lock parse. Empirically confirmed: manifest coverage[toml]==7.16.0 vs. lock coverage[toml]==5.0.0 (a real, large version drift) yields find_drift() == [] and the script prints "matches every pin" / exits 0. This is the exact "guard silently passes a real drift" failure mode this review was asked to hunt for. No current pin in requirements-dev.in uses extras, so it isn't live today, but the guard's entire purpose is to fail loud on drift, and this is a hole in that guarantee for any future extras-pinned dev dependency. Required change: strip an optional \[[^\]]*\] before matching == (e.g. extend _PIN_RE or pre-strip extras in _parse_pins), plus a regression test with an extras-pinned package desynced between the two files.

• tools/check-lock-drift.py:42 (_parse_pins); PEP 503 name normalization is incomplete: only .lower() is applied, so - vs _ (and .) are treated as different package identities. Foo-Bar==2.0 in .in vs foo_bar==2.0 in .txt (same package, same version) is reported as "declared but absent from the lock" rather than recognized as matching; a false positive rather than a false negative, so it fails loud rather than silently passing drift, but it's still a defect in a diagnostic gate whose value is precision. Confirmed via mutation testing: removing the existing .lower() call from _parse_pins does not fail a single test in the shipped tests/test_check_lock_drift.py; there is no case-insensitivity test at all, so the mutation survives. Required change: normalize with re.sub(r"[-_.]+", "-", name).lower() per PEP 503 in _parse_pins, plus tests for case and separator variants.

Non-blocking

• tools/check-lock-drift.py only checks manifest→lock (every .in pin present and matching in .txt); it does not flag a package present in .txt but absent from .in. This is correct scoping, not a gap; a compiled --universal lock legitimately carries transitive dependencies (iniconfig, packaging, pluggy, pygments) that never appear in .in, so a reverse check would false-positive on every compile. Worth a one-line docstring note that this is a deliberate one-directional check, so a future reader doesn't "fix" it into a false-positive machine.
• tools/check-lock-drift.py's docstring still says "compares... every direct dependency"; technically true only for pins the regex actually parses; consider footnoting the extras caveat once #2 above is fixed, so the contract stays honest.

Hand-offs

• None required. The two guard-parsing fixes and the exception-scope fix are small, root-cause, in-repo changes; no architectural or cross-cutting rework needed.

Verdict

REQUEST CHANGES.

Minimum set to unblock merge:

1. Fix (or explicitly document + test) the exception-scope widening in subagent_usage.py::parse_transcript_usage introduced by 8a53bd8.
2. Fix _PIN_RE/_parse_pins in tools/check-lock-drift.py to handle extras syntax without silently dropping the pin from comparison, with a regression test.
3. Add PEP 503 name normalization (-/_/case) to _parse_pins, with tests; the current suite's zero-test-failure result on a .lower()-removal mutant demonstrates this path is unverified today.

Everything else in the PR (the rename's dependabot-core compatibility, the AST-identical formatting, --no-deps correctness, and the stale-reference cleanup) checks out against the source and is ready to merge once the above three are addressed.

[cdeust]

Re-verification of commit 098c738 (fresh scratch repros, not trusting the commit message)

All three prior blocking findings are fixed. Verdict: APPROVE (pending the CI-scope note below, which is non-blocking).

1. subagent_usage.py exception scope

_open_transcript(path) returns a bare open() handle (no with inside it), narrowly guarded by except (OSError, TypeError, ValueError): return None. The caller does fh = _open_transcript(path); if fh is None: return Usage(); with fh: ....

This is legitimate, not a SIM115 dodge:

• ruff check --select SIM115 on the file: all checks passed. The rule doesn't fire because the function's only job is to open-and-return; nothing runs between open() succeeding and the caller entering with fh:, so there is no window where the handle exists outside a context manager while doing work.
• Leak check: wrapped open to capture the handle instance, forced the malformed-record path. Handle's .closed is True after the ValueError propagates, confirming with fh: closes it on the exception path.
• Behavior repro, red before / green after, reproduced independently:
  • Before (8a53bd8): su.parse_transcript_usage(path) on a record with "input_tokens": "abc" returns a zeroed Usage(), no exception. RED.
  • After (098c738): same input raises ValueError: invalid literal for int() with base 10: 'abc'. GREEN, matches origin/main's pre-8a53bd8 behavior exactly.

2. check-lock-drift.py extras / hard-error / markers

Fresh scratch repros against tools/check-lock-drift.py at 098c738:

== extras drift repro (coverage[toml] 7.16.0 vs 5.0.0) ==
lock.txt is out of date with in.txt:
  - coverage: requirements-dev.in pins 7.16.0, requirements-dev.txt pins 5.0.0
exit=1

== unparseable manifest line ("this is not a pin line") ==
unparseable requirements-dev.in line 1: 'this is not a pin line'
exit=1

== env marker still handled (colorama ; sys_platform == 'win32') ==
lock3.txt matches every pin in in3.txt.
exit=0

== dash/underscore normalization (Foo-Bar vs foo_bar, same version) ==
lock4.txt matches every pin in in4.txt.
exit=0

All four match the commit's claims exactly.

3. PEP 503 normalization mutation-killed

Re-ran mutation testing against the shipped tests/test_check_lock_drift.py (18 tests, all passing on the real code):

• Drop .lower() from _normalize (keep only separator collapse): 4 tests fail (test_normalize_lowercases, test_normalize_collapses_separators, test_desynced_separator_variant_is_recognized_as_the_same_package, test_separator_variant_with_real_drift_is_still_caught); matches the commit message exactly.
• Drop the re.sub separator collapse from _normalize (keep only .lower()): 2 tests fail (test_normalize_collapses_separators, test_desynced_separator_variant_is_recognized_as_the_same_package); matches exactly.
• Also mutated the extras regex group away entirely: 4 tests fail (test_parse_pins_handles_extras, test_parse_manifest_pins_handles_extras, test_extras_drift_is_detected_not_silently_passed, test_extras_with_multiple_names_and_marker).
• Also replaced the strict-manifest raise ValueError with a silent continue: 2 tests fail (test_manifest_unparseable_line_raises, test_main_reports_unparseable_manifest_line), and it visibly reproduces the exact "guard silently passes a real drift" failure mode this whole review chain exists to close (prints "matches every pin" with a genuinely unparseable line present).

Every mutant that should die, dies. Full suite: 103 passed. ruff check/ruff format --check on plugins tests tools: all clean.

CI scope: tools/ is not linted

.github/workflows/ci.yml runs ruff check plugins tests and ruff format --check plugins tests; tools/ (where the new drift guard lives) is outside both. The commit's own gate evidence ran ruff check/format --check against plugins tests tools locally, and I confirmed ruff check plugins tests tools and ruff format --check plugins tests tools both pass cleanly right now, at zero cost to add.

Recommendation (non-blocking, but worth doing in this PR or a fast follow-up): add tools to both CI lint/format steps. tools/check-lock-drift.py is the safety-critical guard this whole issue is about; a future edit that reintroduces one of the mutants above (or a plain formatting drift) would ship unnoticed by CI's own lint gate, caught only if someone happens to run the test suite against a scratch-desynced pair. The chmod +x tools/gen-bundle-sbom.py boy-scout fix in this commit is fine as-is (documented direct-invocation usage, correct shebang, matches the same EXE001 pattern from 0d992fe).

No modifications made to the branch beyond this verification pass (scratch repros only, working tree restored to 098c738 clean).