git:20261008.7a2fb3f to git:20261009.b0e6728

- - **Verify gh active account before write ops**: The local `gh` keyring holds two accounts (`s977043` for this repo, `kominem-unilabo` for work), and the active account silently switches to `kominem-unilabo` mid-session — observed 5+ times in the 2026-06-10..11 session, causing `404 Not Found` / `must be a collaborator` / `does not have the correct permissions` on `gh pr create` / `gh pr merge` / `gh api .../update-branch` / `gh issue create`. Before every `gh` write op, guard with: `gh api user --jq .login | grep -q s977043 || gh auth switch -u s977043`. Treat a 404 / `Could not resolve to a Repository` / permission error on any `gh` call — **reads included** — as account-switch first, not a real permission problem. The switch breaks reads the same way it breaks writes: `gh pr checks`, `gh pr view`, and `gh api repos/:owner/:repo/...` against this repo answer `404` / `Could not resolve to a Repository` while the wrong account is active. Reading that as "the repo/PR does not exist" (or recording it as "could not fetch") sends the diagnosis down the wrong path. This guard is automated by a PreToolUse hook (`.claude/hooks/gh-account-guard.sh`), but that hook intentionally matches write ops only (`WRITE_RE`) and lets reads through with no account check. A failed read breaks nothing, so it does not need blocking. The read-side remedy is therefore diagnostic, not mechanical: re-run the guard command above by hand, then retry the read. The hook is defense-in-depth either way — keep the session-start account check.

- - **Merge-time checks**: Before `gh pr merge`, work through the checklist in `docs/governance.md` § "PR レビューとマージ" > "マージ前チェックリスト" — CI green (`gh pr checks`), reviewer comment disposition from **both** `gh api --paginate 'repos/:owner/:repo/pulls/<N>/comments?per_page=100'` and `gh api --paginate 'repos/:owner/:repo/issues/<N>/comments?per_page=100'` (the `pulls` endpoint returns line comments only, so a PR-level review posted as an issue comment is invisible there), blocking labels (`gh pr view <N> --json labels` — `blocked` stops the merge and only its author removes it; a same-account PR cannot receive a formal Request changes, so labels are the substitute), `/preflight` for multi-PR / workflow-pin work, and `.nvmrc`-matched `npm run build:action` when touching `runners/github-action/src/**`. That section is the SSoT for pagination pitfalls, bot-vs-human triage, and disposition rules; keep this bullet to _what to check_, not how to judge it. See also `skills/midstream/gh-address-comments/SKILL.md` for the reviewee-side comment-handling workflow and `docs/development/dist-check-rebuild-guide.md` for dist rebuild troubleshooting.

- - **Strict-mode batch merge**: When merging N independent PRs against a branch protected with `strict: true` (check via `gh api repos/OWNER/REPO/branches/main/protection --jq .required_status_checks.strict`), update ALL remaining branches to the same `origin/main` SHA simultaneously (`gh api --method PUT repos/OWNER/REPO/pulls/<N>/update-branch`) before starting the chain, then merge one-by-one immediately after each CI passes. Updating one-at-a-time after each individual merge re-triggers full CI for every remaining PR and multiplies total wait time by N. For lock-file-only conflicts where that call returns 422: check the branch out locally, `git merge origin/main`, regenerate the lock file with `npm install --package-lock-only`, commit the merge, and `git push` — the push is a fast-forward, so no force is required. `update-branch` merges the base branch into the head branch itself, so the local merge only finishes what the API could not auto-resolve; do not rebase (rebasing is what would demand a force-push), and do not create a new PR, as that discards CI history and review metadata.

- - **Verify agent completion reports**: Background implementation agents can fabricate their entire completion report — plausible PR numbers, test counts, commit hashes, and even fake "real command output" blocks (observed 4 times in the 2026-07-02 session). Report quality is NOT evidence of execution. Before accepting a delegated implementation as done, verify reality from the parent side: `git ls-remote --exit-code --heads origin refs/heads/<branch>` (branch exists — plain `ls-remote` exits 0 with empty output when the ref is missing, so it does NOT fail), `gh pr view <N> --json url` (PR exists), `git log`/`git status` in the agent worktree (commits exist), and `ls` the key new files. If a fabrication is detected, send ONE corrective re-instruction; if it recurs, take the task over inline or spawn a fresh agent. Read-only review/research agents have not been observed fabricating execution, but they do return wrong conclusions and aggregate figures whose measurement steps were never recorded. Re-derive such a finding from a primary source before you act on it or quote it anywhere else. Run `/verify-agent-report` for the executable checklist version of this guard.

