feat(release-manager-handoff): explicit hand-off + publication-ready comments by potiuk · Pull Request #10 · apache/magpie

potiuk · 2026-04-29T11:19:30Z

Summary

Adds two new first-class comments the sync-security-issue skill posts
on the tracker as the issue moves through the release-manager half of
the lifecycle (Steps 12-15), instead of folding the call-to-action into
the catch-all status rollup.

The rollup is the security team's audit trail and accumulates many
small entries collapsed into <details> blocks; the RM-facing
comments are one-shot orientation surfaces with their own dated
context and working @-mention notifications. A drive-by RM should be
able to drive Steps 13-15 from two comments on the issue page without
consulting the rollup or external docs.

What's added

Comment 1 — Release-manager hand-off (Step 12 trigger)

Fires exactly once at the pr merged → fix released swap. Walks
the RM through Steps 13-15 end-to-end with a numbered checklist:
first paste → REVIEW → (rare conditional re-paste after CNA reviewer
comments) → READY → email preview on the #email tab (new
load-bearing checkpoint, see below) → send advisory → wait for
publication-ready notification → second paste → PUBLIC → close.

Template body: tools/vulnogram/release-manager-handoff-comment.md.
Idempotent via the marker 
on line 1.

Comment 2 — Publication-ready notification (Step 14 trigger)

Fires exactly once when the Public advisory URL body field is
populated by sync (the existing Step 14 transition). Tells the RM
the URL has been captured, the JSON has been regenerated to include
it as a vendor-advisory reference, and the final paste + READY
→ PUBLIC + close is now unblocked.

Template body: tools/vulnogram/release-manager-publication-comment.md.
Idempotent via .

Architectural split (tool-specific vs generic)

The user's request was "do it in the way that 'tool' specific part is
done in the tool part in apache-steward submodule and generic workflow
is explained in generic part of it". Concretely:

Concern	Lives in
Vulnogram state machine (`DRAFT` / `REVIEW` / `READY` / `PUBLIC`) + paste flow + `#email` preview tab	`tools/vulnogram/record.md`
Vulnogram-specific RM checklist (the standalone authoritative recipe)	`tools/vulnogram/record.md` — Release-manager checklist
Comment template bodies (parameterised)	`tools/vulnogram/release-manager-handoff-comment.md`, `release-manager-publication-comment.md`
When/why each comment fires, idempotency contract, placeholder substitution rules, apply mechanic	`.claude/skills/sync-security-issue/SKILL.md` (Step 2b + Step 4)
RM-perspective lifecycle narrative	`README.md` — Steps 12-15

The skill loads the comment template by resolving
tools/<cve-tool>/release-manager-{handoff,publication}-comment.md
based on the project's cve_tool setting in <project-config>/project.md,
so a project that swaps Vulnogram for a different CVE tool only needs
to provide its own template files (no skill changes).

Other lifecycle clarifications

READY state added to tools/vulnogram/record.md.
The framework README.md always referenced it but the tool doc only
documented DRAFT / REVIEW / PUBLIC.
#email tab documented as a load-bearing email-preview
checkpoint before the advisory-send step. Fixes a real footgun:
the JSON view doesn't surface formatting issues (truncation, broken
markdown, missing patch links) that the rendered email does.
Step 4 close recipe updated to always follow gh issue close
with an archiveProjectV2Item mutation on every close (terminal
or non-terminal), per the new
Archive a board item recipe
in tools/github/project-board.md. Idempotent on already-archived
items.

Deliberately unchanged

No comment fires at cve allocated. The hand-off comment
deliberately fires only after the release ships — the user-facing
flow before that is well-served by existing rollup status entries
and would lose context by the time the release manager actually
needs the call-to-action.
No skill behaviour change for the validity / fix flow (Steps
1-11). This is purely a downstream-of-release-ship enhancement.

Test plan

prek run --files <touched> passes (doctoc, eof, mixed-line-
endings, trailing whitespace).
Apply the hand-off comment template to a real tracker (#257
on airflow-s/airflow-s is at the fix released step right now)
via the substituted template, verify rendering on github.com,
verify the @-mention to @shahar1 resolves.
Apply the publication-ready notification template to #293
on airflow-s/airflow-s (already at announced, so this is a
catch-up post for the RM who advanced the tracker before the
framework feature existed).
Once a future tracker organically transitions through Steps
12 / 14 with this skill version live, verify both comments fire
at the right moments and that subsequent sync runs respect the
idempotency markers.

