pi-lens 4.4.3 → 4.4.4

package/dist/mcp/worker.js

@@ -2,80 +2,83 @@
 import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
 import {
   analyzeFile
-} from "../chunk-H6MF6EVN.js";
-import "../chunk-OXXKQCSV.js";
-import "../chunk-EJIUXPBX.js";
-import "../chunk-2CD5RS6M.js";
-import "../chunk-FC4RP4I2.js";
-import "../chunk-UZ3TUTRV.js";
-import "../chunk-XMSXXAHW.js";
-import "../chunk-77M37OKR.js";
-import "../chunk-CSHFH5IN.js";
-import "../chunk-VCHXCQFG.js";
-import "../chunk-3EFKIGZN.js";
-import "../chunk-MRXKYPCS.js";
-import "../chunk-7DYBLXYA.js";
-import "../chunk-AB3YYG6N.js";
-import "../chunk-YSZNHOBY.js";
-import "../chunk-RPLINGVB.js";
-import "../chunk-XCJN5IJU.js";
-import "../chunk-76MWC2K6.js";
-import "../chunk-GXW6K4YJ.js";
-import "../chunk-2B73ZPOK.js";
-import "../chunk-YYOIQFRS.js";
+} from "../chunk-CT4MN5IU.js";
+import "../chunk-UBOQLVT2.js";
+import "../chunk-5OFV52AM.js";
+import "../chunk-RKBXZN3A.js";
+import "../chunk-6HWVI6MI.js";
+import "../chunk-S67KYG37.js";
+import "../chunk-KN35K52N.js";
+import "../chunk-ROYSX2S5.js";
+import "../chunk-YH5MVY2U.js";
+import "../chunk-ED36RF6Y.js";
+import "../chunk-BWD5EPKO.js";
+import "../chunk-TIQ2PKDW.js";
+import "../chunk-EBC36LNN.js";
+import "../chunk-HYGZEMX6.js";
+import "../chunk-UZ2XCLYS.js";
+import "../chunk-ZHH37KZL.js";
+import "../chunk-Y6GZHWSJ.js";
+import "../chunk-IYNJ6YPZ.js";
+import "../chunk-EUXZEFTV.js";
+import "../chunk-T57LYLZT.js";
+import "../chunk-XHJBS436.js";
 import "../chunk-3MED75HT.js";
-import "../chunk-M6HSLBWY.js";
-import "../chunk-IBGIOBEE.js";
+import "../chunk-RVK72CZX.js";
+import "../chunk-IWDLU6K3.js";
 import "../chunk-XIMYZ3JA.js";
-import "../chunk-EU63SDCG.js";
-import "../chunk-VWCXW2E7.js";
-import "../chunk-FCSOVF55.js";
-import "../chunk-PNQDPDRC.js";
-import "../chunk-ZXYDQ3TZ.js";
+import "../chunk-3DA2JDOL.js";
+import "../chunk-HWCCCQNX.js";
+import "../chunk-CUHSHSB6.js";
+import "../chunk-UA7ZXYDR.js";
+import "../chunk-T7FEBKXN.js";
+import "../chunk-SRYEJNES.js";
 import "../chunk-5W3R6LFT.js";
-import "../chunk-QHJ6DQ2R.js";
+import "../chunk-V35JG4JB.js";
+import "../chunk-XTBDCR27.js";
+import "../chunk-MPNJLASA.js";
+import "../chunk-US7ECLD7.js";
 import "../chunk-Z54ZSOBZ.js";
-import "../chunk-724UL2TJ.js";
-import "../chunk-QOZXJ4NA.js";
-import "../chunk-GBPP5P7X.js";
-import "../chunk-P7266HLM.js";
-import "../chunk-MQLUAEOC.js";
-import "../chunk-52FUZI6K.js";
-import "../chunk-SAEFPSB6.js";
-import "../chunk-GAEGEPOC.js";
+import "../chunk-GXFV6MYU.js";
+import "../chunk-FM4RDMKT.js";
+import "../chunk-RMLC67LF.js";
+import "../chunk-W66O5E25.js";
+import "../chunk-7HXE67BN.js";
 import "../chunk-Z3CCVDUB.js";
