Skip to content

Commit 5226551

Browse files
committed
ai(rules[AGENTS]) Prefer pinned GitHub source links
why: links to trunk rot silently — the file moves, lines shift, and the anchor lands on unrelated code while still resolving. The rubric warned against bare SHAs, which reads as "don't pin links either". what: - Add Durable Source Links: tag first, then a trunk-reachable 7-char commit ref, trunk only for living documents - Rule out PR-head SHAs, which can be rebased or garbage-collected - Restrict line anchors to pinned refs
1 parent dfffbc2 commit 5226551

1 file changed

Lines changed: 16 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -366,6 +366,22 @@ patterns:
366366
decode an index. Internal agent bookkeeping may use ids; shipped text
367367
may not.
368368

369+
### Durable Source Links
370+
371+
Link to a pinned revision, never to trunk. A pinned permalink is not a
372+
brittle reference; an unlinked SHA dropped into prose is. `blob/master/…`
373+
links rot silently — the file moves, lines shift, and the anchor lands
374+
on unrelated code while still resolving.
375+
376+
- Prefer a release tag (`blob/v1.4.0/…`). Most durable, and it tells
377+
the reader which released version the claim held for.
378+
- Otherwise use a 7-char commit ref (`blob/9a29b1a/…`) reachable from
379+
trunk. Use when there is no tag or the claim is about unreleased
380+
code. Never a PR-head SHA — it can be rebased or garbage-collected.
381+
- Reserve `blob/master/…` for living documents meant to always show the
382+
latest state, such as a contributing guide.
383+
- Line anchors (`#L120-L145`) are only safe on a pinned ref.
384+
369385
### Preservation & Context
370386

371387
**When unsure, leave the text in place and ask.** Subjective cleanup

0 commit comments

Comments
 (0)