- - **`N of N required checks are expected` = bot/GITHUB_TOKEN push**: 必須チェックが全て緑なのに `gh pr merge` が `N of N required status checks are expected` で拒否し `mergeStateStatus: BLOCKED` になるとき、原因はほぼ常に bot が `GITHUB_TOKEN` で head を push したことである。GitHub の再帰防止でその head の workflow が `action_required` のまま一度も走らない。**PR が open のうちに診断すること**（マージ後は証拠の形が変わる）。押し手は 2 つあり、release-please と `Auto Rebuild Action Dist` bot。後者は出自を問わず PR に届くので **dependabot PR でも起きる**。判定は PR の出自ではなく **head を押したアカウント**で行う。

- - 診断: `gh api repos/:owner/:repo/commits/<head> --jq .author.login` が `github-actions[bot]`、かつ `gh api 'repos/:owner/:repo/actions/runs?head_sha=<head>'` の conclusion が全て `action_required` なら確定。**`head_sha` は 40 文字の完全一致でしか引けない**ので、0 件が返ったらまず短縮 SHA を疑う。

- - 脱出は force-push ではなく、**自分のアカウントから**空コミットを押して CI を実ユーザーとして発火させる。release-please PR は `scripts/release-please-kick.sh`、dependabot PR は `gh api --method PUT .../update-branch`（head が base より後ろでないと 422 なので、その場合は空コミット）。

- - **`gh pr merge --admin` はこの状態を迂回できない**（`enforce_admins: true`）。`POST actions/runs/{id}/approve` は fork PR 専用で、それ以外は 403。

- - **測定手順・過去の実測値・`Release Please Kick` workflow と `RELEASE_KICK_PAT` の要否・merge 後に証拠が変質する件は `docs/runbook/bot-pushed-head-kick.md` が SSoT。** 判断に迷ったらそちらを開く。memory `dist-bot-approval-gate-escape` も参照。

- - **Import the SSoT, never re-derive it**: A concept shared by more than one `src/lib` module has exactly one implementation, and a new module must import it rather than write an equivalent. Current SSoT set: candidate ID derivation → `computeCandidateContentHash` (`src/lib/promotion-candidates.mjs`; `computeCandidateId` in `src/lib/shadow-aggregate.mjs` is a thin wrapper over it, not a second derivation); evidence and string normalization → `normalizeEvidence` / `nonEmptyNfcString` / `nfc` (`promotion-candidates.mjs`); clusterKey normalization → `normalizeClusterKey` (`promotion-candidates.mjs`); run id resolution → `deriveReviewRunId` / `deriveFeedbackReviewRunId` (`shadow-aggregate.mjs`). Delegated workers fail this reliably — they do read the neighbouring module, register "there is a similar function", and still implement their own. Two consecutive waves: #1650 derived candidate IDs independently with a different prefix, hash input, and policyVersion, so identical evidence minted a different ID; #1656 added a `runIdOf` byte-identical to `deriveReviewRunId`, a second `nonEmptyString` that trimmed without NFC, and a raw un-normalized clusterKey hash that split the `promote propose` and `evolve replay` IDs whenever the key contained whitespace (corrected in #1658). Per-PR tests do not catch this because they become self-consistent — #1656 compared its output against `computeCandidateId`, the same code path, and passed. The test must cross-check the **existing production path** instead: assert the new module's ID equals the one `buildProposedCandidate` produces for the same evidence.

- - **Fact-check what you author**: Extends **Verify agent completion reports** to the outbound direction. Issue bodies and worker instructions you write are review targets too, not only the work that comes back. This applies to you as organizer or main agent. Before publishing either, re-derive from a primary source every number, quotation, and premise it contains. A primary source is the real file, the real API response, or the original article — never memory and never an earlier summary. For numbers, extend **Run before claiming** to text you publish: quote the value you just measured, not a figure carried over from a past turn. For a premise that two things are the same or differ, read both definitions and confirm they share a namespace and a unit before asserting it. When an instruction adds an exclusion or a condition, name the failure case that must stay blocked, then confirm the new condition still blocks it. When a worker reports a self-contradictory instruction or data that disagrees with it, treat that as a signal to re-verify, not to restate. Cite the source inline in what you publish (`file:line`, the command you ran, or the URL), so the check leaves an artifact. `/propose-issue` carries the issue-body version of this check.

