docs(taxonomy): fix relabel collateral from the capability split#645
Merged
Conversation
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)
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)
HarshMehta112
pushed a commit
to HarshMehta112/magpie
that referenced
this pull request
Jun 29, 2026
Resolve docs/labels-and-capabilities.md conflict: adopt the new contract:/substrate: tool-capability taxonomy from apache#641/apache#645 and relabel the tools/asf-svn row to contract:source-control. Update tools/asf-svn README to the new taxonomy and add the Organization: ASF declaration.
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.
Follow-up to #641 addressing @justinmclean's review
(#641 (comment))
plus a deep review of the capability-axis split. None of these are
caught by the validator — they live in skill/doc bodies, not frontmatter
or the machine-checked capability maps.
Flagged in review
write-skillworked example saidsetup-isolated-setup-doctordoescapability:authoring+capability:reassess. Wrong:authoringis reserved for skills thatauthor other skills (
write-skill,optimize-skill); thesetup-doctor is a platform skill. A bad
setup→authoringreplacement where it should have been
setup→platform. Fixed tocapability:platform+capability:reassess, matching itsfrontmatter.
capabilities; fixed the three untouched references
(
docs/labels-and-capabilities.md+ two inwrite-skill).Found in the deep review
The Capability to tool map still stamped skill-lifecycle phases on
tools — the model RFC-AI-0005 abolishes for the tool axis ("a
lifecycle phase is the wrong model for a tool"). Rewrote each to
describe the interface the tool provides:
cve-orgcarried*(resolve)*/*(intake)*phase tags.mail-sourcesaid "the abstraction is setup".ponymaildescribed the removed "dual role / intake-pipelinecomponent".
skill-evalssaid "setup infrastructure".gmail declares both mail contracts
gmail does inbound report intake and outbound courtesy-reply drafting,
so it provides two contracts, not one. Now declares
contract:mail-source+contract:mail-draft, threaded through bothdirections for consistency:
tools/gmailREADME capability line + role text.one tool carrying two values today).
tools/mail-sourceREADME and bothdocs/vendor-neutrality.mdbackend rosters now list the Gmail API as a
mail-sourcebackend.MCP servers classified by capability
New section in
docs/labels-and-capabilities.mdclassifying the four MCPservers the framework's tools consume — each by the capability its
wrapping tool provides. An MCP is a transport behind a contract, not a
separate axis; a skill never names one.
tools/githubcontract:trackertools/gmailcontract:mail-source+contract:mail-draftapache/comdev)tools/ponymailcontract:mail-archiveapache/comdev)tools/apache-projectscontract:project-metadataJIRA (REST) and
gh(CLI) are noted as non-MCPcontract:trackerbackends.
Verification
skill-and-tool-validategreen (capability-sync matches the dualgmail label).
capability:setupin prose,authoringscopedto
write-skill/optimize-skillonly, everysetup-*skill resolvedto
platform.🤖 Generated with Claude Code