CODESTYLE.md ships link definitions into ./catalog/, which no downstream repo carries

[ptr727]

CODESTYLE.md is carried by every fleet repo at fidelity intent, whole. Two of its reference-link definitions point into catalog/, which is hub-only and appears in no spec/files.json baseline entry, so the links are dead in every downstream copy.

$ git show origin/develop:CODESTYLE.md | grep -n 'catalog'
504:[vscode-tasks]: ./catalog/snippets/configs/vscode-tasks.json
505:[vscode-tasks-python]: ./catalog/snippets/configs/vscode-tasks-python.json

Found while re-vendoring the file into HomeAutomation-Config, where a Copilot review flagged both as broken. The finding is correct and cannot be fixed downstream.

Why a downstream repo cannot resolve it

The definitions are used, by [vscode-tasks] references inside the carried .NET and Python sections. Deleting the definitions alone leaves those references unresolved, so a local fix means editing carried section bodies as well. Since the file is carried whole, the next re-vendor reintroduces all of it and the finding is filed again. That is the churn loop, not a fix.

Scope

Every repo carrying CODESTYLE.md, which is appliesTo: "*". This has presumably been dead in all of them since catalog/ became hub-only, and it surfaces now only because a review happened to read the link block.

Shapes worth weighing

Not proposing a resolution, since it is a carry-model call:

• Inline the task JSON into CODESTYLE.md as a fenced block, so the content travels with the file that references it.
• Drop the two references and their definitions from the carried sections, describing the standard task set in prose instead.
• Declare catalog/snippets/configs/ as carried for the repos whose types use it, which is the heaviest option and pulls hub machinery downstream.
• Point the definitions at the hub URL rather than a relative path, which the carry rules currently forbid, since the hub is private and such a link 404s for a downstream reader.

The second looks closest to how the rest of the carried content handles hub-only material, but that is a preference and the call is yours.

Related: the same class of finding on byte-locked prose is correctly a non-finding per .github/copilot-instructions.md "Reviewing Carried Fleet Content". This one differs because the unit is intent rather than verbatim, so the usual "the reference is intentional" answer does not settle it.

🤖 Generated with Claude Code

[ptr727]

Resolved on develop by #588, squashed as 4e28ddb. Closing by hand rather than by keyword, since Closes #N fires only on a merge into the default branch and the promotion is not imminent.

This issue listed four shapes and did not propose one, since it was a carry-model call. It is settled by the model #580 landed rather than on its own terms, which is why the fourth shape is what shipped.

Why the fourth shape, which the issue recorded as forbidden

The issue ruled out pointing the definitions at the hub URL because "the hub is private and such a link 404s for a downstream reader". That is no longer true. This repository is public, so an absolute hub URL resolves for every reader, and the constraint that ruled the option out is gone.

The carry rule that also forbade it changed in the same pull request. GOVERNANCE.md "Documentation Style Conventions" now carries a second exception to the coordination-reference ban, for a hub-hosted tool or reference snippet the reader executes or copies, on the test that where the content came from stays out while what the reader runs stays in. A catalog snippet a reader is told to copy is squarely that.

What is on develop

Both definitions are absolute hub URLs at main, in CODESTYLE.md under the <!-- External --> group with -link reference names, matching the naming convention for an external URL. CODESTYLE.md is not one of the three files the audit scans for a coordination reference, so nothing downstream is newly flagged.

The issue's own framing surfaced a second defect worth recording, which the review then sharpened. CODESTYLE.md item "VS Code config home" told each repo to re-point [vscode-tasks] at wherever it keeps its own tasks.json, which is exactly what made the reference resolve to a different file in every copy. And the .NET bullets said the task definitions are "carried verbatim" in what the link now names, while calling tasks.json the canonical spec, so the two sentences named two different files as canonical.

Both are fixed by separating them rather than choosing one. A repo carries those three definitions in its own .vscode/tasks.json, which spec/files.json declares for the csharp type with the catalog snippet as its reference, and the hub snippet is the canonical that copy is written against. Each statement is now true of the file it names.

Scope

The links were dead in every repo carrying CODESTYLE.md, which is appliesTo: "*", and they resolve for all of them now. The fix reaches a downstream repo when it takes the file, so it rides the re-vendor sweep that TODO.md carries rather than needing one of its own. CODESTYLE.md is intent fidelity, so a repo adopts the rule in its own copy rather than byte-matching it.

Related: #580 is closed by the same change and carries the model this rests on.