fix(609): the decisions rationale-edit marker is a git trailer, not a bare substring #618

Merged
timothy merged 5 commits from fix/609-decisions-edit-token into main 2026-07-25 19:07:50 +02:00
Owner

fixes #609

The defect

decisions_validate.py armed the body-diff exemption with a bare substring test over the whole commit range, so any commit message containing the literal marker — including prose about the mechanism — suppressed all three rationale comparisons. It fired live in PR #605: a message explaining why no marker was needed armed it, producing 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.

The fix

An affirmative Decisions-Edit: git trailer (yes/true/1, case-insensitive), read with --no-merges and unfold.

Why a trailer rather than the issue's option 2 (own-line match): own-line fixes the observed instance but not the class. This repo's docs commits routinely quote example commit messages — this PR's own commits and its decision record both do — and an own-line matcher arms on the example. Git parses trailers only in a message's final paragraph, so discussing the marker mid-message can no longer disable anything.

Behavior, verified empirically against git 2.55 (not assumed):

commit message shape arms?
Decisions-Edit: yes as final paragraph ✅
same line quoted mid-body, prose after ❌
retired [decisions-edit] substring ❌ (+ ::warning:: nudge)
Decisions-Edit: no ❌
folded no + continuation yes ❌ (unfold)
forge-composed merge commit body ❌ (--no-merges)
alongside Co-Authored-By: ✅

Verification — measured, not just green

The Done-when box that matters: a gate can merge green yet be a no-op, so I measured the effect.

  • Guard measured on this PR's own range: with the trailer → OK; with the marker forced off → it flags the docs.decision-lifecycle record whose rationale this PR edits. The body-diff dimension is genuinely armed here — the inverse of the vacuous #605 run.
  • Tests mutation-verified: every negative control goes red against the matcher without the fix (and specifically without unfold / without --no-merges). A green suite that cannot fail proves nothing.
  • 59 python tests pass; ruff + format clean on touched files (the 4 remaining ruff findings are pre-existing in scripts/scripted-schedules/entrypoint.py).
  • No .cs touched → BOM/format gate not applicable.

Residual, stated rather than papered over

A quoted example that is the final paragraph of a non-merge commit is a trailer by git's own grammar and will arm the guard. Inherent to any trailer scheme; the record says so explicitly.

--no-merges also costs a narrow false negative: 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 a conflict-resolving merge commit has a legitimate rewrite rejected. That failure is loud and costs one extra commit; honoring forge-composed merge bodies would disable the guard silently, which is #609 itself. Deliberate trade.

Review

Cross-family cold review (different model family than the implementer), 4 rounds. No Blocker or High survived the first round; the logic was never challenged after it. Findings:

  • High — forge-composed merge commit could arm the guard (found independently by both reviewer and implementer) → --no-merges
  • Medium — folded trailer: Decisions-Edit: no + continuation yes armed on the continuation alone, inverting the author's explicit no → unfold. Reviewer's catch; same class as #609 itself.
  • Low ×4 — fail-posture docstring, and three inaccurate justifications of mine (including a claim that merges were "separately forbidden", which reading the hook disproved). All corrected.

Docs (same-PR rule)

docs/decisions.md header + new record ci.decisions-edit-trailer, regenerated catalog, docs/ci-cd.md (3 spots), .gitea/workflows/pr-checks.yml, .claude/hooks/decisions-guard.sh.

Note for #610

#610 rewrites this validator wholesale; it should carry the disciplined matcher forward rather than reintroduce a substring test.

🤖 Generated with Claude Code

