pi-lens 4.3.0 → 4.4.1

package/docs/pi-lens-merge-policy.md

@@ -0,0 +1,736 @@
+# pi-lens merge policy — role contract
+
+Run the review → verify → merge policy over one or more open PRs: landing a
+PR, babysitting the merge queue, processing a review backlog. It encodes the
+standing quality gates so any session applies the same discipline.
+
+> Source of truth for every rule below is `AGENTS.md` ("Orchestration and
+> delegated work", plus the defect catalog). This file
+> is the procedure and the record; on any conflict AGENTS.md wins. It replaces
+> the former `merge-train` skill (#3837); the merge-train lane that skill also
+> described is retired.
+
+The policy that landed the 2026-08-17 arc (11 PRs, every one adversarially
+reviewed, zero unreviewed merges). Apply it to each PR in the queue.
+
+A fix to a CI lane or workflow is accepted only when that lane's own run on
+the PR's exact head completes inside its `timeout-minutes`, with the
+acceptance surface quoted from that run's log. Any self-bound inside the lane
+must sit below the job cap by a stated margin so the loud-failure path is
+reachable.
+
+Every PR body starts with `## Why`, `## Notes for the reviewer`, and
+`## Change outline`, followed by the existing `## Summary`, `## Tests`,
+`## Blast radius`, `## Class sweep`, and `## Observability` sections. The
+change outline is the changed symbol's caller/callee tree with `+`/`-` on
+moved lines; include only structural views that changed.
+
+## The loop, per PR
+
+1. **Review.** Spawn `pi-lens-reviewer` (worktree isolation) with the PR
+   number, a one-paragraph summary of the claim, and any PR-specific attack
+   angles. Self-authored and small PRs get reviewed too — the depth follows
+   the review tier below, never the priority label.
+2. **Fix rounds.** Send findings back to the PR's original author agent when
+   its worktree survives (SendMessage — cheapest context); otherwise spawn
+   `pi-lens-fixer` on the branch with the findings inlined.
+   **Since #2486, `SubagentStop` REAPS the stopped agent's own worktree**
+   (maintainer decision, 2026-09-02, reversing the earlier "never removes
+   here" rule, which left ten stale trees in one afternoon). So by default an
+   agent's tree is gone the moment it finishes, and SendMessage to it lands on
+   a branch with no checkout. Its branch survives — a tree is never removed
+   unless its HEAD is already in an `origin/*` ref — so nothing committed is
+   lost and a fresh `pi-lens-fixer` on the branch always works. If this
+   session intends to resume fixers by SendMessage, export
+   `PILENS_HYGIENE_KEEP_AGENT_TREES=1` for the session (or add
+   `--keep-agent-tree` to the registered hook) and the reap is off.
+   Kept trees are then reaped by the `SessionStart` sweep —
+   which runs on `startup` and `resume` only, not on `/clear`, compaction or a
+   fork — once they have been idle ≥30m and are clean and pushed. Idle is
+   measured from the checkout directory and the worktree's HEAD (and its
+   reflog), never from the git index, so the sweep's own dirty check cannot
+   make a finished tree look busy.
+   A tree with uncommitted work, or with work not yet on an `origin/*` ref, is
+   never removed at any age, by any sweep — so a fix round in flight is safe by
+   its own state, not by the clock.
+3. **Verify.** The SAME reviewer verifies each fix round with its own probes.
+   Do not take the fixer's word; do not swap reviewers mid-PR. A reviewer's
+   worktree is an `agent-*` tree too, so once its report lands the tree is
+   clean+pushed and `SubagentStop` reaps it exactly like a fixer's — a
+   SendMessage resume finds no checkout, same as above. Recreate it: the
+   merge-train practice is a FRESH reviewer worktree per VERIFY round, not a
+   kept one. Continuity is the reviewer AGENT (SendMessage still reaches the
+   same identity, so the same judgment and probes carry over); the checkout
+   under it is expected to be rebuilt each round, not preserved. Do not set
+   `--keep-agent-tree` / `PILENS_HYGIENE_KEEP_AGENT_TREES=1` merely to dodge
+   this — that decision stays off by default (see step 2).
+4. **Merge gate.** Merge only when: verdict is merge-ready; every gating check
+   genuinely EXECUTED and passed on the exact head SHA
+   (`node scripts/ci-verdict.mjs <pr-number|sha>` — a DIRTY PR silently skips
+   them, absent is not green); every failing check
+   was read and judged (infra failures — codeload 429/503, SARIF-upload
+   errors, Initialize-CodeQL outages — may be waved through only with the
+   log read and the judgment recorded). A PR that is green on its head but
+   whose merge with `origin/master` was not tested against the exact-pin
+   sweeps is not green — run the sweep on the merge before merging. Apply
+   AGENTS.md's one mutation layer (#4005): new-guard proof and demonstrated
+   correctness gaps gate the merge. `ci-verdict` prints no mutation line, and
+   the nightly Stryker report is not a merge input.
+5. **Merge.** `gh pr merge <N> --merge` (merge commit, repo convention).
+   If "not up to date", `gh api -X PUT .../pulls/<N>/update-branch`, wait for
+   CI, re-gate, merge. On GitHub 503s: retry with backoff, never switch to
+   raw-API merge endpoints.
+   Alternative, once the verdict is in: arm GitHub auto-merge
+   (`gh pr merge <N> --auto --merge`) and let it land the PR when the required
+   checks are green on the current head. Steps 1 through 4 are unchanged: arm
+   it only after the review verdict and with the pushed SHA verified.
+6. **After each merge.** Master moved: check other open PRs for BEHIND/DIRTY,
+   check in-flight agents for file overlap with the merged diff and nudge
+   affected ones to merge origin/master before their next push.
+   Then prune the lane — and ONLY the lane: the merged-ness test is "this
+   tree's branch is the head of the PR just merged" (`gh pr view <n> --json
+   headRefName`), never `merge-base --is-ancestor`: a live fixer's branch
+   with no commits yet passes the ancestor test, and on 2026-09-06 that
+   removed #2358's tree with its uncommitted work. `git worktree remove` every tree on the merged
+   branch (fixer AND reviewer trees, wherever they were created) and delete
+   the merged local branch. A lane's tree lives until its PR merges, not
+   after — the orchestrator owns this step; the reaper only sees
+   `.claude/worktrees/agent-*`, and on 2026-09-06 twenty-one merged trees
+   were still standing at the regroup.
+
+## Merge queue (once the maintainer enables it, #3754)
+
+The repository merges through GitHub's merge queue after the maintainer applies
+the settings in `docs/merge-queue-rollout.md`. Until then every rule above is
+unchanged. With the queue on:
+
+- **Enqueue, do not merge.** `gh pr merge <N> --merge` (add `--auto` while
+  checks are still pending) enqueues the PR: `gh` routes through the queue when
+  the base branch requires one, and a direct merge is refused (step 5). The queue tests the PR merged onto the
+  LATEST master in a `gh-readonly-queue/master/pr-<N>-<sha>` ref via a
+  `merge_group` run of `ci.yml` and `lint.yml`, then merges it with a merge
+  commit.
+- **In the queue is a state, not absent and not done.** `ci-verdict <pr>` on a
+  queued PR with a green head exits 3, kind `in-queue`, naming the queue state
+  and position (`--wait` keeps waiting). A PR that was ejected after a FAILED
+  queue run exits 1, kind `failed`, reason `merge queue run failed and ejected
+  the PR`, with the failing job, step and test lines read from the
+  `merge_group` run. Treat that exactly as a red PR run: fix, push, enqueue
+  again. A failure from before the head's last push is an earlier head's and is
+  ignored. The queue read is one GraphQL call each time a poll finds the head's
+  own checks green (a red or still-running head costs none); an in-queue PR
+  stays pending, so under `--wait` the queue is re-read once per poll until it
+  merges or ejects. Without a queue on master it is the only extra call.
+- **Retire update-branch and BEHIND.** The queue tests against the latest
+  master itself, so `gh pr update-branch`, "not up to date" retries, and the
+  `gh run rerun` replays-the-old-merge-commit workaround are moot. Worse, any
+  push to a queued PR re-runs every check and EJECTS it;
+  ci-verdict's update-branch hint reads "do not update-branch" when master has a
+  queue. The pre-queue rules for retargeting (push to re-arm CI) still apply to
+  the PR's own `pull_request` run.
+- **What still gates enqueueing.** The PR's own head must still be green:
+  the same exit-0 merge gate as step 4, then enqueue. The `merge_group` run
+  re-checks the same required checks on the merge commit; a check that is
+  required but never reports there (a workflow without a `merge_group`
+  trigger) stalls the queue, which `tests/config/merge-queue-workflows.test.ts`
+  pins.
+- **No competing merge lane.** The `train:approved` lane that merged through
+  the REST merge API was retired (#3837); every merge now goes through
+  `gh pr merge` (auto-merge or direct), which the queue intercepts when the
+  base branch requires one.
+
+## Queue ordering
+
+Order by dependency, not age: a PR whose schema/API another PR must consume
+merges first (the consumer then rebases and wires the new surface). Two PRs
+editing the same file get an explicit order decided up front. Log-schema
+changes must extend exact-key pins (`BASELINE_KEYS`-style), never loosen them.
+
+## Quota gate (orchestrator)
+
+Before ANY new dispatch (not a fix round on an open PR): know the account's
+5h and weekly usage. Above 75% of the 5h window or 85% of the weekly window,
+no new work — finish in-flight lanes and merge on green. The numbers are
+readable live: `GET https://api.anthropic.com/api/oauth/usage` with the OAuth
+token from `~/.claude/.credentials.json` (`anthropic-beta: oauth-2025-04-20`)
+returns `five_hour.utilization` / `seven_day.utilization` and reset times; the
+`~/.claude/hooks/quota-gate.mjs` PreToolUse hook on `Agent` reads them and
+blocks dispatch above the thresholds (no hand-written fallback;
+`QUOTA_GATE_OVERRIDE=1` lifts it when the maintainer says so). Read the meters at session start and before
+every refill; state them in the lane ledger. Standing rule from
+2026-09-03, lifted only when the maintainer says so.
+
+## Brief contract (orchestrator)
+
+Before dispatching any issue that adds a shared helper or seam: grep for
+same-shape siblings yourself and write the fold into the SAME slice, or write
+the sibling list, the reason folding is unsafe in one PR, and the follow-up
+issue into the brief. AGENTS.md's net-count rule binds the brief author; the
+fixer and reviewer only enforce what the brief scoped. #2530 shipped a fifth
+bound helper because the brief deferred the fold without a reason.
+
+## External reports (orchestrator)
+
+The contract lives in AGENTS.md, "Issue triage (standing rule)" — assess the
+report against the code before accepting or dispatching, ask the one or two
+facts that would change the design, **do not dispatch work that depends on an
+unanswered load-bearing question**, mirror the answer on the issue and point
+the worker there rather than at a paraphrase, and cite the reporter's reasoning
+as authority. Read it there; this section only points at it.
+
+The train-specific consequence: an external lane's first dispatch is often
+worth delaying by one exchange. On 2026-09-12 a fixer was dispatched on #3000
+between asking the question and receiving the answer, and the answer invalidated
+the brief's central premise — the correction cost a mid-flight `plegma_send` and
+rework that waiting ten minutes would have avoided entirely.
+
+## Filing issues (orchestrator)
+
+Every `gh issue create` carries one TYPE label, at least one `area:*`, and
+exactly one `priority:p1|p2|p3` (AGENTS.md #1676 rubric). The priority labels
+were found deleted from the repo on 2026-09-03 and recreated (#2553); an
+issue filed without one is a triage defect, not a shortcut.
+
+Every reviewer **follow-up issue** generalization verdict is filed and assigned
+to a seam group on the tracking queue in the same turn. At each regroup, scan
+merged PRs for subset-shaped changes that lack a generalization verdict.
+
+Before filing a review follow-up, apply the standing fold rule: fold same-seam
+or same-file items that are about one commit and need no maintainer decision
+into the same PR. Contract-only folds are trailing commits with no
+re-verification; small code folds carry a red-first test and return to the same
+reviewer. File only different-seam, blocked, decision-dependent, untouched
+pre-existing, or risk-class-changing items, as one consolidated issue per PR.
+
+## Round-count rail (orchestrator)
+
+When a verify round reports that a fix round introduced a NEW defect on the
+same record or seam (not merely left one), the next fix brief opens with
+AGENTS.md's state-space step — invariants, writers × axes, the cell list —
+written into the PR body BEFORE any edit, and the fixer is Opus. Never send a
+third patch-only round: #2528 went r2 → r3 → r4 on one cache record, each
+round fixing three findings and adding two, until the model was demanded.
+
+## Orchestrator invariants (any orchestrator, not only Claude)
+
+These are the habits the train depends on. They live here, not in any one
+operator's private notes, so a different orchestrator can run the same train.
+
+- **Contracts move in the same session.** When a review or a dogfood finding
+  reveals a defect CLASS (not an instance), add a numbered shape to AGENTS.md's
+  catalog with the issue ref and a one-line screen, extend the fixer's screen
+  list, and cite the number in the next brief — before the next dispatch. "To
+  err twice is not the mark of a wise man." (2026-09-03: shapes 28–36 came out
+  of one day's reviews this way.)
+- **Second instance of a catalogued shape opens the consolidation lane, not a
+  third instance fix (2026-09-09).** The trigger is the shape recurring at all,
+  not only twice in one session: when a review, an issue or a dogfood finding
+  is the second member of a shape already in AGENTS.md's catalog, the
+  orchestrator files the consolidation lane BEFORE the second instance merges,
+  with three fixed deliverables: one seam every consumer calls, one log line
+  per resolution (which value was chosen and why, throttled once per key per
+  session), and one bounded degradation record for the fallback path. The
+  record: #2691 (yamllint cwd) and #2756 (Prettier ignore cwd) were shape 40
+  twice in one week; each was fixed at its own seam with no log line, and the
+  maintainer had to ask for the seam (#2777). "Contracts move in the same
+  session" covers the catalog row; this rule covers the code.
+- **An external bug's first round is the probe, not the fix (2026-09-09).**
+  For any bug reported from outside (or any bug whose symptom is a tool
+  verdict), the first delegation is an investigator or a fixer whose FIRST
+  deliverable is the reporter's symptom reproduced through the production
+  entry point (the tool handler / MCP tool, not a seam beneath it), red on
+  master, before any state-space table or edit. A fix brief that names a
+  suspected seam is a hypothesis and says so. The record: #2776 spent seven
+  fixer rounds on `clients/lsp/client.ts` (pull-vs-push classification) —
+  each internally consistent, each verified — before a premise probe through
+  `LSPService.touchFile` showed master already returned the pushed
+  diagnostic; one investigator round through `createLspDiagnosticsTool`
+  then found the real cause in `tools/lsp-diagnostics.ts` (primary/auxiliary
+  partition by `diagnostic.source`). Principles §1 "Premise first" already
+  said this; the train had been dispatching fixers on the orchestrator's guess.
+- **Every "should have been caught by" names a nightly or smoke row, and
+  the row is filed the same day.** A detection retrospective that ends in
+  prose is not a retrospective. #2776 (emmylua_ls declares pull diagnostics
+  but only pushes → false "confirmed clean") was reachable by a
+  declared-vs-observed channel probe the capability matrix never ran, and by
+  the custom-`lsp.servers` population the matrix never covers.
+- **Brief pre-flight by touched surface (2026-09-09).** Before dispatching a
+  fixer, read what the fix WILL touch and put the matching dependents into the
+  brief's required test set. Every row below cost at least one extra round
+  today because the fixer ran only "targeted files":
+
+  | Fix touches | Brief must name |
+  |---|---|
+  | a new export on a module that has `vi.mock` doubles | every test file that mocks that module (`grep -rl 'vi.mock(".*<module>' tests`), run them all — #2782 r1: 30 reds in 6 files |
+  | a field on a durable or shared record (cache entry, diagnostic, ledger row) | old-record parse proof, cache schema version, and every test that deep-equals or snapshots the record — #2783 r1/r3 |
+  | a test that spawns a real child (LSP fake server, tool smoke, installer) | the lane admission (header + `vitest.config.ts` project + coverage baseline) and `tests/config/` — #2783 r5 |
+  | a new fixture under `tests/fixtures/` | the fixture-contract sweeps for that directory (style-preserving, population guards) — #2782 r2 |
+  | 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 |
+  | 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` |
+  | 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 |
+  | 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 |
+  | a whole-tree docs restructure of `AGENTS.md` | every governance test that reads `AGENTS.md`, with markers on their own lines — PR #3265 r1 |
+  | a raw poll in a test | the flake-shape ratchet; the fix is the governed wait, never a header admission — #2781 r1 |
+  | 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 |
+
+- **Sandbox by test shape (2026-09-09).** A lane whose tests spawn children
+  (LSP fake server, tool smoke, installer, formatter wire) is dispatched with
+  the runner's full-access mode from round 1. #2781 spent four rounds with a
+  fixer that could not run its own wire tests and reasoned about ordering
+  instead of observing it; the first full-access round found the cause in
+  one pass.
+- **A CI-only red is reproduced in the job's shape before any fix.** Replicate
+  the job env (the `npm test` PATH prefix with `node_modules/.bin`, a pinned
+  `HOME`, no `PI_LENS_HOME`) and trace the leg that differs; a fix that only
+  passes under `node_modules/.bin/vitest run` is a guess. #2775 carried one
+  CI-only red through three rounds until round 5 traced it to the npm PATH
+  prefix resolving the dev-dependency `oxfmt` past the mocked `which`.
+- **Follow-up rounds go to the same worker by send, not a fresh delegation,**
+  while its handle is alive: it keeps the diff and the reasoning, and the
+  brief shrinks to the findings. Release only when the lane moves to review.
+  A fresh worker on a resume loses uncommitted work.
+- **Release a reviewer handle only after reading a merge-ready verdict.** A fix
+  round resumes the SAME reviewer via `resumeFrom` with the model pinned. Twice
+  this week (PRs #3263 r2 and #3261 r2), release ran in the same batch as the
+  read and continuity was lost.
+- **Fleet inventory at every settlement.** A one-shot watch misses anything
+  that settles while it is disarmed: after each settlement,
+  list live workers and read every `done` handle not yet consumed. Two lanes
+  sat finished for 90 minutes today.
+- **Keep a lane ledger.** One file, one row per lane: issue/PR, worker id,
+  round, state, head SHA, merge-order note, and for bug lanes
+  `caught by / should have been caught by`; a header line with the quota
+  reading and the merged list. Update it on every dispatch, report and merge.
+  It is what survives a context reset. `state` is one of exactly:
+  `not started`, `fixing rN`, `waiting on CI`, `waiting on review`,
+  `waiting on verify`, `blocked`, `ready to merge`, `merged`,
+  `needs user decision`, `held` — a fixed vocabulary so a resumed session
+  (or a different orchestrator) can build the status table without reading
+  the transcripts, and so "needs user decision" and "held" are visible as
+  rows rather than buried in prose. (Borrowed 2026-09-07 from the heartbeat
+  classification in aromanarguello/roman-skills `orchestrate-lane`.)
+- **A lane's worktree lives until its PR merges.** Pruning it after a report
+  makes the owning worker un-resumable, so every fix round then costs a fresh
+  worker. Prune on merge, or when the lane is abandoned.
+- **Scope changes are mirrored on the issue before they are sent.** A fixer
+  cannot verify a mid-task `SendMessage`; it CAN verify an issue comment.
+  Post the comment first, then send the message pointing at it
+  (`docs/pi-lens-subagent.md` tells every worker to check). Unmirrored
+  additions are declined by design.
+- **Dependabot PRs merge on real checks, no issue needed (maintainer,
+  2026-09-07).** The PR-title issue-ref gate is a policy check this train
+  applies to human PRs; a bump title can never carry a ref. Merge order: one
+  at a time (each merge dirties the rest; dependabot rebases them itself);
+  gate on Lint, Unit tests and every non-advisory check on the exact head;
+  pr-metadata.yml itself skips "PR title", "PR body (advisory)" and
+  "Close-keyword syntax" for dependabot (2026-09-09, refs #2714), so nothing
+  needs hand-ignoring; hold anything red on a real check
+  with a comment naming the check (2026-09-07: tsls 6 needs a Node-floor bump, biome
+  fails the install test, vitest 5 fails four gates; a bump whose install
+  script is pinned by `allowScripts` needs the pin moved in a maintainer
+  commit on the bump branch). A major bump with peers (vitest + coverage-v8)
+  lands together or not at all.
+- **Detector, ratchet and governance-sweep authoring goes to Opus from
+  round 1.** Their correctness lives in parsing edge cases, exactly where the
+  smaller model loses: #2693 took two Sonnet rounds (~720k tokens) on a text
+  scanner before the rail sent round 3 to Opus, which rewrote it on the AST
+  and closed in two rounds.
+- **Brief shape for a fixer.** Issue/PR number and head; the checked-out
+  branch; the exact findings with file:line, the reviewer's probe to reproduce
+  FIRST, and the remedy shape the maintainer chose; what to fold (net-count)
+  and what stays out; the suites to run (named files + the mechanical
+  governance selector + every tests/config file); the observability record to
+  name; "no agents, foreground runs, one CI read, no monitors". Brief a
+  reviewer with the PR number, the claims as the fixer stated them, and the
+  attack angles that matter for THIS diff; ask for a verdict first.
+- **Round routing.** Fix rounds that only apply a reviewer-prescribed remedy
+  with quoted reds merge on green (CI read on the exact head, both required
+  checks, mergeable state). Rounds that add mechanism, touch session or
+  lifecycle semantics, or rewrite a guard get a fresh verify. Classify the
+  round by its worst finding, not its count: a round whose findings are all
+  contract (body text, docstrings, a record added WITH its test, a test
+  added for an existing behaviour) merges on green — #2647 r2 is that shape;
+  a round with one behaviour finding (a verdict, a guard direction, a
+  lifecycle hook, a failsafe) gets the same-reviewer verify — #2649 r2 and
+  #2654 r2. Say which in the fixer brief so the reviewer is not re-armed by
+  reflex. A verify that
+  reports a NEW defect triggers the round-count rail above.
+- **Retargeting a PR's base does not re-arm CI.** `ci.yml` fires on
+  `opened`/`synchronize`/`reopened`; `gh pr edit --base` is an `edited`
+  event, so the required checks stay ABSENT and `ci-verdict` reports "absent,
+  treating as pending" — exit 3, not 0; the "exit 0" first recorded on #2664
+  was `$?` read after a `| tail`. After a retarget, push a commit or
+  close/reopen. Read the final `ci-verdict: exit <N> (<kind>)` stdout line,
+  never `$?` after a pipe (`; echo $?` on its own line, before any pipe, is
+  also fine). The merge loop is
+  `node scripts/ci-verdict.mjs <pr> --wait <seconds>` — read its final line:
+  0 merge, 3 still pending (re-arm the wait), anything else read the table. Never
+  text-match the table for `failure`: advisory rows (PR body, Vale)
+  print `failure` while the verdict is green, and on 2026-09-07 that stopped
+  the #2692 loop on a green PR.
+- **Maintainer trailing commits** are for intent-free deltas only (a literal
+  NUL byte, a false comment, a missing PR-body heading); anything that changes
+  what code MEANS goes through a fix round.
+- **Mechanical-only verdict (2026-09-07).** When EVERY finding in a review or
+  verify is intent-free — a PR-body census the reviewer corrected, an inverted
+  body sentence, a heading, a literal, a comment — the orchestrator applies
+  them as trailing commits and merges on green: no fixer resume, no re-verify.
+  That is one resume saved per such PR. One finding that changes what code
+  means, however small, makes it a fix round; a fix round that exists anyway
+  carries the mechanical findings with it (#2693 r2 carried F3–F5). Borrowed
+  from the auto-fix-mechanical rule in aromanarguello/roman-skills
+  `final-review`; NOT borrowed from it: auto-fixing null checks, error
+  handling or cleanup hooks, which change meaning.
+- **Allocate the catalog number at MERGE, not at dispatch (2026-09-15).**
+  AGENTS.md's defect-shape catalog is a markdownlint MD029 ordered list: the
+  number is the list position, so dispatch-time reservations create a gap on
+  branches whose holder has not merged. The orchestrator owns allocation; a
+  lane may draft a shape but must not claim a number. At merge, insert or
+  renumber the shape at the next valid sequential position and recheck the
+  whole catalog. This prevents concurrent lanes from colliding without
+  shipping a gap.
+- **On a CROSS-REPOSITORY PR, `action_required` is not `absent` (2026-09-12).**
+  A fork PR's workflow runs sit unapproved until a maintainer approves them
+  (GitHub reports them as `status: completed`, `conclusion: action_required`,
+  with no CI check-run rows), so the required checks read as absent and the
+  verdict is pending. Absent because CI has not registered yet and absent
+  because nobody approved the run look identical in the verdict table and are
+  hours apart in remedy. `node scripts/ci-verdict.mjs <pr>` now tells them
+  apart (#3694): when the verdict is otherwise pending and required checks
+  are absent, it prints `awaiting fork approval` with one
+  `gh api -X POST repos/<owner>/<repo>/actions/runs/<id>/approve` per run. It
+  never approves; approving is the maintainer's call. A head that is green or
+  failing keeps that verdict whatever stale `action_required` runs it carries.
+  #2983 sat unapproved while the lane read it as a slow queue.
+- **`ci-verdict` is the ONE CI reader; do not hand-roll `gh pr checks`,
+  `gh run view --log` or a `watch-*.sh` poller (#3700, 2026-09-30).** Every
+  read the orchestrator did by hand is a mode of `node scripts/ci-verdict.mjs`:
+  - `<pr|sha> [--wait N]` — the gating verdict (exit 0 / 1 / 2 / 3, see the
+    merge loop above). A failed gating job now also prints its failed STEP
+    (so `Ast-grep self-scan` or `Audit production dependencies` reads as what
+    it is, not as a test failure), its `FAIL` and assertion lines and the
+    `Tests` summary with the ANSI codes stripped, the gating and advisory
+    counts on separate lines (advisory reds never gate, and are read before
+    merging), and the remedy hint: `gh run rerun <run>` for a cancelled or
+    superseded run, the `gh api -X POST .../approve` command for fork
+    approval, `gh pr update-branch <pr>` when the failed merge's base is no
+    longer master's head (a rerun replays the old merge commit, #3660). A job
+    that failed with `couldn't find remote ref refs/pull/N/merge` on a MERGED
+    PR is reported as post-merge noise, exit 0, not a red lane.
+  - `--all` — one line per open PR (`#N <author> auto-merge=on|off head=<sha>
+    gating=<state> [first-failure=<check>]`) for status reports; it always
+    exits 0.
+  - `--watch-open [--wait N] [--state-file <path>]` — the notifying wait:
+    watches every open PR that has auto-merge armed or is authored by the
+    repository owner or the `gh` viewer (a PR in a fix round has no
+    auto-merge and still goes red), polls every 90 s, and exits 0 on the first
+    poll with an event, printing `#<pr> <event> @<sha>: <reason>` plus the
+    failure detail (events: `failed`, `fork-approval`, `absent-rearm`,
+    `merged`, `closed`; each PR reports on the TRANSITION from its last seen
+    state, keyed by head SHA). Exit 3 means the window ended with none.
+    `--state-file ~/.cache/pi-lens-orchestrator/watch-state.json` keeps the
+    last seen state across re-arms so the same red is not reported twice. Run
+    it with `run_in_background: true`; it replaces the session-local
+    `watch-automerge.sh`. Events also include `dirty` (merge-conflicted) and
+    `cancelled` (a superseded run nobody replaced, with its rerun command),
+    and a `merged` PR lists its closing issues' states.
+  - `--watch-open --stream` — does not exit on an event: it prints one line per
+    event per head (`FAIL #N@sha: ...` plus the failing test names,
+    `DIRTY #N@sha`, `CANCELLED-NOT-REPLACED #N@sha: ... (gh run rerun <id>)`,
+    `MERGED #N` plus `closes #M: <state>`, `CLOSED #N`) until the window ends
+    (exit 0 if any line was printed, 3 if none).
+  - `--rerun-cancelled` (with `--watch-open`, and REQUIRING `--state-file`:
+    without it every re-armed watch would re-run the same head, so it is a
+    usage error) re-runs a cancelled, unreplaced run itself
+    (`RERUN #N@sha: gh run rerun <id>`), once per head. A refused re-run is
+    retried on the next poll after a backoff (180 s, then 360 s), at most
+    three attempts per head, then left to you.
+  - `--sync-main <path>` (with `--watch-open`) fast-forwards that checkout after
+    a merge (`git pull --ff-only`) and prints `SYNCED <path>: <old> -> <new>`.
+    It refuses, saying why (git's own line, such as `Not possible to
+    fast-forward`), when the checkout is off master, has modified tracked
+    files, or cannot fast-forward, notes local commits not on origin, and prints `LOCKFILE CHANGED: run
+    npm ci when no worker is live` when `package-lock.json` moved. It never
+    runs `npm ci`: live workers share that install.
+  - `--approve-fork <PR>` approves that PR's `action_required` runs on its
+    current head (`gh api -X POST .../actions/runs/<id>/approve`). Explicit,
+    per PR, never part of any watch.
+  Apart from `--approve-fork`, `--rerun-cancelled` and `--sync-main`, which you
+  pass by name, it never approves, reruns or updates a branch: it prints the
+  command.
+- **Read the advisory rows before merging, even though they never gate
+  (2026-09-12).** The exit-code rule above is right and stays: never text-match
+  the verdict table for `failure`, because advisory rows print `failure` on a
+  green PR. But "does not gate" is not "carries no information", and filtering
+  advisory rows out of your attention is a different mistake from filtering
+  them out of the gate. `typos (advisory)` found a real defect in #2955's
+  round-12 diff — a comment in which "reading" was misspelt — which the
+  gating checks had no opinion about and which would otherwise have reached
+  master. (The misspelling is described rather than reproduced here: quoting
+  it verbatim makes this file itself red the typos lane, which is the same
+  detector-versus-prose problem the testing rules already name.) Gate on the exit code; read the advisory failures on the exact head
+  before the merge and dispose of each one (fix as a trailing commit, or say
+  why it is noise).
+- **`gh run rerun` replays the ORIGINAL merge commit; it does not pick up a
+  moved base (2026-09-12).** A pull-request CI run tests `refs/pull/N/merge`,
+  master merged into the branch. When master moves — say a fix for the very
+  failure that red the lane just landed — rerunning the failed job re-runs the
+  SAME merge commit, so the fix is not in the tree and the lane reds again
+  identically. The log's checkout line is the proof and is worth reading every
+  time: `HEAD is now at <sha> Merge <branch-sha> into <BASE-sha>`; if that base
+  is not current master, the run tells you nothing about current master. This
+  cost a false conclusion on 2026-09-12 — a lane red on `pi-lens-warmup-oneshot-*`
+  after its fix had merged looked like the fix not working, and the base was one
+  commit behind. Re-arm with
+  `gh api -X PUT repos/<o>/<r>/pulls/<N>/update-branch` (or a push), never a
+  rerun, whenever the reason to re-run is that the BASE changed. Same family as
+  the retarget rule above: the event that re-runs CI must be one that rebuilds
+  the merge ref.
+- **A nondeterministic gate makes a green a sample, not a proof
+  (2026-09-12).** The fixture-hygiene ratchet reds only when a leaky family
+  actually loses the race, so two PRs on the SAME base can disagree: on
+  2026-09-12 #2994 went green and #2997 red on identical master. Before merging
+  on a green whose base is stale, ask whether the gate that matters is
+  deterministic; if it is not, re-gate on a current base rather than bank the
+  sample. The merged result runs against master, not against the tree that
+  happened to pass.
+- **Detection retrospective on every merged bug fix (2026-09-06).** The
+  catalog records the CODE lesson of a bug (a shape, a screen, a guard). Before
+  a bug-labelled lane's ledger row closes, the orchestrator also records the
+  DETECTION lesson in one line: which verification layer caught it (external
+  user, reviewer probe, CI job, governance sweep, install/compat/tool smoke,
+  dogfood, release gate) and which layer SHOULD have caught it earlier and at
+  what cost. If that layer does not exist, file it as an issue with the bug as
+  its named recurrence — the same standard shapes are held to. The ledger
+  carries a `caught by / should have been caught by` column. Record: #2587's
+  manifest entry escaped the package for four releases; a second registration
+  path masked it, so the shipped defect was foreign-tree adoption, not absence
+  — and no check ever asked a real pi which SOURCE a skill came from. The
+  shape lesson went into AGENTS.md the same day; the layer lesson (a witnessed
+  real-pi pass asserting source and path, #2606) surfaced only because the
+  maintainer brought an outside skill in, and the first runner's count-only
+  row would have passed the broken release.
+- **Harvest every reviewer's "Could not verify" and "Named output".** Those
+  sections hold the structural insights the probes could not close (a
+  runIf-conditional guard, a smoke section that never ran on a real runner, a
+  detector's boundary map). Each entry becomes, before merge, one of: an
+  issue, a ledger note with a reason, or a line in the PR body. Silence is not
+  a disposition.
+  When a Named output becomes an issue the orchestrator declines or defers,
+  the ledger note names a DURABLE reason (a measured cost, a dependency, a
+  design decision with its date), never "not now"; otherwise the same
+  candidate is re-harvested at the next regroup rather than silently dropped.
+- **Debt pass at the regroup (2026-09-07).** Before prioritising the next
+  cycle, run the repo's own dead-code and duplication tools over the files
+  changed since the last release tag (`git diff --name-only v<last>..origin/master`;
+  `npx knip` uses the config in package.json, Sonar's duplication gate is the
+  CI form): every reviewer's "Named output" that named a re-derived seam
+  (#2694: the call-site scan hand-rolled in three sweeps) is what this pass
+  finds across lanes that no single review can see. Findings become issues
+  with the file list, never release blockers, and test-seam duplication is
+  IN scope — "Test infrastructure — reuse before you write" in AGENTS.md is
+  the standing rule, so the borrowed skill's "test duplication is often
+  intentional" exclusion is not borrowed. (Shape from aromanarguello/roman-skills
+  `techdebt`.)
+  Within that changed-file list, weight candidates by commit frequency since
+  the last tag (`git log --since=<last-tag-date> --name-only --pretty=format: |
+  sort | uniq -c | sort -rn`) so the pass follows the real hot spots rather
+  than every touched file equally. A FULL-repo debt pass (not the diff-scoped
+  one) carries a coverage contract: one ledger row per subsystem (id, files,
+  status) and the pass is not closed until every row is filled or skipped with
+  a reason. A debt-pass subsystem worker reports at most TWO materially useful
+  simplifications, each with the deletion test answered, drawn from six
+  candidate shapes: scattered booleans or nullable fields that permit invalid
+  combinations (a state machine or discriminated union); repeated assumptions
+  about an object shape (one typed model); duplicated branching a small map,
+  registry or reducer would remove; unclear state or behaviour ownership (a
+  module boundary); repeated scans or lookups a better collection or index
+  would remove; lifecycle, concurrency or async state whose representation
+  permits stale or contradictory state. Never force an abstraction; boring
+  local code that is already clear stays. This cap is for
+  debt-pass dispatch only and never applies to PR review, where every finding
+  from CRITICAL to NITPICK is reported.
+- **Session retrospective before the regroup.** One ledger block: what the
+  maintainer had to bring in from outside, why the process did not surface it,
+  and where the lesson was routed (contract, skill, issue). The
+  2026-09-06 entry: the autoqa witness/reachability rules and the release-QA
+  layer came from a maintainer link, not from the train's own retrospective
+  on #2587.
+- **Review tier follows what the diff touches, never the priority label
+  (2026-09-06).** The record: the two most dangerous regressions of that day
+  came from p3 follow-ups — #2595 (a 125 s stall on an awaited path, a latent
+  crash) and #2604 (broke offline installs in r2, broke `npm install` on
+  Windows in r3) — and both were caught only by full review; the p3s where
+  review found nothing were the ones touching no production code.
+  - **Tier A — full adversarial review, any priority:** anything under
+    `clients/`, `tools/`, `mcp/`, `scripts/`, `.github/`, or a package
+    manifest / lockfile.
+  - **Tier B — one scoped review pass, scope stated in the brief:** tests-only
+    diffs that are not governance sweeps or ratchets (those are Tier A: a
+    guard is production for the train).
+  - **Tier C — no reviewer agent:** docs, comments, rename-only, data files.
+    Orchestrator read plus CI on the exact head.
+  A prescribed-remedy fix round stays "merge on green" in every tier.
+- **Same-seam siblings batch into the open PR (2026-09-06).** When a review
+  finds a sibling of the same shape on the same seam, it goes into the current
+  PR as another round — reusing the fixer's context and the reviewer's probes
+  — when all three hold: same dependent sweep, remedy prescribed rather than
+  designed, and the PR is not on the critical path of an external or p1 fix.
+  Otherwise file it with the sibling list and the reason. The record: #2598
+  out of #2599 and #2593 out of #2594 each cost a fresh fixer spin-up plus a
+  fresh review (and #2604 then needed three rounds under a review that was
+  already armed on that file); #2603 out of #2595 and #2592 out of #2585 were
+  rightly separate (a new matcher; seventeen per-seam reads). #2596 was filed
+  as a follow-up and closed as a duplicate — pure waste.
+- **Refill order** when the quota gate is open: p1 first, then the queued
+  follow-ups in ledger order, then the program work (#2421 → #2416 → #2383/#195).
+
+## Disposition tables
+
+Verify reports and fixer handoffs end with a per-finding disposition table
+(defined in `docs/pi-lens-reviewer.md` "Findings and verdict");
+read the worst cell to route the round.
+
+## Honesty rules
+
+- A finding is real when a probe proves it; a fix is real when the same probe
+  passes and the regression test was red first.
+- `closes` vs `refs` follows delivery, not optimism; leftovers get an issue
+  comment before anything closes.
+- After merging a `refs #N` PR, VERIFY the issue: read `gh issue view N
+  --comments` and confirm a comment names the remainder. If the PR in fact
+  satisfied every acceptance criterion, close N crediting the PR; if a
+  remainder exists but is unnamed, post it. A `refs` PR with no remainder
+  comment is how #1968 and #2355 sat open for weeks after their fixes
+  landed (found 2026-09-02).
+- Report what ran, what was skipped, and what CI must still confirm.
+
+## Common mistakes (scan at task start)
+
+Each row cost a lane at least once; the prose above carries the record.
+
+| Mistake | Fix |
+|---------|-----|
+| Reading a CI verdict without checking the SHA it judged | `ci-verdict --wait` returned exit 0 for the PREVIOUS head seconds after a push (#2878 trailing, 2026-09-10); compare the verdict's SHA with `gh pr view --json headRefOid` before merging |
+| Reporting "pushed" before `git log -1` shows the commit | Two trailing commits failed the pre-commit hook (changelog one-entry rule, unused vars) and the ledger/body already said pushed; verify the head, then write the row |
+| Folding a worker's extra changelog fragment into an existing one | One fragment = one top-level entry (`rollup-changelog --check`); keep a second fragment separate or drop it |
+| Accepting a worker's "pre-existing red on master" | Run the file on origin/master in YOUR environment before believing it; four workers reported env-specific reds as master reds (2026-09-10) |
+| Letting a fix round enumerate cases instead of deriving the rule | #2877 took 7 rounds; the brief for a rule fix demands derivation from the source of truth (grammar table, measured host sequence) |
+| Accepting a state-space table on its claims | Grep every test id in the table before accepting the round; #2877 r3 and #2868 r3 (2026-09-10) shipped 48–72-cell tables with zero real ids |
+| Believing a worker's "N suites red on origin/master" without auditing its probe ENV | #3026's fixer pinned `TMPDIR` to the harness `.probe-home` and reported 16 unrelated suites red; the tree was green (2026-09-15). Ask for the A/B with the variable held fixed; the `tmpdirCollision` deny rule in `scripts/hooks/guard-bash.mjs` blocks the command |
+| Merging a PR before its own CI has been read on the exact head | #3051 landed 20:05Z with the gitignore negation commit missing; `gitignore-tracked-shadow` redded on every open lane for ~30 min (#3055). `node scripts/ci-verdict.mjs <sha>` before every merge, admin merges included |
+| Hand-triggering attempt 3 after a second infra kill | `ci-infra-kill-rerun.yml`'s classify job was gated `run_attempt == 1`, so it never covered the second kill on one head; #3048 and #3040 each needed a manual rerun (2026-09-15). The gate now covers attempt 2; a third kill is a hand rerun by design |
+| Merging a workflow edit whose only executing lane is master-only | #3033 edited install-smoke's `pnpm-global`/`mise-repro` steps, both gated `!= 'pull_request'`; six cells failed on every master push for a day (#3043). Give the edited lane a PR-eligible cell, or run `gh workflow run <file> --ref <branch>` and quote the run id |
+| Sending a governance-sweep brief to a Sonnet fixer | Two rounds cost 765k tokens / 459 tool uses on #3066 and 587k on round 1 alone (2026-09-15). A brief that adds or edits a `tests/support/sweep-kit.ts` registered-or-fail sweep goes to the strongest available fixer |
+| Dispatching into a backend session window that cannot hold the brief | commandcode's undocumented 5-hour cap killed #2928's worker after 42 turns with uncommitted work and no `COMMIT_MSG.txt`, and gave #3045 r2's worker 0 turns (2026-09-16 00:07Z). Check the backend's cap and reset time before dispatch; re-route on reset (plegma #436) |
+| Accepting a derived guard whose mutations are all neutered-guard rows | #3045 r1's guard accepted a junk marker and a substring launcher with M3/M4/M6 green. Demand one negative-population row: an input the guard must reject (#3075) |
+| Merging a fold PR without mutating what the deleted sibling used to back | Four folds in one session each shipped a newly-sole predicate that was untested (#3064 F1, #3065 F3, #3066 F3, #3068 F2). Mutate every predicate the fold promoted, not only the new code |
+| Accepting a runtime test as red-first evidence for a type-only defect | #3026's case could never red — `tsc` erased both changed lines and the emitted JS was byte-identical. The compile transcript on both `tsconfig.build.json` and `tsconfig.json` is the evidence (#3074) |
+| Admitting a real `git show <sha>` in a test to read historical content | #3066 r1 ran it at MODULE SCOPE; CI checks out at depth 1, so the file would have collected zero tests including three pre-existing #525 cases. Commit the content as a fixture under `tests/fixtures/` |
+| Letting a heavy governance test land without a measured peak RSS | `bounded-container-guard` landed at 9.2 GB on 2026-09-14 and drove the CI kill rate 7.1% → 30.4% in five days (#3058). The `worker-peak-rss` gate (#3062) now fails a `default`-project file over budget; keep it gating, not advisory (#3067) |
+| Arming `plegma watch --next` after the lane already settled | The watch only sees settlements newer than itself; check `plegma_status` by handle first and process a done lane directly (three lanes sat settled for hours, 2026-09-10) |
+| Pruning trees with `merge-base --is-ancestor` | Prune only trees whose branch is the head of the PR just merged (#2358's tree, 2026-09-06) |
+| Retargeting a PR base and waiting for CI | `edited` does not fire ci.yml; push a commit or close/reopen |
+| Reading `$?` after a pipe | Read the final `ci-verdict: exit <N> (<kind>)` line (`; echo $?` on its own line, before any pipe, is also fine) |
+| Text-matching the verdict table for `failure` | Key on the exit code; advisory rows print `failure` on green PRs (#2692) |
+| Committing a worker tree with `git add -A` and a pathspec exclude | Check `git ls-files` for handoff files and scratch dirs before the commit; fold a second fragment (#2807, #2808, 2026-09-09) |
+| Merging two green PRs that edit the same baseline or admission map in parallel | Serialise them and re-run that file's test on master between (#2816) |
+| 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) |
+| 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 |
+| Nudging a capped small-model lane more than once | One continuation, then reassign to the strongest model (GLM lanes, 2026-09-09) |
+| Waiting on CI for a bot-authored PR (github-actions nightly refresh) | A GITHUB_TOKEN push fires no `pull_request` run: required checks stay ABSENT forever; close/reopen the PR to fire them (#2801, 2026-09-09) |
+| 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) |
+| 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) |
+| `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) |
+| Treating a `ci-verdict --wait` exit as a CI verdict without reading it | Exit 70 = GitHub API unreachable; every armed wait died at once during two outages on 2026-09-10 — poll `https://api.github.com/` until 200, then re-arm one wait per PR |
+| Merging a PR that arms a registry-membership guard without telling the other lanes | After #2924, every open PR that adds a formatter, LSP server or MCP tool needs a docs line in the same change; note it in the ledger and the next briefs (2026-09-10) |
+| Judging master from the local checkout | `git fetch origin` and read `origin/master`; #2693 r1 reported a catalog row missing that had merged an hour earlier, and the orchestrator's own branch that morning was cut from a master six commits behind |
+| Swapping reviewers between rounds | Same reviewer verifies; the probes and the mutation set are the continuity |
+| Trusting the fixer's "CI green" | Read ci-verdict on the exact head SHA yourself; absent required checks are not green |
+| A third patch-only round on one seam | Round-count rail: state-space table in the body first, Opus fixer |
+| Merging a `refs` PR with no remainder comment | Post the remainder or close the issue crediting the PR |
+| Dispatching independent agents one message at a time | All independent Agent calls in one message; the quota gate is read once before the batch |
+| Resuming a fixer whose tree was reaped | Spawn a fresh fixer on the branch, or export `PILENS_HYGIENE_KEEP_AGENT_TREES=1` for the session up front |
+| Sweeping a shape by grep-counting tokens | A ratchet reads the exact literal it governs (#2693: four sites counted, six real) |
+| `npx <tool>@latest` inside the repo to measure something | It rewrote package-lock.json (108 deletions) on 2026-09-07; run one-off tools from a scratch prefix, and `git diff --stat` before every commit |
+| `git add -A` in a worktree that links `node_modules` | The ignore rule `node_modules/` does not match a SYMLINK; #2703 committed one and broke the clean-clone install and the tracked-shadow test. `git add <paths>`, and `.gitignore` now says `node_modules` without the slash |
+| `git worktree remove --force` on a tree whose `node_modules` is a symlink | Git follows the link and empties the shared checkout's install (twice on 2026-09-16, #2704 class; every other lane's build broke). `rm node_modules` first (unlink, never `rm -r`), then remove; mechanisation in the Bash hook is filed |
+| Checking a branch out in the shared main tree for your own fix | Reviewers saw the checkout switch under them three times on 2026-09-07; use a throwaway `git worktree add` under `~/.local/share/pi-lens-orchestrator/tmp/<lane>` (never the scratchpad -- #3526: it is `/tmp` on this launcher, tmpfs, and `guard-bash.mjs` denies a checkout landing there), remove it after the push |
+| `gh run rerun --failed` while the run is still in progress | GitHub refuses it; wait for the run to complete (poll `gh run view --json status`), then rerun, then re-read the verdict |
+| Reading a failed job's log before its run completes | Empty output; the log is withheld until the whole run finishes |
+| Treating a reviewer's prescription as the fix | It is a hypothesis: #2693 r2's blanked-slice remedy stayed green on `env: { PWD: cwd }`; the fixer's AST rule replaced it and the reviewer withdrew the prescription |
+| `git add -A` from a worktree without the probe-home exclude | 978 `.probe-home/npm-cache` blobs reached master in a direct push (2026-09-09, #2843); the user-level `commit-index-check` hook now denies it — keep the exclude anyway |
+| Ignoring a red advisory row on a PR that changes what the lane runs | #2833 merged with `Unit tests Windows (advisory)` red on its own head; master carried the red until #2842. Read that row like a gate when the diff touches the lane's script, step or executed files |
+| Restarting the plegma daemon under systemd with the default PATH | Backend detection is a PATH walk in the daemon process; 5 of 10 backends vanished and every Luna/GLM brief was rejected `Unknown model` (plegma#375). Set `Environment=PATH=…npm-global/bin…` in a drop-in and read `daemon.out`'s `backends:` line after ANY restart |
+| Polling `plegma_list` every turn | 68 calls, 194 KB of context in one session for no decision. Arm one background `plegma wait <handle>` per lane in the dispatch turn; `plegma_list` only at reconnect and to consume `done` handles |
+| Running `node ../../scripts/<x>` from a worktree | The path resolves against the worktree's parent, not the repo; two CI waits exited at once with the wrapper's exit 0 (2026-09-10). Inside a worktree the scripts are at `scripts/`; read the wait's output file before trusting an exit code |
+| Appending a worker's body section keyed on an exact heading level | The worker wrote `# Round 7`, the append keyed on `## Round 7`, and the PR body shipped without the round (#2846 v7). `grep` the published body for the section before reporting it landed |
+| Pushing an orchestrator round without `npm run fmt:check` on the whole tree | #2853's merge round redded oxfmt on two trimmed lists (2026-09-10). fmt:check is the last command before any push, orchestrator rounds included |
+| Running a governance suite in the main checkout after merges without rebuilding | Vitest loads compiled `.js`; a stale build makes the run fail closed (or worse, test old code). `npm run build` before any test run in a checkout that has moved |
+| Accepting a lifecycle round on `-t`-only mutation reds | #2853 r6/r7 quoted reds that only reproduced under `-t`; nine awaits never returned whole-file (#2859). Whole-file mutation runs are the acceptance shape (AGENTS.md round-routing) |
+| Sending a scope `note` to a worker about to finish | The #2854 r2 worker settled before the note was read; the round shipped without H2/M1. Check `plegma_status` first; a worker with no turns left gets a new round, not a note |
+| Chaining a check and a commit or push with `;` or a pipe | Three times on 2026-09-25: a commit with `lint=1`, a push with the flake-shape ratchet red, and a push reported done by `echo $?` of a later `grep`. Gate with `&&`, or read the check in its own call; the guard is #3471. Recurred 2026-09-26 on #3492's pushes (a commit piped to `grep` then `;` push piped to `tail -1`, and a mutation `vitest` run `;`-chained to a commit) |
+| Pushing with `npm run build >log 2>&1; echo build=$?; test "$(git rev-parse HEAD)" = SHA && git push …` | `guard-bash.mjs`'s `checkUngated` rule (#3471, landed in G12) denies this: the build's real exit code is thrown away by `;`, so a failed build still reaches the `git push` (case 1's own shape). Rewrite as `npm run build >log 2>&1 && test "$(git rev-parse HEAD)" = SHA && git push …`, or split the build and the push into two calls — never exempt `build` from the check |
+| Opening a PR without `npm run preflight` | #3468 opened with a `build:` title that the title gate rejects; a hand-picked subset of checks (body lint only) left it out. Write `PR_BODY.md` and `COMMIT_MSG.txt` and run the preflight, which lints both |
+| Adding real spawns or waits to a test without running the flake-shape ratchet | #3464's `git init` fixture raised a spawn count and pushed red (#3472); #3492's 60 s `setTimeout` reddened CI the next day, and that push's `clients/lsp/client.ts` change (it alone matches 71 test files) had capped the hook to build-only. `scripts/pre-push-targeted-tests.mjs` now arms `TEST_TREE_GOVERNANCE_TESTS` (the ratchet) on any `tests/` change and runs the armed registries past the cap |
+| Carrying a field from a replaced queue entry into an entry of another kind | #3481 r1 kept the pending read stamp on an unstamped replacement; the queued rename close inherited a stale stamp and was dropped, reopening #3477 inside its own PR (#3491 verify round, fixed in `b937ff0a9`). Probe a review-round fix on every entry kind that shares the queue; AGENTS.md shape 55, model composition #3495 |
+| Encoding a server's message order from the model instead of measuring it | #3484's first cut fenced every version-less server; docker-langserver publishes before the fence reply, so its only answer was dropped, and the fake server published after the reply (#3484 r1, found by the reviewer running the real server). Measure the order per server before the fixture encodes it; AGENTS.md shape 54 |
+| Adding a second per-server strategy marker without a test that drives both | intelephense carried `emptyFirstPublish` when #3484 marked it `diagnosticsFence`; the fence dropped the first publish, the hold swallowed the answer, and three #3310 tests timed out in CI on `b937ff0a9`. `tests/config/strategy-marker-pair-coverage.test.ts` now reds an unregistered pair |
+| Asserting on a record a production deadline can cut short | The dispatch-cap case needed all 33 files hashed inside the 50 ms settle deadline; a loaded runner cut one and master went red on `afea9074d` (#3493). Pin the bounds through a test seam (`_setObservedTimeBoundsForTests`, #3494); the load-simulation pass is #3496 |
+| Reading a `check_suite.completed` wake as a green head | The wake excludes cancelled suites; #3491's run on `a16fb1f82` was cancelled and was reported "finished green" (2026-09-26). Read the run's conclusion on the exact SHA; `ci-verdict` needs `gh`, which cloud sessions lack (#3497) |
+| Describing a guard in a contract line as if it runs | AGENTS.md shape 52 said stores were "pinned by name in the #1894 registry ratchet"; no such ratchet existed (2026-09-25 catalog retro). Name a guard by its path, and a planned one by its open issue |
+| Rewriting a PR body's narrative without re-reading the `.changelog/` fragment | The fragment kept the retracted round-1 story after the body moved on to a different remedy (#3155 r2); re-read the fragment on every body rework, not just the body |
+| Accepting a subset-shaped change without a generalization verdict | #3622 applied idle eviction to 4 of ~44 LSP servers; the maintainer caught the missing population screen by reading the PR. At each regroup, scan merged PRs and require the verdict. |
+| Filing an issue mid-session without a seam group | Issues filed mid-session must be assigned to a seam group at filing (2026-09-30); do not leave the follow-up queue ungrouped. |
+| Filing follow-up issues through the GitHub API without a TYPE or priority label | The orchestrator filed about a dozen issues this way on 2026-09-26 (#3543-#3546, #3548, #3549, #3552, #3556, #3558-#3560); the issue templates that would force a label are bypassed by API creation, and they stayed untriaged until the maintainer noticed by hand. `.github/workflows/untriaged-issues.yml` now fails a daily job listing any open issue still missing either (#3563) |
+| Issuing a mid-flight order without naming the overridden brief clause | State which part of the original brief it overrides and post the order on the issue (#3695 handoff 6) |
+| Explaining why an agent stopped without checking its status | Check the agent's status before attributing its stop (#3695 handoff 7) |
+| Starting agents against an ambiguous target | Confirm the target before dispatching agents (#3695 handoff 8) |
+| Letting strictness-ratchet and glossary pins collide on one change | Run both pin sweeps before pushing (#3455/#3643) |
+| Re-running a `pull_request` job against the old merge SHA | Use `gh pr update-branch` to rebuild the merge ref (#3660; 2026-09-30) |
+| Fixing a hooks or lint gate without sweeping older open branches | Sweep open branches committed before the fix (#3675; 2026-09-30) |
+| Enabling auto-merge before local HEAD equals the pushed SHA | Verify the pushed SHA before enabling auto-merge (#3671) |
+| Waiting for CI after retargeting a base without a push | Push after a base retarget to re-arm CI (#3679) |
+| Leaving fork-PR `action_required` runs unapproved | Approve the runs after pushing to a fork PR (#3656) |
+| Writing a closing keyword on a partial delivery | #4021's title said "closes #1513" while its notes said the global-bin walk remained; the merge auto-closed #1513 and it was reopened by hand (2026-10-07). Close only when every acceptance criterion is met; otherwise write `Refs #N` and post the remainder before merging. Title and body must agree |
+| Two writers doing read-modify-write on one shared record without a lock | The orchestrator ledger lost a freshly written row: a sync script read the file, a row was appended, the sync wrote back its stale copy (2026-10-07). Every writer of a shared record holds one lock across the whole read-modify-write (principles §1, "Design shared state once") |
+| Paraphrasing an acceptance criterion into a review brief | A combination-review brief for #3997 said substituted labels "must reject" where they must be accepted when they form an identifier (2026-10-06). Quote the criterion from the PR body or issue; never restate its polarity from memory |
+| Treating a `completed` settlement as delivered when its declared report is missing | Two codex settlements in one batch wrote `REVIEW.md` instead of the declared `REVIEW_4024.md`, or only a GitHub comment (plegma #689; 2026-10-07). Check the declared file exists; else read the file the worker's final line links, and release by hand |
+| Assuming a hook added mid-session is live | A `SubagentStop` hook added to `.claude/settings.local.json` mid-session never fired and did not show under `/hooks` (2026-10-07). Hooks load at session start: confirm under `/hooks` after adding one, or restart before relying on it |
+| Leaving a lane's report inside the checkout that gets torn down | Closing a reviewer's worktree deleted its `REVIEW_4028.md`; the fix round worked from a relayed list (2026-10-07). Reports go outside worktrees (the handbacks directory), and teardown copies any root report out first |
+| Relying on a declared deliverable name the worker never sees | plegma does not pass `deliverables:` into the delivered task; 4 of 4 briefs that omitted the file name got `REVIEW.md` or no file, 2 of 2 that named it were followed (plegma #689; 2026-10-07). Name every declared file in the brief text |
+| Telling a worker to dispatch a workflow without checking what it publishes | A brief asked a fixer to `gh workflow run` its branch; the job publishes `data/test-history` with no ref guard, and the queued run would have pushed unreviewed rollup output with an oldest-row eviction (#4037, cancelled; 2026-10-07). Read the workflow's push and publish steps and their `if:` guards before asking for a branch dispatch |
+| Trusting a `completed` fix round without checking the PR head moved | The #3997 maintainer round settled `completed` while its lease push to the base repo was rejected; the commit sat in the worker tree (plegma #692; 2026-10-07). After each fix round, compare `gh pr view --json headRefOid` with the worker's commit |
+| Raising a timing budget without proving the guard still reds | A request to widen a 300 ms occupancy budget to 500 ms; the yield-removal mutation measured 220 ms locally while healthy CI measured 324–520 ms, so the guard was vacuous at either value (2026-10-07). Mutate the regression the budget exists for before moving the number |
+| Re-running a broad suite after a one-file conflict resolution | A census-conflict merge on #4013 re-ran `tests/scripts` plus governance (~240 files) the reviewer had just run green on the prior head; the 4 affected files already passed (2026-10-07). Run the files the resolution touches; CI runs the rest |
+| Claiming a measured fact from a partial grep | The orchestrator told the maintainer the merge-train warden's last 20 runs "took zero actions"; the grep had counted only update-branch, rerun and cancel calls, and the runs had posted 24 PR comments and 37 label changes (#4105, 2026-10-07). The maintainer decided on the wrong number and had to re-confirm. Count every effect a component can have before calling it inert |
+| Letting one transient backend error re-route a whole day | A single Luna `Selected model is at capacity` failure moved about 15 later fix lanes to Claude Sonnet while codex had 80% weekly budget and 4 free slots; Claude's weekly budget reached 50% (2026-10-07/08). Treat a capacity error as transient, retry on the next dispatch, and check `plegma_quota` before every Claude fixer |
+| Reading CI in a chain whose push silently did nothing | A background chain gated its push on `&&` after a build that never ran, then read the unchanged head's red Windows job as the "fixed head" result and wrote it into #4111's body (2026-10-07). After every push, compare `gh pr view --json headRefOid` with the pushed commit before reading any CI |
+| 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 |
+| 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 |
+| 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 |
+| 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 |
+| 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 MEDIUM and above or a reproduced sibling, and give each group a "done when" |
+| 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 |
+| 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 |
+| 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). |
+| Passing a commit SHA where a command expected wait seconds | The shell invocation was caught by the command's outcome review; argument-shape validation should have caught it before execution. `land.sh` now validates the wait argument and prints its outcome line. |
+| Losing executable mode in an atomic `.new` to `mv` replacement | The next invocation caught the non-executable script; the file-install check should have compared mode as well as bytes. The replacement now preserves the executable bit. |
+| Reusing a finished PR row for `lane-set --new` | The lane ledger exposed the wrong PR identity; the row allocator should have rejected terminal rows before allocation. New rows now require an unused active identity. |
+| 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. |
+| 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. |
+| 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. |
+| 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. `land.sh` now holds a PR-red/master-green advisory unless `ADVISORY_OK=1`. |
+| 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). |
+| 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. |
+| 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). |
+| Specifying a truncation mechanism instead of an output acceptance criterion | The orchestrator's output read found cut lines after the worker followed the brief; the brief should have stated the required output (complete first sentence, no ellipsis). Rule: acceptance names the required output, not only the mechanism. |
+| Adding a second idle timer without naming the probe consumer | The nightly eviction probe caught the missing configuration coverage; the change's call-tree diff should have listed every idle-timer environment setter. The configuration test now requires every client-read idle timer to be armed by the probe. |
+| Reproducing only one step of a multi-step release-body producer | A user noticed the missing Thanks section; the release-body test should have run the complete producer chain. `bin/relnotes-regen.sh` now runs both steps and refuses to lose the section. |
+| Basing a real-pi premise on an unavailable maintainer-machine probe | The fixer could not rerun the stale probe and the recurrence was found in review; the premise check should have required a repository witness. Fix briefs now require a `tests/real-harness` witness using `withRealPi` and a scripted provider. |
+| Sending a sandboxed verifier a brief path instead of its contents | The verifier reported that the brief was unreadable; the dispatch smoke test should have inspected the delivered argument. Verification now inlines file arguments. |
+| Allowing a mocked handler to throw so every assertion passes vacuously | Verify found the non-blocking degradation; the test double should have failed explicitly when the handler throws. Rule: a test asserting a handler verdict must also assert that no handler-throw degradation was recorded; a shared helper is a candidate, not yet built. |
+| Trusting a worker hand-back that omitted exact test summaries and misreported fixes | Review found nine CAUSED-BY-CHANGE failures and unsupported “fixed” and TLA+ claims; the hand-back check should have required exact summary lines and reviewer red-on-base reruns. Fix lanes now paste the named Vitest summaries and verify identity claims. |
+| 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. |
+| 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. |
+| 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. |