From 5c69c05804d699526a3d1117717ac9b57693df9f Mon Sep 17 00:00:00 2001 From: Justin McLean Date: Thu, 11 Jun 2026 02:24:53 +0000 Subject: [PATCH 1/3] 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. --- tools/spec-loop/specs/README.md | 1 + tools/spec-loop/specs/mentoring-mode.md | 11 ++ .../specs/meta-and-quality-tooling.md | 7 +- tools/spec-loop/specs/overview.md | 1 + .../specs/release-management-lifecycle.md | 136 ++++++++++++++++++ tools/spec-loop/specs/triage-mode.md | 26 +++- 6 files changed, 179 insertions(+), 3 deletions(-) create mode 100644 tools/spec-loop/specs/release-management-lifecycle.md diff --git a/tools/spec-loop/specs/README.md b/tools/spec-loop/specs/README.md index fbef80d2..05bc0446 100644 --- a/tools/spec-loop/specs/README.md +++ b/tools/spec-loop/specs/README.md @@ -31,6 +31,7 @@ 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), 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..2deb477e 100644 --- a/tools/spec-loop/specs/overview.md +++ b/tools/spec-loop/specs/overview.md @@ -45,6 +45,7 @@ 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) | 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 @@ + + +--- +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 +`announce@apache.org`, 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 `/`, 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//`), 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. From 87c768bd8a008639930bc13d9bdd901d3132ebad Mon Sep 17 00:00:00 2001 From: Justin McLean Date: Thu, 11 Jun 2026 02:39:36 +0000 Subject: [PATCH 2/3] 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. --- tools/spec-loop/specs/README.md | 1 + tools/spec-loop/specs/adapters.md | 4 + tools/spec-loop/specs/overview.md | 1 + tools/spec-loop/specs/project-agnosticism.md | 140 +++++++++++++++++++ 4 files changed, 146 insertions(+) create mode 100644 tools/spec-loop/specs/project-agnosticism.md diff --git a/tools/spec-loop/specs/README.md b/tools/spec-loop/specs/README.md index 05bc0446..b6b852ee 100644 --- a/tools/spec-loop/specs/README.md +++ b/tools/spec-loop/specs/README.md @@ -37,6 +37,7 @@ Start with [`overview.md`](overview.md), then: [`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/overview.md b/tools/spec-loop/specs/overview.md index 2deb477e..aebc581f 100644 --- a/tools/spec-loop/specs/overview.md +++ b/tools/spec-loop/specs/overview.md @@ -52,6 +52,7 @@ Each mode is an independently toggleable set of skills. Maturity mirrors | 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 @@ + + +--- +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 + `` 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* (``, + ``, ``, ``, …), resolved from + `/`. 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 `` 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 + `` 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. From 35c7e8b175a865950eecd6b3f46b2c4adaea47fe Mon Sep 17 00:00:00 2001 From: Justin McLean Date: Thu, 11 Jun 2026 02:49:23 +0000 Subject: [PATCH 3/3] 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 +++++++++++++++++++++---- 1 file changed, 176 insertions(+), 33 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 (`` 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 + 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)`, `announce@apache.org`, `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.