Skip to content

Commit c42e0f4

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 b6f9f93 commit c42e0f4

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
@@ -541,6 +541,22 @@ patterns:
541541
decode an index. Internal agent bookkeeping may use ids; shipped text
542542
may not.
543543

544+
### Durable Source Links
545+
546+
Link to a pinned revision, never to trunk. A pinned permalink is not a
547+
brittle reference; an unlinked SHA dropped into prose is. `blob/main/…`
548+
links rot silently — the file moves, lines shift, and the anchor lands
549+
on unrelated code while still resolving.
550+
551+
- Prefer a release tag (`blob/v1.4.0/…`). Most durable, and it tells
552+
the reader which released version the claim held for.
553+
- Otherwise use a 7-char commit ref (`blob/9a29b1a/…`) reachable from
554+
trunk. Use when there is no tag or the claim is about unreleased
555+
code. Never a PR-head SHA — it can be rebased or garbage-collected.
556+
- Reserve `blob/main/…` for living documents meant to always show the
557+
latest state, such as a contributing guide.
558+
- Line anchors (`#L120-L145`) are only safe on a pinned ref.
559+
544560
### Preservation & Context
545561

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

0 commit comments

Comments
 (0)