fixes #609 ## The defect `decisions_validate.py` armed the body-diff exemption with a bare substring test over the whole commit range, so **any** commit message containing the literal marker — including prose *about* the mechanism — suppressed all three rationale comparisons. It fired live in PR #605: a message explaining *why no marker was needed* armed it, producing 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. ## The fix An affirmative `Decisions-Edit:` **git trailer** (`yes`/`true`/`1`, case-insensitive), read with `--no-merges` and `unfold`. **Why a trailer rather than the issue's option 2 (own-line match):** own-line fixes the observed instance but not the class. This repo's docs commits routinely *quote example commit messages* — this PR's own commits and its decision record both do — and an own-line matcher arms on the example. Git parses trailers only in a message's final paragraph, so discussing the marker mid-message can no longer disable anything. Behavior, verified empirically against git 2.55 (not assumed): | commit message shape | arms? | |---|---| | `Decisions-Edit: yes` as final paragraph | ✅ | | same line quoted mid-body, prose after | ❌ | | retired `[decisions-edit]` substring | ❌ (+ `::warning::` nudge) | | `Decisions-Edit: no` | ❌ | | folded `no` + continuation ` yes` | ❌ (`unfold`) | | forge-composed merge commit body | ❌ (`--no-merges`) | | alongside `Co-Authored-By:` | ✅ | ## Verification — measured, not just green The Done-when box that matters: a gate can merge green yet be a no-op, so I measured the effect. - **Guard measured on this PR's own range**: with the trailer → `OK`; with the marker forced off → it **flags** the `docs.decision-lifecycle` record whose rationale this PR edits. The body-diff dimension is genuinely armed here — the inverse of the vacuous #605 run. - **Tests mutation-verified**: every negative control goes **red** against the matcher without the fix (and specifically without `unfold` / without `--no-merges`). A green suite that cannot fail proves nothing. - 59 python tests pass; ruff + format clean on touched files (the 4 remaining ruff findings are pre-existing in `scripts/scripted-schedules/entrypoint.py`). - No `.cs` touched → BOM/format gate not applicable. ## Residual, stated rather than papered over A quoted example that is the **final paragraph of a non-merge commit** is a trailer by git's own grammar and *will* arm the guard. Inherent to any trailer scheme; the record says so explicitly. `--no-merges` also costs a narrow false negative: 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 a conflict-resolving merge commit has a legitimate rewrite rejected. That failure is **loud** and costs one extra commit; honoring forge-composed merge bodies would disable the guard **silently**, which is #609 itself. Deliberate trade. ## Review Cross-family cold review (different model family than the implementer), 4 rounds. No Blocker or High survived the first round; the logic was never challenged after it. Findings: - **High** — forge-composed merge commit could arm the guard (found independently by both reviewer and implementer) → `--no-merges` - **Medium** — folded trailer: `Decisions-Edit: no` + continuation ` yes` armed on the continuation alone, **inverting** the author's explicit `no` → `unfold`. Reviewer's catch; same class as #609 itself. - **Low ×4** — fail-posture docstring, and three inaccurate justifications of mine (including a claim that merges were "separately forbidden", which reading the hook disproved). All corrected. ## Docs (same-PR rule) `docs/decisions.md` header + new record `ci.decisions-edit-trailer`, regenerated catalog, `docs/ci-cd.md` (3 spots), `.gitea/workflows/pr-checks.yml`, `.claude/hooks/decisions-guard.sh`. ## Note for #610 #610 rewrites this validator wholesale; it should carry the disciplined matcher forward rather than reintroduce a substring test. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
timothy added 5 commits 2026-07-25 18:42:21 +02:00
The rationale-edit exemption was a substring test over the whole commit range, so any
message containing the literal marker armed it -- including prose explaining why no
marker was needed, which is how it fired live in PR #605: 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.

Now read as an affirmative `Decisions-Edit:` git trailer. Git parses trailers only in
the final paragraph, so a quoted example message cannot arm it -- which matters because
this commit and its decision record both quote one. A non-affirmative value (`no`) does
not arm it either; the retired substring arms nothing and gets a ::warning:: nudge.

Tests: negative controls (prose mention, quoted mid-body trailer, `no` value, retired
substring) plus positive controls (trailer, uppercase, alongside Co-Authored-By). All
four negative controls verified red against the old matcher.

fixes #609

Decisions-Edit: yes
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Cross-family review (High + Medium + Low), all three reproduced before fixing:

