[AISOS-2495] Test Forge task takeover: clarify merge reconciliation documentation

[forgeSmith-bot]

Summary

This pull request clarifies the behavior of merged pull request reconciliation within the Forge task-takeover and feature workflows. By explicitly documenting and testing that terminal reconciliation relies on the repository namespace and pull request number rather than the head SHA, we prevent confusion and ensure robust matching even when commits are rebuilt, squashed, or force-pushed during human review. This documentation-only clarification alongside supportive testing helps maintain predictable workflow states for developers and automated processes alike.

Changes

Documentation

• Modified docs/guide/task-workflow.md: Added a note under the "Human Review" section clarifying that merged pull requests are terminally reconciled using the repository namespace and PR number instead of the head SHA.
• Modified docs/guide/feature-workflow.md: Added the matching clarification note to the "Human Review" section to maintain documentation consistency across different workflows.

Testing

• Modified tests/unit/workflow/test_pr_state.py: Introduced a new unit test, test_reconciliation_is_independent_of_head_sha, to assert and programmatically guarantee that PR matching and reconciliation are fully decoupled from head SHA.

Implementation Notes

Decoupling terminal reconciliation from the head SHA is a key design choice that prevents reconciliation failures when standard GitHub practices—such as squashing commits or rebuilding branches during review—alter the head SHA. Reconciling by repository namespace and pull request number ensures a stable, immutable identifier for the final state of the PR.

Testing

• Unit Testing: Added test_reconciliation_is_independent_of_head_sha inside tests/unit/workflow/test_pr_state.py to verify that pull request matching and reconciliation depend strictly on repository namespace and PR number, completely independent of the head SHA.
• Manual Verification: Reviewed documentation formatting and structure to ensure consistency across the task and feature guide documents.

Related Tickets

• AISOS-2495

---

Generated by Forge SDLC Orchestrator

[forgeSmith-bot]

🤖 Reviewing a Forge pull request

To send code feedback to Forge, open Files changed, select Review changes, and submit a Request changes review. Forge will address the review feedback automatically and push updates to this pull request.

Regular comments are ignored by the review workflow. Use them for conversation or the Forge commands below:

• /forge rebase - Merge the base branch (e.g. main) into this PR branch, with conflicts resolved by AI.
• /forge skip-gate <name> - Skip a named CI check (substring match) for this PR. This setting persists across subsequent pushes.
• /forge unskip-gate <name> - Remove a previously set CI check skip.

[eshulman2]

what about bug workflow? isn't it true there as well?

[forgeSmith-bot]

Forge is addressing PR review feedback now.