docs: refresh V2 board Status option IDs in AGENTS.md (#1823)

[cliffhall]

Closes #1823

The #### V2 board (#28) gh recipes table was stale — it lists a SDK V2 + New Spec column (1bbb6f57) that has since been removed, and is missing V2 Go Live (b3a6966e), added via the GitHub web UI on 2026-07-27 for the go-live phases (#1804). Following the table fails with:

GraphQL: The single select option Id does not belong to the field (updateProjectV2ItemFieldValue)

Hit while moving #1801 to In Review.

Changes

• Table row SDK V2 + New Spec 1bbb6f57 → V2 Go Live b3a6966e, and every removed column's dead ID (1bbb6f57, 4ac261ee, c28da89f, 73d0b807) collected in one place so a future reader recognizes the failure.
• Recorded that adding V2 Go Live through the web UI left the other four IDs untouched — direct evidence the UI path is safe, which is the mitigation the ⚠️ hazard note immediately below already recommends over updateProjectV2Field.
• Corrected the two prose references to describe V2 Go Live as the go-live phases (plan: v2 go-live runbook — deprecate v1 (1.0.1), branch v1/main, swap main to v2, publish 2.0.0, close v1 backlog, restrict external PRs #1804).
• Added the missing recipe for moving a card already on the board — looking its item id up by issue number via gh project item-list … select(.content.number==N). The existing recipes only covered item-add for a new item, so the common "PR opened → move to In Review" step had nothing to copy verbatim.

Verified against the live board:

gh project field-list 28 --owner modelcontextprotocol --format json \
  --jq '.fields[] | select(.name=="Status") | .options'
→ Todo fbdaf21e, V2 Go Live b3a6966e, In Progress 195df262, In Review 159c8a02, Done 248a3910

Docs-only; no code touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MvKF2mqi4hoQSUqQpZXNTq

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 1m 31s —— View job

---

Code review — PR #1825

• Gather context (read PR diff)
• Verify claims against the live board
• Check for stale references elsewhere in the repo
• Post review

---

Docs-only change to AGENTS.md. The substance is right and the PR does more than the issue asked (dead IDs preserved, UI-path safety evidence recorded, missing recipe added). Three things worth addressing — one is a real, newly-introduced gap.

🟡 The maintenance pointer is now incomplete

AGENTS.md:192 (the closing line of the ⚠️ hazard note) tells a future maintainer where else to update IDs when they rotate:

…re-verify and update the table above (and the 248a3910 / 195df262 references in the recipes below and the merge step above).

This PR adds a third hardcoded option id — 159c8a02 at AGENTS.md:218 — which that list doesn't name. The whole point of the pointer is that the option ids are non-stable and duplicated outside the table; leaving the newest duplicate unlisted reproduces exactly the staleness class this PR is fixing. Suggest:

(and the `248a3910` / `195df262` / `159c8a02` references in the recipes below and the merge step above)

Fix this →

🔵 Nit: In review casing left behind on an adjacent line

The PR fixes In progress → In Progress at AGENTS.md:154, but AGENTS.md:157 two lines later still reads In review while the table (line 183) and the new prose both say In Review. Same class of fix, same paragraph — worth folding in, since a reader re-fetching ids by name (select(.name=="Status")) matches on the exact option label.

🔵 Nit: --limit 500 failure mode in the new recipe

ITEM_ID=$(gh project item-list 28 --owner modelcontextprotocol --format json --limit 500 \
  --jq '.items[] | select(.content.number==<ISSUE_NUMBER>) | .id')

The hazard note itself cites ~197 items on this board, so 500 has headroom today but is a ceiling that will be crossed silently: past it, item-list truncates, the select matches nothing, and item-edit --id "" fails with a confusing node-resolution error rather than "your limit was too low." Optional, but a one-line note ("bump --limit if the board has grown past it") or a guard would save a future debugging session. select(.content.type=="Issue" and .content.number==N) would also be marginally more robust — moot under the never-PRs-on-the-board rule, but free.

✅ What's good

• Collecting all four dead IDs (1bbb6f57, 4ac261ee, c28da89f, 73d0b807) in one line is the right call — the failure mode is an opaque The single select option Id does not belong to the field, and recognizing a rejected id as deliberately removed vs. rotated is exactly what a reader needs at that moment.
• The "web UI addition left the other four ids untouched" note is genuinely useful: the hazard note recommends the UI path but had no evidence for it. The diff is self-corroborating — fbdaf21e / 195df262 / 159c8a02 / 248a3910 are all unchanged lines.
• The new already-on-the-board recipe fills a real gap; "PR opened → move to In Review" is the most-run step in the workflow and previously had no verbatim-copyable recipe.
• No stale references anywhere else — grepped the tree for all four removed column names and IDs; AGENTS.md is the only hit.
• Markdown isn't covered by any format:check glob (root format only reaches core/, scripts/, the shared surface, and the clients), so no pre-push gate applies to a docs-only change here.

⚠️ Verification caveat

I could not independently confirm the option ids against the live board — this job's token lacks project scope (gh project field-list 28 → Could not resolve to a ProjectV2 with the number 28). I'm taking the PR body's field-list output at face value; the two referenced issues do check out (#1804 is the v2 go-live runbook, #1823 is the tracking issue, labeled v2).

Verdict: approve-with-nits. The 159c8a02 pointer is the only one I'd call a should-fix; the other two are polish.
· docs/board-status-v2-go-live

[cliffhall]

Thanks — all three addressed in 3ee0a1f (well, the new HEAD of the branch).

🟡 159c8a02 missing from the maintenance pointer — fixed, and you're right that it's the real one. The pointer at AGENTS.md:192 exists precisely because option ids are non-stable and duplicated outside the table; adding a fourth duplicate without listing it would have re-created the staleness this PR is fixing, one rotation later. Now reads `248a3910` / `195df262` / `159c8a02`.

🔵 In review casing at :157 — fixed. Agreed on the reason: the labels are matched exactly by the select(.name=="Status") re-fetch the section tells you to run, so inconsistent casing in the prose is a small trap.

🔵 --limit 500 — note added, guard declined. Added inline: keep --limit above the board's item count (~200 today), because past it item-list truncates silently and the failure surfaces as an opaque node-resolution error from item-edit --id "" rather than "your limit was too low." That's the part that would burn someone's afternoon. I skipped select(.content.type=="Issue" and …) — you correctly called it moot under the never-PRs-on-the-board rule stated a few lines up, and a redundant guard in a copy-paste recipe invites the reader to wonder which rule is actually true.

On the verification caveat: fair flag, and the right call to state it rather than imply confirmation. The job's token lacks project scope, so the field-list output in the PR body is unverifiable from CI by construction — a limitation of any board-facts PR here, not something this one can close. I re-ran it locally against the live board before pushing; the five ids in the table are current as of today.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 1m 25s —— View job

---

Re-review — PR #1825

• Read updated diff (origin/v2/main...HEAD)
• Verify the three prior review items are addressed
• Re-scan the repo for stale column names / dead option IDs
• Post review

---

All three items from the last round are addressed in 8e8058e6. Nothing blocking; one optional polish suggestion below.

✅ Verified fixes

Item	Status
🟡 159c8a02 missing from the maintenance pointer	Fixed — AGENTS.md:192 now reads `248a3910` / `195df262` / `159c8a02`
🔵 In review casing at :157	Fixed — now In Review, matching the table at :183
🔵 --limit 500 silent-truncation failure mode	Documented at :213 — "past it item-list truncates silently, select matches nothing, and item-edit --id "" fails with an opaque node-resolution error rather than saying the limit was too low"

I re-grepped the tree for every hardcoded option id and every removed column name (1bbb6f57, 4ac261ee, c28da89f, 73d0b807, b3a6966e, fbdaf21e, 195df262, 159c8a02, 248a3910, SDK V2 + New Spec, Building CLI, Building Web, MCP Apps Extension, In review, In progress) across *.md / *.ts / *.tsx / *.mjs / *.json / *.yml. AGENTS.md is the only file with any hit, and the pointer at :192 now names every duplicate: 248a3910 (:159), 195df262 (:203, :210), 159c8a02 (:218). b3a6966e and fbdaf21e appear only in the table, so the pointer is complete — the staleness class this PR fixes is now closed over the whole file.

Also checked: no other file duplicates the board instructions (grepped board #28, projects/28, single-select-option-id outside AGENTS.md — no hits), working tree clean, no trailing whitespace on added lines.

🔵 Optional: the --limit warning lives outside the code block

AGENTS.md:213 puts the truncation warning in the prose paragraph above the fence, but the section's own framing is "copy the recipes below verbatim" (:153) — a reader who grabs just the ```sh block takes --limit 500 with none of the context explaining why the number matters. The two recipes above both carry their guidance as in-block comments (# 1. Add an issue to the board…, # 2. Set its Status…), so a one-line # bump --limit if the board has grown past it inside the fence would match the local convention and survive a copy-paste. Purely optional — the prose is correct as written.

Fix this →

⚠️ Same verification caveat as last round

This job's token still lacks project scope — gh project field-list 28 --owner modelcontextprotocol returns Could not resolve to a ProjectV2 with the number 28, as does item-list. So I can confirm the document is internally consistent but not that the five ids match the live board. Per your note you re-ran field-list locally before pushing; that's the only way to close this from CI, and it's a structural limit of any board-facts PR here rather than something this one can fix.

Verdict: looks good to merge. Docs-only — no format/lint gate applies to Markdown here (the root format globs reach core/, scripts/, the shared surface, and the clients, none of which cover *.md).
· docs/board-status-v2-go-live

[cliffhall]

Taken — the --limit caveat now lives inside the fence as a shell comment, matching the in-block style of the two recipes above it. Your reasoning is the deciding one: the section says to copy the recipes verbatim, so anything that only exists in the prose above the block is guaranteed to be lost by the reader who does exactly that.

Thanks for the pointer-completeness re-grep — confirming that 248a3910 (:159), 195df262 (:203, :210), and 159c8a02 (:218) are the complete set of duplicates the maintenance pointer must name is the part that actually closes the staleness class, and it's not something I'd verified beyond the one id you caught.

On the verification caveat: agreed it's structural, and correctly re-stated rather than dropped on the second pass. Re-ran field-list against the live board again just now — table still current.

Calling this done at two rounds: everything raised is either fixed or explicitly declined with a reason, and the only open item is a CI-token limitation no change to this PR can close.