pi-lens 4.3.0 → 4.4.1

package/docs/pi-lens-fixer.md

@@ -1,109 +1,181 @@
 # Fixer contract
 
-## Mission
-
-- Read the issue, `AGENTS.md`, `docs/pi-lens-subagent.md`, and this contract.
-- Trace the production entry point before naming a seam.
-- Reproduce the defect on the current tree.
-- Implement the smallest root-caused fix.
-- Preserve contributor authorship and leave Git authority to the orchestrator
-  unless the delegation grants it explicitly.
-
-## Standing procedure
-
-### Standard mechanics
-
-- Commit the code as soon as the targeted suite is green, then add evidence in
-  a later commit. A worker can be settled mid-evidence-pass; on PR #3268 the
-  orchestrator had to commit the tree.
-- A whole-module `vi.mock` of a production module must spread `importOriginal`.
-  Run `tests/config/vi-mock-export-sweep.test.ts`.
-- Exact-pin sweeps and merge state: `tests/config/glossary-synonym-sweep.test.ts`
-  (#3279) pins the live retired-synonym identifier population per (term, file)
-  exactly, in both directions. If a change adds or removes one of the pinned
-  identifier uses, run the sweep on the head and on the merge of
-  `origin/master` + head before pushing, then re-pin in the same PR using the
-  sweep's own `UNPINNED`/`STALE` output. On 2026-09-23, two green PRs merged
-  red (#3279's pins predated #3283, leaving master red until #3288), and #3284
-  was red on its own `path` count changes (cue-vet 5→6, dart-analyze 6→4)
-  until an orchestrator trailing commit re-pinned.
-
-### Failure list before code
-
-Before the first edit of any fix, write the list of ways the change could fail
-(the directions the mutation table will later prove) in the PR body. The
-mutation table is that list with transcripts, never a list invented after the
-code. This week's evidence: #3252 r1 shipped an exit table whose inverse
-direction (nonzero WITH findings) was never listed and was caught by the
-reviewer.
-
-Seams are named in the brief before the round; no test is written at an
-unconfirmed seam — a fixer that needs a new seam stops and reports it as a
-finding, not as a test.
-
-A fix round does not deepen: no refactor, no helper extraction, no rename
-beyond the fix's own lines; deepening is its own slice under the owning
-umbrella. #3254 and #3256 stayed inside their briefs; #3178's four rounds show
-the cost of not doing so.
+Read first: the engineering principles (`docs/engineering-principles.md`), then
+`AGENTS.md`, then `docs/pi-lens-subagent.md`, then this contract. Then read the
+issue with its comments (`gh issue view <N> --comments`): its acceptance
+criteria are the contract. Rules the principles or `AGENTS.md` already state
+are not repeated here. Lane mechanics (checkout, `TMPDIR`, push forms, Git
+grants, summary shape) are `docs/pi-lens-subagent.md` "Orchestrator lane
+mechanics"; a brief supplies only `lane=<name>`, scope, and the grant.
+
+## Before code
+
+- Trace the production entry point and reproduce the defect through it
+  (principles §1, "Premise first"). Name no seam before the reproduction; the
+  red reproduction is your feedback loop, built before any theory of the fix.
+- Climb the minimalism ladder before screening against the `AGENTS.md`
+  catalog: the catalog says what must not break, never what to add.
+- Check which open PRs touch your files (`gh pr list`, `gh pr diff`), design to
+  compose, and flag merge order in the PR body. Branch `fix/<N>-<slug>` from
+  `origin/master` unless the brief names a branch. Preserve contributor
+  authorship on a contributor's branch.
+- Write the failure list in the PR body before the first edit (principles §2):
+  inputs, states, orderings, and platforms; a space with two axes is a table.
+  The tests cover that list, not only the happy path. For a change to N of M
+  members, the list also names M, the excluded default, and the planned
+  generalization verdict: *widen in this PR*, *follow-up issue* with its seam
+  group, or *stay specific* with the reason (#3622).
+- When a gate becomes fail-closed, sweep every construction site that reaches
+  it, test doubles included, and prove the sweep with the behaviour suites
+  (#3622).
+- A change on a lifecycle, timing, or identity seam extends or adds a TLA+
+  model in this step (#3802; the rule itself is in `AGENTS.md`). Find the
+  family in `formal/coverage-map.json`, write the invariant the change
+  preserves or tightens, and show the violating config red on the pre-fix model
+  and green after, or carry `TLA+ unaffected: <family> — <reason>` in the PR
+  body. A row is any-of (one listed family's model move or declaration
+  satisfies it); a row of 4+ families only prints a note, except `index.ts`,
+  whose row gates on the lifecycle hook handler a hunk lands in (#3878). The
+  map owner is the lane that adds a `formal/<family>/`: it adds the family and
+  its map row in the same PR, and `validateCoverageMap` reds the Unit tests lane
+  otherwise.
+- Seams are named in the brief before the round. A fixer that needs an
+  unconfirmed seam stops and reports it as a finding, not as a test.
+
+## Scope
+
+- A fix round does not deepen: no refactor, helper extraction, or rename
+  beyond the fix's own lines; deepening is its own slice under the owning
+  umbrella (#3178). Every hunk serves a finding or an acceptance box. Orphans
+  your change created come out; dead code you only noticed goes to the
+  follow-up section.
+- A behaviour-preserving move is its own commit: callers keep exact results and
+  tests stay green; put any behaviour change in a separate commit (#3817).
+- Delete vacuous tests in the files you touch (a case that reds on no
+  mutation, asserts a constant, or duplicates a sibling), with the sweep
+  transcript quoted in `Test assessment`. A redundant test that still guards
+  goes only with the named survivor that covers it.
+- Apply folded review follow-ups per `docs/pi-lens-subagent.md`
+  "Follow-ups", and list filed residuals in one **Residuals** section of the
+  PR body.
 
 ## Evidence
 
+- 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).
+
 - Witness rule (ADR 0007): #1605 owns the witness lanes, and their fixtures
   live under `tests/fixtures/witness/<slice>/`.
-
-- Add a regression test through the production path.
-- Capture the pre-fix assertion failure.
-- Prove the fixed test passes.
-- Mutate or remove every new guard, branch, filter, cap, and fallback; quote the
-  compile-valid red result.
-- Sweep the whole codebase for the defect shape and every enumerable member.
-- Record per-member verdicts, blast radius, affected callers, and bounded
-  observability.
+- A PR claiming it "reduces failures" runs `node scripts/ci-test-diff.mjs <jobA> <jobB>`, quotes its summary, and explains any NEW failures before claiming a reduction.
+- Red-first has one stated exception: when the only red-first path needs broad
+  harness setup, brittle mocks, or a test you would delete right after it
+  proves the fix (shape 7: #1114, #1759), state the exception in `Tests`, name
+  the closest executable check you used, and expect the reviewer to dispute it.
+  A silent omission is a defect.
+- With Git authority, commit the code once the targeted suite is green and
+  after every proven step, before any checkout-based proof; add evidence in a
+  later commit (#3268). Produce a red by restoring only the mutated source path
+  from the pre-fix SHA (`git checkout <sha> -- clients/…`), never `tests`
+  (#3166) and never uncommitted work, and run `git status` after any bulk
+  restore. Without Git authority, use a saved patch.
+- Hand-mutate only the NEW guard, branch, filter, or cap the PR is about, both
+  directions, one row per direction, and quote the compile-valid red. The new
+  test is the only red under at least one mutation. This is the whole PR
+  mutation layer (AGENTS.md, #4005): there is no per-PR Stryker job, comment, or
+  `MUTATION` line, and no survivor triage. The nightly Stryker report on master
+  is exploratory and is not read here. Use bounded hand probes locally; never
+  run a full Stryker campaign in a worktree.
+- Every record the `Observability` section names is asserted by a test in the
+  diff and quoted in the body (#2642, #2647, #2649, #2654).
+- Every behavioural sentence (a docstring invariant, a memo, a registry
+  justification) maps to a test or a probe, or is deleted (#2643, #2654).
+- Name where new state sits in its ladder and what happens to it at
+  `session_start` (#2649, #2654).
+- A measured constant names its measuring command and keeps raw output as a
+  tracked artifact pinned by a test (#3648). Run `git check-ignore -v` on every
+  new artifact path before citing it (#3648).
+- A CI-lane or workflow fix is accepted only when that lane's own run on the
+  exact head completes inside its `timeout-minutes`, with the acceptance
+  surface quoted from its log; any self-bound sits below the job cap by a
+  stated margin.
 
 ## Required checks
 
-- Run `npm run build` before tests and rebuild between mutations.
-- Run targeted tests through the repository's pinned environment. Include every
-  test that mocks or deep-equals a changed module or record.
-- Add `tests/config/` and spawn-heavy lanes for real child or LSP tests.
+- Run every test that mocks or deep-equals a changed module or record, and the
+  spawn-heavy lanes for real child or LSP tests.
+- Before pushing, run `npm run astgrep:self-scan`; the pre-push hook runs the
+  same scan over tracked files, after its build.
 - Reproduce CI-only failures in the CI command shape.
-- Use the exact npm pin in `package.json` for lockfile changes.
-- Add one `.changelog/<slug>.md` fragment for code changes. Never edit
-  `CHANGELOG.md`.
+- Run `npx oxfmt --check` on every touched file with the symlinked pinned
+  devDependency. Never `npm install oxfmt --no-save`: it replaces the linked
+  `node_modules`.
 - Run release-QA end to end when a release-QA row changes.
-
-## Test screens
-
-- Enter through the real production function.
-- Do not use setup-echoing, implementation-mirroring, or mock-only assertions.
-- Do not use ambient stack/caller inspection in doubles.
-- Restore env, timers, cwd, and module state.
-- Make skips explicit and visible.
-- Use independent expected values and behavioral assertions.
-- Keep timing bounds near measured fixed and regressed values.
-- Make every PR-body test id grepable in the tree.
+- Run the reviewer's standing probes (`docs/pi-lens-reviewer.md`) that the diff
+  can trip, and quote their output in the PR body.
+
+## Fix rounds
+
+- On `FIX ROUND` findings, reproduce each finding before fixing it, add a
+  red-first test for every behavioural fix, rebuild, re-run the targeted suites
+  plus anything the findings touched, and push the same branch. If the PR reads
+  DIRTY, merge `origin/master` with additive resolutions and screen the merged
+  result semantically: master may have moved the seam you built on.
+- A reviewer's prescribed remedy is a hypothesis. Test it against your own
+  table of the seam; if it is insufficient, ship the correct shape and quote
+  the red the prescription alone leaves (#2642).
+- When a verify finds a NEW defect on your fix, the next round carries a table
+  enumerated from grep: every writer and reader of the key with the exact
+  expression that derives it, and every call into an external sink or timer
+  with "if it throws" and "if it never returns" columns (#2642, #2649). Fix
+  everything the table exposes; a table that finds nothing is quoted too.
+- Name every governance exemption a round adds, with the reason and whether it
+  is a registration or silencing; it is a finding until the reviewer clears it
+  (#2654).
+- Spot-check one prior round's mutation on the new head (#2583).
+- Re-read the changelog fragment for any claim the round retracts (#3155), then
+  add an honest review-round section to the PR body.
+
+## Before the report
+
+Re-climb the minimalism ladder on what you built. Challenge anything
+unnecessary or unverified with a probe, delete what can go, and simplify what
+remains: prefer deleting over simplifying, simplifying over optimizing, and
+optimizing over automating. If the diff survives, leave it alone; churn is not
+rigor (#2599).
 
 ## Handoff
 
-- Without Git authority, leave changes uncommitted.
-- Write root-level `PR_BODY.md` and `COMMIT_MSG.txt`; keep both untracked.
 - The PR body is the whole `.github/PULL_REQUEST_TEMPLATE.md`, every
   heading present in order: `## Why` (one sentence), `## Notes for the
   reviewer`, `## Change outline`, `## Summary`, `## Type of change`,
   `## Area`, `## Checklist`, `## Tests`, `## Blast radius`,
-  `## Observability` (a record literal from the runtime diff, or exactly
-  `No new failure path; no record added.`), `## Class sweep`, and
-  `## Test assessment`. A brief that names only some headings does not
-  shorten this list.
+  `## Observability` (a record literal from the runtime diff, `none: <reason>`,
+  or exactly `No new failure path; no record added.`, which a new decision
+  branch on a session, lifecycle or delivery seam refuses, #3875),
+  `## Class sweep`, and `## Test assessment`. A brief that names only some
+  headings does not shorten this list. The closing keyword lives in the body;
+  GitHub ignores it in a title.
 - Run `node scripts/check-pr-body.mjs --lint-local PR_BODY.md` and
   `node scripts/check-changelog-fragments.mjs` before the hand-back; both
-  must pass, and the hand-back quotes them. A changelog fragment is
-  `---` / `section: <Added|Changed|Deprecated|Removed|Fixed|Security>` /
-  `---` / blank / one `- ` bullet. (Four of six Luna PRs on 2026-09-23
-  redded the PR-body and changelog gates on the first head; the fixes were
-  all mechanical.)
-- The hand-back carries the commit SHA; a dirty tree is an incomplete
-  round.
-- Include every red, mutation result, skipped check, and environment block.
-- Answer each finding id with `fixed`, `not fixed`, or `withdrawn (reason)`.
-- Report verdict, changed files, totals, and unverifiable checks.
+  must pass, and the hand-back quotes them. A red `PR body (advisory)` check is
+  a fix-before-review item. A changelog fragment is `---` /
+  `section: <Added|Changed|Deprecated|Removed|Fixed|Security>` /
+  `audience: <user|internal>` / `---` / blank / one `- ` bullet. New
+  `audience: user` fragments must begin with a bold lead of at most 100
+  characters, excluding issue references; internal fragments are exempt.
+  `audience` is
+  required: `user` is anything a pi-lens user or agent can observe (tools,
+  diagnostics, messages, config, install, performance, a fixed bug they could
+  hit); `internal` is CI, tests, `formal/`, contributor docs, orchestration, and
+  refactors with no observable change. `npm run changelog:check` checks the
+  rollup, not fragments (#2456).
+- Every code fact in the PR body is a `` `path:line` `` citation the check
+  verifies: the file must be in the committed tree (never an untracked or
+  git-ignored path, which CI cannot read), and a fenced quote after it must
+  match within ±20 lines. Every test, probe, or fixture id in a body table is a
+  grep-able `it(` title or file name in the tree (#2868, #2877).
+- With Git authority, the hand-back carries the commit SHA; a dirty tree is an
+  incomplete round.
+- Report outcome first: branch, PR URL, the root cause in two sentences,
+  red-run evidence, test totals, every mutation result, skipped check, and
+  environment block, and what the orchestrator must decide (merge order,
+  deferred scope, follow-up issues).

package/docs/pi-lens-investigator.md

@@ -1,54 +1,102 @@
 # Investigator contract
 
+Read first: the engineering principles (`docs/engineering-principles.md`), then
+`AGENTS.md`, then `docs/pi-lens-subagent.md`, then this contract. Then read the
+issue and the requested evidence surface.
+
 ## Mission
 
-- Read `AGENTS.md`, `docs/pi-lens-subagent.md`, the issue, and the requested
-  evidence surface.
 - Keep the worktree and Git state read-only.
 - Define the symptom as an answerable question with time window, sessions, and
   build in scope.
 - Reproduce through the reporter's production entry point before naming a seam.
-- Deliver a proven diagnosis and one concrete next step; do not implement a fix.
+- Deliver a proven diagnosis and one concrete next step; a plausible story is
+  not a diagnosis. Implement only a contained fix the brief asks for, under
+  `docs/pi-lens-fixer.md`; otherwise, or when the root cause is architectural,
+  stop and return a fixer brief.
+
+## Evidence sources
+
+- `~/.pi-lens/latency.log` and its `.1` rotation: per-touch records
+  (`lsp_touch_file`, `lsp_aux_wait_outcome`, `availability_decision`,
+  `lsp_scanner_coverage_gap`, breaker and deferral events). Rotation is by size:
+  `PI_LENS_MAX_LOG_SIZE_MB` defaults to 10 (`clients/log-cleanup.ts`), which is
+  hours under active dogfooding. Read the oldest timestamp in `.1` before
+  trusting the pair to span your window.
+- `~/.pi-lens/cascade.log`, `sessionstart.log`, and `tree-sitter.log`: cascade
+  runs, lifecycle, and grammar events.
+- Per-project `worklog.jsonl` and `~/.pi/agent/sessions/`: what the agent was
+  told and did, and when.
+- `pi-analyze` `timeline.ndjson`, when the run produced one: the host-side
+  view.
+- The repository: grep the producer of any record before trusting its fields.
 
 ## Investigation method
 
-- Correlate telemetry with `turnId` or another stable identifier, never time
-  alone.
-- Read the producer before trusting a record's label.
-- Separate worker, daemon, host, cache, build, and environment behavior.
-- Rank falsifiable hypotheses with evidence for and against each.
-- State the observation that would settle each remaining hypothesis.
-- Count a representative population and sweep every member of the root-cause
-  pattern.
-- State blast radius, missing observability, and any unbounded resource.
+- Correlate telemetry with `turnId`, the session id, or the run or boot id the
+  records carry, never wall-clock proximity alone.
+- Attribute the build: date-map evidence against merge times, since the
+  installed pi-lens may predate the fix under evaluation. A record type only one
+  build emits is the cheapest vintage marker.
+- Read the producer before trusting a record's label; a record's `filePath` is
+  not always the subject that produced the reason (#1550).
+- The dispatch record outranks an agent's self-report; the transcript is
+  hearsay.
+- Separate worker, daemon, host, cache, build, and environment behavior, and
+  model-side from host-side failure. For a blocked edit,
+  `hostWouldApplyOldText` (`clients/host-edit-normalize.ts`) records the
+  counterfactual: `wouldApply: true` is a false block by pi-lens, `false` is a
+  genuine miss by the model.
+- Count rates over the window with the denominator named. A missing field is
+  a finding: name the record that would prove it.
+- Classify known against new: check the `AGENTS.md` catalog, open umbrella
+  issues, and recent merges. "Known, fixed, awaiting deploy", "known, open, new
+  instance", and "new bug" carry different next steps.
+- Rank falsifiable hypotheses with evidence for and against each, and state
+  the observation that would settle each one.
+- Sweep a representative population and every member of the root-cause
+  pattern. State blast radius, missing observability, and any unbounded
+  resource.
 - For LSP, dispatch, cache, runner, or tool findings, name the covered registry
   entries and include one non-TypeScript case when the rule is language-neutral.
 
+## Reproducible behavior
+
+When the symptom reproduces, the loop comes before the reading. Build the
+tightest loop that goes red on the symptom (a failing test, a minimal driver, a
+differential run), confirm it matches the reporter's exact symptom, and
+minimize it until every element is load-bearing. Tighten it for speed, signal,
+and determinism; raise the reproduction rate of a nondeterministic symptom by
+looping, parallel drivers, or stress. Write three to five falsifiable hypotheses with predictions
+before testing any. Instrument surgically, tag the instrumentation, and remove
+all of it before reporting; loops live in your worktree and are reverted. The
+report recommends the regression test's seam: the one that captures the bug's
+pattern, not the spot where it surfaced.
+
 ## Evidence rules
 
 - **Already-shipped check before naming a slice:** for every umbrella member the
   brief cites as remaining work, grep the current tree and the closing PRs and
   state shipped, partially shipped, or not shipped with `file:line`; a first
-  slice may name only work whose absence was verified on the current head.
-  The 2026-09-22 primitives brief named three scanner filter blocks as the
-  #1461 first slice even though #1622/#1625/#1628 had already removed them;
-  the fixer found the premise error in PR #3264 and the #1892 comment on
-  2026-09-23.
-
+  slice may name only work whose absence was verified on the current head
+  (#1461, #3264, #1892).
 - A reported defect is not confirmed until the production-path probe is red on
   the current tree for the reported reason.
 - A probe must distinguish competing hypotheses, use independent observations,
   and avoid setup-echoing or mirrored predicates.
-- Prefer real stores, sinks, coordinators, binaries, and host harnesses. Mock
-  only true process or host boundaries.
 - Preserve commands, outputs, exact paths, build identity, and timestamps.
 - Use concise, active, plain prose.
 
 ## Handoff
 
-- Write the diagnosis to the requested root-level artifact.
-- If issue access is granted, post the diagnosis to the tracking issue; a file
-  alone is not durable evidence.
-- Report `confirmed`, `refuted`, or `blocked` for each hypothesis.
-- If implementation becomes necessary, stop and return a fixer brief to the
-  orchestrator.
+- Verdict first: the root cause, or the ranked hypotheses when the evidence
+  does not settle it, with the two or three trimmed log lines that prove it.
+  Then rates and counts, build attribution, known-versus-new mapped to issue
+  numbers, and `confirmed`, `refuted`, or `blocked` for each hypothesis.
+- Write the diagnosis to the requested root-level artifact. With issue access
+  granted, post it on the tracking issue; a file alone is not durable evidence.
+- The next step is one of: an issue to file (title, body, labels, and
+  acceptance criteria ready to post, after showing no open issue covers the
+  shape), a fix to dispatch, or a measurement to wait for. Without `gh` write
+  access, the orchestrator posts it. Write an issue so a fixer needs no further
+  investigation.