You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/06/29 00:17:37 UTC
(magpie) 01/01: feat(tools): add source-control (VCS) capability and wire it into git-using skills
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch feat/source-control-capability
in repository https://gitbox.apache.org/repos/asf/magpie.git
commit 541bf6646b08a34d9bf24b8f380215340e7e990a
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Mon Jun 29 02:17:15 2026 +0200
feat(tools): add source-control (VCS) capability and wire it into git-using skills
Make source control a first-class, separable capability of the tool
layer, distinct from the issue-tracker / forge surface, so a project
can pair its tracker with a non-Git VCS.
- tools/github/source-control.md: new capability reference mapping the
abstract VCS operations the dev-loop skills need (status, branch,
stage, commit, diff, log, fetch, push, worktree, stash) to their Git
bindings, with the distributed-vs-centralized caveat and the list of
tracked non-Git bridges.
- tools/github/tool.md: list source control as the sixth capability and
document tracker/VCS separability in "When to replace this tool".
- projects/_template/project.md: dedicated Source control row in the
Tools enabled manifest.
- Wire the capability into the six skills that use git as the project's
source control (issue-fix-workflow, security-issue-fix,
pr-management-code-review, issue-reproducer, issue-reassess,
issue-triage): each now states its git calls are the Git binding of
the capability and that a non-Git VCS substitutes its own binding for
the same abstract operation. Framework-plumbing git usage (setup-*,
shared-config-sync, override-upstream) is intentionally left as-is —
it operates on the steward framework's own repos, not the project's
source.
Groundwork for the non-Git VCS bridges (#601-#605, #608).
Generated-by: Claude Code (Opus 4.8)
---
.claude/skills/issue-fix-workflow/SKILL.md | 13 ++++
.claude/skills/issue-reassess/per-issue-flow.md | 7 +-
.claude/skills/issue-reproducer/SKILL.md | 9 ++-
.claude/skills/issue-reproducer/runtime-recipes.md | 10 +++
.claude/skills/issue-triage/SKILL.md | 7 +-
.../skills/pr-management-code-review/selectors.md | 9 +++
.claude/skills/security-issue-fix/SKILL.md | 13 ++++
projects/_template/project.md | 3 +-
tools/github/source-control.md | 87 ++++++++++++++++++++++
tools/github/tool.md | 21 ++++--
10 files changed, 170 insertions(+), 9 deletions(-)
diff --git a/.claude/skills/issue-fix-workflow/SKILL.md b/.claude/skills/issue-fix-workflow/SKILL.md
index 2895510e..169bec06 100644
--- a/.claude/skills/issue-fix-workflow/SKILL.md
+++ b/.claude/skills/issue-fix-workflow/SKILL.md
@@ -181,6 +181,19 @@ opened (still gated by an explicit confirmation step).
---
+## Source control
+
+The `git …` invocations in this skill are the **Git binding** of the
+framework's source-control capability
+([`tools/github/source-control.md`](../../../tools/github/source-control.md)),
+operating on the project's `<upstream>` working copy. If the project's
+manifest enables a non-Git VCS under *Tools enabled → Source control*,
+substitute that tool's binding for the same abstract operations
+(working-tree status, branch, stage, commit, diff, push); the skill
+logic is unchanged.
+
+---
+
## Step 0 — Pre-flight check
1. **Issue exists and is triaged.** Fetch from `<issue-tracker>`;
diff --git a/.claude/skills/issue-reassess/per-issue-flow.md b/.claude/skills/issue-reassess/per-issue-flow.md
index eea0dbd0..83e17dc3 100644
--- a/.claude/skills/issue-reassess/per-issue-flow.md
+++ b/.claude/skills/issue-reassess/per-issue-flow.md
@@ -95,7 +95,12 @@ hygiene"*](../issue-reproducer/runtime-recipes.md#working-tree-hygiene),
the reproducer resets the working tree on its way out. The campaign
shouldn't need to do anything extra here, but it should **verify**
the reset happened before moving on (`git status` clean) —
-campaign-scale drift from working-tree leak is hard to debug.
+campaign-scale drift from working-tree leak is hard to debug. (The
+`git status` check is the **Git binding** of the framework's
+source-control capability
+([`tools/github/source-control.md`](../../../tools/github/source-control.md));
+a project on a non-Git VCS enabled under *Tools enabled → Source
+control* substitutes that tool's working-tree-status binding.)
## Bulk-mode subagent fanout
diff --git a/.claude/skills/issue-reproducer/SKILL.md b/.claude/skills/issue-reproducer/SKILL.md
index c404d0c5..c7ce9879 100644
--- a/.claude/skills/issue-reproducer/SKILL.md
+++ b/.claude/skills/issue-reproducer/SKILL.md
@@ -213,7 +213,14 @@ skill once per candidate in its campaign loop.
[`<project-config>/reproducer-conventions.md`](../../../projects/_template/reproducer-conventions.md).
4. **Working tree** — confirm we are in the `<upstream>` checkout
and `git status` is clean (or accept a `--allow-dirty` flag if
- the user explicitly opts in).
+ the user explicitly opts in). The `git` calls in this skill (here
+ and the reset protocol in
+ [`runtime-recipes.md`](runtime-recipes.md)) are the **Git binding**
+ of the framework's source-control capability
+ ([`tools/github/source-control.md`](../../../tools/github/source-control.md));
+ a project that enables a non-Git VCS under *Tools enabled → Source
+ control* substitutes that tool's binding for the same abstract
+ operations.
5. **Drift check** — see *Snapshot drift* above.
6. **Override consultation** — see *Adopter overrides* above.
7. **Credential-isolation setup verified** — Step 6 executes
diff --git a/.claude/skills/issue-reproducer/runtime-recipes.md b/.claude/skills/issue-reproducer/runtime-recipes.md
index ba3a50c6..f934acd5 100644
--- a/.claude/skills/issue-reproducer/runtime-recipes.md
+++ b/.claude/skills/issue-reproducer/runtime-recipes.md
@@ -156,6 +156,16 @@ worrying about accidental loss of legitimate work.
If the reset itself fails, stop and surface — do not proceed to
the next issue with a known-dirty tree.
+> **Source control.** The `git stash` / `git clean` / `git checkout`
+> / `git reset` calls above are the **Git binding** of the framework's
+> source-control capability
+> ([`tools/github/source-control.md`](../../../tools/github/source-control.md)),
+> resetting the project's `<upstream>` working copy between runs. If
+> the project's manifest enables a non-Git VCS under *Tools enabled →
+> Source control*, substitute that tool's working-copy-reset binding
+> (`hg revert --all` + purge, `svn revert -R` + cleanup, …) for the
+> same abstract operation; the reset protocol is unchanged.
+
## JDK / interpreter version awareness
Reproducer outcomes can depend on the runtime version. The skill
diff --git a/.claude/skills/issue-triage/SKILL.md b/.claude/skills/issue-triage/SKILL.md
index 0fb4cf4f..b26129ee 100644
--- a/.claude/skills/issue-triage/SKILL.md
+++ b/.claude/skills/issue-triage/SKILL.md
@@ -323,7 +323,12 @@ permits batched reads) the inputs the classifier needs.
6. **Recent-fix scan** — for `ALREADY-FIXED` detection, search
`<upstream>`'s git log since the issue's filing date for
commits referencing the issue key (e.g., `git log --grep=<KEY>`)
- or touching the cited code locations.
+ or touching the cited code locations. This `git log` is the **Git
+ binding** of the framework's source-control capability
+ ([`tools/github/source-control.md`](../../../tools/github/source-control.md));
+ a project on a non-Git VCS enabled under *Tools enabled → Source
+ control* substitutes that tool's history-read binding (`hg log`,
+ `svn log`, …) for the same abstract operation.
**Bulk mode for N > 5** — when the resolved selector has more
than 5 issues, follow the same subagent-fanout pattern as
diff --git a/.claude/skills/pr-management-code-review/selectors.md b/.claude/skills/pr-management-code-review/selectors.md
index bbd810bc..ca75de37 100644
--- a/.claude/skills/pr-management-code-review/selectors.md
+++ b/.claude/skills/pr-management-code-review/selectors.md
@@ -143,6 +143,15 @@ back empty, announce it once at session start (so the
maintainer knows the touching-mine half contributed nothing) and
fall back to review-requested only.
+> **Source control.** The `git log` / `git diff` calls here are the
+> **Git binding** of the framework's source-control capability
+> ([`tools/github/source-control.md`](../../../tools/github/source-control.md)),
+> reading history on the project's `<upstream>` working copy. If the
+> project's manifest enables a non-Git VCS under *Tools enabled →
+> Source control*, substitute that tool's history-read binding (`hg
+> log`, `svn log`, …) for the same abstract operation; the selector
+> logic is unchanged.
+
### Matching open PRs against the active set
Open PRs (excluding drafts and PRs authored by `<viewer>` —
diff --git a/.claude/skills/security-issue-fix/SKILL.md b/.claude/skills/security-issue-fix/SKILL.md
index bb5f8eb9..c7c11db9 100644
--- a/.claude/skills/security-issue-fix/SKILL.md
+++ b/.claude/skills/security-issue-fix/SKILL.md
@@ -170,6 +170,19 @@ in `docs/prerequisites.md` for the overall setup.
---
+## Source control
+
+The `git …` invocations in this skill are the **Git binding** of the
+framework's source-control capability
+([`tools/github/source-control.md`](../../../tools/github/source-control.md)),
+operating on the project's `<upstream>` working copy and its fork. If
+the project's manifest enables a non-Git VCS under *Tools enabled →
+Source control*, substitute that tool's binding for the same abstract
+operations (status, fetch, branch, diff, stage, commit, push); the
+skill logic is unchanged.
+
+---
+
## Step 0 — Pre-flight check
Do **all** of these before the Step 1 sync. Any failure is an
diff --git a/projects/_template/project.md b/projects/_template/project.md
index 87cbb3b0..b2494a90 100644
--- a/projects/_template/project.md
+++ b/projects/_template/project.md
@@ -86,7 +86,8 @@ publicly archived lists may appear in CVE `references[]` as
| Capability | Tool | Adapter directory | Config knobs declared here |
|---|---|---|---|
-| Issue tracking + source control + project board | `github` | [`../../tools/github/`](../../tools/github/) | `tracker_repo`, `upstream_repo`, `github_project_board_*`, `issue_template_fields` |
+| Issue tracking + project board | `github` | [`../../tools/github/`](../../tools/github/) | `tracker_repo`, `upstream_repo`, `github_project_board_*`, `issue_template_fields` |
+| Source control (VCS) | `github` (Git) — replaceable with a non-Git VCS | [`../../tools/github/source-control.md`](../../tools/github/source-control.md) | `upstream_repo`, `default_branch`; for a non-Git VCS declare the sibling tool + its working-copy URL |
| Inbound email / drafts | `<one or more mail-source backends>` | [`../../tools/mail-source/contract.md`](../../tools/mail-source/contract.md) (abstract) + per-backend adapter dirs (`tools/gmail/`, `tools/ponymail/`, `tools/mail-source/imap/`, `tools/mail-source/mbox/`, ...) | See [Mail sources](#mail-sources) below — declare each backend's role (primary / preferred-for-`<op>` / fallback / optional) and `mandatory` flag |
| CVE allocation + record mgmt | `vulnogram` | [`../../tools/vulnogram/`](../../tools/vulnogram/) | see [CVE tooling](#cve-tooling) below |
| Release voting / announce | TODO: ASF mailing lists — or replace with the project's release-comms backend | — | via `dev_list` / `announce_list` / `users_list` |
diff --git a/tools/github/source-control.md b/tools/github/source-control.md
new file mode 100644
index 00000000..c1c6ac2e
--- /dev/null
+++ b/tools/github/source-control.md
@@ -0,0 +1,87 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [GitHub — source-control (VCS) capability](#github--source-control-vcs-capability)
+ - [What the skills require](#what-the-skills-require)
+ - [Distributed-VCS assumptions](#distributed-vcs-assumptions)
+ - [When to replace this capability](#when-to-replace-this-capability)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# GitHub — source-control (VCS) capability
+
+Shared reference for the **version-control operations** the skills run
+against a local working copy of the project's source. On the GitHub
+tool this capability is backed by **Git** (`git` + `git worktree`),
+which is GitHub's native VCS.
+
+This is a *distinct* capability from the tracker / project-board
+surface documented in [`operations.md`](operations.md): those recipes
+talk to the GitHub API over `gh`; the recipes here operate on a local
+checkout with the `git` binary and never touch the network except for
+explicit `fetch` / `push`. A project can in principle pair GitHub's
+tracker with a different VCS, or a different forge with Git — see
+[*When to replace this capability*](#when-to-replace-this-capability).
+
+## What the skills require
+
+The dev-loop skills (`issue-fix-workflow`, `pr-management-code-review`,
+`issue-reproducer`, `issue-reassess`) and the `setup-steward` worktree
+machinery rely on the following abstract operations. The Git binding is
+shown alongside each; a sibling VCS tool provides its own binding for
+the same abstract operation.
+
+| Abstract operation | Git binding | Used by |
+|---|---|---|
+| Locate the repo root / common dir | `git rev-parse --show-toplevel` / `--git-common-dir` / `--git-dir` | worktree setup, all dev-loop skills |
+| Inspect working-copy state | `git status` (`-s` / `--short`) | fix-workflow, code-review pre-flight |
+| Create / switch a line of work | `git checkout` / `git switch`, `git branch` | fix-workflow (branch per fix) |
+| Stage + record a change | `git add`, `git commit -m` | fix-workflow |
+| Show changes | `git diff` (`--cached`, `<base>`) | code-review, fix-workflow |
+| History read | `git log` (`--oneline` / `--grep` / `--author` / `--since`), `git show` | reproducer, reassess, nomination |
+| Determine divergence base | `git merge-base`, `git rev-parse` | code-review (diff against base) |
+| Sync with the forge | `git fetch [origin]`, `git push [-u]` | fix-workflow hand-off |
+| Re-apply onto an updated base | `git rebase` | triage rebase action |
+| Isolated checkouts | `git worktree add` / `list --porcelain` | `setup-steward` worktree flow |
+| Park uncommitted work | `git stash --include-untracked` | fix-workflow safety |
+
+Write-path operations (`commit`, `push`, `rebase`) stay gated on
+explicit user confirmation in the calling skill, exactly as the
+tracker write paths are.
+
+## Distributed-VCS assumptions
+
+The Git binding assumes a **distributed** model: local commits,
+cheap branches, a `worktree` primitive, and a `fetch`/`push` split
+from the forge. Skills written against this capability should treat
+those as the *abstract* contract, not as guaranteed primitives — a
+centralized backend (e.g. Subversion, Perforce) maps "branch + local
+commit + push" onto a different shape (changelists, server-side
+branches) and its tool doc must spell out the divergence.
+
+## When to replace this capability
+
+Source control is a separable capability: any VCS that can provide the
+abstract operations above can be plugged in by creating a sibling
+`tools/<vcs>/` directory with its own `source-control.md` binding and
+listing it in the project manifest under *Tools enabled* (the
+*Source control* row). The generic skill logic — *"branch off the
+default branch, commit the fix, push for review"* — does not change
+when the VCS changes; only the bindings in the tool doc do.
+
+Tracked VCS bridges that implement this capability against a non-Git
+backend:
+
+- Mercurial (Hg) — apache/magpie#601
+- Apache Subversion (SVN) — apache/magpie#602
+- Jujutsu (jj) — apache/magpie#603
+- Fossil — apache/magpie#604
+- Perforce / Helix Core — apache/magpie#605
+
+Forge bridges that pair a non-GitHub forge with this capability live
+alongside the tracker bridges (GitLab #305, Forgejo/Gitea #310,
+Bitbucket #606, SourceHut #607 — the last also exercising the Hg
+binding).
diff --git a/tools/github/tool.md b/tools/github/tool.md
index 83a5c400..0300033d 100644
--- a/tools/github/tool.md
+++ b/tools/github/tool.md
@@ -24,12 +24,13 @@ A project opts into this tool by naming it in its manifest under
## What this tool provides
-The skills use GitHub for five distinct capabilities. Each has its own
+The skills use GitHub for six distinct capabilities. Each has its own
reference file in this directory:
| Capability | File | What it covers |
|---|---|---|
| CLI / API operations | [`operations.md`](operations.md) | `gh` CLI + `gh api` recipes the skills invoke (issue edit, milestone create, label edit, comment post, PR create, collaborator lookup, auth sanity check) |
+| Source control (VCS) | [`source-control.md`](source-control.md) | The version-control operations the dev-loop skills run on a local checkout — branch/commit/diff/log/fetch/push/worktree — backed by Git on the GitHub tool; the separable capability the non-Git VCS bridges plug into |
| Issue-body schema | [`issue-template.md`](issue-template.md) | The body-field schema pattern: skills read named `### <field>` sections from the issue body; the per-project field names are declared in the project manifest |
| Lifecycle labels | [`labels.md`](labels.md) | Generic lifecycle-label taxonomy (`needs triage`, `cve allocated`, `pr created`, `pr merged`, `fix released`, `announced - emails sent`, `announced`, closing dispositions) |
| Project board (Projects V2) | [`project-board.md`](project-board.md) | GraphQL introspection + `updateProjectV2ItemFieldValue` pattern; per-project node IDs live in the project manifest |
@@ -39,16 +40,26 @@ reference file in this directory:
The generic skills are written around an abstract *"issue tracker with
body fields, labels, milestones, comments, a project board, and a
-CLI"*. Any backend that provides those primitives can be plugged in by:
+CLI"*, plus a *"source-control working copy with branches, commits,
+diffs, history, and a fetch/push split"*. Any backend that provides
+those primitives can be plugged in by:
1. Creating a sibling `tools/<name>/` directory with the same files
- (`tool.md`, `operations.md`, `issue-template.md`, `labels.md`,
- `project-board.md` — the last only if the backend has a board-
- equivalent).
+ (`tool.md`, `operations.md`, `source-control.md`,
+ `issue-template.md`, `labels.md`, `project-board.md` — the last
+ only if the backend has a board-equivalent, and `source-control.md`
+ only for the VCS capability).
2. Listing that tool in the project's manifest under *Tools enabled*.
3. Declaring the backend-specific values (repo slug / project key / URL
templates / field names / board IDs) in the project manifest.
+The two capabilities are **separable**: the source-control capability
+([`source-control.md`](source-control.md)) can be backed by a
+different VCS than the tracker (e.g. GitHub issues over a Mercurial or
+Subversion working copy, or a Bitbucket/SourceHut forge over Git), so a
+sibling tool may implement only the VCS binding and leave the rest to
+the GitHub tool — or vice versa.
+
A JIRA adapter, for instance, would replace:
- `gh issue view/edit/create/comment` with JIRA REST calls;