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.
- package/CHANGELOG.md +477 -0
- package/README.md +45 -3
- package/config/biome/core.jsonc +3 -3
- package/config/dependency-cruiser-eager-allowlist.json +1 -0
- package/dist/{chunk-UBOQLVT2.js → chunk-2DDDCJDL.js} +4 -4
- package/dist/{chunk-RKKOYPRA.js → chunk-2DMLM3ZO.js} +13 -15
- package/dist/chunk-2F47TQOA.js +73 -0
- package/dist/{chunk-O4NWQT6I.js → chunk-2PHMIAKO.js} +4 -4
- package/dist/{chunk-DGUKIYSI.js → chunk-2RLWJO5K.js} +8 -10
- package/dist/{chunk-S67KYG37.js → chunk-2X4VLOCC.js} +2 -2
- package/dist/{chunk-TIQ2PKDW.js → chunk-3MYEA7QD.js} +4 -4
- package/dist/{chunk-3DA2JDOL.js → chunk-3WEPUD2V.js} +551 -203
- package/dist/{chunk-AMERCH6V.js → chunk-4AVZ3TG7.js} +15 -16
- package/dist/{chunk-IYNJ6YPZ.js → chunk-4PCQCU47.js} +4 -4
- package/dist/chunk-4WX4CTUE.js +57 -0
- package/dist/{chunk-P63GXC37.js → chunk-5APMQ2IJ.js} +31 -4
- package/dist/{chunk-ZIVJBOO3.js → chunk-5CV5ITZF.js} +2 -2
- package/dist/{chunk-6DLWKFEX.js → chunk-5ZR3APIM.js} +41 -42
- package/dist/{chunk-XTBDCR27.js → chunk-63RIVFQI.js} +4 -4
- package/dist/{chunk-GSLNCYGG.js → chunk-75SY4F24.js} +13 -14
- package/dist/{chunk-U44DJXQP.js → chunk-7RQXA5GG.js} +15 -18
- package/dist/chunk-A3YNG5KP.js +45 -0
- package/dist/{chunk-5OFV52AM.js → chunk-AE37FEGH.js} +1 -1
- package/dist/{chunk-BWD5EPKO.js → chunk-AMXIUN2R.js} +4 -6
- package/dist/{chunk-3KAZU3VR.js → chunk-ARD426WI.js} +2 -2
- package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
- package/dist/{chunk-YH5MVY2U.js → chunk-BHUWL2Y3.js} +7 -7
- package/dist/{chunk-CT4MN5IU.js → chunk-BI5LAQ3Y.js} +353 -359
- package/dist/{chunk-KAPJINKN.js → chunk-BM5GS6ZH.js} +2 -2
- package/dist/{chunk-TLX72JTG.js → chunk-BWYQUPOS.js} +1 -1
- package/dist/chunk-CFRQMBGP.js +49 -0
- package/dist/{chunk-RMLC67LF.js → chunk-CJYKEW2L.js} +2 -30
- package/dist/chunk-CKEQFGLT.js +32 -0
- package/dist/{chunk-IWDLU6K3.js → chunk-DC4CFXM5.js} +4 -6
- package/dist/{chunk-ZVUL7QYY.js → chunk-DMSLNKF7.js} +29 -32
- package/dist/{chunk-KN35K52N.js → chunk-DQXSPYRI.js} +3 -3
- package/dist/{chunk-HYGZEMX6.js → chunk-EVDGNG4F.js} +11 -5
- package/dist/{chunk-SRYEJNES.js → chunk-F5Z6URKM.js} +2 -2
- package/dist/{chunk-UMS2MFPZ.js → chunk-F6X3YJWD.js} +2 -3
- package/dist/{chunk-XYURS6EN.js → chunk-FA5LDARD.js} +15 -17
- package/dist/{chunk-24AKHFGP.js → chunk-FFL3A2VP.js} +6 -6
- package/dist/chunk-FJIVKLPH.js +31 -0
- package/dist/chunk-G2B7F6ZU.js +88 -0
- package/dist/{chunk-US7ECLD7.js → chunk-GAACZY6R.js} +131 -41
- package/dist/{chunk-MZGQNL3Y.js → chunk-GMTFDAOK.js} +12 -13
- package/dist/{chunk-VOOAPROD.js → chunk-GNSIWBAT.js} +3 -3
- package/dist/chunk-GTAI2J6U.js +27 -0
- package/dist/{chunk-RVK72CZX.js → chunk-GZE7WOI4.js} +1362 -459
- package/dist/{chunk-IUE7SSKV.js → chunk-H7HTEQUZ.js} +13 -7
- package/dist/{chunk-EUXZEFTV.js → chunk-HK6JVFZC.js} +3 -3
- package/dist/chunk-IPDG45G5.js +26 -0
- package/dist/{chunk-5HSRT26B.js → chunk-J6JP25XU.js} +16 -15
- package/dist/{chunk-HWCCCQNX.js → chunk-JL6CXUMW.js} +13 -6
- package/dist/{chunk-EBC36LNN.js → chunk-K2YGBXOA.js} +17 -17
- package/dist/{chunk-WMYE35PX.js → chunk-KLQVC3XC.js} +7 -5
- package/dist/{chunk-ATKJFDQN.js → chunk-KSR7RGQY.js} +12 -14
- package/dist/{chunk-POMLXPMY.js → chunk-KXF5R4UN.js} +1 -1
- package/dist/{chunk-LLJNQKQW.js → chunk-LEJOJDXL.js} +20 -13
- package/dist/{chunk-JUKMK5Y4.js → chunk-MA77RSFN.js} +10 -11
- package/dist/{chunk-GAQ7OQG6.js → chunk-MKVZQUEG.js} +85 -96
- package/dist/{chunk-2EECBNC5.js → chunk-MN7MHUXQ.js} +75 -0
- package/dist/{chunk-DEL2U6CM.js → chunk-MT6BVNFW.js} +16 -14
- package/dist/chunk-NDMCVUYK.js +507 -0
- package/dist/{chunk-HRNHZA3N.js → chunk-NIU2IPC5.js} +12 -16
- package/dist/{chunk-AGSS7277.js → chunk-NNKXDXXS.js} +7 -24
- package/dist/{chunk-V35JG4JB.js → chunk-OJLTLYHB.js} +152 -334
- package/dist/{chunk-J6MPGQTS.js → chunk-OLAWH5UQ.js} +81 -15
- package/dist/{chunk-T57LYLZT.js → chunk-OOU2WZZE.js} +1 -1
- package/dist/{chunk-CYRKQRPM.js → chunk-OSTKYB55.js} +2 -4
- package/dist/chunk-P4QNXS6I.js +27 -0
- package/dist/chunk-PKES3ISE.js +297 -0
- package/dist/{chunk-ROYSX2S5.js → chunk-PO45POGF.js} +2 -2
- package/dist/{chunk-T7FEBKXN.js → chunk-PPIBVH4R.js} +7 -9
- package/dist/{chunk-3RKP3FMS.js → chunk-PQJFG24Z.js} +295 -23
- package/dist/{chunk-KUA4OJ5Y.js → chunk-Q3UZHW6N.js} +846 -350
- package/dist/{chunk-N5FLEO7W.js → chunk-Q4EMRFNA.js} +37 -37
- package/dist/{chunk-5IUSNGOC.js → chunk-Q4FCYCRE.js} +28 -21
- package/dist/chunk-Q6D6VMI4.js +22 -0
- package/dist/{chunk-UZ2XCLYS.js → chunk-QGSTQH4D.js} +8 -8
- package/dist/{chunk-DUO2TU77.js → chunk-RZOXUSPC.js} +10 -4
- package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
- package/dist/{chunk-GMX5OS7B.js → chunk-S67UJDGQ.js} +11 -12
- package/dist/chunk-SCIUNBPF.js +44 -0
- package/dist/{chunk-RKBXZN3A.js → chunk-SJJYRZB4.js} +2 -2
- package/dist/chunk-SXGD4ANG.js +25 -0
- package/dist/{chunk-YCWYO6TQ.js → chunk-T7FTXGS3.js} +48 -45
- package/dist/{chunk-FM4RDMKT.js → chunk-TIQJPRDD.js} +115 -61
- package/dist/{chunk-XHJBS436.js → chunk-TIYGSODX.js} +25 -25
- package/dist/{chunk-S2HEXIWI.js → chunk-U2SDMG7C.js} +10 -6
- package/dist/{chunk-2KXTHF3M.js → chunk-U6OC3QEM.js} +253 -33
- package/dist/{chunk-AWSCPCN2.js → chunk-UCGQT677.js} +19 -19
- package/dist/chunk-UHGF5UT5.js +32 -0
- package/dist/{chunk-JW3YWBVB.js → chunk-UN4TEBWN.js} +17 -19
- package/dist/{chunk-ZHH37KZL.js → chunk-V3APN3DY.js} +17 -17
- package/dist/{chunk-ED36RF6Y.js → chunk-V63BC55Q.js} +1 -1
- package/dist/{chunk-XBJVAEEO.js → chunk-VG5JS5SW.js} +3 -2
- package/dist/{chunk-W66O5E25.js → chunk-VPBIMOAQ.js} +13 -15
- package/dist/chunk-VQH24FIP.js +37 -0
- package/dist/{chunk-YNE3RP52.js → chunk-VSFLRN5Y.js} +8 -1
- package/dist/{chunk-7D6L4MTX.js → chunk-W2V54OCL.js} +3 -3
- package/dist/{chunk-2FN63LPV.js → chunk-W5LGKNET.js} +13 -14
- package/dist/{chunk-IQWN5JCP.js → chunk-W5R5SABV.js} +13 -14
- package/dist/{chunk-R3T7CLQ2.js → chunk-WIZWZR4C.js} +41 -41
- package/dist/{chunk-TOY6QKOH.js → chunk-WQOIR3QY.js} +17 -17
- package/dist/{chunk-Y6GZHWSJ.js → chunk-XAIT2YGS.js} +6 -6
- package/dist/chunk-XCUHKYCQ.js +23 -0
- package/dist/{chunk-GSM5UU7A.js → chunk-XQCSWV2G.js} +44 -35
- package/dist/{chunk-OHKJ7PQF.js → chunk-YBSONGSZ.js} +43 -39
- package/dist/{chunk-GXFV6MYU.js → chunk-YISME6ON.js} +72 -39
- package/dist/chunk-YRD4ISED.js +30 -0
- package/dist/{chunk-SD4I7ZO4.js → chunk-YSBHPOY6.js} +43 -53
- package/dist/{chunk-QBFBRV2B.js → chunk-Z2XAOKHK.js} +4 -2
- package/dist/{chunk-5VSF4UUQ.js → chunk-Z7IGUAXL.js} +34 -39
- package/dist/{chunk-MPNJLASA.js → chunk-ZKXQKGWZ.js} +10 -13
- package/dist/{chunk-J64T55EI.js → chunk-ZQ6NZZTB.js} +75 -9
- package/dist/chunk-ZUUI3ZSA.js +38 -0
- package/dist/{chunk-7HXE67BN.js → chunk-ZYNI26MI.js} +2 -2
- package/dist/index.js +32674 -27567
- package/dist/mcp/analyze-cli.js +11 -12
- package/dist/mcp/cli.js +46 -45
- package/dist/mcp/server.js +1210 -574
- package/dist/mcp/worker.js +65 -65
- package/dist/probes/installer.js +21 -23
- package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
- package/docs/adr/README.md +1 -0
- package/docs/agent-tools.md +28 -7
- package/docs/ast-grep_rules_catalog.md +5 -3
- package/docs/configuration.md +12 -1
- package/docs/defect-shapes.md +738 -0
- package/docs/engineering-principles.md +12 -0
- package/docs/environment-variables.md +20 -0
- package/docs/features.md +16 -1
- package/docs/globalconfig.md +37 -8
- package/docs/invariants/caches-stores.md +30 -0
- package/docs/invariants/dispatch-runners.md +164 -0
- package/docs/invariants/git-guard-host.md +53 -0
- package/docs/invariants/language-config.md +31 -0
- package/docs/invariants/lsp-trust-exec.md +286 -0
- package/docs/invariants/paths-os.md +59 -0
- package/docs/invariants/session-telemetry.md +74 -0
- package/docs/lsp-capability-matrix.md +105 -12
- package/docs/lsp-idle-eviction.md +37 -18
- package/docs/pi-lens-fixer.md +24 -2
- package/docs/pi-lens-investigator.md +14 -0
- package/docs/pi-lens-merge-policy.md +32 -17
- package/docs/pi-lens-monitor.md +66 -10
- package/docs/pi-lens-orchestration.md +41 -0
- package/docs/pi-lens-release.md +20 -0
- package/docs/pi-lens-retro.md +5 -4
- package/docs/pi-lens-reviewer.md +54 -7
- package/docs/pi-lens-subagent.md +10 -3
- package/docs/release-qa-baseline.md +19 -7
- package/docs/servercapabilities.md +47 -47
- package/docs/settings.md +9 -5
- package/docs/subagent-compat.md +1 -1
- package/docs/usage.md +1 -0
- package/package.json +8 -5
- package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
- package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
- package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
- package/rules/rule-catalog.json +25 -1
- package/scripts/analyze-pi-lens-logs.mjs +15 -5
- package/scripts/lib/is-main-module.mjs +27 -0
- package/scripts/lib/scratch-home-env.mjs +21 -0
- package/scripts/rpc-load-check.mjs +4 -6
- package/scripts/warm-loader-cache.mjs +2 -5
- package/dist/chunk-3PTHXJXR.js +0 -28
- package/dist/chunk-3QED2P4V.js +0 -31
- package/dist/chunk-5WRPDP2A.js +0 -47
- package/dist/chunk-ABBOA7UD.js +0 -157
- package/dist/chunk-CUHSHSB6.js +0 -273
- package/dist/chunk-GL5LUMZE.js +0 -51
- package/dist/chunk-HAD7QRQI.js +0 -30
- package/dist/chunk-JORED7EX.js +0 -44
- package/dist/chunk-KYUB6QDC.js +0 -72
- package/dist/chunk-LZSEQW6A.js +0 -57
- package/dist/chunk-M2IFVFWU.js +0 -79
- package/dist/chunk-M2UD3LPU.js +0 -88
- package/dist/chunk-MBKQHGA7.js +0 -39
- package/dist/chunk-R7YOCSNV.js +0 -23
- package/dist/chunk-SKAMFC7A.js +0 -28
- package/dist/chunk-SYE6T2EB.js +0 -28
- package/dist/chunk-TRETHTQO.js +0 -26
- package/dist/chunk-UA7ZXYDR.js +0 -184
- package/dist/chunk-XTFDJI3T.js +0 -24
- 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 -->
|