pi-lens 4.4.7 → 4.4.9

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 (186) hide show
  1. package/CHANGELOG-USER.md +31 -0
  2. package/CHANGELOG.md +327 -0
  3. package/README.md +13 -2
  4. package/config/dependency-cruiser-eager-allowlist.json +1 -1
  5. package/config/markdownlint/run-no-fix.mjs +36 -0
  6. package/dist/{chunk-4LM3VAZH.js → chunk-2VZ3VN3N.js} +2 -2
  7. package/dist/{chunk-PUZ3E2J4.js → chunk-3HTZDY3C.js} +8 -6
  8. package/dist/{chunk-RORGS5II.js → chunk-3NPWO5UO.js} +7 -13
  9. package/dist/{chunk-MNJIXFX4.js → chunk-47UCC4MM.js} +1 -1
  10. package/dist/chunk-4ENEJHF4.js +198 -0
  11. package/dist/chunk-5GEYJJHG.js +22 -0
  12. package/dist/{chunk-U6VN4NVL.js → chunk-5YSEQHJN.js} +3 -3
  13. package/dist/{chunk-6IR3ZYIB.js → chunk-6GPB3JLL.js} +3 -3
  14. package/dist/{chunk-MB6PXBUA.js → chunk-7R5GZIA6.js} +7 -15
  15. package/dist/{chunk-DH5JPM3K.js → chunk-7UTSNTWM.js} +10 -9
  16. package/dist/{chunk-24BILSZW.js → chunk-7YTRG6YW.js} +2 -2
  17. package/dist/{chunk-KW5JQPO5.js → chunk-AACN5GNE.js} +2 -2
  18. package/dist/{chunk-PKES3ISE.js → chunk-ACRJ2GZ5.js} +2 -2
  19. package/dist/{chunk-4ZYJHQMB.js → chunk-C3YRO3EU.js} +10 -12
  20. package/dist/{chunk-PQJFG24Z.js → chunk-CB7PEVOJ.js} +1300 -946
  21. package/dist/{chunk-ABPKUVA4.js → chunk-CDFJF5YD.js} +1 -1
  22. package/dist/{chunk-T7A2HK2B.js → chunk-CJS6WE66.js} +17 -18
  23. package/dist/{chunk-3YY7IXIL.js → chunk-CM6BDY4E.js} +14 -60
  24. package/dist/{chunk-RZOXUSPC.js → chunk-CZCAZVTD.js} +16 -2
  25. package/dist/chunk-DGKFWQK4.js +23 -0
  26. package/dist/{chunk-NA7SEXHE.js → chunk-E65WJVI5.js} +7 -9
  27. package/dist/{chunk-2TF6RXWB.js → chunk-EKNYSXFB.js} +8 -10
  28. package/dist/{chunk-RRV3FNNM.js → chunk-EY6LY2HO.js} +27 -30
  29. package/dist/{chunk-LBLBAFG3.js → chunk-F6BEQWAK.js} +17 -5
  30. package/dist/{chunk-4L36HG27.js → chunk-FGNSESAC.js} +12 -14
  31. package/dist/{chunk-3FRLWYBG.js → chunk-FRUBVFXV.js} +39 -42
  32. package/dist/{chunk-FB5SCCPT.js → chunk-G22UNQID.js} +14 -15
  33. package/dist/{chunk-LV4UMYVH.js → chunk-GQTQUNCG.js} +26 -27
  34. package/dist/{chunk-E7HJ56Y7.js → chunk-H3BVMK47.js} +64 -73
  35. package/dist/chunk-H6FLQ5NW.js +28 -0
  36. package/dist/{chunk-QHSNL7B2.js → chunk-HEA3EM23.js} +15 -19
  37. package/dist/{chunk-AWDSEDER.js → chunk-HSOBIN22.js} +2 -2
  38. package/dist/{chunk-EAOK7MIZ.js → chunk-HYSKJMZK.js} +17 -4
  39. package/dist/{chunk-VUZWQ7UG.js → chunk-IICERRFF.js} +46 -72
  40. package/dist/{chunk-OXOI55RU.js → chunk-IILEH3ZC.js} +8 -10
  41. package/dist/{chunk-ZKXQKGWZ.js → chunk-J3Q2NYJR.js} +4 -3
  42. package/dist/{chunk-YHC2O2WO.js → chunk-JUZ67QZQ.js} +20 -9
  43. package/dist/chunk-KR5VGMVT.js +25 -0
  44. package/dist/{chunk-F7K5IBZG.js → chunk-KV6GQOGN.js} +41 -44
  45. package/dist/{chunk-SNDXCFRS.js → chunk-KXMJLOZF.js} +25 -23
  46. package/dist/{chunk-CB4WHS4H.js → chunk-L4Y3ROKQ.js} +3 -3
  47. package/dist/{chunk-3F6BMY53.js → chunk-L6WBJGQS.js} +1 -1
  48. package/dist/{chunk-MPKRJBPK.js → chunk-L7O774U7.js} +30 -32
  49. package/dist/{chunk-URCQWAQ4.js → chunk-LAHHGNAY.js} +21 -21
  50. package/dist/{chunk-V63BC55Q.js → chunk-LT62P654.js} +1 -1
  51. package/dist/{chunk-ZMAUPOMG.js → chunk-LWOM6LVS.js} +34 -34
  52. package/dist/{chunk-HO6LWE2E.js → chunk-MKPDIAZH.js} +21 -1
  53. package/dist/{chunk-2PHMIAKO.js → chunk-MN635QYA.js} +3 -4
  54. package/dist/{chunk-KDX35VXP.js → chunk-MQ4PPCJB.js} +166 -149
  55. package/dist/{chunk-QOE342SU.js → chunk-MRLH4MYU.js} +2 -2
  56. package/dist/{chunk-CE6VMBCB.js → chunk-N56BNAA6.js} +20 -21
  57. package/dist/{chunk-L3CMBQMH.js → chunk-N5CEGQPG.js} +14 -17
  58. package/dist/{chunk-7E2563GA.js → chunk-NCLO6E6N.js} +13 -33
  59. package/dist/{chunk-J6JP25XU.js → chunk-NL5LSKVD.js} +4 -3
  60. package/dist/{chunk-U7BD2QL7.js → chunk-NMUSOZ2D.js} +10 -12
  61. package/dist/{chunk-BZARLRJW.js → chunk-NOWH2VA2.js} +8 -33
  62. package/dist/{chunk-U2SDMG7C.js → chunk-NUSXS6YB.js} +6 -5
  63. package/dist/{chunk-ZJTT47IG.js → chunk-OSEKJEUU.js} +2 -2
  64. package/dist/{chunk-FZKFVUEC.js → chunk-OUYAUXAT.js} +647 -355
  65. package/dist/{chunk-ZE3KXHS7.js → chunk-PBZNYHMM.js} +84 -4
  66. package/dist/{chunk-U5HPROLA.js → chunk-PIIUNJIT.js} +2 -4
  67. package/dist/chunk-PKLB2XJL.js +8 -0
  68. package/dist/{chunk-RC2Z6K47.js → chunk-PRHYIA6X.js} +15 -6
  69. package/dist/{chunk-RQS4QQSD.js → chunk-PXQ45SGD.js} +2 -2
  70. package/dist/chunk-Q6JQKWPK.js +25 -0
  71. package/dist/{chunk-F6X3YJWD.js → chunk-QB7T2PHK.js} +2 -2
  72. package/dist/{chunk-TIQJPRDD.js → chunk-QGITU23N.js} +3 -2
  73. package/dist/chunk-QJJKOHLH.js +57 -0
  74. package/dist/{chunk-4LOE5R5P.js → chunk-QP33NKYC.js} +18 -15
  75. package/dist/{chunk-N5WSK2K7.js → chunk-QVBOXT3L.js} +12 -17
  76. package/dist/{chunk-DPGEAHZT.js → chunk-RNJFRXEN.js} +10 -18
  77. package/dist/{chunk-EKWX4WD3.js → chunk-RNXOWDM6.js} +10 -10
  78. package/dist/{chunk-O4BJFESU.js → chunk-RTFMDIKV.js} +1 -1
  79. package/dist/{chunk-LS3QJRUB.js → chunk-SIQHOB6P.js} +11 -13
  80. package/dist/{chunk-3K2F6UDZ.js → chunk-SLSMJPEF.js} +43 -42
  81. package/dist/chunk-T5QSLSMM.js +50 -0
  82. package/dist/chunk-TGQDAG4B.js +88 -0
  83. package/dist/{chunk-4YHYPW2G.js → chunk-THYHUIDR.js} +44 -13
  84. package/dist/{chunk-YVHBNSME.js → chunk-TMNUTMT5.js} +1099 -1100
  85. package/dist/{chunk-WDBICWH3.js → chunk-TOE2RRCS.js} +1 -1
  86. package/dist/chunk-TYHPVE5H.js +25 -0
  87. package/dist/chunk-UAKO2M6B.js +73 -0
  88. package/dist/chunk-UC5AXW5Z.js +20 -0
  89. package/dist/chunk-UTJP6WOS.js +28 -0
  90. package/dist/{chunk-DQZFQSR5.js → chunk-UXTQ3QPD.js} +4 -4
  91. package/dist/chunk-UYXV5NIS.js +20 -0
  92. package/dist/{chunk-KKCK636N.js → chunk-V2WDBOLZ.js} +10 -12
  93. package/dist/{chunk-PR6PO3ES.js → chunk-V67D6TMU.js} +22 -20
  94. package/dist/{chunk-VSFLRN5Y.js → chunk-VCRVNLE7.js} +135 -2
  95. package/dist/{chunk-CPSR3AVL.js → chunk-VO4JFPTV.js} +2 -2
  96. package/dist/{chunk-XT2HTCJ5.js → chunk-VWLSU3XV.js} +6 -5
  97. package/dist/{chunk-WME2OQST.js → chunk-W5E72HJA.js} +66 -24
  98. package/dist/{chunk-LLS45EWB.js → chunk-W7TY6HYX.js} +6 -8
  99. package/dist/{chunk-CCV2EU7T.js → chunk-WSSLVMDA.js} +12 -13
  100. package/dist/{chunk-YISME6ON.js → chunk-WTB4GKMH.js} +10 -1
  101. package/dist/{chunk-KPPJTH44.js → chunk-X5BJ3G2P.js} +64 -35
  102. package/dist/{chunk-JMEKXFOL.js → chunk-XKFO2SZV.js} +39 -34
  103. package/dist/{chunk-HR3OJ3TH.js → chunk-XLAI7UYY.js} +84 -31
  104. package/dist/{chunk-H7OR7DFZ.js → chunk-XO756WE5.js} +53 -37
  105. package/dist/{chunk-F5Z6URKM.js → chunk-XVB3Q2PG.js} +2 -4
  106. package/dist/{chunk-R5MOQM2H.js → chunk-YOXCCJDF.js} +607 -366
  107. package/dist/{chunk-ZGSJDWQU.js → chunk-ZCQBNPRH.js} +2 -2
  108. package/dist/chunk-ZD4KVFXI.js +234 -0
  109. package/dist/{chunk-WGRJOXED.js → chunk-ZDMFGACN.js} +1295 -966
  110. package/dist/{chunk-OSTKYB55.js → chunk-ZMMHHXSW.js} +1 -1
  111. package/dist/{chunk-75GAYVNO.js → chunk-ZPM7ZIFL.js} +6 -6
  112. package/dist/{chunk-LUBPZN36.js → chunk-ZVCDHYWZ.js} +9 -11
  113. package/dist/{chunk-Y7F7IEE3.js → chunk-ZZN74OGD.js} +102 -7
  114. package/dist/{chunk-L5JYIU47.js → chunk-ZZSJAR76.js} +39 -20
  115. package/dist/index.js +10933 -8644
  116. package/dist/mcp/analyze-cli.js +12 -17
  117. package/dist/mcp/cli.js +43 -42
  118. package/dist/mcp/server.js +3073 -1147
  119. package/dist/mcp/worker.js +61 -61
  120. package/dist/probes/installer.js +18 -19
  121. package/docs/adr/0003-git-guard-latch-writer.md +11 -6
  122. package/docs/agent-tools.md +58 -16
  123. package/docs/alignment-families.md +29 -0
  124. package/docs/analysisall.md +1 -1
  125. package/docs/ast-grep_rules_catalog.md +6 -4
  126. package/docs/ci-bot-pr-checks.md +128 -0
  127. package/docs/configuration.md +150 -12
  128. package/docs/defect-shapes.md +107 -15
  129. package/docs/engineering-principles.md +27 -2
  130. package/docs/environment-variables.md +18 -1
  131. package/docs/features.md +14 -7
  132. package/docs/globalconfig.md +11 -3
  133. package/docs/invariants/git-guard-host.md +7 -3
  134. package/docs/invariants/language-config.md +15 -4
  135. package/docs/invariants/lsp-trust-exec.md +25 -4
  136. package/docs/invariants/paths-os.md +4 -2
  137. package/docs/invariants/session-telemetry.md +2 -2
  138. package/docs/language-coverage.md +1 -0
  139. package/docs/lsp-capability-matrix.md +167 -65
  140. package/docs/lsp-idle-eviction.md +4 -1
  141. package/docs/merge-queue-rollout.md +10 -8
  142. package/docs/module-report-read-symbol.md +34 -23
  143. package/docs/pi-lens-fixer.md +34 -17
  144. package/docs/pi-lens-investigator.md +3 -0
  145. package/docs/pi-lens-merge-policy.md +34 -17
  146. package/docs/pi-lens-monitor.md +9 -0
  147. package/docs/pi-lens-orchestration.md +4 -1
  148. package/docs/pi-lens-reviewer.md +6 -6
  149. package/docs/pi-lens-subagent.md +19 -3
  150. package/docs/public-api-stability.md +57 -7
  151. package/docs/release-qa-baseline.md +7 -4
  152. package/docs/schema/pi-lens-config-v1.json +21 -2
  153. package/docs/servercapabilities.md +3 -1
  154. package/docs/settings.md +11 -7
  155. package/docs/word-index.md +20 -7
  156. package/package.json +11 -4
  157. package/rules/ast-grep-rules/rule-tests/no-accumulating-spread-js-test.yml +37 -0
  158. package/rules/ast-grep-rules/rule-tests/ts-redundant-filter-map-test.yml +12 -1
  159. package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-js-test.yml +12 -0
  160. package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-test.yml +25 -0
  161. package/rules/ast-grep-rules/rules/no-accumulating-spread-js.yml +49 -1
  162. package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +1 -2
  163. package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +1 -2
  164. package/rules/ast-grep-rules/rules/ts-redundant-filter-map.yml +9 -1
  165. package/rules/ast-grep-rules/rules-disabled/filter-then-map-js.yml +17 -0
  166. package/rules/ast-grep-rules/rules-disabled/filter-then-map.yml +36 -0
  167. package/rules/ast-grep-rules/self-scan-baseline.json +1 -1
  168. package/scripts/download-grammars.js +3 -2
  169. package/skills/pi-lens-lsp-navigation/SKILL.md +5 -1
  170. package/dist/chunk-46TNM7XZ.js +0 -88
  171. package/dist/chunk-72OKUXSD.js +0 -31
  172. package/dist/chunk-7GLOLOSH.js +0 -57
  173. package/dist/chunk-AKUUMGD5.js +0 -26
  174. package/dist/chunk-ASUXV767.js +0 -22
  175. package/dist/chunk-CTADOKYM.js +0 -25
  176. package/dist/chunk-GNSIWBAT.js +0 -106
  177. package/dist/chunk-HWDAVBFU.js +0 -49
  178. package/dist/chunk-JJ2RRESP.js +0 -58
  179. package/dist/chunk-KXF5R4UN.js +0 -48
  180. package/dist/chunk-LSC3VADM.js +0 -23
  181. package/dist/chunk-OE5ZBP7F.js +0 -443
  182. package/dist/chunk-SHLDT3OI.js +0 -27
  183. package/dist/chunk-UF7RTZSO.js +0 -27
  184. package/dist/chunk-W4WP2ERB.js +0 -30
  185. package/dist/chunk-YES5CACN.js +0 -73
  186. package/dist/chunk-Z2XAOKHK.js +0 -136
