The template-reference check and the byte-locked Fleet Bootstrap section cannot both be satisfied

[ptr727]

spec/audit.py flags any downstream AGENTS.md containing the hub's name, and the byte-locked AGENTS.md > Fleet Bootstrap section contains it. A repository that carries the canonical correctly is therefore guaranteed to fail the check, and the only way to pass is to break the byte-lock.

Audited against hub main 7194f91. Found on Blog immediately after it re-vendored Fleet Bootstrap from 3a7cc64 (ptr727/Blog#11), which is the first downstream repository to carry that section at all.

The two rules, both on main

spec/files.json declares the section verbatim:

{ "path": "AGENTS.md", "sections": [ { "name": "Fleet Bootstrap", "fidelity": "verbatim" }, ... ] }

The canonical text names the repository, and says so in its own words:

the canonical rules, machine-readable spec, and procedures live in github.com/ptr727/ProjectTemplate ... This section is byte-locked across every repository in the fleet, so it reads identically wherever it is found

spec/audit.py then flags exactly that, skipping only the hub:

if entry.get("name") != HUB_NAME:
 for path in ("AGENTS.md", "GOVERNANCE.md", ".github/copilot-instructions.md"):
 ...
 if ... HUB_NAME.lower() in ...:
 findings.append(("DRIFT", f"carried: {path} references the template repo ..."))

The comment above it reads "A downstream repo naming it is still flagged, which is the point." That intent is coherent on its own. It just cannot coexist with a byte-locked section whose whole purpose is to name the destination, since Fleet Bootstrap exists precisely to tell an agent where the rules live when nothing else present does.

Reproduction

$ python3 spec/audit.py --branch develop Blog
 DRIFT carried: AGENTS.md references the template repo by name or link (...)

Blog's AGENTS.md byte-matches the canonical Fleet Bootstrap, Context and Delegation Discipline, and Where the Rules Live, verified by hashing each ## heading block against the hub. The verbatim findings are gone and this one took their place.

Scope

reports/divergences.md lists 19 repositories still owing Fleet Bootstrap. Every one of them trips this check on the day it converges, so the finding count goes up as the fleet gets more correct, which inverts what the ledger is for. Blog is the only repository carrying it today, which is why it surfaced here first and why it is worth settling before the propagation wave.

Which rule gives

Not proposing a resolution, since it is a governance call, but the shapes seem to be:

• Exempt the Fleet Bootstrap region from the reference check, keeping the check for prose outside it. This preserves both intents: readers do not see coordination machinery in ordinary rule text, and the one section whose job is routing still routes.
• Drop the hub name from the canonical and describe the hub without naming it. This weakens the section, because an agent that reads "a shared template" with no destination cannot fetch it, which is the failure Fleet Bootstrap was added to fix.
• Narrow the check to GOVERNANCE.md and .github/copilot-instructions.md, where the stale "report drift upstream" paragraph the comment mentions actually lived.

The first looks closest to the intent behind both rules, but that is a preference and the call is yours.

🤖 Generated with Claude Code

[ptr727]

Resolved on develop at 3d1a0b1, by the first of the three shapes this issue offered, exempting the Fleet Bootstrap region from the reference check while keeping the check for prose outside it.

spec/audit.py now calls template_ref_outside_verbatim, which excises each verbatim region by position before scanning, so a repository carrying the canonical byte-for-byte no longer trips the check:

elif template_ref_outside_verbatim(text, verbatim_secs[path], HUB_NAME):

The function states why that is not a loophole:

A verbatim section's bytes are the hub's canonical and are checked byte-for-byte elsewhere, so a hub reference inside one cannot be removed downstream: the repo would have to fail the verbatim check to clear this one. [...] A hub reference that reaches a verbatim section is the hub's defect to fix once in the canonical, never each repo's to clear.

Eight self-test cases lock it, and two of them are the ones worth naming here. Positional excision rather than content removal is required by a fenced copy of the section is prose, not the section, which still flags, because removing the extracted text would delete a fenced copy along with the real region and the scan would fail open. And same document with nothing declared verbatim still flags keeps the check live for any repository that has not declared the section. The others cover a re-cased heading, a CRLF document, the heading appearing twice, a reference in prose the repo owns, and no reference at all.

Landed by #572. The scope concern this issue raised is also settled: the finding no longer rises as the fleet converges, which the regenerated reports/divergences.md confirms by listing AGENTS.md > Fleet Bootstrap as a section that never arrived for 18 repositories rather than as drift for the two that carry it.