source-control: pull-request + babysit-prs are gh/GitHub-locked with no forge seam, under a forge-neutral plugin name

[kyle-sexton]

Plugin: source-control · Category: tool assumption (1) — observation / scope decision
Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)

Findings

• Entire pull-request + babysit-prs surfaces route every read and write through gh (tree-wide grep for gitlab/bitbucket/azure-devops/glab: zero hits). plugin.json:5 + keywords declare "github".
• commit, worktree, resolve-conflicts are forge-agnostic (pure git).

Why flagged

A consumer on GitLab/Bitbucket/Azure DevOps cannot use half the plugin's skills. Arguably inherent-and-declared (description/keywords say GitHub) — but the plugin name "source-control" is a generic domain noun that does not signal GitHub-only, while the playbook's naming rules normally surface tool scope as brand-in-name. Filed as a scope decision, not a hidden hardcode.

Fix direction

Either document the GitHub boundary prominently as an inherent declared scope (PLUGIN-PHILOSOPHY's cross-platform contract allows a declared narrower boundary), or record forge-neutrality as a deferred capability with a trigger. No hardcode swap.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human. Scope decision, not a hidden hardcode. pull-request + babysit-prs route every read/write through gh (grep: zero gitlab/bitbucket/azure hits); commit/worktree/resolve-conflicts are forge-agnostic. Two documented options: (a) declare the GitHub boundary prominently as inherent scope (PLUGIN-PHILOSOPHY's cross-platform contract permits a declared narrower boundary), or (b) record forge-neutrality as a deferred capability with a trigger. Product/scope call. Priority: high (north-star, source-control).

[kyle-sexton]

This was generated by AI (decision-brief lane).

Decision brief (2-minute read)

Problem. The source-control plugin carries a forge-neutral domain name, but its two highest-value skills (pull-request, babysit-prs) route every read and write through gh against GitHub-only concepts, so a GitLab/Bitbucket/Azure DevOps consumer loses half the plugin with no seam to plug into. The decision is whether to build a forge-adapter seam (the pattern work-items already shipped for trackers), or to declare GitHub an inherent scope and defer neutrality with a trigger.

Today. Verified against the current main checkout:

