Skip to content

chore: drop the asset-hotlinking ADR and trim AGENTS.md - #86

Merged
lesnik512 merged 1 commit into
mainfrom
chore/readme-absolute-links
Sep 7, 2026
Merged

chore: drop the asset-hotlinking ADR and trim AGENTS.md#86
lesnik512 merged 1 commit into
mainfrom
chore/readme-absolute-links

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Why

docs/adr/0003-docs-vendor-assets-readmes-hotlink.md is not carrying enough to justify a permanent
record. Its decision is readable from the source it describes: docs repos hold vendored
docs/assets/lockup-*.svg, READMEs hold raw.githubusercontent.com URLs, and the split is visible
in either file without prose. Its supporting reasoning, that mkdocs build --strict does not
validate external URLs, is a property of MkDocs that anyone can re-derive.

The AGENTS.md paragraph goes for the same reason. It described what is not enforced, without
instructing anything:

Nothing enforces that shape, and nothing checks that an ADR path cited from code or from this
file still resolves; both are read at review time. Both ADRs and INVARIANT: docstrings ratchet:
nothing prunes a record once its call is settled. Keeping them lean is a standing habit.

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.md renumbers to 0003 rather than leaving a gap, keeping
the sequence contiguous as AGENTS.md specifies.

Three references updated:

Reference Form Caught by
AGENTS.md, brand surfaces relative Markdown link the link gate
brand/README.md backticked bare path nothing
brand/build/symbols.py, flask_horn docstring backticked bare path nothing

Only 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.md sentence pointing at the deleted ADR is removed rather than reworded. What remains
in that section, that assets are generated in brand/projects/<repo>/, is the part not derivable
from 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.md paragraph stated. That
rule is removed in this PR, so the exception and the rule it breaks land together.

The deleted AGENTS.md sentence 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

  • No change to the hotlinking practice itself; only the record of why it was chosen
  • No renumbering of ADRs 0001 or 0002
  • No change to any other repo's ADRs, which are numbered independently

Verification

  • uv run pytest: 125 passed, 29 skipped
  • Link gate: 228 total, 0 errors
  • git grep for 0003-docs-vendor and 0004-flask-horn: no matches remain

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.
@lesnik512
lesnik512 merged commit b86bc21 into main Sep 7, 2026
3 checks passed
@lesnik512
lesnik512 deleted the chore/readme-absolute-links branch September 7, 2026 05:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant