yak(ratchets-deferred-decisions-handoff-practice-ccjp): ratchets, deferred decisions, handoff practice

AGENTS.md

@@ -142,8 +142,65 @@ failure ride along: if it predates your change, stop and discuss it with the use
 rather than working around it.
 
 Browser tests (`make playwright*`) are *external* verification and are **not**
-part of the Lens pass. Whether they ever join it is an open decision (see the yak
-"ratchets, deferred decisions, handoff practice").
+part of the Lens pass. Decided 2026-10-28 (human, yak "ratchets, deferred
+decisions, handoff practice"): it stays that way - Playwright is not wired into
+`make verify` or into either `VERIFY_SENSORS`. The targets need a running
+Phoenix server or the Docker Chrome container, and a gate that only runs with
+docker or sudo is not a gate the Lens pass can rely on. Run them as their own
+loop, by hand, when a change touches the browser surface.
+
+### Landing the plane
+
+The Lens pass is what you land with, so it is the last step of every session,
+not a thing that only happens on push:
+
+- After any session that changed code, run `make precommit`. It is `make check`
+  under its session-ending name and costs about a second; there is no session
+  where it is not worth running.
+- Before handing off - to a human, a reviewer, or the next agent - run
+  `make verify`, or push, which fires `.githooks/pre-push` and runs the same
+  pass on the same tree. A hand-off note that says "tests pass" without a Lens
+  pass behind it is a guess, not a hand-off.
+- A failing Lens pass is triaged into the classes above (see *Triage classes*)
+  and **reported** in the hand-off note, with the class it fell in. A nit gets a
+  yak; it does not get fixed inline mid-build. Never re-run until green.
+- `git push --no-verify` stays the deliberate override for a branch you know is
+  red. It is never how a session lands.
+
+## Ratchets
+
+The coverage threshold in `app/mix.exs` and `blogex/mix.exs` (the `threshold:`
+inside each `test_coverage/0`) is a **floor**, not a target:
+
+- After each behavior-test yak lands, re-measure both apps - `make test.coverage`
+  then `make coverage` inside each app - and raise the floor to the new total.
+  The convention is integer truncation of the measurement: a measured 82.61%
+  means a floor of 82. Never above the measurement: a floor that cannot pass is
+  not a ratchet, it is a red gate.
+- Never lower a floor. A legitimate drop is a conversation, not a config edit.
+  Lowering the number, or adding an `ignore_modules` entry to prop it up, hides
+  the behavior gap the floor exists to surface.
+- The record of the last measurement and its date is the comment above
+  `test_coverage/0` in that app's `mix.exs`. Update it there, in the same commit
+  as the number. Do not copy the totals into this file: one record, in the
+  place the gate reads, is the whole point.
+
+Two further health numbers are baselines-to-be; neither is `make verify`'s
+business yet, and neither is to be invented:
+
+- **CRAP offender count.** `make crap` in one app is the sensor: a passing run
+  prints `Summary: ... worst_score=...`, a failing run prints `High scores: N`
+  and the offending functions. Both apps sit under the default `--max-score
+  (30)`, and the decision (2026-10-28) not to lower it, plus the baseline
+  offender count, live in the comment above the `crap` target in
+  `app/Makefile` / `blogex/Makefile`.
+- **Mutation survivor count.** Mutation is a slot comment only in
+  `app/Makefile` and `blogex/Makefile` ("yak: mutation testing with muex - a
+  sensor, not a gate"), and `muex` is a dependency of neither app. Nothing has
+  been mutated, so there is no survivor baseline; do not conjure one from a run
+  that did not happen. When the mutation yak lands, its survivors become the
+  baseline the same way the coverage floor did: measured, dated, recorded where
+  the sensor lives.
 
 # Development
 Always fix failing tests, credo issues and format isseus.