-import "../chunk-L3BLXZG7.js";
+import "../chunk-KAPJINKN.js";
+import "../chunk-AGSS7277.js";
 import "../chunk-2BEMIWEW.js";
-import "../chunk-ACXEQZOU.js";
-import "../chunk-Q7DUK4LX.js";
-import "../chunk-AW7R2GWG.js";
-import "../chunk-RWWYJ623.js";
-import "../chunk-VRZP76YM.js";
-import "../chunk-QOBUHWHX.js";
-import "../chunk-QILIYSJF.js";
-import "../chunk-6C7JWPCP.js";
-import "../chunk-5NGR67U5.js";
-import "../chunk-C34ZXZ7O.js";
+import "../chunk-IJYGIDF4.js";
+import "../chunk-GAQ7OQG6.js";
+import "../chunk-DEL2U6CM.js";
+import "../chunk-5VSF4UUQ.js";
+import "../chunk-3KAZU3VR.js";
+import "../chunk-P63GXC37.js";
+import "../chunk-HRNHZA3N.js";
+import "../chunk-TLX72JTG.js";
+import "../chunk-DGUKIYSI.js";
+import "../chunk-XBJVAEEO.js";
+import "../chunk-KUA4OJ5Y.js";
 import "../chunk-BW5KFIQC.js";
 import "../chunk-QYF5S6P6.js";
-import "../chunk-PHDMFAKM.js";
-import "../chunk-2BBLFX75.js";
-import "../chunk-XVF2VVXP.js";
+import "../chunk-DUO2TU77.js";
+import "../chunk-J6MPGQTS.js";
+import "../chunk-5HSRT26B.js";
 import {
   setProjectTrustState
-} from "../chunk-ZANLILYD.js";
+} from "../chunk-M2IFVFWU.js";
 import "../chunk-2EECBNC5.js";
-import "../chunk-JAU72XNY.js";
+import "../chunk-J64T55EI.js";
 import {
   logExtension
-} from "../chunk-XTMJ7XDT.js";
+} from "../chunk-POMLXPMY.js";
 import "../chunk-JMYYOTQG.js";
-import "../chunk-QQNQ7SJW.js";
-import "../chunk-AOHZU2BM.js";
+import "../chunk-QBFBRV2B.js";
+import "../chunk-YNE3RP52.js";
 import "../chunk-LJDODBBZ.js";
-import "../chunk-CHOW74WE.js";
+import "../chunk-CYRKQRPM.js";
 import "../chunk-ABBOA7UD.js";
-import "../chunk-N2H3ZPZY.js";
+import "../chunk-3RKP3FMS.js";
 import "../chunk-NXL4FFQQ.js";
 
 // dist/mcp/worker.js

package/dist/probes/installer.js

@@ -53,31 +53,31 @@ import {
   verifyNpmPackageEntry,
   verifyToolBinary,
   wasLastResolveTransient
-} from "../chunk-ACXEQZOU.js";
-import "../chunk-Q7DUK4LX.js";
-import "../chunk-AW7R2GWG.js";
-import "../chunk-RWWYJ623.js";
-import "../chunk-VRZP76YM.js";
-import "../chunk-QOBUHWHX.js";
-import "../chunk-QILIYSJF.js";
-import "../chunk-6C7JWPCP.js";
-import "../chunk-5NGR67U5.js";
-import "../chunk-C34ZXZ7O.js";
+} from "../chunk-GAQ7OQG6.js";
+import "../chunk-DEL2U6CM.js";
+import "../chunk-5VSF4UUQ.js";
+import "../chunk-3KAZU3VR.js";
+import "../chunk-P63GXC37.js";
+import "../chunk-HRNHZA3N.js";
+import "../chunk-TLX72JTG.js";
+import "../chunk-DGUKIYSI.js";
+import "../chunk-XBJVAEEO.js";
+import "../chunk-KUA4OJ5Y.js";
 import "../chunk-BW5KFIQC.js";
 import "../chunk-QYF5S6P6.js";
-import "../chunk-PHDMFAKM.js";
-import "../chunk-2BBLFX75.js";
-import "../chunk-XVF2VVXP.js";
-import "../chunk-ZANLILYD.js";
+import "../chunk-DUO2TU77.js";
+import "../chunk-J6MPGQTS.js";
+import "../chunk-5HSRT26B.js";
+import "../chunk-M2IFVFWU.js";
 import "../chunk-2EECBNC5.js";
