chore(log): the handoff log was serialising every parallel branch

DECISIONS-LOG.md was append-only in ONE file and every agent appended to its tail, so any two concurrent branches collided on the same last hunk. Measured against the live Gitea today: four of the five open PRs were mergeable=false, and `git merge-tree` named DECISIONS-LOG.md as the ONLY conflicting path in all four. #22 fix/crafty-oauth2-proxy-signin CONFLICT: DECISIONS-LOG.md #20 feat/conformance-job-template CONFLICT: DECISIONS-LOG.md #19 feat/conformance-trigger-kubeconfig CONFLICT: DECISIONS-LOG.md #18 feat/conformance-runner-image CONFLICT: DECISIONS-LOG.md #17 feat/ci-is-the-approver clean — it wrote no handoff Nothing was wrong with any of those changes. The log's storage format serialised work that was otherwise parallel, and the cost grew with every concurrent branch (N branches -> N-1 rebases, each invalidating the gate run before it). The agents work in isolated worktrees precisely so they do not block each other; this one file undid that. So: stop sharing a file. Handoffs are now one-per-file under decisions/, named YYYY-MM-DD-<slug>.md. Disjoint paths have nothing to merge. There is deliberately no index file (a shared mutable file is the thing that just failed) and no counter (two agents would race for the same number) — the directory listing is the index. DECISIONS-LOG.md is frozen as the pre-2026-09-29 archive, its SHA-256 pinned in decisions/ARCHIVE.sha256, and a new gate stage rejects any change to it. That is a guard and not a paragraph because the old habit is written into the runbooks and into every agent that has read the log, and getting it wrong does not fail: it produces a clean-looking commit that re-creates the conflict on OTHER branches, later, misattributed. ci/decisions-log.sh new stage: archive pinned; every entry named with a real date, carrying date/branch/title frontmatter that agrees with its filename, and all three of CLAUDE.md §7's sections with a real body under each. Exit 0 or 1 only — no skip path by construction, so no fail-open surface on a guard that closes one. ci/gate.sh runs it; fail and (impossible) skip both BLOCK. No REQUIRE_DECISIONS_LOG knob: a guard with an off switch is not a guard. ci/tests/decisions-log.test.sh 22 assertions, incl. the one that matters — an append to the archive is rejected, and the message names the file to write instead. ci/tests/gate-decision.test.sh +3 assertions for the new wiring, AND a pre-existing bug: the stub list never included gitea-settings, so run_stage saw exit 127 and recorded a FAILED stage in every case. 15 of 47 assertions failed on main for that reason alone — the suite was measuring its own missing stub. Now 50/50. CLAUDE.md §7 rewritten; §2b widened to the new path. ci/Makefile, ci/README.md, .gitea/workflows/README.md — stage named where the other stages are named. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
2026-09-29 22:35:55 -05:00
1 parent cadf64a514
commit 72a46ad82d
@@ -1,7 +1,7 @@
 # CLAUDE.md — how work lands in this repo

 Read this before doing anything durable. It is the delivery contract for AI coding
-sessions and agents. `DECISIONS-LOG.md`'s last entry is the current PM handoff and
+sessions and agents. The newest entry in `decisions/` is the current PM handoff and
 takes precedence on *what* to work on; this file governs *how* it lands.

 ## 1. Never push to `main`. Ever.
@@ -48,9 +48,10 @@ reports as `success`, so a green tick is not by itself evidence that anything ra

 ## 2b. Never infer platform state from this repository

-**This repo is not evidence about the live platform.** Neither is `DECISIONS-LOG.md`.
-Both describe what someone believed at the time of writing, and both have been
-confidently wrong for a month at a stretch.
+**This repo is not evidence about the live platform.** Neither is the handoff log
+(`decisions/`, and the frozen `DECISIONS-LOG.md` archive). Both describe what someone
+believed at the time of writing, and both have been confidently wrong for a month at a
+stretch.

 On 2026-09-29 the log stated the merge gate was a required status check with a runner
 online. The API said `branch_protections: []` and **zero** runners. Everything downstream
@@ -139,9 +140,32 @@ invocations concurrently.
  flow. Do not design around committing one — read the expiry from the issuing page and
  treat a burnt token as free to retry.

-## 7. Before you finish
+## 7. Before you finish — write a handoff entry, in its OWN file

-Append a handoff entry to `DECISIONS-LOG.md` describing what you changed, what you
-verified, and what you did **not** verify. State gaps plainly — an honest
-"UNVERIFIED" is worth more than an optimistic "green", and this repo has already been
-burned by the difference.
+Add **one new file**:
+
+    decisions/YYYY-MM-DD-<slug>.md          <slug> = your branch's last segment
+
+with frontmatter (`date`, `branch`, `title`) and exactly these three sections:
+
+    ## What changed
+    ## What I verified
+    ## What I did NOT verify
+
+State gaps plainly — an honest "UNVERIFIED" is worth more than an optimistic "green",
+and this repo has already been burned by the difference. All three headings are
+**enforced** by `ci/decisions-log.sh`, because the third is the one that gets dropped.
+Template and full rationale: `decisions/README.md`.
+
+**Do NOT append to `DECISIONS-LOG.md`.** It is a frozen archive (pre-2026-09-29), its
+SHA-256 is pinned in `decisions/ARCHIVE.sha256`, and the merge gate rejects any change
+to it. Appending to its tail is what every agent used to do, and because every branch
+appended to the *same last hunk*, no two concurrent branches could auto-merge. Measured
+on 2026-09-29: **four of the five open PRs were `mergeable: false`, with
+`DECISIONS-LOG.md` the only conflicting path in all four** — none of those changes had
+anything to do with each other. Separate files have nothing to merge, which is the
+entire fix. Note that the damage from getting this wrong lands on *other people's*
+branches, later, which is why it is a gate stage and not a request.
+
+Many older handoff entries and runbooks say "append to `DECISIONS-LOG.md`". That
+wording is **stale**, in the same way §1's `git push origin main` wording is stale.