docs(runbook): require post-promotion reconciliation

[ss-o]

Summary

• require post-squash main-to-next reconciliation for repositories using the next to main model
• document exact tree-equality and ancestry verification
• prohibit reset, rebase, force-push, or branch replacement as reconciliation shortcuts
• correct the source-guard reference to validate head-repository identity before branch name

Evidence

In z-shell/zsh-eza, a prior squash promotion left its new main commit outside next. The next promotion then required a dedicated reconciliation and produced four avoidable workflow conflicts. PRs z-shell/zsh-eza#88 and #90 demonstrate the promotion and immediate ancestry-only back-merge sequence this runbook now documents.

Instruction impact review

1. Classification: operational runbook guidance, not a new policy decision, runtime adapter, or enforcement mechanism.
2. Consumers: maintainers, humans, and all supported agent runtimes operating on repositories assigned the next to main model.
3. Canonical owner: runbooks/branch-protection.md remains the correct owner because this is a repeatable branch-protection and promotion procedure.
4. Duplication or contradiction: ADR-0008 owns the branch model and this runbook already owns promotion mechanics. No equivalent post-promotion reconciliation instruction exists. The former head-ref-only guard reference was incomplete.
5. Manifest impact: none. The existing required branch-protection route already selects this runbook.
6. Runtime delivery: unchanged. Every supported runtime receives the mandatory runbook through the required instruction manifest route, without optional hooks or skills.
7. Generated output and size: unaffected because neither AGENTS.md nor an adapter changes.

Validation

• python3 scripts/validate-agent-policy.py
• python3 -m unittest scripts/test_validate_agent_policy.py -v (68 passed)
• trunk check runbooks/branch-protection.md --no-progress
• Markdown content-contract and diff checks

Closes #483

[Copilot]

Pull request overview

Updates the branch-protection runbook to prevent main/next history divergence in repositories that use the next → main promotion model, based on observed conflicts after squash promotions.

Changes:

• Strengthens the “main source-branch guard” guidance to validate the PR head repository identity before allowing branch-name patterns.
• Adds a required post-promotion main → next reconciliation procedure, including tree-equality and ancestry verification steps.
• Explicitly prohibits reset/rebase/force-push/branch replacement as reconciliation shortcuts.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.