[cliffhall]

Closes #5334

Description

The security-advisory skill and AGENTS.md said an advisory's [GHSA-…] draft card converts to an issue only after publication, and treated the private fork's PR as the fix's PR. In practice the fix reaches v2/main through a public PR in this repository, which then had no issue to Closes and no card tracking it. This describes the flow as it was run for #5332 / #5333:

• security-advisory skill: the flow table and steps 3 to 6. Step 4: the fork's PR is where the review happens and is not merged. Step 5 gains three subsections: convert the card to an issue that keeps its opaque title and link-and-triage body (labels and milestone at that point); push the fork's branch under the same opaque name (gate first) and open a public PR with an opaque title and body, linked with addCloseIssueReferences, card → In Review, no Copilot loop; a maintainer merges, the issue is closed and the card goes to Done. Then the existing close-the-fork's-PR recipe. Step 6 becomes: after publication, retitle the issue [GHSA-…] - <published summary> and replace its triage lines with the advisory link. The exposure warning now starts at the push to this repository rather than at the merge. Follow-up cards still convert only after publication.
• AGENTS.md: the Contributing "security advisory's fix" exception (both PRs, the public one's opaque-text and no-Copilot exceptions), the Issue-driven work style [GHSA- bullet (conversion timing; follow-up cards still wait for publication), the Incoming milestone exemption, and a pointer from the Copilot-loop bullet to the exception.
• board-ops: the Convert recipe's timing sentence.
• Two stale restatements of "no public issue": docs/ai-software-factory.md and the release skill's advisory-credit bullet (plus the matching comment in scripts/release-notes.mjs).

Server Details

• Server: none (repository-wide)
• Changes: agent guidance (AGENTS.md, skills) and one design doc; one code comment

Motivation and Context

See #5334. The public PR for GHSA-w766-5x43-whvw (#5333) had to be opened against an issue converted early (#5332) with no recipe for either step.

How Has This Been Tested?

Docs and skills only, no client-observable surface. Targeted probes:

• npm run verify:skills: OK, 11 skills, listing share unchanged at 3903/4000 (no skill description changed, so skills:eval was not rerun).
• npm run local:gate: exit 0 on 8c7af45.
• No vulnerability details appear in any changed text; the only advisory id named is the already-public example in this body.

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Protocol Documentation (not applicable: no protocol surface touched)
• My changes follow MCP security best practices
• I have updated the server's README accordingly (not applicable: no server changed)
• I have added a changeset (npm run changeset) if this changes what a TypeScript server publishes (not applicable: nothing published changes)
• I have tested this with an LLM client (not applicable: docs and skills only)
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling (not applicable: no code)
• I have documented all environment variables and configuration options (not applicable: none added)

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 11f64f9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

🟡 Changes recommended

The recipe leaves HEAD detached but invokes gh pr create without --head, preventing the public PR from being opened even after the push succeeds.

1 open issue

• Pass --head when creating a PR from detached HEAD · New

What changed in this PR

Documents how privately reviewed security fixes reach v2/main through public PRs with opaque titles and bodies, addressing the tracking gap in #5334.

Changes:

• Moves advisory-card conversion before the public fix PR, while keeping follow-up cards private until publication.
• Defines public PR creation, review exceptions, merge close-out, and post-publication updates.
• Aligns related guidance and reporter-credit explanations with the revised flow; no runtime behavior changes.

File	Description
scripts/​release-notes.mjs	Updates only the comment explaining advisory reporter credits.
docs/​ai-software-factory.md	Aligns the security-flow overview with earlier issue conversion.
AGENTS.md	Updates advisory PR exceptions, conversion timing, and review rules.
.claude/​skills/​security-advisory/​SKILL.md	Adds the public fix PR procedure and revises publication steps.
.claude/​skills/​release/​SKILL.md	Corrects the explanation for sourcing advisory credits.
.claude/​skills/​board-ops/​SKILL.md	Updates advisory-card conversion timing.

_{Review effort: Balanced}

[cliffhall]

Copilot round 1: one finding, fixed.

• Detached HEAD with no --head (security-advisory skill, the public-PR recipe): fixed in 11f64f9. The recipe now tells you to pass --head "$BRANCH" to gh pr create, since the worktree it creates is detached.

Gate re-run on 11f64f9: exit 0. Requesting round 2.

[Copilot]

🟢 Approval recommended

No active review issues are reported for the security-fix workflow documentation updates.

No open issues 🎉

1 resolved since last review

• Pass --head when creating a PR from detached HEAD

_{Review effort: Balanced}

[cliffhall]

Copilot round 2 (on 11f64f9): clean, "Approval recommended", no new findings; the round-1 finding shows as resolved. The loop ends on the first clean round.