State which checkout an agent works in and what the hub is

[ptr727]

Carries the TODO.md cluster "Reaching the Hub in Your Own Checkout" whole, all four entries. They ship together because a rule telling a repository to fetch the hub while staying silent on whose clone it fetches into licenses the failure it exists to prevent.

What changed

GOVERNANCE.md "Repository Boundaries and Write Safety" gains the isolation rule as two bullets, and its opening widens to say the section bounds a write to a checkout on disk as well as a write that reaches GitHub. The unit is the task rather than the agent, on the evidence in #557 that one agent hit the hazard alone when a git mv intended for the hub landed in another repository, so a per-agent rule would have permitted exactly the thing that went wrong. The three commands that cross the boundary are named because each is correct in isolation, and the rule pairs with the mechanical habit of giving a mutating command an absolute path rather than the working directory it inherited. The second bullet covers a tree another task is already live in: the two signals that say so, the instruction to stop rather than re-apply a reverted edit, and how a footprint already left there is undone.

GOVERNANCE.md "Verification Discipline" gains the same rule for reading. A clone is whatever it last fetched rather than the branch it names, so a finding taken from one carries a date nobody stated. That section is the home because its framing that every failure under it is green describes the stale-clone failure exactly.

AGENTS.md "Fleet Bootstrap" names github.com/ptr727/ProjectTemplate as the hub, so the word that carries the whole instruction is defined where the routing lives, and the closing paragraph goes from two bounding rules to three by adding the reach rule: a checkout of your own, fetched immediately before reading, worked in rather than in one that another task is using.

README.md defines six terms inside "What This Repo Is", for a repository that carries no instruction set and therefore cannot read the bootstrap section at all. Each term names the file that answers it, which doubles as the per-task entry point #579 asks for, so audit yourself against the hub resolves to AUDIT.md and close the review loop resolves to the PR Review Etiquette contract. No new heading, so the section order spec/readme-structure.md fixes is unchanged.

.github/copilot-instructions.md points a reviewer at the four hub scripts and at the GOVERNANCE.md exception permitting such a pointer inside carried text, since without it an agent has no in-file rule telling it a scripts/prose_lint.py reference is a hub pointer rather than a broken local path. The same edit corrects the byte-locked section count from two to three, matching what spec/files.json and spec/section-model.md both declare.

host-setup/agent-safety/ carries the same two rules in the host-wide blocks, which each state that they are kept in sync with their GOVERNANCE.md counterpart deliberately, because they cover sessions no AGENTS.md reaches. The safety block's heading becomes Repository Boundaries and Write Safety to match the scope it now has and the section it mirrors, and the kit README is corrected where describing that block: it no longer states a rule count, and it names both classes the hook mechanically enforces against the three that are prose only.

Fleet impact

Four verbatim sections change, so every fleet repository shows drift until the re-vendor. That rides the visit already queued under "Fleet Sweeps" rather than owing a sweep of its own. The two host-setup blocks reach a machine only when install.py is re-run there, and the installer replaces any v\d+ marker block in place, so the version marker stays at v1 and the renamed heading is picked up with it.

Verification

Run on c039ecd against origin/develop:

• python3 scripts/prose_lint.py . --diff origin/develop --summary reports 0 violations. The diff scope was confirmed non-empty first, 28 changed lines across 7 files, since a zero from an empty scope is the false clean that gate exists to prevent.
• python3 scripts/repo_gate.py reports 0 issues on both eol and sha-pin.
• python3 spec/validate.py reports 22 cataloged, 0 backlog repos classifying cleanly.
• python3 -m unittest discover -s scripts runs 268 tests, OK.
• markdownlint-cli2 over 44 files, cspell over README.md and HISTORY.md, editorconfig-checker, and actionlint all report clean.
• All seven files are still CRLF, checked by byte scan rather than by file.

Review

Five findings across four rounds, every one accepted and fixed, none declined. Three arrived as suppressed comments with no thread, and are answered in pull request comments quoting each one. Two of the five were defects this pull request's own earlier rounds introduced, which is recorded in the replies rather than quietly corrected.

