README gains a 'Coverage ratchet' section next to the #150 lock docs:
both floors (global 29, changed-lines 70), the raise-never-lower
doctrine, why the omitted canary files don't count, the merge-base
diff-range-notation choice, and the local reproduction commands.
RED-first (test_pr_context_diff_is_against_merge_base): the diff-cover
invocation now pins --diff-range-notation .. so the changed-lines diff
is against the merge base rather than the PR merge-ref tip — Gitea
Actions checks out the merge ref, and the default three-dot notation
would measure unrelated merge-commit lines. --compare-branch
origin/master is retained (fetch-depth: 0 guarantees the ref exists in
both push and PR contexts); the explicit range notation is the
supported mechanism diff-cover's CLI offers for pinning the range.
Both floors measured and committed: global 29% (.coveragerc [report]
fail_under, canary_* scripts omitted — they are CI-run scripts, not
imported code) and changed-lines 70% (diff-cover --fail-under in the CI
test job). doctrine: raise, never lower.
coverage + diff-cover join [project.optional-dependencies] dev and the
pinned CI lock is regenerated (uv pip compile ... --extra dev --extra
memory --python-version 3.11): coverage==7.16.0, diff-cover==10.5.1 plus
transitives. scripts/check_dep_lock.py passes (drift ratchet green).
tests/test_ci_lock_contract.py (RED-first): asserts the committed floors,
lock pins, lock-only install, fetch-depth: 0 on the test checkout, and
the coverage run / report --fail-under / xml / diff-cover step chain.
Per-finding map: finding -> commit -> red evidence for all six gate
findings (F1-F6), final battery numbers, and the F3+F5 shared-commit
deviation note.
Gate-review F6 (pre-existing): the type-check job still installed
".[dev,memory]" — the one remaining floating install, leaving the
PROTECTED type-check toolchain unreproducible. Switched to the same
lock-only pattern as lint/unit-tests/canary: pip install -r
requirements-ci.txt + pip install -e . --no-deps. The lock pins
pyright==1.1.411, so the ratchet now runs against a pinned pyright.
RED->GREEN: config-only finding; red evidence was ci.yml:196 installing
floating extras (gate finding). yaml.safe_load parses after the edit;
no floating 'pip install .[...] ' remains in any workflow.
Gate-review F4: two known blind spots were undocumented — (1) marker-only
drift (env-marker changes with identical pins) is invisible to the pin
diff, (2) direct-URL requirement lines are skipped by the old parser /
now fail loudly instead of being compared. Both disclosed in the module
docstring with guidance; no behavior change.
RED->GREEN: docs-only finding; red evidence is the pre-existing docstring
lacking the disclosure (gate finding itself). Checker behavior and tests
unchanged (15 pass).
Gate-review F3: with uv absent, run_uv_compile() let subprocess raise a
raw FileNotFoundError traceback. Now caught (sentinel -1) and main()
prints the house actionable pattern: what to install (pinned uv into
.ci-venv), what command (pip install + PATH export), local install doc.
Gate-review F5: uv's full resolution listing went to stdout even on
success, polluting CI logs. stdout/stderr are now captured and printed
only on compile failure.
RED->GREEN: new test (uv_binary stubbed to a missing binary, PATH
stripped) failed with FileNotFoundError, passes with exit 1 + actionable
stderr. Real smoke: successful run no longer prints uv's 'Resolved 37
packages' listing.
Gate-review F2: lock_requirements() silently skipped any requirement
line lacking '==', so a degraded floor-style lock (e.g. 'rune>=0.49.0')
would pass the drift diff with its floor pins intact. Options
(-r/--index-url/...) remain the only tolerated non-pin lines; any other
non-pinned form (floor, range, wildcard, bare name) now exits 1 with an
actionable message naming the offending line and the regen command.
RED->GREEN: two new tests (floor fixture + unpinned/wildcard variants)
failed against the skip behavior, pass after the loud-failure fix. The
pre-existing skip-options test was updated to match the tightened
contract; the committed lock (37 pins) still parses clean.
Gate-review F1: the drift-ratchet step installed uv==0.10.11 into
.ci-venv but never exported PATH, so check_dep_lock.py resolved
/usr/bin/uv (0.12.10) and re-compiled the lock with a different
resolver than generated it. Both ends fixed:
- ci.yml drift step: export PATH="$PWD/.ci-venv/bin:$PATH" before
invoking the checker.
- check_dep_lock.uv_binary(): prefer the interpreter-adjacent uv
(sys.executable's dir — where CI pins it) over shutil.which.
RED->GREEN: two new tests (PATH-stripped + decoy-uv-on-PATH) failed
against the old resolver order, pass after the fix.
README Development section: how to regenerate requirements-ci.txt after
dependency edits (exact uv pip compile command), why --python-version 3.11
(runner-interpreter markers), and why CI installs the project with
--no-deps (deps only from the pinned lock). Regeneration command and
rationale also documented in the scripts/check_dep_lock.py header.
All three CI venvs (.ci-venv, .test-venv, .canary-venv) now install deps
exclusively from the pinned requirements-ci.txt, then the project itself
with --no-deps — no floating escape hatch remains. The canary job's ad-hoc
'textual==8.2.8 textual-autocomplete==4.0.6 sqlite-vec || true' pre-install
is deleted: the lock pins exactly those versions. Lint job gains a
dependency-lock drift ratchet step (scripts/check_dep_lock.py) that fails
the job when the lock no longer matches pyproject.toml.
requirements-ci.txt: fully-pinned output of
'uv pip compile pyproject.toml -o requirements-ci.txt --extra dev --extra
memory --python-version 3.11' (plain pip format; runners need no uv).
scripts/check_dep_lock.py: drift ratchet — regenerates the compile into a
temp file, diffs requirement pins against the committed lock, exits 1 with
the regeneration command on drift. Unit-tested against fixture files.
Nick