Put the repo's own conventions where the section model sends them - #14
Merged
Conversation
`AGENTS.md > Project Conventions` was a section the hub does not declare, which the audit flags as drift to reconcile. Reconciling it found that most of it was already reconciled elsewhere. Three of the four rules were near-verbatim duplicates of entries already in `TODO.md` Traps: never populating media over HTTP, `content/` being an imported archive, and a gate proving itself by failing. Duplicated rules are worse than absent ones, because the two copies drift and nothing says which is current, so those three are deleted here rather than moved. The fourth was unique and is the load-bearing one. The URL contract being ground truth and its lists being append-only appeared nowhere else, and in particular not in `OPERATIONS.md`, which operates that contract through the whole local-verification and deploy path without ever stating the invariant behind it. It moves there, ahead of the verification section that depends on it, and picks up the length-floor clause that `TODO.md` carried separately, since a floor is what makes append-only checkable rather than aspirational. `AGENTS.md` is left carrying only the three sections the hub declares, and its intro drops from four things to three, which is what the hub's own intro says. Note this does not resolve ProjectTemplate#552. That contradiction is about the byte-locked `Fleet Bootstrap` section naming the template repo, which is untouched here and still flagged. ## Verification - Every verbatim unit still byte-matches the canonical, so removing the local section disturbed none of the carried ones. - markdownlint, editorconfig-checker, and the prose gate are clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR reconciles repo-specific guidance with the hub’s section model by removing the undeclared ## Project Conventions section from AGENTS.md and relocating the remaining unique invariant (the URL contract/append-only lists) into the operational documentation where it is exercised.
Changes:
- Add a new
## The URL Contractsection toOPERATIONS.md, documenting the “ground truth” and append-only invariants forchecks/*urls.txtand the need for a length floor. - Remove the non-hub-declared
## Project Conventionssection fromAGENTS.md. - Update the
AGENTS.mdintro to reflect that it now contains three things (not four).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| OPERATIONS.md | Adds a dedicated “URL Contract” section to document the invariant that the operational verification procedures depend on. |
| AGENTS.md | Removes the repo-specific conventions section to match the hub-declared section set and updates the intro accordingly. |
The preamble said this project's own conventions live "here", which was true while `Project Conventions` was in this file and stopped being true in the same change that moved it out. An agent reading the sentence would look for repo invariants in `AGENTS.md` and find none. The sentence's actual point is provider independence, that a rule a reviewer must honor cannot live in the Copilot-specific file, and that point survives intact. It now names the topical docs that own the content instead of claiming this file does. Co-Authored-By: Claude Opus 5 (1M context) <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
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.
AGENTS.md > Project Conventionsis a section the hub does not declare, whichspec/audit.pyflags as drift to reconcile andspec/section-model.mdresolves by moving repo-specific content to a topical doc. Reconciling it found that most of it was already reconciled somewhere else.Three of the four were already duplicated
Project ConventionsTODO.mdTrapscontent/is an imported archiveDuplicated rules are worse than absent ones, because the two copies drift apart and nothing says which is current. Those three are deleted rather than moved, since moving them would have made a third copy.
The fourth is the load-bearing one, and it moves to OPERATIONS.md
The URL contract being ground truth, and its lists being append-only, appeared nowhere else. In particular it was absent from
OPERATIONS.md, which operates that contract through the entire local-verification and deploy path without ever stating the invariant behind it:grepfor "append-only" or "ground truth" there returned nothing before this change.It lands as a new
## The URL Contractsection immediately ahead ofLocal Verification Before a Pull Request, which is the procedure that depends on it, and picks up the length-floor clauseTODO.mdcarried separately, since a floor is what makes append-only checkable rather than aspirational.AGENTS.mdnow carries only the three sections the hub declares, and its intro drops from four things to three, matching the hub's own.What this does not fix
ProjectTemplate#552. That contradiction is about the byte-locked
Fleet Bootstrapsection naming the template repo, which is untouched here and still flagged. This change clears the undeclared section finding only.Verification
## headingblock against hubmain, so removing the local section disturbed none of the carried ones.🤖 Generated with Claude Code