docs: move the wiki page list to its own file, and make it self-checking - #366
Merged
Conversation
The five bug-pattern PRs were stacked because they shared three files.
Everything else in them was disjoint — no two touched the same page — so
95% of the work was independent and all of it got serialised anyway.
Then the chain merged into itself and 13 pages never reached main.
Two of the three shared files did not need to be conflicts.
SYNC_LOG.md is append-only by its own stated rule ("Append only. Never
edit historical rows."), which is exactly the case merge=union already
covers for findings. Two syncs appending a row each now merge cleanly.
The coverage percentages in CLAUDE.md were a number that goes stale on
its own, and had: the sentence claimed 83% for mdl/executor while that
area had grown from 248 findings to 498. Replaced with a pointer to
`make digest-status`, which computes it.
That leaves the seed table in maintain-wiki.md as the only shared file —
one appended row per page, a trivial conflict that `git merge main`
resolves in seconds. File-wide union is deliberately NOT applied there:
it is prose with a table in it, and union on prose silently keeps both
sides of an edited line. That trade-off is already recorded in
.gitattributes from the fix-issue.md split.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The seed table was the last file forcing wiki PRs to be serialised: one appended row per page, in the middle of a prose file where merge=union would be a hazard rather than a help. It is now a table and nothing else in .claude/skills/maintain-wiki/pages.md, with union in .gitattributes. The prose stays behind and explains why the split exists. Also carries 62b2525, which missed #364's merge by minutes: the union rule for SYNC_LOG.md and the removal of the coverage percentages from CLAUDE.md. Two things found while doing it, both the same shape as the findings the wiki digests. The page list had DRIFTED. architecture/mcp-backend.md and models/ped-mutation-constraints.md were added in June 2026 and were still missing from it in September — three months, unnoticed, because a table of contents has no failure mode of its own. Both rows added, and scripts/check-wiki-pages.sh now asserts BOTH directions: a page absent from the list is invisible to anyone choosing what to sync, and a row naming no file is a page someone believes exists. Controlled by truncating the list and watching it fail. check-findings was NOT in CI. The findings README said it was, and a PR body said it was, and neither was true. Both it and the new page check now run in push-test.yml. The README's correction says what happened rather than quietly editing the claim, because "we said it was wired and it was not" is exactly the class of finding this corpus exists to hold. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The seed table was the last file forcing wiki PRs to be serialised. It's now a table and nothing else in
.claude/skills/maintain-wiki/pages.md, withmerge=unionin.gitattributes; the prose stays inmaintain-wiki.mdand explains why the split exists.Union is safe on a pure table and not safe on prose — it keeps both sides of an edited line silently. That's the same trade-off already recorded from the
fix-issue.mdsplit, which is why the file is a table with no preamble.Also carries
62b25250, which missed #364's merge by minutes — theSYNC_LOG.mdunion rule and the removal of the coverage percentages fromCLAUDE.md. Worth noting that #364 merged at680025d7and reported success; the second commit simply wasn't there yet.Two things found while doing it
The page list had drifted for three months.
architecture/mcp-backend.mdandmodels/ped-mutation-constraints.mdwere added in June 2026 and were still missing from the list in September. Nothing noticed, because a table of contents has no failure mode of its own — it is only wrong in the sense that it is incomplete, and nothing reads it looking for that.Both rows added, and
scripts/check-wiki-pages.shnow asserts both directions: a page absent from the list is invisible to anyone choosing what to sync, and a row naming no file is a page someone believes exists. Controlled by truncating the list and watching it fail:check-findingswas not in CI. The findings README said it was. A PR body said it was. Neither was true —push-test.ymlhad no step for it. Both it and the new page check now run there.The README's correction says what happened rather than quietly editing the claim:
Where parallel wiki work stands now
docs-wiki/SYNC_LOG.mdmerge=unionmerge=unionCLAUDE.mdcoveragemake digest-statusNothing left to serialise. Independent branches off
main, merged in any order.🤖 Generated with Claude Code