diff --git a/.claude/skills/savegame/SKILL.md b/.claude/skills/savegame/SKILL.md new file mode 100644 index 0000000..e18acb0 --- /dev/null +++ b/.claude/skills/savegame/SKILL.md @@ -0,0 +1,225 @@ +--- +name: savegame +description: "Save the session: the GA-R4 bookend (bounded ledger summary, ledger rotation, memory review) PLUS a full transcript sweep that proves nothing raised in-session would be lost on a context clear. Use at the end of any working session, before /clear, before handing off, or whenever the operator says savegame / save / close out / bookend / wrap up / are we safe to clear. Also use when a session is about to be compacted, and when you find a PRIOR session that ended with no bookend (GA-R4 rule 7 post-hoc close). Repo-specific: it encodes this repository's GA-R1..R7 rules, gate names and paths." +--- + +# savegame + +The end-of-session procedure for THIS repo. It does two jobs that are easy to +confuse: + +1. **The GA-R4 BOOKEND** -- a bounded, durable record of what the session did. +2. **THE SWEEP** -- proof that every finding, decision and measurement raised + in the session already lives on a repo surface, so a `/clear` loses nothing. + +The sweep is the half that gets skipped, and it is the half that matters. Across +the sessions that ran it, the items marked FIRST SURFACE -- existing only in the +transcript -- were consistently the highest-consequence ones. A bookend without +a sweep is a tidy record of work whose findings evaporated. + +## Hard rules this skill does NOT relax + +- **It PREPARES; it does not commit.** Run every gate and write every file, then + present ONE reviewable diff and STOP. The operator commits. (Ruled 2026-07-31, + operator: "Prepare everything, stop before commit (Recommended)".) +- Hard rule 1 still applies: findings are **LOGGED, NOT EXECUTED**. If the sweep + finds a defect, it goes in the sweep file. It does not get fixed here. +- Hard rule 2 still applies: every number in the summary is QUOTED from captured + output. Never from memory, never from another document's prose (GA-R1 rule 2). +- Status claims go ONLY in `docs/CURRENT-STATE.md`. The ledger records session + NARRATIVE; a ledger line touching status is a pointer, never a claim (GA-R4 r5). + +--- + +## Step 1 -- Durability triad (do this FIRST; it is the only irreversible risk) + +A session that ends unpushed is not durable, and this is the one failure a clear +makes unrecoverable. Check all three, not just the first: + +```bash +git status --porcelain | wc -l # want 0 +git log @{u}..HEAD --oneline | wc -l # want 0 (unpushed) +``` + +Then **every execution host's clone**, not just this one. The 2026-07-27 +stale-clone hazard is why this is checked rather than assumed, and on +2026-07-31 `voffice1` was found 6 commits behind at close. + +**Never hardcode the repo's own name or path** -- it has been renamed/forked once +already (D-110) and will again. Discover the remote-side clone the same way the +parent skill does, from a `$REPO` set once per session or from `git remote -v`: + +```bash +ssh voffice1 "cd \"\$REPO\" && git fetch -q; git rev-list --count HEAD..@{u}" +``` + +Under D-138 the DC client hosts matter too -- the dc0 rack carries a +`~/repo-stage/` copy of `bundle.yaml` + overlays with NO git at all. A staged +copy that has drifted from the repo is a silent deploy hazard: compare digests, +do not assume. + +**A lagging clone is not a loss** (the remote has the work) **but it IS a +hazard** and belongs in the summary. + +## Step 2 -- Gates, all of them, and quote the numbers + +```bash +bash scripts/repo-lint.sh # expect 0 fail +bash scripts/run-tests-all.sh # expect ALL GREEN (n harnesses) +bash scripts/ledger-scan.sh # open decisions, SEC count, next-free numbers +``` + +Quote the ACTUAL numbers into the summary. If a gate is red, the summary says so +plainly with the failing line -- a close that hides a red gate is worse than no +close. Note `run-tests-all.sh --record-manifest` WRITES the manifest; never pass +it here. + +**Reconcile ledger-scan against what the session CLAIMED.** If the session opened +SEC rows or assigned D-/DOCFIX-/BUNDLEFIX numbers, the scan's next-free values +must have moved accordingly. A mismatch means a number was assigned and not +recorded, or recorded and not assigned. + +## Step 3 -- THE SWEEP (the half that gets skipped) + +Method, ruled 2026-07-31 ("Model reads the session, then greps each candidate"): + +**(a) Enumerate.** Read back over the whole session and list EVERY: +- finding, defect or surprise -- including ones already fixed; +- measurement that contradicts a standing document; +- decision or operator ruling, with its exact utterance; +- trap, workaround or environment fact discovered; +- own-mistake (see Step 5); +- thing deliberately NOT done, and why. + +Do not filter for importance yet. The 2026-07-30 sweep's most valuable item was +a permission-rule text that looked like housekeeping. + +**(b) Prove each one, mechanically.** For every candidate, grep the repo for it: + +```bash +grep -rn "" docs/CURRENT-STATE.md docs/changelog-*.md docs/ runbooks/ scripts/ +``` + +An item with a hit is ALREADY ON SURFACE -- record where. An item with no hit is +**FIRST SURFACE** and would have been lost. This grep step is not optional: an +unverified "that's already recorded" is precisely the claim that has been wrong +before. + +**(c) Write it** to `docs/audit/queued-findings--