diff --git a/docs/reorg/2026-10-14-tidy/HANDOVER.adoc b/docs/reorg/2026-10-14-tidy/HANDOVER.adoc new file mode 100644 index 000000000..9210dad19 --- /dev/null +++ b/docs/reorg/2026-10-14-tidy/HANDOVER.adoc @@ -0,0 +1,293 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += Handover: running the tidy-up packets from fresh sessions +Jonathan D.A. Jewell (hyperpolymath) +v1.0.0, 2026-10-14 +:toc: left +:toclevels: 2 +:sectnums: +:icons: font + +[.lead] +The plan in link:README.adoc[README.adoc] was written by one session, and +its first packet (P1.1, #1244) was executed by a sonnet-tier worker under +supervision. From here each packet runs in its own session. This note is +what that session needs beyond the plan: the session rules, what P1.1 +taught, the environment it lands in, the gates that bite, the reviewer +brief, and paste-ready prompts. + +Reading order for a packet session: `README.adoc` _Guardrails for every +packet_, this note, the packet's own row, then the tier briefing in +`3-practice/ai-instruction/`. + +== Session model + +* One packet, one session, one branch, one pull request. The branch is + `tidy/` from the current `main` (so `tidy/p1-4`). + The PR title is `chore(tidy): P1.4 — `. +* The session ends when the PR is merged or the owner closes it. A merged + branch is finished: do not restart it and do not stack a second packet on + it. P1.1 restarted a merged branch and the Debt ratchet went red on a + trailer carried over from the merged history; a fresh branch cannot have + that problem. +* The worker never merges, never force-pushes, never admin-overrides, and + never resolves a review thread it did not answer. The owner merges after + the reviewer approves. +* The PR body carries: the packet id and a link to the plan; the authority + for each change (ruling id, map target, or "applied-unless-struck, D113" + with the (E) arm named); the packet's acceptance block with the result of + every line pasted verbatim; and a "not done" list. A green that did not + run is not green. +* Concurrency cap, from + link:../../../3-practice/ai-instruction/opus.adoc[opus.adoc]: at most three + packet sessions open at once. Private-repo work is sequential; nothing in + Phase 1 or 2 touches a private repo. + +== Which packets can run side by side + +[cols="1,2,3",options="header"] +|=== +| Group | Packets | Why + +| Parallel-safe now +| P1.5, P1.8 +| Disjoint files: the mirror reusable and the mirror vars; the + community-health files and the map. + +| Serial, one session, in this order +| P1.4, then P1.10, then P1.7 +| All three delete entries from `.hypatia-baseline.json`; parallel branches + would conflict on the JSON array. P1.4 also edits validators and + `ci-pipeline`. + +| Owner approval first +| P1.2 then P1.9; P1.3 +| P1.2 closes or merges 63 issues on the strength of the dispositions table; + the owner says the table is approved before a bot closes anything. P1.3 + only labels (reversible) but reads the same table. P1.9 follows P1.2. + +| Owner action first +| P1.6 +| Needs an admin token to force-cancel the stuck Pages run, and the D341 + ruling (Pages or docs-only). + +| Serial, after the Phase 1 file packets merge +| P2.1 to P2.6, one session +| Every Phase 2 packet edits `standards-map.toml` and the README routing. +|=== + +Phases 3 to 8 do not start until Phase 2 lands; their rows in the plan say +what each waits on. + +== What P1.1 taught + +The worker got 186 of 188 dispositions right. The two it got wrong are the +shapes to watch for, and the rest are the habits that caught them. + +* *Code-scanning acks are tripwires, not findings.* A baseline entry whose + rule id starts `CSA` echoes live alert state that cannot be re-verified + from the tree. It is kept (re-acked to #957) even when the file looks + clean. The worker deleted one as "unverifiable". +* *A tracker must be an issue that will stay open.* The worker pointed four + acks at #1173, which the dispositions table marks for closure; #1243 was + opened instead. Before naming an issue as `tracking_issue`, check the + table. +* *Verify against the file or the pinned rule, not the issue text.* The + plan's counts came from issue bodies written weeks earlier; the 21 + "expiring" acks were all dead by the time the packet ran. Re-measure, + then act. +* *The baseline format is byte-exact.* `.hypatia-baseline.json` must + round-trip through `jq -a --indent 1 .` unchanged, or the validator diff + is noise. +* *Widening is declared, never absorbed.* P1.1 deleted 28 entries outside + its brief because a CI replay proved them dead; the PR body said so and + offered the block for revert. Widen only with proof, and say so. + +== The environment a session lands in + +* The cloud container has `git`, `jq`, `bash` and `bun`. It does not have + `just`, `nickel`, `shellcheck`, `actionlint`, or a working `yq` (the one + installed is a stub). Run recipes as `bash scripts/