@@ -41,8 +41,9 @@ registry; other doubles only as `AGENTS.md` admits them.
41
41
  compose, and flag merge order in the PR body. Branch `fix/<N>-<slug>` from
42
42
  `origin/master` unless the brief names a branch. Preserve contributor
43
43
  authorship on a contributor's branch.
44
- - Write the failure list in the PR body before the first edit (principles §2):
45
- inputs, states, orderings, and platforms; a space with two axes is a table.
44
+ - Write the failure list under `### Tests` in the PR body before the first edit
45
+ (principles §2): inputs, states, orderings, and platforms; a space with two
46
+ axes is a table.
46
47
  The tests cover that list, not only the happy path. For a change to N of M
47
48
  members, the list also names M, the excluded default, and the planned
48
49
  generalization verdict: *widen in this PR*, *follow-up issue* with its seam
@@ -85,7 +86,7 @@ registry; other doubles only as `AGENTS.md` admits them.
85
86
  tests stay green; put any behaviour change in a separate commit (#3817).
86
87
  - Delete vacuous tests in the files you touch (a case that reds on no
87
88
  mutation, asserts a constant, or duplicates a sibling), with the sweep
88
- transcript quoted in `Test assessment`. A redundant test that still guards
89
+ transcript quoted in `### Tests`. A redundant test that still guards
89
90
  goes only with the named survivor that covers it.
90
91
  - Apply folded review follow-ups per `docs/pi-lens-subagent.md`
91
92
  "Follow-ups", and list every gap left open in one **Accepted residuals** section of
@@ -232,7 +233,8 @@ registry; other doubles only as `AGENTS.md` admits them.
232
233
  (#2654).
233
234
  - Spot-check one prior round's mutation on the new head (#2583).
234
235
  - Re-read the changelog fragment for any claim the round retracts (#3155), then
235
- add an honest review-round section to the PR body.
236
+ update the PR body in place so it describes the current head. Do not append a
237
+ round section; commits and review threads hold the history.
236
238
  - Lint the PR body (`--lint-local`) before the first push of a round, not only
237
239
  at hand-back: `PR body (advisory)` re-reads the same body on every push, so
238
240
  an unfixed finding reds each one.
@@ -245,21 +247,36 @@ remains: prefer deleting over simplifying, simplifying over optimizing, and
245
247
  optimizing over automating. If the diff survives, leave it alone; churn is not
246
248
  rigor (#2599).
247
249
 
250
+ The hand-back summary lists scope growth first, then a `Decisions:` line: each
251
+ default you chose and each brief line you read a particular way, with its
252
+ reason. Each check the body or the hand-back cites as proof names what it does
253
+ not prove in one clause (`does not prove: Windows`, `does not prove: a real
254
+ server`), so routing reads the gap, not only the green. A reinterpretation the
255
+ orchestrator has to discover in the diff is a finding (#5242 kept a version the
256
+ brief misnamed; #5254 read "turn" as a prompt).
257
+
248
258
  ## Handoff
249
259
 
250
- - The PR body is the whole `.github/PULL_REQUEST_TEMPLATE.md`, every
251
- heading present in order: `## Why` (one sentence), `## Notes for the
252
- reviewer`, `## Change outline`, `## Summary`, `## Type of change`,
253
- `## Area`, `## Checklist`, `## Tests`, `## Blast radius`,
254
- `## Observability` (a record literal from the runtime diff, `none: <reason>`,
260
+ - The PR body follows `.github/PULL_REQUEST_TEMPLATE.md`, which a reader must
261
+ be able to scan (#5003): `## Summary` (at most three sentences, with the
262
+ closing keyword, which GitHub ignores in a title, and with counted sentences
263
+ in its `Refs #NNN`, `Remaining #NNN:` and `Closes #NNN` lines counted too),
264
+ `## Notes for the reviewer`
265
+ (at most five bullets, no tables or fences), `## Change outline`, and
266
+ `## Proof and checks` with `### Tests`, `### Class sweep` (ending in one
267
+ `Alignment:` line that names the families of `docs/alignment-families.md` the
268
+ change touches, or `none: <reason>` of 12+ characters),
269
+ `### Observability` (a record literal from the runtime diff, `none: <reason>`,
255
270
  or exactly `No new failure path; no record added.`, which a new decision
256
- branch on a session, lifecycle or delivery seam refuses, #3875),
257
- `## Class sweep`, `## Fold check` (one line per candidate, `#N folded`,
258
- `#N not folded` or `#N sequenced`, then its reason, or `none: <reason>`;
259
- the body lint owns the form and the local script owns the candidate list,
260
- #4711), and `## Test assessment`. A brief that names only some
261
- headings does not shorten this list. The closing keyword lives in the body;
262
- GitHub ignores it in a title.
271
+ branch on a session, lifecycle or delivery seam refuses, #3875), and
272
+ `### Fold check` (one line per candidate, `#N folded`, `#N not folded` or
273
+ `#N sequenced`, then its reason, or `none: <reason>`; the body lint owns the
274
+ form and the local script owns the candidate list, #4711). Add `### Blast
275
+ radius` only when the change reaches outside the touched module or hits a hot
276
+ path. The lint caps visible text at 5000 characters and each code fence at 20
277
+ lines: quote failing lines, not whole runs, and give each mutation one table
278
+ row, not a paragraph. A brief that names only some headings does not shorten
279
+ this list.
263
280
  - Run `node scripts/check-pr-body.mjs --lint-local PR_BODY.md` and
264
281
  `node scripts/check-changelog-fragments.mjs` before the hand-back; both
265
282
  must pass, and the hand-back quotes them. The body lint reads the closed
@@ -272,7 +289,7 @@ rigor (#2599).
272
289
  reference written as `owner/repo#N` or a URL is refused unless the body
273
290
  already closes a bug, which owes the section whatever else it cites. CI refuses a label
274
291
  it cannot read; the local preflight, with no working gh, warns and skips it
275
- as for a closed issue (#4968). A non-bug PR either deletes the `## Detection` section or
292
+ as for a closed issue (#4968). A non-bug PR either deletes the `### Detection` section or
276
293
  fills the three lines, and a `Shape:` or `Enforcer:` line it does write is
277
294
  validated too; free text in between reds the local preflight. A bug-closing
278
295
  PR that answers a layer, the `Gap: none:` reason, the `Shape: new:` name or
@@ -9,6 +9,9 @@ issue and the requested evidence surface.
9
9
  - Keep the worktree and Git state read-only.
10
10
  - Define the symptom as an answerable question with time window, sessions, and
11
11
  build in scope.
12
+ - Search closed issues and merged PRs for the target before the first probe;
13
+ a closed duplicate is the answer (a second #5123 investigation ran on
14
+ 2026-11-02).
12
15
  - Reproduce through the reporter's production entry point before naming a seam.
13
16
  - Deliver a proven diagnosis and one concrete next step; a plausible story is
14
17
  not a diagnosis. Implement only a contained fix the brief asks for, under
@@ -19,19 +19,24 @@ acceptance surface quoted from that run's log. Any self-bound inside the lane
19
19
  must sit below the job cap by a stated margin so the loud-failure path is
20
20
  reachable.
21
21
 
22
- Every PR body starts with `## Why`, `## Notes for the reviewer`, and
23
- `## Change outline`, followed by the existing `## Summary`, `## Tests`,
24
- `## Blast radius`, `## Class sweep`, `## Observability`, and `## Fold check`
25
- sections. The change outline is the changed symbol's caller/callee tree with
26
- `+`/`-` on moved lines; include only structural views that changed.
22
+ Every PR body has `## Summary` (at most three sentences, counted sentences in
23
+ its `Refs #NNN`, `Remaining #NNN:` and `Closes #NNN` lines included),
24
+ `## Notes for the reviewer` (at most five bullets), `## Change outline`, and
25
+ `## Proof and checks`, which holds `### Tests`, `### Class sweep`,
26
+ `### Observability`, and `### Fold check`, plus the conditional sections the
27
+ template lists. The change outline is the changed symbol's caller/callee tree
28
+ with `+`/`-` on moved lines; include only structural views that changed.
29
+ `scripts/check-pr-body.mjs` caps visible text at 5000 characters and each code
30
+ fence at 20 lines (#5003).
27
31
 
28
32
  ## The loop, per PR
29
33
 
30
34
  1. **Review.** Spawn `pi-lens-reviewer` (worktree isolation) with the PR
31
35
  number, a one-paragraph summary of the claim, and any PR-specific attack
32
36
  angles. Self-authored and small PRs get reviewed too — the depth follows
33
- the review tier below, never the priority label. Bots review the PR as well:
34
- every bot thread (Greptile and others) gets a disposition reply, `fixed in
37
+ the review tier below, never the priority label. Bots review a PR when the
38
+ orchestrator requests it (`@coderabbitai review`, `@greptileai`,
39
+ `/agentic_review`), never on their own: every bot thread (Greptile and others) gets a disposition reply, `fixed in
35
40
  <sha>`, `accepted and disclosed`, or `rejected because <reason>`.
36
41
  2. **Fix rounds.** Send findings back to the PR's original author agent when
37
42
  its worktree survives (SendMessage — cheapest context); otherwise spawn
@@ -209,7 +214,7 @@ issue filed without one is a triage defect, not a shortcut.
209
214
  **Merge bar (user, 2026-10-18).** A PR merges when no HIGH finding is open and
210
215
  every gating check is green on the exact head. Each MEDIUM or LOW finding
211
216
  either folds into the same PR or becomes an accepted residual: the PR body
212
- lists it under `## Accepted residuals`, named `p3` with its severity and live
217
+ lists it under `### Accepted residuals`, named `p3` with its severity and live
213
218
  population (for example `p3 (MEDIUM, live 0): <the gap>`), so the gap keeps a
214
219
  priority without an issue.
215
220
  A residual never becomes a follow-up issue. File an issue only for p2 or
@@ -221,10 +226,16 @@ reopen the round.
221
226
  **Known gaps (user, 2026-10-19).** An open p3 issue is an accepted known gap,
222
227
  not backlog. The orchestrator closes it as not planned with the `known-gap`
223
228
  label and lists it under its seam on the pinned tracker #4626. When a PR
224
- merges, its `## Accepted residuals` lines join the same tracker under their
229
+ merges, its `### Accepted residuals` lines join the same tracker under their
225
230
  seam. A known gap reopens as p2 when it turns material: a live wrong result,
226
231
  data loss, a hang, or a leak with no bound.
227
232
 
233
+ **Ideas go on the tracker (user, 2026-10-31).** A rule candidate, research idea
234
+ or optional slice that no lane will start is never filed as a p3 issue. It goes
235
+ straight onto the pinned known-gaps tracker under its seam. On 2026-10-31 five
236
+ such issues were filed from research passes (#5083, #5091, #5093, #5094,
237
+ #5096); three were closed onto #4835.
238
+
228
239
  Every reviewer **follow-up issue** generalization verdict that meets that bar is
229
240
  filed and assigned to a seam group on the tracking queue in the same turn. At each regroup, scan
230
241
  merged PRs for subset-shaped changes that lack a generalization verdict.
@@ -312,7 +323,7 @@ operator's private notes, so a different orchestrator can run the same train.
312
323
  | a change that touches identifier uses of a glossary-retired synonym | run `tests/config/glossary-synonym-sweep.test.ts` on the head AND on the merge with `origin/master`, then re-pin in the PR from the sweep's own `UNPINNED`/`STALE` output — #3279, #3283, #3284, #3288 |
313
324
  | a new `vi.mock` in a test file | run `tests/config/vi-mock-export-sweep.test.ts`; whole-module mocks of a production module must spread `importOriginal` — PR #3268's CI red, fixed by trailing commit `621d61c5c` |
314
325
  | a changelog fragment | front matter `section: <Section>` plus `audience: user` or `audience: internal` and exactly one top-level entry; new user entries open with a bold lead of at most 100 characters (refs excluded), never `CHANGELOG.md`, validated by `node scripts/check-changelog-fragments.mjs` — PR #3268 r1 shipped `category:` and a paragraph |
315
- | a PR body | the header gate: exactly one-sentence `## Why`, `## Notes for the reviewer`, `## Change outline`, plus Summary / Tests with `### Test assessment` / Blast radius / Class sweep / Fold check / Observability; run `node scripts/check-pr-body.mjs --lint-local` before pushing — three PRs this week needed orchestrator body edits |
326
+ | a PR body | the header gate: `## Summary`, `## Notes for the reviewer`, `## Change outline`, plus Tests / Class sweep / Fold check / Observability, inside the caps; run `node scripts/check-pr-body.mjs --lint-local` before pushing — three PRs this week needed orchestrator body edits |
316
327
  | a whole-tree docs restructure of `AGENTS.md` | every governance test that reads `AGENTS.md`, with markers on their own lines — PR #3265 r1 |
317
328
  | a raw poll in a test | the flake-shape ratchet; the fix is the governed wait, never a header admission — #2781 r1 |
318
329
  | a new, renamed or deleted rule file under `rules/` | `npm run docs:rule-catalogs` and commit the generated catalog; `tests/scripts/rule-catalogs.test.ts` is a strict consumer of every rule file, not of rule ids — #3214 r1 |
@@ -366,8 +377,9 @@ operator's private notes, so a different orchestrator can run the same train.
366
377
  applies to human PRs; a bump title can never carry a ref. Merge order: one
367
378
  at a time (each merge dirties the rest; dependabot rebases them itself);
368
379
  gate on Lint, Unit tests and every non-advisory check on the exact head;
369
- pr-metadata.yml itself skips "PR title", "PR body (advisory)" and
370
- "Close-keyword syntax" for dependabot (2026-09-09, refs #2714), so nothing
380
+ pr-metadata.yml itself skips "PR metadata" (the title and close-keyword
381
+ checks, one job since #5002) and "PR body (advisory)" for dependabot
382
+ (2026-09-09, refs #2714), so nothing
371
383
  needs hand-ignoring; hold anything red on a real check
372
384
  with a comment naming the check (2026-09-07: tsls 6 needs a Node-floor bump, biome
373
385
  fails the install test, vitest 5 fails four gates; a bump whose install
@@ -418,7 +430,7 @@ operator's private notes, so a different orchestrator can run the same train.
418
430
  also fine). The merge loop is
419
431
  `node scripts/ci-verdict.mjs <pr> --wait <seconds>` — read its final line:
420
432
  0 merge, 3 still pending (re-arm the wait), anything else read the table. Never
421
- text-match the table for `failure`: advisory rows (PR body, Vale)
433
+ text-match the table for `failure`: advisory rows (PR body, Lint (advisory))
422
434
  print `failure` while the verdict is green, and on 2026-09-07 that stopped
423
435
  the #2692 loop on a green PR.
424
436
  - **Maintainer trailing commits** are for intent-free deltas only (a literal
@@ -517,7 +529,7 @@ operator's private notes, so a different orchestrator can run the same train.
517
529
  the verdict table for `failure`, because advisory rows print `failure` on a
518
530
  green PR. But "does not gate" is not "carries no information", and filtering
519
531
  advisory rows out of your attention is a different mistake from filtering
520
- them out of the gate. `typos (advisory)` found a real defect in #2955's
532
+ them out of the gate. The typos step of `Lint (advisory)` found a real defect in #2955's
521
533
  round-12 diff — a comment in which "reading" was misspelt — which the
522
534
  gating checks had no opinion about and which would otherwise have reached
523
535
  master. (The misspelling is described rather than reproduced here: quoting
@@ -554,7 +566,7 @@ operator's private notes, so a different orchestrator can run the same train.
554
566
  DETECTION lesson in one line: which verification layer caught it and which
555
567
  layer SHOULD have caught it earlier and at what cost. The accepted layer
556
568
  words are the `DETECTION_LAYERS` list exported by `scripts/check-pr-body.mjs`,
557
- which the `## Detection` body check reads; the prose does not restate them.
569
+ which the `### Detection` body check reads; the prose does not restate them.
558
570
  `nightly` may carry its workflow as `nightly:<workflow>`. A PR that only
559
571
  references a `bug` or `nightly-drift` issue, in its body or its title, owes
560
572
  the section too (#4968: the 2026-10-29 audit found 24 bug-linked PRs merged
@@ -723,7 +735,7 @@ Each row cost a lane at least once; the prose above carries the record.
723
735
  | Reviewing a branch head that no longer carries master | Reviewer merges origin/master into the scratch checkout first; CONFLICTING is not reviewable (#2808 vs #2795) |
724
736
  | Pushing docs, config or data straight to master without preflight | `npm run preflight` on the exact tree first; three master reds on 2026-09-09 |
725
737
  | Nudging a capped small-model lane more than once | One continuation, then reassign to the strongest model (GLM lanes, 2026-09-09) |
726
- | Waiting on CI for a bot-authored PR (github-actions nightly refresh) | A GITHUB_TOKEN push fires no `pull_request` run: required checks stay ABSENT forever; close/reopen the PR to fire them (#2801, 2026-09-09) |
738
+ | Waiting on CI for a bot-authored PR (github-actions nightly refresh) | A GITHUB_TOKEN push fires no `pull_request` run. Since #5062 the opening job dispatches `ci.yml` and `lint.yml` on the bot branch (`docs/ci-bot-pr-checks.md`); a bot PR still BLOCKED with every check absent means that dispatch step failed or did not run: read the nightly's `Open refresh PRs` job, then close/reopen to fire the checks (#2801, 2026-09-09) |
727
739
  | Leaving a design question to the fixer (where evidence comes from, which identity rule) | Decide it in the brief; #2900 oscillated three rounds (walker → findings → walker again) until round 4's brief fixed the evidence source (2026-09-10) |
728
740
  | Guessing a lane's branch name when writing a brief | Read `gh pr view N --json headRefName` in the same command that builds the brief; plegma refused two dispatches on invented refs (#2908, #2898; 2026-09-10) |
729
741
  | `git add -A -- . ':!<ignored file>'` in a chained command | The exclude pathspec on an IGNORED path makes `git add` exit 1 and the chain stops before the commit; use plain `git add -A` (ignored files never stage) and verify the index afterwards (2026-09-10, twice) |
@@ -849,9 +861,14 @@ Each row cost a lane at least once; the prose above carries the record.
849
861
  | Pushing to a PR branch while a fix round is queued against its old head | Merging master into #4594 staled the queued round's lease; the worker pushed a diverged copy to its handle branch (plegma #723). The orchestrator's push-verify refuses while a round still publishes to that branch. |
850
862
  | Resuming a reviewer without naming the deliverable | The resumed verifies of #4575 and #4593 inherited report names that did not match the brief, so the hand-back missed the report. Every resumed round names its `deliverables` explicitly. |
851
863
  | Calling an issue "blocked on a release" without reproducing it on master | #4554 waited on a release; 58 runs on master did not reproduce it, and it closed crediting #4563. Reproduce on master before naming a blocker. |
852
- | Bolding a residual bullet (`- **p3 (LOW, live 0):**`) under `## Accepted residuals` | The tracker parser read only a bare `p3`, so #4832's three residuals were recorded as "none" (2026-10-25). `known-gap-add.sh` now reads the bold form, pinned by its test case (g) |
864
+ | Bolding a residual bullet (`- **p3 (LOW, live 0):**`) under `### Accepted residuals` | The tracker parser read only a bare `p3`, so #4832's three residuals were recorded as "none" (2026-10-25). `known-gap-add.sh` now reads the bold form, pinned by its test case (g) |
853
865
  | Planning a tracker layout before measuring the platform's limits | An 11-issue pinned split was proposed and dispatched; GitHub pins 3 issues per repository, and the assumed 65k body cap was already exceeded by #4626 at 91k (2026-10-25). Measure the limit first, then plan |
854
866
  | Pasting the `claude-lane.sh` header into a brief | The header began `Worktree (created, ...):`, the brief guard wants `Worktree:`, and two dispatches were refused (2026-10-25). The header now starts with `Worktree:`, pinned by `test-claude-lane-header.sh` |
855
867
  | Linting a PR body in the main checkout | The main checkout sits on another branch, so citations resolved against the wrong tree; three edits needed a hand-built head tree (2026-10-25). `pr-body.sh edit` without `--tree` now builds a temp tree at the PR head |
856
868
  | Guessing issue labels (`area:ci`, `area:formal`, `chore`) | Three filings were refused, and the refusal listed only priority labels (2026-10-25). `file-issue.sh` now lists the known type, area and priority labels |
857
869
  | Reaping a lane whose issue is closed while its ledger row is live | Two maintainer-ordered lanes on closed issues (#4714, #4691) were flagged for TaskStop (2026-10-25). `agent-reap.sh` now skips a closed issue with a live ledger row |
870
+ | Dispatching four heavy plegma workers while a local model server runs | The host ran out of memory, hung, and took the daemon and two reviews with it (2026-11-02). The cap is two heavy workers while `ds4-server` or `llama-server` runs, and the orchestrator dispatch guard now lowers the daemon's live heavy cap to two while either process runs |
871
+ | Regenerating `package-lock.json` with the npm on PATH | npm 9.2 dropped every `libc` field twice in one day (#5200, the #5201 bump), and npm 11.18.0 had to redo it. Regenerate only with `npx npm@11.18.0 install --package-lock-only --ignore-scripts`. The default `check:lockfile` reads `libc` only on the root entry, so it does not refuse the drop yet; #5207 (open) adds that refusal |
872
+ | Applying a reviewer's reuse prescription without its ratchets | Verify r3 on #5202 asked to import `REAL_NODE_MODULES` from lane-check-kit; that module imports `child_process`, and the flake-shape real-process-spawn ratchet then flagged the test (2026-11-02). Run the governance suite on a prescription before pushing it; the round reverted to the local path |
873
+ | Bisecting a worktree-only red by hand | Three unrelated files red in one plegma tree and green on master; an hour of bisecting ended at a stale shared `node_modules/.vitest-cache` (2026-11-02). Rerun once with `--fsModuleCache=false` before bisecting; #5212 moved Vitest's module cache (`fsModuleCachePath`) into each worktree's `.vitest-cache`, so new runs stop writing the shared copy. The old copy in the main install stays until someone deletes it, and the runtime `vitest.config.mjs` from `tests/support/lane-check-kit.ts` still writes there (accepted residual) |
874
+ | Dispatching a user-facing design before the maintainer has seen the output | #5202 round 4 was interrupted twice as the maintainer moved from full prose to headlines to a straight copy of the release bodies (2026-11-02). Show the rendered sample and agree the design before the round |
@@ -135,6 +135,15 @@ the requested window.
135
135
  `filePath` even for a formatter that never settles or an Escape; a chained
136
136
  file with no later `*_format_late_resync` row on the same `filePath` is the
137
137
  anti-join to report.
138
+ `withheld_blocker_late_advisory` (#5108) is the same hand-off for a
139
+ tool_result handler the host bound abandoned while a run without authorship
140
+ withheld blockers: one row per abandoned call that queued its disclosure
141
+ for the calling session's next context call, with `metadata.notices` (the
142
+ withheld lines; the advisory shows five) and `metadata.budgetMs`, and the
143
+ tool name as `filePath`. The row is written even when the advisory never
144
+ reaches the agent: a full queue or a session that ended before its next
145
+ context call drops it as the `agent-advisory-dropped` degradation (`cap`
146
+ or `scope-retired`), so report the pair.
138
147
  **Session decisions** (#3873; each row is one lifecycle event, none is per
139
148
  occurrence in a loop): `session_handoff_slot` (`op`: `stashed`, `replaced`,
140
149
  `taken`, `key-mismatch-left` (once per stale slot), `forwarded`,
@@ -31,9 +31,12 @@ per-PR loop itself is `docs/pi-lens-merge-policy.md`.
31
31
  each candidate as folded into this PR (one `Closes #…` per folded issue) or
32
32
  not folded, with the reason (two hazards in one review, a maintainer decision,
33
33
  a blocked dependency, a different seam). The brief carries the candidate list
34
- and its decisions, and the PR body records them under `## Fold check`.
34
+ and its decisions, and the PR body records them under `### Fold check`.
35
35
  Planning precedes filing: a new issue is the answer for p2+ work no lane can
36
36
  carry, never for a p3 the lane could fold (history: `HISTORY.md`, 2026-10-20).
37
+ - A PR body's `### Class sweep` ends with one `Alignment:` line naming the
38
+ families of `docs/alignment-families.md` the change touches, or `none:
39
+ <reason>`; the body lint refuses a body without it.
37
40
  - The per-PR loop (review, verify, auto-merge on green), round routing, the
38
41
  merge gate and the Common mistakes table live in `docs/pi-lens-merge-policy.md`.
39
42
  - Read CI with `node scripts/ci-verdict.mjs <pr|sha>` (exact head, all pages).
@@ -82,7 +82,7 @@ does not ship.
82
82
  | A relaxed or rewritten existing assertion | Mutate the behaviour the test is named for; a rewrite that stays green is a deleted test (AGENTS "Issue and PR design contract"; principles §2) | The red on the new assertion, with that behaviour broken | #4390 (the eviction smoke's rewrite passed with root re-registration broken) |
83
83
  | A new decision branch on a session, lifecycle or delivery seam | Name its record, sink plus kind, and read it back through the real seam (`docs/invariants/session-telemetry.md` "Session, telemetry, and delivery"; shape 31) | The record literal, and the test that reads it back | #3873 (a fix that could not be shown to fire live), #3875 |
84
84
  | A new failure path, catch or silent return | One bounded record per distinct event, in a stream a monitor reads without asking (principles §1 "Every new failure path gets bounded observability"; shape 31) | The record literal and its sink, or `none:` with its reason | #4562 (a failed log write stayed silent), #4575 (a failed save left no trace) |
85
- | Every diff, every changed file, tests included | Read the whole diff file by file. Check each PR-body claim against the diff, and look in the body for proof before calling it missing (principles §3 "Reviewing and delegating") | The body line or transcript quoted beside a claim the diff cannot show, or the finding names the body line that lacks it | #4574 F2, #4582 F1; 3 of Greptile's 4 false positives were a transcript already in the body (#4572, #4573, #4577) |
85
+ | Every diff, every changed file, tests included | Read the whole diff file by file. Check each claim against the diff: PR-body lines, changelog fragments and user-doc sentences alike, with a probe when the claim is about behaviour. For each check the body cites as proof, name what it does not prove; a check cited for more than it covers is a finding. Look in the body for proof before calling it missing (principles §3 "Reviewing and delegating") | The body line or transcript quoted beside a claim the diff cannot show, or the finding names the body line that lacks it | #4574 F2, #4582 F1; 3 of Greptile's 4 false positives were a transcript already in the body (#4572, #4573, #4577); bots, not reviewers, caught a changelog overclaim (#5237) and a doc sentence the loader contradicts (#5252) |
86
86
 
87
87
  Rows 1, 2 and 4 are mechanical from #4585: `scripts/check-pr-body.mjs`
88
88
  (`lintDiffCompliance`, wired into both entry points) reds a body that omits
@@ -145,21 +145,21 @@ real seam. Check that every gate the diff adds is exercised through that path.
145
145
  the exception to the one-spot-check cap above.
146
146
  - Repeat the pattern and population sweeps. Check blast radius, bounded
147
147
  observability, changelog, commit, and PR-body requirements.
148
- - Re-run the PR's `## Class sweep` search yourself and widen it when the
148
+ - Re-run the PR's `### Class sweep` search yourself and widen it when the
149
149
  named shape is broader than the touched seam (#4273, #4268).
150
- - Read the `## Fold check` against the open issues and pull requests the PR's
150
+ - Read the `### Fold check` against the open issues and pull requests the PR's
151
151
  mechanism has: the lint checks the form (candidate, decision, reason), not
152
152
  that every candidate was found, so decide whether the section's search was
153
153
  wide enough and whether each `not folded` reason holds (#4711). Open each
154
154
  candidate's diff (`gh pr diff <n>`) or the files its issue names: a
155
155
  `not folded` line is a finding when the candidate edits the same hunk or
156
156
  symbol, or owns a rule this PR re-derives, and a member your own search finds
157
- that the `## Class sweep` missed is a finding too. The gates check form only
157
+ that the `### Class sweep` missed is a finding too. The gates check form only
158
158
  and the author writes these lines, so this read is the only judgment they
159
159
  get. Recurrence: #4713 wrote "shares no clients/ file" beside #4712, and the
160
160
  review then re-derived a `clients/analysis-root.ts` rule #4712 edits, while
161
161
  the class sweep missed a single-scan-root member.
162
- - On a bug-closing PR, check the `## Detection` lesson: the layer named under
162
+ - On a bug-closing PR, check the `### Detection` lesson: the layer named under
163
163
  `Should have been caught by:` must be one that would actually have caught
164
164
  the bug, and `Gap:` must be a real issue, test, or reason (#4288). Judge
165
165
  `Shape:` and `Enforcer:` too: the lint checks the catalog number and that the
@@ -380,6 +380,6 @@ Use short, active, plain prose.
380
380
 
381
381
  Apply this standard to PR and issue bodies, review comments, commit messages, documentation, and changelog entries. Lead with the outcome. Remove words that do no work. Use active voice and present tense. Use second person for instructions, and use the imperative for steps. Keep one idea per sentence, with about 20–25 words and no more than 30 words. Use consistent terminology and sentence-case headings. Define acronyms on first use. Prefer plain words over jargon. Avoid `please`, filler, noun piles, nested parentheticals, and em-dash chains. Use the Oxford comma.
382
382
 
383
- The mechanical rules are checked by `scripts/check-prose.mjs`. The checker ignores fenced code, inline code, URLs, quoted log lines, blockquotes, and tables. It blocks long sentences, filler, and title-case headings. It warns on passive voice. The CLI accepts a body file or standard input and supports `--json`.
383
+ The mechanical rules are checked by `scripts/check-prose.mjs`. The checker ignores fenced code, inline code, URLs, quoted log lines, blockquotes, and tables. It warns on long sentences, filler, and passive voice, and it blocks title-case headings (#5110). The CLI accepts a body file or standard input and supports `--json`.
384
384
 
385
385
  Reviewers judge clarity, terminology, active voice, sentence structure, and whether each list uses parallel grammar. Treat a mechanically clean result as necessary, not sufficient. Report prose that obscures the outcome or makes a user infer the action.
@@ -81,8 +81,11 @@ the brief gives.
81
81
  checkout the shell happens to sit in, and agent shells reset their working
82
82
  directory between calls. Never edit the main checkout: other lanes and the
83
83
  orchestrator read it, and its branch must not move under them.
84
- - **Teardown.** `rm` a symlinked `node_modules` before `git worktree remove`
85
- (`ls -ld node_modules` first; unlink the link, never `rm -r` it). Removing the worktree over the link follows it
84
+ - **Teardown.** Run `node scripts/worktree-remove.mjs <path>`: it unlinks a
85
+ symlinked `node_modules`, refuses a real directory, then runs `git worktree
86
+ remove` (#5111). By hand: `rm` a symlinked `node_modules` before `git
87
+ worktree remove` (`ls -ld node_modules` first; unlink the link, never `rm -r`
88
+ it). Removing the worktree over the link follows it
86
89
  and deletes the main checkout's install (#3173; the hook denies the removal
87
90
  and `AGENTS.md` "Commands and gates" says how `pr-worktree.mjs close` does
88
91
  it). A real `node_modules` directory is removed only after confirming the
@@ -233,6 +236,19 @@ before moving on; the plegma daemon's cgroup holds every worker's children
233
236
  long-lived worktree (#3180); reproduce with `--dryRunOnly`, never under a kill
234
237
  timeout.
235
238
 
239
+ Stop only the processes you started, by the PIDs you recorded: never `pkill`,
240
+ or a `pgrep -f` match, on a name another lane also runs. One worker killed
241
+ another lane's `lane:check` and one reviewer killed another lane's ast-grep
242
+ that way (2026-11-02). Never unlink, replace or re-point the linked
243
+ `node_modules` to get past a guard; report the refusal in the hand-back. The
244
+ orchestrator owns private installs (2026-11-02, #5199).
245
+
246
+ A test that copies scripts into a temp root resolves their imports from that
247
+ root upward. Under a `TMPDIR` inside the worktree it finds the worktree's
248
+ `node_modules` and passes, then fails on CI and on any outside `TMPDIR`. Run
249
+ such a test once with `TMPDIR` outside the worktree before the hand-back
250
+ (#5202 r2: `Cannot find module 'marked'`).
251
+
236
252
  A sandboxed worker may find the shared `.git` and the linked `node_modules`
237
253
  read-only and the network absent (a write-confined sandbox does this; the
238
254
  runner's own notes say which mode lifts it). Run Vitest as
@@ -251,7 +267,7 @@ Fold a review follow-up into the same PR when it shares the seam or files, is
251
267
  about one commit, and needs no maintainer decision. Contract-only folds (body,
252
268
  comments, wording) are trailing commits; small code folds carry a red-first
253
269
  test and are routed per principles §3 "Round routing". A MEDIUM or LOW that
254
- does not fold is an accepted residual: list it under `## Accepted residuals`,
270
+ does not fold is an accepted residual: list it under `### Accepted residuals`,
255
271
  named `p3` with its severity and live population, and file nothing. File only p2 or
256
272
  higher work that cannot ride the PR (a HIGH outside its scope, or a MEDIUM
257
273
  with a live population), as one consolidated issue per PR. The merge bar is in
@@ -83,10 +83,14 @@ The trailing ` [PILENS_CFG_NNNN]` marker is appended by
83
83
  `withConfigDiagnosticCode`, is idempotent, and is always last. Match on it:
84
84
 
85
85
  ```sh
86
- # every ignored-config warning this session, from the durable degradation log
86
+ # every config file this session that is unreadable, unparsable, or not a JSON object
87
87
  grep 'PILENS_CFG_0001' ~/.pi-lens/latency.log
88
88
 
89
- # suppress one code while keeping every other pi-lens warning
89
+ # every unknown key and rejected value this session (typos, wrong types);
90
+ # latency.log keeps only the first notice's code per file, so read extension.log
91
+ grep -E 'PILENS_CFG_000[45]' ~/.pi-lens/extension.log
92
+
93
+ # drop only the whole-file notices; typo notices keep PILENS_CFG_0004 and PILENS_CFG_0005
90
94
  pi ... 2>&1 | grep -v 'PILENS_CFG_0001'
91
95
  ```
92
96
 
@@ -99,11 +103,11 @@ this policy explicitly reserves the right to change.
99
103
 
100
104
  | Code | Meaning | Emitter |
101
105
  | --- | --- | --- |
102
- | `PILENS_CFG_0001` | A config file exists but could not be read or parsed, so it is ignored. | `warnIgnoredConfigOnce` (`clients/config-warn.ts`), the single choke point behind the LSP, global, and project config loaders. |
106
+ | `PILENS_CFG_0001` | A config file exists but is unreadable, unparsable, or not a JSON object, so it is ignored. | `warnIgnoredConfigOnce` (`clients/config-warn.ts`), the single choke point behind the LSP, global, and project config loaders, and its default code for a read or parse failure. |
103
107
  | `PILENS_CFG_0002` | A deprecated config **key** was accepted inside its deprecation window. | `deprecationRecords` (`clients/config-resolve.ts`), one record per `(file, key)`, delivered by `reportPiLensConfigRecords` (#2426). |
104
108
  | `PILENS_CFG_0003` | A deprecated config **file location** was read inside its window. | Same producer and same delivery path as `PILENS_CFG_0002`. |
105
- | `PILENS_CFG_0004` | A config field no schema property claims was dropped. | `validate()` (`clients/config-core/normalize.ts`) produces the record; `reportPiLensConfigRecords` (`clients/config-resolve.ts`) delivers it through `warnIgnoredConfigOnce` (#2426). |
106
- | `PILENS_CFG_0005` | A config field's value did not match its schema and was dropped. One FIELD; the rest of the file is in effect. | Same producer and same delivery path as `PILENS_CFG_0004`. |
109
+ | `PILENS_CFG_0004` | A config field no schema property claims was dropped. | `validate()` (`clients/config-core/normalize.ts`) produces the record; `reportPiLensConfigRecords` (`clients/config-resolve.ts`) delivers it through `warnIgnoredConfigOnce` (#2426). The global and project loaders' own unknown-key scans pass the same code (`clients/lens-config.ts`, `clients/project-lens-config.ts`). |
110
+ | `PILENS_CFG_0005` | A config field's value did not match its schema, or one member of a list field was rejected by its id check (`dispatch.disabledRunners`, `lsp.disabledServers`). The rejected field or member is dropped; the rest of the file stays in effect. | Same producer and same delivery path as `PILENS_CFG_0004`, plus the loaders' own value checks (`clients/lens-config.ts`, `clients/project-lens-config.ts`, `clients/tool-config.ts`, `clients/lens-flag-registry.ts`), and the `dispatch.disabledRunners` and `lsp.disabledServers` id checks (`clients/dispatch/disabled-runners.ts`, `clients/lsp/config.ts`). |
107
111
  | `PILENS_CFG_0006` | A config key that would modify an object's prototype (`__proto__`, `constructor`, `prototype`) was refused. | Both halves of the config core, through the shared policy in `clients/config-core/safe-object.ts`. |
108
112
  | `PILENS_CFG_0007` | Further config notices were suppressed by a bound, and this one carries the count — the WHOLE count, including anything an earlier bound in the same pipeline dropped. Nothing about the config is wrong; the notice list was truncated. | `MigrationRecordCollector.finalize` (`clients/config-core/records.ts`) — the ONE producer, reached through `finalizeRecords` by every record list: the shared resolution, the global loader's unknown-key scan, the project loader's unknown-key scan, and its legacy-document enumeration. Rendered with neutral prose and recorded under the `config-notice-suppressed` degradation kind, never `config-ignored`. |
109
113
  | `PILENS_CFG_0008` | Resolving a config failed internally, so the WHOLE file was ignored and pi-lens ran on defaults. | The two guards under the pipeline: `resolveConfig` (`clients/config-core/resolve.ts`) and the global loader's post-parse catch (`clients/lens-config.ts`). Carries the error class only, never its message. |
@@ -375,7 +379,7 @@ are part of the contract, so the predicate is named here** (`refusalMatches` in
375
379
 
376
380
  Everything else stays a warning and the tool runs, exactly as it did before: a
377
381
  misspelled mode name, an abbreviation (`max`), a substring or reverse containment
378
- (`files` for `maxLspFiles`, `file` for `path`), a leading or middle word
382
+ (`files` for `maxLspFiles`, `pth` for `path`), a leading or middle word
379
383
  (`sourcePath` is not `source`), a key whose qualifier retargets the head noun
380
384
  (`maxFiles`). Such keys still get the `did you mean` hint, except that a
381
385
  retargeted head noun is never the hint (`maxFiles` gets none, `cwdPath` gets
@@ -391,6 +395,52 @@ JSON-RPC `-32602` error; `arguments` absent, `null` or `[]` means no arguments.
391
395
  pass extra keys today would break, so it needs a major, through the removal
392
396
  checklist in section 4.
393
397
 
398
+ ### The single-file tool parameter is `path`
399
+
400
+ Every pi-lens tool that acts on one named file takes it as **`path`** (#5041).
401
+ That is the canonical spelling: new tools declare it, and the description a
402
+ model reads names it. It is also what keeps a call from being answered for the
403
+ wrong scope — a tool that only declares an older name refuses or ignores the
404
+ canonical one, and an ignored file parameter leaves the call running on its
405
+ default scope, whose answer then reads as if it were about the named file.
406
+
407
+ The MCP tools keep accepting **`file`**, and `lens_diagnostic_mark` keeps
408
+ accepting **`filePath`**, as declared aliases of `path`, so no caller written
409
+ against an older spelling breaks. A call may send any one of them; a call that
410
+ sends two spellings naming different files is refused rather than guessed at.
411
+ Adding a fourth spelling, or dropping one of these, changes this contract
412
+ through section 4.
413
+
414
+ ### The MCP tool result block contract
415
+
416
+ An MCP tool result carries a `content` array of text blocks. For an **opted-in
417
+ JSON cell** (`module_report` `*-json`, `project_report` `view: "json"`, and
418
+ `lsp_navigation`, whose envelope is always JSON) the contract is:
419
+
420
+ - **block 0 is the payload.** It is one machine-parsed document; a stale-build
421
+ advisory or an ignored-arguments note never joins it.
422
+ - **later text blocks are annotations.** The `warmCodeStale: true` advisory and
423
+ the `Ignored unknown argument(s)` note ride their own trailing blocks, with
424
+ the ignored-arguments note ahead of the advisory when both are present.
425
+ - **the contract footer is stamped on the last text block.** `stripContractFooter`
426
+ (`tools/render-compact.ts`) is the single owner of `CONTRACT_FOOTER_TAIL_RE`;
427
+ a reader strips it before parsing block 0. The function is a no-op when no
428
+ footer is at the tail, so a payload whose footer rides another block is
429
+ returned byte-identical.
430
+
431
+ The cell opts in through a `jsonCell` marker in `details`; `stripResultDetails`
432
+ removes `details` before the wire, so the marker never leaks. Text cells keep
433
+ the single-block shape: the advisory is appended to the payload's own block.
434
+
435
+ The delivered text (all blocks joined, footer included) stays inside
436
+ `MAX_RESULT_BYTES`; the payload budget reserves the annotation bytes and the
437
+ block separators. A **truncated** JSON cell is not parseable by design: its
438
+ footer reports `truncated=true` and the advisory still rides a later block.
439
+
440
+ Observability: the `warmCodeStale` marker is the record; this contract adds no
441
+ telemetry. A display-only client that renders block 0 alone hides the advisory;
442
+ that is an accepted residual.
443
+
394
444
  ## 6. File I/O Lifecycle Bridge (v2)
395
445
 
396
446
  `PiLensIOBridge` is public API from day one ([RFC 3654](rfcs/3654-unified-io-bridge-v2.md)).
@@ -406,7 +456,7 @@ The compatibility policy and migration path from legacy v1 symbols are documente
406
456
  | 2. Append-only `PILENS_CFG_*` codes | `CONFIG_DIAGNOSTIC_CODES` | `tests/clients/config-diagnostic-codes.test.ts` |
407
457
  | 3. Reserved `$schema` identity anchor | `CONFIG_SCHEMA_ID`, `CONFIG_SCHEMA_ANCHOR_KEY` | `assertSchemaIdentityAnchor` |
408
458
  | 4. Deprecation window + removal checklist | `DEPRECATED_CONFIG_SURFACES` | `tests/clients/config-deprecation-registry.test.ts` |
409
- | 5. Config core: tiers, deny precedence, ProcessSpec trust | `clients/config-core/` | `tests/clients/config-core/*.test.ts`, `tests/config/config-core-schema-stability.test.ts` |
459
+ | 5. Config core: tiers, deny precedence, ProcessSpec trust | `clients/config-core/` | `tests/clients/config-core/*.test.ts` |
410
460
 
411
461
  ## Related
412
462
 
@@ -84,7 +84,7 @@ PR's packed tarball (#2700, the check #2587 was missing). `attw`
84
84
  | mcp-diagnostics-full | `lens_diagnostics` full mode answers on a fixture repo | mcp-stdio | `tools/call` `pilens_diagnostics` with `mode` `full` and `refreshRunners` `cheap`, POLLED | text carries a `Summary (N files diagnosed this session)` line with N at least 1 | tool result text | new — `tests/clients` covers the handler, nothing covers it through a packaged install | — |
85
85
  | mcp-turn-end | the turn-end pipeline runs over the turn's files and returns an advisory | mcp-stdio | `tools/call` `pilens_turn_end` with the fixture file | text carries `Turn-end over N file(s).` with N at least 1 | tool result text | new — `scripts/smoke-availability-lifecycle.mjs` covers lifecycle availability, not the packaged turn-end path | #1605 lane 2 (availability-lifecycle): overlaps the turn-end half; #1605 asserts latch recovery, this row asserts the packaged turn-end path answers at all |
86
86
  | mcp-lsp-navigation | LSP navigation answers on a fixture | mcp-stdio | `tools/call` `pilens_lsp_navigation` with operation `documentSymbol` and the fixture path | result is not an error and names the fixture's exported `releaseQaFixtureSymbol` | tool result text | `scripts/smoke-tools.mjs --lsp` is the per-server sibling; this row is the packaged-path variant | #1829 lane 2/3 (gated real-binary + the rotating install lane): #1829 pins each tool's own contract, this row pins that the packaged LSP path answers |
87
- | config-provenance | a project config is LOADED and its provenance is reportable | mcp-stdio | `tools/call` `pilens_effective_config` with the fixture file | result names the fixture's `.pi-lens.json` as a contributing document | tool result text | new — `tests/config/pi-lens-config-schema.test.ts` covers the schema, not the packaged load | — |
87
+ | config-provenance | a project config is LOADED and its provenance is reportable | mcp-stdio | `tools/call` `pilens_effective_config` with the fixture file | result names the fixture's `.pi-lens.json` as a contributing document | tool result text | `tests/clients/lsp/resolved-config.test.ts` compares the published schema with `PI_LENS_CONFIG_SCHEMA`, and `tests/clients/public-surface-drift.test.ts` reads it; no test covers the packaged config load | — |
88
88
  | degradation-visible | a silently-ignored input is RECORDED as a degradation instead of vanishing | mcp-stdio | `tools/call` `pilens_health` with the fixture's project-tier `lsp.enabled` (a global-only setting) loaded | health text carries a `config-ignored` degradation line naming the fixture's `.pi-lens.json` | health tool result text | `clients/degradation-ledger.ts` is the reused machinery; no smoke asserts it end to end | #1605 lane 2 (availability-lifecycle): the degradation-recorded half; #1605 additionally asserts RECOVERY, which this row does not |
89
89
  | global-config-location | the agent-dir global config file supplies the global tier when it exists and the legacy default does not | mcp-stdio | `tools/call` `pilens_effective_config` on a real pi-lens MCP server whose env sets `PI_CODING_AGENT_DIR` at a scratch dir holding `extensions/pi-lens.json` | the tool result NAMES the agent-dir file as a contributing config document (the `pi-coding-agent-dir` winner) | tool result text | `tests/clients/global-config-location.test.ts` covers the resolution in-process; no smoke drives the packaged MCP path with the env set | — |
90
90
  | config-shadow-record | a lower-precedence global config file beside the winner is recorded once per session | mcp-stdio | `tools/call` `pilens_effective_config` then `pilens_health` twice, on a real MCP server whose env has BOTH `~/.pi-lens/config.json` and `PI_CODING_AGENT_DIR/extensions/pi-lens.json` present | health carries a `config-location-shadowed: 1` line naming the shadowed agent-dir file, and the count stays 1 on a second health read after a further config load | the two health tool result texts | `clients/degradation-ledger.ts` `recordDegradationOnce` and `tests/clients/global-config-location.test.ts`; no smoke asserts the record end to end | #1605 lane 2 (availability-lifecycle): the degradation-recorded half, as `degradation-visible`; this row additionally pins the once-per-session count across two loads |
@@ -155,7 +155,7 @@ newest-in-range lane reads it, bounded above so `"*"` can never mean
155
155
  matrix has passed on. A newer host enters the window in ONE change: run this
156
156
  matrix on it, add it to that test's verified list, and move the workflow's
157
157
  ceiling together. P1 is one verified host per minor line from 0.86 onward;
158
- 0.86–1.4 are in-window, and every minor line below 0.86 falls outside the
158
+ 0.86–1.5 are in-window, and every minor line below 0.86 falls outside the
159
159
  window entirely, so none needs a dedicated host. A ceiling past an unrun
160
160
  minor still claims that minor, so the verified-minor ratchet names the admitted
161
161
  lines explicitly.
@@ -171,9 +171,11 @@ the old hosts; a real 0.80.10 session delivered the staged guidance at
171
171
 
172
172
  ### Verified hosts
173
173
 
174
- The certified policy is `>=0.86.1 <1.5.0`, and this table is the whole verified
174
+ The certified policy is `>=0.86.1 <1.6.0`, and this table is the whole verified
175
175
  set: `tests/packaging.test.ts` fails when it and `PI_HOST_SUPPORTED_RANGE`
176
- disagree. Each listed minor line has a release-QA witness; the workflow ceiling
176
+ disagree. Each listed minor line through 1.4 has a release-QA witness; 1.5 was
177
+ certified by maintainer decision on 2026-11-02, with its witness blocked by
178
+ the lane npm guard. The workflow ceiling
177
179
  and `tests/packaging.test.ts` list are updated together.
178
180
 
179
181
  | host | date | pi-lens commit | result |
@@ -186,6 +188,7 @@ and `tests/packaging.test.ts` list are updated together.
186
188
  | 1.2.0 | 2026-10-16 | 9400454891d5a1beb0a4d2d9452dece276e22e71 | 15 pass / 1 skipped (git-install-loads) |
187
189
  | 1.3.0 | 2026-10-16 | 9400454891d5a1beb0a4d2d9452dece276e22e71 | 15 pass / 1 skipped (git-install-loads) |
188
190
  | 1.4.0 | 2026-10-22 | 75a1a3c893ed0ac44a3081dd3d475c1e72349099 | 15 pass / 1 skipped (git-install-loads) |
191
+ | 1.5.0 | 2026-11-02 | e5017388815d476e783fc850b3d05c6ce98bd85e | Maintainer certification; release QA blocked by npm guard (17 untested) |
189
192
 
190
193
  Re-run any row with `node scripts/release-qa.mjs --pi <host>` at the listed commit.
191
194
 
@@ -502,6 +502,16 @@
502
502
  "x-stability": "stable"
503
503
  },
504
504
  "dispatch": {
505
+ "type": "object",
506
+ "additionalProperties": true,
507
+ "properties": {
508
+ "disabledRunners": {
509
+ "type": "array",
510
+ "items": { "type": "string", "x-stability": "experimental" },
511
+ "x-deny": "array-union",
512
+ "x-stability": "experimental"
513
+ }
514
+ },
505
515
  "x-stability": "stable"
506
516
  },
507
517
  "widget": {
@@ -546,8 +556,17 @@
546
556
  "additionalProperties": true,
547
557
  "properties": {
548
558
  "threshold": { "type": "number", "x-stability": "experimental" },
549
- "disable": { "x-stability": "experimental" },
550
- "select": { "x-stability": "experimental" },
559
+ "disable": {
560
+ "type": "array",
561
+ "items": { "type": "string", "x-stability": "experimental" },
562
+ "x-deny": "array-union",
563
+ "x-stability": "experimental"
564
+ },
565
+ "select": {
566
+ "type": "array",
567
+ "items": { "type": "string", "x-stability": "experimental" },
568
+ "x-stability": "experimental"
569
+ },
551
570
  "ignorePaths": {
552
571
  "type": "array",
553
572
  "items": { "type": "string", "minLength": 1, "x-stability": "experimental" },
@@ -6,7 +6,7 @@ server's `initialize` handshake. Generated by `node scripts/server-capabilities.
6
6
  absent on the generating host are listed under *Unavailable* — run in a
7
7
  provisioned environment (the nightly) to capture those rows.
8
8
 
9
- _Last generated: 2026-10-27 on linux; 41 servers captured, 9 unavailable._
9
+ _Last generated: 2026-11-04 on linux; 42 servers captured, 9 unavailable._
10
10
 
11
11
  ## Diagnostic mode + navigation/edit operations
12
12
 
@@ -28,6 +28,7 @@ Legend: ✓ advertised, · not. **mode** = document diagnostics (`pull` = `textD
28
28
  | docker-official | push-only | · | · | ✓ | · | · | · | ✓ | · | ✓ | · | ✓ | ✓ | · | · | · | 1 |
29
29
  | emmylua | pull | · | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | · | · | · | 4 |
30
30
  | expert | push-only | · | save | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | 2 |
31
+ | fallow | push-only | · | · | · | · | · | · | ✓ | · | · | · | ✓ | · | · | · | · | 0 |
31
32
  | fish | push-only | · | save+text | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 23 |
32
33
  | fsharp | push-only | · | save+text | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | 0 |
33
34
  | gleam | push-only | · | save | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | · | · | 0 |
@@ -75,6 +76,7 @@ surface, including providers pi-lens does not yet consume.
75
76
  - **docker-official**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, inlayHintProvider, inlineCompletionProvider, renameProvider, semanticTokensProvider, textDocumentSync
76
77
  - **emmylua**: codeActionProvider, definitionProvider, diagnosticProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, referencesProvider, textDocumentSync, workspaceSymbolProvider
77
78
  - **expert**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, declarationProvider, definitionProvider, documentFormattingProvider, documentSymbolProvider, executeCommandProvider, experimental, foldingRangeProvider, hoverProvider, implementationProvider, referencesProvider, selectionRangeProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
79
+ - **fallow**: codeActionProvider, codeLensProvider, hoverProvider, positionEncoding, textDocumentSync
78
80
  - **fish**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
79
81
  - **fsharp**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspaceSymbolProvider
80
82
  - **gleam**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, referencesProvider, renameProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace