pi-lens 4.4.4 → 4.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +45 -3
  3. package/config/biome/core.jsonc +3 -3
  4. package/config/dependency-cruiser-eager-allowlist.json +1 -0
  5. package/dist/{chunk-UBOQLVT2.js → chunk-2DDDCJDL.js} +4 -4
  6. package/dist/{chunk-RKKOYPRA.js → chunk-2DMLM3ZO.js} +13 -15
  7. package/dist/chunk-2F47TQOA.js +73 -0
  8. package/dist/{chunk-O4NWQT6I.js → chunk-2PHMIAKO.js} +4 -4
  9. package/dist/{chunk-DGUKIYSI.js → chunk-2RLWJO5K.js} +8 -10
  10. package/dist/{chunk-S67KYG37.js → chunk-2X4VLOCC.js} +2 -2
  11. package/dist/{chunk-TIQ2PKDW.js → chunk-3MYEA7QD.js} +4 -4
  12. package/dist/{chunk-3DA2JDOL.js → chunk-3WEPUD2V.js} +551 -203
  13. package/dist/{chunk-AMERCH6V.js → chunk-4AVZ3TG7.js} +15 -16
  14. package/dist/{chunk-IYNJ6YPZ.js → chunk-4PCQCU47.js} +4 -4
  15. package/dist/chunk-4WX4CTUE.js +57 -0
  16. package/dist/{chunk-P63GXC37.js → chunk-5APMQ2IJ.js} +31 -4
  17. package/dist/{chunk-ZIVJBOO3.js → chunk-5CV5ITZF.js} +2 -2
  18. package/dist/{chunk-6DLWKFEX.js → chunk-5ZR3APIM.js} +41 -42
  19. package/dist/{chunk-XTBDCR27.js → chunk-63RIVFQI.js} +4 -4
  20. package/dist/{chunk-GSLNCYGG.js → chunk-75SY4F24.js} +13 -14
  21. package/dist/{chunk-U44DJXQP.js → chunk-7RQXA5GG.js} +15 -18
  22. package/dist/chunk-A3YNG5KP.js +45 -0
  23. package/dist/{chunk-5OFV52AM.js → chunk-AE37FEGH.js} +1 -1
  24. package/dist/{chunk-BWD5EPKO.js → chunk-AMXIUN2R.js} +4 -6
  25. package/dist/{chunk-3KAZU3VR.js → chunk-ARD426WI.js} +2 -2
  26. package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
  27. package/dist/{chunk-YH5MVY2U.js → chunk-BHUWL2Y3.js} +7 -7
  28. package/dist/{chunk-CT4MN5IU.js → chunk-BI5LAQ3Y.js} +353 -359
  29. package/dist/{chunk-KAPJINKN.js → chunk-BM5GS6ZH.js} +2 -2
  30. package/dist/{chunk-TLX72JTG.js → chunk-BWYQUPOS.js} +1 -1
  31. package/dist/chunk-CFRQMBGP.js +49 -0
  32. package/dist/{chunk-RMLC67LF.js → chunk-CJYKEW2L.js} +2 -30
  33. package/dist/chunk-CKEQFGLT.js +32 -0
  34. package/dist/{chunk-IWDLU6K3.js → chunk-DC4CFXM5.js} +4 -6
  35. package/dist/{chunk-ZVUL7QYY.js → chunk-DMSLNKF7.js} +29 -32
  36. package/dist/{chunk-KN35K52N.js → chunk-DQXSPYRI.js} +3 -3
  37. package/dist/{chunk-HYGZEMX6.js → chunk-EVDGNG4F.js} +11 -5
  38. package/dist/{chunk-SRYEJNES.js → chunk-F5Z6URKM.js} +2 -2
  39. package/dist/{chunk-UMS2MFPZ.js → chunk-F6X3YJWD.js} +2 -3
  40. package/dist/{chunk-XYURS6EN.js → chunk-FA5LDARD.js} +15 -17
  41. package/dist/{chunk-24AKHFGP.js → chunk-FFL3A2VP.js} +6 -6
  42. package/dist/chunk-FJIVKLPH.js +31 -0
  43. package/dist/chunk-G2B7F6ZU.js +88 -0
  44. package/dist/{chunk-US7ECLD7.js → chunk-GAACZY6R.js} +131 -41
  45. package/dist/{chunk-MZGQNL3Y.js → chunk-GMTFDAOK.js} +12 -13
  46. package/dist/{chunk-VOOAPROD.js → chunk-GNSIWBAT.js} +3 -3
  47. package/dist/chunk-GTAI2J6U.js +27 -0
  48. package/dist/{chunk-RVK72CZX.js → chunk-GZE7WOI4.js} +1362 -459
  49. package/dist/{chunk-IUE7SSKV.js → chunk-H7HTEQUZ.js} +13 -7
  50. package/dist/{chunk-EUXZEFTV.js → chunk-HK6JVFZC.js} +3 -3
  51. package/dist/chunk-IPDG45G5.js +26 -0
  52. package/dist/{chunk-5HSRT26B.js → chunk-J6JP25XU.js} +16 -15
  53. package/dist/{chunk-HWCCCQNX.js → chunk-JL6CXUMW.js} +13 -6
  54. package/dist/{chunk-EBC36LNN.js → chunk-K2YGBXOA.js} +17 -17
  55. package/dist/{chunk-WMYE35PX.js → chunk-KLQVC3XC.js} +7 -5
  56. package/dist/{chunk-ATKJFDQN.js → chunk-KSR7RGQY.js} +12 -14
  57. package/dist/{chunk-POMLXPMY.js → chunk-KXF5R4UN.js} +1 -1
  58. package/dist/{chunk-LLJNQKQW.js → chunk-LEJOJDXL.js} +20 -13
  59. package/dist/{chunk-JUKMK5Y4.js → chunk-MA77RSFN.js} +10 -11
  60. package/dist/{chunk-GAQ7OQG6.js → chunk-MKVZQUEG.js} +85 -96
  61. package/dist/{chunk-2EECBNC5.js → chunk-MN7MHUXQ.js} +75 -0
  62. package/dist/{chunk-DEL2U6CM.js → chunk-MT6BVNFW.js} +16 -14
  63. package/dist/chunk-NDMCVUYK.js +507 -0
  64. package/dist/{chunk-HRNHZA3N.js → chunk-NIU2IPC5.js} +12 -16
  65. package/dist/{chunk-AGSS7277.js → chunk-NNKXDXXS.js} +7 -24
  66. package/dist/{chunk-V35JG4JB.js → chunk-OJLTLYHB.js} +152 -334
  67. package/dist/{chunk-J6MPGQTS.js → chunk-OLAWH5UQ.js} +81 -15
  68. package/dist/{chunk-T57LYLZT.js → chunk-OOU2WZZE.js} +1 -1
  69. package/dist/{chunk-CYRKQRPM.js → chunk-OSTKYB55.js} +2 -4
  70. package/dist/chunk-P4QNXS6I.js +27 -0
  71. package/dist/chunk-PKES3ISE.js +297 -0
  72. package/dist/{chunk-ROYSX2S5.js → chunk-PO45POGF.js} +2 -2
  73. package/dist/{chunk-T7FEBKXN.js → chunk-PPIBVH4R.js} +7 -9
  74. package/dist/{chunk-3RKP3FMS.js → chunk-PQJFG24Z.js} +295 -23
  75. package/dist/{chunk-KUA4OJ5Y.js → chunk-Q3UZHW6N.js} +846 -350
  76. package/dist/{chunk-N5FLEO7W.js → chunk-Q4EMRFNA.js} +37 -37
  77. package/dist/{chunk-5IUSNGOC.js → chunk-Q4FCYCRE.js} +28 -21
  78. package/dist/chunk-Q6D6VMI4.js +22 -0
  79. package/dist/{chunk-UZ2XCLYS.js → chunk-QGSTQH4D.js} +8 -8
  80. package/dist/{chunk-DUO2TU77.js → chunk-RZOXUSPC.js} +10 -4
  81. package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
  82. package/dist/{chunk-GMX5OS7B.js → chunk-S67UJDGQ.js} +11 -12
  83. package/dist/chunk-SCIUNBPF.js +44 -0
  84. package/dist/{chunk-RKBXZN3A.js → chunk-SJJYRZB4.js} +2 -2
  85. package/dist/chunk-SXGD4ANG.js +25 -0
  86. package/dist/{chunk-YCWYO6TQ.js → chunk-T7FTXGS3.js} +48 -45
  87. package/dist/{chunk-FM4RDMKT.js → chunk-TIQJPRDD.js} +115 -61
  88. package/dist/{chunk-XHJBS436.js → chunk-TIYGSODX.js} +25 -25
  89. package/dist/{chunk-S2HEXIWI.js → chunk-U2SDMG7C.js} +10 -6
  90. package/dist/{chunk-2KXTHF3M.js → chunk-U6OC3QEM.js} +253 -33
  91. package/dist/{chunk-AWSCPCN2.js → chunk-UCGQT677.js} +19 -19
  92. package/dist/chunk-UHGF5UT5.js +32 -0
  93. package/dist/{chunk-JW3YWBVB.js → chunk-UN4TEBWN.js} +17 -19
  94. package/dist/{chunk-ZHH37KZL.js → chunk-V3APN3DY.js} +17 -17
  95. package/dist/{chunk-ED36RF6Y.js → chunk-V63BC55Q.js} +1 -1
  96. package/dist/{chunk-XBJVAEEO.js → chunk-VG5JS5SW.js} +3 -2
  97. package/dist/{chunk-W66O5E25.js → chunk-VPBIMOAQ.js} +13 -15
  98. package/dist/chunk-VQH24FIP.js +37 -0
  99. package/dist/{chunk-YNE3RP52.js → chunk-VSFLRN5Y.js} +8 -1
  100. package/dist/{chunk-7D6L4MTX.js → chunk-W2V54OCL.js} +3 -3
  101. package/dist/{chunk-2FN63LPV.js → chunk-W5LGKNET.js} +13 -14
  102. package/dist/{chunk-IQWN5JCP.js → chunk-W5R5SABV.js} +13 -14
  103. package/dist/{chunk-R3T7CLQ2.js → chunk-WIZWZR4C.js} +41 -41
  104. package/dist/{chunk-TOY6QKOH.js → chunk-WQOIR3QY.js} +17 -17
  105. package/dist/{chunk-Y6GZHWSJ.js → chunk-XAIT2YGS.js} +6 -6
  106. package/dist/chunk-XCUHKYCQ.js +23 -0
  107. package/dist/{chunk-GSM5UU7A.js → chunk-XQCSWV2G.js} +44 -35
  108. package/dist/{chunk-OHKJ7PQF.js → chunk-YBSONGSZ.js} +43 -39
  109. package/dist/{chunk-GXFV6MYU.js → chunk-YISME6ON.js} +72 -39
  110. package/dist/chunk-YRD4ISED.js +30 -0
  111. package/dist/{chunk-SD4I7ZO4.js → chunk-YSBHPOY6.js} +43 -53
  112. package/dist/{chunk-QBFBRV2B.js → chunk-Z2XAOKHK.js} +4 -2
  113. package/dist/{chunk-5VSF4UUQ.js → chunk-Z7IGUAXL.js} +34 -39
  114. package/dist/{chunk-MPNJLASA.js → chunk-ZKXQKGWZ.js} +10 -13
  115. package/dist/{chunk-J64T55EI.js → chunk-ZQ6NZZTB.js} +75 -9
  116. package/dist/chunk-ZUUI3ZSA.js +38 -0
  117. package/dist/{chunk-7HXE67BN.js → chunk-ZYNI26MI.js} +2 -2
  118. package/dist/index.js +32674 -27567
  119. package/dist/mcp/analyze-cli.js +11 -12
  120. package/dist/mcp/cli.js +46 -45
  121. package/dist/mcp/server.js +1210 -574
  122. package/dist/mcp/worker.js +65 -65
  123. package/dist/probes/installer.js +21 -23
  124. package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
  125. package/docs/adr/README.md +1 -0
  126. package/docs/agent-tools.md +28 -7
  127. package/docs/ast-grep_rules_catalog.md +5 -3
  128. package/docs/configuration.md +12 -1
  129. package/docs/defect-shapes.md +738 -0
  130. package/docs/engineering-principles.md +12 -0
  131. package/docs/environment-variables.md +20 -0
  132. package/docs/features.md +16 -1
  133. package/docs/globalconfig.md +37 -8
  134. package/docs/invariants/caches-stores.md +30 -0
  135. package/docs/invariants/dispatch-runners.md +164 -0
  136. package/docs/invariants/git-guard-host.md +53 -0
  137. package/docs/invariants/language-config.md +31 -0
  138. package/docs/invariants/lsp-trust-exec.md +286 -0
  139. package/docs/invariants/paths-os.md +59 -0
  140. package/docs/invariants/session-telemetry.md +74 -0
  141. package/docs/lsp-capability-matrix.md +105 -12
  142. package/docs/lsp-idle-eviction.md +37 -18
  143. package/docs/pi-lens-fixer.md +24 -2
  144. package/docs/pi-lens-investigator.md +14 -0
  145. package/docs/pi-lens-merge-policy.md +32 -17
  146. package/docs/pi-lens-monitor.md +66 -10
  147. package/docs/pi-lens-orchestration.md +41 -0
  148. package/docs/pi-lens-release.md +20 -0
  149. package/docs/pi-lens-retro.md +5 -4
  150. package/docs/pi-lens-reviewer.md +54 -7
  151. package/docs/pi-lens-subagent.md +10 -3
  152. package/docs/release-qa-baseline.md +19 -7
  153. package/docs/servercapabilities.md +47 -47
  154. package/docs/settings.md +9 -5
  155. package/docs/subagent-compat.md +1 -1
  156. package/docs/usage.md +1 -0
  157. package/package.json +8 -5
  158. package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
  159. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
  160. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
  161. package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
  162. package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
  163. package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
  164. package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
  165. package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
  166. package/rules/rule-catalog.json +25 -1
  167. package/scripts/analyze-pi-lens-logs.mjs +15 -5
  168. package/scripts/lib/is-main-module.mjs +27 -0
  169. package/scripts/lib/scratch-home-env.mjs +21 -0
  170. package/scripts/rpc-load-check.mjs +4 -6
  171. package/scripts/warm-loader-cache.mjs +2 -5
  172. package/dist/chunk-3PTHXJXR.js +0 -28
  173. package/dist/chunk-3QED2P4V.js +0 -31
  174. package/dist/chunk-5WRPDP2A.js +0 -47
  175. package/dist/chunk-ABBOA7UD.js +0 -157
  176. package/dist/chunk-CUHSHSB6.js +0 -273
  177. package/dist/chunk-GL5LUMZE.js +0 -51
  178. package/dist/chunk-HAD7QRQI.js +0 -30
  179. package/dist/chunk-JORED7EX.js +0 -44
  180. package/dist/chunk-KYUB6QDC.js +0 -72
  181. package/dist/chunk-LZSEQW6A.js +0 -57
  182. package/dist/chunk-M2IFVFWU.js +0 -79
  183. package/dist/chunk-M2UD3LPU.js +0 -88
  184. package/dist/chunk-MBKQHGA7.js +0 -39
  185. package/dist/chunk-R7YOCSNV.js +0 -23
  186. package/dist/chunk-SKAMFC7A.js +0 -28
  187. package/dist/chunk-SYE6T2EB.js +0 -28
  188. package/dist/chunk-TRETHTQO.js +0 -26
  189. package/dist/chunk-UA7ZXYDR.js +0 -184
  190. package/dist/chunk-XTFDJI3T.js +0 -24
  191. package/dist/chunk-Z3CCVDUB.js +0 -76