-import "../chunk-JAU72XNY.js";
-import "../chunk-XTMJ7XDT.js";
+import "../chunk-J64T55EI.js";
+import "../chunk-POMLXPMY.js";
 import "../chunk-JMYYOTQG.js";
-import "../chunk-QQNQ7SJW.js";
-import "../chunk-AOHZU2BM.js";
+import "../chunk-QBFBRV2B.js";
+import "../chunk-YNE3RP52.js";
 import "../chunk-LJDODBBZ.js";
 import "../chunk-ABBOA7UD.js";
-import "../chunk-N2H3ZPZY.js";
+import "../chunk-3RKP3FMS.js";
 import "../chunk-NXL4FFQQ.js";
 export {
   GITHUB_TOOLS,

package/dist/workers/project-snapshot-persist-worker.js

@@ -4,19 +4,38 @@ import {
 } from "../chunk-2BEMIWEW.js";
 import {
   serveGzipStageWorker
-} from "../chunk-UOPVJQ4N.js";
+} from "../chunk-IJYGIDF4.js";
 import "../chunk-LJDODBBZ.js";
 import "../chunk-NXL4FFQQ.js";
 
 // dist/clients/project-snapshot-persist-worker.js
+import { parentPort } from "node:worker_threads";
 function semanticSnapshotFingerprint(request, body) {
   return fingerprintProjectSnapshotJson(body, request.generatedAt);
 }
-serveGzipStageWorker((request) => ({
-  id: request.id,
-  generation: request.generation,
-  stagePath: request.stagePath
-}), {
-  semanticFingerprint: semanticSnapshotFingerprint,
-  skipIfFingerprints: (request) => request.priorFingerprints
-});
+function serveForcedFailure() {
+  parentPort?.on("message", (message) => {
+    try {
+      if (typeof message !== "object" || message === null || !("id" in message) || !("generation" in message))
+        return;
+      parentPort?.postMessage({
+        id: message.id,
+        generation: message.generation,
+        error: "forced snapshot worker failure (PI_LENS_TEST_SNAPSHOT_WORKER_FAIL)"
+      });
+    } catch {
+    }
+  });
+}
+if (process.env.PI_LENS_TEST_SNAPSHOT_WORKER_FAIL === "no-stage-path") {
+  serveForcedFailure();
+} else {
+  serveGzipStageWorker((request) => ({
+    id: request.id,
+    generation: request.generation,
+    stagePath: request.stagePath
+  }), {
+    semanticFingerprint: semanticSnapshotFingerprint,
+    skipIfFingerprints: (request) => request.priorFingerprints
+  });
+}

package/dist/workers/review-graph-persist-worker.js

@@ -1,7 +1,7 @@
 import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
 import {
   serveGzipStageWorker
-} from "../chunk-UOPVJQ4N.js";
+} from "../chunk-IJYGIDF4.js";
 import "../chunk-LJDODBBZ.js";
 import "../chunk-NXL4FFQQ.js";
 

package/docs/configuration.md

@@ -221,6 +221,17 @@ once no matter which spelling each file uses. Migrating does not change the
 answer, staying un-migrated is not a way around the denial, and a half-migrated
 pair of files merges rather than one clobbering the other.
 
+Denying a file's **language server** (its primary, such as `json` or
+`typescript`) leaves that file unchecked for the language itself. Every
+diagnostics route then reports a file with no findings as **unconfirmed**, not
+clean, with a "Primary LSP (…): not available" note that says it is disabled in
+config. On write-time checks the note appears once per server per session, and
+a later write of such a file shows a one-line "unconfirmed" status instead of
+"clean". When the denied server has a fallback (`deno` for `typescript`) that
+cannot start either, the note says so. Cross-file (cascade) checks name the
+server once per session. Auxiliary scanners such as `typos` still run and
+report their own findings.
+
 Two rules make the rest of the table unambiguous:
 
 - **The search stops at `$HOME`.** pi-lens never reads a config file in your

package/docs/engineering-principles.md

@@ -55,6 +55,14 @@ event per session, never one per occurrence in a loop; repeated degradations go
 through a once-only or counted record. A discriminator nothing can observe is a
 vacuous guard and does not ship.
 
