Refresh GitHubWorkflow.md for formal PR review tools

Part of #14310. Spawned from #14333.

Context

The #14333 capability-coverage audit found that the GitHub Workflow substrate is broadly documented, but learn/agentos/GitHubWorkflow.md is stale at a high-risk workflow point: it still frames review participation as posting a structured comment with create_comment, while current Agent OS review practice and the GitHub Workflow MCP surface require a formal PR review state through manage_pr_review or the documented gh pr review fallback.

This is not a request for a new GitHub Workflow guide. The guide already exists and is registered in learn/tree.json; the issue is that its PR review/tool section no longer matches the current source and review contract.

Live latest-open sweep: checked latest 20 open issues at 2026-06-29T16:32:13Z. Closest adjacent items were #14327, #14339, #14333, and current #14310 children, but no open issue specifically refreshes GitHubWorkflow.md for the formal PR review / reviewer invitation tool surface.

A2A in-flight sweep: checked latest 30 all-status messages immediately before filing; only recent #14333 checkpoint FYIs appeared, with no overlapping [lane-claim] or [lane-intent] for this guide-refresh scope.

Knowledge Base ticket sweep: no equivalent ticket surfaced. Exact/local sweep found adjacent implementation/review-contract tickets (#12951, #13587) and the current pull-request skill routing docs, but those do not update GitHubWorkflow.md.

The Problem

GitHubWorkflow.md currently teaches the old, comment-only review loop:

• learn/agentos/GitHubWorkflow.md:21-31 describes the Autonomous Review Loop and says the agent posts a structured review comment using create_comment.
• learn/agentos/GitHubWorkflow.md:108-110 documents get_conversation, create_comment, and update_comment for PR/issue conversations.

The current runtime and workflow contract moved beyond that:

• .agents/skills/pr-review/references/pr-review-guide.md:38 says formal reviews must use manage_pr_review; if unavailable, use the legacy comment plus gh pr review fallback, and the visible GitHub reviewDecision must be set either way.
• .agents/skills/pr-review/references/pr-review-guide.md:273 explicitly calls substantive review prose posted through manage_issue_comment without atomic manage_pr_review or fallback gh pr review a merge-gate failure.
• ai/mcp/server/github-workflow/openapi.yaml:730-787 exposes manage_pr_review as the formal PR review create/update primitive.
• ai/mcp/server/github-workflow/openapi.yaml:824-887 exposes manage_pr_reviewers as the reviewer-request invitation primitive.
• ai/services/github-workflow/PullRequestService.mjs:848-1011 implements formal PR review creation/update and returns review IDs, state, URL, and submitted time.
• ai/services/github-workflow/PullRequestService.mjs:1021-1094 implements reviewer-request add/remove using the REST requested_reviewers endpoint.
• Unit coverage exists for both managePrReview and managePrReviewers under test/playwright/unit/ai/services/github-workflow/.

This guide mismatch can train agents to post review-looking comments without flipping GitHub's formal review state, the exact failure class the current review workflow is designed to prevent.

The Architectural Reality

GitHubWorkflow.md is the public conceptual guide for the GitHub Workflow MCP server. It should explain the local-first sync model, issue/PR management, comments/conversations, ProjectV2 membership, and the formal review layer at the level a maintainer needs to use the server correctly.

The source-of-authority split should be preserved:

The Fix

Refresh learn/agentos/GitHubWorkflow.md so it reflects the current GitHub Workflow tool contract:

• Replace the old review-loop wording that says reviews are posted with create_comment.
• Explain manage_pr_review as the atomic formal PR review primitive and link it to the pr-review skill requirement.
• Explain manage_pr_reviewers as the reviewer invitation layer, distinct from merge/readiness validation.
• Update comment/conversation tool names from legacy create_comment / update_comment framing to the current manage_issue_comment / conversation-selector model where applicable.
• Keep the guide narrative and local-first sovereignty framing; do not turn it into an OpenAPI dump.
• Preserve the ProjectV2 section unless local V-B-A finds stale adjacent wording while editing.

Acceptance Criteria

• learn/agentos/GitHubWorkflow.md no longer instructs agents that the PR review loop is satisfied by a standalone comment tool.
• The guide names manage_pr_review as the formal review-state primitive and states that the visible GitHub reviewDecision must be set by manage_pr_review or gh pr review fallback.
• The guide names manage_pr_reviewers as the reviewer-request invitation primitive and distinguishes invitation from approval/merge eligibility.
• The guide updates stale comment-tool naming to the current manage_issue_comment / get_conversation selector model where relevant.
• The update links to .agents/skills/pr-review/references/pr-review-guide.md and/or summarizes its required formal-state rule without duplicating the full review template.
• The guide remains conceptual and readable; OpenAPI remains the complete operation reference.
• Run the guide lint/checks relevant to documentation changes, or state why no automated check applies.

Out of Scope

• Rewriting the whole GitHub Workflow guide.
• Changing the MCP tool contract or PR review workflow logic.
• Changing ProjectV2 behavior, release-board membership, or issue relationship semantics except for clearly adjacent stale wording discovered during the edit.
• Touching GitLab Workflow docs; #11404 owns GitLab productization.

Decision Record Impact

None. This aligns existing docs with implemented MCP tool surfaces and the existing pr-review workflow.

Related

• Parent epic: #14310
• Discovery audit: #14333
• Adjacent dead-command / final sweep tickets: #14339, #14327
• Adjacent implementation/history: #12951, #13587

Origin Session ID: f9ecf11e-78ce-4a48-b353-b970adf49d92

Retrieval Hint: query_raw_memories("formal PR review state gap manage_pr_review reviewDecision GitHubWorkflow guide comment-only recurring failure")