fix(record): find the trailer block where the merge tool left it (#406)

.agents/claims/CLAIM-ENG-TRAILER-MERGE-ARTIFACTS.md

@@ -0,0 +1,5 @@
+# CLAIM-ENG-TRAILER-MERGE-ARTIFACTS
+
+| Claim | Row IDs | Agent | Worktree / remote dir | Branch | Owned scope | State | Last update |
+|---|---|---|---|---|---|---|---|
+| `CLAIM-ENG-TRAILER-MERGE-ARTIFACTS` | `ENG-TRAILER-MERGE-ARTIFACTS` (`ACTIVE`) | Claude Code (opus-5), helper role | isolated worktree `/home/mudler/_git/vllm.cpp-trailers`; no GPU, no registry, no publication | `row/ENG-TRAILER-MERGE-ARTIFACTS`, issue [#406](https://github.com/mudler/vllm.cpp/issues/406) | Owns ONLY: NEW `.agents/specs/trailer-merge-artifacts.md`; the paragraph-fusion helpers in `scripts/check-commit-trailers.py`; and the five cases in `tests/scripts/test_check_commit_trailers.py`. EXCLUDES every other rule in that checker, the merge-method process change the spec names as follow-up, and all product source | `ACTIVE` | 2026-08-11 — fix implemented; 21/21 green; the five real `main` commits re-verified and the verdict table reproduces |

.agents/roadmap_v1.md

@@ -36,7 +36,6 @@ issue is not yet placed. Keyed record: update in place, never append.
 
 | Issue | Row | Title | Kind |
 |---:|---|---|---|
-| [#391](https://github.com/mudler/vllm.cpp/issues/391) | `PERF-CPU-DECODE-BARRIER` | CPU backend: batch-1 decode is barrier-bound (47% sync), and paged attention branches per element | perf |
 | [#168](https://github.com/mudler/vllm.cpp/issues/168) | `BACKEND-CUDA-SM110` | Jetson AGX Thor (sm_110): 32B NVFP4, Tekken tokenizer blocker | feature |
 | [#199](https://github.com/mudler/vllm.cpp/issues/199) | `BACKEND-METAL-MLX` | macOS MLX build fails on `-Werror` in MLX headers | bug |
 | [#41](https://github.com/mudler/vllm.cpp/issues/41) | `BACKEND-ROCM` | ROCm (AMD GPU) backend | feature |
@@ -54,6 +53,7 @@ issue is not yet placed. Keyed record: update in place, never append.
 | [#117](https://github.com/mudler/vllm.cpp/issues/117) | `ENG-RELEASE-BINARIES` | Binary release | feature |
 | [#170](https://github.com/mudler/vllm.cpp/issues/170) | `ENG-RELEASE-BINARIES` | Publish container images to GHCR (cuda, vulkan, cpu) | feature |
 | [#322](https://github.com/mudler/vllm.cpp/issues/322) | `ENG-RELEASE-BINARIES` | Release handoff collides with tracked checkout `assets` directory | bug |
+| [#406](https://github.com/mudler/vllm.cpp/issues/406) | `ENG-TRAILER-MERGE-ARTIFACTS` | The trailer gate fails on how commits LAND: GitHub's Co-authored-by displaces the trailer block | bug |
 | [#206](https://github.com/mudler/vllm.cpp/issues/206) | `KERNEL-SSM-MAMBA` | RTX 5070 Ti: close Qwen3.5-4B TTFT, TPOT and VRAM gaps vs vLLM — owns the sm_120 post-conv token tile and the K=4 causal-conv arm (PR #155) | feature |
 | [#305](https://github.com/mudler/vllm.cpp/issues/305) | `KERNEL-SSM-MAMBA` | GDN causal-conv: the `conv_state` initial-state read races the final-state write across blocks (`VT_CONV_REG` + exact chunks, both default ON) | bug |
 | [#396](https://github.com/mudler/vllm.cpp/issues/396) | `KV-EXTERNAL-CACHE` | `test_lmcache_connector` data race under TSan: `MockLmcacheServer` writes non-atomic `listen_fd_` before joining its accept thread | bug |
@@ -68,6 +68,7 @@ issue is not yet placed. Keyed record: update in place, never append.
 | [#359](https://github.com/mudler/vllm.cpp/issues/359) | `MODEL-MM-muse-glimmer-muse-glimmer-for-conditional-generation` | Muse Glimmer GGUF k-quant generates INCOHERENT text where llama.cpp on the same file is coherent | bug |
 | [#298](https://github.com/mudler/vllm.cpp/issues/298) | `PERF-27B-LMHEAD-DSR` | `main` is RED on the `device-leakage` DSR ratchet: `PrepareLmHeadResident` added a 33rd `vt_ifdef` to the shared layer | bug |
 | [#213](https://github.com/mudler/vllm.cpp/issues/213) | `PERF-27B-LMHEAD-FP4` | Qwen3.6 NVFP4 baselines (27B and 35B-A3B) must reach vLLM speed parity | perf |
+| [#391](https://github.com/mudler/vllm.cpp/issues/391) | `PERF-CPU-DECODE-BARRIER` | CPU backend: batch-1 decode is barrier-bound (47% sync), and paged attention branches per element | perf |
 | [#299](https://github.com/mudler/vllm.cpp/issues/299) | `ROAD-V1-C1` | `FUSION-DENSE-MIGRATE`: 5 dense SwiGLU models bypass the MUST-route merged-GEMM seam with no stated blocker (spec [`fusion-dense-migrate.md`](specs/fusion-dense-migrate.md)) | bug |
 | [#314](https://github.com/mudler/vllm.cpp/issues/314) | `ROAD-V1-C1` | `FUSION-DENSE-MIGRATE` glue half: `glm4`/`phi3` still hand-call add+RMSNorm instead of `vt::FusedChain` (split out of #299, which closed the merged-GEMM half only) | bug |
 | [#337](https://github.com/mudler/vllm.cpp/issues/337) | `ROAD-V1-C1` | `FUSION-DENSE-MIGRATE`: the five dgx SACRED paged-engine gates are OWED after the merged-GEMM fold (`test_{commandr,glm4,minicpm,minicpm3,phi3}_paged_engine` SKIP on a CPU box) | bug |

.agents/specs/trailer-merge-artifacts.md

@@ -0,0 +1,156 @@
+# The trailer gate rejects correct commits because of paragraph placement
+
+Issue: [#406](https://github.com/mudler/vllm.cpp/issues/406).
+Row: `ENG-TRAILER-MERGE-ARTIFACTS`. Related: [#274](https://github.com/mudler/vllm.cpp/issues/274).
+
+`main` is red on the `agent-record` job. The trailer gate is failing on **how
+commits land**, not on how they are written, and one of its failure modes rejects
+a commit that is entirely correct.
+
+## Scope
+
+**In scope.** How `scripts/check-commit-trailers.py` locates the trailer block.
+
+**Out of scope, deliberately.** The uniqueness rule, the forbidden-AI-trailer
+rule, and every other assertion the checker makes. No rule is relaxed; only the
+*location* of the block changes. No product source is touched.
+
+## Upstream chain
+
+None. vLLM has no counterpart to this protocol machinery, so the mirror rule does
+not apply and there is no upstream `file:line` to port from. Governed by
+`AGENTS.md` §"Changing the rules or a checker", which requires a spec, a
+red-before test or mutation, and green-after evidence, and forbids turning a red
+gate green by deleting an assertion or widening a scope.
+
+## Our baseline — five failures, only one of which is the gate's fault
+
+`check-commit-trailers.py` reads trailers through `git interpret-trailers
+--parse`, which by design treats **only the final paragraph** as the trailer
+block. Measured on `main`:
+
+```console
+$ git show -s --format=%B dbd0d51c | git interpret-trailers --parse
+Co-authored-by: Ettore Di Giacinto <mudler@localai.io>
+```
+
+That commit carries a complete, correct trailer block. Git cannot see it, because
+GitHub appended `Co-authored-by:` as a separate trailing paragraph. The checker
+counts zero and reports the trailers missing.
+
+**13 of the last 30 commits on `main` fail this check.** They did not red CI at
+the time only because those runs were cancelled (#274) — the cancellation hid the
+defect rather than causing it.
+
+The five distinct shapes, each verified against the real commit:
+
+| Commit | Shape | Verdict |
+|---|---|---|
+| `dbd0d51c` | human `Co-authored-by:` appended below the block | **gate defect** — correct commit rejected |
+| `f64f2b71` | bot `Co-authored-by:` appended below the block | **real violation**, previously hidden by the parse |
+| `87308dea` | GitHub's `---------` separator between block and co-author | malformed message |
+| `b8293c88` | multi-commit squash doubled the whole block | malformed message |
+| `b580452d` | "Merge pull request #N", no trailers at all | real violation |
+
+Only the first is the gate's fault. That is the one this row fixes.
+
+## Port map
+
+| Item | Local anchor | Motion |
+|---|---|---|
+| `join_trailing_trailer_paragraphs`, `_is_trailer_paragraph` | `scripts/check-commit-trailers.py` | new |
+| `parsed_trailers` | same file | fuse before parsing |
+| uniqueness, marker placement, forbidden-AI-trailer rules | same file | **unchanged** |
+
+## Design
+
+**Fuse consecutive trailing trailer-shaped paragraphs before parsing.** A
+paragraph qualifies only if every line is trailer-shaped (`Key: value`, or an
+indented continuation). A prose paragraph still terminates the block, so trailers
+buried mid-message remain invalid — the looseness this gate exists to prevent is
+untouched.
+
+Nothing is relaxed. The block must still exist, the marker must still sit above
+it, each declaration must still appear exactly once, and an AI co-author is still
+forbidden. The change is that the block is *found* where a merge tool actually
+left it.
+
+**What was rejected, and why it matters.** The first attempt also collapsed
+identical duplicate trailers, to fix the `b8293c88` squash case. That is a
+relaxation of the uniqueness rule, and an existing test
+(`test_protocol_and_ai_declarations_are_unique_and_exact`) pins it. Rewriting an
+assertion to suit the change is exactly what `AGENTS.md` forbids, and the
+distinction is real: a doubled block is a genuinely malformed message, fixable at
+source by writing the squash body or landing a single-commit PR, whereas the
+`Co-authored-by` case is a correct commit defeated by the parser. It was reverted
+in full; `b8293c88` stays red on purpose.
+
+**A consequence to state plainly:** making the block visible also makes
+previously-hidden `Co-authored-by` lines visible to the forbidden-AI-trailer
+rule. `f64f2b71` names a bot co-author and now fails where it silently passed.
+That is the gate working, not a regression, but it means merges that attribute a
+bot will red until the merge method stops adding them.
+
+## Tests to port
+
+None upstream, for the reason in Upstream chain. Written from scratch in the
+checker's **paired** suite, `tests/scripts/test_check_commit_trailers.py`:
+
+1. RED-BEFORE: a human `Co-authored-by:` appended below a valid block passes.
+2. A doubled trailer block still **fails** (`b8293c88` stays red by design).
+3. Contradictory `AI-Assisted` declarations still fail.
+4. A "Merge pull request" message with no trailers still fails.
+5. Prose after the trailer block still fails — proving the fusion is bounded.
+
+Cases 2–5 are the guards that keep the fusion from becoming a hole; all four were
+already green before the change and must stay green.
+
+## Gates
+
+- `scripts/agent-preflight.sh` and `--staged`.
+- `tests/scripts/test_check_commit_trailers.py`, read by test-case COUNT.
+- The five real `main` commits above, each re-checked by
+  `check-commit-trailers.py --range '<sha>~1..<sha>'`, with the verdict table
+  reproducing exactly.
+- `python3 scripts/agent-integration.py --base origin/main`.
+- No CUDA, GPU or SACRED gate is implicated: no product source is touched.
+
+## Evidence
+
+The `git interpret-trailers --parse` output above; the 13-of-30 count on `main`;
+and the per-commit verdict table before and after, which is the binding result.
+
+## Dependencies
+
+None.
+
+## Work breakdown
+
+| ID | Work | Done when |
+|---|---|---|
+| W1 | RED-BEFORE case for the appended human co-author | fails before the fix |
+| W2 | `join_trailing_trailer_paragraphs` + `parsed_trailers` | W1 green, guards still green |
+| W3 | Re-verify the five real commits | table reproduces |
+
+## Risks / decisions
+
+- **Fusion could hide a malformed block.** Bounded by requiring every line of
+  every fused paragraph to be trailer-shaped, and pinned by the prose-after guard.
+- **This does not make `main` green on its own.** Four of the five shapes are
+  merge-method artifacts that remain red by design. The durable fix for those is
+  how commits land, which is a process change and not this row's scope.
+
+## Stop conditions
+
+Return `NEEDS_DECISION` rather than widening scope if closing the remaining four
+shapes would require relaxing uniqueness, the marker placement rule, or the
+forbidden-AI-trailer rule. Those are the guarantees the gate exists to hold.
+
+## Now
+
+W3 done; the row is landing. Next: decide the merge-method change that closes the
+four remaining shapes, which is process, not checker.
+
+## Outcome
+
+Pending.

scripts/check-agent-record.py

@@ -351,8 +351,14 @@
 # marched every PR into it. User-directed, issue #374; `ACTIVE` on its committed
 # spec. No checker semantic beyond the row's own scope and no product source is
 # changed by the bump.
+# 150 since 2026-08-11: +`ENG-TRAILER-MERGE-ARTIFACTS` (the trailer gate rejects
+# correct commits because GitHub appends `Co-authored-by:` as a separate
+# paragraph, which hides the block from `git interpret-trailers --parse`; 13 of
+# the last 30 commits on main failed the check, unnoticed because those runs were
+# cancelled). User-directed, issue #406; `ACTIVE` on its committed spec. No rule
+# in that checker is relaxed and no product source changes.
 # Bumped for a real new row, never to make a failing state transition pass.
-ENGINE_ROWS = 149
+ENGINE_ROWS = 150
 
 ENGINE_SUMMARY_SECTIONS = (
     ("Engine and scheduling", "Engine core and scheduling"),

scripts/check-commit-trailers.py

@@ -57,12 +57,54 @@ def _git(repo: Path, *args: str, input_text: str | None = None) -> str:
     return result.stdout.strip()
 
 
+TRAILER_LINE = re.compile(r"^[A-Za-z][A-Za-z0-9-]*:[ \t].+$")
+CONTINUATION_LINE = re.compile(r"^[ \t]+\S")
+
+
+def _is_trailer_paragraph(paragraph: str) -> bool:
+    """Whether every line of a paragraph is trailer-shaped."""
+    lines = [line for line in paragraph.splitlines() if line.strip()]
+    if not lines:
+        return False
+    if not TRAILER_LINE.match(lines[0]):
+        return False
+    return all(
+        TRAILER_LINE.match(line) or CONTINUATION_LINE.match(line) for line in lines[1:]
+    )
+
+
+def join_trailing_trailer_paragraphs(message: str) -> str:
+    """Fuse consecutive trailer-shaped paragraphs at the END into one block.
+
+    `git interpret-trailers --parse` reads ONLY the final paragraph, so anything
+    appended after the trailer block hides it completely. GitHub does exactly
+    that on a squash merge: it adds `Co-authored-by:` as a new paragraph, and the
+    protocol trailers above it stop being visible. Measured on main: dbd0d51c,
+    87308dea and f64f2b71 all parse to nothing but that one line, and the gate
+    reported them as missing trailers they plainly carry (#406).
+
+    Only TRAILER-SHAPED paragraphs are fused. A prose paragraph still terminates
+    the block, so trailers buried mid-message remain invalid -- the looseness
+    this gate exists to prevent is untouched.
+    """
+    paragraphs = _paragraphs(message)
+    if not paragraphs:
+        return message
+    fused: list[str] = []
+    while paragraphs and _is_trailer_paragraph(paragraphs[-1]):
+        fused.insert(0, paragraphs.pop())
+    if len(fused) < 2:
+        return message
+    return "\n\n".join(paragraphs + ["\n".join(fused)])
+
+
 def parsed_trailers(message: str) -> str:
-    """Return exactly what ``git interpret-trailers --parse`` returns."""
+    """Return what ``git interpret-trailers --parse`` returns, after fusing any
+    trailer-shaped paragraphs appended below the block (see the helper above)."""
 
     result = subprocess.run(
         ["git", "interpret-trailers", "--parse"],
-        input=message,
+        input=join_trailing_trailer_paragraphs(message),
         text=True,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,

scripts/check-gate-commands.py

@@ -275,8 +275,15 @@ def audit() -> list[dict]:
 # baseline member. All three departures are the same lifecycle-policy closure,
 # not downgraded verdicts or hidden work. Re-adding DONE to GATED_STATES is the
 # load-bearing mutation pinned in the paired suite.
+# 2026-08-11: +ENG-TRAILER-MERGE-ARTIFACTS. The row reaches ACTIVE on its
+# committed spec (issue #406), whose Gates section names the preflight,
+# tests/scripts and agent-integration invocations plus the per-commit
+# re-verification of the five real main commits, and records that no
+# CUDA/GPU/SACRED gate is implicated because no product source is touched.
+# Growth, so the set is re-pinned in the same change.
 RUNNABLE_BASELINE = frozenset({
     "ATTN-CHUNKED-LOCAL",
+    "ENG-TRAILER-MERGE-ARTIFACTS",
     "ENG-RECORD-CONFLICT-SURFACES",
     "SAMPLE-PROMPT-LOGPROBS",
     "ATTN-ROPE-FAMILY",

tests/scripts/test_check_commit_trailers.py

@@ -275,5 +275,82 @@ def test_ambiguous_revision_name_fails_closed(self) -> None:
             )
 
 
+class MergeArtifacts(unittest.TestCase):
+    """The trailer gate must judge the CLAIM, not the paragraph layout (#406).
+
+    Every shape below was taken from a real commit on main. The gate was failing
+    on how commits LAND rather than on how they are written, and 13 of the last
+    30 commits on main failed it -- unnoticed only because those runs were
+    cancelled (#274).
+    """
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.checker = load_checker()
+
+    def test_github_co_authored_by_does_not_hide_the_block(self) -> None:
+        """RED-BEFORE: this is dbd0d51c, 87308dea and f64f2b71 on main.
+
+        Squash-merging through GitHub appends `Co-authored-by:` as a SEPARATE
+        trailing paragraph. `git interpret-trailers --parse` reads only the last
+        paragraph, so the protocol trailers become invisible and the gate counts
+        zero. The commit is correct; the parse is what breaks.
+
+        AGENTS.md forbids AI tools from adding Co-Authored-By. It does not
+        forbid GitHub from recording a real human co-author, so this must pass.
+        """
+        message = STRICT_MESSAGE + "\nCo-authored-by: Ettore Di Giacinto <mudler@localai.io>\n"
+        self.assertEqual(
+            self.checker.validate_commit_message(message, strict=True), []
+        )
+
+    def test_a_squash_that_doubles_the_trailer_block_still_fails(self) -> None:
+        """b8293c88, the commit that turned main red, must STAY red.
+
+        Squashing a multi-commit PR concatenates each commit's trailer block, so
+        every trailer appears twice. That was tempting to collapse -- two
+        identical declarations do say the same thing -- but it is NOT what this
+        change fixes, and relaxing it would delete a rule that catches genuinely
+        malformed messages.
+
+        The distinction that matters: the Co-authored-by case above is a correct
+        commit REJECTED BY THE PARSE, while this one is a message that really is
+        malformed and is fixable at the source by writing the squash body (or by
+        landing a single-commit PR). AGENTS.md's "fix the cause, not the gate"
+        puts this on the process side of the line.
+        """
+        _, _, trailers = STRICT_MESSAGE.rpartition("FOLLOWING_AGENTS_PROTOCOL\n")
+        doubled = STRICT_MESSAGE + "\nFOLLOWING_AGENTS_PROTOCOL\n" + trailers
+        errors = self.checker.validate_commit_message(doubled, strict=True)
+        self.assertTrue(errors, "a doubled trailer block must still be rejected")
+
+    def test_contradictory_declarations_fail(self) -> None:
+        """A commit cannot both declare and deny AI assistance."""
+        conflicting = STRICT_MESSAGE + "AI-Assisted: false\n"
+        errors = self.checker.validate_commit_message(conflicting, strict=True)
+        self.assertTrue(errors, "contradictory declarations must fail")
+
+    def test_a_github_merge_commit_with_no_trailers_still_fails(self) -> None:
+        """This is b580452d. It must STAY red -- a real violation, not a layout
+        artifact. The relaxation is about placement and duplication only."""
+        message = (
+            "Merge pull request #386 from mudler/row/ENG-NOW-DERIVED-DONE\n"
+            "\n"
+            "close the row\n"
+        )
+        errors = self.checker.validate_commit_message(message, strict=True)
+        self.assertTrue(errors, "a message with no trailers at all must fail")
+
+    def test_prose_after_the_trailers_still_fails(self) -> None:
+        """A prose paragraph must still terminate the block.
+
+        Without this the relaxation would accept trailers buried anywhere near
+        the end, which is exactly the looseness the gate exists to prevent.
+        """
+        message = STRICT_MESSAGE + "\nAnd then some closing prose about the change.\n"
+        errors = self.checker.validate_commit_message(message, strict=True)
+        self.assertTrue(errors, "prose after the trailer block must still fail")
+
+
 if __name__ == "__main__":
     unittest.main()