feat(overnight-multi-issue-implementation): seven lessons from an 11-hour, 20-PR overnight run (1.3.0)

[wan-huiyan]

Seven additions to overnight-multi-issue-implementation, all distilled from one overnight run — 17 items, 20 merged PRs, 4 orchestrated workflows, 91 subagents, ~11 hours. Each one cost real work on that night.

What's new in the SKILL body

#	Where it lands	What it says
1	New subsection at the top of the tier rubric	Never truncate a findings payload. Three reviewers returned six critical findings; the merging agent got JSON.stringify(reviews).slice(0, 9000) and five arrived. The sixth was cut mid-object and was the worst of the six. Everything visible said the gate had worked. Make the actor report received-vs-answered; keep the run journal as the recovery path.
2	New top-level section after the collision audit	Coordinating with sessions you do not control. A branch you can diff; a live agent session you can only negotiate with. Claim id + state + label + file list on a committed shared board. Append, never replace. Don't drop the claim while your PRs are open. Nothing expires it.
3	New top-level section after (2)	Amend a running orchestration through a file on disk, not the script. Editing the script changes every agent prompt, so a resume re-runs completed work instead of replaying from cache — here that would have discarded eight finished PRs.
4	Appended to the collision-audit section	A third kind of collision neither pre-flight audit can see: the same piece of work, twice, under two names, in a live session's uncommitted tree. Gate rather than parallelise, then extract and prove the refactor changed no result.
5	Appended to the "baseline clean" callout	Your own brief's baseline numbers go stale mid-run. A parallel PR re-derived the test counts mid-flight (269 → 314) and a later item quoted its brief. Measure on your own rebase; never carry a count from a document.
6	New top-level section before Phase C	What an autonomous run may and may not decide. An assumption is a default, not a ruling. For pre-registered questions: DISCLOSE, not COMPUTE. An un-run unit is "no result", not "inconclusive". Production changes in the reverting direction only, on unanimous reviewer authorisation. Merging is a separate grant from changing production.
7	Appended to the tier rubric's reviewer prompts	A verbatim reviewer line: "Check whether this change ships a fresh instance of the defect it repairs." Five of the twenty merged PRs did. Most common finding of the night, and every instance was caught by re-deriving a number, never by reading the diff. Plus: dropping an honest positive is drift too.

SKILL.md 553 → 742 lines.

Verified absent before splicing

All seven were grepped against 1.2.2 first. None was already present. The nearest existing neighbours are noted below because they needed seam work, not because they duplicated anything.

Seams adjusted (connective tissue only — no draft content rewritten)

• The tier-rubric intro says "the 3-tier rubric below", and block 1 now sits between it and Tier 1 — one sentence added so the pointer still reads.
• Block 6 says merging its own PRs is a grant. Phase C step 4 and the anti-patterns say "implement" is never "merge" by implication. One sentence now states the relationship: neither grant is implied by the instruction to implement, and the two grants are independent of each other.
• The "Don't auto-deploy after merge" anti-pattern would otherwise argue against block 6's production paragraph. It now names the one bounded exception (return production to the prior behaviour, unanimous authorisation). A doc arguing against its own shipped guidance is a landmine; this closes it.
• Block 7 sat visually under Tier 2. Its scope line now says "Tier 1's review-panel prompts included".
• overnight-review-panel-blocked-reviewer-reads-as-clean is now listed in References — the body cites it, and it's a live plugin in this bundle (not a dead cross-reference).

What the self-review caught, and fixed

An independent reviewer read the spliced result against CONTRIBUTING.md. Three real defects, all fixed in this PR:

