[repo]: split docs/ai into one file per entry - #1253
Merged
Merged
Conversation
The three shared files per package — ChangeLog.md, Decisions.md, Flow.md — were append-only with newest entries on top, so any two concurrent PRs wrote the same line and GitHub marked both conflicted. #1251 declared `merge=union` for the two log files. That does resolve the collision locally, but GitHub ignores merge drivers when it computes a PR's mergeability, so the PRs stayed blocked regardless. Measured on #1250, whose merge base is the .gitattributes commit itself and which changes nothing but those two logs and one test: it merges into main clean locally with the union driver, conflicts locally without it, and GitHub reports `mergeable: false` either way. So stop sharing the files. Each entry is now its own file under docs/ai/{changelog,decisions,flows}/, named by date and title. Two PRs add two different files and there is nothing to merge — the same reason changesets keeps one file per change instead of one shared changelog. .gitattributes goes with it, having nothing left to declare. 396 entries moved across the four packages. The prose is untouched; the only edit is each entry's headings moving up one level, from `##` to `#`, since every entry is now a document rather than a section. Verified by demoting every new file back a level and comparing it to the source text it came from, byte for byte. Flows stay one file per flow and are still edited in place, so two PRs revising the same flow still conflict. That one is worth seeing: it means two changes disagree about how the code runs. Open PRs that append to the old files will hit a modify/delete conflict once. Resolving it is moving the entry into a new file.
seunlanlege
added a commit
that referenced
this pull request
Sep 10, 2026
…ayout #1253 split docs/ai into a file per entry so concurrent PRs stop conflicting on one shared file — which this branch had been doing on every rebase. Rewrites this branch's entries into that layout: two changelog files, seven decisions, the log flow, and the routes flow updated for /logs and its handheld gate.
seunlanlege
added a commit
that referenced
this pull request
Sep 10, 2026
…ayout #1253 split docs/ai into a file per entry so concurrent PRs stop conflicting on one shared file — which this branch had been doing on every rebase. Rewrites this branch's entries into that layout: two changelog files, seven decisions, the log flow, and the routes flow updated for /logs and its handheld gate.
seunlanlege
added a commit
that referenced
this pull request
Sep 10, 2026
…ayout #1253 split docs/ai into a file per entry so concurrent PRs stop conflicting on one shared file — which this branch had been doing on every rebase. Rewrites this branch's entries into that layout: two changelog files, seven decisions, the log flow, and the routes flow updated for /logs and its handheld gate.
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
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 problem
Every package under
sdk/packages/*kept three shared files indocs/ai/—ChangeLog.md,Decisions.mdandFlow.md. All three were append-only with newest entries on top, so any two concurrent PRs wrote the same line and GitHub marked both conflicted.#1251 declared
merge=unionfor the two log files. That fixes it locally and does nothing on GitHub, which ignores merge drivers when it computes a PR's mergeability.Measured on #1250, which changes nothing but those two logs and one test file, and whose merge base is the
.gitattributescommit itself:mainmerge=unionChangeLog.mdandDecisions.mdmergeable: false,dirtySame two commits, same base SHA.
The change
Each entry is now its own file:
Two PRs add two different files, so there is nothing to merge. It is the same reason changesets keeps one file per change instead of one shared changelog.
396 entries moved across core, indexer, sdk and simplex. The prose is untouched. The only edit is each entry's headings moving up one level, from
##to#, since an entry is now a document rather than a section..gitattributesis deleted — it had nothing left to declare. The rootCLAUDE.mddocuments the layout and says not to gather entries back into a shared file, with the GitHub reason attached so nobody re-litigates it. Each package gained adocs/ai/README.mdcarrying the conventions that used to sit in the three preambles.Flows stay one file per flow and are still edited in place, so two PRs revising the same flow still conflict. That one is worth seeing: it means two changes disagree about how the code runs.
Verification
The splitter is fence-aware. That mattered — the
## YYYY-MM-DDline inside each preamble's format example would otherwise have become a bogus entry.Every entry was then reconstructed from the files on disk: demote the headings back a level, compare to the source text in the parent commit, byte for byte. All 396 recovered, and the per-directory file counts match exactly, so no two entries slugged to the same name and quietly overwrote each other.
Two branches off this commit, each adding a changelog entry, merge with no conflict.
For open PRs
#1250, #1246, #1234 and #1185 still append to the old files, so each hits a modify/delete conflict once. Resolving it means moving the entry into a new file under
changelog/ordecisions/.