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.
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)
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>
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>
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.
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
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
fixes #609
The defect
decisions_validate.pyarmed 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/--headrun 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-mergesandunfold.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):
Decisions-Edit: yesas final paragraph[decisions-edit]substring::warning::nudge)Decisions-Edit: nono+ continuationyesunfold)--no-merges)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.
OK; with the marker forced off → it flags thedocs.decision-lifecyclerecord whose rationale this PR edits. The body-diff dimension is genuinely armed here — the inverse of the vacuous #605 run.unfold/ without--no-merges). A green suite that cannot fail proves nothing.scripts/scripted-schedules/entrypoint.py)..cstouched → 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-mergesalso costs a narrow false negative: merging main into a PR branch is discouraged but not mechanically blocked (prepush-rebase-check.shonly 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:
--no-mergesDecisions-Edit: no+ continuationyesarmed on the continuation alone, inverting the author's explicitno→unfold. Reviewer's catch; same class as #609 itself.Docs (same-PR rule)
docs/decisions.mdheader + new recordci.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
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