kandev/docs/plans/github-auto-merge-reliability/task-01-bind-and-pace-asynchronous-merge.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-bind-and-pace-asynchronous-merge	Bind and pace asynchronous merge	done	1		plan.md	REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002	AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.1 AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.7	../../specs/integrations/system-design/github-pr-merge-queue.md

Task 01: Bind and Pace Asynchronous Merge

Summary

Carry the reviewed head SHA through the automatic merge provider call. Pace pending status requests and keep the operation bounded by context.

In scope

• Replace positional merge parameters with a typed request value.
• Require an expected head on the automation service path.
• Send GitHub's sha field through the CLI and PAT clients.
• Decode the provider expected-head diagnostic.
• Wait at least one second between pending reads.
• Add deterministic provider, service, mismatch, timeout, and cancellation tests.

Out of scope

• Attempt persistence or retry authorization.
• Changes to manual merge eligibility or presentation.

Acceptance

• An automatic request cannot merge a head that differs from the refreshed head.
• Pending reads occur no more than once per second.
• Cancellation and the existing deadline stop polling promptly.
• Manual merge behavior remains unchanged.

Verification

go test -tags fts5 ./internal/github -run 'Test(GHClient|PATClient).*MergePR|TestMergePRForAutomation'

Run the command from apps/backend.

Files likely touched

• apps/backend/internal/github/client.go
• apps/backend/internal/github/gh_client.go
• apps/backend/internal/github/pat_client.go
• apps/backend/internal/github/service_pr.go
• apps/backend/internal/github/gh_client_commands_test.go
• apps/backend/internal/github/pat_client_writes_test.go
• apps/backend/internal/github/service_pr_auth_test.go

Dependencies

None.

Risks

• Interface changes affect provider mocks and non-automation callers.
• Real waits can make tests slow. Tests need an injected wait boundary.

Parallelism

sequential

Inputs

• Integration acceptance criteria 002.1 and 002.7.
• GitHub asynchronous merge response and expected-head contracts.

Results

• Added a typed merge request with an optional method and expected head SHA.
• Required a non-empty expected head on the automatic merge service path.
• Sent GitHub's sha field through the CLI and token clients.
• Added context-aware one-second pacing before pending status reads.
• Included the provider's expected head in failed-request diagnostics.
• Verification: focused GitHub tests passed, 26 tests.
• Verification: orchestrator head-forwarding regression passed, 1 test.