🤖 Generated with Claude Code

…comments Adds two new first-class comments the sync-security-issue skill posts on the tracker as the issue moves through the release-manager half of the lifecycle (Steps 12-15), instead of folding the call-to-action into the catch-all status rollup. The rollup is the security team's audit trail and accumulates many small entries; the RM-facing comments are one-shot orientation surfaces with their own dated context and working @-mention notifications. Comment 1 — Release-manager hand-off (Step 12 trigger). Fires exactly once at the `pr merged` -> `fix released` swap, walks the RM through Steps 13-15 end-to-end without forcing them to consult external docs. Lives in tools/<cve-tool>/release-manager-handoff-comment.md as a parameterised template; sync substitutes CVE_ID, RM_HANDLE, the Vulnogram #source / #email tab URLs, the embedded-JSON anchor, the public archive scan URL, and absolute github.com URLs into the framework. Idempotent via an HTML marker on line 1. Comment 2 — Publication-ready notification (Step 14 trigger). Fires exactly once when the *Public advisory URL* body field is populated and the CVE JSON has been regenerated to include the archive URL. Tells the RM the final paste + READY -> PUBLIC + close is now unblocked. Tool-specific Vulnogram details (record state machine, paste flow, email-preview tab) live under tools/vulnogram/; generic workflow (when each comment fires, idempotency, apply mechanic) lives in the sync skill spec and the framework README. Other lifecycle clarifications: - READY state added to tools/vulnogram/record.md (between REVIEW and PUBLIC); the README always referenced it but the tool doc didn't. - Vulnogram #email tab documented as a load-bearing email-preview checkpoint before the advisory-send step. - Step 4 close recipe updated to follow `gh issue close` with an `archiveProjectV2Item` mutation on every close (terminal or non-terminal); the recipe lives in tools/github/project-board.md ("Archive a board item — terminal-state cleanup"), idempotent on already-archived items. No changes to the existing skill behaviour at `cve allocated` — the hand-off comment deliberately fires only after release ships (the user-facing flow before that is handled by existing rollup status entries). Generated-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

potiuk · 2026-04-29T11:20:53Z

cc: @shahar1 @raboof

Fifth and final PR of the security genericization series. Lifts the remaining 4 docs in docs/security/ to read config knobs from projects/_template/project.md and the contract docs from PR1-PR4 (cve_authority.*, governance.*, security_inbox.*, forwarders.*, archive_system.*, scope_detection.*). Plus a final scrub of 4 skills for leftover ASF/Vulnogram literals. Byte-equivalent for the airflow-s adopter: every ASF/Airflow/ Vulnogram-specific value either resolves through a config knob whose ASF default matches today's behaviour, OR stays as one named-example aside in generic prose. Per-target lifts: - docs/security/threat-model.md (+107/-77) — Purpose/Scope/ Assumptions reframed from "ASF"/"PMC" to governance-knob terms. STRIDE matrix rows A.6/A.7/C.1-C.4/E.1-E.2 lifted: Vulnogram -> <cve-tool>; security@apache.org -> <security-list>; DRAFT/REVIEW/READY/PUBLIC -> cve_authority.states sequence (allocated -> review-ready -> publish-ready -> public). Mitigations M.10/M.16/M.18/M.19/M.27 + residual risks #3/#8/#10/#11 + re-audit cadence ownership generalised. - docs/security/forwarder-routing-policy.md (+42/-27) — references the optional security-issue-import-via-forwarder sub-skill from PR3 (#387) and the tools/forwarder-relay/README.md contract. Replaces "ASF-security relay" / "security@apache.org" with forwarders.enabled / <security-list> / foundation_security_address. ASF-Airflow shown as a named-example aside per concept. - docs/security/how-to-fix-a-security-issue.md (+20/-8) — "governance-authorised member of the adopting project (per governance.cve_allocation_gate)" replaces "PMC member of apache/airflow"; <cve-tool> + cve_authority.* replaces Vulnogram- specific URLs and state names; archive_system.advisory_publication_signal_url replaces the lists.apache.org users-list URL. - docs/security/new-members-onboarding.md (+26/-13) — onboarding- style register preserved. "PMC members and committers" reframed as "governance body that satisfies governance.cve_allocation_gate"; per-user-config "PMC status" steps reference the governance knob; Vulnogram steps reference <cve-tool> via cve_authority.record_url_template. - Final scrub of 4 skills (+17/-15 net): security-issue-import, security-issue-import-via-forwarder, security-issue-invalidate, security-issue-fix — leftover literal references caught and lifted to roster.bare_name_handles / governance.escalation_contact / forwarders.<adapter>.contact_handle. Aggregate: 8 files, +240/-156 lines. That closes the series. Five PRs (#381, #386, #387, #388, this) transitioned the security skill family from Airflow/ASF-coupled to a generic framework with ASF as the default-configured option. The airflow-s adopter, with the ASF defaults baked into project.md, sees byte-equivalent behaviour throughout. Non-ASF adopters override specific dimensions (CVE authority, mail provider, archive system, governance gate, scope axis) by changing only their <project-config>/ files. Generated-by: Claude Code (Opus 4.7)