Not carried here

TODO.md is untouched. Its clustered form exists only on the #592 branch, so editing it here would conflict. The cluster heading is deleted after #592 merges.

#557 and #579 close on the develop to main promotion, not on this pull request.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Defines key fleet terms (for “hub”, “review loop”, “stand up”, etc.) and strengthens governance guidance around working in isolated checkouts and avoiding stale-clone reads, so agents have unambiguous, self-contained instructions and failure modes are explicitly guarded against.

Changes:

• Adds explicit term definitions to README.md so requests like “audit against the hub” and “close the review loop” resolve to concrete entry-point docs.
• Extends GOVERNANCE.md write-safety scope to include local working-tree hazards and adds a corresponding stale-clone warning under verification discipline.
• Propagates the “hub” definition / reach guidance into AGENTS.md, .github/copilot-instructions.md, and host-wide host-setup/agent-safety/ blocks for consistency.

Reviewed changes

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

Show a summary per file

File	Description
README.md	Defines commonly used fleet terms and adds missing reference links for those entry points.
GOVERNANCE.md	Expands write-safety to include local checkout hazards and adds stale-clone guidance under verification.
AGENTS.md	Names the hub explicitly and adds the “reach the hub in your own fetched checkout” bounding rule.
.github/copilot-instructions.md	Adds guidance that hub-script references are intentional pointers (not broken local paths) and updates byte-locked section count/constraints.
host-setup/agent-safety/claude-md-safety.md	Mirrors the new local-checkout write-safety rule in the host-wide safety block.
host-setup/agent-safety/claude-md-fleet.md	Defines the hub explicitly and adds the “reach hub via your own fetched checkout” rule to the host-wide fleet bootstrap block.

[Copilot]

Pull request overview

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

Suppressed comments (1)

host-setup/agent-safety/claude-md-safety.md:2

• The section title says "GitHub Write Safety", but the opening paragraph now explicitly covers local working-tree writes (e.g., blanket add / hard reset) in addition to GitHub/API writes. Renaming the header would keep the scope consistent for readers skimming headings.

## GitHub Write Safety (Any Project, Every Session)

A `gh` / GitHub API write runs under the logged-in identity, so a mis-targeted write acts publicly as that account on someone else's repository, an outward-facing and hard-to-reverse act. These rules bound every write (a git push, an API mutation, a comment, a label, a merge) in every session on this machine, including ad-hoc work outside any project, and they bound a write to a checkout on disk as well, since a blanket add or a hard reset in a working tree another task is using destroys work without ever reaching GitHub. Reads are unrestricted. A committed repo's `GOVERNANCE.md` "Repository Boundaries and Write Safety" states the same rules for its fleet, and the two are kept in sync deliberately, because this file also covers sessions that `AGENTS.md` never reaches. The `gh-write-guard` PreToolUse hook enforces the mechanical half.

[ptr727]

Answering the suppressed finding from the round on 02f64e1, which has no thread to reply to.

The section title says "GitHub Write Safety", but the opening paragraph now explicitly covers local working-tree writes (e.g., blanket add / hard reset) in addition to GitHub/API writes. Renaming the header would keep the scope consistent for readers skimming headings.

Accepted and fixed in 1cc8b13. The heading is now Repository Boundaries and Write Safety (Any Project, Every Session), taking the name of the GOVERNANCE.md section it mirrors, which the block's own opening paragraph already says it is kept in sync with. The rename needs no marker-version bump, since install.py replaces the whole block by its v\d+ markers and the heading sits inside them.

Verifying it surfaced two further stale claims in host-setup/agent-safety/README.md that this pull request had introduced and nothing flagged, both fixed in the same commit:

• It described the block as carrying "the same three write rules", which this pull request made four. The count is dropped rather than corrected, since a hand-maintained count in prose is the maintenance trap GOVERNANCE.md "Quantitative Claims" exists for.
• It read "The write rules have a hook behind them", which now overreaches. The gh-write-guard hook watches Bash for GitHub writes and cannot see which checkout a command belongs in, so that sentence is narrowed to the GitHub write rules and says why the rest is prose only.

