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.
- package/CHANGELOG-USER.md +31 -0
- package/CHANGELOG.md +327 -0
- package/README.md +13 -2
- package/config/dependency-cruiser-eager-allowlist.json +1 -1
- package/config/markdownlint/run-no-fix.mjs +36 -0
- package/dist/{chunk-4LM3VAZH.js → chunk-2VZ3VN3N.js} +2 -2
- package/dist/{chunk-PUZ3E2J4.js → chunk-3HTZDY3C.js} +8 -6
- package/dist/{chunk-RORGS5II.js → chunk-3NPWO5UO.js} +7 -13
- package/dist/{chunk-MNJIXFX4.js → chunk-47UCC4MM.js} +1 -1
- package/dist/chunk-4ENEJHF4.js +198 -0
- package/dist/chunk-5GEYJJHG.js +22 -0
- package/dist/{chunk-U6VN4NVL.js → chunk-5YSEQHJN.js} +3 -3
- package/dist/{chunk-6IR3ZYIB.js → chunk-6GPB3JLL.js} +3 -3
- package/dist/{chunk-MB6PXBUA.js → chunk-7R5GZIA6.js} +7 -15
- package/dist/{chunk-DH5JPM3K.js → chunk-7UTSNTWM.js} +10 -9
- package/dist/{chunk-24BILSZW.js → chunk-7YTRG6YW.js} +2 -2
- package/dist/{chunk-KW5JQPO5.js → chunk-AACN5GNE.js} +2 -2
- package/dist/{chunk-PKES3ISE.js → chunk-ACRJ2GZ5.js} +2 -2
- package/dist/{chunk-4ZYJHQMB.js → chunk-C3YRO3EU.js} +10 -12
- package/dist/{chunk-PQJFG24Z.js → chunk-CB7PEVOJ.js} +1300 -946
- package/dist/{chunk-ABPKUVA4.js → chunk-CDFJF5YD.js} +1 -1
- package/dist/{chunk-T7A2HK2B.js → chunk-CJS6WE66.js} +17 -18
- package/dist/{chunk-3YY7IXIL.js → chunk-CM6BDY4E.js} +14 -60
- package/dist/{chunk-RZOXUSPC.js → chunk-CZCAZVTD.js} +16 -2
- package/dist/chunk-DGKFWQK4.js +23 -0
- package/dist/{chunk-NA7SEXHE.js → chunk-E65WJVI5.js} +7 -9
- package/dist/{chunk-2TF6RXWB.js → chunk-EKNYSXFB.js} +8 -10
- package/dist/{chunk-RRV3FNNM.js → chunk-EY6LY2HO.js} +27 -30
- package/dist/{chunk-LBLBAFG3.js → chunk-F6BEQWAK.js} +17 -5
- package/dist/{chunk-4L36HG27.js → chunk-FGNSESAC.js} +12 -14
- package/dist/{chunk-3FRLWYBG.js → chunk-FRUBVFXV.js} +39 -42
- package/dist/{chunk-FB5SCCPT.js → chunk-G22UNQID.js} +14 -15
- package/dist/{chunk-LV4UMYVH.js → chunk-GQTQUNCG.js} +26 -27
- package/dist/{chunk-E7HJ56Y7.js → chunk-H3BVMK47.js} +64 -73
- package/dist/chunk-H6FLQ5NW.js +28 -0
- package/dist/{chunk-QHSNL7B2.js → chunk-HEA3EM23.js} +15 -19
- package/dist/{chunk-AWDSEDER.js → chunk-HSOBIN22.js} +2 -2
- package/dist/{chunk-EAOK7MIZ.js → chunk-HYSKJMZK.js} +17 -4
- package/dist/{chunk-VUZWQ7UG.js → chunk-IICERRFF.js} +46 -72
- package/dist/{chunk-OXOI55RU.js → chunk-IILEH3ZC.js} +8 -10
- package/dist/{chunk-ZKXQKGWZ.js → chunk-J3Q2NYJR.js} +4 -3
- package/dist/{chunk-YHC2O2WO.js → chunk-JUZ67QZQ.js} +20 -9
- package/dist/chunk-KR5VGMVT.js +25 -0
- package/dist/{chunk-F7K5IBZG.js → chunk-KV6GQOGN.js} +41 -44
- package/dist/{chunk-SNDXCFRS.js → chunk-KXMJLOZF.js} +25 -23
- package/dist/{chunk-CB4WHS4H.js → chunk-L4Y3ROKQ.js} +3 -3
- package/dist/{chunk-3F6BMY53.js → chunk-L6WBJGQS.js} +1 -1
- package/dist/{chunk-MPKRJBPK.js → chunk-L7O774U7.js} +30 -32
- package/dist/{chunk-URCQWAQ4.js → chunk-LAHHGNAY.js} +21 -21
- package/dist/{chunk-V63BC55Q.js → chunk-LT62P654.js} +1 -1
- package/dist/{chunk-ZMAUPOMG.js → chunk-LWOM6LVS.js} +34 -34
- package/dist/{chunk-HO6LWE2E.js → chunk-MKPDIAZH.js} +21 -1
- package/dist/{chunk-2PHMIAKO.js → chunk-MN635QYA.js} +3 -4
- package/dist/{chunk-KDX35VXP.js → chunk-MQ4PPCJB.js} +166 -149
- package/dist/{chunk-QOE342SU.js → chunk-MRLH4MYU.js} +2 -2
- package/dist/{chunk-CE6VMBCB.js → chunk-N56BNAA6.js} +20 -21
- package/dist/{chunk-L3CMBQMH.js → chunk-N5CEGQPG.js} +14 -17
- package/dist/{chunk-7E2563GA.js → chunk-NCLO6E6N.js} +13 -33
- package/dist/{chunk-J6JP25XU.js → chunk-NL5LSKVD.js} +4 -3
- package/dist/{chunk-U7BD2QL7.js → chunk-NMUSOZ2D.js} +10 -12
- package/dist/{chunk-BZARLRJW.js → chunk-NOWH2VA2.js} +8 -33
- package/dist/{chunk-U2SDMG7C.js → chunk-NUSXS6YB.js} +6 -5
- package/dist/{chunk-ZJTT47IG.js → chunk-OSEKJEUU.js} +2 -2
- package/dist/{chunk-FZKFVUEC.js → chunk-OUYAUXAT.js} +647 -355
- package/dist/{chunk-ZE3KXHS7.js → chunk-PBZNYHMM.js} +84 -4
- package/dist/{chunk-U5HPROLA.js → chunk-PIIUNJIT.js} +2 -4
- package/dist/chunk-PKLB2XJL.js +8 -0
- package/dist/{chunk-RC2Z6K47.js → chunk-PRHYIA6X.js} +15 -6
- package/dist/{chunk-RQS4QQSD.js → chunk-PXQ45SGD.js} +2 -2
- package/dist/chunk-Q6JQKWPK.js +25 -0
- package/dist/{chunk-F6X3YJWD.js → chunk-QB7T2PHK.js} +2 -2
- package/dist/{chunk-TIQJPRDD.js → chunk-QGITU23N.js} +3 -2
- package/dist/chunk-QJJKOHLH.js +57 -0
- package/dist/{chunk-4LOE5R5P.js → chunk-QP33NKYC.js} +18 -15
- package/dist/{chunk-N5WSK2K7.js → chunk-QVBOXT3L.js} +12 -17
- package/dist/{chunk-DPGEAHZT.js → chunk-RNJFRXEN.js} +10 -18
- package/dist/{chunk-EKWX4WD3.js → chunk-RNXOWDM6.js} +10 -10
- package/dist/{chunk-O4BJFESU.js → chunk-RTFMDIKV.js} +1 -1
- package/dist/{chunk-LS3QJRUB.js → chunk-SIQHOB6P.js} +11 -13
- package/dist/{chunk-3K2F6UDZ.js → chunk-SLSMJPEF.js} +43 -42
- package/dist/chunk-T5QSLSMM.js +50 -0
- package/dist/chunk-TGQDAG4B.js +88 -0
- package/dist/{chunk-4YHYPW2G.js → chunk-THYHUIDR.js} +44 -13
- package/dist/{chunk-YVHBNSME.js → chunk-TMNUTMT5.js} +1099 -1100
- package/dist/{chunk-WDBICWH3.js → chunk-TOE2RRCS.js} +1 -1
- package/dist/chunk-TYHPVE5H.js +25 -0
- package/dist/chunk-UAKO2M6B.js +73 -0
- package/dist/chunk-UC5AXW5Z.js +20 -0
- package/dist/chunk-UTJP6WOS.js +28 -0
- package/dist/{chunk-DQZFQSR5.js → chunk-UXTQ3QPD.js} +4 -4
- package/dist/chunk-UYXV5NIS.js +20 -0
- package/dist/{chunk-KKCK636N.js → chunk-V2WDBOLZ.js} +10 -12
- package/dist/{chunk-PR6PO3ES.js → chunk-V67D6TMU.js} +22 -20
- package/dist/{chunk-VSFLRN5Y.js → chunk-VCRVNLE7.js} +135 -2
- package/dist/{chunk-CPSR3AVL.js → chunk-VO4JFPTV.js} +2 -2
- package/dist/{chunk-XT2HTCJ5.js → chunk-VWLSU3XV.js} +6 -5
- package/dist/{chunk-WME2OQST.js → chunk-W5E72HJA.js} +66 -24
- package/dist/{chunk-LLS45EWB.js → chunk-W7TY6HYX.js} +6 -8
- package/dist/{chunk-CCV2EU7T.js → chunk-WSSLVMDA.js} +12 -13
- package/dist/{chunk-YISME6ON.js → chunk-WTB4GKMH.js} +10 -1
- package/dist/{chunk-KPPJTH44.js → chunk-X5BJ3G2P.js} +64 -35
- package/dist/{chunk-JMEKXFOL.js → chunk-XKFO2SZV.js} +39 -34
- package/dist/{chunk-HR3OJ3TH.js → chunk-XLAI7UYY.js} +84 -31
- package/dist/{chunk-H7OR7DFZ.js → chunk-XO756WE5.js} +53 -37
- package/dist/{chunk-F5Z6URKM.js → chunk-XVB3Q2PG.js} +2 -4
- package/dist/{chunk-R5MOQM2H.js → chunk-YOXCCJDF.js} +607 -366
- package/dist/{chunk-ZGSJDWQU.js → chunk-ZCQBNPRH.js} +2 -2
- package/dist/chunk-ZD4KVFXI.js +234 -0
- package/dist/{chunk-WGRJOXED.js → chunk-ZDMFGACN.js} +1295 -966
- package/dist/{chunk-OSTKYB55.js → chunk-ZMMHHXSW.js} +1 -1
- package/dist/{chunk-75GAYVNO.js → chunk-ZPM7ZIFL.js} +6 -6
- package/dist/{chunk-LUBPZN36.js → chunk-ZVCDHYWZ.js} +9 -11
- package/dist/{chunk-Y7F7IEE3.js → chunk-ZZN74OGD.js} +102 -7
- package/dist/{chunk-L5JYIU47.js → chunk-ZZSJAR76.js} +39 -20
- package/dist/index.js +10933 -8644
- package/dist/mcp/analyze-cli.js +12 -17
- package/dist/mcp/cli.js +43 -42
- package/dist/mcp/server.js +3073 -1147
- package/dist/mcp/worker.js +61 -61
- package/dist/probes/installer.js +18 -19
- package/docs/adr/0003-git-guard-latch-writer.md +11 -6
- package/docs/agent-tools.md +58 -16
- package/docs/alignment-families.md +29 -0
- package/docs/analysisall.md +1 -1
- package/docs/ast-grep_rules_catalog.md +6 -4
- package/docs/ci-bot-pr-checks.md +128 -0
- package/docs/configuration.md +150 -12
- package/docs/defect-shapes.md +107 -15
- package/docs/engineering-principles.md +27 -2
- package/docs/environment-variables.md +18 -1
- package/docs/features.md +14 -7
- package/docs/globalconfig.md +11 -3
- package/docs/invariants/git-guard-host.md +7 -3
- package/docs/invariants/language-config.md +15 -4
- package/docs/invariants/lsp-trust-exec.md +25 -4
- package/docs/invariants/paths-os.md +4 -2
- package/docs/invariants/session-telemetry.md +2 -2
- package/docs/language-coverage.md +1 -0
- package/docs/lsp-capability-matrix.md +167 -65
- package/docs/lsp-idle-eviction.md +4 -1
- package/docs/merge-queue-rollout.md +10 -8
- package/docs/module-report-read-symbol.md +34 -23
- package/docs/pi-lens-fixer.md +34 -17
- package/docs/pi-lens-investigator.md +3 -0
- package/docs/pi-lens-merge-policy.md +34 -17
- package/docs/pi-lens-monitor.md +9 -0
- package/docs/pi-lens-orchestration.md +4 -1
- package/docs/pi-lens-reviewer.md +6 -6
- package/docs/pi-lens-subagent.md +19 -3
- package/docs/public-api-stability.md +57 -7
- package/docs/release-qa-baseline.md +7 -4
- package/docs/schema/pi-lens-config-v1.json +21 -2
- package/docs/servercapabilities.md +3 -1
- package/docs/settings.md +11 -7
- package/docs/word-index.md +20 -7
- package/package.json +11 -4
- package/rules/ast-grep-rules/rule-tests/no-accumulating-spread-js-test.yml +37 -0
- package/rules/ast-grep-rules/rule-tests/ts-redundant-filter-map-test.yml +12 -1
- package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-js-test.yml +12 -0
- package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-test.yml +25 -0
- package/rules/ast-grep-rules/rules/no-accumulating-spread-js.yml +49 -1
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +1 -2
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +1 -2
- package/rules/ast-grep-rules/rules/ts-redundant-filter-map.yml +9 -1
- package/rules/ast-grep-rules/rules-disabled/filter-then-map-js.yml +17 -0
- package/rules/ast-grep-rules/rules-disabled/filter-then-map.yml +36 -0
- package/rules/ast-grep-rules/self-scan-baseline.json +1 -1
- package/scripts/download-grammars.js +3 -2
- package/skills/pi-lens-lsp-navigation/SKILL.md +5 -1
- package/dist/chunk-46TNM7XZ.js +0 -88
- package/dist/chunk-72OKUXSD.js +0 -31
- package/dist/chunk-7GLOLOSH.js +0 -57
- package/dist/chunk-AKUUMGD5.js +0 -26
- package/dist/chunk-ASUXV767.js +0 -22
- package/dist/chunk-CTADOKYM.js +0 -25
- package/dist/chunk-GNSIWBAT.js +0 -106
- package/dist/chunk-HWDAVBFU.js +0 -49
- package/dist/chunk-JJ2RRESP.js +0 -58
- package/dist/chunk-KXF5R4UN.js +0 -48
- package/dist/chunk-LSC3VADM.js +0 -23
- package/dist/chunk-OE5ZBP7F.js +0 -443
- package/dist/chunk-SHLDT3OI.js +0 -27
- package/dist/chunk-UF7RTZSO.js +0 -27
- package/dist/chunk-W4WP2ERB.js +0 -30
- package/dist/chunk-YES5CACN.js +0 -73
- package/dist/chunk-Z2XAOKHK.js +0 -136
package/docs/pi-lens-fixer.md
CHANGED
|
@@ -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
|
|
45
|
-
inputs, states, orderings, and platforms; a space with two
|
|
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
|
|
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
|
-
|
|
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
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
`##
|
|
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
|
-
|
|
258
|
-
`#N
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
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
|
|
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
|
|
23
|
-
|
|
24
|
-
`##
|
|
25
|
-
|
|
26
|
-
|
|
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
|
|
34
|
-
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
370
|
-
|
|
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,
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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 |
|
package/docs/pi-lens-monitor.md
CHANGED
|
@@ -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
|
|
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).
|
package/docs/pi-lens-reviewer.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
package/docs/pi-lens-subagent.md
CHANGED
|
@@ -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.** `
|
|
85
|
-
|
|
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
|
|
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
|
|
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
|
-
#
|
|
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
|
|
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
|
|
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`, `
|
|
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
|
|
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 |
|
|
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.
|
|
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.
|
|
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;
|
|
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": {
|
|
550
|
-
|
|
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-
|
|
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
|