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/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 65802378 New skills (#492)
65802378 is described below
commit 65802378d99f37fd9265ed75bb24320fb62d97b8
Author: Justin Mclean <[email protected]>
AuthorDate: Fri Jun 12 02:57:50 2026 +1000
New skills (#492)
* Add release-management lifecycle spec and record skill-catalogue gaps
New cross-cutting spec release-management-lifecycle.md (proposed,
Drafting) grounds the 14-step, 10-skill family already designed in
docs/release-management/ but absent from the loop specs; wired into the
README and overview indexes.
Record Known gaps in the existing specs for the plan pass to pick up:
- mentoring-mode: family is one skill deep; first-contribution welcome
and contributor-to-committer path tracker undesigned.
- triage-mode: missing general-issue dedupe/stale/backlog-dashboard;
contributor-growth skills not a formalised family (PMC nomination,
emeritus, offboarding missing); repo-health audits a one-off.
- meta-and-quality-tooling: add optimize-skill; triage-mode: add
pr-management-quick-merge to Where it lives.
* Add project-agnosticism spec for de-ASF-coupling the skill catalogue
New cross-cutting spec project-agnosticism.md (experimental, infra)
captures the standing audit + mechanism for keeping skills usable outside
the ASF. Three generalisation mechanisms in preference order: placeholders
for values, adapters for system swaps, and capability/backend flags for
workflow branches that differ by ecosystem (the model already proven in
docs/release-management/). ASF stays the default profile, never the only
one.
Known gaps for the plan pass: no automated ASF-coupling lint, no non-ASF
adopter profile fixture/eval, and capability-flag vocabulary owed to
contributor intake (ICLA vs DCO), security intake, and CVE allocation.
Wired into the README/overview indexes and cross-referenced from
adapters.md.
* Plan: add ASF-coupling lint + non-ASF profile fixture work items
Plan pass under-covered the project-agnosticism spec. Add the two
buildable gaps as work items: ASF-coupling advisory lint folded into
skill-and-tool-validator (item 5) and a non-ASF adopter profile fixture
plus smoke eval (item 7). Reword the deferral note so only the
capability-flag vocabulary stays deferred (spec-authoring task following
the release-management backend-flag precedent), and add explicit
sequencing notes for the dedupe/backlog and repo-health gaps so later
plan passes do not silently drop them. Refresh the stale What's-been-built
spec list.
---
tools/spec-loop/IMPLEMENTATION_PLAN.md | 209 +++++++++++++++++----
tools/spec-loop/specs/README.md | 2 +
tools/spec-loop/specs/adapters.md | 4 +
tools/spec-loop/specs/mentoring-mode.md | 11 ++
tools/spec-loop/specs/meta-and-quality-tooling.md | 7 +-
tools/spec-loop/specs/overview.md | 2 +
tools/spec-loop/specs/project-agnosticism.md | 140 ++++++++++++++
.../specs/release-management-lifecycle.md | 136 ++++++++++++++
tools/spec-loop/specs/triage-mode.md | 26 ++-
9 files changed, 501 insertions(+), 36 deletions(-)
diff --git a/tools/spec-loop/IMPLEMENTATION_PLAN.md
b/tools/spec-loop/IMPLEMENTATION_PLAN.md
index 0b5de99c..8c955e80 100644
--- a/tools/spec-loop/IMPLEMENTATION_PLAN.md
+++ b/tools/spec-loop/IMPLEMENTATION_PLAN.md
@@ -19,7 +19,8 @@ one PR** (the branch-per-feature constraint).
- **Spec set** — [`specs/`](specs/): an `overview` plus a functional
spec per area (the four live modes, the security lifecycle, the
- privacy-LLM gate, the sandbox, CVE tooling, adoption/setup, adapters,
+ release-management lifecycle (proposed), the privacy-LLM gate, the
+ sandbox, CVE tooling, adoption/setup, adapters, project-agnosticism,
and meta/quality tooling).
- **Loop scaffolding** — `loop.sh` (plan / build / consolidate; a branch
per work item; never pushes), `PROMPT_plan.md`, `PROMPT_build.md`,
@@ -36,10 +37,10 @@ one PR** (the branch-per-feature constraint).
- **Contributor skills** — `contributor-nomination`,
`contributor-activity-sweep`, and `committer-onboarding` shipped with
eval suites. Formerly tracked under draft PRs #227–#229.
-- **Drafting — issue-fix-workflow skill** — `issue-fix-workflow` and
- `audit-finding-fix` shipped with eval suites (covers generic drafting
- from audit findings, formerly tracked as `generic-drafting` / #296).
- Spec: [`specs/drafting-mode.md`](specs/drafting-mode.md).
+- **Drafting — issue-fix-workflow and audit-finding-fix skills** —
+ both shipped with eval suites (covers generic drafting from triaged
+ issues and audit findings, formerly tracked as `generic-drafting` /
+ #296). Spec: [`specs/drafting-mode.md`](specs/drafting-mode.md).
- **Docs — mode economics page** — `docs/mode-economics.md` exists
(per-mode token-cost shape, vendor-neutral).
- **Meta — spec-status index** — `tools/spec-status-index/` exists as a
@@ -61,42 +62,156 @@ one PR** (the branch-per-feature constraint).
---
+## In-flight (local branches and open PRs — not available to build)
+
+The following items are already built on local branches or open as PRs.
+Do not duplicate them.
+
+| Branch slug | PR | Description |
+|---|---|---|
+| `injection-guard` | merged (#473) | Prompt-injection hardening on
forwarder-relay ingest |
+| `check-headers` | #474 | License-header enforcement check in spec-validator |
+| `spec-validator-known-gaps` | #490 | Enforce Known-gaps section in every
functional spec |
+| `spec-validate-hook` | #489 | pre-commit hook for spec-validate |
+| `skill-quality-fix` | #488 | Stabilise setup-verify eval + extend check-1
coverage |
+| `check-eval-coverage` | #481 | SOFT eval-coverage check (check #8) |
+| `eval-quick-merge` | #480 | pr-management-quick-merge skill + evals |
+| `spec-validator-path-check` | local | Validate paths referenced in
Validation blocks |
+| `spec-validator-spdx` | local | Enforce SPDX header on spec files |
+| `tracker-dashboard-tests` | local | pyproject + pytest suite for
security-tracker render.py |
+| `loop-imp` | #467 | Incremental update runs from .last-sync marker |
+| `loop-cli-ux` | #472 | Explicit loop.sh argument handling |
+| `node-bump-markdownlint` | local | Node 22.13→22.20 bump for markdownlint |
+| `token-reduction` | #479 | Slim AGENTS.md into a glossary |
+| `docs-modes-sync` | #483 | Sync modes.md skill inventory |
+| `docs-mentoring-sync` | #482 | Sync mentoring spec to experimental |
+| `eval-setup-status` | #484 | Fix setup-status eval prompts |
+
+---
+
## Work items (planned)
Priority order. Each maps to one branch and one PR. Branch names are
slugs, not numbers (numbering implies an order the specs don't carry).
-1. **Prompt-injection defence hardening.** Skills that ingest external
- content — issue bodies, PR descriptions, mail threads — are potential
- injection surfaces. Audit the highest-risk ingestion skills
- (`security-issue-import`, `security-issue-import-from-pr`,
- `security-issue-import-from-md`, `security-issue-import-via-forwarder`)
- and add explicit injection-resistance guidance (e.g. a
- `treat-as-data` framing block at the ingest boundary) or a validator
- rule in `tools/skill-and-tool-validator/` that flags missing
- data-boundary markers. Validation:
+1. **First release-management skill: release-vote-draft.**
+ `specs/release-management-lifecycle.md` is the only `proposed` spec
+ with zero implemented skills. The adopter contract templates
+ (`projects/_template/release-management-config.md`,
+ `release-build.md`, `pmc-roster.md`, `release-trains.md`,
+ `site-repo.md`) already exist. `release-vote-draft` is the most
+ standalone and highest-frequency PMC task: it takes RC metadata
+ (project name, version, RC number, artifact URLs) and produces a
+ VOTE email draft following ASF conventions. Include an eval suite
+ in `tools/skill-evals/evals/release-vote-draft/`.
+ Validation:
```bash
uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
- uv run --project tools/skill-evals skill-eval
tools/skill-evals/evals/security-issue-import/
+ uv run --project tools/skill-evals skill-eval
tools/skill-evals/evals/release-vote-draft/
```
- Spec:
[`specs/security-issue-lifecycle.md`](specs/security-issue-lifecycle.md)
- (import path);
[`specs/meta-and-quality-tooling.md`](specs/meta-and-quality-tooling.md)
- (validator surface).
- Branch `injection-guard`.
-
-2. **License-header enforcement.** Skills and tools must carry the
- Apache-2.0 SPDX header (`<!-- SPDX-License-Identifier: Apache-2.0 …
- -->` for Markdown; `# SPDX-License-Identifier: Apache-2.0` for
- Python) per repo-wide `AGENTS.md`. Add a check to
- `tools/skill-and-tool-validator/` that fails when a skill or tool
- source file is missing the header, so new contributions are caught at
- validation time rather than in code review. Validation:
+ Spec:
[`specs/release-management-lifecycle.md`](specs/release-management-lifecycle.md).
+ Branch `release-vote-draft`.
+
+2. **Second release-management skill: release-announce-draft.**
+ Companion to `release-vote-draft`. Takes a successful vote tally
+ (binding +1 count, RC metadata) and produces the ANNOUNCE email
+ draft for the ASF announce@ and dev@ lists, following ASF posting
+ conventions (subject: `[ANNOUNCE] Apache <Project> <Version>
+ released`). Also standalone: it does not depend on
+ `release-vote-draft` being run in the same session. Include an
+ eval suite.
+ Validation:
```bash
uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
+ uv run --project tools/skill-evals skill-eval
tools/skill-evals/evals/release-announce-draft/
+ ```
+ Spec:
[`specs/release-management-lifecycle.md`](specs/release-management-lifecycle.md).
+ Branch `release-announce-draft`.
+
+3. **Stale-issue sweep for general triage.**
+ `specs/triage-mode.md` Known Gaps explicitly names stale-handling
+ as missing from the general-issue side (the security side covers
+ this via `security-issue-sync`). Add a new skill
+ `issue-stale-sweep` that surfaces issues with no activity past a
+ configurable threshold and proposes closure or an update request
+ (waits for maintainer confirmation before posting). Include an eval
+ suite.
+ Validation:
+ ```bash
+ uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
+ uv run --project tools/skill-evals skill-eval
tools/skill-evals/evals/issue-stale-sweep/
+ ```
+ Spec: [`specs/triage-mode.md`](specs/triage-mode.md).
+ Branch `issue-stale-sweep`.
+
+4. **First-contribution welcome/orientation skill.**
+ `specs/mentoring-mode.md` Known Gaps names the "first-contribution
+ welcome/orientation skill" as missing. Add `mentoring-welcome`,
+ which greets first-time contributors on a newly opened issue or PR
+ with orientation context: contributing guide link, community norms,
+ expected next steps, and a pointer to the good-first-issue pool.
+ Waits for maintainer confirmation before posting. Include an eval
+ suite.
+ Validation:
+ ```bash
+ uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
+ uv run --project tools/skill-evals skill-eval
tools/skill-evals/evals/mentoring-welcome/
+ ```
+ Spec: [`specs/mentoring-mode.md`](specs/mentoring-mode.md).
+ Branch `mentoring-welcome`.
+
+5. **ASF-coupling advisory lint (fold into `skill-and-tool-validator`).**
+ `specs/project-agnosticism.md` Known Gaps names the absence of an
+ automated ASF-coupling check as its first gap. Add a new SOFT advisory
+ category to `tools/skill-and-tool-validator` that reuses the existing
+ walk, file allowlist, and inline `e.g.`/`example:` markers (the same
+ machinery as the placeholder check). It flags a curated, tiered set of
+ ASF-coupled tokens in skill bodies (high-confidence:
+ `svn (mv|commit|co)`, `[email protected]`, `dist/(dev|release)/`,
+ Vulnogram URLs; low-confidence: bare `PMC` / `ICLA` / `incubator`) and
+ tags each hit with a remedy class (placeholder / adapter /
+ capability-flag). SOFT only: surfaces on stderr, never fails the build.
+ Extend the validator tests with a coupled fixture and an allowlisted
+ fixture.
+ Validation:
+ ```bash
uv run --project tools/skill-and-tool-validator --group dev pytest
+ uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
+ ```
+ Spec: [`specs/project-agnosticism.md`](specs/project-agnosticism.md).
+ Branch `asf-coupling-lint`.
+
+6. **Sync drafting-mode spec Known Gaps to reflect shipped skills.**
+ `specs/drafting-mode.md` Known Gaps still says "Generic
+ (non-security, non-issue) Drafting from audit-tool findings is
+ `proposed`", but `audit-finding-fix` shipped with a full eval suite.
+ Update the Known Gaps section to reflect the current state and
+ remove the stale `proposed` claim so new plan passes do not
+ re-raise this as a gap.
+ Validation:
+ ```bash
+ uv run --project tools/spec-validator --group dev spec-validate
tools/spec-loop/specs/
+ uv run --project tools/spec-validator --group dev pytest
+ ```
+ Spec: [`specs/drafting-mode.md`](specs/drafting-mode.md).
+ Branch `drafting-spec-sync`.
+
+7. **Non-ASF adopter profile fixture + smoke eval.**
+ `specs/project-agnosticism.md` acceptance #3 requires that a non-ASF
+ profile can be declared without editing any skill body, but there is
+ no fixture to prove it. Add a worked non-ASF profile under
+ `projects/_template/` (non-ASF values for the existing placeholders
+ and any capability flags) plus a smoke eval that drives a
+ representative skill through it and asserts no skill-body edits are
+ needed. This turns acceptance #3 into a measurable gate. Pure
+ engineering, no policy decision required.
+ Validation:
+ ```bash
+ uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
+ uv run --project tools/skill-evals skill-eval
tools/skill-evals/evals/non-asf-profile-smoke/
```
- Spec:
[`specs/meta-and-quality-tooling.md`](specs/meta-and-quality-tooling.md).
- Branch `check-headers`.
+ Spec: [`specs/project-agnosticism.md`](specs/project-agnosticism.md).
+ Branch `non-asf-profile-fixture`.
---
@@ -111,7 +226,35 @@ slugs, not numbers (numbering implies an order the specs
don't carry).
it would skip the proof MISSION requires.
- When a build iteration creates a new skill, its eval suite is part of
that same work item — not a separate one.
-- **Next plan pass:** the `adapters.md` spec Known Gaps section was not
- fully read in this pass (only the first 40 lines were sampled). If
- both remaining work items are built before the next plan beat, reading
- `adapters.md` in full is the first step to identify additional items.
+- **Release-management family:** only the two most standalone skills
+ (`release-vote-draft`, `release-announce-draft`) are planned here.
+ The remaining eight (`release-prepare`, `release-keys-sync`,
+ `release-rc-cut`, `release-verify-rc`, `release-vote-tally`,
+ `release-promote`, `release-archive-sweep`, `release-audit-report`)
+ should be planned in subsequent passes once the first two establish
+ the skill-authoring patterns for this family.
+- **Triage contributor-growth gaps** (PMC-member nomination,
+ emeritus-committer handling, contributor offboarding) noted in
+ `triage-mode.md` Known Gaps are intentionally deferred: they are
+ vague enough that a spec-RFC conversation is more appropriate than
+ a direct build item.
+- **Project-agnosticism:** two of the three gaps in
+ `project-agnosticism.md` are buildable and planned now: the ASF-coupling
+ advisory lint (work item 5) and the non-ASF adopter profile fixture
+ (work item 7). The remaining gap, the capability-flag vocabulary for
+ contributor intake (ICLA vs DCO), security intake, and CVE allocation,
+ is deferred only until someone enumerates the option sets and defaults,
+ following the backend-flag precedent already set by
+ `release-management-lifecycle.md` (distribution / approval / announcement
+ backends). That is a spec-authoring task, not yet a build item.
+- **General-issue dedupe and backlog dashboard** (`triage-mode.md` Known
+ Gaps) are deferred behind `issue-stale-sweep` (work item 3): dedupe
+ overlaps the existing `security-issue-deduplicate` matching approach and
+ a backlog dashboard overlaps `pr-management-stats`, so both should reuse
+ those patterns once stale-sweep establishes the general-issue skill
+ shape. Not dropped, sequenced after item 3.
+- **Repo-health family** (`triage-mode.md` Known Gaps: the standalone
+ `ci-runner-audit` plus candidate siblings, GitHub Actions security
+ audit, dependency-update triage, license/NOTICE compliance, flaky-test
+ detection) is deferred pending a family spec; it is a multi-skill area
+ that wants its own spec before any build item.
diff --git a/tools/spec-loop/specs/README.md b/tools/spec-loop/specs/README.md
index fbef80d2..b6b852ee 100644
--- a/tools/spec-loop/specs/README.md
+++ b/tools/spec-loop/specs/README.md
@@ -31,11 +31,13 @@ Start with [`overview.md`](overview.md), then:
[`drafting-mode.md`](drafting-mode.md),
[`pairing-mode.md`](pairing-mode.md).
- Cross-cutting: [`security-issue-lifecycle.md`](security-issue-lifecycle.md),
+ [`release-management-lifecycle.md`](release-management-lifecycle.md),
[`privacy-llm-gate.md`](privacy-llm-gate.md),
[`agent-isolation-sandbox.md`](agent-isolation-sandbox.md),
[`cve-tooling.md`](cve-tooling.md),
[`adoption-and-setup.md`](adoption-and-setup.md),
[`adapters.md`](adapters.md),
+ [`project-agnosticism.md`](project-agnosticism.md),
[`meta-and-quality-tooling.md`](meta-and-quality-tooling.md),
[`security-reporting.md`](security-reporting.md).
diff --git a/tools/spec-loop/specs/adapters.md
b/tools/spec-loop/specs/adapters.md
index 2e2fc32d..744e5e41 100644
--- a/tools/spec-loop/specs/adapters.md
+++ b/tools/spec-loop/specs/adapters.md
@@ -82,3 +82,7 @@ done
- `experimental` overall — adapter coverage varies; a new adopter system
(e.g. GitLab, a different mail backend) is a gap the plan pass records.
+- Adapters cover the *system-swap* case; the broader audit of residual
+ ASF coupling across the catalogue, and the capability-flag mechanism for
+ workflow branches that no adapter resolves, live in
+ [project-agnosticism.md](project-agnosticism.md).
diff --git a/tools/spec-loop/specs/mentoring-mode.md
b/tools/spec-loop/specs/mentoring-mode.md
index 32939ad1..b5e5cffc 100644
--- a/tools/spec-loop/specs/mentoring-mode.md
+++ b/tools/spec-loop/specs/mentoring-mode.md
@@ -115,3 +115,14 @@ uv run --project tools/skill-evals skill-eval
tools/skill-evals/evals/good-first
and readiness thresholds may shift once real backlog candidates run
through it. The curation counterpart (relabeling the *existing* backlog
as good-first-issue candidates) is still unspecced.
+- **The family is one shipped skill deep against a core MISSION stream.**
+ Mentoring is named as one of the four day-to-day work streams, but only
+ `pr-management-mentor` ships (plus the Mentoring-flagged
+ `good-first-issue-author`). Two newcomer-facing capabilities are
+ designed nowhere yet: a *first-contribution welcome / orientation* skill
+ that greets a contributor's first issue or PR with project-convention
+ pointers and a clean hand-off, and a *contributor-to-committer path*
+ tracker that reads the nomination-evidence signals
+ `contributor-nomination` already gathers and surfaces when a contributor
+ is approaching readiness. Both are candidate work items for the plan
+ pass.
diff --git a/tools/spec-loop/specs/meta-and-quality-tooling.md
b/tools/spec-loop/specs/meta-and-quality-tooling.md
index a0c9b43e..9f4b0823 100644
--- a/tools/spec-loop/specs/meta-and-quality-tooling.md
+++ b/tools/spec-loop/specs/meta-and-quality-tooling.md
@@ -45,8 +45,11 @@ trustworthy as it grows.
- `tools/spec-validator/` — validates spec-loop spec frontmatter
(required keys, valid `status`/`kind`/`mode` values, body-section
presence); the spec-side counterpart to `skill-and-tool-validator`.
-- Skills: `write-skill` (author/update a skill), `list-skills`
- (live, generated index of every skill, grouped by family).
+- Skills: `write-skill` (author/update a skill), `optimize-skill`
+ (restructure an existing skill or sweep a set: split oversized
+ `SKILL.md`, lift project-specific values into placeholders, harden
+ prompt-injection defences), `list-skills` (live, generated index of
+ every skill, grouped by family).
## Behaviour & contract
diff --git a/tools/spec-loop/specs/overview.md
b/tools/spec-loop/specs/overview.md
index 294b2680..aebc581f 100644
--- a/tools/spec-loop/specs/overview.md
+++ b/tools/spec-loop/specs/overview.md
@@ -45,12 +45,14 @@ Each mode is an independently toggleable set of skills.
Maturity mirrors
| Area | Spec |
|---|---|
| Security-issue lifecycle (the load-bearing use case) |
[security-issue-lifecycle.md](security-issue-lifecycle.md) |
+| Release-management lifecycle (proposed, spec-first) |
[release-management-lifecycle.md](release-management-lifecycle.md) |
| Privacy-LLM gate + PII redaction |
[privacy-llm-gate.md](privacy-llm-gate.md) |
| Agent isolation / layered sandbox |
[agent-isolation-sandbox.md](agent-isolation-sandbox.md) |
| CVE tooling | [cve-tooling.md](cve-tooling.md) |
| Security reporting & dashboards |
[security-reporting.md](security-reporting.md) |
| Adoption & setup | [adoption-and-setup.md](adoption-and-setup.md) |
| Adapters (Gmail / PonyMail / Jira / GitHub / mail-source / forwarder-relay /
mail-archive / github-body-field / github-rollup) | [adapters.md](adapters.md) |
+| Project-agnosticism (de-ASF coupling) |
[project-agnosticism.md](project-agnosticism.md) |
| Meta & quality tooling |
[meta-and-quality-tooling.md](meta-and-quality-tooling.md) |
## The non-negotiables every area inherits
diff --git a/tools/spec-loop/specs/project-agnosticism.md
b/tools/spec-loop/specs/project-agnosticism.md
new file mode 100644
index 00000000..56452abb
--- /dev/null
+++ b/tools/spec-loop/specs/project-agnosticism.md
@@ -0,0 +1,140 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+---
+title: Project-agnosticism (de-ASF coupling)
+status: experimental
+kind: feature
+mode: infra
+source: >
+ MISSION.md § Abstract and § Affordability and vendor neutrality
+ ("'project' means both an ASF PMC and any non-ASF community, neither is
+ a second-class citizen"). README.md § Skill families. The placeholder +
+ adapter contract in adapters.md and adoption-and-setup.md, and the
+ backend-flag model proven in docs/release-management/ (distribution /
+ approval / announcement backends).
+acceptance:
+ - No shipped skill hardcodes an ASF-only assumption a non-ASF adopter
+ cannot satisfy; every ASF-specific surface is a placeholder, an
+ adapter backend, or a capability-flag branch with a documented
+ non-ASF path and a sensible default.
+ - Behavioural branches that differ by ecosystem (list vote vs
+ PR-approval, svn dist vs github-releases, ICLA vs DCO, mailing-list
+ intake vs GitHub discussion) are selected by a declared
+ `<project-config>` flag, not by editing the skill.
+ - The catalogue stays runnable by an ASF adopter unchanged: ASF is the
+ default profile, not a removed one.
+---
+
+# Project-agnosticism (de-ASF coupling)
+
+## What it does
+
+Keeps the skill catalogue usable by any open-source community, not just
+ASF projects, by ensuring every ASF-specific assumption lives behind one
+of three generalisation mechanisms rather than being baked into a skill.
+MISSION makes non-ASF adopters first-class; this area is the standing
+audit and the mechanism that holds that promise as the catalogue grows.
+
+The three mechanisms, in order of preference:
+
+1. **Placeholders** for project-specific *values* (`<tracker>`,
+ `<upstream>`, `<security-list>`, `<default-branch>`, …), resolved from
+ `<project-config>/`. This is the default and already widely used.
+2. **Adapters** for swapping the backing *system* a step talks to
+ (`tools/gmail`, `tools/ponymail`, `tools/jira`, `tools/github`,
+ `tools/mail-source`). See [adapters.md](adapters.md).
+3. **Capability / backend flags** for the harder case: a step whose
+ *workflow itself* differs by ecosystem. The adopter declares the
+ profile in `<project-config>` and the skill branches on it, keeping the
+ step sequence identical while only the emitted commands / wording
+ change. This is the "conditional flags" mechanism, already modelled in
+ `docs/release-management/` (`release_dist_backend`,
+ `release_approval_mechanism`, `release_announce_backend`).
+
+## Where it lives
+
+- The placeholder + config-resolution contract: `adapters.md`,
+ `adoption-and-setup.md`, and the adopter scaffold
+ `projects/_template/`.
+- The backend-flag precedent: `docs/release-management/README.md`
+ (§ adopter backends) and `projects/_template/release-management-config.md`.
+- The skills carrying residual ASF coupling to audit, by family:
+ - **security**: `security@`-style intake and the ASF security-team
+ relay (`security-issue-import-via-forwarder`), CVE allocation assuming
+ an ASF CNA (`security-cve-allocate`), Vulnogram as the CVE tool.
+ - **contributor / committer growth**: `committer-onboarding`
+ (ICLA gate, PMC vote semantics, `dev@` announce),
+ `contributor-nomination` (committer-vs-PMC roster framing).
+ - **release-management** (proposed): the whole ASF release ritual,
+ already designed with backend flags; the audit confirms the non-ASF
+ paths stay first-class as the skills land.
+ - any skill whose prose names `apache.org` lists, `svn` dist trees,
+ `incubator`, or ASF-only governance steps without a flag.
+
+## Behaviour & contract
+
+- **ASF is the default profile, never the only one.** Generalising a
+ skill must not regress the ASF path; the ASF behaviour becomes the
+ default value of the new flag / adapter, so an ASF adopter sees no
+ change.
+- **Prefer the lightest mechanism.** A value goes in a placeholder; a
+ system swap goes in an adapter; only a genuine workflow fork gets a
+ capability flag. Do not add a flag where a placeholder suffices.
+- **Every flag has a documented non-ASF path.** A capability flag that
+ only enumerates ASF options (e.g. an approval mechanism with just
+ `dev-list-vote`) is incomplete; it must name at least one non-ASF
+ option (`pr-approval`, `maintainer-roster`, `github-discussion`, …) and
+ describe the adopter-facing default.
+- **Advisory, not paternalistic.** The audit surfaces candidate coupling
+ for a maintainer to judge; some ASF strings are legitimate (examples,
+ the ASF default profile, ASF-specific docs). It does not auto-rewrite.
+
+## Out of scope
+
+- Removing or de-prioritising ASF support: ASF is the reference adopter
+ and the default profile.
+- The privacy gate and sandbox ([privacy-llm-gate.md](privacy-llm-gate.md),
+ [agent-isolation-sandbox.md](agent-isolation-sandbox.md)), which are
+ already project-agnostic.
+- The runtime adapter implementations themselves (that is
+ [adapters.md](adapters.md)); this area governs the *coupling audit* and
+ the *flag contract*, not the adapter code.
+
+## Acceptance criteria
+
+1. Every shipped skill is auditable for ASF coupling, and each residual
+ coupling is a placeholder, an adapter backend, or a capability-flag
+ branch with a non-ASF default.
+2. Ecosystem-divergent workflow steps branch on a declared
+ `<project-config>` flag, not on skill edits.
+3. The ASF profile runs the catalogue unchanged (default-valued flags),
+ and a non-ASF profile can be declared without editing any skill body.
+
+## Validation
+
+```bash
+# Advisory sweep: surface ASF-coupled tokens in skill bodies that should
+# be a placeholder, an adapter backend, or a capability-flag branch.
+# Expected to flag legitimate ASF-default examples too; a human judges.
+grep -rInE 'apache\.org|[[:alpha:]]+@apache|\bdev@|\bannounce@|\bICLA\b|\bsvn
(mv|co|commit)|\bincubator\b|Vulnogram' skills/ \
+ | grep -vE '<[a-z-]+>' | head -40
+uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
+```
+
+## Known gaps
+
+- **No automated ASF-coupling lint exists.** The sweep above is a manual
+ grep; a deterministic advisory check (analogous to the
+ `skill-and-tool-validator` warnings, with an allowlist for legitimate
+ ASF-default strings) is a candidate work item.
+- **No non-ASF adopter profile fixture exists** to run the catalogue
+ against. A `projects/_template` non-ASF profile plus a smoke eval that
+ drives a representative skill through it would turn acceptance #3 into a
+ measurable gate.
+- **The capability-flag vocabulary is defined only for
+ release-management.** The same backend-flag treatment is still owed to:
+ contributor intake (ICLA vs DCO vs none), security intake
+ (`security@`-list + ASF-team relay vs a project's own private intake),
+ and CVE allocation (ASF CNA vs adopter CNA vs no-CVE). Each is a
+ candidate work item for the plan pass.
diff --git a/tools/spec-loop/specs/release-management-lifecycle.md
b/tools/spec-loop/specs/release-management-lifecycle.md
new file mode 100644
index 00000000..7c4609e2
--- /dev/null
+++ b/tools/spec-loop/specs/release-management-lifecycle.md
@@ -0,0 +1,136 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+---
+title: Release-management lifecycle (end-to-end)
+status: proposed
+kind: feature
+mode: Drafting
+source: >
+ MISSION.md § Initial Goals ("cut a first Apache release through the
+ standard process within 3 months of resolution adoption"). README.md
+ § Skill families (release-management, proposed). Designed spec-first in
+ docs/release-management/ (README.md, process.md, spec.md) plus the
+ adopter scaffold projects/_template/release-management-config.md. No
+ release-* skill code exists yet.
+acceptance:
+ - The family's design (14-step process, per-skill state-change
+ boundaries, adopter contract) is reviewable independently of any
+ runtime skill; it already is, in docs/release-management/.
+ - Each release-* skill, when it lands, ships flagged `experimental` and
+ carries `mode: Drafting` or `mode: Triage` per the skill table.
+ - The agent never holds, invokes, or proxies the Release Manager's
+ signing key, and never publishes the release; steps 3, 4, 10, 11 emit
+ paste-ready recipes the human executes as themselves.
+---
+
+# Release-management lifecycle
+
+## What it does
+
+End-to-end automation for an ASF project's release lifecycle, from the
+planning issue and version bump through to `[ANNOUNCE]` on
+`[email protected]`, the archive sweep, and the per-release audit log.
+Ten skills compose into the canonical 14-step process. The procedural
+shape is foundation-wide; project-specific content (release-train
+identity, build invocation, `KEYS` path, vote-window length, retention
+rule, audit-log location) plugs in through `<project-config>/`, exactly
+as the security family does. Non-ASF adopters are first-class: the
+distribution backend, approval mechanism, and announcement backend each
+parametrise the lifecycle without baking in an ASF assumption.
+
+This is the load-bearing parallel to the security-issue lifecycle: a
+multi-skill, high-procedure ASF-process family with shared
+state-change-boundary discipline, designed docs-first before any skill
+code lands.
+
+## Where it lives
+
+- Design docs (present today): `docs/release-management/README.md`
+ (family overview + skill table), `docs/release-management/process.md`
+ (14-step lifecycle, Mermaid flow, label reference),
+ `docs/release-management/spec.md` (per-skill scope and state-change
+ boundary).
+- Adopter contract: `projects/_template/release-management-config.md`,
+ `projects/_template/release-build.md`, `projects/_template/pmc-roster.md`,
+ `projects/_template/site-repo.md`, and the shared
+ `projects/_template/release-trains.md`.
+- Skills (all `proposed`, none implemented yet): `release-prepare`,
+ `release-keys-sync`, `release-rc-cut`, `release-verify-rc`,
+ `release-vote-draft`, `release-vote-tally`, `release-promote`,
+ `release-announce-draft`, `release-archive-sweep`,
+ `release-audit-report`.
+- Adapters it will read/draft through: `tools/github`, `tools/ponymail`
+ (vote threads), `tools/gmail` (announce/vote drafts), plus the project's
+ `svn` dist tree as a distribution backend.
+
+## Behaviour & contract
+
+- **The agent never holds the signing key.** Steps 3 (`KEYS`), 4 (RC tag,
+ sign, checksums, `svn` import to `dist/dev/<project>/`), and 10
+ (`svn mv dist/dev → dist/release`) emit paste-ready command recipes; the
+ Release Manager runs every signing and `svn commit` operation as
+ themselves. Mirrors `security-cve-allocate` (Vulnogram URL + paste-ready
+ JSON, human submits).
+- **The agent never publishes the release.** Step 10 (promotion) and step
+ 11 (`[ANNOUNCE]` send + site-bump merge) are the moments of release; the
+ agent drafts artefacts, the RM and PMC execute and merge.
+- **Drafts, never sends.** `[VOTE]` (step 7) and `[ANNOUNCE]` (step 11)
+ email bodies are drafted to the maintainer's outbox; no skill calls a
+ send.
+- **Conservative tally.** `release-vote-tally` classifies +1/0/-1 binding
+ vs non-binding against the PMC roster and refuses to count ambiguous
+ votes, flagging `AMBIGUOUS, needs RM call` rather than guessing.
+- **Read-only verification.** `release-verify-rc` (signatures, checksums,
+ RAT license headers, NOTICE/LICENSE, prohibited binaries, version
+ consistency) and `release-audit-report` make no state change; voters can
+ run verification in their own dev loop before posting `+1`.
+- **Promotion gated on health evidence, not throughput.** Moving any
+ release-* skill from `experimental` to default-on, or from Drafting to a
+ state-changing lane, requires evidence from Release Managers and binding
+ voters that the process is healthier (fewer stalled RCs, shorter
+ time-to-`[ANNOUNCE]`, fewer reverted promotions).
+
+## Out of scope
+
+- Holding, invoking, or proxying the RM's private signing key.
+- Publishing the release: the `svn mv` promotion, the `[ANNOUNCE]` send,
+ and the site-bump merge are human acts.
+- A new mode. Release-management is a family spanning the existing Triage
+ and Drafting modes; it introduces no new mode.
+
+## Acceptance criteria
+
+1. The 14-step process, per-skill state-change boundaries, and adopter
+ contract are reviewable from `docs/release-management/` without any
+ skill code (they are today).
+2. Each `release-*` skill, as it lands, validates under
+ `skill-and-tool-validate`, ships `experimental`, and carries the
+ `mode` its skill-table row assigns.
+3. No skill in the family signs, imports, promotes, sends, or merges on
+ autopilot; the key-holding and publishing steps emit paste-ready
+ recipes only.
+
+## Validation
+
+```bash
+test -f docs/release-management/spec.md
+test -f docs/release-management/process.md
+test -f projects/_template/release-management-config.md
+uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-validate
+```
+
+## Known gaps
+
+- **No `release-*` skill code exists yet.** The family is `proposed`,
+ designed docs-first (mirroring Mentoring). All ten skills land in
+ follow-up PRs, each flagged `experimental`. The plan pass turns each
+ un-implemented skill in the `docs/release-management/` table into a work
+ item.
+- **No eval suites exist** under `tools/skill-evals/evals/release-*/`;
+ each skill needs one per the per-skill-eval convention before it can
+ graduate from `experimental`.
+- **Health-evidence promotion criteria are unmeasured.** No adopter has
+ cut a release through the family yet, so the RM/binding-voter evidence
+ window that would justify default-on or a state-changing lane has no
+ data behind it.
diff --git a/tools/spec-loop/specs/triage-mode.md
b/tools/spec-loop/specs/triage-mode.md
index 1c469993..41f1027a 100644
--- a/tools/spec-loop/specs/triage-mode.md
+++ b/tools/spec-loop/specs/triage-mode.md
@@ -30,7 +30,9 @@ suggestion the human signs off on.
## Where it lives
- PR queue: `pr-management-triage`, `pr-management-stats`,
- `pr-management-code-review` (deep review is a triage variant).
+ `pr-management-code-review` (deep review is a triage variant),
+ `pr-management-quick-merge` (read-only express-lane surfacing of
+ trivial, low-risk PRs a maintainer can review in seconds).
Reference implementation: `tools/pr-management-stats/`.
- General issues: `issue-triage`, `issue-reassess`, `issue-reproducer`.
Companion reporting skill: `issue-reassess-stats` (read-only dashboard
@@ -78,3 +80,25 @@ uv run --project tools/skill-and-tool-validator --group dev
skill-and-tool-valid
- PR and general-issue triage are `experimental` — no adopter-pilot eval
has run; behaviour may change.
+- **General-issue triage lacks the dedupe, stale-handling, and
+ backlog-dashboard coverage the security side already has.** There is
+ no general-issue deduplication skill (only `security-issue-deduplicate`
+ exists), no stale-issue management (nudge, then propose-close after a
+ warning window), and no general open-issue backlog dashboard
+ (`pr-management-stats` covers PRs; `issue-reassess-stats` only covers
+ reassess-campaign `verdict.json` output). Each is a candidate work item.
+- **The contributor-growth skills are not yet a formalised family.**
+ `contributor-nomination`, `contributor-activity-sweep`,
+ `committer-onboarding`, and `good-first-issue-author` (Mentoring) span
+ the contributor-to-committer path but are catalogued ad hoc;
+ `contributor-activity-sweep` and `committer-onboarding` are not yet
+ referenced by any spec. Missing members of that path: PMC-member
+ nomination (distinct from committer), emeritus / inactive-committer
+ handling, and contributor offboarding. Worth deciding whether this
+ becomes a named family.
+- **Repo-health audits are a one-off with no family around them.**
+ `ci-runner-audit` is a standalone read-only audit (obsolete runner
+ labels, macOS arch mismatches) with no sibling skills. A repo-health
+ family is a candidate: GitHub Actions workflow security audit (the repo
+ already runs `zizmor` in pre-commit), dependency-update triage,
+ license / NOTICE compliance, and flaky-test detection.
