Automate ADO user story state transitions on PR create/complete

Goal

Make ADO work-item state transitions follow the PR lifecycle automatically, so sprint state isn't dependent on developers remembering manual steps that are routinely missed.

Current Behavior

The intended workflow on the BGV Development board is:

1. Active when work starts (already automated by /start-work, GH #124)
2. Ready for Review when the PR is created
3. Closed when the PR completes

Both transitions after step 1 are manual today and frequently neglected:

• Active → Ready for Review — requires the developer to drag the card in the ADO web UI. Frequently skipped because nothing prompts for it at PR-creation time.
• Ready for Review → Closed — requires the developer to (a) set the PR to auto-complete and (b) check the "Complete linked work items" checkbox in the auto-complete dialog. Either step is easy to miss.

The team-standards CLAUDE.md note already calls out the second trap explicitly:

Note that AB#<id> alone does not auto-close the work item — auto-close requires the PR to be set to auto-complete with the appropriate work-item transition rules configured.

The result is that linked work items drift from reality. PRs merge with their cards still Active. Sprint reports become unreliable. The same workflow rule existed before, but compliance was uneven enough that the standard alone hasn't solved it.

Proposed Solution

Four options, roughly ordered from lightest to heaviest:

1. Team-standard reminder

Extend standards/CLAUDE.md with a workflow rule that any PR-creating context (especially craft-pr) reminds the developer to set auto-complete with work-item completion enabled. Lightest touch, but still relies on the developer to act, which is what we have today minus the prompt.

2. craft-pr skill enhancement (recommended starting point)

When the skill creates a PR linked to an ADO work item:

• Immediately transition the work item from Active → Ready for Review via wit_update_work_item. Symmetric with how /start-work already transitions to Active.
• When the developer opts into auto-complete, programmatically set the PR's auto-complete options including completeWorkItems: true (via repo_update_pull_request / the equivalent REST API parameter), instead of leaving that as a checkbox the developer has to remember.
• Default behavior; opt-out flag (e.g., --no-state-transition) for projects with non-standard workflows.

This covers the common path and slots into existing skill ergonomics.

3. Server-side automation

ADO Service Hook → Azure Function (or Logic App) listens for pull request created / pull request completed events and transitions linked work items unconditionally. Catches PRs created outside craft-pr (web UI, other tools). Higher infra cost. Composes with GH #100 (autonomous agent), which shares Service Hook plumbing.

4. ADO built-in policies

Investigate whether ADO has project- or repo-level policy support for forcing "complete linked work items" on PR completion. If it exists, this is the lowest-effort fix and should be evaluated before building anything.

Recommendation: Start with option 2 (covers the common case via the tool the team already runs) and add option 1 as a backstop for PRs created any other way. Confirm/dismiss option 4 during research. File option 3 as a follow-up only if the non-craft-pr PR gap matters in practice.

Acceptance Criteria

1. Research confirms the canonical state name(s) used in BGV Development's User Story workflow — specifically the post-Active / pre-Closed state. (May not be literally "Ready for Review" — could vary per project.)
2. craft-pr, when creating a PR linked to an ADO work item, transitions that work item from Active to the next-after-Active state.
3. craft-pr, when the developer enables auto-complete, sets the PR's auto-complete options to include "Complete linked work items" — programmatically, not as a manual checkbox.
4. State transition can be opted out via a flag for projects with non-standard workflows (e.g., bugs, custom state machines).
5. standards/CLAUDE.md documents the full lifecycle alongside the existing "Mark Work Items Active" rule: Active (/start-work) → next state (/craft-pr) → Closed (PR auto-complete).
6. At least one negative scenario verified: craft-pr fails gracefully (warns and continues) when the linked work item's state machine doesn't have the expected target state.
7. PRs against multiple linked work items: skill transitions all of them, not just the primary.

Open Questions

• What's the canonical "Ready for Review" state name in BGV Development's User Story workflow type? Worth checking other project state machines too in case BGV uses different names per project.
• Does ADO's auto-complete dialog "Complete linked work items" checkbox map to a specific REST API field on PullRequest.completionOptions? Need to confirm before option 2 is implementable.
• Should this issue ship as one PR (research + craft-pr changes + standards update) or split per the phased-work standard? Probably split: standards-only PR first, then craft-pr enhancement.
• GitHub issues already auto-close via Closes #N in PR body — already standard practice. This issue is ADO-specific; should we mention parity with the GH path in the standards section?

Related

• #124 / #126 — /start-work skill establishes the pattern of skill-driven work-item state transitions; this issue extends that pattern through the rest of the lifecycle.
• #100 — autonomous PR review agent shares ADO Service Hook infrastructure if option 3 is ever pursued.
• #127 — scheduling research; relevant only if a recurring "find work items still Active after their PR closed" sweep is needed as a backstop.

Read the /craft-pr skill and the /start-work pattern from #124/#126, then inspect standards/CLAUDE.md. Confirm the canonical ADO state and the PR completion-options field before changing the skill. Done means linked work items transition on PR creation and auto-complete, opt-out and failure cases are handled, multiple links work, and the lifecycle is documented.