feat: template assurer/protector bot — enforce the mint contract, propose repairs, never auto-merge #579

What is being asked for

A fleet bot that acts as template assurer / protector / maintainer / reviver for repos
minted from hyperpolymath/rsr-template-repo.

The detection half is filed separately at hyperpolymath/hypatia#871. This issue is the
enforcement/repair half: what runs on a hit, and what it is allowed to do.

Why a bot, and why a cautious one

Four defects (#200, #201, #202, #203 in the template repo) are the same class: a child
asserting provenance it does not have. The estate has ~352 public repos and minting is
ongoing, so this is a standing condition, not a one-off cleanup.

But the repair surface is dangerous. Two of the four defects were caused by over-eager
automation: #203 happened because a generation step included all template branches, and
the duplicated CONTRIBUTING.md in #200 was itself a sync artefact. A bot that "fixes"
template drift without an ownership model will happily flatten legitimate child work — which
is why this must be report-and-propose first, with a narrowly allowlisted auto-fix set.

Proposed shape

Assure (read-only, scheduled)

1. Read each child's .machine_readable/PROVENANCE.a2ml; resolve template_repo /
   template_branch / template_commit / template_tree.
2. Run the conformance checks (see hypatia#871 for the rule set).
3. Emit a per-child receipt: conforming / drifted / unreachable-pin / provenance-absent.

Protect (fail-closed, cheap, no repair)

4. Fail any mint that would inherit template work branches. The child's branch set is a
   contract (extra_branches, empty = default-only) and include_all_branches must be
   false on the generate API path. This alone would have prevented Findings submissions #203.
5. Fail any mint whose provenance names the child as its own template (the chore(deps): bump github/codeql-action from 4.35.5 to 4.36.0 in the actions group #200/Claude/intelligent faraday 5 x ou u #201 class).

Maintain (propose, never auto-merge)

6. For template-owned paths that changed upstream, open a PR that takes the template side,
   leaving child-owned regions alone. This is Copier's update behaviour and it needs the
   ownership model to be safe — see the open question below.
7. Assign a decay issue for any divergence it cannot classify, rather than guessing.

Revive (opt-in, human-triggered only)

8. For a repo whose pin is unreachable (template branch deleted, history rewritten), rebuild
   provenance from the nearest resolvable ancestor and record that it was repaired, how, and
   by what, rather than silently stamping a fresh pin.

The ownership question this cannot answer alone

A hash-everything comparison is wrong: a child is supposed to diverge, so whole-tree
hashing flags every legitimate edit and is useless within a week. Template maintenance needs
a per-region ownership model — template-owned bytes vs child-owned bytes — which the estate
does not yet have in a machine-readable form.

Two viable routes, and this needs an owner decision (filed against standards):

• Adopt Copier — .copier-answers.yml, sentinel blocks, 3-way merge, copier update.
  Solved problem, battle-tested, but a real migration away from the bespoke repo-init.
• Stay bespoke and add the missing half — the estate already wrote its own answer-file
  (PROVENANCE.a2ml) and explicitly recorded that it was "hand-simulating" Copier/Cruft.
  Extending that means owning the ownership model ourselves.

Known caveat for whichever route wins: copier update applies only the delta between
template versions, so a template-owned file that diverged once is never healed by later
updates, and no conflict marker is left to show it. A conformance check is still required —
the update mechanism alone is not sufficient.

Acceptance

• A bot identity with an explicitly read-only default; write actions opt-in per repo.
• Mint-time protection (items 4–5) lands first — highest value, lowest risk, no repair.
• Repair actions open PRs and never push to a default branch.
• A documented "never do" list, including: never force unrelated histories together,
  never delete a branch only because it has no common ancestor, never hand-edit a
  generated region.
• Negative controls for every protection, per hypatia#871's acceptance note.
• Fleet enrolment/receipts coordinated with standards#636; do not invent a second
  composer (that responsibility is scaffoldia's).

Related

rsr-template-repo #200, #201, #202, #203, PR #207; hyperpolymath/hypatia#871;
standards#634, standards#636.