stack/docs/scratchpads/pr-merge-message-field.md

PR merge squash message field

• Charter: /home/hermes/agent-work/CHARTER-PRMERGE-MESSAGE-FIELD.md
• Owner: be-coder-08
• Branch: fix/pr-merge-message-field
• Base: remote main / local origin/main at 85d2108e4ed15c744ad3b87a5b629e7b2d39405a
• Estate: HOMELAB tooling shared by HOMELAB and USC

Objective

Add an optional, identity-checked Gitea squash message to pr-merge.sh so genuine multi-author PRs retain non-poster branch authors without weakening hardcoded squash behavior.

Binding requirements

1. Do remains hardcoded to squash; no provider/repository default may select merge style.
2. A verified trailer uses a PR commit's linked author.login and that same commit's author email. No /users/{login} primary-email lookup occurs. Recorded rationale: this asks only what the provider can answer.
3. A commit with author.login null blocks before merge, prints both the null provider fact and commit email fact, and names the escalation principal.
4. The BLOCK arm must be observed firing; a normal single-author API payload remains exactly { "Do": "squash" }.
5. Every provider mutation is read back from the provider; no real PR is merged during tests.

Derived interface decisions

• Add --co-author-trailers rather than accepting arbitrary message text. The wrapper enumerates PR commits and constructs trailers, making an unchecked Co-authored-by line unexpressible.
• Require --escalate-to PRINCIPAL with --co-author-trailers, so the BLOCK diagnostic always names a principal rather than a generic role.
• Do not expose MergeTitleField separately. When trailers exist, set it from the provider PR title and set MergeMessageField only to construction-generated trailers. This preserves one provider source for the title and avoids an unrelated caller-controlled degree of freedom.
• Preserve first-commit order and emit one trailer per distinct non-poster author.login, using that first linked commit's own email.

Plan

1. Version the currently deployed wrapper byte-for-byte under infra/fleet/tools/git/pr-merge.sh.
2. Pre-register verified, null-login BLOCK, unchanged single-author, and hardcoded-squash tests; observe RED before implementation.
3. Implement authenticated commit enumeration, construction-only trailers, message fields on REST, and force REST when trailers are requested.
4. Copy the exact final versioned bytes to the deployed wrapper; verify hashes match.
5. Run focused and baseline checks, static/security review, identity-bound commit, queue guard plus direct Woodpecker terminal enumeration, push, self-post PR, and provider poster read-back. Stop at push/PR; do not merge.

Evidence

• RED against the byte-identical deployed baseline (sha256 08a65e8584c5…): rc 1 with eight named failures. The wrapper rejected --co-author-trailers; the null-login path emitted none of the required BLOCK facts/principal; and both verified/ordinary API paths failed the stdin-config credential assertion (ordinary path exposed the fixture token through curl argv). Log: /home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-red.log.