Write down the process, and put a check behind the required pull request - #4
Merged
Merged
Conversation
The repository had the rules of the profile and none of the rules of working on it. main is protected by a ruleset, and nothing said so in the repository, which is how an edit ends up committed on main before anybody notices. CONTRIBUTING.md carries the process: the life cycle of a change, the two issue forms, the four outcomes of triage with refusal as a first-class one, the five branch prefixes, the commit scopes, and the table of what cuts which version bump. CLAUDE.md carries what an agent has to know before the first edit, and references that process instead of repeating it. The two issue forms are shaped by what this repository is. A notation report asks for the bytes that were written, because a profile exists so that two implementations can be compared and a report with no bytes in it cannot be. A notation proposal asks for the conformance case up front, and says out loud that declaring a form to mean nothing is a valid outcome of the form. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015AqyzSutJgPQiub6mc5AZg
The repository claims that a specification and an implementation cannot drift apart, and had nothing checking that the specification does not drift apart from itself. A required pull request with no check behind it only guarantees that somebody clicked. tools/check-profile.mjs validates profile.json against its schema, requires a conformance case for every notation an indexer decides, refuses a case naming a notation that does not exist, resolves every section reference to a real heading of SPEC.md, and holds the three files to the one version in profile.json. No dependencies, no build, under a second. The schema validator implements only the keywords the schema uses and fails on any keyword it does not implement. A validator that ignores what it does not understand reports a success it never established. .gitattributes fixes the line ending at LF, because the suite compares strings and a check on Windows has to read the bytes a check on Linux reads. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015AqyzSutJgPQiub6mc5AZg
… behind The branch was written against 0.1.0 while 0.2.0 was being released on main. Rebasing it surfaced what the check was built to surface, on its first run and without anybody looking for it: profile.json said 0.2.0 and the header of SPEC.md still said 0.1.0. The version header is corrected, and the check now holds package.json to the same version, since the profile is distributed as a package and that is a fourth place to forget. The section references of the process documents and the issue forms are corrected to the sections 0.2.0 actually has. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015AqyzSutJgPQiub6mc5AZg
heitorrapcinski
force-pushed
the
chore/repository-governance
branch
from
September 6, 2026 20:53
95e0c51 to
0740cf6
Compare
heitorrapcinski
added
the
documentation
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.
Summary of changes
The repository carried the rules of the profile and none of the rules of working on it.
mainwas already protected by a ruleset and nothing said so, which is how an edit ends up committed onmainbefore anybody notices.CONTRIBUTING.md— the process: the five stages from an issue tomain, the two issue forms, the four outcomes of triage with refusal as a first-class one, the five branch prefixes, the commit scopes, the two mandatory sections of a pull request, and the table of what cuts which version bump.CLAUDE.md— what an agent has to know before its first edit. It references the process instead of repeating it, and states the one rule this repository turns on: the unit of work is a notation, and a notation lives in three files at once.tools/check-profile.mjsandnpm run check— the check behind the required pull request. It validatesprofile.jsonagainst its schema, requires a case for every notation an indexer decides, refuses a case naming a notation that does not exist, resolves every section reference to a real heading ofSPEC.md, catches duplicate identifiers, and holdsSPEC.md,tests/conformance.jsonandpackage.jsonto the version inprofile.json. No dependencies, no build, 8 seconds in CI..gitattributesfixes the line ending at LF so the check reads the same bytes on every operating system.The schema validator implements only the keywords the schema uses and fails on any keyword it does not implement. A validator that ignores what it does not understand reports a success it never established.
What it caught on its first run
Rebasing this branch onto 0.2.0 ran the check against real content for the first time, and it immediately found a divergence nobody was looking for:
profile.jsonsaid0.2.0and the header ofSPEC.mdstill said0.1.0, released and tagged that way. Fixed here, and it is why the version rule now coverspackage.jsonas well — a fourth place to forget.Closes #3
What an implementation has to do
Nothing. No notation changed and
profile.jsonis untouched. The only edit toSPEC.mdis the version in its header, which now says the version it was released as.The three files
SPEC.md, because the prose of a notation changed — no notation changed; the version header was correctedprofile.json, because an entry was added, changed or removedtests/conformance.json, because a case was added or its expectation changedCHANGELOG.md, in the same commit as the change it documentsnpm run checkpasses locally: yes — 31 notations (19 an indexer decides, 12 rendering), 35 cases, version 0.2.0.Version
None. It alters no notation, so it waits in
[Unreleased]for the next cycle, perCONTRIBUTING.md§ 6. TheFixedentry for the stale header goes out with whatever cuts next.AI productivity analysis
2026-09-06to2026-09-06)Estimated human effort (without AI assistance)
The volume is a poor guide here and the weight is elsewhere: reading the process of the sibling repository closely enough to adapt it rather than copy it, deciding which of its parts do not apply to a repository that ships no code, writing a schema validator that is honest about its own coverage instead of one that passes everything it does not parse, and reconciling the branch with a version that was released underneath it.
🤖 Generated with Claude Code
https://claude.ai/code/session_015AqyzSutJgPQiub6mc5AZg