work: h051-059-main-sync-pre-pr-guard

[ExatronOmega]

Summary

• Signposter handoff for issue H051-059 — Main sync pre-PR guard #589.
• Source branch: work/issue-589-h051-059-main-sync-pre-pr-guard
• Base branch: main

Changed files

• src/signposter/git_utils.py
• src/signposter/pr.py
• tests/test_git_utils.py
• tests/test_pr.py

Safety notes

• Generated by Signposter PR planning surface.
• No merge or issue close is implied by this PR.
• Issue should remain open until explicit integration/close policy.

Related issue: #589

[AlphaExatron]

Signposter reviewer gate: APPROVE

Confidence: 0.88
Risk: medium
Scope match: yes
CI considered: yes
Merge recommendation: yes
Automerge eligible: no

Findings:

• The PR adds a read-only branch sync helper in git_utils and uses it in PR planning.
• Known out-of-sync states (ahead, behind, diverged) block PR planning before PR creation.
• unknown sync state is surfaced in PR plan output but does not block, avoiding false failures in checkout environments without local origin/main.
• PR plan output includes base sync status and reason as operator evidence.
• The initial PR CI failed because unknown was treated as blocking; the follow-up commit fixed that behavior and CI is now green.

Summary:
Reviewer approved this change.

No merge or issue close is implied by this review.