<!-- SPDX-License-Identifier: Apache-2.0
     https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [🚀 Release-manager hand-off — `CVE_ID`](#-release-manager-hand-off--cve_id)
  - [Step 1 of 3 — address reviewer feedback (if any), then promote to READY](#step-1-of-3--address-reviewer-feedback-if-any-then-promote-to-ready)
  - [Step 2 of 3 — preview the advisory email, then send it](#step-2-of-3--preview-the-advisory-email-then-send-it)
  - [Step 3 of 3 — sync closes out the rest (no further action from you)](#step-3-of-3--sync-closes-out-the-rest-no-further-action-from-you)
  - [Reference links (only if you want them)](#reference-links-only-if-you-want-them)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- SPDX-License-Identifier: Apache-2.0
     https://www.apache.org/licenses/LICENSE-2.0 -->

<!--
     Manual-paste variant of the release-manager hand-off comment
     posted by `security-issue-sync` at the `pr merged` → `fix released`
     transition (Step 12 of the lifecycle), when the OAuth API push
     of the CVE JSON did not succeed during the sync run that fires
     this hand-off (no OAuth credentials configured on the operator
     machine, session expired, transient HTTP error, schema rejection).

     This template is the counterpart to
     `release-manager-handoff-comment-oauth-pushed.md`. The sync skill
     picks between the two based on the outcome of `vulnogram-api-check`
     + `vulnogram-api-record-update` — see Step 5b of
     `.claude/skills/security-issue-sync/SKILL.md` for the decision
     flow.

     **Gate**: this comment is ONLY posted when the CVE record's
     state in Vulnogram is `REVIEW` (verified by sync via
     `vulnogram-api-record-fetch` after Step 5b's push attempt).
     When the record is still `DRAFT` after the push attempt — for
     any reason — sync posts the
     `remediation-developer-fill-fields-comment.md` instead and the
     tracker stays assigned to the remediation developer. The RM
     never receives a hand-off while the record is in `DRAFT`. The
     "How to advance from `DRAFT` to `REVIEW`" lifecycle question is
     scoped to the remediation-developer template, not this one.

     **No `uv run` invocations are RM-facing in this template.**
     When the OAuth push fails, the security team's next sync
     resolves the issue (re-run `vulnogram-api-setup`, retry the
     push). The RM's surface stays the same as in the OAuth-pushed
     variant plus an explicit "you may need to paste the JSON into
     #source" fallback if the security team cannot resolve the
     OAuth path. The paste itself is a UI action — click Edit →
     paste → Save — not a shell command.

     Placeholders the skill substitutes:

       CVE_ID                    e.g. CVE-2026-40690
       RM_HANDLE                 GitHub handle of the release manager
                                 (with leading `@`)
       SECURITY_LIST             e.g. security@<project>.apache.org
       USERS_LIST                e.g. users@<project>.apache.org
       ANNOUNCE_LIST             e.g. announce@apache.org
       SOURCE_TAB_URL            <cve_tool_record_url_template>#source
       EMAIL_TAB_URL             <cve_tool_record_url_template>#email
                                 (Vulnogram's email-preview tab URL)
       JSON_ANCHOR_URL           Tracker body deep-link to the embedded
                                 CVE JSON section (e.g.
                                 https://github.com/<tracker>/issues/<N>#cve-json--paste-ready-for-cve-yyyy-nnnn)
       BOARD_URL                 Project-board URL with the `Status:
                                 Announced` filter pre-applied (used
                                 in Step 3's reference to the
                                 wrap-up cleanup)
       MILESTONE_URL             Tracker-side URL of the milestone
                                 this tracker belongs to (used in
                                 the conditional close-milestone
                                 line of the wrap-up comment in
                                 Step 3)
       FRAMEWORK_RECORD_MD_URL   Link to tools/cve-tool-vulnogram/record.md on
                                 the framework's GitHub
       FRAMEWORK_SYNC_SKILL_URL  Link to .claude/skills/security-issue-sync/
                                 SKILL.md on the framework's GitHub
       FRAMEWORK_README_URL      Link to README.md on the framework's
                                 GitHub (Steps 12-15 anchor)
       CANNED_RESPONSES_URL      Link to <project-config>/canned-
                                 responses.md on the tracker's GitHub

     The HTML marker on the first line is load-bearing: the skill
     detects an already-posted hand-off comment by grepping for
     this exact string and skips the post on subsequent sync runs
     (idempotency).

     Do not paraphrase the marker. Do not move it off line 1. Do
     not add a `<!-- v2 -->` until the schema actually changes —
     the skill's grep is anchored on `v1`.
-->
<!-- apache-magpie: release-manager-handoff v1 -->

## 🚀 Release-manager hand-off — [`CVE_ID`](SOURCE_TAB_URL)

RM_HANDLE — the release with the fix has shipped, and the CVE record on Vulnogram is in **`REVIEW`** state with all mandatory content populated. This tracker is now yours to drive from **Steps 13 → 14 → 15** of the security process. Three actions, in order; each one is a single click in Vulnogram; **no shell commands required from you at any point**.

> **You will never see this comment while the record is in `DRAFT`.** Sync gates the hand-off on the record reaching `REVIEW`. If you ever see this comment paired with a `DRAFT` state on the linked record, please ping @potiuk on this issue before clicking anything in Vulnogram — that combination is a bug we want to know about, not a state for you to resolve.
>
> *(The security team has already pushed the CVE JSON content into Vulnogram and filled every body field on this tracker that the public advisory needs. Your job is to: address any CVE-reviewer feedback that lands during `REVIEW`, move the record to `READY` when review closes, then send the advisory email. That's it.)*

---

### Step 1 of 3 — address reviewer feedback (if any), then promote to READY

Open the record's [`#source` tab](SOURCE_TAB_URL) in your browser. **State** field at the top should read `REVIEW` — that is the precondition for this comment firing, so it should match. If it doesn't, stop and ping @potiuk; otherwise:

1. **Click the [OSS/ASF Emails tab](EMAIL_TAB_URL)** (the `#email` anchor) on the same page. Scroll through any reviewer comments left by the ASF Security Team's CVE reviewers. **You do not need to act on reviewer comments yourself** — they arrive by email on `SECURITY_LIST` with the CVE ID in the subject, and sync detects them on the next run, opens corresponding body-field updates on this tracker, and re-pushes the JSON. If the comments tab is empty, or carries a closure note (*"OK, looks good"* / *"approved"*), proceed to the next step.

2. **When the reviewer thread is clear** (no open comments, or all comments have an *"OK, looks good"*-style closer), click the **REVIEW button on the Editor tab** to advance the record from `REVIEW` → `READY`. Click **Save**. *The record is now staged for advisory send.*

> 💡 *How do you know the reviewer thread is clear?* Two signals: (a) no new reviewer email on `SECURITY_LIST` carrying the CVE ID for ~3 days, or (b) an explicit "looks good" reply from the reviewer. Most CVEs go through `REVIEW` with no reviewer comments at all — in that case, you can usually move `REVIEW → READY` immediately after Step 1.1's tab-check confirms there's nothing to address.

---

### Step 2 of 3 — preview the advisory email, then send it

With the record in `READY`, click the [OSS/ASF Emails tab](EMAIL_TAB_URL) (the `#email` anchor) on the same record page. This shows you, in the exact format that goes out, what the advisory email will look like when sent to `USERS_LIST` and `ANNOUNCE_LIST`.

**Check that:**
- The subject line is `CVE_ID: <one-line description>` and the description matches what you'd want public.
- The body's short-summary paragraph reads as instructions to a user (*"Users are advised to upgrade to version X"*), not just a technical description of the bug.
- The *Affected versions* range is correct.
- The reporter credit line is present and spelled correctly.

**If anything looks wrong**: don't edit it in Vulnogram. Comment on this tracker (just `@potiuk: the X field needs Y`) and we'll fix the corresponding body field here, regenerate the JSON, and re-push within the next sync. Re-preview after that.

**If everything looks right**: click the **Send these Emails** button on the OSS/ASF Emails tab. That one action ships the advisory to `USERS_LIST`, `ANNOUNCE_LIST`, and [`oss-security@lists.openwall.com`](https://oss-security.openwall.org/) — the tab is the "**OSS**/ASF Emails" tab precisely because it dispatches the `oss-security` copy (required per the [ASF security-committers policy](https://www.apache.org/security/committers.html)) automatically alongside the ASF lists. **You do not send a separate copy by hand — that is the only send action you make for this CVE.**

> ⚠️ **Do not touch the tracker labels yourself.** Sync flips `fix released` → `announced - emails sent` + `announced` automatically when it sees the advisory in the public archive (usually within the same day). If you flip them manually you race the automation.

---

### Step 3 of 3 — sync closes out the rest (no further action from you)

Once the advisory archives on `lists.apache.org/list.html?USERS_LIST` (typically within minutes of sending), the next sync run does this for you, end-to-end:

1. Captures the published advisory URL into this tracker's body.
2. Regenerates the CVE JSON (now including the archive URL as a `vendor-advisory` reference) and re-pushes it to Vulnogram.
3. Moves the Vulnogram record `READY` → `PUBLIC` (this is the CNA-feed dispatch — once it lands, `cve.org` starts propagating).
4. Flips this tracker's labels (`fix released` → `announced - emails sent` + `announced`).
5. Closes this tracker as `completed`.
6. **Archives this tracker** from the `Announced` column on the [Security issues board](BOARD_URL) (`archiveProjectV2Item` GraphQL mutation — sync, not you).
7. *(Conditional)* **Closes the [`MILESTONE_TITLE`](MILESTONE_URL) milestone** if this tracker was the last open issue on it.

The CVE will propagate to `cve.org` on its own within a few hours; sync will detect the publication on a subsequent run and post a courtesy *"CVE is live on cve.org"* note to the reporter on the original email thread.

**You're done.** The lifecycle is complete from your side at Step 2 (Send Email). Everything above is sync's job — no further comments will tag you with manual cleanups.

---

### Reference links (only if you want them)

- **The full lifecycle in one place** — [`README.md` Steps 12–15](FRAMEWORK_README_URL#for-release-managers--steps-1215)
- **Vulnogram-specific mechanics** (state machine, paste-flow details) — [`tools/cve-tool-vulnogram/record.md`](FRAMEWORK_RECORD_MD_URL)
- **Reusable email wording for ad-hoc replies** — [`canned-responses.md`](CANNED_RESPONSES_URL)

---

<details><summary>Manual-paste fallback — only if Step 1 found the JSON content on Vulnogram does not match this tracker's embedded JSON</summary>

If Step 1 found the JSON on Vulnogram does **not** match this tracker's [embedded JSON](JSON_ANCHOR_URL) (i.e. the security team's automated push was blocked when this comment was posted), follow these one-time steps before continuing with Step 1:

1. Open [the embedded JSON section](JSON_ANCHOR_URL) of this tracker's body. Click `Copy` on the JSON code block (or select and ⌘C / Ctrl-C).
2. Open [`#source` tab](SOURCE_TAB_URL) on Vulnogram. The editor takes JSON as plain text.
3. Select all (⌘A / Ctrl-A) in the editor and paste (⌘V / Ctrl-V).
4. Click **Save**.
5. Now go back to Step 1 — the record is loaded; verify reviewer comments (if any) and move `REVIEW` → `READY`.

The security team will resolve the automated-push issue on their side (re-run `vulnogram-api-setup`); subsequent sync runs will keep the record in sync without you needing to repeat this paste.

</details>
