docs(agents): markdown sits outside every gate, so a bad merge ships green #42

Merged

jlxq0 merged 1 commit from docs-markdown-conflict into main

2026-09-02 02:48:43 +00:00

jlxq0 commented

2026-09-02 02:46:28 +00:00

Owner

Documentation only, from a mistake I made an hour ago.

Rebasing #19 produced AGENTS.md with three copies of each of three entries, and fmt --check, clippy -D warnings, 139 tests, audit and deny all passed, because none of them reads markdown. It surfaced only because a stray ||||||| marker reached the commit, which is luck rather than a check.

Two causes, recorded because either alone is enough. A resolver handling <<<<<<< / ======= / >>>>>>> silently mangles a diff3 conflict, treating its extra ||||||| base section as content. And when both sides of an additive conflict end mid-item, concatenating them drops the delimiter the shared trailing context was supplying: in Rust that is a missing } and the compiler says so, in markdown nothing does.

The control costs one command and works because these conflicts are additive, so the resolved file must be main's file plus the branch's block, exactly:

diff <(head -<N> AGENTS.md) <(git show origin/main:AGENTS.md)   # must be empty
grep -c "<the entry's first line>" AGENTS.md                    # must be 1

Both were run against this PR's own file before committing it.

And the part I would tell my past self: reset rather than iterate on a damaged resolution. I made it worse twice before rebuilding it deterministically, and each pass added a copy.

Documentation only, from a mistake I made an hour ago. Rebasing `#19` produced `AGENTS.md` with **three copies of each of three entries**, and `fmt --check`, `clippy -D warnings`, 139 tests, `audit` and `deny` all passed, because none of them reads markdown. **It surfaced only because a stray `|||||||` marker reached the commit**, which is luck rather than a check. **Two causes, recorded because either alone is enough.** A resolver handling `<<<<<<<` / `=======` / `>>>>>>>` silently mangles a **diff3** conflict, treating its extra `||||||| ` base section as content. And when both sides of an additive conflict end mid-item, concatenating them drops the delimiter the shared trailing context was supplying: in Rust that is a missing `}` and the compiler says so, in markdown nothing does. **The control costs one command and works because these conflicts are additive**, so the resolved file must be `main`'s file plus the branch's block, exactly: diff <(head -<N> AGENTS.md) <(git show origin/main:AGENTS.md) # must be empty grep -c "<the entry's first line>" AGENTS.md # must be 1 Both were run against this PR's own file before committing it. **And the part I would tell my past self:** reset rather than iterate on a damaged resolution. I made it worse twice before rebuilding it deterministically, and each pass added a copy.

jlxq0 added 1 commit

2026-09-02 02:46:28 +00:00

docs(agents): markdown sits outside every gate, so a bad merge ships green

CI / cargo (pull_request) Successful in 51s

Details

CI / docker (pull_request) Successful in 54s

Details

296f193492

A rebase of #19 produced AGENTS.md with three copies of each of three entries,
and fmt, clippy, 139 tests, audit and deny all passed, because none of them
reads markdown. It surfaced only because a stray ||||||| marker reached the
commit, which is luck rather than a check.

Two causes recorded because either alone is enough. A resolver handling only
<<<<<<< / ======= / >>>>>>> mangles a diff3 conflict by treating its base
section as content. And when both sides of an additive conflict end mid-item,
concatenating them drops the delimiter the shared trailing context supplied,
which a compiler catches in Rust and nothing catches in markdown.

The control is one command, and it works because these conflicts are additive:
the resolved file must be main's file plus the branch's block, byte for byte,
with each entry appearing once. Rebuild rather than resolve in place, and reset
rather than iterate on a damaged resolution, since each pass adds a copy.

jlxq0 merged commit 1a7571521a into main

2026-09-02 02:48:43 +00:00

jlxq0 deleted branch docs-markdown-conflict

2026-09-02 02:48:44 +00:00

jlxq0 referenced this pull request from a commit

2026-09-02 02:48:45 +00:00

Merge pull request 'docs(agents): markdown sits outside every gate, so a bad merge ships green' (#42) from docs-markdown-conflict into main