1. "The observed run" was never defined in the shipped file. Five new passages rest on it — including the load-bearing "five of twenty merged PRs" — while the only run the file described was the 2026-05-08 chatbox session (2 PRs, ~6 hours, ~38 dispatches). A reader following the phrase landed on numbers that contradicted it, and the run that actually backs the prose lived only in the README and the commit message, neither of which ships to an installed user. Fixed: the Overview now names the run the phrase means, and a second worked example at the end gives it, with each lesson traced to what it cost.
2. The production carve-out quietly removed the human. The anti-pattern demands "human review for high-stakes changes"; the new exception permitted a change on "unanimous reviewer authorisation", and everywhere else in the file a reviewer is a subagent. As written, the run could change production unattended but could not merge a PR without waking someone. Fixed at both ends: the reviewers are named as the run's own agents, no human is in the loop at 3am, that is why the direction bound comes first, and anything that is not a revert still waits for a person.
3. The stale-baseline lesson collided with the recipe three lines above it. That recipe defines the baseline as a failing-set snapshot taken once, before the chain; the new text said to measure it "on its own rebase" — which absorbs an earlier PR's regression into the new baseline and then prints IDENTICAL over it. Fixed: the two are now distinguished — what you must never quote from a document is the suite's headline count, not the pre-chain snapshot.

Two smaller ones from the same read: the companion-skill pointer had been left below the new third-collision paragraphs, where it read as covering them (it is branch-based by construction; the third kind is defined by having no branch) — moved above, and it now says so. And resumeFromRunId was named without saying what provides it.

Two pre-existing anonymization scars in files this PR already touches, fixed while here: for the\nthe project (SKILL.md) and the project propensity project (README.md) are both the visible seam of an old scrub, not identifiers.

Deliberately not fixed, flagged instead: plugin.json's description still reads "v1.2.0 adds Phase 0 …" while shipping 1.3.0. Editing it means editing a description, which this PR promised not to do; it under-sells two minors of content but is not wrong.

One thing in the draft was wrong

The draft called block 4 "a fourth collision the file audit cannot see". The document establishes two collisions (ID-level in the tracker-id audit, file-level in the branch audit); the three-item list it follows is a list of decisions, not collisions. Changed to "a third kind of collision, and neither pre-flight audit can see it".

Versions — every place this repo records one

The failure mode #20, #21 and #24 all had to come back for is a content change that never ships because a version did not move. All four moved here:

SKILL.md frontmatter                    1.2.0 -> 1.3.0
plugins/.../.claude-plugin/plugin.json  1.2.2 -> 1.3.0
.claude-plugin/marketplace.json         1.2.2 -> 1.3.0
VERSION (bundle)                        1.2.1 -> 1.3.0

Two drifts closed on the way:

• The SKILL.md frontmatter was still at 1.2.0 — the 1.2.1 and 1.2.2 bumps were manifest-only, so the file's own header disagreed with what shipped.
• VERSION was a patch behind the plugins (1.2.1 vs 1.2.2), because the last two bumps didn't touch it. release.yml's own comment says "Bump VERSION in the same PR as the version bump", so it moves here. This will cut a v1.3.0 GitHub release on merge — flagging it explicitly since it is the one side effect of this PR that isn't a docs change.

Description untouched

No description field changed anywhere. The gate reports overnight-multi-issue-implementation at 1,463 chars, 73 to spare — byte-identical to the pre-change run.

Gates

python3 scripts/check_skill_descriptions.py . --no-color --triggers   exit 0
scripts/leak_scan.sh .                                    LEAK GATE: clean, exit 0
python3 .github/scripts/validate_plugins.py    OK: marketplace + plugins valid, exit 0

Listing budget, --context 1000000:

Listing budget @ 1,000,000 ctx
  needed     30,504 chars  (~7,626 tok)
  budget     40,000 chars  (~10,000 tok)
  fits, 9,496 chars to spare

(At the default 200k context the whole install is still over budget by 22,504 chars — unchanged by this PR, which adds no description text.)

core.hooksPath is set to .githooks; the pre-push hook ran both gates on the push.

Leak check

The additions name one project-relative path (docs/site/assets/live.json), generic counts, and one filename (journal.jsonl). No client names, no emails, no keys, no tokens. Gate clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_013JVMGELnoA2vM56Va4gLXE