potiuk opened a new pull request, #340:
URL: https://github.com/apache/airflow-steward/pull/340
## Summary
Introduces a `capability:*` label dimension orthogonal to the
existing `area:*` labels, makes it enforceable across the
framework, and adds a sync check that keeps the docs and the
source aligned.
`area:*` answers *what part of the framework does this touch?*;
`capability:*` answers *what kind of action does this perform?*.
A single query on `capability:triage` finds every triage-flow
issue across `area:pr-management` + `area:issue` + `area:security`
without enumerating per-area.
## What's in this PR
### Taxonomy
- **New doc** `docs/labels-and-capabilities.md` — canonical
reference: label-dimension definitions, 9 capability bucket
definitions, per-skill map for all 30 skills, per-tool map for
all 18 tools, the rule.
- **9 capability buckets**: `triage`, `review`, `fix`, `intake`,
`reconciliation` *(new — covers
[#337](https://github.com/apache/airflow-steward/issues/337)'s
ASF-dashboard step)*, `resolve`, `reassess`, `stats`, `setup`.
- **Multi-capability examples**: `security-issue-fix` =
`fix`+`resolve` *(opens the PR that closes the tracker)*;
`setup-isolated-setup-doctor` = `setup`+`reassess`; `cve-org` =
`resolve`+`intake`; `mail-source` / `ponymail` = `setup`+`intake`;
`skill-evals` / `spec-status-index` = `setup`+`stats`.
### Rule
`AGENTS.md` gains a new section that points at the canonical doc
and states the rule per artefact type: issues / PRs get
`area:*` + `capability:*`; new tools declare their capability in
the README first paragraph; new skills declare it in SKILL.md
frontmatter (single string or YAML list).
### Backfill
- **30 SKILL.md files** — `capability:` field added to every
existing skill's frontmatter via a one-shot script aligned with
the per-skill map in the doc. Dual-capability skills use the
YAML list form.
- **10 tool READMEs** — `**Capability:**` line added in-place.
- **8 new tool README stubs** — created for tools that previously
had no top-level README (`cve-org`, `dev`, `github`, `gmail`,
`mail-source`, `ponymail`, `privacy-llm`, `vulnogram`). Each
stub carries the capability line + a brief description that
points at existing internal docs.
### Validator (renamed `skill-validator` → `skill-and-tool-validator`)
The validator grew beyond skills, so the directory, Python module,
CLI entry point (`skill-validate` → `skill-and-tool-validate`),
and every cross-reference (`.asf.yaml`,
`.pre-commit-config.yaml`, `dependabot.yml`, `tests.yml`,
`CONTRIBUTING.md`, `write-skill`, `init_skill.py`) were renamed.
Three new checks, all HARD:
1. **Frontmatter capability** — `capability:` is now required;
accepts single-string or YAML-list form; rejects values outside
the 9-bucket taxonomy.
2. **Tool README + capability** — every `tools/<name>/` must have
a `README.md` with a `**Capability:** capability:NAME` line.
Multi-value form `**Capability:** capability:NAME + capability:NAME`
is supported.
3. **Capability sync** — compares the two tables in
`docs/labels-and-capabilities.md` against the live frontmatter +
tool README declarations, bidirectionally. Drift in either
direction is flagged. Italic-parenthetical future-state notes
(`*(+ capability:X once #N lands)*`) in the doc are stripped
before comparison.
### Prek hook
The `skill-and-tool-validate` hook trigger now fires on changes
to `tools/*/README.md` and `docs/labels-and-capabilities.md`, not
just skill files, so the sync check catches drift at commit time.
### Tests
12 new tests across `TestValidateFrontmatter`,
`TestValidateTools`, `TestValidateCapabilitySync`. Existing tests
updated to seed a minimal `docs/labels-and-capabilities.md` in the
test fixture (capability-sync is HARD and would otherwise fire
"missing doc" on every TestMain run). 218 tests green.
## Scope notes
- Adopter trackers are explicitly carved out — their label
schemes are per-project. The taxonomy applies to *this
framework repository* only.
- Pre-existing soft warnings on 4 unrelated skills
(`gh-list-no-limit`, `criteria-source`) are not from this PR
and remain as-is.
## Test plan
- [x] `uv run --project tools/skill-and-tool-validator
skill-and-tool-validate`
clean (4 pre-existing soft warnings on unrelated skills).
- [x] `pytest` clean (218 tests).
- [ ] Open the rendered doc on GitHub and spot-check table
alignment and link rendering.
- [ ] Sanity-check the prek hook firing on a sample doc change
in the next branch.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