+**Gates fail closed on what they do not recognize.** When code decides a
+verdict (a trust check, a lint, a census, a body check), it admits a short list
+of known-good forms and refuses everything else. It never enumerates known-bad
+spellings. Each review of an enumerated gate finds the next spelling it missed;
+one gate took sixteen rounds that way. Once a second round finds a new
+spelling, stop patching and redesign. Screen: can an input nobody planned for
+pass the gate?
+
 **Blast radius as a call-tree diff.** For any change to a shared seam, list the
 changed symbol, its callers above, its callees below, with plus and minus on the
 lines that moved. Prose keeps missing callers; a tree the reviewer can grep does
@@ -118,6 +126,12 @@ thing is required, a registry entry, a baseline row and lane membership. A
 mocked seam is not a real spawn and gets an exemption with its reason, never an
 admission.
 
+**A new ratchet sweeps the open changes before it lands.** A governance test
+that rejects a new pattern fails every open change that already adds one, and
+none of them conflict textually, so nothing warns. Before merging a ratchet,
+run it against each open change merged with the base, and fix or notify each
+one it fails. Screen: which open change would fail this test after the merge?
+
 **Run targeted files while iterating; the full suite runs once.** Build before
 testing when tests execute compiled output, and rebuild between mutations. A red
 is environmental only when the same test is red on the base branch in the same
@@ -156,6 +170,13 @@ literal, a changelog line) are applied by the orchestrator as trailing commits
 and never re-verified; anything that changes what code means goes through a
 round, however small it looks.
 
+**A round does what its brief prescribes, and flags anything more.** A worker
+that changes something outside its brief lists that change as scope growth at
+the top of its hand-off; one round widened a shared detector while asked to add
+a single admission. Routing then re-classifies the round, because a silent extra
+mechanism turns a merge-on-green round into one that needs a verify. Screen:
+does the hand-off name every change the brief did not ask for?
+
 **Merge gate.** Merge only when the verdict is merge-ready, every gating check
 genuinely executed and passed on the exact head, and every failing check was
 read and judged. Absent is not green. Read exit codes directly, never after a
@@ -170,11 +191,22 @@ at the worktree root; the orchestrator commits. Implementation and review are
 never mixed in one delegation. Scope changes are mirrored on the tracking issue
 before they are sent, so the worker can verify them.
 
+**Work in progress survives a cut.** A worker with Git authority commits at
+each green step; one without it leaves its tree and names it in the hand-off.
+A backend outage, a quota stop or a crash then costs one step, not the round,
+and the next round ports the tree instead of redoing it. Screen: how much is
+lost if this process dies now?
+
 **No manufactured work.** An idle worker is cheaper than fake work. Delegate
 when a real producer, consumer, probe or diagnosis is unresolved, never to keep
 a pool busy. The same applies to status artifacts: they exist for coordination
 someone consumes.
 
+**A step done by hand twice becomes a script with a test.** That includes
+cleanup, triage and status upkeep. The script surfaces unfinished work and
+never hides it: stalled work is restarted, not unassigned, archived or deleted.
+Screen: is this the second time this step was done by hand?
+
 ## 4. Honesty and records
 
 **Closes versus refs follows delivery, not optimism.** Close only when every

package/docs/lsp-capability-matrix.md

