Define per-section fidelity for AGENTS.md; make fleet-law verbatim - #420
Merged
Conversation
A fleet-wide rule carried as intent drifts - it paraphrases, weakens, or vanishes downstream, which has happened repeatedly (comment style, Verification Discipline, Write Safety). AGENTS.md is rule text and rule text is universal, so the default is verbatim; intent is the exception for a section that describes one repo. Classify all 18 sections and declare each fidelity in files.json: - verbatim (16, one operational-scoped): Foundational Principles, Repository Boundaries and Write Safety, Git and Commit Rules, Branching Model, Release Model, Operational Repositories (appliesTo operational), Repository Onboarding and Conformance, PR Title and Commit Conventions, Documentation Style Conventions, Verification Discipline, PR Review Etiquette, Communicating with the User, Workflow YAML Conventions, Supported Development Platforms, Editor and Tasks, Repository Details. - intent (2): Devcontainer and Repository Layout describe this repo's own toolchain and tree. Generalize the Branching Model back-merge sentence (drop this repo's own history SHAs) so it can carry verbatim. Add spec/section-model.md as the ground-truth classification an agent or human consults - it also states that adding, removing, or re-typing a section carries fleet-wide review weight. This lights up AGENTS verbatim drift across the fleet on the next audit, which is the convergence pressure, applied idempotently and burned down over time. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Defines a per-section fidelity model for AGENTS.md so fleet-wide rule text can be enforced verbatim (byte-checked) while explicitly repo-specific sections remain intent-checked, reducing silent drift across downstream repos.
Changes:
- Add
spec/section-model.mddocumenting whichAGENTS.mdsections areverbatimvsintent, plus how structure/fidelity changes are governed. - Update
spec/files.jsonto declare fidelity for allAGENTS.mdsections (mostlyverbatim, withDevcontainerandRepository Layoutasintent). - Generalize
AGENTS.mdBranching Model guidance by removing repo-specific historical back-merge SHAs so the section can carry verbatim.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| spec/section-model.md | New ground-truth doc for AGENTS.md section fidelity and governance. |
| spec/files.json | Declares per-section fidelity for AGENTS.md in the baseline. |
| AGENTS.md | Removes repo-specific SHA examples from Branching Model back-merge guidance. |
- section-model.md: convert inline links to reference-style per the DSC rule. - AGENTS.md Branching: drop 'still' for pure present tense. - fidelity-model.md: the old 3-section verbatim rationale is stale, point it at section-model.md for the current per-section classification. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This was referenced Jul 24, 2026
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.
Establishes that a fleet-wide rule carries verbatim and only a section describing one repo carries as intent - so a rule can no longer silently paraphrase, weaken, or vanish downstream (the recurring drift: comment style, Verification Discipline, Write Safety).
AGENTS.md is rule text, and rule text is universal - the repo-specific values live in other files (
.editorconfig,.devcontainer/, the real tree), not this prose. So the default is verbatim; intent is the exception.files.json. 16 verbatim (oneappliesTo: operational), 2 intent (Devcontainer, Repository Layout - they describe this repo's own toolchain and tree).spec/section-model.md- the ground-truth classification an agent or human consults, not re-derived each session. It also codifies that adding, removing, or re-typing a section carries fleet-wide review weight.Blast radius (intended): the next audit lights up AGENTS verbatim drift across the fleet - ~90% of AGENTS.md is now byte-checked. That is the convergence pressure, applied idempotently via the catalog and burned down over time (progress, not perfection). Verified:
validate.pygreen (every verbatim section resolves in the hub AGENTS.md), selftest green, and a sample audit shows the expected wave (PhotoCleaner: 3 -> 14 AGENTS section findings).