feat(tools): model pull-request review/merge as contract:change-request#678
Merged
Merged
Conversation
The vendor-neutrality scorer classified every pr-management skill as "portable" because they invoke `gh pr`, which matched contract:tracker — and tracker is green (GitHub + Atlassian). But Jira has no pull-request model: its adapter covers issues, not PR review/merge. So a skill driving `gh pr` is coupled to GitHub even though the issue side of tracker is portable. Introduce contract:change-request — the proposed-change review + merge gate (pull request / merge request / Gerrit change) — as a distinct vendor-backed contract with GitHub as the sole backend today. `gh pr` moves from the tracker usage tokens into change-request; tag tools/github with it. Result: 8/10 contracts vendor neutral (was 8/9); change-request joins mail-draft as the second open gap. 23 skills are vendor-coupled (the 19 that drive `gh pr`, plus the 4 mail-draft ones) — each flips to portable the moment a second forge review/merge backend (GitLab, Gitea) ships. Regenerate the docs/vendor-neutrality.md block (a pytest keeps it in sync) and register the contract in the skill-and-tool-validator allow-set. Raised on apache/magpie-site#17.
potiuk
force-pushed
the
feat/change-request-contract
branch
from
0c9c379 to
a11bb77
Compare
potiuk
added a commit
that referenced
this pull request
Jul 2, 2026
…mail patch backends (#669) (#679) contract:change-request shipped in #678 as a scorer policy entry with GitHub as the sole backend and no interface tool. This completes it into a full backend-neutral contract with two more backends, so the pull-request review/merge gate works on non-GitHub projects. - tools/change-request/: the interface spec (Kind: interface). Seven backend-neutral verbs (list_open, get, get_discussion, post_review, land, reject, status), generic lifecycle verbs, and the land <-> contract:source-control boundary. Answers the issue's four open questions (diff identity, CI/mergeable degradation, apply idempotency, patch-author vs committer attribution). - tools/jira-patch/ (Vendor: Atlassian): patch on a JIRA issue; review via JIRA comments; land delegates to asf-svn (svn patch + svn commit). - tools/mail-patch/ (Vendor: email): [PATCH] thread on dev@; reads via mail-archive, replies via mail-draft (never sends); land delegates to asf-svn. - tools/github: retag prose as one change-request backend (land = gh pr merge), no longer the sole one. - skills/pr-management-triage: contract-binding section mapping each disposition to a verb; the gh/GraphQL commands are the GitHub resolution of those verbs (triage never lands). - docs + scorer: change-request flips vendor-neutral (3 vendors: GitHub, Atlassian, email); score 8/10 -> 9/10; ~19 skills flip vendor-coupled -> portable; only mail-draft remains a gap. Regenerate docs/vendor-neutrality.md and add a scorer test. Naming: the issue proposed contract:change-proposal; ships as contract:change-request to match #678. Same seam; change-request is canonical. Closes #669. Co-authored-by: Tester <t@example.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The deterministic vendor-neutrality scorer marked the whole
pr-managementfamily (and 14 other skills) as portable, because
gh pr …matchedcontract:tracker— which is green (GitHub + Atlassian/Jira). But Jira onlyimplements the issue side of tracker; it has no pull-request model. So those
skills were credited with a portability that doesn't exist: PR review/merge
works on GitHub only.
What
contract:change-request— the proposed-change review + merge gate(PR / MR / Gerrit change), vendor-backed, GitHub sole backend today.
gh prmoves from thetrackerusage tokens intochange-request;tools/githubis tagged with the new contract.skill-and-tool-validatorallow-set and add ascorer test for GitHub-only change-request coupling; regenerate the
docs/vendor-neutrality.mdblock (kept in sync by an existing pytest).Impact
change-requestjoins
mail-draftas the second open gap.become portable as soon as a second forge review/merge backend (GitLab,
Gitea) ships — no skill code changes; the seam is the contract.
Follow-up in apache/magpie-site will surface these numbers on the /tools page
once this merges.
Raised on apache/magpie-site#17.
🤖 Generated with Claude Code