High -- on a pull_request event actions/checkout lands on a synthetic merge commit whose
body the forge composes from the PR description, so a description ending in an example
marker armed a guard no author armed. Excluded merge commits from the range; merging main
into a PR branch is separately forbidden, so no author-written commit is skipped.

Medium -- a folded value (`no` + continuation ` yes`) was split into independent lines and
the continuation armed on its own, inverting the value the author wrote. Read with `unfold`
so the value is judged whole.

Low -- the module docstring promised fail-open while marker resolution deliberately fails
closed. The posture is right; the docstring was wrong. Documented as the one exception.

Both new negative controls verified red against the unfixed matcher. Decision record
amended to state the residual honestly rather than overclaim: a quoted example that is the
FINAL paragraph of an ordinary commit is a trailer by git's own grammar and does arm. What
the change buys is that discussing the marker can no longer disable anything.

fixes #609

Decisions-Edit: yes
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Review Low x2, both correct and both the stale-comment class:

The claim that prepush-rebase-check.sh forbids merging main into a PR branch is
false. That hook refuses a branch that is BEHIND origin/main; a merge makes
origin/main an ancestor, so the push is allowed. Merging main in is discouraged by
convention only. So --no-merges does cost a real false negative: an author who marks
ONLY a conflict-resolving merge commit gets a legitimate rewrite rejected. Keeping
--no-merges and stating the trade explicitly -- that failure is loud and costs one
extra commit, whereas honoring forge-composed merge bodies disables the guard
silently, which is #609 itself.

The module comment also still claimed a quoted example cannot arm the guard, which
contradicts the residual the decision record now states accurately. Aligned both, and
narrowed the record's Rule line from "some commit" to "some NON-MERGE commit" so the
stated contract matches the implementation.

No logic change -- comments, docstring, record prose and regenerated catalog only.

fixes #609

Decisions-Edit: yes
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Review Low: the module comment and the _edit_trailer_armed summary still said
"a commit message ... does arm" / "some commit", while the matcher excludes merges.
The decision Rule and catalog already carried the qualification; these two did not.
Comment-only.

fixes #609

Decisions-Edit: yes
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs(609): qualify the two ci-cd.md mentions as non-merge
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 12s
PR Gates / Docs update reminder (pull_request) Successful in 12s
PR Gates / decisions lifecycle (pull_request) Successful in 16s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 7m55s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 8s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 7s
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 15m16s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 19m30s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
f49556b6ef
Last review Low, marked safe-to-defer but it is two words in a file this PR already
edits. Both prose mentions of the marker now say "non-merge commit", matching the
decision Rule, the catalog, the module comment and the function docstring.

Docs-only.

fixes #609

Decisions-Edit: yes
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Author
Owner

Cross-family cold review (review-only brief, different model family than the implementer), 4 rounds over the branch and each fix commit.

Round 1 (c597c49f): 1 High, 1 Medium, 1 Low — all reproduced empirically before fixing.
Round 2 (cc9481f5): MERGEABLE, 2 Low — both correct, both factual errors in my justifications.
Round 3 (e9f4444f): MERGEABLE, 1 Low (wording).
Round 4 (f49556b6): clean.

No Blocker at any round; no High or Medium survived round 1, and the logic was not challenged after it — every later finding was documentation accuracy.

Review-verdict: MERGEABLE @ f49556b6

Cross-family cold review (review-only brief, different model family than the implementer), 4 rounds over the branch and each fix commit. Round 1 (`c597c49f`): 1 High, 1 Medium, 1 Low — all reproduced empirically before fixing. Round 2 (`cc9481f5`): MERGEABLE, 2 Low — both correct, both factual errors in my justifications. Round 3 (`e9f4444f`): MERGEABLE, 1 Low (wording). Round 4 (`f49556b6`): clean. No Blocker at any round; no High or Medium survived round 1, and the logic was not challenged after it — every later finding was documentation accuracy. Review-verdict: MERGEABLE @ f49556b6
timothy merged commit 798ecd1f53 into main 2026-07-25 19:07:50 +02:00
timothy deleted branch fix/609-decisions-edit-token 2026-07-25 19:07:50 +02:00
Sign in to join this conversation.