Carried rules name hub-only tooling that no downstream repo can run, so agents rebuild it by hand

[ptr727]

GOVERNANCE.md is carried by every fleet repository. It names a script that exists in none of them.

$ git show origin/develop:GOVERNANCE.md | grep -c 'scripts/pr_review.py'
1
$ git show origin/develop:spec/files.json | grep -c '"scripts/'
0

The line is GOVERNANCE.md "PR Review Etiquette" at line 301, instructing the reader to run scripts/pr_review.py status <n> --repo <owner>/<name> to read every review round rather than only the head. The instruction is correct and the tool works. A downstream agent following it finds no such path, because scripts/ is hub-only and appears in no spec/files.json baseline entry.

TODO.md already carries an entry asking where a carried file may name hub-only machinery. What that entry lacked, and what this issue adds, is evidence that the cost is being paid rather than anticipated.

What downstream agents do instead

They build their own. Over the past two days of onboarding, several sessions had to be redirected by hand to scripts/pr_review.py and scripts/prose_lint.py after producing worse ad-hoc versions of both. None of those agents did anything wrong. They were pointed at a tool absent from their tree by a document that does not say how to reach it, and reconstructing it is the only remaining move.

The second-order cost is worse than the duplicated effort. A rule that names a tool its reader cannot run teaches the reader that a pointer in carried text is decorative, and that lesson generalizes to the pointers that do resolve.

The same gap makes a safety rule harder to follow than it should be

Some operations fail the same way repeatedly regardless of how plainly the rule is stated. Two are on record from this fleet's own sessions:

• A command run from the wrong working directory, which does not error. It returns a confident answer about a different tree.
• A GitHub node id typed by hand into a mutation, which the gh-write-guard hook correctly refuses because the id did not come from a query in that same command.

The second is the instructive one. The rule against hand-typing an id is stated plainly in GOVERNANCE.md and again in the host-level guidance, and an agent that had read both still reached for the literal. That says the shape of the operation is what fails, not the agent's knowledge of the rule, and a rule restated more firmly does not fix a shape.

The fix is a shape that cannot be performed wrongly. A reply-and-resolve helper in scripts/pr_review.py would take a pull request number and a finding, query the thread ids itself, and never put an id anywhere a hand could type one. That removes the failure instead of detecting it after the fact.

It also depends entirely on this issue, because a helper only helps where it can be run.

Two resolutions, and they are not equivalent

The script joins the carried set. Every repository holds a copy, the pointer resolves, and every fix to the tool becomes a fleet re-vendor. This is the model repo-config/configure.sh already runs, and its cost is visible in the re-vendor entries in TODO.md.

The rule states the behavior and drops the tool name, the way the coordination-reference rule already requires of this repository. The pointer stops lying, and the tool stays unreachable, so the agents keep rebuilding it.

Neither is satisfying, which is why the TODO.md entry on reducing the copied surface proposes the third: the hub hosts the tool once and a downstream repository calls it, so there is no copy to go stale and no re-vendor to schedule. That option needs a pinning policy and an answer for an unreachable hub, and it is the same decision as the reusable-workflow question, so the three want settling together.

Related: #559 is the same class from the other direction, a carried file whose link definitions point into hub-only catalog/, dead in every downstream copy.

Filed from the onboarding-feedback pass in #576, where both halves are recorded as TODO.md entries.

[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 offered two resolutions and named a third from TODO.md. The third is what landed: the hub hosts the tool and a carried rule names it as the hub's.

What is on develop

GOVERNANCE.md carries a new verbatim section, Hub-Hosted Tooling, declared in spec/files.json and spec/section-model.md with a router row in AGENTS.md "Where the Rules Live". It answers the three questions this issue and the TODO.md entry left open:

• Carried against reached. A repository carries the content it is audited against and the configuration that describes it, and reaches machinery holding nothing per-repo.
• Pinning. A tool is named by its path in a hub checkout, read at main and fetched immediately before use, with its target named explicitly rather than defaulted, and the working directory left as the tool's own contract. CI reaches the same rules as a composite action pinned to a commit SHA, which is "Action pinning" applied unchanged and which .github/actions/prose-gate/action.yml already implements.
• An unreachable hub. The tool did not run, and that is the result reported, never a hand-rolled substitute. That is the failure this issue measured, stated as a rule.

The literal case is fixed: "PR Review Etiquette" names scripts/pr_review.py as the hub's and says it is invoked from a hub checkout.

The rule that was blocking it

"Carried files carry no coordination references" conflated where a file came from with what its reader runs, so a carried rule could not name a hub tool at all. It now carries a second exception for a hub-hosted tool the reader executes, with the test stated: where the content came from stays out, what the reader runs stays in. The audit's template_ref_outside_verbatim check needed no widening, because the new section defers to AGENTS.md "Fleet Bootstrap" for the destination and GOVERNANCE.md still holds no occurrence of the hub name.

The near-term half, also done

repo-config/configure.sh is out of the spec/files.json baseline, the fleet's only carried script and the worked example the TODO.md entry named. It resolves every payload path against its own directory, so a run from a hub checkout compares a repo against the hub's payloads and never opens the carried copies. Those copies stay, being what a repo is audited against and what its own AUDIT.md diffs the live rulesets against. spec/divergences.json carries a new retire disposition for a copy that is deleted rather than converged.

What this leaves

• The downstream deletion sweep. A repo holding a copy keeps it until next visited, and nothing flags it now that the manifest entry is gone. Regenerate reports/divergences.md before using it as the work list, since the committed copy predates this decision.
• The re-vendor sweep grows by an entirely new carried section no downstream repo holds, changed bytes in three verbatim GOVERNANCE.md sections, and a new AGENTS.md router row.

Both are carried on the TODO.md entries this change rewrote, so neither is lost by closing this.

The reply-and-resolve helper this issue proposed is a separate TODO.md entry, and the dependency it was waiting on is now met, since the rule states how a repository reaches a hub script.

Related: #559 is closed by the same change.