… known gap Add the missing [dependency-groups] dev section to tools/skill-and-tool-validator/pyproject.toml so that the spec's validation command (uv run --project ... --group dev pytest) works. The validate_asf_coupling check (SOFT check apache#10), its patterns, and the full TestValidateAsfCoupling test class were already present in the source; 258 tests pass, and skill-and-tool-validate surfaces 86 advisory asf-coupling warnings on the live repo with no hard failures. Update specs/project-agnosticism.md Known-gaps to replace "No automated ASF-coupling lint exists" with the current state: the lint is live and advisory, and the remaining work is acting on the flagged coupling hits. Generated-by: Claude (Opus 4.7)

… known gap (#538) * lint to make sure skills are ASF-agnostic * feat(validator): add dev dependency-group and close asf-coupling-lint known gap Add the missing [dependency-groups] dev section to tools/skill-and-tool-validator/pyproject.toml so that the spec's validation command (uv run --project ... --group dev pytest) works. The validate_asf_coupling check (SOFT check #10), its patterns, and the full TestValidateAsfCoupling test class were already present in the source; 258 tests pass, and skill-and-tool-validate surfaces 86 advisory asf-coupling warnings on the live repo with no hard failures. Update specs/project-agnosticism.md Known-gaps to replace "No automated ASF-coupling lint exists" with the current state: the lint is live and advisory, and the remaining work is acting on the flagged coupling hits. Generated-by: Claude (Opus 4.7)

potiuk merged commit 2efe27f into main Apr 29, 2026
6 checks passed

potiuk deleted the feat/release-manager-handoff-comments branch April 29, 2026 11:21

andreahlert added the mode:Triage Agentic Triage — spot, classify, route, surface duplicates label May 7, 2026

andreahlert mentioned this pull request May 15, 2026

docs(principles): add operational principles document #147

Merged

potiuk mentioned this pull request May 30, 2026

feat(security): docs lift + final scrub (PR5/5) #399

Merged

5 tasks

justinmclean mentioned this pull request Jun 20, 2026

feat(validator): add dev dependency-group and close asf-coupling-lint known gap #538

Merged

15 tasks

justinmclean mentioned this pull request Jul 4, 2026

test(spec-loop): add runner fixture coverage #735

Merged

15 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(release-manager-handoff): explicit hand-off + publication-ready comments#10

feat(release-manager-handoff): explicit hand-off + publication-ready comments#10
potiuk merged 1 commit into
mainfrom
feat/release-manager-handoff-comments

potiuk commented Apr 29, 2026

Uh oh!

potiuk commented Apr 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

potiuk commented Apr 29, 2026

Summary

What's added

Comment 1 — Release-manager hand-off (Step 12 trigger)

Comment 2 — Publication-ready notification (Step 14 trigger)

Architectural split (tool-specific vs generic)

Other lifecycle clarifications

Deliberately unchanged

Test plan

Uh oh!

potiuk commented Apr 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants