timothy
fba5233caf
168 records -> docs/decisions/records/<area>/<topic>.md (163 active, 23 dirs) and docs/decisions/archive/<area>/<topic>.md (5 archived). The filename IS the key, so one-active-record-per-key becomes a filesystem property rather than a validator check, and supersession becomes a `git mv`. WHY: the monolith was a concurrency problem before an aesthetic one. A 3,900-line append target made parallel sessions collide -- PR #605 and PR #614 both hit append-vs-append conflicts during routine rebases, and hand-resolving those inside the corpus is exactly the operation the rationale-rewrite guard exists to police. HOW IT IS VERIFIED: a ~170-file diff cannot be meaningfully read, so correctness does not rest on reading it. The parser was taught BOTH formats first, so the body-diff guard parses the old form at the merge-base and the new form at head -- the migration validates itself, no bypass. The proof is a field-level equivalence harness: 168 records before and after, zero lost, zero gained, zero field mismatches, zero rationale bodies differing. Reviewers should scrutinise the harness; it is the actual evidence. What measuring caught that reading would not have: - ~500 lines sit OUTSIDE any record -- decisions.md's lifecycle schema and each topic file's preamble, mostly the only copy. Source files are kept and stripped, never deleted. They also cannot be filed per-area: topic files hold several areas and 4 of 23 areas span several files. - Archive discovery was a non-recursive glob; after the split it found ZERO archived records, surfacing as four bogus "supersedes points to unknown key" errors rather than an obvious failure. - ~32 live docs point into the corpus BY DATE, which the split dangles. Each stripped file now ends with a generated "Records formerly in this file" index, which also rescues the identical breadcrumbs in old issue comments. - decisions.md's "In this file:" list was 97 same-file anchor bullets that the split makes WRONG, not merely stale. Dropped; the generated index replaces them with links that resolve. The equivalence harness now runs against a checked-in FIXTURE, not the live corpus. The earlier version migrated the real tree, which made it a one-shot: the moment the migration landed there was nothing left to move and the tests failed for reasons unrelated to the code. A fixture keeps them testing the SCRIPT rather than the repo's current state. Keys preserved verbatim, warts included: `sched` (12) and `scheduling` (1) remain two directories for one concept. Renaming a key is not a move -- it changes identity, breaks the equivalence proof, and invalidates MemPalace's per-key drawers. Taxonomy normalisation is separate work. refs #610
4.4 KiB
key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
| key | title | status | since | supersedes | superseded-by | rule | signals | mechanics |
|---|---|---|---|---|---|---|---|---|
| ci.decisions-edit-trailer | 2026-07-25 — The rationale-edit marker is a git trailer, not a substring anywhere in the commit range (#609) | active | 2026-07-25 | none | none | The body-diff exemption is armed by an affirmative `Decisions-Edit:` **git trailer** (`yes`/`true`/`1`, case-insensitive, read with `unfold`) on some NON-MERGE commit in the PR's merge-base range — never by a substring search over the message text. A non-affirmative value (`no`) does not arm it, the retired `[decisions-edit]` substring arms nothing (the validator emits a `::warning::` nudge when it sees one without a trailer), and a git error leaves the guard ON. | decisions-edit, Decisions-Edit trailer, rationale-prose edit, body-diff guard, decisions_validate, vacuous gate, green no-op · paths: `scripts/decisions_validate.py`, `scripts/tests/test_decisions_validate.py` · issues: #609, #603, #521 | `git log --no-merges --format='%(trailers:key=Decisions-Edit,valueonly,unfold)' <mb>..<head>`; `dv._edit_trailer_armed` |
The guard could disable itself by being described. The original check was
EDIT_TOKEN.lower() in git log --format=%B mb..head, so any commit message containing the literal
string anywhere set token = True and suppressed all three rewrite comparisons (active survivors,
active→archive laundering, archive survivors). It fired live in PR #605: a commit message explaining
why no token was needed contained the bracketed token, and armed it. The result was a green
--base/--head run that was vacuous on the body-diff dimension, in the one PR that hand-resolved a
merge conflict inside the corpus the guard exists to police. No content was damaged, but the gate
reported success while checking nothing — the "a gate can merge green yet be a no-op" class.
Why a trailer and not an own-line match. Requiring the token alone on its own line fixes the
observed instance, but not the class: this repo's docs commits routinely quote example commit
messages, and the commit introducing this very record does so. An own-line matcher would arm on the
example. Git recognises a trailer only in the message's final paragraph, so a Decisions-Edit: yes
line quoted mid-body followed by more prose parses as nothing at all (verified against git 2.55).
Requiring an affirmative value closes the same trap one level up: Decisions-Edit: no, the natural
way to record a deliberate non-edit, must not read as consent.
Three exactness requirements the naive trailer read still gets wrong (all found in review, all
regression-tested). --no-merges: on a pull_request event actions/checkout lands on a synthetic
merge commit whose body the forge composes from the PR description, so without it a description
ending in an example marker arms a guard no author armed. That exclusion is not free: merging main
into a PR branch is discouraged but not mechanically blocked (prepush-rebase-check.sh only refuses a
branch that is behind main, and a merge makes main an ancestor), so an author who marks ONLY such a
merge commit has a legitimate rewrite rejected — a LOUD failure costing one extra commit, deliberately
preferred over silently disabling the guard. unfold: a folded Decisions-Edit: no + continuation
yes otherwise yields two lines, and the continuation arms on its own — inverting the value the
author wrote. And resolving the marker fails closed on a git error, the one deliberate exception
to this module's fail-open posture: a fail-open marker lookup is #609 through a different door.
The residual, stated rather than papered over: a quoted example that is the final paragraph of an ordinary commit message is, by git's own grammar, a trailer — and will arm. That is inherent to any trailer scheme; what the change buys is that merely mentioning or discussing the marker, which is what actually happened in #605, can no longer disable anything.
The marker's scope is unchanged — still narrow, still only for a rationale-prose edit to a
surviving or archived record (docs.decision-lifecycle); only its form changed. It coexists with the
Co-Authored-By: trailer the commit-msg hook already mandates, so armed commits carry a
multi-trailer block. The retired form is left detectable on purpose: a contributor with the old habit
gets a warning naming the form change, not a bare "prose changed" failure.