Skip to content

Commit ccc831c

Browse files
cliffhallclaude
andcommitted
docs: address Copilot review round 8 on #2444
Parameterize the GHSA id in board-ops' draft-card lookup, which matched the literal placeholder, and fail loudly when nothing matches. Make accepting the advisory the approval act that moves a GHSA draft Incoming -> Todo, and record it as an exemption to the Incoming <=> milestone invariant in AGENTS.md and in the audit notes, since a draft card cannot carry a milestone. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 50a9634 commit ccc831c

4 files changed

Lines changed: 17 additions & 3 deletions

File tree

‎.claude/skills/board-ops/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,11 @@ Look it up by **title** instead, then feed that item id to `item-edit` or
4040
`item-delete` exactly as usual:
4141

4242
```sh
43+
GHSA=GHSA-xxxx-yyyy-zzzz # the advisory's real id
4344
ITEM_ID=$(gh project item-list 28 --owner modelcontextprotocol --format json --limit 500 \
4445
--jq '.items[] | select(.content.type=="DraftIssue")
45-
| select(.content.title | startswith("[GHSA-xxxx-yyyy-zzzz]")) | .id')
46+
| select(.content.title | startswith("['"$GHSA"']")) | .id')
47+
[ -n "$ITEM_ID" ] || echo "no draft card titled [$GHSA] on #28" >&2
4648
```
4749

4850
Match on the **bracketed GHSA id**, not on words from the summary — a summary is

‎.claude/skills/issue-triage/SKILL.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -295,7 +295,12 @@ Two things the queries must account for, both learned the hard way:
295295
- **The two milestone checks are #28-only.** Every milestone in this repo is a
296296
v2 release bucket, so a `v1` issue has none it could take — running the
297297
Incoming⇔milestone invariant over board #11 would flag every card on it for a
298-
state it cannot reach.
298+
state it cannot reach. They also read **Issue items only**, which is what
299+
exempts a `[GHSA-` advisory draft on #28: it cannot carry a milestone, and its
300+
approval is the advisory's **acceptance** (`/security-advisory` step 3),
301+
which lives on the advisory rather than the board. The audit cannot see that,
302+
so a GHSA draft past `Incoming` is correct once its advisory is accepted and
303+
is not reported.
299304
- **Count the labels; don't test for presence.** The invariant is *exactly
300305
one*, so a predicate that only asks "is any version label present" passes an
301306
issue carrying **both** `v1` and `v2` — which belongs to two lines at once

‎.claude/skills/security-advisory/SKILL.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,13 @@ provisional score could not have had.
183183
moves the advisory `triage` → `draft`. The state is readable as `state` and
184184
`submission.accepted` on the API object.
185185

186+
**Then move the card `Incoming` → `Todo`.** On #28 the approval act is
187+
normally assigning a milestone, and a draft card cannot carry one — so for an
188+
advisory draft, **accepting the advisory is the approval**, and it is what
189+
licenses the card to leave `Incoming`. `AGENTS.md` records this as the
190+
advisory exemption to its `Incoming` ⇔ milestone invariant. The milestone
191+
arrives with the public issue in step 6, where the ordinary rule resumes.
192+
186193
**Invalid, out of scope, or upstream → close** with a comment saying which, and
187194
why. A reporter who is told nothing reasonably assumes they were ignored.
188195

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -371,7 +371,7 @@ skills; the rules are here.
371371
- **Label by type — exactly one of `bug` / `enhancement` / `documentation` / `chore` / `question`** on every issue you create or triage. The version label says which line the work belongs to; the type label says what kind of work it is, and the two are independent. Don't force the binary: pressing a docs task or a dependency pin into `enhancement` degrades it to "not a bug", at which point filtering by it stops telling you anything. A **PR** needs no type label — it is classified through the issue it closes.
372372
- **Every v2 issue you create gets a milestone.** Milestones are _release_ buckets, so pick by when the work ships. Never leave a v2 issue you filed unmilestoned pending a decision. Two exceptions, both deliberate: an issue that arrives **unboarded** stays unmilestoned in `Incoming` until a maintainer approves it — there, the _absence_ of a milestone is the signal; and **every milestone is a v2 release bucket, so a `v1` issue has none to take**. Say so when filing one rather than dropping it in a v2.x bucket.
373373
- **Every v2 board item has a Priority.** Priority is a **board field**, not a label, so an unboarded issue has nowhere to store it. Derive it with the rubric in the `issue-triage` skill rather than asserting it. Board #11 has no Priority field; a v1 issue gets a Status and nothing else.
374-
- **`Incoming` ⇔ no milestone; everything past it ⇔ milestoned — on board #28.** Board #11 is exempt for the reason above: a v1 issue has no bucket to take, so its Status is set on its own and the audit's milestone checks do not apply to it. The rest of the invariant is unchanged: assigning the milestone _is_ the approval act, so the two always go together. `Todo` asserts a maintainer signed off, so never park an unreviewed issue there — that erases the distinction and quietly promotes unreviewed work into the queue. An issue created through the documented flow skips `Incoming` entirely, because filing it _was_ the approval.
374+
- **`Incoming` ⇔ no milestone; everything past it ⇔ milestoned — on board #28.** Board #11 is exempt for the reason above: a v1 issue has no bucket to take, so its Status is set on its own and the audit's milestone checks do not apply to it. A `[GHSA-` **advisory draft** on #28 is exempt too, for a different reason: a draft card cannot carry a milestone, so its approval act is **accepting the advisory**, which moves it `Incoming` → `Todo`; its milestone arrives with the public issue after publication. The rest of the invariant is unchanged: assigning the milestone _is_ the approval act, so the two always go together. `Todo` asserts a maintainer signed off, so never park an unreviewed issue there — that erases the distinction and quietly promotes unreviewed work into the queue. An issue created through the documented flow skips `Incoming` entirely, because filing it _was_ the approval.
375375
- **`Done` means the work shipped.** Exactly two things earn a card a place in Done: its **PR merged**, or it is a **parent whose last sub-issue closed**. Anything else — duplicate, won't fix, not planned, obsolete, superseded — means nothing shipped, so the card is **deleted**. Done is read as the record of what a milestone actually delivered; a duplicate sitting there makes that record wrong in a way nobody can detect later. Deleting a card touches the board only — the issue keeps its labels and comments and stays searchable forever.
376376
- **When work begins**, create a feature branch and set Status to **In Progress**. **Branch names start with the target version segment** — `v2/fix/2071-oauth-resource-metadata`, `v1/fix/proxy-ssrf-pin` — matching the base branches themselves.
377377
- **When work is complete**, run `npm run format` then `npm run local:gate`, **sign off every commit** (`git commit -s` — the DCO check is a hard merge gate with no partial credit), open a PR against the matching base branch with **`Closes #<ISSUE_NUMBER>` as the body's first line**, and set Status to **In Review**.

0 commit comments

Comments
 (0)