State the cross-repo rule by intent, not mechanism

[ptr727]

Reported from a downstream session: Copilot insisted on removing a README.md link pointing to a related device-builder repo, citing the no-cross-repo-link rule. That link was legitimate content. The rule I wrote in #344/#359 made that misreading reasonable, so this fixes the rule rather than the reviewer.

Two defects in the rule as written

1. It led with the mechanism and buried the carve-out. The sentence opened with "adds no link (inline URL or reference definition) to another fleet repo" and only qualified it fifteen lines later with "unless that repo is the subject". Read top-down, the ban looks absolute.

2. It claimed README.md is carried verbatim. It is not. spec/files.json gives README.md neither whole: true nor sections, so it is a per-repo file governed only by readme-structure.md. A repo's own README is its own content. The rule never should have reached it, which is exactly where the over-application landed.

Restated by intent

Two things banned in carried files:

• Any reference to the template repo, prose or link. Private, so it 404s, and the coordination flow is machinery a consumer should not see.
• A sibling fleet repo named as an illustrative example ("repo X does it this way", "see repo Y's adoption"). That couples repos and rots as they diverge.

And explicitly permitted:

A contextually relevant link to a related project is not a coordination reference, and is expected. Where another repo is part of this repo's subject matter - the image that consumes this config, the builder that generates this hardware, a library this depends on - link it normally. The test is whether the link serves a reader of this repo's content, not whether the target happens to be in the fleet.

Plus the scope correction: the rule governs carried template content, and a repo's own README.md and topical docs are outside it.

spec/project-types.json's recurring.norepoxref is reworded to match.

The mechanical check needed no change

spec/audit.py greps only for the template name in the two agent-instruction files. It never looked for sibling links, so it was not the source of the over-application and its behavior is unchanged - re-verified against PlexCleaner (flags) and Vantage-Config (clean).

spec/validate.py, markdownlint, editorconfig-checker: clean.

Downstream note: ESPHome-NonRoot is amending its local AGENTS.md for the same reason. Once this lands, its next carry converges on this wording.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Clarifies the “no cross-repo references” governance rule by stating the intent (avoid coordination/template references in carried files) rather than an overly broad mechanism-based ban, and corrects the scope so it does not overreach into per-repo README.md content.

Changes:

• Restates the carried-file cross-repo guidance in AGENTS.md to explicitly ban coordination references (template repo + sibling “example” repos) while permitting contextually relevant links.
• Updates spec/project-types.json (recurring.norepoxref) to match the clarified rule and scope.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
AGENTS.md	Rewords the documentation-style rule to emphasize intent and explicitly allow relevant cross-project links when they serve the repo’s subject matter.
spec/project-types.json	Updates the corresponding audit/assertion text (recurring.norepoxref) to align with the clarified rule and corrected README scope.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

spec/project-types.json:147

• Minor grammar in the assertion text: "in prose or link" reads like it's missing an article. For a normative rule statement, "in prose or a link" is clearer and matches the phrasing used in AGENTS.md.

                { "id": "recurring.norepoxref", "verdict": "intent", "assert": "A carried file (AGENTS.md, CODESTYLE.md, WORKFLOW.md, .github/copilot-instructions.md, repo-config/README.md, repo-config/develop.json, repo-config/main.json, spec/secrets.json, the carried AUDIT.md) carries no coordination reference: no reference to the template repo in prose or link (private, so it 404s for the carrying repo's readers, and the coordination flow is machinery a consumer should not see - state the behavior, not the destination), and no sibling fleet repo named as an illustrative example of a rule or adoption. A contextually relevant link to a related project is NOT a coordination reference and is expected (the image that consumes this config, a library this depends on) - the test is whether the link serves a reader of this repo's content. The rule governs carried template content. A repo's own README.md and topical docs are its own content. spec/audit.py mechanically checks the two agent-instruction files for the template name.", "intentRef": "AGENTS.md#documentation-style-conventions" }