projects_write: add iterations to an existing iteration field (currently impossible without wiping item assignments)

[ungum-ungum]

Describe the feature or problem you’d like to solve

projects_write supports create_iteration_field (added in #2232, closing #1854), but there is no way to add an iteration to an existing iteration field — the single most common sprint operation ("add the next sprint").

Today, when an agent is asked to "add the next sprint to the Sprint field", the only iteration-related method available is create_iteration_field, so agents end up creating a duplicate field instead of appending to the existing one.

The underlying blocker is a public API asymmetry, which I verified empirically (2026-07-27):

1. GraphQL: the only way to modify iterations is updateProjectV2Field with iterationConfiguration, whose docs state "provided values overwrite the existing configuration". Its ProjectV2Iteration input accepts only {startDate, duration, title} — no id, while the read-side type ProjectV2IterationFieldIteration does expose id.
2. Consequence (tested on a disposable project): rebuilding the list with identical titles/dates regenerates all iteration ids (e.g. 18dd8506 → 3038b65f), and every item's iteration field value is silently cleared — for completed and active iterations alike.
3. REST: the new projectsV2 REST endpoints only allow creating fields (POST .../fields); fields/{field_id} has no PATCH/PUT, and the iteration items schema is additionalProperties: false with no id either.
4. Precedent in the same mutation: ProjectV2SingleSelectFieldOptionInput does have an optional id, documented as "Include this to preserve the option's identity during updates, preventing item field values from being cleared". The GitHub web UI's internal endpoint uses exactly this pattern for iterations (existing entries carry id, new entries send id: ""). Iterations appear to be the one place this mechanism was left out of the public schema.

Proposed solution

Two complementary parts:

1. (Root fix, likely needs routing to the Projects/GraphQL team) Add an optional id: String to the ProjectV2Iteration input, with the same preserve-identity semantics as ProjectV2SingleSelectFieldOptionInput.id. This would make read-modify-write appends safe for any API consumer, not just MCP.
2. (This repo) Add an add_iteration method to projects_write that appends an iteration to an existing iteration field (auto-computing the next start date from the last iteration when omitted). If/while the schema lacks id, the method could either (a) be gated with an explicit destructive warning, or (b) mitigate by snapshotting item assignments before the rewrite and re-assigning them to the regenerated ids afterwards.

This would benefit every team running sprint workflows through the MCP server: sprint planning is a recurring, high-frequency operation, and it is currently the one Projects v2 write that agents cannot perform safely at all.

Example prompts or workflows (for tools/toolsets only)

• "Add the next sprint to the Sprint field in project 14"
• "Extend our Sprint iterations through the end of Q4, two weeks each"
• "Create 'Sprint 23' starting 2026-10-03 with a duration of 14 days"
• "Our sprints ran out — add six more iterations matching the current cadence"
• "Insert next sprint and move all unfinished items from the current one into it"

Additional context

• Verification was done via schema introspection (__type on ProjectV2Iteration, ProjectV2IterationFieldIteration, ProjectV2SingleSelectFieldOptionInput) and a live experiment on a throwaway user project; happy to share the exact GraphQL calls and before/after output.
• Related: Feature Request: Support for GitHub Projects v2 Iteration Fields #1854 (closed by feat: add create_project and create_iteration_field methods to projects_write #2232, which covers field creation only).
• Public schema references (docs.github.com schema.docs.graphql): input ProjectV2Iteration (no id) vs type ProjectV2IterationFieldIteration (has id); UpdateProjectV2FieldInput.iterationConfiguration overwrite note; ProjectV2SingleSelectFieldOptionInput.id preserve-identity note.