@@ -0,0 +1,738 @@
1
+ ## Recurring defect shapes
2
+
3
+ Screen against these before writing code. Shapes are numbered once, grouped by
4
+ the surface they bite; each block loads only when its trigger applies. A shape
5
+ whose open population is countable names its census in its entry. The census
6
+ is one command, run at the repo root, printing one line per member or naming
7
+ one baseline key. A PR that fixes members of the shape quotes that census
8
+ before and after. A shape with no census in its entry is uncounted: a PR that
9
+ fixes its members says so instead of quoting a before and after.
10
+
11
+ <!-- markdownlint-disable MD029 -->
12
+
13
+ <important if="touching a path key or path spelling">
14
+
15
+ ### touching a path key or path spelling
16
+
17
+ 1. **Divergent path keys:** path-keyed maps use `PathKeyedMap` and normalize on
18
+ write, read, delete, and rehydrate. Tests use mixed separators and casing.
19
+ A normalizer change tables every writer and reader of the map with the
20
+ normalizer each uses; a claim that one normalizer subsumes another is
21
+ measured per transformation (separators, dot segments, case, symlinks,
22
+ existence), never asserted (#3178: four rounds, two inverted arms, one
23
+ unmeasured swap). Never put `path.resolve` in front of an identity key:
24
+ it folds `..` lexically before the link resolves, so `/repo/link/../f.ts`
25
+ keys a different file than the kernel does (three instances on
26
+ 2026-10-25, listed in `HISTORY.md`). Screen: does
27
+ any spelling reach `normalizeMapKey` or `realpathOrResolve` through a
28
+ `path.resolve` first? Enforced by `tests/config/path-identity-sweep.test.ts`
29
+ (partial: a raw realpath or a raw `path.resolve` key outside
30
+ `clients/path-utils.ts`).
31
+
32
+ 2. **Host path functions in a shape branch:** once a path is classified as
33
+ Windows-shaped, use `path.win32`; do not use host-default `path` functions.
34
+ Prefer `toPosix`, `splitPathSegments`, and the path identity helpers.
35
+
36
+ 32. **Mixed path comparison:** use one platform-aware containment expression;
37
+ do not combine case-sensitive equality with case-folded relative paths. A
38
+ tool-reported path is attributed with `pathsEqual` against the tool's cwd,
39
+ capturing only the path the tool's renderer emits. Enforced by
40
+ `tests/config/reported-path-attribution-sweep.test.ts` (shrink-only census).
41
+ ADR: docs/adr/0009-reported-path-attribution.md
42
+
43
+ 39. **Walk-up result used as eligibility:** return ownership and start-directory
44
+ identity separately; enumerate root-position by ambient-input cells.
45
+
46
+ 74. **Split host-path resolution:** a path is resolved by its provenance, at one
47
+ seam per provenance. A path a host tool was given as an argument goes
48
+ through `resolveHostToolPath` / `resolveToolCallFilePath`, never a bare
49
+ `path.resolve(base, raw)`, which turns `~` into `<base>/~/…`, a path that
50
+ cannot exist, and dispatch then reports ghost findings for it. A shell
51
+ operand follows shell rules (a quoted tilde stays literal; no `@` strip or
52
+ unicode fold), bound to the token it came from. A path recovered from disk
53
+ or generated by pi-lens is an identity and is never re-resolved.
54
+
55
+ 64. **Named path vs written set:** a guard keyed on the path a tool NAMES must
56
+ hold for every path the tool WRITES; enumerate the written set (a rename's
57
+ importers, an `ast_grep_replace` folder or its project default, a
58
+ server-initiated `workspace/applyEdit` with no call at all) and key the
59
+ permission per call, never per path. Three rounds on the read guard's
60
+ authorship seam (#4187 R2-3, R4-1, R5): the pre-write retire covered the
61
+ named path while the post-write advance covered every recorded one, so a
62
+ file nothing checked was re-baselined over another writer's bytes. The
63
+ screen: for each writer, table named-at-call against actually-written, and
64
+ ask which rule answers for a path in the second column only.
65
+ A first credit from a bridge is range-scoped to the bytes it reports, and
66
+ settled-sweep drift never creates authorship (#4210); screen the next
67
+ positional edit both inside and outside the reported range. This is the
68
+ bridge/LSP/native-edit rule only: recognized bash (#4131 R2), pipeline
69
+ sibling files, and agent_end are pinned whole-file exceptions.
70
+
71
+ 65. **Unknown authorship range:** a producer that cannot recover a truthful
72
+ range must carry UNKNOWN to `ReadGuard.creditAuthorship`; UNKNOWN
73
+ creates no authorship. A scope after a credit is what the credit holds
74
+ plus what it may keep, so no credit widens an empty or range scope past
75
+ the lines it produced: not a drain, a bash write or a pipeline credit.
76
+ A native write's creation read vouches for the whole file instead.
77
+ UNKNOWN keeps a scope only under the writer rule
78
+ (`mayAdvanceAuthorship`) and while a read that names a tool call bounds
79
+ it after a move; otherwise it leaves an empty scope, which vouches for
80
+ no line. An own oldText edit must not retire its write's authorship. A
81
+ producer with no pre-write check says so with `advanceAuthorship:
82
+ false`, never by leaning on UNKNOWN. Enforced at
83
+ `clients/mutation-bridge.ts` and `clients/read-guard.ts`, with the
84
+ F-4210-2 production bridge witness.
85
+
86
+ </important>
87
+
88
+ <important if="adding or reading a cache, durable record, or project-intelligence state">
89
+
90
+ ### adding or reading a cache / durable record
91
+
92
+ 4. **Unsettled resource:** every timer, worker, child, watcher, and loser path
93
+ is unref'd or cleared on every settle path. Tracked entries are removed on
94
+ failure as well as success. Teardown does not await a dead resource forever.
95
+ Enforced by `tests/config/hook-await-bounds.test.ts` (partial: hook awaits
96
+ and timeout races only; timer handles have no detector).
97
+
98
+ 6. **Incomplete freshness:** use the right content, size, mtime, dependency,
99
+ and existence axes. Missing finding paths are not current findings.
100
+ Enforced by `tests/clients/freshness-sweep.test.ts` (partial: mtime
101
+ comparisons must go through the kernel comparator; an mtime cache-key
102
+ equality without a size or hash sibling is not scanned).
103
+
104
+ 9. **One-axis bound:** bound the resource axis that grows, including bytes,
105
+ timers, WASM objects, and retained evidence.
106
+ Enforced by `tests/config/bounded-container-guard.test.ts`,
107
+ `tests/config/bounded-eviction-idiom-sweep.test.ts` and
108
+ `tests/clients/bounded-telemetry-sweep.test.ts` (partial: container count
109
+ and telemetry only; bytes, WASM objects and timers have no detector).
110
+
111
+ 12. **Out-of-guard mirror refresh:** refresh behavior-gating mirrors before the
112
+ guard releases, or validate the committed generation/object identity.
113
+
114
+ 15. **Timer versus long operation:** an operation holds a counted gate for its
115
+ lifetime; a background timer checks it at fire time and re-arms a fresh,
116
+ bounded delay.
117
+
118
+ 18. **Cooldown beyond caller cadence:** verify both recovery suppression and
119
+ promotion of values served during cooldown.
120
+
121
+ 24. **Second writer without discriminator:** enumerate all writers and add a
122
+ reason/kind field before composing branches.
123
+
124
+ 28. **Cold-path work on warm path:** compute expensive record fields only inside
125
+ the failure or timeout branch, and measure any hot-path cost.
126
+
127
+ 29. **Reset cap counter:** a retire or skip records its decision where the
128
+ selector reads it, so the same item cannot re-enter with a fresh count.
129
+
130
+ 41. **Hot bound reached at p50:** record hit rate and prefer adaptive or
131
+ demotion behavior over a constant that has become the work.
132
+
133
+ 46. **Long-lived container without a bound:** module-level `Map`/`Set` state
134
+ is bounded, evicted, or content-keyed; a reset or TTL read is not a bound.
135
+ Enforced by `tests/config/bounded-container-guard.test.ts` (shrink-only).
136
+
137
+ 47. **Retry or drain loop consumes its own work list:** a bounded retry or
138
+ drain loop must not remove its tracked item from the collection it iterates
139
+ on the first successful pass. Later attempts must observe the resource's
140
+ actual absence before untracking it; tests cover a resource recreated
141
+ between attempts.
142
+
143
+ 51. **Cross-request derived-state cache where a request-local pass is
144
+ affordable:** for a derived value on a hot path, measure a request-local
145
+ bounded recompute first; persist it only when the fresh-process benchmark
146
+ shows the recompute is the cost, and then the entry carries the generation
147
+ it was derived from. Tool-run caches are governed by the delivery gate
148
+ instead. ADR: docs/adr/0006-derived-state-benchmark-first.md
149
+
150
+ </important>
151
+
152
+ <important if="a delivery surface or lane">
153
+
154
+ ### a delivery surface or lane
155
+
156
+ Project-wide scanner delivery has one owner per live worklist. The primary
157
+ session owns turn-end delivery; a concurrent secondary owns only its own
158
+ file-scoped worklist and receives no project-wide scanner output.
159
+
160
+ | Producer population | Primary turn_end | Secondary turn_end |
161
+ |---|---|---|
162
+ | Project-wide scanners (gitleaks, knip, jscpd, and equivalent shared stores) | admit and deliver | suppress at the delivery gate |
163
+ | Session-owned file or runner findings | admit its own session | admit its own session |
164
+
165
+ 5. **Dropped side channel:** trace flags, bindings, and provenance through
166
+ spreads, maps, filters, and JSON serialization.
167
+
168
+ 10. **Silencing as fixing:** distinguish clean, filtered, unavailable, errored,
169
+ suppressed, deferred, and partial results. Any bound on an agent-facing
170
+ path discloses its truncation on the rendered surface; a count recorded
171
+ only in `latency.log` is not disclosure (#3166 r2: an 80-finding input
172
+ bound zeroed a neighbour's genuine errors, counted only in the log).
173
+ An out-of-session-root project edit records one bounded degradation and
174
+ uses the existing advisory notice seam; intended vendor skips and pi-owned
175
+ OS-temp artifacts stay silent (`clients/runtime-tool-result.ts`,
176
+ `clients/ephemeral-root.ts`).
177
+ A delta decides only what is new: a blocker stays pending, recorded and
178
+ gating, until an observation no longer holds it. An edit-range gate
179
+ decides only delivery, and a run with no verdict (failed, unanswered, in
180
+ flight) observes nothing, so neither retires a recorded blocker. A skip
181
+ has a verdict only with a stated not-applicable reason
182
+ (`RUNNER_SKIP_REASONS`). A recorded blocker is still observed only at its
183
+ own line, aligned to the current bytes: another occurrence of the same
184
+ rule is not it. A fallback for missing evidence narrows what retires:
185
+ with no alignment, its identity anywhere keeps it. It stays a per-write
186
+ hold and never widens what counts as the same finding: the match still
187
+ needs the entry's own line text, and owed lines are matched by content,
188
+ never widened to the file. A skip that defers to another source's
189
+ evidence answers only for what that evidence sees, and only when that
190
+ source answered: an edit-gated primary sees the edit, so a recorded
191
+ finding outside it stays, and a silent primary sees nothing. A recorded
192
+ finding is judged only by a run of its own runner: one that would defer
193
+ to a source whose copy has another identity runs while it holds a
194
+ recorded finding there, or nothing could retire one it cannot place. A
195
+ kept entry with no place in a write's bytes is recorded as such
196
+ (`positionStale`), never inferred later from one line's hash, and a line
197
+ with no word character owes nothing by its text.
198
+ Enforced by `tests/clients/dispatch/runners/run-outcome-ratchet.test.ts`,
199
+ `tests/clients/dispatch/runners/parsed-nothing-sweep.test.ts` and
200
+ `tests/clients/delivery-surface-ratchet.test.ts` (partial: no detector
201
+ for an agent-facing bound that omits its truncation line).
202
+
203
+ 26. **Old-role filter on a substitute:** compare fallback output with the
204
+ substituted surface's contract, including non-blocking findings.
205
+
206
+ 27. **Unredacted user content:** parser messages and hand-authored strings may
207
+ contain file input; normalize and redact at the shared diagnostic seam.
208
+
209
+ 31. **Pull-only observability:** new behavior emits a success or decision record
210
+ in the streams that monitors and analyzers read. A new decision branch on a
211
+ session, lifecycle or delivery seam names its record, cites an existing one,
212
+ or says `none: <reason>` naming each file (`check-pr-body` prompts for it);
213
+ a test reads a record back, and a reason is judged by the reviewer
214
+ (#3875; recurrence #3873: the S2/S3 fixes could not be shown to fire live).
215
+ A new or changed `catch` handler in `clients/`, `mcp/`, `tools/` or
216
+ `index.ts` is judged by `tests/config/silent-catch-sweep.test.ts`: a record
217
+ seam on every path, an unconditional `throw`, or a `none: <reason>` marker,
218
+ and the file's pinned set re-pinned in the same change (`PI_LENS_PRINT_PINS=1`
219
+ prints the rows). `scripts/` and `tests/` stay outside its scope.
220
+
221
+ 75. **Swallowed failure recorded as a different event:** a `catch` that drops a
222
+ failure and lets the normal path continue makes the log report success or
223
+ an event that never happened (an unreadable subtree counted as deleted, a
224
+ rejected save counted as sent). A catch on a runtime path records the
225
+ failure under its own kind, or says `none: <reason>`. Screen: force the
226
+ failure through the real entry point and read the record it wrote.
227
+
228
+ 43. **Prose mistaken for executable structure:** define lexical states and
229
+ reachability before scanning shell, workflow, or source text.
230
+
231
+ 61. **Stand-in for unknown text stripped per consumer:** when a lexer leaves a
232
+ placeholder for text it cannot know (a command substitution's output),
233
+ read the input under each bounding assumption rather than teaching each
234
+ consumer to ignore the placeholder: empty (the text the rules matched
235
+ before it existed) and opaque (no rule word matches it, no path resolves
236
+ through it), denying if either reading denies. Enforced by `findDeny` in
237
+ `scripts/hooks/guard-bash.mjs`, pinned by the "substitution next to a rule
238
+ word (#3997)" rows in `tests/scripts/guard-bash-hook.test.ts`. Recurrence:
239
+ #3997 round 3 stripped the mark at three call sites and left
240
+ `checkUngated`, `mktemp` flags, and `git $(:) stash` open.
241
+
242
+ 49. **Whitespace counted as structure when it is alignment:** a leading run can
243
+ be alignment, not one nesting unit (call continuations, block-comment and
244
+ template-literal interiors; #3038, #3039, #3052, #3059, #3116). Name which
245
+ lines carry structure and exclude the rest before counting; decline rather
246
+ than pin a style when only ambiguous runs remain.
247
+
248
+ 54. **One-direction filter proof:** a filter that drops stale input is proven
249
+ in both directions: it never passes stale input and never drops the only
250
+ fresh answer. The model carries a no-drop invariant beside the safety one,
251
+ and the test double emits in the real server's measured order, not the
252
+ order the fix assumes (#3484 r1: the fence dropped docker-langserver's only
253
+ publish; the model checked `FreshResult` alone and the fake published after
254
+ the fence reply).
255
+
256
+ 79. **Prefix churn from a non-append write:** a provider caches the request in
257
+ order (tools, then system, then messages), so a write that changes bytes
258
+ before the newest message re-bills the whole conversation: a returned
259
+ `context` list that makes pi rebuild the system head, or a tool-set change
260
+ on a model that folds system messages into the head. Write at the tail
261
+ only, and count each tool-set change as one full rewrite on such models. A
262
+ host-generation gate takes a recorded fixture per certified minor, never
263
+ two. Screen: drive two real-session requests that differ only in the
264
+ writer, and compare the head and pi-ai's collapsed head. Enforced by
265
+ `tests/clients/prompt-cache-prefix-writers.test.ts` (one tier-2 cell per
266
+ writer: registration, session-start plan, activation, injection).
267
+
268
+ 84. **Tool-state prose blind to a posture:** model-facing text (orientation,
269
+ tool descriptions, nudges) that names a tool as active, inactive, available
270
+ or needing activation must hold under every posture the renderer cannot see:
271
+ each `tools.<name>.enabled` value, each `tools.lazy` value (true, false,
272
+ auto) and each host (pi, MCP, which can call only the tools it has a name
273
+ for). Derive the named set from the registry, never a hand list. Screen:
274
+ render the prose under each posture combination and each host, and assert
275
+ every clause is true (#4293, #4294 enabled axis; #4682 lazy axis and the
276
+ hand list that dropped two tools).
277
+
278
+ </important>
279
+
280
+ <important if="a runner outcome or tool execution">
281
+
282
+ ### a runner or tool outcome
283
+
284
+ 3. **Wrong argv transform:** verify a command is the wrapper shape before
285
+ dropping an argv element or launcher name.
286
+
287
+ 13. **Wrong failure classification:** derive availability and verdicts from raw
288
+ evidence; preserve the classifier and evidence when a caller asserts a fact.
289
+ Runner log parsers tolerate ANSI control sequences, padding, and CRLF before
290
+ extracting a count; the exact Windows bytes are pinned by
291
+ `tests/config/windows-vitest-failure-count.test.ts`, and the parser is
292
+ `parseVitestSummary` (shape 63).
293
+ Enforced by `tests/clients/dispatch/runners/run-outcome-ratchet.test.ts`
294
+ and `tests/clients/dispatch/runners/parsed-nothing-sweep.test.ts`
295
+ (partial: the classification choice itself is review-enforced; a
296
+ latch-literal rule fires on every correct write).
297
+
298
+ 16. **Unverified external-tool claim:** probe the real binary before encoding
299
+ exit codes, output shapes, severity names, or fixtures. For a third-party
300
+ extension, server, or file format, read its source or schema at a pinned
301
+ SHA and pin a test vector generated from it, citing the SHA; a double
302
+ built from an issue's description encodes the same guess (#2432).
303
+ Enforced by `tests/clients/dispatch/smoke-fixture-coverage.test.ts`
304
+ (partial: every registered dispatch runner needs captured real-binary bytes
305
+ replayed by `tests/clients/dispatch/runners/captured-real-output.test.ts`,
306
+ or an exemption naming a fact about the tool; presence only, not fidelity).
307
+
308
+ 40. **Tool root drift:** all runner, formatter, and LSP child spawns use
309
+ `resolveToolCwd`; mutation of the seam, log, or fallback must turn a test red.
310
+ Enforced by `tests/support/spawn-cwd-scan.ts` and its runner sweep.
311
+
312
+ 42. **Language-specific rule:** use `LANGUAGES` and registry facts; add a
313
+ non-TypeScript row whenever the rule is language-neutral.
314
+
315
+ 48. **Fallback direction chosen without naming the user-facing obstruction:**
316
+ "fail closed" is not a universal justification. For each fallback, catch,
317
+ or default, name the concrete failure that reaches the user and choose the
318
+ direction from that harm; test unreadable, absent, and thrown lookup states
319
+ where the seam supports both directions.
320
+
321
+ 53. **Unhandled stream or process event is a host-fatal throw:** every callback
322
+ on a child process, socket, or stream is total (catch, bound, record); a
323
+ throw there bypasses the caller's `try/catch` and kills the pi host (#3375,
324
+ #3383, #3389). `data` handlers are enforced by
325
+ `tests/clients/data-handler-bounds-sweep.test.ts` and socket `error`
326
+ listeners by `tests/clients/socket-error-listener-sweep.test.ts`, and
327
+ worker or IPC `message` listeners (typed `unknown`, one non-rethrowing
328
+ try) by `tests/clients/worker-message-boundary-ratchet.test.ts`; screen
329
+ `close` and timer callbacks by hand.
330
+
331
+ 60. **Wasm failure outside the #3605 containment:** every failure thrown out
332
+ of web-tree-sitter classifies through `classifyTreeSitterWasmError`, and a
333
+ `catch` inside a `withParsedTree` consumer calls `reportWasmAbort` before it
334
+ swallows the error. An unclassified or swallowed trap is never counted,
335
+ charged or recycled, and the runtime later fails elsewhere (#3996: the
336
+ bash wasm's unresolved `isalpha` import threw an unclassified `TypeError`
337
+ on every `[ a == b ]`, and a callback-traversal trap surfaced raw).
338
+ `tests/clients/grammar-runtime-imports.test.ts` reds on a shipped grammar
339
+ that imports a function the runtime does not export.
340
+
341
+ 62. **Delete or rewrite through a dependency link:** a lane's `node_modules` is
342
+ a symlink to the main checkout's install, so any verb that removes or
343
+ rewrites under it reaches every lane (#3173: `git worktree remove` followed
344
+ the link twice; #4044: a worker's `npm ci --dry-run` emptied it under ~7
345
+ lanes, because npm 9.2.0 ignores `--dry-run` for the clean-install family).
346
+ Such a verb runs only where `node_modules` is a real directory, or in a
347
+ scratch copy. The hook's verb list (`NPM_NODE_MODULES_WRITERS` in
348
+ `scripts/hooks/guard-bash.mjs`) is the catalog: a new verb alias or
349
+ package manager (pnpm, yarn, bun) needs its own entry, and the hook binds
350
+ Claude lanes only, so a codex worker's half is the plegma shim
351
+ (apmantza/plegma#693). Sweep 2026-10-07, clean in the repo's own scripts
352
+ (`grep -rnE "rmSync\(.*node_modules|rm -rf .*node_modules|npm ci"
353
+ scripts clients tools`): no script runs a writer in a lane tree.
354
+ Deletes are the second member, measured with GNU coreutils on 2026-10-07:
355
+ `rm -rf node_modules/`, `rm -rf node_modules/*`, `find node_modules/
356
+ -delete`, `find -L|-H node_modules -delete`, `find node_modules/ -exec rm`
357
+ and `cd node_modules && rm -rf ./*` empty the link target, while `rm -rf
358
+ node_modules` (no slash) removes only the link. `classifyNodeModulesDelete`
359
+ denies the first set through the same `hasNodeModulesSymlinkOutside` seam;
360
+ that seam follows the complete symlink chain with a fail-closed fallback
361
+ when the target cannot be resolved (#4080).
362
+ a lane unlinks without a slash or glob. Consolidation verdict: two rules on
363
+ one classifier seam, kept apart because the npm rule judges a verb and the
364
+ delete rule a path operand (deleting the delete rule relocates nothing the
365
+ npm rule could absorb). Both share one path test,
366
+ `operandThroughNodeModulesLink` (npm's is `<prefix>/node_modules/`, or its
367
+ cwd plus the project its walk-up finds), and one rule for every value form
368
+ (#4054 round 4, after round 3 regressed `--prefix "$(pwd)"`): a directory
369
+ is tested where the program lands (the holder of each `node_modules`
370
+ component physically, as the kernel follows a link before `..`; npm's
371
+ `--prefix` lexically; npm's walk-up from the physical cwd), and a part
372
+ the resolver cannot read (an unknown cwd, `$( … )`, backticks, an unknown
373
+ variable) is the project the command runs in, failing closed in a linked
374
+ lane only. `find -L|-follow` also counts an operand that holds the link.
375
+ Unguarded, listed in the header's not-handled list: a glob that expands to
376
+ the link (`rm -rf */`), `xargs rm`, `rsync --delete`, `mv`, `npx rimraf`.
377
+
378
+ 63. **Tool console output parsed unstripped:** parsing Vitest or any tool's
379
+ console output: strip ANSI first, and test with `FORCE_COLOR=1`. CI runs
380
+ Vitest with colour, and escape codes split `Tests` from its counts and
381
+ `FAIL` from its file, so a parser reads "no tests", "no red" or the wrong
382
+ class (#4074, #4075, #4079, #4087: the pre-push hook recorded `failed: 0`
383
+ for a red run). Read a Vitest transcript only through `parseVitestSummary`
384
+ in `scripts/lib/vitest-summary.mjs` (pure, so importing it does not make a
385
+ script a workflow writer); its consumers are guarded over a real coloured
386
+ run by `tests/scripts/vitest-summary-consumers.test.ts`.
387
+ Consolidation verdict: folded onto that seam (deleting it would send seven
388
+ scripts back to private regexes). Sweep 2026-10-07 over `scripts/`,
389
+ `scripts/lib/`, `tests/support/` and `.github/`
390
+ (`grep -rnE "Tests\s|Test Files|stripVTControl|u001b|x1b"`): the other
391
+ hits are the classifier's own already-normalized patterns, `ci-verdict`'s
392
+ line classifier (strips before it matches), `check-pr-body`'s lint of pasted
393
+ body text, and readers of Vitest's JSON report.
394
+ 80. **Single scan root:** a detector takes its population from one root while
395
+ its subject can write in several, so a clean answer from the wrong root
396
+ reads as a complete negative. Screen: for each detector, list the roots its
397
+ subject can write in. Then show that each root gets its own verdict, or that
398
+ one root provably covers them. Census: not countable yet. Instance and
399
+ dates: `HISTORY.md`.
400
+
401
+ 83. **Rule re-derived beside its owner:** a consumer rebuilds a rule that a
402
+ shared seam already owns (a marker list, a glob-to-RegExp matcher, a case
403
+ fold) instead of calling the owner, so the copy drifts from it on
404
+ spelling, anchoring, case and file-versus-directory. The copy is always
405
+ plausible beside the owner, and a fix of one consumer leaves its siblings.
406
+ Screen: before writing a marker, pattern, bound or normaliser, grep the
407
+ tree for its literal and for the matcher that applies it; does a module
408
+ already own it, and does this caller route through that module? Then list
409
+ the other callers that hold their own copy and fold them or say why not.
410
+ Census: not countable yet. Enforcer: none: judgment-only. A scan cannot
411
+ tell a copied rule from a coincidental literal without reading what the
412
+ value feeds. Instances and dates: `HISTORY.md`.
413
+
414
+ </important>
415
+
416
+ <important if="a test double, ratchet or sweep">
417
+
418
+ ### a test double, ratchet or sweep
419
+
420
+ 7. **Vacuous test:** prove the real entry point and real fixture arm. A skip is
421
+ visible, a mock has the required fields, and the test fails pre-fix. A hook
422
+ handler that swallows its own throw (`handleToolCall` returns `undefined`
423
+ and records `tool-call-handler-throw`) reads a crash as the verdict under
424
+ test: call it through `runHandlerExpectingNoThrow`
425
+ (`tests/support/handler-verdict.ts`; the pi mock does it for `tool_call`
426
+ hooks), enforced by `tests/config/handler-verdict-sweep.test.ts` (#4182).
427
+ Enforced by `tests/config/vacuous-skip-coverage.test.ts` (partial: skips
428
+ and conditional tests; "fails pre-fix" is the PR body's red transcript,
429
+ not scannable).
430
+
431
+ 8. **Name heuristic:** a filename skip has an observable count and a content
432
+ escape hatch; never silently drop a real file.
433
+
434
+ 11. **Skipped CI as green:** absent required checks are not passing checks.
435
+
436
+ 14. **Duplicate module instance:** tests import the same `.js` artifact as the
437
+ runtime and never reset a private `.ts` twin. Enforced by
438
+ `tests/config/module-instance-coverage.test.ts`.
439
+
440
+ 33. **Source assertion for runtime behavior:** prefer a runtime probe; source
441
+ scans need proof that runtime observation is impossible.
442
+
443
+ 34. **Spelling enumerator:** detect semantic structure, not a finite list of
444
+ syntactic spellings, and test an unlisted spelling.
445
+
446
+ 35. **Platform-only red:** platform-dependent tests run under injectable
447
+ `path.posix` and `path.win32` semantics on every authoritative lane.
448
+
449
+ 36. **Count-based baseline laundering:** maintenance tools match content
450
+ identity, not occurrence counts, and refuse replacement identities.
451
+
452
+ 37. **Raw control byte:** source fixtures encode control characters as escapes or
453
+ buffers; tracked-source sweeps enforce this.
454
+
455
+ 38. **Data-only admission:** a new exemption or baseline row requires a reason
456
+ in a separate checked file and a fixture that crosses the boundary.
457
+
458
+ 44. **Portable entry-module check:** compare `import.meta.url` with
459
+ `pathToFileURL(process.argv[1]).href`.
460
+
461
+ 45. **Root wrapper drops metadata:** wrappers preserve the complete marker table
462
+ and are checked against direct root resolution.
463
+
464
+ 50. **Test double's fabricated identifier reaching code that acts on it:** a
465
+ pid, fd, port, lock path or handle invented by a mock reaches production
466
+ code that registers, signals, writes or deletes by it (#2042, #3091).
467
+ Verify ownership against the OS when the identifier is admitted, not its
468
+ range. Pids are enforced by `tests/support/kill-guard.ts`; screen the
469
+ other identifier kinds by hand.
470
+
471
+ 59. **Generated edit with unlisted consumers:** a bot edit to a value that tests
472
+ pin must leave green every test that names the edited ids. Screen: apply
473
+ the generator's real output to the real tree (all-eligible case included),
474
+ build, and run every test that mentions the field or the registry; this
475
+ sweep is manual (#3994 F1, r3). Tests take "an unmeasured server" from a
476
+ class the generator never touches, never a hard-coded id.
477
+ A removed or demoted CI job is the same shape: before deleting it, list
478
+ every consumer of its check name, comment marker and ci-verdict line (job
479
+ and gate pins, advisory and deferred allowlists, contracts, PR template) and
480
+ give each a disposition in the PR body (#4005).
481
+
482
+ 66. **In-process module double with a real seam:** when a `clients/` module has
483
+ a test setter, adopter, or reset, drive that seam; keep a double only at a
484
+ process or host boundary. New in-process `vi.mock` targets and hand-rolled
485
+ LSP client or service doubles are ratcheted by
486
+ `tests/clients/flake-shape-ratchet.test.ts` (`in-process-mock`,
487
+ `service-double`). Its census is the `in-process-mock` key of
488
+ `tests/support/flake-shape-baseline.json`: one line per `<file>::<module>`
489
+ row, 1009 of them on master 33eac2aa1. #4709 drives that count down.
490
+
491
+ 67. **Sink read before drain:** a log sink's `log`/`append` only enqueue, so a
492
+ test that reads the sink's byte offset, line count, or rows while one of
493
+ its own writes is queued counts late bytes on the wrong side of its window,
494
+ or misses them. Await that sink's flush (or `flushAllNdjsonWriters`) right
495
+ before the read with no other await in between, or inside the reading
496
+ helper. Enforced by `tests/config/sink-read-drain-sweep.test.ts`.
497
+
498
+ 68. **Model switch drift:** a TLA+ config constant that mirrors a code choice
499
+ (inject a read, retire on an unknown range) goes stale when the code
500
+ changes and the constant does not, and TLC then proves the old design
501
+ green. A PR that changes such a behaviour flips the constant in the same
502
+ change; a `TLA+ unaffected` line never covers it. Screen: for a mapped
503
+ file's diff, list the CONSTANTS in the family's as-built
504
+ `formal/<family>/*.cfg` and check each against the changed branch.
505
+ Enforced by `tests/config/tla-switch-pins.test.ts` over
506
+ `formal/switch-pins.json`: every constant a config assigns is
507
+ pinned, `notCodeChoice` or `deferred` with a reason; a pin names the test
508
+ that drives the real code, and every `expect: pass` config must resolve
509
+ the constant to the pinned value. Flipping the code reds the pin's test;
510
+ flipping the model without the registry reds the gate. read-guard is
511
+ fully pinned; the other families' code choices are deferred, and the
512
+ deferred and notCodeChoice counts are pinned exactly.
513
+
514
+ 69. **Enumerated detector:** a scanner that lists the spellings it knows
515
+ passes every spelling it does not, so the guard is green while the
516
+ defect ships. Derive the rule from the seam (the specifier, the store,
517
+ the sink) and fail closed on an unrecognised form. Screen: plant an
518
+ alias, an indirect call and a value reached through another binding,
519
+ and quote each result; every green plant is fixed or named as a residual.
520
+ On 2026-10-18 five detector PRs took two to six rounds each because
521
+ every verify found one more spelling. A detector's first round therefore lists its admitted forms
522
+ and refuses everything else; a residual names an admitted form that is
523
+ too broad, never a spelling the detector does not read.
524
+
525
+ 73. **Fixture adopts an ancestor root:** a fixture created with no project
526
+ marker inherits whatever root sits above it, so one stray `.git` at the tmp
527
+ root became the project root and #4559's quick-mode cell failed three
528
+ pre-push runs. Plant the fixture's own marker, or assert the root it
529
+ resolved before the case runs. Guard: planned in #4560, not yet running.
530
+
531
+ 76. **Instrument attributes by id and order, not by the emitting subject:** a
532
+ probe that brackets each phase with an offset into a buffered async sink,
533
+ and drains rows by subject id alone, folds a sibling's late row into its own
534
+ phase. The verdict then depends on write order, so the same measurement
535
+ flips between two answers and a data refresh commits the artifact as a
536
+ finding. Stamp each row with the subject that emitted it, or scope the drain
537
+ to that subject, and require the last writer of a verdict to be the subject's
538
+ own emitter. Enforced by `tests/clients/lsp/lsp-publish-trace-attribution.test.ts`.
539
+ Instance and dates: `HISTORY.md`.
540
+
541
+ 77. **Cancellation read as failure:** an aggregate that compares each shard's
542
+ result against `success` reds a required check when the shard finished every
543
+ step and lost its race with `timeout-minutes`, and no rerun recovers it,
544
+ because the infra-kill classifier reads only `failure` runs. A shard's own
545
+ step conclusions tell a teardown cancellation from a mid-check one, and every
546
+ required job's measured runtime belongs beside its cap, because a cap set at
547
+ the measured maximum fails the first time a runner is slow. That runtime is
548
+ also a per-shard SUM, so it can never be the stale-cost verdict: only the
549
+ table's rank agreement with the run's own ordering is scale-free enough to
550
+ survive one shard's machine. Guard: `tests/scripts/check-shard-verdict.test.ts`
551
+ (the seam, both fail-closed directions), the gating-step list in
552
+ `tests/config/unit-tests-shard-workflow.test.ts`, and
553
+ `tests/scripts/ci-verdict-runtime-cap.test.ts` (a measured runtime beside its
554
+ cap). Instance and dates: `HISTORY.md`.
555
+
556
+ 78. **A dependency's cache directory attributed to the fixture that triggered
557
+ it:** a loader that materialises `os.tmpdir()/<tool>` on the caller's own
558
+ stack looks like a fixture sibling, so the creator recorded for it is
559
+ accurate per process and wrong per cause, and the sweep reds a file that
560
+ never created it. Pin the loader's cache off for the test process rather
561
+ than admitting the directory's name, and keep a planted sibling red to prove
562
+ it. Enforced by the by-path-cache case in
563
+ `tests/config/tmp-fixture-hygiene.test.ts`, plus the `JITI_FS_CACHE=0` pin
564
+ that `tests/support/vitest-setup.ts` and `vitest.config.ts` force on the
565
+ test process. Instance and dates: `HISTORY.md`.
566
+
567
+ 81. **Synchronous native-tree walk holds every tree:** a sweep that parses many
568
+ files with `@ast-grep/napi` in a loop that never reaches a macrotask keeps
569
+ every native tree until the case ends, because the finalizer that frees a
570
+ tree runs only when the event loop turns (V8 heap stays near 40 MB while RSS
571
+ reaches 1.7 to 1.9 GB). An `await` on a settled promise does not turn it.
572
+ Turn the loop once per file with `setImmediate`. Screen: does the loop's
573
+ body parse, and does it reach a `setImmediate` or a real I/O await per
574
+ iteration? Enforcer: none: judgment-only. The per-file RSS budget and its
575
+ 200 MB headroom warning observe the symptom, but a source scan cannot tell
576
+ which loops parse without data-flow reading, so it could not fail closed.
577
+ Instances and dates: `HISTORY.md`.
578
+
579
+ 82. **One home variable pinned, the rest left at the real home:** a test or
580
+ probe environment that pins `PI_LENS_HOME` but leaves `HOME`,
581
+ `USERPROFILE` and the XDG directories alone lets every child that resolves
582
+ its own config from them write into the maintainer's home
583
+ (`~/.config/.opengrep`, `~/.config/.semgrep`), and a symlinked managed `bin`
584
+ lets an installer write through to the real `~/.pi-lens/bin`. The pin is
585
+ the whole set, assigned once in the worker so every child inherits it.
586
+ Screen: which directory does the process I run resolve from, and is every
587
+ variable that names it pinned? Enforcer:
588
+ `tests/clients/worker-home-pin-hermeticity.test.ts` (a real child reports
589
+ its HOME and XDG directories),
590
+ `tests/config/real-home-reader-registry.test.ts` (a file that reads the
591
+ real home through `REAL_HOME` or `userInfo` needs a row in
592
+ `tests/support/real-home-readers.ts`)
593
+ and `tests/clients/installer/managed-bin-symlink-escape-4789.test.ts`
594
+ (a pinned `PI_LENS_HOME` whose `bin` links out is refused). Instances and
595
+ dates: `HISTORY.md`.
596
+
597
+ 85. **Default-budget tree census:** a test whose callback walks the repo tree (a
598
+ whole-tree walker, a `git ls-files` spawn, a recursive directory walk, or a
599
+ suite-level population it reads) keeps vitest's 5 s default, and a walk that
600
+ costs 0.7 s on Linux costs several times that on the Windows unit leg and
601
+ times out there. The gate enforces that the third argument is an identifier
602
+ named `TREE_WALK_TIMEOUT_MS` (the shared constant, read by name, not by
603
+ binding) or a `scaledTestTimeout(...)` call (the reason goes in a comment the
604
+ gate does not read). A raw number or a file-local constant does not follow
605
+ the lane's timeout scale and is refused; a same-named local constant is
606
+ admitted and an import alias of the shared one is refused (no live member
607
+ either way). Screen: does this case call a walker or read a binding one
608
+ produced, and is its third argument one of those two forms? Census: 151 in
609
+ `tests/config`, all budgeted; 79 outside it still keep the default (a probe,
610
+ not a command). Enforcer: `tests/config/tree-census-timeout.test.ts` (it
611
+ derives the declaration callee from the file's vitest imports, resolves
612
+ walker aliases, and counts a test-shaped call it cannot trace as a census).
613
+ It does not read a walker reached through a helper in another module, a
614
+ variable-bound arrow-function walker, a local spawn wrapper, or a walk named
615
+ only by an enclosing `describe.each` or loop; `Unit tests Windows` is the
616
+ backstop. Instances and dates: `HISTORY.md`.
617
+
618
+ 86. **Turn-count wait for real I/O:** a test waits for a file write, a child
619
+ exit or a drain by awaiting a fixed number of event-loop turns, then
620
+ asserts. The count holds on an idle host and runs out on a loaded CI runner,
621
+ so the red lands on an unrelated PR. Wait on `waitFor`
622
+ (`tests/clients/interleaving-kit.ts`), which reads a real-clock deadline
623
+ scaled by `PI_LENS_TEST_TIMEOUT_SCALE`, and give the test a timeout above
624
+ that deadline. Screen: does the wait end on the event it waits for or on a
625
+ real-clock deadline, never on a count? Enforcer: none yet; the detector is
626
+ tracked in #4865. Instances and dates: `HISTORY.md`.
627
+
628
+ </important>
629
+
630
+ <important if="session, turn or generation lifecycle">
631
+
632
+ ### session, turn or generation lifecycle
633
+
634
+ 17. **Process latch for session state:** every once-latch has a session reset;
635
+ session dedupe belongs in the degradation ledger where possible.
636
+ Host `session_start` admission survives extension factory re-runs through
637
+ the process-lifetime `WeakSet<object>` in `clients/session-scope.ts`:
638
+ pi's RPC re-delivery reuses one event object, while each genuine start
639
+ allocates another, and weak identity needs no `session_shutdown` release.
640
+ Enforced by `tests/config/session-scope-sweep.test.ts` (partial: session
641
+ state outside the store; "every once-latch has a reset" is not scanned).
642
+
643
+ 19. **Re-derived identity:** carry resolved identity or correlation across
644
+ asynchronous stages; do not reconstruct it from ambiguous later inputs.
645
+
646
+ 20. **Staleness-only fallback:** stale work is not proof of ownership; require
647
+ origin provenance before claiming it.
648
+
649
+ 21. **Late loser overwrite:** concurrent writers carry a monotonic generation;
650
+ mutation of the generation guard must turn a test red.
651
+ Enforced by `tests/clients/generation-guard-sweep.test.ts` (partial: no
652
+ new hand-rolled guard; an unguarded concurrent writer is not scanned).
653
+
654
+ 22. **Session-straddling write:** capture the session generation before an
655
+ await and check it before publishing.
656
+ Enforced by `tests/config/session-scope-sweep.test.ts` and
657
+ `tests/clients/session-event-guard-sweep.test.ts` (partial: stale-context
658
+ wrappers only; a write after an await with no captured scope is not
659
+ scanned).
660
+
661
+ 23. **Advanced cursor predicate:** predicates about the starting leaf receive
662
+ the starting path, not the loop cursor.
663
+
664
+ 25. **Module-scope uniqueness assumption:** process evaluation can create
665
+ multiple copies; process-wide registries and latches use `getProcessSingleton`.
666
+ Enforced by `tests/config/module-instance-coverage.test.ts` (partial: the
667
+ test-side duplicate-instance half; module-level registries without
668
+ `getProcessSingleton` are not censused).
669
+
670
+ 30. **Load-time platform constant:** use a live platform read or an isolated
671
+ fresh import for every platform branch test.
672
+
673
+ 55. **Field inherited across entry kinds:** when a coalescing queue carries a
674
+ field from a replaced entry into its replacement (a read stamp, a save
675
+ flag), check every kind the replacement can be, not only the kind the fix
676
+ was written for (#3491: a queued close inherited a stale touch's read stamp
677
+ and the stale-read drop discarded the close). No model composes the two
678
+ fixes yet; that is #3495.
679
+
680
+ 56. **Subset without a population verdict:** when a mechanism, policy, guard,
681
+ or optimisation targets N of M members, name the excluded default and a
682
+ generalization verdict; see `docs/pi-lens-reviewer.md` (recurrence: #3622).
683
+
684
+ 57. **Released-writer input shapes:** property-test generators include the
685
+ input shapes produced by older released writers (#3594 R2-F1).
686
+
687
+ 58. **Known identity carried forward:** when a producer knows an identity,
688
+ carry it through asynchronous stages instead of re-deriving it downstream
689
+ (#3643 F3).
690
+
691
+ 70. **Joined single flight answers for edits after it started:** a caller
692
+ that joins an in-flight scan gets an answer computed before its own
693
+ edits. Withholding that answer and re-reading the baseline later loses
694
+ findings when another writer stores the row in between. Deliver the
695
+ joined answer and carry the edited files into the next scan. Screen:
696
+ for a join, list the writers that can store the row between the join and
697
+ the next scan, and show the finding survives each.
698
+
699
+ 71. **One signal wired consumer by consumer:** a detector or notifier added on
700
+ one consumer's seam, while other consumers derive state from the same
701
+ files. Each detector then picks its own subset, and two tools disagree
702
+ about one file. Screen: for a new detector, notifier or staleness marker,
703
+ list every consumer that holds state derived from the same content, and
704
+ show each one receives the change or record why not.
705
+
706
+ 72. **Process-global last-write-wins session field:** a field that holds one
707
+ session's value for the whole process answers for whichever session wrote
708
+ last, so a second live session overwrites what another one read. Key the
709
+ state by session identity, or decide from live membership. Instances:
710
+ #4554 (fixed by #4563, still open) and #4564. No guard yet: not scanned.
711
+
712
+ **Expired successor hand-off:** an expired successor marker may authorize
713
+ its named interrupted successor only for the fixed retention window in
714
+ `clients/session-lifecycle.ts`; the shared slot retires at that boundary
715
+ and records its dropped activation count before releasing the payload.
716
+ Its test-only pending-window override is accepted only in a Vitest process;
717
+ production keeps the fixed 60-second pending window.
718
+ The window and supersession paths are pinned by the session lifecycle and
719
+ session-scope tests.
720
+
721
+ </important>
722
+
723
+ <important if="availability policy or installer">
724
+
725
+ ### availability or installer
726
+
727
+ 52. **A second store answering the same availability question:** a new latch,
728
+ map or cache answering "can `<tool>` run, at what path" beside the shared
729
+ policy (`availability-policy.ts`, `createAvailabilityLatch`). A consumer the
730
+ gate can see is enforced by `tests/clients/availability-policy-coverage.test.ts`
731
+ (shrink-only `KNOWN_GAPS`); the named-store registry ratchet is still open
732
+ in #1894, so a change touching another store moves it onto the shared
733
+ policy by hand. ADR: docs/adr/0005-tool-availability-enforcement-seam.md
734
+
735
+ </important>
736
+
737
+
738
+ <!-- markdownlint-enable MD029 -->