Make migrated repos adopt template-sync, and stop it clobbering local hooks

[Bill Traynor (wmat)]

Three related changes to close the gap that let #165 sit unnoticed in a migrated repository.

1. MIGRATION.md never tells a migrated repo to adopt template-sync.yml

A repository created with Use this template gets the workflow in the initial file copy, and README.adoc step 4 explains it. A repository migrated by following MIGRATION.md gets only the files its 15 steps name — and none of them is template-sync.yml. So a migrated spec has nothing watching this repository at all.

That is not hypothetical. riscv-high-assurance-cryptography completed the migration in September and took #159, #161 and #165 by hand, each well after they merged upstream; #165 would not have surfaced there by itself. Its workflow directory still has no template-sync.yml.

New Step 16 — Adopt template-sync.yml (do not skip this): copy the workflow, confirm GHTOKEN is visible (organization secrets count), run it once rather than waiting for Monday, and review the bootstrap PR — which with no .template-version copies every template-owned file and is larger than every later one. It also says to decide deliberately about the reference documents (ANTORA.md, UPGRADING.md, ARC_SUBMISSION.md, CODE_OF_CONDUCT.md) that a migrated repo often never copied.

2. The don't-fork rule was only where migrators never look

UPGRADING.md puts it well — a local edit to a template-owned file "is a fork you will be re-doing on every upgrade forever" — but a migrator has no reason to open UPGRADING.md, and by the time they do the fork exists. Step 16 gains a Keep template-owned files unmodified subsection: send the change upstream if it generalizes, and otherwise put it in a file the template does not own (Makefile.local, a repo: local hook, a workflow of your own name). It cites how the spec above keeps its KAT workflow and link gate while taking build-pdf.yml and version-bot.yml verbatim.

3. .pre-commit-config.yaml is misclassified as template-owned

This one is a live regression, not a documentation gap. A spec repository is expected to add repo: local hooks for its own invariants, so the file carries template structure and repo-specific hooks on the same lines — the definition of a shared file. Copying it wholesale drops the repo's hooks without saying so.

Concretely, the next template-sync run against riscv-high-assurance-cryptography would delete this:

      - id: cross-page-refs
        entry: python3 scripts/check-cross-page-refs.py
        files: ^modules/ROOT/pages/.*\\.adoc$

— the gate that keeps cross-chapter links from rendering broken on the website — and move pre-commit-hooks from v5.0.0 back to this repository's v4.5.0.

So it moves out of the wholesale-copy list in template-sync.yml and into the shared for f in … list that gets reported for a hand merge, out of Template-owned in UPGRADING.md section A and into the Shared files table, and out of the git checkout command in section 2.4. The new table row and a short note say what is whose: take the template's hooks and rev bumps, keep your own repo: local block.

4. Nothing was updating action versions

dependabot.yml covered gitsubmodule and npm only, so action versions moved only when someone edited a workflow by hand. The Node 20 runner deprecation currently reaches seeded repositories as a warning on every single run with nothing opening a PR about it. Adds the github-actions ecosystem, monthly and grouped, so it arrives as one reviewable PR rather than one per action.

Verification

.github/dependabot.yml and .github/workflows/template-sync.yml both parse; check-yaml and yamlfmt pass. Every edit was applied through anchored string replacement that asserts each anchor matched exactly once, so no neighbouring text moved. grep confirms .pre-commit-config.yaml now appears only in the shared list and the two UPGRADING.md places, and no longer in either wholesale-copy list.

Documentation and configuration only — no workflow logic changes.

🤖 Generated with Claude Code