Correction: Project status options CAN be edited via API without breaking workflows - the option input accepts an id

[PBNZ]

Correction to a documented landmine, with evidence. Found while commissioning a board (private repo,
2026-07-20).

Context

org-migration-checklist.md,
under Board rebuild, says:

Replacing a Project's status options breaks the built-in workflows silently. A new column set
via API leaves every default workflow ("item closed → status X", "auto-close", "PR merged")
pointing at deleted option ids — they show a warning icon and dangle until each is re-edited by
hand in the UI. Budget the click-through.

The failure is real, but the rule drawn from it is too strong, and it is expensive: taken at
face value it says the Status field is API-forbidden, so every column change becomes manual UI work
— and an agent that has internalised it will refuse the operation (mine did, correctly, having
copied the rule into a project's AGENTS.md).

The finding: ProjectV2SingleSelectFieldOptionInput has an optional id field.

query { __type(name:"ProjectV2SingleSelectFieldOptionInput"){ inputFields{ name } } }
# -> id (String, nullable), name (String!), color (enum!), description (String!)

Omitting id for an option that already exists is what mints a new id — which orphans every item's
stored value and leaves the built-in workflows pointing at a dead option. Passing the existing id
through preserves both. The landmine is specific to a replacement; an additive, id-echoing
edit is safe.

Verified in practice. A live board's three stock options were expanded to six in one mutation,
echoing the ids of the three that were kept (one of them renamed):

• Todo's id was reused for the renamed first column, so the Item added to project workflow kept
  firing at the right option;
• In Progress and Done kept theirs, so Item closed, Auto-close issue, PR merged and
  PR linked to issue all stayed pointed at live options;
• the three genuinely new options were passed without id.

Afterwards: all six enabled workflows still enabled and correctly targeted, and all item values
preserved (75 items, verified by re-reading every item's Status). Zero click-through.

Note the ordering consequence, which is the useful design lever: options render in array order, so
"insert a column in the middle" and "rename a column while keeping its automation" are both
achievable in one call — you just have to read the current ids first.

Proposal

Rewrite the bullet in symptom → cause → fix form, matching the rest of that checklist:

• Status options replaced via API, and now the built-in workflows dangle? → The option
  list was sent without ids, so GitHub minted new ones and every workflow (and every item value)
  still refers to the old, now-deleted options. → ProjectV2SingleSelectFieldOptionInput accepts
  an optional id: read the current options first
  (field(name:"Status"){... on ProjectV2SingleSelectField{options{id name}}}), echo the id back
  for every option you keep or rename, and omit id only for new ones. Then verify —
  workflows(first:20){nodes{name enabled}} plus a re-read of item values — before trusting it.
  Only a full replacement needs the UI click-through.

Tasks

• Update the bullet in standard/org-migration-checklist.md.
• If the eventual board-bootstrap tooling ever sets columns, have it read-then-echo ids by
  construction.

Acceptance criteria

• The checklist tells an agent how to change status options safely, instead of implying it must not.
• The verification step (workflows enabled + item values intact) is part of the fix, not left to
  taste.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Landed on main via #24 and merged by @PBNZ; shipping in v0.5.0.

— 🤖 Claude, on behalf of @PBNZ