Batch Complete

Close out a feature subtree, cancel an abandoned workstream, or clean up stale items in one operation. Handles gate checks, active-item warnings, and reports exactly what succeeded and what was skipped.

Step 1 — Identify Scope

Resolve $ARGUMENTS to a UUID via query_items search (operation="search", query=$ARGUMENTS, limit=5); if ambiguous, present matches via AskUserQuestion.

If $ARGUMENTS is empty, classify the request from conversation context:

• Feature subtree: user mentions completing "everything under" a named item → search for that item, use rootId
• Specific items: user lists names or IDs → collect each UUID, use itemIds
• Cleanup: user wants to clear old/stale items → search by status or title fragment, collect UUIDs, use itemIds

If scope still cannot be determined, ask via AskUserQuestion: "Which item (or items) do you want to complete? Provide a root UUID, a title fragment, or a list of item IDs."

Step 2 — Preview Impact

Before executing, show the user what will happen. Call:

query_items(operation="overview", itemId="<rootId>")

Parse the child counts by role and present a preview table. Use the trigger chosen (or likely to be chosen) to set the action label — trigger="complete" shows "will be completed"; trigger="cancel" shows "will be cancelled":

◆ Impact Preview — "Auth System Feature"  [trigger: complete]
  ○ queue:    3 items (will be completed)
  ◉ work:     1 item  (active — will be force-completed)
  ◉ review:   1 item  (active — will be force-completed)
  ✓ terminal: 2 items (already done — will be skipped)

◆ Impact Preview — "Auth System Feature"  [trigger: cancel]
  ○ queue:    3 items (will be cancelled)
  ◉ work:     1 item  (active — will be force-cancelled)
  ◉ review:   1 item  (active — will be force-cancelled)
  ✓ terminal: 2 items (already done — will be skipped)

For itemIds path (no root item): call query_items(operation="get", itemId=" ") on each item and build the same role-grouped preview table from the individual results. For large lists (10+ items), use query_items(operation="search") with filters instead of individual get calls.

If any items are in work or review, warn the user that active work will be force-completed (gate checks still apply). Use AskUserQuestion with three options:

◆ 2 items are currently active (work or review).
  How would you like to proceed?
  1. Proceed — complete everything including active items
  2. Cancel active items instead — use trigger="cancel" (bypasses gates)
  3. Abort — leave everything as-is

Wait for the user's choice before continuing. Record whether to use trigger="complete" or trigger="cancel".

Step 3 — Gate Check

Skip this step if trigger="cancel" was already chosen in Step 2 — cancel bypasses all gates, so gate checking is unnecessary.

For trigger="complete", gate previewing is best-effort. complete_tree performs the definitive gate check during execution and reports any failures in its response. A lightweight pre-check is still useful to surface issues before committing — call get_context on each child from Step 2's results rather than on the root item (the root itself is not completed by complete_tree, only its descendants are):

get_context(itemId="<child-uuid>")   ← repeat for each child listed in Step 2

If any child's gate status shows missing required notes, display them:

⊘ Gate Warnings (preview — definitive check runs at execution):
  "Implement login" — missing: implementation-notes (work, required)
  "Write tests" — missing: session-tracking (work, required)