Centralize build (build-reusable.yml) and bump Node

[SteveLLamb]

Summary

Replaces #346. Moves the per-repo build workflow into a single central reusable workflow in html-pub and folds the "official tooling" enforcement from #346 into it. Each document repo's main.yml becomes a thin stub, so future Action/Node bumps and pipeline changes happen once here instead of being copy-pasted (and cmp-locked) across ~70 repos.

Originally prompted by the GitHub Node 20 → 24 deprecation (forced 16 Jun 2026, removed 16 Sep 2026), which flagged actions/checkout@v3 and aws-actions/configure-aws-credentials@v1-node16.

Replaces #346

#346 ("Enforce official Tooling") kept the duplicated main.yml plus a diff/cmp match check. This supersedes it:

• Keeps the submodule provenance + currency enforcement (the valuable part).
• Drops the diff/cmp on main.yml — obsolete once main.yml is a stub (nothing to compare; it would false-fail).
• Relocates enforcement into build-reusable.yml (rides the pipeline ref → always current) instead of action.yml (submodule-pinned → its checks were only as fresh as the submodule being checked).

Closes #346 in favor of this.

What changed (html-pub)

• NEW .github/workflows/build-reusable.yml — on: workflow_call, holds the real pipeline:
  • actions/checkout@v5, aws-actions/configure-aws-credentials@v6 (Node 24 clean)
  • existing build/deploy steps unchanged (./tooling/workflows, ./workflows, release notify)
  • Enforce official tooling step (skipped in html-pub itself):
    • Provenance (always): tooling URL in .gitmodules must equal https://github.com/SMPTE/html-pub.git — blocks forks.
    • Currency (always — a build only happens when someone edits the doc, so editors must be current): recorded submodule SHA must equal latest official main, else fail with copy-paste bump instructions.
    • OVERRIDE_SUBMODULE_SHA / OVERRIDE_SUBMODULE_REF inputs — sanctioned escape hatch (mismatch warns instead of failing) for testing or rebuilding an old release.
• .github/workflows/main.yml → thin stub calling the reusable workflow locally (uses: ./.github/workflows/build-reusable.yml).
• workflows/action.yml:
  • removed the cmp "Confirm that the right workflow is active" step (obsolete; false-fails against stubs).
  • bumped marocchino/sticky-pull-request-comment@v2 → v3 (last Node 20 action surfaced in CI).

Residual: jwalton/gh-find-current-pr@v1 is still Node 20 — no Node 24 release exists yet, it isn't surfaced as a warning, and it will force-migrate on 16 Jun. Bump when upstream ships one.

How it works

• Document repo main.yml = thin stub: triggers + permissions + uses: SMPTE/html-pub/.github/workflows/build-reusable.yml@<ref> + secrets: inherit.
• The reusable workflow checks out the caller with submodules: true; uses: ./tooling/workflows resolves against the caller's checked-out submodule, so build/validation code stays pinned by each repo's submodule SHA (reproducibility preserved).
• Two independent version knobs, both zero per-repo maintenance for pipeline changes: the stub @ref (pipeline) and the submodule SHA (build code).

Testing — validated on SMPTE/tst123-4-private#2

All three enforcement paths verified on a real consumer repo (stub → build-reusable.yml@feature/bump-node-GH):

1. Happy path (override active) → ✅ green: Recorded == Target, "Official tooling confirmed", full build/deploy ran. https://github.com/SMPTE/tst123-4-private/actions/runs/27441610569
2. Currency failure (no override, submodule behind main) → ❌ fails with the bump message. https://github.com/SMPTE/tst123-4-private/actions/runs/27441392891
3. Fork rejection (.gitmodules pointed at SteveLLamb/html-pub) → ❌ fails the URL check before any submodule code runs. https://github.com/SMPTE/tst123-4-private/actions/runs/27441703680

Also confirmed the original Node 20 warnings (checkout, aws-creds, sticky-comment) are gone.

Rollout — every repo that uses the tooling submodule

After this merges to html-pub main:

1. Switch the pipeline ref to a stable one — use @main (auto-current) or a release tag in stubs, not the feature branch.

2. Replace each repo's .github/workflows/main.yml with the stub:

   name: Build SMPTE document
   
   on:
     push:
     pull_request:
     release:
       types: [published]
   
   jobs:
     build:
       permissions:
         id-token: write
         contents: write
         pull-requests: write
       uses: SMPTE/html-pub/.github/workflows/build-reusable.yml@main
       secrets: inherit

3. Ensure the tooling submodule uses the official URL and is bumped to latest main (enforcement requires it at edit time).

4. No with: OVERRIDE_* in production stubs — that block is testing-only; omitting it enforces latest main.

5. Update html-pub-template so new repos are born with the stub.

6. (Optional) update-tooling-submodule.yml still uses actions/checkout@v3 (warning-only, not cmp-guarded) — bump to @v5 when convenient.

Mechanical and scriptable across the ~69 existing repos; the stub never needs editing again for future pipeline/Action/Node bumps.

[github-actions]

Review links

Clean
Redline to current draft
Redline to most recent published edition

[SteveLLamb]

@palemieux

This applies the same reusable-workflow pattern as the auto-PCD rollout (see #423) — the real logic lives in one @main-referenced workflow in html-pub (build-reusable.yml, like pcd-update-reusable.yml), and each repo carries only a thin caller stub. Changes happen once centrally and every repo picks them up automatically, with the #346 official-tooling enforcement folded into that same central file.

And because this centralizes it, the repeated tooling-and-workflow bumps I've had to do across all repos over the last three months collapse into a single edit in html-pub. That recurring per-repo cascade is exactly what the reusable-workflow pattern eliminates.

• Enforcement currently runs on every build (PR, push-to-main, release), since a build only happens when someone edits a doc. If you'd prefer the currency check release-only, it's a one-line if: scope change (the URL/fork check should stay broad regardless).
• "Enforce latest main" means an old release can't be rebuilt against its original tooling without OVERRIDE_SUBMODULE_SHA — by design; flag if that's undesirable.