ptr727/projecttemplate/carried-instruction-file-guard

Carried Instruction File Guard

Why this exists

A downstream repo's AGENTS.md/GOVERNANCE.md/CODESTYLE.md/WORKFLOW.md can hold two different kinds of content mixed in one file. One kind is sections that are stale copies of the hub's fleet-wide rules. The other is local rules the repo wrote for a fault the fleet has never seen elsewhere. Re-vendoring the hub's canonical version over the whole file deletes the second kind silently, because nothing about the diff looks wrong. This has actually happened. A resync replaced a repo's AGENTS.md wholesale with the hub's. The repo's own local additions were gone with no error, no warning, and no review comment calling it out.

The fix is not "be careful." Being careful is what failed the first time. The fix is a mechanical check you run before any overwrite touches one of these files, every time, regardless of how routine the request sounds.

Before you touch any of these files

1. Check whether the file's content is declared `verbatim` or `intent`. The hub's spec/section-model.md names, section by section, which parts of AGENTS.md and GOVERNANCE.md are universal fleet law (safe to byte-match against the hub). It also names which parts describe the repo itself (never safe to overwrite from another repo). Fetch it from a hub checkout, github.com/ptr727/ProjectTemplate, if you don't have one. CODESTYLE.md and WORKFLOW.md are carried whole at intent fidelity, judged by meaning, not hashed.
2. If any part of the file is `intent`, or if the file predates a clean split into hub-governed sections, do not diff-and-replace. Probe instead. For each rule or paragraph in the current file that is not obviously boilerplate:

• Pick the phrase in it that is most peculiar to this repo, not generic governance vocabulary. A rule about "always sign commits" is generic. A rule about "this repo's Docker image pins Alpine 3.19 because 3.20 broke the s6 supervisor" is peculiar.
• Grep the hub's canonical copy of the same file for that peculiar phrase.
• Absent from the hub canonical means it is a local addition. It is never dropped because it looks similar to something else, and never dropped because a merge or overwrite would be simpler without it.

1. A local addition found by the probe gets a destination, not a deletion. It either names a rule that should apply fleet-wide, or it is genuinely specific to this repo. In the first case, flag it for the maintainer to promote into the hub. In the second case, it moves to the repo's own topical doc before the carried file is touched. Those docs are CODESTYLE.md for a language/formatting convention, ARCHITECTURE.md for a design decision, OPERATIONS.md for a runbook or operational note, TODO.md for backlog. Move it, confirm it is not lost, and only then proceed with the carry.
2. Do not trust a similarity or word-overlap check for step 2. A repo-specific rule written in ordinary governance language reads as a reworded duplicate of an unrelated hub rule to that kind of check. That check will confidently tell you the local content is redundant when it is not. Exact phrase presence or absence is the only check that has held up.

What is actually safe to overwrite without this procedure

A section spec/section-model.md names as verbatim can be re-vendored directly, in a file that is already cleanly split. Cleanly split means the file carries only that declared section, nothing else mixed in. Byte-matching such a section against the hub canonical is the point of verbatim fidelity, and the audit already checks it that way. The guard above is for everything else. That is intent-fidelity content, a file that has not been split yet, or any file you are not certain is clean.

If you are not sure which case you are in

Stop and say so, rather than guessing. Naming the uncertainty costs one sentence. Silently overwriting the wrong thing costs someone's local rules with no way to notice until much later.