Context
The sync_all MCP tool performs bi-directional synchronization of issues, pull requests, and discussions, writing Markdown files directly to resources/content/. Running this tool while checked out on a feature branch pollutes that branch with upstream documentation changes and introduces race conditions.
The Problem
Currently, the "dev-branch-only" restriction for sync_all is merely documented in the OpenAPI specification ("description-as-policy"). This has proven empirically insufficient in environments with shared checkouts or multi-agent harnesses, leading to recurring branch pollution and chore: ticket sync conflicts.
The Architectural Reality
The agent-callable sync_all tool is mapped in ai/services/github-workflow/toolService.mjs directly to SyncService.runFullSync.
The Fix
We must enforce the branch restriction mechanically at the tool-surface boundary, not within the SyncService library itself.
- Wrap the
sync_all tool mapping in toolService.mjs with a branch-check guard that verifies git branch --show-current is dev.
- Throw a clear, actionable error if the branch is not
dev.
- Do not modify
SyncService.runFullSync directly, as daemons (e.g., PrimaryRepoSyncService) and release pipelines legitimately call it from their own controlled contexts.
Acceptance Criteria
Avoided Traps
- Checking inside
SyncService.runFullSync: Rejected because it would block legitimate daemon and build-script callers. The library should remain agnostic.
- Auto-checkout to
dev before sync: Rejected due to the high risk of side-effects on the caller's working tree (losing uncommitted work).
Related
- Supersedes #11145 (reframing the architectural requirement without attribution bias).
Context
The
sync_allMCP tool performs bi-directional synchronization of issues, pull requests, and discussions, writing Markdown files directly toresources/content/. Running this tool while checked out on a feature branch pollutes that branch with upstream documentation changes and introduces race conditions.The Problem
Currently, the "dev-branch-only" restriction for
sync_allis merely documented in the OpenAPI specification ("description-as-policy"). This has proven empirically insufficient in environments with shared checkouts or multi-agent harnesses, leading to recurring branch pollution andchore: ticket syncconflicts.The Architectural Reality
The agent-callable
sync_alltool is mapped inai/services/github-workflow/toolService.mjsdirectly toSyncService.runFullSync.The Fix
We must enforce the branch restriction mechanically at the tool-surface boundary, not within the
SyncServicelibrary itself.sync_alltool mapping intoolService.mjswith a branch-check guard that verifiesgit branch --show-currentisdev.dev.SyncService.runFullSyncdirectly, as daemons (e.g.,PrimaryRepoSyncService) and release pipelines legitimately call it from their own controlled contexts.Acceptance Criteria
toolService.mjssync_allmapping wraps with a branch-check guard.sync_alltool description updated to reflect mechanical enforcement.SyncService.runFullSynclibrary surface remains unchanged.Avoided Traps
SyncService.runFullSync: Rejected because it would block legitimate daemon and build-script callers. The library should remain agnostic.devbefore sync: Rejected due to the high risk of side-effects on the caller's working tree (losing uncommitted work).Related