Decide the translation gate's scope, and whether to require it

[mairas]

Blocks merging hatlabs/halpi2#49, hatlabs/halmet#24, hatlabs/sh-esp32#20 and hatlabs/sh-rpi#29. Not a defect — a decision, surfaced by a 7-persona review that reached it from three directions (synthesis, findings 1, 3, 4).

What is actually true today

translation-status --check reads the whole repository. Its unit of judgement is the repo; the unit of work is one page in one language. So:

• An English-only edit cannot go green. One typo fix in docs/en/ marks that page's nine translations stale and exits 1.
• Every other open pull request inherits it. The paths filter was deliberately removed (a required check that never runs leaves a PR unmergeable forever), and actions/checkout builds the merge-with-main tree, so a PR touching only CI sees the same red.
• Merge skew reddens main with nobody at fault. Two PRs edit different parts of one English page; both authors do the full nine-locale job and stamp against their own hash; the merged file hashes to neither, so all nine go stale. Deterministic — the stamp covers the whole file.
• None of it blocks anything. No branch protection and no ruleset on main in any of the four repos (gh api repos/<r>/branches/main/protection → 404, rulesets → []). A red check sits beside an enabled merge button.

Three ways out

1. Require the check and accept the coupling. Add a branch protection rule naming translation-status / translation-status, with "require branches to be up to date before merging" on — that last part is what removes the merge-skew case. Honest, and what the plan intended. Cost: a typo fix becomes a nine-locale task, and the first stale page reddens every open PR until it is drained.
2. Rescope the gate. Block unconditionally on missing, unstamped and orphaned — structural, cheap to fix, no translation work implied. Block on stale only for English pages whose blob changed against the merge base. Keeps the whole-repository report and the whole-repository push-to-main check. Costs a change in halos-org/docs-tools and halos-org/shared-workflows.
3. Leave it advisory. Merge as-is, add no protection. Then none of the above costs anything — and the migration has changed nothing either, since the previous check was also advisory.

Merging the four PRs today selects option 3 by default.

Two consequences that follow from the choice

• Blocking creates the incentive for the one bypass the design cannot catch. A contributor blocked by a locale they cannot translate can re-stamp everything in seconds; the diff is one frontmatter line per file, indistinguishable from an honest re-stamp. The workflow header already assigns this to reviewers. A cheap CI assertion would catch the pure case: a translation whose translated_from changed must have at least one other changed line. Worth adding if option 1 is chosen.
• The bot now comments on every pull request, including ones touching no documentation, because removing the paths filter also removed the old workflow's early exit when a PR touched no English page. Under option 3 this is noise on every PR for a check nobody must satisfy.

[mairas]

Decided (2026-08-13)

Gate scope: option 2 — stale is scoped to the pages the pull request touched.

• missing, unstamped and orphaned stay absolute and whole-repository. They are structural, cheap to fix, and never imply translation work that the PR author did not create.
• stale counts only for English pages whose content changed in this pull request. Editing docs/en/faq.md without its translations is red; a page someone left stale last month does not redden a PR that touches only .github/.

Enforcement: yes — the check becomes required, with "require branches to be up to date before merging" enabled. That second part is what closes the merge-skew case (two independently green PRs merging into a red main).

Order of work

Branch protection comes last. Turning it on before the rescope would enforce precisely the whole-repository behaviour that was rejected.

1. halos-org/docs-tools — teach translation-status --check to scope stale to a diff, cut a release.
2. halos-org/shared-workflows — pass the right base ref per event.
3. Bump the pin in Adopt halos-docs-tools and the shared translation gate hatlabs/halpi2#49, Adopt halos-docs-tools and the shared translation gate hatlabs/halmet#24, Adopt halos-docs-tools and the shared translation gate hatlabs/sh-esp32#20, Adopt halos-docs-tools and the shared translation gate hatlabs/sh-rpi#29 and merge.
4. Add branch protection naming translation-status / translation-status on all four.

hatlabs/sh-rpi still needs its backlog drained before step 4: docs/en/tutorials/openplotter-server/index.md is missing in all nine locales, and missing is absolute under this decision.

Consequences accepted with option 1, now moot

The mass re-stamp bypass gets much less attractive: a contributor is only ever asked to translate pages their own PR changed, so there is no "blocked by a locale I cannot translate" pressure on unrelated work. Worth revisiting if that turns out to be wrong.

Still open and unchanged: the bot comments on every pull request, including those touching no documentation, because removing the paths filter also removed the old early exit. Tracked separately if it becomes noise.