Define a merge path for App-authored signed docs sync PRs

[ss-o]

Objective

Define and validate a safe merge path for GitHub App-authored, verified documentation-sync pull requests targeting next, without bypassing or weakening the wiki's branch rules.

Evidence

The current next ruleset requires verified commit signatures and linear history. The zsh-lint reference-sync workflow intentionally uses a GitHub App token with sign-commits: true, so its pull request will be authored by the App bot and its head commits should be verified.

GitHub's documented merge behavior creates a policy conflict:

• On a branch requiring signed commits, GitHub only permits squash merging through the web UI when the person performing the merge is the pull-request author.
• Rebase-and-merge rewrites commits without signature verification.
• Merge commits conflict with the required-linear-history rule.

A human maintainer therefore cannot use the ordinary GitHub UI to merge the App-authored sync PR while preserving both current rules.

Related provisioning task: z-shell/zsh-lint#85

Acceptance criteria

• Select a merge strategy after comparing at least:
  • a maintainer-dispatched, App-authenticated squash merge after review;
  • App-enabled auto-merge gated by explicit pull-request reviews and required checks;
  • any GitHub-native alternative that preserves verified signatures and linear history.
• Preserve required commit signatures and required linear history.
• Require explicit human review and successful required checks before an automated or App-authenticated merge can complete.
• Do not rely on administrator/ruleset bypass for the normal path.
• Restrict any App token to the existing minimum repository permissions and the z-shell/wiki installation.
• Document the operator flow, failure recovery, and emergency disable/revocation path without recording credentials or installation identifiers.
• Validate the selected path with an App-authored PR from docs-sync/zsh-lint to next.
• Confirm the resulting commit on next remains verified and the branch history remains linear.

Boundaries

• This issue owns merge-policy and merge-operation design for the wiki.
• It does not provision the GitHub App or store its credentials; that remains in Provision the GitHub App for wiki reference synchronization zsh-lint#85.
• It must not weaken signature, history, review, or check requirements merely to make automation mergeable.
• Do not publish App identifiers, installation details, private keys, or other secret material.

Triage

Suggested item type: Task
Suggested priority: Medium
Suggested effort: Medium
Suggested status: Todo

[ss-o]

New evidence from #797 confirms the documented rebase-merge failure mode.

Before merge, both PR commits were SSH-signed and independently verified. The PR passed Trunk, Build Performance, CodeQL, local production build, and hosted review. GitHub's rebase merge then replaced them with cd42fc5b and 0d4c8334; the public GitHub commit API reports both as verified: false, reason unsigned. The active next ruleset remained enabled, so the connector-backed merge path bypassed the intended signature gate.

Do not use rebase merge for this path. Content and linear history are correct, but signature remediation requires a separate maintainer decision: either replace only these two freshly-created equivalent commits with the reviewed signed originals using an exact force-with-lease, or accept the unsigned merge artifacts and keep remediation tracked here. No branch rewrite or ruleset change has been attempted.

[ss-o]

Follow-up from the reconciliation incident:

• GitHub's rebase merge rewrote the two reviewed signed commits as unsigned commits, confirming that rebase merge is not a valid normal path under the signed-history requirement.
• With maintainer approval, next was repaired using an explicit exact lease: 0d4c8334e08085b5a39ebdd01edb46f9e196f57e → c62e99fc4009bdd77891356c5b88b44ca0526d82.
• A fresh fetch confirms the remote parent chain 04bba130 → 31c8c94c → c62e99fc; git verify-commit succeeds for both remote-referenced commits with the expected ED25519 signer.
• The repaired head and the rewritten head have the same tree (c6f692879acbfa62738e1a276ee2b902ccfb8c5d), so this changed commit identity/signature state only.
• No branch rule or repository setting was changed.

This is recovery evidence, not the desired recurring merge path. The acceptance criteria here remain open.