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 09:30:57 UTC
(magpie) branch main updated: docs(taxonomy): fix relabel collateral from the capability split (#645)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new a3e07554 docs(taxonomy): fix relabel collateral from the capability split (#645)
a3e07554 is described below
commit a3e0755457dfc81ce0242dd73725210fd42569aa
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Mon Jun 29 11:30:51 2026 +0200
docs(taxonomy): fix relabel collateral from the capability split (#645)
* docs(taxonomy): fix relabel collateral from the capability split
Deep review of the #641 capability-axis split surfaced prose that the
mechanical relabel left in the old single-vocabulary state — the
validator can't catch these because they live in skill/doc bodies, not
frontmatter or the machine-checked maps.
Flagged in #641 review:
- write-skill worked example said `setup-isolated-setup-doctor` is
`capability:authoring` — wrong. `authoring` is reserved for skills
that author other skills (write-skill, optimize-skill); the
setup-doctor is a platform skill. Fixed to `capability:platform`
(matching its frontmatter `platform + reassess`).
- stale "nine buckets" count (the split makes ten skill capabilities)
in docs/labels-and-capabilities.md and two write-skill references.
Found in the deep review (lifecycle phases wrongly stamped on tools,
which RFC-AI-0005 explicitly abolishes for the tool axis):
- cve-org row carried `*(resolve)*` / `*(intake)*` skill-phase tags.
- mail-source row said "the abstraction is setup".
- ponymail row described the removed "dual role / intake-pipeline
component".
- skill-evals row said "setup infrastructure".
- the Capability-to-tool map header still implied dual-value rows.
All rewritten to describe the interface the tool provides. Validator
green; no frontmatter or capability-sync changes.
Generated-by: Claude Code (Opus 4.8)
* docs(taxonomy): gmail declares both mail contracts; classify MCP servers
gmail does inbound report intake *and* outbound courtesy-reply drafting,
so it provides two contracts, not one. Declare
`contract:mail-source + contract:mail-draft` and thread the mail-source
membership through both directions so it stays consistent:
- tools/gmail README capability line + role text.
- docs/labels-and-capabilities.md tool-map row + the dual-value note in
the map header (gmail is the one tool carrying two values today).
- tools/mail-source README and the two docs/vendor-neutrality backend
rosters now list the Gmail API as a mail-source backend.
Also add an "MCP servers, classified by capability" section to
docs/labels-and-capabilities.md: the four MCP servers the framework's
tools consume (GitHub, Gmail, PonyMail, apache-projects), each
classified by the capability its wrapping tool provides — an MCP is a
transport behind a contract, not a separate axis.
Validator green (capability-sync matches the dual gmail label).
Generated-by: Claude Code (Opus 4.8)
---------
Co-authored-by: Tester <t...@example.com>
---
docs/labels-and-capabilities.md | 45 ++++++++++++++++++++++++++++++++---------
docs/vendor-neutrality.md | 4 ++--
skills/write-skill/SKILL.md | 9 +++++----
tools/gmail/README.md | 7 +++++--
tools/mail-source/README.md | 2 +-
5 files changed, 48 insertions(+), 19 deletions(-)
diff --git a/docs/labels-and-capabilities.md b/docs/labels-and-capabilities.md
index 7d6d4a04..0ded88dc 100644
--- a/docs/labels-and-capabilities.md
+++ b/docs/labels-and-capabilities.md
@@ -11,6 +11,7 @@
- [Standalone labels](#standalone-labels)
- [Capability to skill map](#capability-to-skill-map)
- [Capability to tool map](#capability-to-tool-map)
+ - [MCP servers, classified by capability](#mcp-servers-classified-by-capability)
- [The rule](#the-rule)
- [A GitHub issue](#a-github-issue)
- [A pull request](#a-pull-request)
@@ -219,15 +220,17 @@ Capabilities for every skill currently in
## Capability to tool map
-Tools under [`tools/`](../tools/). Tools with two values (separated by
-`+`) carry both labels — the dual role is explained in each row.
+Tools under [`tools/`](../tools/). A tool's capability is the interface
+it provides; a tool may carry more than one value (separated by `+`) when
+it implements multiple contracts (e.g. `tools/gmail` provides both
+`mail-source` and `mail-draft`).
| Tool | Capability / capabilities | Role |
|---|---|---|
| [`tools/agent-guard`](../tools/agent-guard/) | `substrate:action-guard` | Deterministic `PreToolUse` guard dispatcher: blocks `gh`/`git` commands that would ping maintainers, carry a `Co-Authored-By` trailer, mark-ready prematurely, leak security language publicly, or empty a PR via force-push. Extensible — skills contribute guards via `guards.d` |
| [`tools/agent-isolation`](../tools/agent-isolation/) | `substrate:sandbox` | Secure-agent sandbox helpers |
| [`tools/apache-projects`](../tools/apache-projects/) | `contract:project-metadata` | ASF project-metadata substrate (`apache/comdev` `apache-projects-mcp`); read-only `projects.apache.org/json` rosters / people / releases. Backs `contributor-nomination` and the security roster-resolution paths; tracked at `main`, not pinned |
-| [`tools/cve-org`](../tools/cve-org/) | `contract:cve-authority` | Publishes to CVE.org *(resolve)* and records the resulting CVE state back into the tracker *(intake)* |
+| [`tools/cve-org`](../tools/cve-org/) | `contract:cve-authority` | CVE.org services adapter: publishes records to CVE.org and reads back the resulting CVE state. Implements the `tools/cve-tool/` contract for the CVE.org-direct backend |
| [`tools/cve-tool`](../tools/cve-tool/) | `contract:cve-authority` | Adapter contract for CNA backends (Vulnogram, MITRE form, CVE.org direct, GHSA). Pure interface spec; no executable code — adapters under sibling `tools/cve-tool-*/` directories implement it. |
| [`tools/cve-tool-vulnogram`](../tools/cve-tool-vulnogram/) | `contract:cve-authority` | ASF Vulnogram CVE-allocation adapter. Implements the `tools/cve-tool/` contract. Previously named `tools/vulnogram/`. |
| [`tools/dashboard-generator`](../tools/dashboard-generator/) | `substrate:analytics` | Self-contained HTML dashboard generator |
@@ -237,11 +240,11 @@ Tools under [`tools/`](../tools/). Tools with two values (separated by
| [`tools/github`](../tools/github/) | `contract:tracker` | GitHub REST / GraphQL substrate (called by every lifecycle phase — pure substrate, no single phase) |
| [`tools/github-body-field`](../tools/github-body-field/) | `contract:tracker` | Read or rewrite one `### Field` section of a GitHub issue body without bringing the body into agent context — substrate helper for the security-sync skills |
| [`tools/github-rollup`](../tools/github-rollup/) | `contract:tracker` | Append to (or create) the status-rollup comment on a GitHub issue without bringing the rollup body into agent context — substrate helper for every status-update-emitting skill |
-| [`tools/gmail`](../tools/gmail/) | `contract:mail-draft` | Gmail API substrate |
+| [`tools/gmail`](../tools/gmail/) | `contract:mail-source` + `contract:mail-draft` | Gmail API substrate — inbound report intake (`mail-source`) plus outbound courtesy-reply drafting (`mail-draft`); read + draft only, never sends |
| [`tools/jira`](../tools/jira/) | `contract:tracker` | JIRA REST substrate (read-only today; write subcommands tracked in [#301](https://github.com/apache/magpie/issues/301)) |
| [`tools/mail-archive`](../tools/mail-archive/) | `contract:mail-archive` | Adapter contract for public mail-archive backends (PonyMail, Hyperkitty, Discourse, Google Groups, GitHub Discussions). Pure interface spec. |
-| [`tools/mail-source`](../tools/mail-source/) | `contract:mail-source` | Mail-source backend abstraction (mbox / IMAP / Mailman 3); the abstraction is setup, every concrete read is part of the intake pipeline |
-| [`tools/ponymail`](../tools/ponymail/) | `contract:mail-archive` | PonyMail archive substrate; same dual role as `mail-source` — substrate plus an intake-pipeline component |
+| [`tools/mail-source`](../tools/mail-source/) | `contract:mail-source` | Mail-source backend abstraction (mbox / IMAP / Mailman 3) feeding a uniform inbound thread/message view to the intake pipeline |
+| [`tools/ponymail`](../tools/ponymail/) | `contract:mail-archive` | PonyMail public mail-archive substrate (ASF `lists.apache.org`); implements the `tools/mail-archive/` contract |
| [`tools/scan-format`](../tools/scan-format/) | `contract:scan-format` | Adapter contract for security-scanner report formats (ASVS reference); reads a scan's finding index + per-finding evidence for the `security-issue-import-from-scan` pipeline. |
| [`tools/permission-audit`](../tools/permission-audit/) | `substrate:sandbox` | Audit + atomically edit Claude Code `permissions.allow[]` entries; backs `/magpie-setup verify --apply-permission-audit` (check 8d) |
| [`tools/pr-management-stats`](../tools/pr-management-stats/) | `substrate:analytics` | PR-backlog analytics engine |
@@ -251,7 +254,7 @@ Tools under [`tools/`](../tools/). Tools with two values (separated by
| [`tools/sandbox-lint`](../tools/sandbox-lint/) | `substrate:sandbox` | Sandbox settings linter |
| [`tools/security-tracker-stats-dashboard`](../tools/security-tracker-stats-dashboard/) | `substrate:analytics` | Security-tracker analytics engine |
| [`tools/spec-loop`](../tools/spec-loop/) | `substrate:framework-dev` | Spec-driven build loop runner (Ralph-style) for framework development |
-| [`tools/skill-evals`](../tools/skill-evals/) | `substrate:framework-dev` | Eval harness for skills; the harness is setup infrastructure, the run output is governance evidence |
+| [`tools/skill-evals`](../tools/skill-evals/) | `substrate:framework-dev` | Eval harness for skills; framework-dev infrastructure whose run output is governance evidence |
| [`tools/skill-and-tool-validator`](../tools/skill-and-tool-validator/) | `substrate:framework-dev` | Skill-frontmatter and convention validator |
| [`tools/spec-status-index`](../tools/spec-status-index/) | `substrate:framework-dev` | Index of spec / RFC implementation status — substrate that also doubles as a governance/stats view |
| [`tools/spec-validator`](../tools/spec-validator/) | `substrate:framework-dev` | Spec-frontmatter and body-section validator — counterpart to `skill-and-tool-validator` for `tools/spec-loop/specs/` |
@@ -263,7 +266,29 @@ happen to consume it (RFC-AI-0005). `tools/github` provides the
`contract:cve-authority`; `tools/privacy-llm` is `substrate:privacy`.
Use a `contract:<name>` value when the tool implements a capability
contract under `tools/<contract>/`, and a `substrate:<name>` value for
-framework substrate. A tool may carry more than one (rare).
+framework substrate. A tool may carry more than one (rare —
+`tools/gmail` is the only one today).
+
+## MCP servers, classified by capability
+
+Several tools wrap a [Model Context Protocol](https://modelcontextprotocol.io)
+(MCP) server as their concrete backend. An MCP server is **not** a
+separate axis — it is classified by the capability its *wrapping tool*
+provides; the MCP is just the transport, interchangeable with a CLI or
+REST backend behind the same contract. A skill never names an MCP
+server — it targets the capability, and the tool routes to whichever
+backend the adopter wired in. The framework consumes four:
+
+| MCP server | Tool prefix | Wrapped by | Capability provided | Organization |
+|---|---|---|---|---|
+| GitHub MCP | `mcp__github__*` | [`tools/github`](../tools/github/) | `contract:tracker` | — |
+| Gmail MCP (claude.ai) | `mcp__claude_ai_Gmail__*` | [`tools/gmail`](../tools/gmail/) | `contract:mail-source` + `contract:mail-draft` | — |
+| PonyMail MCP (`apache/comdev`) | `mcp__ponymail__*` | [`tools/ponymail`](../tools/ponymail/) | `contract:mail-archive` | ASF |
+| apache-projects MCP (`apache/comdev`) | `mcp__apache-projects__*` | [`tools/apache-projects`](../tools/apache-projects/) | `contract:project-metadata` | ASF |
+
+Non-MCP backends fulfil the same contracts: JIRA is reached over REST
+and `gh` is the CLI fallback, both `contract:tracker`. See
+[`docs/prerequisites.md`](prerequisites.md) for connection setup.
---
@@ -337,5 +362,5 @@ in security (`area:security` + `capability:triage`) become trivially
findable as a cohort even though they live in different families.
Capability is also a forcing function for skill design: if a new skill
-doesn't fit any of the nine buckets cleanly, that's a signal worth
-inspecting before the skill ships.
+doesn't fit any of the ten skill-capability buckets cleanly, that's a
+signal worth inspecting before the skill ships.
diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md
index 2310ae26..8d0751e7 100644
--- a/docs/vendor-neutrality.md
+++ b/docs/vendor-neutrality.md
@@ -154,7 +154,7 @@ with pluggable backends already include:
|---|---|
| [`tools/cve-tool`](../tools/cve-tool/) | CNA backends — Vulnogram, MITRE form, CVE.org direct, GHSA |
| [`tools/mail-archive`](../tools/mail-archive/) | PonyMail, Hyperkitty, Discourse, Google Groups, GitHub Discussions |
-| [`tools/mail-source`](../tools/mail-source/) | mbox, IMAP, Mailman 3 |
+| [`tools/mail-source`](../tools/mail-source/) | mbox, IMAP, Gmail API ([`tools/gmail`](../tools/gmail/)), Mailman 3 |
| [`tools/forwarder-relay`](../tools/forwarder-relay/) | ASF Security relay, huntr.com, HackerOne triagers |
| [`tools/scan-format`](../tools/scan-format/) | security-scanner report formats (ASVS reference) |
| [`tools/vcs`](../tools/vcs/) | Git (complete), Mercurial, Subversion, … (extension points) |
@@ -199,7 +199,7 @@ contract for one vendor:
|---|---|---|
| [`tools/cve-tool`](../tools/cve-tool/) | [`tools/cve-tool-vulnogram`](../tools/cve-tool-vulnogram/) (ASF) | MITRE form, CVE.org direct, GHSA |
| [`tools/mail-archive`](../tools/mail-archive/) | [`tools/ponymail`](../tools/ponymail/) (ASF) | Hyperkitty, Discourse, Google Groups, GitHub Discussions |
-| [`tools/mail-source`](../tools/mail-source/) | mbox, IMAP | Mailman 3 |
+| [`tools/mail-source`](../tools/mail-source/) | mbox, IMAP, Gmail API ([`tools/gmail`](../tools/gmail/)) | Mailman 3 |
| [`tools/forwarder-relay`](../tools/forwarder-relay/) | ASF-security ([`tools/gmail/asf-relay.md`](../tools/gmail/asf-relay.md)) | huntr.com, HackerOne |
| [`tools/scan-format`](../tools/scan-format/) | ASVS | other scanner formats |
| [`tools/vcs`](../tools/vcs/) | Git | Mercurial, Subversion, … |
diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md
index 5263f8ad..6b51ae8e 100644
--- a/skills/write-skill/SKILL.md
+++ b/skills/write-skill/SKILL.md
@@ -374,9 +374,9 @@ for the override → upstream loop.
lifecycle phases (e.g. `security-issue-fix` does
`capability:fix` + `capability:resolve`,
`setup-isolated-setup-doctor` does
- `capability:authoring` + `capability:reassess`), use the YAML list
+ `capability:platform` + `capability:reassess`), use the YAML list
form and list **all** that apply — do not collapse to one to be
- neat. If the skill doesn't fit any of the nine buckets at all,
+ neat. If the skill doesn't fit any of the ten buckets at all,
treat that as a design signal worth pausing for — either the
bucket set needs a new entry (raise an issue against
[`docs/labels-and-capabilities.md`](../../docs/labels-and-capabilities.md))
@@ -400,8 +400,9 @@ for the override → upstream loop.
conventions, placeholder convention, prompt-injection
absolute rule.
- [`docs/labels-and-capabilities.md`](../../docs/labels-and-capabilities.md)
- — the label taxonomy: `area:*` + `capability:*` dimensions, the
- nine capability buckets, the skill / tool → capability map, and
+ — the label taxonomy: `area:*` + the two capability axes, the
+ ten skill capabilities + tool capabilities, the skill / tool →
+ capability maps, and
the rule that every framework issue / PR / tool / skill / doc
declares its capability.
- [`docs/setup/agentic-overrides.md`](../../docs/setup/agentic-overrides.md)
diff --git a/tools/gmail/README.md b/tools/gmail/README.md
index d847ee65..ac770b16 100644
--- a/tools/gmail/README.md
+++ b/tools/gmail/README.md
@@ -12,9 +12,12 @@
# `tools/gmail/`
-**Capability:** contract:mail-draft
+**Capability:** contract:mail-source + contract:mail-draft
-Gmail API substrate. Read + draft-only — never sends. Used by the security-issue-import / sync / invalidate flows for inbound report intake and outbound courtesy-reply drafting. See [`tool.md`](tool.md) for the operation catalogue and the per-area files for ASF relay routing, draft backends, threading, search queries.
+Gmail API substrate. Read + draft-only — never sends. Provides two
+contracts: `mail-source` for inbound report intake (search / read a
+uniform thread/message view) and `mail-draft` for outbound courtesy-reply
+drafting. Used by the security-issue-import / sync / invalidate flows. See [`tool.md`](tool.md) for the operation catalogue and the per-area files for ASF relay routing, draft backends, threading, search queries.
## Prerequisites
diff --git a/tools/mail-source/README.md b/tools/mail-source/README.md
index 3e77b89d..e702628b 100644
--- a/tools/mail-source/README.md
+++ b/tools/mail-source/README.md
@@ -14,7 +14,7 @@
**Capability:** contract:mail-source
-Mail-source backend abstraction. Pluggable backends (mbox, IMAP, future Mailman 3 / Hyperkitty) that feed the security-issue-import intake pipeline a uniform thread/message view. See [`contract.md`](contract.md) for the backend interface.
+Mail-source backend abstraction. Pluggable backends (mbox, IMAP, the Gmail API via [`tools/gmail`](../gmail/), future Mailman 3 / Hyperkitty) that feed the security-issue-import intake pipeline a uniform thread/message view. See [`contract.md`](contract.md) for the backend interface.
## Prerequisites