docs(branching): define promotion trigger criteria for next -> main repos

[ss-o]

Goal

Define when a next → main promotion should happen for the repositories
ADR-0008 assigns that branch model to, and decide whether any part of the
trigger should be automated.

Context

decisions/0008-branching-model.md establishes which repositories promote
(wiki, src, zi, zsh-lint, zsh-eza) and states that promotion is a
publication trigger for class-1 deploy repos. runbooks/branch-protection.md
and runbooks/release.md cover how a promotion is protected and reconciled
once it happens. None of these documents states when a promotion should
happen — that is currently informal maintainer judgment, undocumented and
unaudited.

A working precedent already exists for automating a readiness signal
without automating the merge decision: release-prepare.yml (class 2) opens
or updates a proposal issue with a draft changelog when releasable commits
land, but a maintainer still cuts the tag. The same pattern (propose, don't
auto-merge) is the natural fit for next → main promotion.

Decision needed

Choose a promotion-trigger model, potentially per class rather than
org-wide:

1. Continuous — promote on every green next commit. Simplest, but no
   margin for delayed/nightly CI failures on deploy-sensitive repos.
2. Bake/soak period — promote once next has been green for N
   hours/days. Fits wiki/src, where a bad promotion triggers a deploy.
3. Fixed cadence — batch commits into a scheduled promotion (daily/
   weekly). Reduces deploy flapping but is a poor fit for zi/zsh-eza,
   where main is the ref consumers pull directly and staleness has a
   direct cost.
4. Readiness-proposal automation — a promote-prepare.yml workflow
   (mirroring release-prepare.yml) opens/updates a next → main PR when
   next is ahead of main, checks pass, and no open release-blocker-type
   issue exists; a human still merges via the documented admin-bypass path.
5. Status quo — leave it fully manual, undocumented.

Acceptance criteria

• A documented trigger model exists for each next → main repository (or an
  explicit statement that one model applies to all of them, with reasoning).
• The chosen model states its relationship to existing CI/branch-protection
  requirements (runbooks/branch-protection.md) rather than duplicating
  them.
• Any automation proposed opens or updates a PR only — it does not
  auto-merge into main, consistent with promotion being a deliberate
  publication act (ADR-0008 Consequences).
• The decision is recorded as an ADR (or an accepted amendment to ADR-0008,
  per its "changing a repository's assigned model requires amending this
  ADR" clause) rather than left informal, so future audits have a written
  comparison point the way ADR-0008's branch-model table already provides
  for branch assignment.

References

• decisions/0008-branching-model.md
• decisions/0007-release-publication-flow.md
• runbooks/branch-protection.md
• runbooks/release.md (release-prepare.yml precedent)
• runbooks/adr.md

This issue records a policy gap and proposes options for maintainer
discussion. No workflow or policy file is changed as part of filing it.

[ss-o]

Current-state evidence for the five repositories ADR-0008 assigns the promotion model, measured today:

repository	next vs main
z-shell/zi	+37 / -0
z-shell/zsh-eza	+23 / -1
z-shell/wiki	+12 / -1
z-shell/src	+6 / -2
z-shell/zsh-lint	+4 / -1

Two things this suggests for the trigger design.

The backlog spread is wide. Unpromoted work ranges from 4 to 37 commits. A single commit-count threshold would fire constantly for zi and almost never for zsh-lint, so a count alone looks like a poor trigger. Age of the oldest unpromoted commit, or the presence of a releasable change, may discriminate better.

There is a second, separate drift. Four of the five also have commits on main that never came back to next (the -N column). That is the reverse direction from promotion, and it accumulates quietly after hotfixes or direct-to-main changes. A promotion trigger that only watches next → main will not surface it, and promoting while next is behind risks reintroducing whatever main fixed. Worth deciding explicitly whether the readiness signal should also assert -0.

Measured from public branch state only. Numbers move as work lands, so treat them as a snapshot rather than a target.