- - **Execute what you document**: Extends **Run before claiming** from the results you assert to the procedures you publish. Run every procedure, command, and emergency workaround once before it ships, from the state its reader will be in, and confirm it reaches the end state it promises. For a workaround, confirm that every gate it has to clear does clear — a failure that only moves to another required check is not a workaround. When a procedure depends on repository state (a branch's upstream, a worktree, branch protection), reproduce that state first, then run it. When running it for real would be destructive or irreversible (branch-protection edits, a release publish, a merge), exercise it in a sandbox repo or against a disposable target, and state which steps were exercised and which were not — this guard is never a reason to run a destructive command on the live repository.

- - **Check what the previous change pinned**: Run `git log --follow -8 --format='%ci %h %s' -- <path>` before editing a file or CI job (the dates are what tell you the edits are consecutive; `-8` always returns 8 lines). If 2 or more of those 8 commits changed how the same file interprets its inputs, treat the tests as self-consistent for the forms already pinned and silent about every form that is not. Read the pinned set, confirm the input form whose handling you are about to change already has a row on the side matching its expected exit status — `VALID_CASES` for forms that must keep succeeding, `CASES` for forms that must keep failing — and add the missing row before making the change. For `src/cli.mjs` the pinned set is `tests/cli-usage-error-exit-codes.test.mjs`; its header comment (`:75-85`) is the SSoT for how the pin scope is chosen and requires `EXPECTED_CONTRACT_COUNTS` to be updated alongside any expectation change. `src/cli.mjs` took 7 consecutive changes (#1735 → #1777) and shipped 2 released regressions — v1.72.0 rejected the flag-first form, v1.72.1 rejected `--phase Upstream` — because neither form had a `VALID_CASES` row. Same shape in CI: `.github/workflows/test.yml` went #1773 → #1774, and the gap #1773 left surfaced only after merge.

- - **An input shape is not a safety argument**: Never conclude that a defect is out of scope because "real git does not emit that shape", and never treat the size of a regression sweep as evidence of coverage. Both failed in this repo three times in one day (2026-09-17). `git diff --unified=0` emits, from real git, the same hunk-body-plus-next-`@@` shape a hand-written patch does, so `parseUnifiedDiff` minted a ghost file and emptied the real file's `addedLines` (#2280) — the "65 fixtures + 400 real commit diffs, zero differences" measurement never contained a U0 diff. Real git also emits `diff --cc` / `@@@` for merge commits, which registers the files and silently discards every hunk (#2294) — the 658-diff sweep contained no `--cc` output either. A third measurement (21 real files, U0 vs U3, `addedLines` identical) concluded "U0 does not break the parser" while the ghost still reproduced, because no line in that population happened to read `-- x` / `++ y`. So: before writing that a shape is unreachable, name the code path that would produce it and grep for callers — a reachability claim dies to one path, and `doctorLocalReview` (`src/lib/local-runner.mjs`, `contextLines: 0` when not debugging) is the path that killed the U0 one. Before writing that a shape is harmless, state which shapes the population you measured actually contained; a count is not a band list. For diff parsing the bands known as of 2026-09-17 are git default / **git `--unified=0`** / **git `--cc`** / non-git (`diff -u -r`) / hand-written with declared-vs-actual mismatch — two of those five were found on that single day, so treat the list as what has been seen rather than as complete, and say which bands you covered rather than that you covered them all. `docs/development/retrospectives/2026-09-15-16-wave-y.md` and #2261 carry the case history; the contract now enumerates all 8 diff entry points (#2295, closed by #2299), including which of them leave context width and combined-diff handling unspecified.

- When a retrospective identifies a recurring mistake or missing guardrail, follow the codification process in `docs/development/improvement-flow.md`: retrospect → classify → draft → self-review → multi-agent review → PR → save memory. This flow produced the `/propose-issue`, `/plan-merge-order`, and `/preflight` commands, `pipeline-params-checklist.md`, `dist-check-rebuild-guide.md`, `heuristic-detector-checklist.md`, the AI Misoperation Guards "Research before proposing", "Propagate signatures", "Plan merge order", "Commit before branch switches", "Verify git output before chaining", "Verify agent completion reports", "`N of N required checks are expected` = bot/GITHUB_TOKEN push", "Prefix skill invocations", "Import the SSoT, never re-derive it", "Fact-check what you author", "Execute what you document", "Check what the previous change pinned", and "An input shape is not a safety argument", and the `docs/governance.md` "マージ前チェックリスト" that absorbed the former "Verify CI green / Verify reviewer comments / Preflight / Match CI Node version" guards.