[Copilot]

Pull request overview

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

Suppressed comments (1)

host-setup/agent-safety/README.md:14

• The paragraph says only "The GitHub write rules have a hook behind them", but the hook also enforces the git branch-bypass protections described above (direct push/force-push/delete and --admin/--no-verify). As written, this understates what is mechanically enforced vs prose-only.

The hook is the mechanical backstop. The CLAUDE.md rules and the carried GOVERNANCE.md rules are the behavioral layer. Prose alone is not enough, since the incident happened under prose rules, so both ship. The GitHub write rules have a hook behind them, and everything else is prose only, since no hook can see which checkout a command belongs in, or what a line of text means.

[ptr727]

Answering the suppressed finding from the round on 1cc8b13, which has no thread to reply to.

The paragraph says only "The GitHub write rules have a hook behind them", but the hook also enforces the git branch-bypass protections described above (direct push/force-push/delete and --admin/--no-verify). As written, this understates what is mechanically enforced vs prose-only.

Accepted and fixed in daf3f50. The narrowing in 1cc8b13 overcorrected: it was answering the checkout-isolation rule having no hook, and in doing so it swept the branch-bypass class into "everything else is prose only", which the same file's own hook description five lines above contradicts.

The sentence now names both hook-backed classes, the GitHub write rules and the git operations that bypass a repository protection, and names the three that genuinely have no hook rather than leaving them as a remainder: which checkout a command belongs in, the data a line of text quotes, and how an authorization is recorded.

Worth recording that the previous round's fix introduced this one. A narrowing word is load-bearing, and narrowing to answer one case is how a neighboring case gets swept up in the remainder.

[Copilot]

Pull request overview

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

Suppressed comments (2)

AGENTS.md:20

• The phrase "one another task is using" is missing the relative pronoun and reads ungrammatically. Consider inserting "that" so the rule is clear and scans correctly.

Three rules bound every path above. **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. **Reach the hub as a checkout of your own and fetch it immediately before reading it**, because a clone is whatever it last fetched rather than the branch it names, and work only in that checkout rather than in one another task is using, per [`GOVERNANCE.md`](./GOVERNANCE.md) "Repository Boundaries and Write Safety" and "Hub-Hosted Tooling". And **the audit is read-only**: it produces a report and never edits the repository it measures, so a fix is a separate, reviewable change.

host-setup/agent-safety/claude-md-fleet.md:11

• This bullet uses "one another task is using" (missing "that"), which is grammatically incorrect and slightly obscures the intended guidance.

- **Reach the hub as a checkout of your own, fetched immediately before it is read.** A clone is whatever it last fetched rather than the branch it names, so a stale one answers confidently instead of failing, and a single file lifted out of the tree runs against whatever the caller happens to have. Work only in that checkout rather than in one another task is using, since a blanket add, a hard reset, or a branch switch in a tree someone else is editing destroys work while every command is individually correct.

[ptr727]

Answering both suppressed findings from the round on daf3f50, which have no threads to reply to. They are one finding against two files, AGENTS.md and host-setup/agent-safety/claude-md-fleet.md, and both read:

The phrase "one another task is using" is missing the relative pronoun and reads ungrammatically.

Fixed in c039ecd, both copies, but on a different reason than the one given. The construction is a reduced relative clause with an object gap, which is grammatical in English without the pronoun, the same shape as "the file another task is editing". So the sentence is not ungrammatical.

The observation underneath it is right anyway, and it is why the fix is taken rather than declined. "One another" is a fixed reciprocal pronoun, so a reader parses those two words as a unit and only backtracks on reaching the verb. A garden path in a rule that is byte-locked across the fleet costs every reader of every copy, and the explicit "that" removes it for one word.

Recording the reason precisely because these two files are carried, so the next reviewer of a downstream copy meets the same construction elsewhere and should decline it as a grammar finding while still taking it as a readability one.

[Copilot]

Pull request overview

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