• ~168 gh invocation lines excluding tests/evals (188 including them) across plugins/source-control/ — dominated by gh pr (~103) and gh api (~71). Densest sites: skills/pull-request/SKILL.md (30), skills/pull-request/reference/monitor.md (32), readiness.md (15), create.md (14), merge.md (10), scripts/fetch-annotations.sh + scripts/fetch-failed-logs.sh (13 each), and the babysit engine (skills/babysit-prs/scripts/babysit_gh.py, babysit_merge.py, babysit_resolve_thread.py, bin/source-control-babysit-*).
• The coupling is conceptual, not just CLI syntax: Checks API (check runs, statuses, annotations), GraphQL review-thread pagination and resolveReviewThread, auto-merge, mergeStateStatus, CI-log ZIP fetch via gh run, and GitHub App / bot identities (claude[bot]). Roughly 8 of the plugin's userConfig keys in .claude-plugin/plugin.json are GitHub-semantic (bot logins, check contexts, watched owners).
• commit, worktree, resolve-conflicts, setup are pure git — forge-agnostic today. plugin.json already says "Git and GitHub delivery workflow" and keywords include github; only the plugin name is neutral.
• Repo precedent: plugins/work-items/tools/work-item-tracker/ — CONTRACT.md (ADR 0022), a dispatcher, adapters/github/ + adapters/local-markdown/ each with capabilities.json and per-verb scripts, plus a conformance suite, bound per-repo via .work-item-tracker.json. That seam works because it abstracts a small closed set of 9 verbs. The PR surface is an order of magnitude wider and is actively changing (feat(source-control): babysit autopilot merge tier — bot-account review + criteria-gated merge #476 merge tier approved-staged, source-control:babysit-prs: gh-bot.sh bot token generation fails, worker writes fall back to personal identity #450/source-control:babysit-prs: claude[bot] review job commits a fix locally but cannot push it (GitHub App write denied) #454 bot identities unresolved).

Options.

1. RECOMMENDED — Declare GitHub-only scope now; record forge-neutrality as a deferred capability with a trigger. Declare gh/GitHub as an inherent boundary of pull-request + babysit-prs per PLUGIN-PHILOSOPHY "Prerequisites and failure behavior" (README, plugin description, and skill-level prerequisite declarations); file the forge seam as deferred, trigger = first concrete non-GitHub consumer (or a maintainer-owned repo landing on another forge). Keep the plugin name: half the skills are genuinely forge-agnostic, and MIGRATION-PLAYBOOK ("Tool-scope shows up as brand-in-name, not a structural split... do not formalize such a split") argues against both a rename-to-brand (would misdescribe commit/worktree/resolve-conflicts) and a plugin split. Rationale: zero demand signal today (tree-wide grep for gitlab/glab/bitbucket/azure-devops: zero hits; the one real multi-backend demand, feat(work-items): Jira adapter for the work-item-tracker seam #379 Jira, is tracker-side, not PR-side), and abstracting the PR surface now means freezing an interface while feat(source-control): babysit autopilot merge tier — bot-account review + criteria-gated merge #476/source-control:babysit-prs: gh-bot.sh bot token generation fails, worker writes fall back to personal identity #450/source-control:babysit-prs: claude[bot] review job commits a fix locally but cannot push it (GitHub App write denied) #454 are still mutating it — a single-implementation seam built against a moving target. Fully reversible: nothing done here forecloses option 2 later; the deferral record preserves the paths and the work-items pattern as the named candidate. Flag for ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 (portability lint lane): the declared boundary needs a mechanical exemption so the lane doesn't re-file this class.

2. Full forge-adapter seam mirroring the work-items pattern. A forge contract + dispatcher + adapters/github/ with capabilities.json and conformance, consumed by both skills. Right end-state if multi-forge demand materializes, and the repo has proven the pattern. But the tracker seam covered 9 verbs; this one must cover PR CRUD, Checks/annotations, log fetch, review threads (GraphQL-only on GitHub), auto-merge semantics, and bot identity — across ~168 call sites including prose instruction files, with no second adapter to validate the contract against. High effort, high churn against feat(source-control): babysit autopilot merge tier — bot-account review + criteria-gated merge #476's staged merge tier, speculative until a consumer exists.

3. Thin choke-point indirection now, seam later. Extend the babysit_gh.py runner pattern so all scripted gh calls in both skills flow through one wrapper module, leaving SKILL.md/reference prose gh-explicit. Cheapest partial hedge and reduces later seam cost, but it buys no actual portability (the skills' instruction surface still speaks gh), adds indirection with a single implementation, and still ossifies during the feat(source-control): babysit autopilot merge tier — bot-account review + criteria-gated merge #476 churn window. Only worth doing opportunistically as scripts are touched, not as this issue's resolution.

Related.

• source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440 — outward_write_mode: report-only|write decided (default report-only); maintainer explicitly carved forge scope out as this separate decision. Orthogonal: the write-mode key applies to source-control regardless of forge scope.
• planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 — precedent: planning routed through the tracker seam, but that seam already existed and named wayfind in its contract; no analogous shipped seam exists for the PR domain.
• feat(work-items): Jira adapter for the work-item-tracker seam #379 — Jira adapter demand: tracker-seam-side, not PR-side; the current demand evidence for forge neutrality.
• source-control:babysit-prs: claude[bot] review job commits a fix locally but cannot push it (GitHub App write denied) #454 — claude[bot] push denied (GitHub App write): open identity/permissions question on the exact surface a seam would freeze.
• feat(source-control): babysit autopilot merge tier — bot-account review + criteria-gated merge #476 — babysit autopilot merge tier approved-staged: actively expanding the GitHub-specific surface.
• ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 — portability lint lane: needs a declared-scope exemption mechanism if option 1 lands.

[kyle-sexton]

Operator decision (2026-07-19, decision-session batch 1; relayed).

ACCEPTED (after seam clarification) — the brief's RECOMMENDED option: declare GitHub-only scope for pull-request + babysit-prs now (README, plugin description, skill-level prerequisite declarations); keep the source-control plugin name; record the forge seam as a deferred capability with trigger = first concrete non-GitHub git-host consumer. Clarified in-session: this is the git-forge seam (PR/merge host) only — the operator's day-job Jira requirement is the tracker seam, already decided and in flight via #379; nothing here affects it. Flag for #531: the declared GitHub boundary needs a mechanical exemption in the portability lint lane.

Re-intake: removing needs-human, adding priority: needs-triage for routing.