Vendor and document the maintainer merge workflow

[josecelano]

Goal

Bring the currently external, maintainer-operated pull-request merge workflow into this repository and document it as an agent-aware, reproducible process.

Background

Maintainers currently invoke /home/josecelano/Bin/github-merge.py through gh-merge {PR-NUMBER} to construct, inspect, sign, and optionally push local merge commits. The script is not versioned with this repository, and its required configuration, temporary branches, hook behavior, validation flow, and recovery process are undocumented here.

During the merge of PR #2020, the merge tool ran git merge --commit, which invoked the repository pre-commit hook. The hook's dictionary formatter rewrote project-words.txt and aborted the temporary merge commit. The incident showed that an external, undocumented merge tool leaves both maintainers and agents without a repository-local procedure for understanding side effects, recovering safely, and preparing a mergeable tree.

This task is related to EPIC #2003. It provides a concrete, immediately useful merge-workflow integration without selecting the EPIC's eventual automation architecture. The EPIC may replace or refactor the result after its design decision.

Scope

In scope

• Vendor the current merge script under contrib/dev-tools/git/ with its existing license and provenance preserved.
• Provide a repository-local entry point or documented invocation equivalent to the current gh-merge {PR-NUMBER} workflow.
• Add the dedicated AI-agent merge skill at .github/skills/dev/git-workflow/merge-pull-request/SKILL.md.
• Require the AI-agent merge skill to direct agents to verify the target branch and clean working tree; run the repository-local tool; inspect the temporary merge; run validation; recognize hook side effects; recover safely; and never sign or push without explicit maintainer confirmation.
• Document required Git configuration, credentials, signing prerequisites, temporary branches, merge inspection, testing, signing, and push confirmation.
• Document how Git hooks run during the tool's temporary git merge --commit operation, including the requirement that mutating hook actions leave the merge tree unchanged.
• Define a safe recovery procedure for a failed merge attempt, including how to return to the target branch and remove temporary state.
• Add maintainable automated coverage or a deterministic dry-run strategy for the repository-owned wrapper and any repository-specific behavior.
• Record the relationship to EPIC Overhaul: Automation Tools and AI Agent Guardrails #2003 without treating this implementation as its final automation design.

Out of scope

• Changing GitHub's server-side merge behavior or repository branch-protection policy.
• Replacing the repository's existing pre-commit or pre-push framework.
• Designing the final common action/check/policy runner proposed by EPIC Overhaul: Automation Tools and AI Agent Guardrails #2003.
• Automating maintainer judgment, PR review, or the final decision to sign and push a merge.
• Rewriting the vendored merge algorithm beyond necessary repository integration, security, portability, or correctness changes.

Acceptance criteria

• The merge tool is versioned under contrib/dev-tools/git/ with its provenance, copyright, and license preserved.
• A maintainer can discover and invoke the repository-local merge workflow without depending on an undocumented path outside the repository.
• .github/skills/dev/git-workflow/merge-pull-request/SKILL.md provides AI agents with explicit instructions for preflight, temporary branches, merge inspection, validation, hook side effects, recovery, signing, and explicit push confirmation.
• Documentation explicitly states that the tool creates a temporary merge commit with git merge --commit, which invokes installed pre-commit hooks.
• Documentation explains how a mutating hook action can block a merge and gives a safe recovery path that does not discard unrelated work.
• Automated coverage or a documented deterministic dry-run strategy validates repository-specific, non-destructive behavior; unsupported interactive or networked paths have an explicit test-boundary rationale.
• The implementation's interim relationship to EPIC Overhaul: Automation Tools and AI Agent Guardrails #2003 is documented and does not claim to choose the future automation architecture.
• linter all and relevant tests pass.
• Manual verification scenarios are executed and documented with status and evidence.
• Acceptance criteria are re-reviewed after implementation and reflect actual behavior.

Verification plan

Automatic checks

• linter all
• Focused tests for the repository-local merge tool, wrapper, or dry-run behavior
• TORRUST_GIT_HOOKS_LOG_DIR=.tmp ./contrib/dev-tools/git/hooks/pre-commit.sh
• Pre-push checks when applicable

Manual scenarios

1. Prerequisite discovery: From a clean checkout, follow only repository-local documentation to identify required Git configuration, credentials, and signing setup.
2. Non-destructive merge inspection: Run the repository-local merge tool for a disposable test PR or supported dry-run fixture, then decline signing and pushing. The target branch must return to its initial commit without temporary branches or unrelated changes.
3. Hook-side-effect recovery: In an isolated checkout with a deliberately unsorted dictionary, trigger a pre-commit abort during merge inspection and follow the documented recovery. It must preserve unrelated work and explain how to prepare a canonical merge tree before retrying.
4. Signed merge completion: In an authorized disposable or maintainer-reviewed context, inspect, validate, sign, and explicitly confirm a push. The merge commit must be signed and pushed only after confirmation.

Risks and trade-offs

• Vendoring a script preserves a known workflow but creates an ownership obligation. Preserve provenance and license, minimize local divergence, and document the update policy.
• The workflow is interactive and can push protected branches. The skill must retain explicit human confirmation rather than making signing or pushing automatic.
• Git hooks can mutate the temporary merge tree. The workflow must make this visible, require a clean canonical tree before retrying, and document recovery that protects unrelated work.
• Network, credential, GPG, and interactive-shell paths are difficult to unit test completely. Cover deterministic local behavior and document manual verification boundaries explicitly.

References

• Related EPIC: Overhaul: Automation Tools and AI Agent Guardrails #2003
• Triggering PR: feat(git): format project dictionary before commits #2020
• External source before vendoring: /home/josecelano/Bin/github-merge.py
• Planning snapshot SHA-256: e390eb014131f3183a2cba642134974a6b09b19a65322d17dd7c81cf4ffbaad2
• contrib/dev-tools/git/hooks/pre-commit.sh
• contrib/dev-tools/git/format-project-words.sh

[josecelano]

Implemented via #2027