chore: drop the asset-hotlinking ADR and trim AGENTS.md - #86
Merged
Conversation
Removes docs/adr/0003-docs-vendor-assets-readmes-hotlink.md, renumbers the flask-horn ADR into the gap, and fixes the three references. Also drops the AGENTS.md paragraph describing what is enforced only at review time.
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.
Why
docs/adr/0003-docs-vendor-assets-readmes-hotlink.mdis not carrying enough to justify a permanentrecord. Its decision is readable from the source it describes: docs repos hold vendored
docs/assets/lockup-*.svg, READMEs holdraw.githubusercontent.comURLs, and the split is visiblein either file without prose. Its supporting reasoning, that
mkdocs build --strictdoes notvalidate external URLs, is a property of MkDocs that anyone can re-derive.
The
AGENTS.mdparagraph goes for the same reason. It described what is not enforced, withoutinstructing anything:
This file is loaded into every agent turn, so a paragraph that changes no behaviour costs on every
one of them.
Design
0004-flask-horn-historical-artwork-grant.mdrenumbers to0003rather than leaving a gap, keepingthe sequence contiguous as
AGENTS.mdspecifies.Three references updated:
AGENTS.md, brand surfacesbrand/README.mdbrand/build/symbols.py,flask_horndocstringOnly the first would have failed CI if missed. The other two are the class of unchecked citation
described in #84, met in the course of a change that renames an ADR, which is
exactly the scenario that issue predicts.
The
AGENTS.mdsentence pointing at the deleted ADR is removed rather than reworded. What remainsin that section, that assets are generated in
brand/projects/<repo>/, is the part not derivablefrom reading a single file.
Accepted cost
Deleting an ADR discards its rejected alternative. Hotlinking assets into docs sites as well as
READMEs is no longer recorded as considered and rejected, so it can be proposed again with no
written answer waiting. That is the thing ADRs exist to prevent, and this PR accepts it deliberately
rather than by oversight.
This is also the first exception to the ratchet rule that the same
AGENTS.mdparagraph stated. Thatrule is removed in this PR, so the exception and the rule it breaks land together.
The deleted
AGENTS.mdsentence is quoted as evidence in #84, whose option (4)rested on it existing. That does not change the issue's outcome, which had already settled on a test,
but its brief will need a touch-up.
Non-goals
0001or0002Verification
uv run pytest: 125 passed, 29 skippedgit grepfor0003-docs-vendorand0004-flask-horn: no matches remain