pi-lens 4.4.3 → 4.4.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +721 -0
- package/README.md +25 -3
- package/config/dependency-cruiser-eager-allowlist.json +1 -0
- package/dist/chunk-22Y2BM7H.js +23 -0
- package/dist/{chunk-WU567RSC.js → chunk-27VWVB23.js} +16 -14
- package/dist/{chunk-FLKWCIZH.js → chunk-2FYKETQJ.js} +10 -6
- package/dist/{chunk-MQLUAEOC.js → chunk-2LDMXL2M.js} +2 -2
- package/dist/{chunk-YSZNHOBY.js → chunk-2SDHYHHO.js} +17 -17
- package/dist/chunk-2Y6OJRSI.js +38 -0
- package/dist/chunk-3SNDVPOR.js +507 -0
- package/dist/{chunk-EJIUXPBX.js → chunk-3WCEHYOI.js} +1 -1
- package/dist/chunk-44X7VIKR.js +73 -0
- package/dist/{chunk-Q7DUK4LX.js → chunk-4FHUGDKU.js} +16 -14
- package/dist/{chunk-H6MF6EVN.js → chunk-4ODSZ35Z.js} +1498 -534
- package/dist/{chunk-ZGDGW2V3.js → chunk-4U7GDSZQ.js} +2 -2
- package/dist/chunk-54NIOJJZ.js +25 -0
- package/dist/{chunk-ZWFS3OEF.js → chunk-5DKE4HGX.js} +38 -37
- package/dist/{chunk-VRZP76YM.js → chunk-5LRUKYFA.js} +34 -4
- package/dist/{chunk-QOBUHWHX.js → chunk-63NMUNYP.js} +12 -16
- package/dist/{chunk-VWCXW2E7.js → chunk-6XSESGWD.js} +13 -6
- package/dist/{chunk-QGQ5CCCG.js → chunk-72J27ICO.js} +2 -3
- package/dist/{chunk-CSHFH5IN.js → chunk-7FLRUH6B.js} +1 -1
- package/dist/chunk-7IYC4ENJ.js +297 -0
- package/dist/chunk-7WWQAW5P.js +30 -0
- package/dist/{chunk-EU63SDCG.js → chunk-7ZS7MC24.js} +885 -451
- package/dist/{chunk-KBG47GHP.js → chunk-AHWA4AKM.js} +18 -12
- package/dist/{chunk-FMSO6RDZ.js → chunk-AI3GP74G.js} +17 -19
- package/dist/chunk-APFJKOP6.js +67 -0
- package/dist/{chunk-RXCOMYPY.js → chunk-ASRAO7KG.js} +31 -33
- package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
- package/dist/{chunk-QILIYSJF.js → chunk-CG5V25HX.js} +1 -1
- package/dist/chunk-CKEQFGLT.js +32 -0
- package/dist/{chunk-RPLINGVB.js → chunk-COOUUC5W.js} +6 -6
- package/dist/{chunk-GBPP5P7X.js → chunk-CPZ5JJW6.js} +4 -4
- package/dist/{chunk-OCAGUNBC.js → chunk-DS2USX5G.js} +13 -15
- package/dist/chunk-EA2ZRG44.js +27 -0
- package/dist/{chunk-ZHFZWTZV.js → chunk-EDMLIW6W.js} +13 -14
- package/dist/{chunk-2EECBNC5.js → chunk-EIKRZ32J.js} +75 -0
- package/dist/chunk-EKNWOL2I.js +27 -0
- package/dist/{chunk-CMMHNUZ2.js → chunk-ELZRSR5N.js} +65 -43
- package/dist/{chunk-BKE7E7TC.js → chunk-EN5AM7PX.js} +11 -12
- package/dist/{chunk-N2H3ZPZY.js → chunk-EWXXLS26.js} +227 -24
- package/dist/chunk-EX4EXBW7.js +37 -0
- package/dist/{chunk-YYOIQFRS.js → chunk-EXVXBSGN.js} +130 -52
- package/dist/{chunk-6GFRNVYR.js → chunk-F7BO6FWH.js} +12 -13
- package/dist/chunk-FEDWAYDS.js +2485 -0
- package/dist/{chunk-JAU72XNY.js → chunk-FWZRGGGY.js} +73 -9
- package/dist/{chunk-GXW6K4YJ.js → chunk-G224FADB.js} +1 -1
- package/dist/chunk-G5UCJFT7.js +26 -0
- package/dist/{chunk-67WMNWEE.js → chunk-GLW3YDZZ.js} +22 -13
- package/dist/{chunk-724UL2TJ.js → chunk-GTDSYEA2.js} +72 -39
- package/dist/{chunk-PHDMFAKM.js → chunk-GYRZ72R4.js} +10 -4
- package/dist/chunk-HYVXA3BB.js +49 -0
- package/dist/{chunk-SAEFPSB6.js → chunk-IEBJF3PN.js} +23 -15
- package/dist/chunk-IJYGIDF4.js +186 -0
- package/dist/{chunk-ACXEQZOU.js → chunk-IL7K66ZQ.js} +101 -109
- package/dist/{chunk-ZXYDQ3TZ.js → chunk-JWOVP5BL.js} +50 -19
- package/dist/{chunk-OXXKQCSV.js → chunk-K2GUZ4DN.js} +4 -4
- package/dist/{chunk-AW7R2GWG.js → chunk-K4SZB56V.js} +39 -39
- package/dist/{chunk-WOA4LN2R.js → chunk-KCBRHV5E.js} +3 -3
- package/dist/{chunk-3W7IEVVL.js → chunk-KFXCL4OV.js} +47 -45
- package/dist/{chunk-2BBLFX75.js → chunk-KJJAVH3X.js} +81 -15
- package/dist/{chunk-VCHXCQFG.js → chunk-KPVLQHCZ.js} +4 -6
- package/dist/{chunk-P7266HLM.js → chunk-KX56K73G.js} +10 -13
- package/dist/{chunk-VSSBEUFT.js → chunk-LMCTHJ2H.js} +19 -19
- package/dist/{chunk-IBGIOBEE.js → chunk-MEFLGBCS.js} +69 -8
- package/dist/{chunk-TYM6OUIT.js → chunk-MKPCELNI.js} +17 -17
- package/dist/{chunk-XTMJ7XDT.js → chunk-N3PLNNCW.js} +1 -1
- package/dist/chunk-N5FBM25N.js +22 -0
- package/dist/{chunk-CHOW74WE.js → chunk-NFNVDDGB.js} +7 -12
- package/dist/{chunk-52FUZI6K.js → chunk-NLIVE7L6.js} +2 -30
- package/dist/{chunk-SS36ZX4J.js → chunk-OMJ3OFBJ.js} +6 -6
- package/dist/{chunk-4W4VLAPJ.js → chunk-OZNCKLOX.js} +13 -14
- package/dist/chunk-P5XUGPIX.js +31 -0
- package/dist/{chunk-5UCAH366.js → chunk-PJXNTPB2.js} +253 -33
- package/dist/chunk-PKOXJIVT.js +88 -0
- package/dist/{chunk-6C7JWPCP.js → chunk-PP2A5V2T.js} +27 -26
- package/dist/{chunk-L3BLXZG7.js → chunk-Q42LJANT.js} +31 -70
- package/dist/{chunk-AB3YYG6N.js → chunk-Q4BKKOVC.js} +8 -8
- package/dist/{chunk-3EFKIGZN.js → chunk-QT66NEYN.js} +4 -4
- package/dist/{chunk-3VPVG5SU.js → chunk-RCHO5W7M.js} +19 -18
- package/dist/{chunk-77M37OKR.js → chunk-RG3MXTRI.js} +7 -7
- package/dist/chunk-RG7OODGM.js +57 -0
- package/dist/{chunk-T6CPIZNT.js → chunk-RU34BA4D.js} +44 -39
- package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
- package/dist/{chunk-5NGR67U5.js → chunk-S55TEC7I.js} +33 -5
- package/dist/{chunk-M6HSLBWY.js → chunk-SJHC3BCZ.js} +7956 -8047
- package/dist/{chunk-XCJN5IJU.js → chunk-SNEUMLM7.js} +4 -4
- package/dist/{chunk-UZ3TUTRV.js → chunk-T4NGVFYI.js} +2 -2
- package/dist/{chunk-2VUQMUMT.js → chunk-THEXI2QO.js} +49 -43
- package/dist/{chunk-R3PCY3YS.js → chunk-TL2TCJYL.js} +15 -16
- package/dist/{chunk-C34ZXZ7O.js → chunk-TPYYEDP5.js} +838 -352
- package/dist/{chunk-AOHZU2BM.js → chunk-TVZRLTG6.js} +8 -1
- package/dist/{chunk-XMSXXAHW.js → chunk-UCVMSOXF.js} +2 -2
- package/dist/chunk-UL5SXQVX.js +32 -0
- package/dist/{chunk-GAEGEPOC.js → chunk-UO66IMVP.js} +2 -2
- package/dist/{chunk-N3X6Q4YT.js → chunk-UVY4TOJH.js} +3 -3
- package/dist/{chunk-2CD5RS6M.js → chunk-VIDEKABZ.js} +23 -2
- package/dist/{chunk-JSQFTSC6.js → chunk-VITFDI3O.js} +13 -14
- package/dist/{chunk-YIUAVF7E.js → chunk-VUAVE3QC.js} +42 -42
- package/dist/{chunk-QOZXJ4NA.js → chunk-WUY4BZEP.js} +21 -20
- package/dist/{chunk-VCO24T4L.js → chunk-X3UTCXAA.js} +43 -53
- package/dist/chunk-XHDBJODR.js +45 -0
- package/dist/{chunk-MXGY6KPT.js → chunk-XHLK33VM.js} +28 -21
- package/dist/{chunk-RWWYJ623.js → chunk-XI34NWDI.js} +2 -2
- package/dist/{chunk-QQNQ7SJW.js → chunk-XWFIHYCH.js} +12 -4
- package/dist/{chunk-6SDEP3AJ.js → chunk-Y2TPADJR.js} +10 -11
- package/dist/{chunk-MRXKYPCS.js → chunk-Y5KTA2OB.js} +17 -17
- package/dist/{chunk-7DYBLXYA.js → chunk-YKVDBNPO.js} +11 -5
- package/dist/{chunk-2B73ZPOK.js → chunk-YSDPVDFC.js} +3 -3
- package/dist/chunk-YWNO5Q4R.js +44 -0
- package/dist/{chunk-QHJ6DQ2R.js → chunk-YWWG4AQA.js} +165 -32
- package/dist/{chunk-3JNKMP3B.js → chunk-YXDCRUKQ.js} +4 -4
- package/dist/{chunk-UXGETRP4.js → chunk-YXGRRORB.js} +16 -17
- package/dist/{chunk-SQ4TVJBR.js → chunk-ZAPSUBLU.js} +13 -7
- package/dist/{chunk-76MWC2K6.js → chunk-ZPJM7DID.js} +90 -97
- package/dist/{chunk-XVF2VVXP.js → chunk-ZSUX7KEM.js} +16 -15
- package/dist/index.js +31038 -20893
- package/dist/mcp/analyze-cli.js +11 -11
- package/dist/mcp/cli.js +47 -43
- package/dist/mcp/server.js +2188 -906
- package/dist/mcp/worker.js +66 -63
- package/dist/probes/installer.js +21 -23
- package/dist/workers/project-snapshot-persist-worker.js +28 -9
- package/dist/workers/review-graph-persist-worker.js +1 -1
- package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
- package/docs/adr/README.md +1 -0
- package/docs/ast-grep_rules_catalog.md +5 -3
- package/docs/configuration.md +20 -0
- package/docs/engineering-principles.md +44 -0
- package/docs/environment-variables.md +20 -0
- package/docs/features.md +16 -1
- package/docs/globalconfig.md +37 -8
- package/docs/lsp-capability-matrix.md +105 -12
- package/docs/lsp-idle-eviction.md +44 -36
- package/docs/pi-lens-fixer.md +139 -14
- package/docs/pi-lens-investigator.md +14 -0
- package/docs/pi-lens-merge-policy.md +120 -17
- package/docs/pi-lens-monitor.md +71 -9
- package/docs/pi-lens-retro.md +6 -3
- package/docs/pi-lens-reviewer.md +160 -5
- package/docs/pi-lens-subagent.md +29 -14
- package/docs/release-qa-baseline.md +21 -7
- package/docs/servercapabilities.md +53 -63
- package/docs/settings.md +9 -5
- package/docs/subagent-compat.md +1 -1
- package/docs/usage.md +1 -0
- package/package.json +9 -5
- package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
- package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
- package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
- package/rules/rule-catalog.json +25 -1
- package/scripts/analyze-pi-lens-logs.mjs +15 -5
- package/scripts/download-grammars.js +40 -7
- package/scripts/lib/is-main-module.mjs +27 -0
- package/scripts/lib/latency-log-phases.mjs +95 -0
- package/scripts/lib/scratch-home-env.mjs +21 -0
- package/scripts/rpc-load-check.mjs +568 -81
- package/scripts/warm-loader-cache.mjs +2 -5
- package/dist/chunk-23WOO7TX.js +0 -23
- package/dist/chunk-3YN6V5TV.js +0 -85
- package/dist/chunk-466Z26MG.js +0 -30
- package/dist/chunk-4UNXBNE2.js +0 -24
- package/dist/chunk-6STA6Z7I.js +0 -47
- package/dist/chunk-ABBOA7UD.js +0 -157
- package/dist/chunk-BRGDSBJE.js +0 -28
- package/dist/chunk-EC47DWFA.js +0 -56
- package/dist/chunk-FCSOVF55.js +0 -273
- package/dist/chunk-IZSHAIJ7.js +0 -26
- package/dist/chunk-KDERNTCQ.js +0 -28
- package/dist/chunk-KSX3TXSZ.js +0 -69
- package/dist/chunk-LOP6GRPH.js +0 -31
- package/dist/chunk-PNQDPDRC.js +0 -184
- package/dist/chunk-UOPVJQ4N.js +0 -103
- package/dist/chunk-XAGLWMJ4.js +0 -51
- package/dist/chunk-XIJZVPD5.js +0 -39
- package/dist/chunk-Z3CCVDUB.js +0 -76
- package/dist/chunk-Z527N6YQ.js +0 -28
- package/dist/chunk-ZANLILYD.js +0 -79
- /package/dist/{chunk-FC4RP4I2.js → chunk-6HWVI6MI.js} +0 -0
package/docs/pi-lens-fixer.md
CHANGED
|
@@ -14,11 +14,29 @@ Before mocking a `clients/` module, look for its test seam (`set*`, `adopt*`, or
|
|
|
14
14
|
`reset*`). The pre-flight must list the mock dependents of any module whose
|
|
15
15
|
exports change.
|
|
16
16
|
|
|
17
|
+
A new test starts from `tests/support/`: a registration question (flags,
|
|
18
|
+
tools, commands, declarations) goes through tier 1
|
|
19
|
+
(`tests/support/pi-runner.ts`, a real `ExtensionRunner`), a session-flow case
|
|
20
|
+
through tier 2 (`tests/support/pi-session.ts`), and a JSON-lines sink through
|
|
21
|
+
`readNdjsonRows` (`tests/support/ndjson-rows.ts`), asserting `skipped === 0`
|
|
22
|
+
when the claim needs the complete output. No fake of an in-process store or
|
|
23
|
+
registry; other doubles only as `AGENTS.md` admits them.
|
|
24
|
+
|
|
17
25
|
- Trace the production entry point and reproduce the defect through it
|
|
18
26
|
(principles §1, "Premise first"). Name no seam before the reproduction; the
|
|
19
27
|
red reproduction is your feedback loop, built before any theory of the fix.
|
|
28
|
+
Reproduce on the reporter's pi host and pi-lens version, taken from the
|
|
29
|
+
report or its session log. When that version cannot be installed, name the
|
|
30
|
+
one you used instead; never substitute the latest silently. Report
|
|
31
|
+
`confirmed`, `partially confirmed` (name what differed), `not reproduced`
|
|
32
|
+
(name what you tried), or `blocked` (name the missing access or state).
|
|
20
33
|
- Climb the minimalism ladder before screening against the `AGENTS.md`
|
|
21
34
|
catalog: the catalog says what must not break, never what to add.
|
|
35
|
+
- Mechanism for a race, security edge case or failure nobody has reproduced is
|
|
36
|
+
not built in the round (principles §1, speculative robustness). Name its
|
|
37
|
+
trigger path, evidence and cost under scope at the top of the hand-back, and
|
|
38
|
+
leave the decision to the maintainer. Validation, error handling and security
|
|
39
|
+
at a real trust boundary are still required.
|
|
22
40
|
- Check which open PRs touch your files (`gh pr list`, `gh pr diff`), design to
|
|
23
41
|
compose, and flag merge order in the PR body. Branch `fix/<N>-<slug>` from
|
|
24
42
|
`origin/master` unless the brief names a branch. Preserve contributor
|
|
@@ -32,12 +50,22 @@ exports change.
|
|
|
32
50
|
- When a gate becomes fail-closed, sweep every construction site that reaches
|
|
33
51
|
it, test doubles included, and prove the sweep with the behaviour suites
|
|
34
52
|
(#3622).
|
|
53
|
+
- A new module, or a new use of a detection or caching primitive (stat,
|
|
54
|
+
mtime, inode, content or line hash, directory walk, install stamp, sequence
|
|
55
|
+
counter), lists the existing modules that use the same primitive for the
|
|
56
|
+
same purpose. Find them by searching for the primitive, such as
|
|
57
|
+
`rg -l 'statSync|mtimeMs|createHash|readdir|projectSeq' clients`, never by
|
|
58
|
+
your own seam's call names. The consolidation verdict cites that list
|
|
59
|
+
(#4536).
|
|
35
60
|
- A change on a lifecycle, timing, or identity seam extends or adds a TLA+
|
|
36
61
|
model in this step (#3802; the rule itself is in `AGENTS.md`). Find the
|
|
37
62
|
family in `formal/coverage-map.json`, write the invariant the change
|
|
38
63
|
preserves or tightens, and show the violating config red on the pre-fix model
|
|
39
64
|
and green after, or carry `TLA+ unaffected: <family> — <reason>` in the PR
|
|
40
|
-
body.
|
|
65
|
+
body. The unaffected line is wrong when the change alters a behaviour an
|
|
66
|
+
as-built config constant encodes: flip that constant, its configs and its
|
|
67
|
+
`formal/switch-pins.json` value instead, and keep its pin test red on the old
|
|
68
|
+
behaviour (#4387, #4393). A row is any-of (one listed family's model move or declaration
|
|
41
69
|
satisfies it); a row of 4+ families only prints a note, except `index.ts`,
|
|
42
70
|
whose row gates on the lifecycle hook handler a hunk lands in (#3878). The
|
|
43
71
|
map owner is the lane that adds a `formal/<family>/`: it adds the family and
|
|
@@ -60,12 +88,13 @@ exports change.
|
|
|
60
88
|
transcript quoted in `Test assessment`. A redundant test that still guards
|
|
61
89
|
goes only with the named survivor that covers it.
|
|
62
90
|
- Apply folded review follow-ups per `docs/pi-lens-subagent.md`
|
|
63
|
-
"Follow-ups", and list
|
|
64
|
-
PR body
|
|
91
|
+
"Follow-ups", and list every gap left open in one **Accepted residuals** section of
|
|
92
|
+
the PR body, each named `p3` with its severity and live population (merge bar:
|
|
93
|
+
`docs/pi-lens-merge-policy.md` "Filing issues").
|
|
65
94
|
|
|
66
95
|
## Evidence
|
|
67
96
|
|
|
68
|
-
- Use `scripts/mutate.mjs` for bounded hand mutations; it restores the target automatically, but only while the file still holds the mutated bytes. A leftover journal (`<file>.mutate-backup`) blocks the next run on that file; recover with `--restore`, which refuses and prints the three hashes when the file was edited since. If a crash left the file already at its original bytes, `--restore` also refuses; check the printed hashes and delete the journal by hand. `--restore` is crash recovery only: run against a live `mutate.mjs` run on the same file, it pulls that run's mutation, and that run then reports ERROR (exit 4).
|
|
97
|
+
- Use `scripts/mutate.mjs` for bounded hand mutations; it restores the target automatically, but only while the file still holds the mutated bytes. A leftover journal (`<file>.mutate-backup`) blocks the next run on that file; recover with `--restore`, which refuses and prints the three hashes when the file was edited since. If a crash left the file already at its original bytes, `--restore` also refuses; check the printed hashes and delete the journal by hand. `--restore` is crash recovery only: run against a live `mutate.mjs` run on the same file, it pulls that run's mutation, and that run then reports ERROR (exit 4). The transcript's status line is `SURVIVED` (tests passed), `RED` (a test run failed), `REFUSED` (the edit was not applied), `BROKEN` (the build failed) or `ERROR` (no verdict); only `RED` proves a test catches the mutation (#4510).
|
|
69
98
|
|
|
70
99
|
- Witness rule (ADR 0007): #1605 owns the witness lanes, and their fixtures
|
|
71
100
|
live under `tests/fixtures/witness/<slice>/`.
|
|
@@ -81,19 +110,65 @@ exports change.
|
|
|
81
110
|
from the pre-fix SHA (`git checkout <sha> -- clients/…`), never `tests`
|
|
82
111
|
(#3166) and never uncommitted work, and run `git status` after any bulk
|
|
83
112
|
restore. Without Git authority, use a saved patch.
|
|
84
|
-
- Hand-mutate only the NEW guard, branch, filter, or cap the PR is about,
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
113
|
+
- Hand-mutate only the NEW guard, branch, filter, or cap the PR is about, and
|
|
114
|
+
the behaviour behind each relaxed assertion (next bullet), both directions,
|
|
115
|
+
one row per direction, and quote the compile-valid red. The new test is the
|
|
116
|
+
only red under at least one mutation. These rows are the whole PR mutation
|
|
117
|
+
layer (AGENTS.md, #4005): there is no per-PR Stryker job, comment, or
|
|
88
118
|
`MUTATION` line, and no survivor triage. The nightly Stryker report on master
|
|
89
119
|
is exploratory and is not read here. Use bounded hand probes locally; never
|
|
90
120
|
run a full Stryker campaign in a worktree.
|
|
91
|
-
-
|
|
92
|
-
|
|
121
|
+
- A PR that relaxes or rewrites an existing assertion (a changed meaning makes
|
|
122
|
+
the old expectation wrong) mutates the behaviour that test is named for. Quote
|
|
123
|
+
the red on the new assertion. A rewrite that stays green with that
|
|
124
|
+
behaviour broken is a deleted test (#4390: the eviction smoke's rewrite
|
|
125
|
+
passed with root re-registration broken).
|
|
126
|
+
- A PR that adds or changes a detector (a ratchet, census or source scan)
|
|
127
|
+
writes STATE_TABLE.md before the first edit: each form the detector
|
|
128
|
+
admits, and the statement that every other form refuses. It then plants
|
|
129
|
+
three spellings its author did not design for: an alias, an indirect
|
|
130
|
+
call and a value reached through another binding. Quote each result. A
|
|
131
|
+
plant that stays green is fixed. A stated residual names an admitted
|
|
132
|
+
form that is too broad, never an unread spelling (AGENTS.md shape 69).
|
|
133
|
+
- The manual per-test campaign (`stryker-pertest.yml`, #4365) lists tests that
|
|
134
|
+
cover mutated code but kill no mutant. It is a triage input, not a verdict:
|
|
135
|
+
a candidate that guards another seam or a named recurrence stays, and a
|
|
136
|
+
deletion it proposes lands only with the covering test named and the
|
|
137
|
+
reviewer's agreement test by test.
|
|
138
|
+
- Every record the `Observability` section names is asserted by a test under
|
|
139
|
+
`tests/` (any collected test, not only a file this PR touches) and quoted in
|
|
140
|
+
the body (#2642, #2647, #2649, #2654). The body lint refuses a named record
|
|
141
|
+
literal no collected test reads back (`scripts/check-pr-body.mjs`, #4597), so
|
|
142
|
+
a record the section names without a read-back cannot merge; `none: <reason>`
|
|
143
|
+
still answers a diff with no record. A mention counts whatever its spelling:
|
|
144
|
+
a backticked span, a bare word and a link label are all read against the
|
|
145
|
+
record values the runtime emits, so prose that reuses a record's own name is
|
|
146
|
+
a mention too.
|
|
147
|
+
- The read-back is the record's full name in an assertion, a comparison, a
|
|
148
|
+
`case` label or a record-keyed row inside a declaration vitest collects and
|
|
149
|
+
runs, or inside a module-scope helper that one of them calls. A title, a
|
|
150
|
+
`console.log`, a skipped test and an excluded tree do not count, and a record
|
|
151
|
+
named only through a table imported from another file does not either, so
|
|
152
|
+
inline the name in the assertion. The declaration may be spelled with a
|
|
153
|
+
computed modifier or bracket link (`it["only"]`) and through an alias
|
|
154
|
+
(`const t = it`); a form the lint cannot classify (`it[modifier]`, a
|
|
155
|
+
destructured alias) makes its whole file contribute nothing, so write the
|
|
156
|
+
declaration the plain way. Naming a record that predates the PR owes the same
|
|
157
|
+
test.
|
|
93
158
|
- Every behavioural sentence (a docstring invariant, a memo, a registry
|
|
94
159
|
justification) maps to a test or a probe, or is deleted (#2643, #2654).
|
|
95
160
|
- Name where new state sits in its ladder and what happens to it at
|
|
96
161
|
`session_start` (#2649, #2654).
|
|
162
|
+
- A change on a hot path (dispatch, `session_start`, LSP diagnostics, a cache
|
|
163
|
+
lookup, turn-end) quotes a before/after timing from the real path in the
|
|
164
|
+
body, with the command, at a small and a large input; per-input work on a
|
|
165
|
+
tool path also needs a size or time bound. Name and justify any regression
|
|
166
|
+
(#4344 r1; #4368 r1). The `Hot-path latency (advisory)` lane (#4363) times
|
|
167
|
+
`session_start`, `dispatchLint` and the diagnostics-cache replay on the head
|
|
168
|
+
and its first parent (`HEAD^1`); read its job summary, and time by hand any
|
|
169
|
+
hot path it does not cover (a language server's time, a dependency bump).
|
|
170
|
+
Green means no regression of 1.25x and 5 ms; a "slower, below threshold" row
|
|
171
|
+
is still a number to read.
|
|
97
172
|
- A measured constant names its measuring command and keeps raw output as a
|
|
98
173
|
tracked artifact pinned by a test (#3648). Run `git check-ignore -v` on every
|
|
99
174
|
new artifact path before citing it (#3648).
|
|
@@ -114,10 +189,31 @@ exports change.
|
|
|
114
189
|
`node_modules`.
|
|
115
190
|
- Run release-QA end to end when a release-QA row changes.
|
|
116
191
|
- Run the reviewer's standing probes (`docs/pi-lens-reviewer.md`) that the diff
|
|
117
|
-
can trip, and quote their output in the PR body.
|
|
192
|
+
can trip, and quote their output in the PR body. The `verify-pi-lens` skill
|
|
193
|
+
(`.claude/skills/verify-pi-lens/SKILL.md`) holds the real-path recipes.
|
|
118
194
|
|
|
119
195
|
## Fix rounds
|
|
120
196
|
|
|
197
|
+
- When bot threads or code-scanning alerts exist, read and dispose of each
|
|
198
|
+
one. A missing bot review is never evidence of anything: it never blocks the
|
|
199
|
+
round and never becomes something to wait for. The threads, every page:
|
|
200
|
+
`gh api graphql --paginate -f query='query($owner:String!,$name:String!,$number:Int!,$endCursor:String){repository(owner:$owner,name:$name){pullRequest(number:$number){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:1){nodes{author{login} body}}}}}}}' -F owner="$(gh repo view --json owner --jq .owner.login)" -F name="$(gh repo view --json name --jq .name)" -F number=<N> --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | "\(.id) \(.path):\(.line) \(.comments.nodes[0].author.login): \(.comments.nodes[0].body)"'`,
|
|
201
|
+
and the alerts:
|
|
202
|
+
`gh api --paginate "repos/{owner}/{repo}/code-scanning/alerts?ref=refs/heads/<branch>&state=open" --jq '.[] | "\(.number) \(.rule.id) \(.most_recent_instance.location.path):\(.most_recent_instance.location.start_line)"'`.
|
|
203
|
+
Both commands follow their cursor to the last page, so the list is clear
|
|
204
|
+
only after that page prints: one page is never read as the whole list.
|
|
205
|
+
An alert on another branch is not this round's; read the head you pushed.
|
|
206
|
+
Before the hand-back, reply to and resolve every thread this round fixes, and
|
|
207
|
+
name every other open thread and alert in the PR body with its disposition.
|
|
208
|
+
A round that finds none says so in one line and moves on. Where the brief
|
|
209
|
+
withholds GitHub writes
|
|
210
|
+
(`docs/pi-lens-subagent.md`),
|
|
211
|
+
put the same list in the body and the hand-back for the orchestrator to post
|
|
212
|
+
and resolve. The disposition words and the merge condition are
|
|
213
|
+
`docs/pi-lens-merge-policy.md` "The loop, per PR" step 1 and step 4
|
|
214
|
+
(`:34`, `:81`); this contract does not restate them. Recurrence: #4566 and
|
|
215
|
+
#4575 (2026-10-17), where the threads outlived the rounds that should have
|
|
216
|
+
read them.
|
|
121
217
|
- On `FIX ROUND` findings, reproduce each finding before fixing it, add a
|
|
122
218
|
red-first test for every behavioural fix, rebuild, re-run the targeted suites
|
|
123
219
|
plus anything the findings touched, and push the same branch. If the PR reads
|
|
@@ -137,6 +233,9 @@ exports change.
|
|
|
137
233
|
- Spot-check one prior round's mutation on the new head (#2583).
|
|
138
234
|
- Re-read the changelog fragment for any claim the round retracts (#3155), then
|
|
139
235
|
add an honest review-round section to the PR body.
|
|
236
|
+
- Lint the PR body (`--lint-local`) before the first push of a round, not only
|
|
237
|
+
at hand-back: `PR body (advisory)` re-reads the same body on every push, so
|
|
238
|
+
an unfixed finding reds each one.
|
|
140
239
|
|
|
141
240
|
## Before the report
|
|
142
241
|
|
|
@@ -155,13 +254,25 @@ rigor (#2599).
|
|
|
155
254
|
`## Observability` (a record literal from the runtime diff, `none: <reason>`,
|
|
156
255
|
or exactly `No new failure path; no record added.`, which a new decision
|
|
157
256
|
branch on a session, lifecycle or delivery seam refuses, #3875),
|
|
158
|
-
`## Class sweep`,
|
|
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
|
|
159
261
|
headings does not shorten this list. The closing keyword lives in the body;
|
|
160
262
|
GitHub ignores it in a title.
|
|
161
263
|
- Run `node scripts/check-pr-body.mjs --lint-local PR_BODY.md` and
|
|
162
264
|
`node scripts/check-changelog-fragments.mjs` before the hand-back; both
|
|
163
|
-
must pass, and the hand-back quotes them.
|
|
164
|
-
|
|
265
|
+
must pass, and the hand-back quotes them. The body lint reads the closed
|
|
266
|
+
issue's labels through `gh api`; a `::warning::` that the Detection check
|
|
267
|
+
was skipped means gh failed, so the section was not required, not that it
|
|
268
|
+
passed (#4288). A non-bug PR either deletes the `## Detection` section or
|
|
269
|
+
fills the three lines, and a `Shape:` or `Enforcer:` line it does write is
|
|
270
|
+
validated too; free text in between reds the local preflight. A bug-closing
|
|
271
|
+
PR that answers a layer, the `Gap: none:` reason, the `Shape: new:` name or
|
|
272
|
+
the `Enforcer: none:` reason with `unknown`, `n/a`, `tbd` or `?` is refused
|
|
273
|
+
(#4519); the layer words are `DETECTION_LAYERS`, `nightly:<workflow>`
|
|
274
|
+
included. A red `PR body (advisory)` check is a fix-before-review item.
|
|
275
|
+
A changelog fragment is `---` /
|
|
165
276
|
`section: <Added|Changed|Deprecated|Removed|Fixed|Security>` /
|
|
166
277
|
`audience: <user|internal>` / `---` / blank / one `- ` bullet. New
|
|
167
278
|
`audience: user` fragments must begin with a bold lead of at most 100
|
|
@@ -172,6 +283,20 @@ rigor (#2599).
|
|
|
172
283
|
hit); `internal` is CI, tests, `formal/`, contributor docs, orchestration, and
|
|
173
284
|
refactors with no observable change. `npm run changelog:check` checks the
|
|
174
285
|
rollup, not fragments (#2456).
|
|
286
|
+
- A bug fix's detection lesson names the defect SHAPE and its tree-wide
|
|
287
|
+
enforcer, not only a test for the instance: the `Shape:` line names the
|
|
288
|
+
`AGENTS.md` "Recurring defect shapes" number (or `new: <name>`), and the
|
|
289
|
+
`Enforcer:` line a test on base that scans the whole population, an issue to
|
|
290
|
+
build one, or `none: judgment-only, <reason>`. With `Shape: #N` a path
|
|
291
|
+
enforcer must be one catalog entry N names. The fix's own one-bug test is its
|
|
292
|
+
regression test, not the closed gap. The body lint enforces both lines
|
|
293
|
+
(#4439).
|
|
294
|
+
- A `Shape: new: <name>` is a proposal, not a catalog entry: write the
|
|
295
|
+
proposed shape text in the PR body under "Proposed contract change
|
|
296
|
+
(maintainer decision)" and never edit `AGENTS.md`. Catalog shapes and rule
|
|
297
|
+
changes are the maintainer's decision; the orchestrator lands an approved
|
|
298
|
+
one in its own change (#4577's fixer added shape 74 unasked, and the
|
|
299
|
+
governance suites redded).
|
|
175
300
|
- Every code fact in the PR body is a `` `path:line` `` citation the check
|
|
176
301
|
verifies: the file must be in the committed tree (never an untracked or
|
|
177
302
|
git-ignored path, which CI cannot read), and a fenced quote after it must
|
|
@@ -17,6 +17,12 @@ issue and the requested evidence surface.
|
|
|
17
17
|
|
|
18
18
|
## Evidence sources
|
|
19
19
|
|
|
20
|
+
The log root is the monitored process's, resolved as in
|
|
21
|
+
`docs/pi-lens-monitor.md` "Inputs": a non-empty `PI_LENS_HOME`, then any
|
|
22
|
+
probe-home redirect, then `~/.pi-lens`. The paths below assume the default.
|
|
23
|
+
Rotation also writes timestamped archives; pass `--archived` to the analyzer
|
|
24
|
+
to read them.
|
|
25
|
+
|
|
20
26
|
- `~/.pi-lens/latency.log` and its `.1` rotation: per-touch records
|
|
21
27
|
(`lsp_touch_file`, `lsp_aux_wait_outcome`, `availability_decision`,
|
|
22
28
|
`lsp_scanner_coverage_gap`, breaker and deferral events). Rotation is by size:
|
|
@@ -62,6 +68,14 @@ issue and the requested evidence surface.
|
|
|
62
68
|
|
|
63
69
|
## Reproducible behavior
|
|
64
70
|
|
|
71
|
+
Reproduce on the reporter's pi host version and pi-lens version, taken from
|
|
72
|
+
the report or its session log. When you cannot install that version, say so
|
|
73
|
+
and name the version you used instead. Never substitute the latest silently.
|
|
74
|
+
Report one of four outcomes: confirmed, partially confirmed (name what
|
|
75
|
+
differed), not reproduced (name what you tried), or blocked (name the missing
|
|
76
|
+
access or state). Our bugs often depend on the host version; #4690 raises the
|
|
77
|
+
certified floor to 0.86.1.
|
|
78
|
+
|
|
65
79
|
When the symptom reproduces, the loop comes before the reading. Build the
|
|
66
80
|
tightest loop that goes red on the symptom (a failing test, a minimal driver, a
|
|
67
81
|
differential run), confirm it matches the reporter's exact symptom, and
|
|
@@ -21,16 +21,18 @@ reachable.
|
|
|
21
21
|
|
|
22
22
|
Every PR body starts with `## Why`, `## Notes for the reviewer`, and
|
|
23
23
|
`## Change outline`, followed by the existing `## Summary`, `## Tests`,
|
|
24
|
-
`## Blast radius`, `## Class sweep`, and `##
|
|
25
|
-
change outline is the changed symbol's caller/callee tree with
|
|
26
|
-
moved lines; include only structural views that changed.
|
|
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.
|
|
27
27
|
|
|
28
28
|
## The loop, per PR
|
|
29
29
|
|
|
30
30
|
1. **Review.** Spawn `pi-lens-reviewer` (worktree isolation) with the PR
|
|
31
31
|
number, a one-paragraph summary of the claim, and any PR-specific attack
|
|
32
32
|
angles. Self-authored and small PRs get reviewed too — the depth follows
|
|
33
|
-
the review tier below, never the priority label.
|
|
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
|
|
35
|
+
<sha>`, `accepted and disclosed`, or `rejected because <reason>`.
|
|
34
36
|
2. **Fix rounds.** Send findings back to the PR's original author agent when
|
|
35
37
|
its worktree survives (SendMessage — cheapest context); otherwise spawn
|
|
36
38
|
`pi-lens-fixer` on the branch with the findings inlined.
|
|
@@ -75,7 +77,8 @@ moved lines; include only structural views that changed.
|
|
|
75
77
|
sweeps is not green — run the sweep on the merge before merging. Apply
|
|
76
78
|
AGENTS.md's one mutation layer (#4005): new-guard proof and demonstrated
|
|
77
79
|
correctness gaps gate the merge. `ci-verdict` prints no mutation line, and
|
|
78
|
-
the nightly Stryker report is not a merge input.
|
|
80
|
+
the nightly Stryker report is not a merge input. Every bot review thread
|
|
81
|
+
carries its disposition reply and is resolved before the merge.
|
|
79
82
|
5. **Merge.** `gh pr merge <N> --merge` (merge commit, repo convention).
|
|
80
83
|
If "not up to date", `gh api -X PUT .../pulls/<N>/update-branch`, wait for
|
|
81
84
|
CI, re-gate, merge. On GitHub 503s: retry with backoff, never switch to
|
|
@@ -160,6 +163,18 @@ blocks dispatch above the thresholds (no hand-written fallback;
|
|
|
160
163
|
every refill; state them in the lane ledger. Standing rule from
|
|
161
164
|
2026-09-03, lifted only when the maintainer says so.
|
|
162
165
|
|
|
166
|
+
## Host capacity (orchestrator)
|
|
167
|
+
|
|
168
|
+
The maintainer may cap how many subagents run at once, for example when RAM is
|
|
169
|
+
shared with a local model. This is a machine-load cap, separate from
|
|
170
|
+
`PI_LENS_TEST_MAX_WORKERS` and from Git authority. A lane counts by what it
|
|
171
|
+
runs, not by its role or brief wording: any agent that runs a build, Vitest, a
|
|
172
|
+
language server or a probe counts, including an investigator that reproduces
|
|
173
|
+
through a probe and a Git-read-only reviewer. Agents that only read files and
|
|
174
|
+
call `gh`, grep or Explore never count and run in parallel with the capped
|
|
175
|
+
lanes; their brief says "no builds, no tests, no language servers, no probes"
|
|
176
|
+
(maintainer, 2026-10-14).
|
|
177
|
+
|
|
163
178
|
## Brief contract (orchestrator)
|
|
164
179
|
|
|
165
180
|
Before dispatching any issue that adds a shared helper or seam: grep for
|
|
@@ -171,12 +186,12 @@ bound helper because the brief deferred the fold without a reason.
|
|
|
171
186
|
|
|
172
187
|
## External reports (orchestrator)
|
|
173
188
|
|
|
174
|
-
|
|
189
|
+
This section is the contract; AGENTS.md "Issue triage & labels" holds the labels only. Assess the
|
|
175
190
|
report against the code before accepting or dispatching, ask the one or two
|
|
176
191
|
facts that would change the design, **do not dispatch work that depends on an
|
|
177
192
|
unanswered load-bearing question**, mirror the answer on the issue and point
|
|
178
193
|
the worker there rather than at a paraphrase, and cite the reporter's reasoning
|
|
179
|
-
as authority.
|
|
194
|
+
as authority. The steps above are the whole contract.
|
|
180
195
|
|
|
181
196
|
The train-specific consequence: an external lane's first dispatch is often
|
|
182
197
|
worth delaying by one exchange. On 2026-09-12 a fixer was dispatched on #3000
|
|
@@ -191,8 +206,27 @@ exactly one `priority:p1|p2|p3` (AGENTS.md #1676 rubric). The priority labels
|
|
|
191
206
|
were found deleted from the repo on 2026-09-03 and recreated (#2553); an
|
|
192
207
|
issue filed without one is a triage defect, not a shortcut.
|
|
193
208
|
|
|
194
|
-
|
|
195
|
-
|
|
209
|
+
**Merge bar (user, 2026-10-18).** A PR merges when no HIGH finding is open and
|
|
210
|
+
every gating check is green on the exact head. Each MEDIUM or LOW finding
|
|
211
|
+
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
|
|
213
|
+
population (for example `p3 (MEDIUM, live 0): <the gap>`), so the gap keeps a
|
|
214
|
+
priority without an issue.
|
|
215
|
+
A residual never becomes a follow-up issue. File an issue only for p2 or
|
|
216
|
+
higher work that cannot ride the PR: a HIGH outside the PR's scope, or a
|
|
217
|
+
MEDIUM with a live population. Before a final round, the brief says "final
|
|
218
|
+
round" and names what it fixes; a residual of MEDIUM or below after it does not
|
|
219
|
+
reopen the round.
|
|
220
|
+
|
|
221
|
+
**Known gaps (user, 2026-10-19).** An open p3 issue is an accepted known gap,
|
|
222
|
+
not backlog. The orchestrator closes it as not planned with the `known-gap`
|
|
223
|
+
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
|
|
225
|
+
seam. A known gap reopens as p2 when it turns material: a live wrong result,
|
|
226
|
+
data loss, a hang, or a leak with no bound.
|
|
227
|
+
|
|
228
|
+
Every reviewer **follow-up issue** generalization verdict that meets that bar is
|
|
229
|
+
filed and assigned to a seam group on the tracking queue in the same turn. At each regroup, scan
|
|
196
230
|
merged PRs for subset-shaped changes that lack a generalization verdict.
|
|
197
231
|
|
|
198
232
|
Before filing a review follow-up, apply the standing fold rule: fold same-seam
|
|
@@ -202,6 +236,16 @@ re-verification; small code folds carry a red-first test and return to the same
|
|
|
202
236
|
reviewer. File only different-seam, blocked, decision-dependent, untouched
|
|
203
237
|
pre-existing, or risk-class-changing items, as one consolidated issue per PR.
|
|
204
238
|
|
|
239
|
+
Folds also decide the issue list itself, one step earlier than a review
|
|
240
|
+
finding: `AGENTS.md`, "Orchestration and delegated work" states that check.
|
|
241
|
+
|
|
242
|
+
A brief carries the lane's facts and the task, and points at the role
|
|
243
|
+
contract for everything else. Lane facts are the worktree, branch, base,
|
|
244
|
+
TMPDIR, test-worker cap, Git grant, and deliverable path. It never restates
|
|
245
|
+
contract rules such as hooks, trailers, stash, PR-body lint or summary
|
|
246
|
+
shape, because the role wrapper loads them. `bin/claude-lane.sh` prints
|
|
247
|
+
exactly the lane facts.
|
|
248
|
+
|
|
205
249
|
## Round-count rail (orchestrator)
|
|
206
250
|
|
|
207
251
|
When a verify round reports that a fix round introduced a NEW defect on the
|
|
@@ -268,7 +312,7 @@ operator's private notes, so a different orchestrator can run the same train.
|
|
|
268
312
|
| 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 |
|
|
269
313
|
| 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` |
|
|
270
314
|
| 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 |
|
|
271
|
-
| 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 / Observability; run `node scripts/check-pr-body.mjs --lint-local` before pushing — three PRs this week needed orchestrator body edits |
|
|
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 |
|
|
272
316
|
| a whole-tree docs restructure of `AGENTS.md` | every governance test that reads `AGENTS.md`, with markers on their own lines — PR #3265 r1 |
|
|
273
317
|
| a raw poll in a test | the flake-shape ratchet; the fix is the governed wait, never a header admission — #2781 r1 |
|
|
274
318
|
| 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 |
|
|
@@ -334,7 +378,16 @@ operator's private notes, so a different orchestrator can run the same train.
|
|
|
334
378
|
round 1.** Their correctness lives in parsing edge cases, exactly where the
|
|
335
379
|
smaller model loses: #2693 took two Sonnet rounds (~720k tokens) on a text
|
|
336
380
|
scanner before the rail sent round 3 to Opus, which rewrote it on the AST
|
|
337
|
-
and closed in two rounds.
|
|
381
|
+
and closed in two rounds. The rule covers checks that scan source text or
|
|
382
|
+
its AST. A plain assertion over config or workflow data (two pins match, a
|
|
383
|
+
key exists) goes to Sonnet, or to Haiku when mechanical (#4350).
|
|
384
|
+
- **Haiku 5.5 is the orchestrator's cheap lane.** The orchestrator uses it
|
|
385
|
+
without asking for read-only locate and premise-pointer passes, CI-red and
|
|
386
|
+
nightly investigations (`pi-lens-investigator`), and mechanical lanes
|
|
387
|
+
through `pi-lens-fixer-light`. Mechanical lanes include trailing folds,
|
|
388
|
+
dependabot pin and allowlist moves, and reviewer-prescribed test rows. It
|
|
389
|
+
never authors detectors or governance sweeps (the Opus rule above), and
|
|
390
|
+
never takes lifecycle or identity seams or reviews of runtime diffs.
|
|
338
391
|
- **Brief shape for a fixer.** Issue/PR number and head; the checked-out
|
|
339
392
|
branch; the exact findings with file:line, the reviewer's probe to reproduce
|
|
340
393
|
FIRST, and the remedy shape the maintainer chose; what to fold (net-count)
|
|
@@ -410,8 +463,8 @@ operator's private notes, so a different orchestrator can run the same train.
|
|
|
410
463
|
(so `Ast-grep self-scan` or `Audit production dependencies` reads as what
|
|
411
464
|
it is, not as a test failure), its `FAIL` and assertion lines and the
|
|
412
465
|
`Tests` summary with the ANSI codes stripped, the gating and advisory
|
|
413
|
-
counts on separate lines (advisory
|
|
414
|
-
merging), and the remedy hint: `gh run rerun <run>` for a cancelled or
|
|
466
|
+
counts on separate lines (an advisory red gates only when master is green
|
|
467
|
+
on that lane, and every red is read before merging), and the remedy hint: `gh run rerun <run>` for a cancelled or
|
|
415
468
|
superseded run, the `gh api -X POST .../approve` command for fork
|
|
416
469
|
approval, `gh pr update-branch <pr>` when the failed merge's base is no
|
|
417
470
|
longer master's head (a rerun replays the old merge commit, #3660). A job
|
|
@@ -458,7 +511,7 @@ operator's private notes, so a different orchestrator can run the same train.
|
|
|
458
511
|
Apart from `--approve-fork`, `--rerun-cancelled` and `--sync-main`, which you
|
|
459
512
|
pass by name, it never approves, reruns or updates a branch: it prints the
|
|
460
513
|
command.
|
|
461
|
-
- **Read the advisory rows before merging, even
|
|
514
|
+
- **Read the advisory rows before merging, even where they do not gate
|
|
462
515
|
(2026-09-12).** The exit-code rule above is right and stays: never text-match
|
|
463
516
|
the verdict table for `failure`, because advisory rows print `failure` on a
|
|
464
517
|
green PR. But "does not gate" is not "carries no information", and filtering
|
|
@@ -501,8 +554,18 @@ operator's private notes, so a different orchestrator can run the same train.
|
|
|
501
554
|
layer SHOULD have caught it earlier and at what cost. The accepted layer
|
|
502
555
|
words are the `DETECTION_LAYERS` list exported by `scripts/check-pr-body.mjs`,
|
|
503
556
|
which the `## Detection` body check reads; the prose does not restate them.
|
|
557
|
+
`nightly` may carry its workflow as `nightly:<workflow>`, and a bug-closing
|
|
558
|
+
PR is refused when `Caught by:`, `Should have been caught by:`, the reason
|
|
559
|
+
after `Gap: none:`, the `Shape: new:` name or the `Enforcer: none:` reason is
|
|
560
|
+
a placeholder (starts with `unknown`, or is exactly `n/a`, `tbd` or `?`)
|
|
561
|
+
(#4519: 139 of 363 closed bugs read unknown in the 2026-10-16 retro).
|
|
504
562
|
If that layer does not exist, file it as an issue with the bug as
|
|
505
|
-
its named recurrence — the same standard shapes are held to. The
|
|
563
|
+
its named recurrence — the same standard shapes are held to. The lesson
|
|
564
|
+
names the defect SHAPE and its tree-wide enforcer, not only a test for the
|
|
565
|
+
instance: the Gap names the `AGENTS.md` catalog shape (or a new shape) and
|
|
566
|
+
either a test that scans the whole population, an issue to build one, or
|
|
567
|
+
`judgment-only` with the reason. A one-bug test is the fix's regression
|
|
568
|
+
test, not the closed gap (lint half: #4439). The ledger
|
|
506
569
|
carries a `caught by / should have been caught by` column. Record: #2587's
|
|
507
570
|
manifest entry escaped the package for four releases; a second registration
|
|
508
571
|
path masked it, so the shipped defect was foreign-tree adoption, not absence
|
|
@@ -617,6 +680,10 @@ Each row cost a lane at least once; the prose above carries the record.
|
|
|
617
680
|
| Dispatching a fixer on an issue's text without checking it against the code | Grep the claimed gap on master before the brief. A stale premise turns the lane into a no-op or a witness-only PR |
|
|
618
681
|
| Writing off a worker's reds as "sandbox" without a same-env base run | Accept a sandbox attribution only with the same test names red on origin/master under the same env vars. Hundreds of guard reds can hide one real red |
|
|
619
682
|
| Folding a reviewer's remedy after running only the file the reviewer named | Run every test that references the changed symbol (`rg -l <symbol> tests`) before pushing a fold |
|
|
683
|
+
| Refreshing a census or matrix cell from a probe artifact | shape 76: the row must come from the subject's own emitter, never from an order-sensitive drain (#4615) |
|
|
684
|
+
| Reading a cancelled shard as a failure, or assuming a rerun clears it | shape 77: check the shard's own step conclusions and its measured runtime against the cap (#4672) |
|
|
685
|
+
| Admitting a third-party cache directory at the shared tmp root by name | shape 78: pin the loader's cache off and keep a planted sibling red (#4673) |
|
|
686
|
+
| Writing bytes ahead of the newest message (a returned `context` list, a tool-set change) without measuring the provider prefix | shape 79: write at the tail only, count a tool-set change as one full rewrite on a collapsing model, and compare the head and pi-ai's collapsed head across two real-session requests |
|
|
620
687
|
| Pushing with `-q` or a grep filter, then landing on whatever the PR head is | Read the push result unfiltered, check `git merge-base --is-ancestor <intended> origin/<branch>`, and land with `EXPECT_HEAD=<intended or its merge>` |
|
|
621
688
|
| Gating a background step on `until ! pgrep -f '<pattern>'` | That command line matches itself and never exits. Chain the steps in one command, or wait on a PID |
|
|
622
689
|
| Editing an orchestrator script while a chain or monitor runs it | Stop the chain first, or write a new file and `mv` it into place |
|
|
@@ -722,8 +789,10 @@ Each row cost a lane at least once; the prose above carries the record.
|
|
|
722
789
|
| Diagnosing a red from the first `##[error]` line | #4054's shard-5 red was called "npm registry unreachable"; that line came from a passing stubbed test, and the real failure was a 5 s timeout in check-pr-body.test.ts (#4088, 2026-10-07). Read the FAIL lines; treat annotation lines from stubbed tests as noise |
|
|
723
790
|
| Triggering CI on a bot PR before checking whether a run already exists | land.sh closed and reopened #4084 30 s after an update-branch, before the new run registered, which cancelled the run, and the cancelled aggregate read red (2026-10-07). Reopen only when no run exists for the head after a real wait |
|
|
724
791
|
| Writing a closing keyword where GitHub does not honour it, or by accident | #4121's title said `closes #3873`, which fails the close-keyword check (titles are never honoured); #4094's body said "then fixed #4080", an accidental closing keyword (2026-10-07). Put closing keywords in the body only, and reread the body for `fix(es\|ed) #N` prose |
|
|
792
|
+
| Quoting a closing keyword in a commit message | #4375's commit f40ac6c28 quoted `not fixed: #4346` and `Whether this closes #1513` as lint examples; GitHub acts on commit-message keywords that reach the default branch, so the merge closed both (2026-10-14). `closingIssuesReferences` omits them. Commit messages get the same keyword rules as the body; quote examples as `#N` without the keyword |
|
|
793
|
+
| Merging a contract-doc edit on an orchestrator read alone | #4379's seven-line host-cap section used "read-only" for the opposite of its meaning in `docs/pi-lens-subagent.md`, and left probe-running investigators unclassified; a scoped review caught both (2026-10-14). An edit to `docs/pi-lens-*.md` or AGENTS.md gets one scoped reviewer pass |
|
|
725
794
|
| Seeding a group list from the active queue instead of the tracker | The orchestrator's session group held 3 issues while `area:session` had 8 more open p2s, so "is the session group done?" was answered from an incomplete list (2026-10-08). Build a group from the label and the tracker, then subtract what is out of scope |
|
|
726
|
-
| Filing every LOW review finding as an issue | Each review spawned about one follow-up, so the CI group stayed at about 36 open after 16 closures (2026-10-07). Fold or drop LOW findings; file only
|
|
795
|
+
| Filing every LOW review finding as an issue | Each review spawned about one follow-up, so the CI group stayed at about 36 open after 16 closures (2026-10-07). Fold or drop LOW findings; file only what the merge bar admits (p2 or higher that cannot ride the PR), and give each group a "done when" |
|
|
727
796
|
| No cleanup when lanes end | 78 GB of finished lane trees and a 22 GB leaking test TMPDIR filled the root disk twice; two reviewers lost probe runs and one fixer's test file was truncated (2026-10-07). Remove a lane's trees and TMPDIR when its PR merges, and keep a disk alarm |
|
|
728
797
|
| Deriving the next round from a stale brief or a stale premise | #3871's brief asked for a selection fix #3903 had already shipped, and #3813's assumed every producer was unfixed; both fixers correctly refused to rebuild merged work (2026-10-07). Re-check the premise on current master when a lane starts, not when the issue was filed |
|
|
729
798
|
| Calling a PR-owned hygiene leak pre-existing because the same files fail on a later run | The PR's own CI run exposed the leak, but the reviewer classified it as a flake and fixed an unreachable injected path; the PR review and red-on-base comparison should have owned the finding. The hygiene check now treats a new leak on a green-master PR as CAUSED-BY-PR until red-on-base proves otherwise, and harness children receive a private `TMPDIR` (#4133, #4128). |
|
|
@@ -733,7 +802,7 @@ Each row cost a lane at least once; the prose above carries the record.
|
|
|
733
802
|
| Matching a flake on text that CI never prints | The unmatched CI output was noticed during review; the matcher test should have used a captured CI transcript. The flake matcher now keys on the classifier's actual output. |
|
|
734
803
|
| Letting keyword-title lint contradict the repository convention | The title gate review found the contradiction; the title-convention test should have pinned the accepted form. The lint rule now follows the repository's title convention. |
|
|
735
804
|
| Relaying a shard failure to a fixer without mirroring it on the PR | The fixer noticed the missing scope record; the scope-mirror hook should have rejected the handoff. The handoff path now records the scope on the PR before dispatch. |
|
|
736
|
-
| Treating a repeatedly red advisory lane as harmless | The maintainer's retrospective found the 21% flake after a misleading PR draw
|
|
805
|
+
| Treating a repeatedly red advisory lane as harmless | The maintainer's retrospective found the 21% flake after a misleading PR draw. The advisory policy and newest-master comparison should have held the PR. `merge-on-green.sh` now holds any advisory check red on the PR and green on master. `ADVISORY_OK='<lane>: <reason>'` must name the judgment; it refuses a bare `1`. #4540 (2026-10-17) and #4848 (2026-10-25) landed past such a red. |
|
|
737
806
|
| Forgetting to arm the landing chain after a trailing fix | A later PR-GREEN event exposed that the fix was waiting unarmed; the trailing-fix command should have verified arming. Rule: after a trailing fix, arm `land.sh` in the same step (not yet mechanised). |
|
|
738
807
|
| Accepting an identity trade-off without a complete timing-cell table | Cloud verification found primary-item loss after the trade-off was accepted from prose; the fixer's state table and review should have enumerated every timing cell. The brief now requires the complete state table before accepting the trade-off. |
|
|
739
808
|
| Letting a scoped test exceed Vitest's default timeout | A repeated cloud review caught the timeout; the local targeted run should have exercised the test under its default timeout. Rule: a scoped review runs new tests under the default Vitest timeout before passing them (not yet mechanised). |
|
|
@@ -747,3 +816,37 @@ Each row cost a lane at least once; the prose above carries the record.
|
|
|
747
816
|
| Adapting repository fixtures to a Plegma guard failure | Verify caught the harness-specific workaround; the fixture lane should have reported the environment block without changing repository tests. Plegma-guard fixture failures are now reported as environmental. |
|
|
748
817
|
| Reading a piped command's exit status instead of its outcome record | A pending chain was reported as successful because `tail` returned zero; the landing check should have read the chain's own result. `land.sh` now prints `LAND-RESULT #N: <state> (rc=N)`, which callers must read. |
|
|
749
818
|
| Routing a same-seam new defect to a weaker fixer after a prior round | The next verify found the same-seam defect after a Luna-high assignment; round routing should have selected Opus from the seam and round count. Rule: a new same-seam defect after two rounds goes to Opus (cloud fixer when the subscription is short) with the state table and model step first. |
|
|
819
|
+
| Asking the maintainer whether to build or file a missing detection layer | The orchestrator owns the detection retrospective: it files the layer issue, or folds it into the same-seam PR, the same day, and tells the maintainer (maintainer, 2026-10-13). |
|
|
820
|
+
| Sending a detector or governance-test round to a cheap model | The #4341 npx-pin scanner went to a Haiku round before the Opus-from-round-1 rule was re-read; check the routing bullets before every detector brief. |
|
|
821
|
+
| Routing on the word "governance" instead of the risk | #4350 (a CodeQL pin-equality test) went to Opus as "governance authoring"; the Opus rule is for source-scanning detectors only. |
|
|
822
|
+
| Leaving the `dist/` precondition undeclared | At least 5 lanes (#4417, #4418, the #4422 verify, the #4410 r1 review, the #4423 review F5) each ruled out the same 3 census reds that need `npm run build:dist` (2026-10-14). Mechanical: fail fast when a selected test needs `dist/` and it is missing or stale (#4436); `CLAUDE.md` names `npm run build:dist` for those files meanwhile |
|
|
823
|
+
| A wait helper with a fixed wall-clock budget | `interleaving-kit` `waitFor` ran out at 3000 ms under CI load (run 38618401454, `tests/clients/fix-run-restore.test.ts:378`); the file passed alone and under 3 shuffle seeds, so the red read as a flake. Mechanical, filed as #4437 |
|
|
824
|
+
| Briefing a worker to "report the size first" before a large migration | A worker cannot wait for a reply, so the #4432 fixer did the migration anyway (2026-10-14). A brief authorizes the conditional branch with its bound, or tells the worker to stop and hand back; `AGENTS.md` "Orchestration and delegated work" |
|
|
825
|
+
| Naming a file by basename in a brief | "index.ts" meant `clients/lsp/index.ts`; a Haiku measurement pass searched the root `index.ts` and reported the #2052 comment missing (2026-10-14). Name every file by its repo path |
|
|
826
|
+
| Sending a lane that must find its own failure space to Haiku | #4342 rounds 1 and 2 left three review findings (a wall-clock bound, a wrong offline premise, a 13-vs-20 population); a fresh Opus round with a state table passed verify first time (#4410 round 3). Haiku folds with a prescribed remedy (#4340, #4341, #4345, #4356, #4368, #4372, #4374, #4417) landed first try. Haiku takes only a prescribed change; `AGENTS.md` "Orchestration and delegated work" |
|
|
827
|
+
| Listing a blast radius without the changed result's callers | #4411 round 3 changed `touchFile`'s result and the body omitted the cascade neighbour caller (`clients/dispatch/integration.ts:2139`), which then printed an uncaused "inconclusive" line every turn (review N2). `AGENTS.md` already requires `module_report` with `blastRadius: true` before and after; run it for the changed result and quote every caller, then read each one |
|
|
828
|
+
| Leaving a ledger row reading as a remainder after a PR flips from `refs` to `closes` | The orchestrator's closes-check refused two lands (#4422, #4409) because the row still named a remainder after verify confirmed every criterion (2026-10-14). Mechanical, orchestrator tooling outside this repo: to be fixed in the orchestrator's land tooling, not by a repo check |
|
|
829
|
+
| Linting the PR body only at the end of a round | #4423's advisory `PR body` check went red on 5 consecutive pushes in round 2 with the same passive-voice findings (2026-10-14); a push does not change the body, so the check re-read the unfixed one each time. Lint the body with `--lint-local` before the first push of a round (`docs/pi-lens-fixer.md` "Fix rounds") |
|
|
830
|
+
| Concluding "no existing seam does this" from a search of your own call names | #4528 searched `notifyExternalFileChange\(` and missed six freshness modules in `clients/`; five detectors ended up wiring their own consumers (#4535). Search by primitive (`docs/pi-lens-fixer.md` "Before code"); the reviewer widens the query (`docs/pi-lens-reviewer.md`, #4536) |
|
|
831
|
+
| Importing `dist/` from a script a workflow runs before any build | #4525's `scripts/assert-evaluated.mjs` reached `dist/` through `lib/clean-signal.mjs`, so `tool-smoke-prs` would fail on every refresh PR. #4531 pins the import graph with a test and plants |
|
|
832
|
+
| Pinning workflow step shell as text instead of running it | #4531 r1: four mutations of the Swift, APFS and handshake shell survived, including deleting `set +e`. Run the extracted step shell against stubs in a test |
|
|
833
|
+
| Filing gap after gap on one mechanism without an audit | Eleven freshness gaps went into #4532 before anyone asked why there were eleven; the cause was one missing fan-out (#4535). Three issues on one mechanism open a consolidation audit (`AGENTS.md` "Orchestration and delegated work") |
|
|
834
|
+
| Landing with an unresolved bot review thread | #4548 and #4558 merged with open Greptile threads (2026-10-17); each one's disposition arrived or never did, and nothing held the land. Every bot thread gets a disposition reply and is resolved before the merge (step 1 and step 4 of "The loop, per PR") |
|
|
835
|
+
| Pushing a worker tree on a stale "failed" settlement | The #4575 r5 settlement read as failed while its resumed turn was live and about to push (plegma #752). The orchestrator's push-verify now refuses a tree with a live agent process, and its wait loop takes a `turnId`. |
|
|
836
|
+
| Settling a fix round with unpushed commits | #4582 r1 settled with the commits still local and nobody noticed (plegma #753). The settlement hook now prints `UNPUSHED` or `DIRTY` for the tree it just settled. |
|
|
837
|
+
| Switching `closes` to `refs` through a raw `gh pr edit` body edit | The #4581 land was refused because commit `d068be947` still closed #4488. `pr-body.sh` now refuses a body that drops a commit's close keyword, and the orchestrator guard denies raw body edits. |
|
|
838
|
+
| Reading an empty DeepSeek turn as a worker stall and resuming it | Four resumes on one backend exhausted the balance (plegma #751). Two empty turns on one backend mean check the backend or the quota before any resume. |
|
|
839
|
+
| Proving a workflow floor with a test that matched the step's shell text | The step's exit code was never checked, and the body claimed a shared helper had not landed (#4584 review F1/F3). The reviewer caught both under the existing tautological-test and reuse-the-seam rules, and the round moves the case to `tests/scripts/floor-steps-executed.test.ts`. |
|
|
840
|
+
| Taking a local `vitest --shard=3/5` soak as CI's shard 3 | The shard never contained the target file, so four runs were wasted (#4488). The soak now asserts the target is in the set it recovered from CI's own job log before it runs. |
|
|
841
|
+
| Trusting fixers and reviewers to read the bot threads on their own | Greptile threads and code-scanning alerts reached a round only when the orchestrator relayed them (#4566, #4575). The role contracts now carry a conditional read-and-dispose rule; a missing bot review is never evidence, and the reviewer's own pass stands alone. |
|
|
842
|
+
| Leaving the PR watcher down after a context compaction | #4594 sat conflicting with nobody told (2026-10-18). An orchestrator hook now marks a compacted or resumed session and denies tool calls until the watcher runs again. |
|
|
843
|
+
| Resuming a review or fix round without `passthrough: ["gh"]` | A workspace override drops the inherited passthrough (plegma #762), so the #4593 verifier ran with `gh` unauthenticated and could not read CI or threads. The orchestrator's delegate guard refuses such a round. |
|
|
844
|
+
| 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. |
|
|
845
|
+
| 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. |
|
|
846
|
+
| 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. |
|
|
847
|
+
| 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) |
|
|
848
|
+
| 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 |
|
|
849
|
+
| 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` |
|
|
850
|
+
| 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 |
|
|
851
|
+
| 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 |
|
|
852
|
+
| 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 |
|