@@ -283,5 +283,5 @@ date-based `direct` expiry (#3401) and consecutive-night `idle-eviction`
 counts (#3989). Regenerated every run; never a measurement.
 
 ```json
-{"first-publish":{"dockerfile":{"firstMissed":"2026-10-10"},"prisma":{"firstMissed":"2026-10-10"},"python":{"firstMissed":"2026-10-10"},"shell":{"firstMissed":"2026-10-10"},"terraform":{"pendingFirstPublish":"direct","runs":1},"yaml":{"firstMissed":"2026-10-10"}}}
+{"first-publish":{"typescript":{"pendingFirstPublish":"direct","runs":1}}}
 ```

package/docs/lsp-idle-eviction.md

@@ -15,7 +15,7 @@ respawned server reports every finding it reported before eviction; the
 content-bound coverage check the auxiliary freeze depends on. A server that
 cannot demonstrate it is never proposed for eviction on perf grounds alone.
 
-_Last generated: 2026-10-10 on linux; 48 registry servers: 8 eligible, 0 vetoed, 16 inconclusive, 24 unavailable (0 not reached: budget)._
+_Last generated: 2026-10-18 on linux; 49 registry servers: 17 eligible, 0 vetoed, 18 inconclusive, 14 unavailable (0 not reached: budget)._
 
 ## Per-server rows
 
@@ -36,69 +36,58 @@ step log only, because it flaps.
 | server | role | declared | result | reason | respawn | coverage |
 |---|---|---|---|---|---|---|
 | ast-grep | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
-| bash | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| bash | primary | transparent | eligible | · | ok | preserved |
 | clojure | primary | transparent | eligible | · | ok | preserved |
 | cmake | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
 | cpp | primary | transparent | eligible | · | ok | preserved |
 | csharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| css | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| css | primary | transparent | eligible | · | ok | preserved |
 | cue | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | dart | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | deno | primary | transparent | eligible | · | ok | preserved |
-| docker | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| docker | primary | transparent | eligible | · | ok | preserved |
 | docker-official | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | elixir | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| expert | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
-| fish | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| expert | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
+| fish | primary | transparent | eligible | · | ok | preserved |
 | fsharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | gleam | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | go | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | haskell | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| html | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| html | primary | transparent | eligible | · | ok | preserved |
 | java | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | json | primary | transparent | eligible | · | ok | preserved |
 | kotlin | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| lean | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
 | lua | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | marksman | primary | transparent | eligible | · | ok | preserved |
 | nix | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | ocaml | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | omnisharp | primary | unmeasured | unavailable | no-fixture | n/a | n/a |
 | opengrep | auxiliary | transparent | eligible | · | ok | preserved |
-| php | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| php | primary | transparent | eligible | · | ok | preserved |
 | powershell | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
-| prisma | primary | transparent | unavailable | server-not-started | n/a | n/a |
-| python | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| prisma | primary | transparent | eligible | · | ok | preserved |
+| python | primary | transparent | eligible | · | ok | preserved |
 | python-jedi | primary | transparent | eligible | · | ok | preserved |
 | ruby | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | rust | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | shuck | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
-| svelte | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
+| svelte | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | swift | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | terraform | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | tinymist | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | toml | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | typescript | primary | transparent | eligible | · | ok | preserved |
 | typos | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
-| vue | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
-| yaml | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| vue | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
+| yaml | primary | transparent | eligible | · | ok | preserved |
 | zig | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | zizmor | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 
 ## Declared versus measured
 
-`drift` means the registry evicts a server the measurement vetoes. A `proposal`
-or `info` line is for a maintainer to act on in a follow-up; this run changed
-nothing.
-
-- **bash** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **css** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **docker** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **fish** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **html** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **php** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **prisma** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **python** [info] declared transparent with no evidence this run: unavailable (server-not-started)
-- **yaml** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+No divergence between declared policy and this run's measurement.
 
 ## Reasons
 

package/docs/pi-lens-fixer.md

@@ -32,12 +32,22 @@ exports change.
 - When a gate becomes fail-closed, sweep every construction site that reaches
   it, test doubles included, and prove the sweep with the behaviour suites
   (#3622).
+- A new module, or a new use of a detection or caching primitive (stat,
+  mtime, inode, content or line hash, directory walk, install stamp, sequence
+  counter), lists the existing modules that use the same primitive for the
+  same purpose. Find them by searching for the primitive, such as
+  `rg -l 'statSync|mtimeMs|createHash|readdir|projectSeq' clients`, never by
+  your own seam's call names. The consolidation verdict cites that list
+  (#4536).
 - A change on a lifecycle, timing, or identity seam extends or adds a TLA+
   model in this step (#3802; the rule itself is in `AGENTS.md`). Find the
   family in `formal/coverage-map.json`, write the invariant the change
   preserves or tightens, and show the violating config red on the pre-fix model
   and green after, or carry `TLA+ unaffected: <family> — <reason>` in the PR
-  body. A row is any-of (one listed family's model move or declaration
+  body. The unaffected line is wrong when the change alters a behaviour an
+  as-built config constant encodes: flip that constant, its configs and its
+  `formal/switch-pins.json` value instead, and keep its pin test red on the old
+  behaviour (#4387, #4393). A row is any-of (one listed family's model move or declaration
   satisfies it); a row of 4+ families only prints a note, except `index.ts`,
   whose row gates on the lifecycle hook handler a hunk lands in (#3878). The
   map owner is the lane that adds a `formal/<family>/`: it adds the family and
@@ -60,12 +70,13 @@ exports change.
   transcript quoted in `Test assessment`. A redundant test that still guards
   goes only with the named survivor that covers it.
 - Apply folded review follow-ups per `docs/pi-lens-subagent.md`
-  "Follow-ups", and list filed residuals in one **Residuals** section of the
-  PR body.
+  "Follow-ups", and list every gap left open in one **Accepted residuals** section of
+  the PR body, each named `p3` with its severity and live population (merge bar:
+  `docs/pi-lens-merge-policy.md` "Filing issues").
 
 ## Evidence
 
-- Use `scripts/mutate.mjs` for bounded hand mutations; it restores the target automatically, but only while the file still holds the mutated bytes. A leftover journal (`<file>.mutate-backup`) blocks the next run on that file; recover with `--restore`, which refuses and prints the three hashes when the file was edited since. If a crash left the file already at its original bytes, `--restore` also refuses; check the printed hashes and delete the journal by hand. `--restore` is crash recovery only: run against a live `mutate.mjs` run on the same file, it pulls that run's mutation, and that run then reports ERROR (exit 4).
+- Use `scripts/mutate.mjs` for bounded hand mutations; it restores the target automatically, but only while the file still holds the mutated bytes. A leftover journal (`<file>.mutate-backup`) blocks the next run on that file; recover with `--restore`, which refuses and prints the three hashes when the file was edited since. If a crash left the file already at its original bytes, `--restore` also refuses; check the printed hashes and delete the journal by hand. `--restore` is crash recovery only: run against a live `mutate.mjs` run on the same file, it pulls that run's mutation, and that run then reports ERROR (exit 4). The transcript's status line is `SURVIVED` (tests passed), `RED` (a test run failed), `REFUSED` (the edit was not applied), `BROKEN` (the build failed) or `ERROR` (no verdict); only `RED` proves a test catches the mutation (#4510).
 
 - Witness rule (ADR 0007): #1605 owns the witness lanes, and their fixtures
   live under `tests/fixtures/witness/<slice>/`.
@@ -81,19 +92,65 @@ exports change.
   from the pre-fix SHA (`git checkout <sha> -- clients/…`), never `tests`
   (#3166) and never uncommitted work, and run `git status` after any bulk
   restore. Without Git authority, use a saved patch.
-- Hand-mutate only the NEW guard, branch, filter, or cap the PR is about, both
-  directions, one row per direction, and quote the compile-valid red. The new
-  test is the only red under at least one mutation. This is the whole PR
-  mutation layer (AGENTS.md, #4005): there is no per-PR Stryker job, comment, or
+- Hand-mutate only the NEW guard, branch, filter, or cap the PR is about, and
+  the behaviour behind each relaxed assertion (next bullet), both directions,
+  one row per direction, and quote the compile-valid red. The new test is the
+  only red under at least one mutation. These rows are the whole PR mutation
+  layer (AGENTS.md, #4005): there is no per-PR Stryker job, comment, or
   `MUTATION` line, and no survivor triage. The nightly Stryker report on master
   is exploratory and is not read here. Use bounded hand probes locally; never
   run a full Stryker campaign in a worktree.
-- Every record the `Observability` section names is asserted by a test in the
-  diff and quoted in the body (#2642, #2647, #2649, #2654).
+- A PR that relaxes or rewrites an existing assertion (a changed meaning makes
+  the old expectation wrong) mutates the behaviour that test is named for. Quote
+  the red on the new assertion. A rewrite that stays green with that
+  behaviour broken is a deleted test (#4390: the eviction smoke's rewrite
+  passed with root re-registration broken).
+- A PR that adds or changes a detector (a ratchet, census or source scan)
+  writes STATE_TABLE.md before the first edit: each form the detector
+  admits, and the statement that every other form refuses. It then plants
+  three spellings its author did not design for: an alias, an indirect
+  call and a value reached through another binding. Quote each result. A
+  plant that stays green is fixed. A stated residual names an admitted
+  form that is too broad, never an unread spelling (AGENTS.md shape 69).
+- The manual per-test campaign (`stryker-pertest.yml`, #4365) lists tests that
+  cover mutated code but kill no mutant. It is a triage input, not a verdict:
+  a candidate that guards another seam or a named recurrence stays, and a
+  deletion it proposes lands only with the covering test named and the
+  reviewer's agreement test by test.
+- Every record the `Observability` section names is asserted by a test under
+  `tests/` (any collected test, not only a file this PR touches) and quoted in
+  the body (#2642, #2647, #2649, #2654). The body lint refuses a named record
+  literal no collected test reads back (`scripts/check-pr-body.mjs`, #4597), so
+  a record the section names without a read-back cannot merge; `none: <reason>`
+  still answers a diff with no record. A mention counts whatever its spelling:
+  a backticked span, a bare word and a link label are all read against the
+  record values the runtime emits, so prose that reuses a record's own name is
+  a mention too.
+- The read-back is the record's full name in an assertion, a comparison, a
+  `case` label or a record-keyed row inside a declaration vitest collects and
+  runs, or inside a module-scope helper that one of them calls. A title, a
+  `console.log`, a skipped test and an excluded tree do not count, and a record
+  named only through a table imported from another file does not either, so
+  inline the name in the assertion. The declaration may be spelled with a
+  computed modifier or bracket link (`it["only"]`) and through an alias
+  (`const t = it`); a form the lint cannot classify (`it[modifier]`, a
+  destructured alias) makes its whole file contribute nothing, so write the
+  declaration the plain way. Naming a record that predates the PR owes the same
+  test.
 - Every behavioural sentence (a docstring invariant, a memo, a registry
   justification) maps to a test or a probe, or is deleted (#2643, #2654).
 - Name where new state sits in its ladder and what happens to it at
   `session_start` (#2649, #2654).
+- A change on a hot path (dispatch, `session_start`, LSP diagnostics, a cache
+  lookup, turn-end) quotes a before/after timing from the real path in the
+  body, with the command, at a small and a large input; per-input work on a
+  tool path also needs a size or time bound. Name and justify any regression
+  (#4344 r1; #4368 r1). The `Hot-path latency (advisory)` lane (#4363) times
+  `session_start`, `dispatchLint` and the diagnostics-cache replay on the head
+  and its first parent (`HEAD^1`); read its job summary, and time by hand any
+  hot path it does not cover (a language server's time, a dependency bump).
+  Green means no regression of 1.25x and 5 ms; a "slower, below threshold" row
+  is still a number to read.
 - A measured constant names its measuring command and keeps raw output as a
   tracked artifact pinned by a test (#3648). Run `git check-ignore -v` on every
   new artifact path before citing it (#3648).
@@ -114,10 +171,31 @@ exports change.
   `node_modules`.
 - Run release-QA end to end when a release-QA row changes.
 - Run the reviewer's standing probes (`docs/pi-lens-reviewer.md`) that the diff
-  can trip, and quote their output in the PR body.
+  can trip, and quote their output in the PR body. The `verify-pi-lens` skill
+  (`.claude/skills/verify-pi-lens/SKILL.md`) holds the real-path recipes.
 
 ## Fix rounds
 
+- When bot threads or code-scanning alerts exist, read and dispose of each
+  one. A missing bot review is never evidence of anything: it never blocks the
+  round and never becomes something to wait for. The threads, every page:
+  `gh api graphql --paginate -f query='query($owner:String!,$name:String!,$number:Int!,$endCursor:String){repository(owner:$owner,name:$name){pullRequest(number:$number){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:1){nodes{author{login} body}}}}}}}' -F owner="$(gh repo view --json owner --jq .owner.login)" -F name="$(gh repo view --json name --jq .name)" -F number=<N> --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | "\(.id) \(.path):\(.line) \(.comments.nodes[0].author.login): \(.comments.nodes[0].body)"'`,
+  and the alerts:
+  `gh api --paginate "repos/{owner}/{repo}/code-scanning/alerts?ref=refs/heads/<branch>&state=open" --jq '.[] | "\(.number) \(.rule.id) \(.most_recent_instance.location.path):\(.most_recent_instance.location.start_line)"'`.
+  Both commands follow their cursor to the last page, so the list is clear
+  only after that page prints: one page is never read as the whole list.
+  An alert on another branch is not this round's; read the head you pushed.
+  Before the hand-back, reply to and resolve every thread this round fixes, and
+  name every other open thread and alert in the PR body with its disposition.
+  A round that finds none says so in one line and moves on. Where the brief
+  withholds GitHub writes
+  (`docs/pi-lens-subagent.md`),
+  put the same list in the body and the hand-back for the orchestrator to post
+  and resolve. The disposition words and the merge condition are
+  `docs/pi-lens-merge-policy.md` "The loop, per PR" step 1 and step 4
+  (`:34`, `:81`); this contract does not restate them. Recurrence: #4566 and
+  #4575 (2026-10-17), where the threads outlived the rounds that should have
+  read them.
 - On `FIX ROUND` findings, reproduce each finding before fixing it, add a
   red-first test for every behavioural fix, rebuild, re-run the targeted suites
   plus anything the findings touched, and push the same branch. If the PR reads
@@ -137,6 +215,9 @@ exports change.
 - Spot-check one prior round's mutation on the new head (#2583).
 - Re-read the changelog fragment for any claim the round retracts (#3155), then
   add an honest review-round section to the PR body.
+- Lint the PR body (`--lint-local`) before the first push of a round, not only
+  at hand-back: `PR body (advisory)` re-reads the same body on every push, so
+  an unfixed finding reds each one.
 
 ## Before the report
 
@@ -160,8 +241,17 @@ rigor (#2599).
   GitHub ignores it in a title.
 - Run `node scripts/check-pr-body.mjs --lint-local PR_BODY.md` and
   `node scripts/check-changelog-fragments.mjs` before the hand-back; both
-  must pass, and the hand-back quotes them. A red `PR body (advisory)` check is
-  a fix-before-review item. A changelog fragment is `---` /
+  must pass, and the hand-back quotes them. The body lint reads the closed
+  issue's labels through `gh api`; a `::warning::` that the Detection check
+  was skipped means gh failed, so the section was not required, not that it
+  passed (#4288). A non-bug PR either deletes the `## Detection` section or
+  fills the three lines, and a `Shape:` or `Enforcer:` line it does write is
+  validated too; free text in between reds the local preflight. A bug-closing
+  PR that answers a layer, the `Gap: none:` reason, the `Shape: new:` name or
+  the `Enforcer: none:` reason with `unknown`, `n/a`, `tbd` or `?` is refused
+  (#4519); the layer words are `DETECTION_LAYERS`, `nightly:<workflow>`
+  included. A red `PR body (advisory)` check is a fix-before-review item.
+  A changelog fragment is `---` /
   `section: <Added|Changed|Deprecated|Removed|Fixed|Security>` /
   `audience: <user|internal>` / `---` / blank / one `- ` bullet. New
   `audience: user` fragments must begin with a bold lead of at most 100
@@ -172,6 +262,20 @@ rigor (#2599).
   hit); `internal` is CI, tests, `formal/`, contributor docs, orchestration, and
   refactors with no observable change. `npm run changelog:check` checks the
   rollup, not fragments (#2456).
+- A bug fix's detection lesson names the defect SHAPE and its tree-wide
+  enforcer, not only a test for the instance: the `Shape:` line names the
+  `AGENTS.md` "Recurring defect shapes" number (or `new: <name>`), and the
+  `Enforcer:` line a test on base that scans the whole population, an issue to
+  build one, or `none: judgment-only, <reason>`. With `Shape: #N` a path
+  enforcer must be one catalog entry N names. The fix's own one-bug test is its
+  regression test, not the closed gap. The body lint enforces both lines
+  (#4439).
+- A `Shape: new: <name>` is a proposal, not a catalog entry: write the
+  proposed shape text in the PR body under "Proposed contract change
+  (maintainer decision)" and never edit `AGENTS.md`. Catalog shapes and rule
+  changes are the maintainer's decision; the orchestrator lands an approved
+  one in its own change (#4577's fixer added shape 74 unasked, and the
+  governance suites redded).
 - Every code fact in the PR body is a `` `path:line` `` citation the check
   verifies: the file must be in the committed tree (never an untracked or
   git-ignored path, which CI cannot read), and a fenced quote after it must