@chris1807/claude-kit 2.2.2 → 2.2.4

package/README.md

@@ -279,6 +279,7 @@ Claude automatically:
 7. Generates a UAT checklist from acceptance criteria
 8. **Pauses for you to manually test**
 9. Creates the PR after you confirm
+10. **Attaches any hand-run deployment script** to the work item, with the run command in the attachment comment, so `/promote`, `/cherry-pick`, and `/deploy-release` list it for every environment. Data fixes are planned as run-once migrations the app applies by itself wherever the project has that mechanism; a hand-run script is the fallback and the plan says why
 
 **Implementing a whole Feature:** point `/implement` at a Feature work item and it implements the child User Stories in waves driven by the `Custom.Order` field — stories with the same order value are implemented in parallel (one agent per story, each in an isolated git worktree), and the next order value starts only after the previous wave is merged and green. Everything lands on one `feature/` branch with a single review, UAT pass, and PR that links every story.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Claude Code starter kit for Azure DevOps teams — agents, hooks, MCP servers, slash commands, and end-to-end work item → PR → release → deploy workflow automation",
   "type": "module",
   "bin": {

package/templates/commands/add-to-release.md

@@ -38,7 +38,7 @@ Wait for confirmation.
 
 ## Step 4: Assign and Tag
 
-Use `wit_update_work_items_batch` to:
+Use `wit_work_item_write` (action `update_batch`) to:
 1. Set the Iteration Path to `{project}\Release #{N}` on each new work item
 2. Append `release-{N}` to each work item's tags
 

package/templates/commands/cherry-pick.md

@@ -52,14 +52,16 @@ Show them with the table above, before the confirmation:
 ```
 📜 Scripts to run with this promotion:
 
-| Work Item | Script |
-|-----------|--------|
-| AB#1234 | 2026-09-11_add_delivery_index.sql |
-| AB#1240 | backfill-tenant-flags.ps1 |
+| Work Item | Script | How to run |
+|-----------|--------|------------|
+| AB#1234 | 2026-09-11_add_delivery_index.sql | sqlcmd -S <server> -d Compass -i 2026-09-11_add_delivery_index.sql |
+| AB#1240 | backfill-tenant-flags.ps1 | — |
 
 Download them from the work items. This command does not run them.
 ```
 
+`How to run` is the attachment's comment (`attributes.comment` on the relation) — `/implement` and `/rework` write the run command there when they attach a script. Show `—` when it is empty.
+
 If nothing carries an attachment, say `No deployment scripts attached` on one line and move on.
 
 **Reported, never enforced.** A script does not block the promotion and does not change the gate check: the attachment may already have been run, may be a reference copy, may not be a script at all. Listing it is the whole job — the person deploying decides.
@@ -123,7 +125,7 @@ Cherry-picking:
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Cherry-pick AB#1234, AB#1235 → {Environment}`
    - **description**: List all work items with IDs and titles, and — under a `Scripts to run` heading — any deployment scripts found in Step 1b, so whoever merges sees them without opening the work items
-3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
+3. Link all work items to the PR via `wit_work_item_link_write` (action `link_to_pull_request`)
 
 ## Step 6: Pick Who Verifies Each Group (before the merge)
 

package/templates/commands/close-orphan-tasks.md

@@ -16,7 +16,7 @@ All work items live in the **CSI Development** Azure DevOps project (see CLAUDE.
 
 ## Step 1: Find Orphaned Tasks
 
-Use the Azure DevOps MCP `wit_query_by_wiql` with a hierarchy link query. The Source is the parent, the Target is the child Task:
+Use the Azure DevOps MCP `wit_query` (action `wiql`) with a hierarchy link query. The Source is the parent, the Target is the child Task:
 
 ```sql
 SELECT [System.Id]
@@ -31,11 +31,11 @@ MODE (MustContain)
 
 If a **scope** was given, add the matching constraint to the `[Target]` clause (e.g. `AND [Target].[System.AreaPath] UNDER 'CSI Development\\Compass'`, or `AND [Target].[System.Title] CONTAINS 'PAY'`).
 
-> **Note on state names:** Process templates vary. Some projects close tasks to `Done` instead of `Closed`, or use `Resolved`. If the query returns nothing or errors on an unknown state, first confirm the valid states for the Task type via `wit_get_work_item_type`, then adjust the `NOT IN` list and the close target in Step 3 accordingly.
+> **Note on state names:** Process templates vary. Some projects close tasks to `Done` instead of `Closed`, or use `Resolved`. If the query returns nothing or errors on an unknown state, first confirm the valid states for the Task type via `wit_work_item` (action `get_type`), then adjust the `NOT IN` list and the close target in Step 3 accordingly.
 
 If the link query is unsupported or returns no usable pairs, fall back to: query all open Tasks in scope with a flat WIQL, fetch each task's parent via `relations`, and keep only those whose parent state is in the three target states.
 
-Fetch the matched tasks (and their parents) in a batch via `wit_get_work_items_batch_by_ids` to get titles, states, assignees, and parent context.
+Fetch the matched tasks (and their parents) in a batch via `wit_work_item` (action `get_batch`) to get titles, states, assignees, and parent context.
 
 ## Step 2: Present the Candidates
 
@@ -59,11 +59,11 @@ Otherwise, wait for explicit confirmation before proceeding. Never close tasks w
 
 ## Step 3: Close the Tasks
 
-For each confirmed task, use `wit_update_work_items_batch`:
+For each confirmed task, use `wit_work_item_write` (action `update_batch`):
 - **path**: `/fields/System.State`
 - **value**: `Closed` (or the project's terminal Task state confirmed in Step 1)
 
-Then add a comment on each via `wit_add_work_item_comment` so the auto-close is traceable:
+Then add a comment on each via `wit_work_item_comment_write` (action `add`) so the auto-close is traceable:
 
 > Auto-closed by `/close-orphan-tasks` — parent AB#{parentId} is in state "{parentState}".
 

package/templates/commands/create-release.md

@@ -38,13 +38,13 @@ Create a new iteration in Azure DevOps via `work_create_iterations`:
 
 ## Step 4: Assign Work Items to the Release
 
-Use `wit_update_work_items_batch` to set the Iteration Path on each work item to the new release iteration:
+Use `wit_work_item_write` (action `update_batch`) to set the Iteration Path on each work item to the new release iteration:
 - **path**: `/fields/System.IterationPath`
 - **value**: `{project}\Release #{N}`
 
 ## Step 5: Tag Work Items
 
-Use `wit_update_work_items_batch` to add a release tag to each work item:
+Use `wit_work_item_write` (action `update_batch`) to add a release tag to each work item:
 - **path**: `/fields/System.Tags`
 - **value**: append `release-{N}` to existing tags
 

package/templates/commands/create-work-item.md

@@ -404,7 +404,7 @@ This applies to **User Story**. It does **not** apply to Bug or Hot Fix: neither
 
 ### Call the create API
 
-Call `mcp__azure-devops__wit_create_work_item` with:
+Call `mcp__azure-devops__wit_work_item_write` (action `create`) with:
 
 - **project**: the chosen project
 - **workItemType**: `Feature`, `Bug`, `User Story`, or `Hot Fix` (two words, exact casing)
@@ -431,7 +431,7 @@ If the `Open Questions` section is non-empty, append it as a clearly-labeled HTM
 
 ### Move to Dev Ready (pointed items only)
 
-If story points were agreed in Step 4, set `System.State` to `Dev Ready` via `mcp__azure-devops__wit_update_work_item` **after** the item is created (a separate call — new items start in `New`, and some process templates reject a non-initial state in the create call). If the state transition is rejected, report the error and leave the state as-is — don't silently retry through intermediate states. Items created without points stay in `New`.
+If story points were agreed in Step 4, set `System.State` to `Dev Ready` via `mcp__azure-devops__wit_work_item_write` (action `update`) **after** the item is created (a separate call — new items start in `New`, and some process templates reject a non-initial state in the create call). If the state transition is rejected, report the error and leave the state as-is — don't silently retry through intermediate states. Items created without points stay in `New`.
 
 **Features are never moved.** A Feature stays in `New` and advances only as its child stories are verified and closed — the same rule `/implement` follows.
 
@@ -462,7 +462,7 @@ On `yes`:
    ```
 
    **Wait for the user.** Revise and re-present until approved. Do not create anything before approval.
-5. On approval, create each story with `mcp__azure-devops__wit_create_work_item` in the same project, setting:
+5. On approval, create each story with `mcp__azure-devops__wit_work_item_write` (action `create`) in the same project, setting:
    - `System.Description` and `Microsoft.VSTS.Common.AcceptanceCriteria` — rendered to HTML per the Step 8 rules
    - `Custom.Order` — the wave number
    - `Microsoft.VSTS.Scheduling.StoryPoints` — the agreed points
@@ -489,7 +489,7 @@ For a **Bug**, fetch `Microsoft.VSTS.TCM.ReproSteps` and `Microsoft.VSTS.TCM.Sys
 
 For a **Hot Fix**, fetch `System.Description` and `Microsoft.VSTS.TCM.ReproSteps`, and confirm the narrative is in the former and the reproduction detail in the latter.
 
-If a check fails the write didn't take — fix it with `wit_update_work_item` before reporting success. Don't report a created item you haven't read back.
+If a check fails the write didn't take — fix it with `wit_work_item_write` (action `update`) before reporting success. Don't report a created item you haven't read back.
 
 After creation, report:
 

package/templates/commands/deploy-release.md

@@ -20,7 +20,7 @@ Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** t
 
 ## Step 1: Read the Release
 
-Query Azure DevOps for all work items tagged with `release-{N}` or assigned to the `Release #{N}` iteration using `search_workitem` or `wit_get_work_items_for_iteration`.
+Query Azure DevOps for all work items tagged with `release-{N}` or assigned to the `Release #{N}` iteration using `search_workitem` or `wit_work_item` (action `list_for_iteration`).
 
 Present the release contents:
 
@@ -93,14 +93,16 @@ Show them with the gate check, before Step 4's confirmation:
 ```
 📜 Scripts to run with this promotion:
 
-| Work Item | Script |
-|-----------|--------|
-| AB#1234 | 2026-09-11_add_delivery_index.sql |
-| AB#1240 | backfill-tenant-flags.ps1 |
+| Work Item | Script | How to run |
+|-----------|--------|------------|
+| AB#1234 | 2026-09-11_add_delivery_index.sql | sqlcmd -S <server> -d Compass -i 2026-09-11_add_delivery_index.sql |
+| AB#1240 | backfill-tenant-flags.ps1 | — |
 
 Download them from the work items. This command does not run them.
 ```
 
+`How to run` is the attachment's comment (`attributes.comment` on the relation) — `/implement` and `/rework` write the run command there when they attach a script. Show `—` when it is empty.
+
 If nothing carries an attachment, say `No deployment scripts attached` on one line and move on.
 
 **Reported, never enforced.** A script does not block the promotion and does not change the gate check: the attachment may already have been run, may be a reference copy, may not be a script at all. Listing it is the whole job — the person deploying decides.
@@ -179,7 +181,7 @@ Cherry-picking commits for Release #{N}:
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Release #{N} → {Environment}`
    - **description**: List all work items included with their IDs and titles, and — under a `Scripts to run` heading — any deployment scripts found in Step 3b, so whoever merges sees them without opening the work items
-3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
+3. Link all work items to the PR via `wit_work_item_link_write` (action `link_to_pull_request`)
 
 ## Step 8: Pick Who Verifies Each Group (before the merge)
 

package/templates/commands/edit-work-item.md

@@ -230,9 +230,9 @@ Render every Markdown section to HTML first — Azure DevOps description and acc
 
 Apply writes in this order, so a failure partway through leaves the most useful state behind:
 
-1. **Update the parent item** — one `mcp__azure-devops__wit_update_work_item` call with every changed field. Never include `System.State` for a Feature.
+1. **Update the parent item** — one `mcp__azure-devops__wit_work_item_write` (action `update`) call with every changed field. Never include `System.State` for a Feature.
 2. **Update existing children** (verdict `Update`) — one call per story, points and `Custom.Order` in the same call as the text changes. If points were set on a story still at or before `Dev Ready`, set `System.State` = `Dev Ready` in that same call.
-3. **Create added children** — `mcp__azure-devops__wit_create_work_item` with description, acceptance criteria, `Custom.Order`, agreed `Microsoft.VSTS.Scheduling.StoryPoints`, and `System.AssignedTo` copied from the Feature if it has an assignee. Then link each to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse`), then move pointed ones to `Dev Ready` in a follow-up call.
+3. **Create added children** — `mcp__azure-devops__wit_work_item_write` (action `create`) with description, acceptance criteria, `Custom.Order`, agreed `Microsoft.VSTS.Scheduling.StoryPoints`, and `System.AssignedTo` copied from the Feature if it has an assignee. Then link each to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse`), then move pointed ones to `Dev Ready` in a follow-up call.
 4. **Re-order** any story whose only change is `Custom.Order` — one call each, touching that field alone.
 5. **Retire** stories the user approved — set `System.State` = `Removed`, or remove the parent link, whichever the user chose. **Never delete a work item.**
 6. **Post comments** (if the user said yes) via `mcp__azure-devops__wit_work_item_comment_write` — one short comment per edited item saying what changed and why, and naming the Feature edit that drove it (e.g. `Scope updated via edit of AB#6240: acceptance criteria 2 reworded to cover SSO; re-ordered from wave 3 to wave 2.`).

package/templates/commands/implement.md

@@ -32,7 +32,7 @@ The description and acceptance criteria fields may contain embedded images (scre
 
 ### Comments
 
-Read the work item comments via `wit_list_work_item_comments`. Comments often contain clarifications, scope changes, or additional requirements added after the work item was created. Incorporate any relevant information from comments into your understanding of the work item.
+Read the work item comments via `wit_work_item` (action `list_comments`). Comments often contain clarifications, scope changes, or additional requirements added after the work item was created. Incorporate any relevant information from comments into your understanding of the work item.
 
 ## Step 2: Summarize and Confirm
 
@@ -98,7 +98,7 @@ Each question below is about a cost that is cheap now and expensive once the cod
 | 2 | **Is each piece in the right layer?** Domain / Application / Infrastructure / API boundaries hold — no business rules in a controller, no Mongo or EF types in Domain, no HTTP concepts below API. | An `IMongoCollection<T>` parameter on a Domain method |
 | 3 | **What is the simplest plan that still meets every AC?** State it, then adopt it or say in one line why the heavier one is needed. | An interface with exactly one implementation, added "for testability" |
 | 4 | **What else touches the files being modified?** Name the callers. A change to a shared contract, DTO, or response shape is a breaking change until proven otherwise. | Editing a shared DTO with no note about its other consumers |
-| 5 | **What happens to data that already exists?** New required fields, schema changes, and backfills each need an answer for rows written before this change. | A non-nullable field added with no default and no backfill |
+| 5 | **What happens to data that already exists?** New required fields, schema changes, and backfills each need an answer for rows written before this change — and the answer should run itself: the project's run-once migration mechanism if it has one, not a script someone has to remember in every environment (see **Deployment Scripts** in CLAUDE.md). | A non-nullable field added with no default and no backfill; a `backfill.js` to run by hand on test, staging and prod when the API already runs one-time migrations at startup |
 | 6 | **How does it fail?** Partial failure, concurrent callers, a retried request. Is the operation idempotent, and does it need to be? | A multi-step write with no story for a crash between steps |
 | 7 | **Does it hold at real data volume?** Queries inside loops, unbounded result sets, a missing index, a list endpoint with no paging. | A `foreach` over accounts issuing one query each |
 | 8 | **Is it safe?** Authorization on every new endpoint, and **no sensitive field** (TIN, SSN, EIN, TaxId, BankAccountNumber, RoutingNumber, any `Encrypted*`) read, logged, returned, or projected — see the sensitive-data rule in CLAUDE.md. | A new endpoint returning a whole entity because it was convenient |
@@ -131,6 +131,10 @@ Present the plan to the user:
 ### Files to Delete (if any)
 - `path/to/old/file.cs` — {why it's being removed}
 
+### Data Changes (if any)
+- {what changes in existing data} — **automated** by {the project's run-once mechanism}: `{file}`
+- {what changes in existing data} — **hand-run** `{script path}`, because {which Deployment Scripts reason applies}. Attached to the work item when the PR goes up.
+
 ### Unit Tests
 - `path/to/new.tests.cs` — covers {scenario 1}, {scenario 2}, {edge case}
 - `path/to/existing.tests.cs` — adds cases for {new behavior}
@@ -188,12 +192,14 @@ Remember the `BASE_BRANCH` — you will need it for the PR step.
 
 ### Move the Work Item to Active
 
-Once the branch is created, move the work item (User Story, Bug, Hot Fix, or other single work item — never a Feature) to `Active` via `wit_update_work_item`:
+Once the branch is created, move the work item (User Story, Bug, Hot Fix, or other single work item — never a Feature) to `Active` via `wit_work_item_write` (action `update`):
 - **path**: `/fields/System.State`
 - **value**: `Active`
 
 If the work item is already `Active`, skip the update. If the project's process template does not have an `Active` state (the update call returns an invalid-state error), fall back in this order: `In Progress` → `Doing` → leave the current state and warn the user that the state could not be advanced automatically. Do not silently swallow the error.
 
+After the update, **read the work item back** (`wit_work_item`, action `get`) and confirm `System.State` actually changed. If it didn't, say so explicitly — do not proceed reporting the item as in progress when the board still shows it otherwise.
+
 ### Ensure an Open Child Task Exists
 
 The child **Task** is where hours live: Step 10 closes it and logs the hours worked when the PR goes up. So an implementation run must never proceed without one — if there's nothing to close, nothing gets logged.
@@ -264,7 +270,7 @@ Create it? (yes / edit / skip)
 - `edit` → ask what to change (title or hours), revise, re-show, ask again
 - `skip` → continue without a Task, and **warn** that Step 10 will have no Task to close and no hours will be logged for this story
 
-On `yes`, create it with `mcp__azure-devops__wit_create_work_item`:
+On `yes`, create it with `mcp__azure-devops__wit_work_item_write` (action `create`):
 
 - **workItemType**: `Task`
 - **title**: `{PREFIX} - Implement: {short summary of the story}` — reuse the parent's product prefix (`COM`, `PAY`, `CDA`, …), extracted from the parent's title
@@ -275,7 +281,7 @@ On `yes`, create it with `mcp__azure-devops__wit_create_work_item`:
   - `System.AssignedTo` — copy from the parent (pass the parent's `uniqueName` / email if the value is an identity object). If the parent is unassigned, leave it unset rather than failing.
   - `System.State` — `Active`, since implementation is starting right now (fall back to the template's in-progress equivalent, or leave it at the default and note it)
 
-Then link it as a child of the work item with `mcp__azure-devops__wit_add_child_work_items` (or `wit_work_items_link` with `System.LinkTypes.Hierarchy-Forward`, parent → task).
+Then link it as a child of the work item with `mcp__azure-devops__wit_work_item_write` (action `add_child`) (or `wit_work_item_link_write` (action `link`) with `System.LinkTypes.Hierarchy-Forward`, parent → task).
 
 If the create or link call fails, report it and ask whether to implement without a Task or stop. Don't silently continue — the user needs to know hours won't be tracked.
 
@@ -387,15 +393,26 @@ Wait for the user's response before proceeding. Do NOT create a PR until confirm
    - **targetRefName**: `refs/heads/{BASE_BRANCH}` (the branch captured in Step 4)
    - **title**: `AB#{id}: {work item title}`
    - **labels**: `["hotfix"]` if the work item type is Hot Fix
-3. Link the PR to the work item via `wit_link_work_item_to_pull_request`
-4. **Close related Tasks and log hours** — see "Closing Related Tasks" below.
-5. **Move the work item to `Code Review`** via `wit_update_work_item`:
+3. Link the PR to the work item via `wit_work_item_link_write` (action `link_to_pull_request`)
+4. **Attach deployment scripts** — see "Attaching Deployment Scripts" below.
+5. **Close related Tasks and log hours** — see "Closing Related Tasks" below.
+6. **Move the work item to `Code Review`** via `wit_work_item_write` (action `update`):
    - **path**: `/fields/System.State`
    - **value**: `Code Review`
 
    If the project's process template does not have a `Code Review` state (the update call returns an invalid-state error), fall back in this order: `Resolved` → `In Review` → leave the current state and warn the user that the state could not be advanced automatically. Do not silently swallow the error.
 
-> **Only the Task ever gets closed — never the parent.** The child Task is closed here, at PR creation (step 4 above). When the PR is later completed/merged, do **not** enable Azure DevOps's "Complete associated work items" option: it transitions *every* linked work item, including the parent this PR is linked to. The parent User Story or Bug stays in `Code Review`: merging this PR into `main` deploys nothing, and promoting to `dev` deploys the code but **leaves the state alone** — the developer moves it to `Ready for Testing` once they have checked it on Dev. From there `/promote` and `/deploy-release` advance it to `Testing` → `Staging` → `Deployed` across `test → staging → prod` (see **Work Item States ↔ Environments** in CLAUDE.md).
+> **Only the Task ever gets closed — never the parent.** The child Task is closed here, at PR creation (step 5 above). When the PR is later completed/merged, do **not** enable Azure DevOps's "Complete associated work items" option: it transitions *every* linked work item, including the parent this PR is linked to. The parent User Story or Bug stays in `Code Review`: merging this PR into `main` deploys nothing, and promoting to `dev` deploys the code but **leaves the state alone** — the developer moves it to `Ready for Testing` once they have checked it on Dev. From there `/promote` and `/deploy-release` advance it to `Testing` → `Staging` → `Deployed` across `test → staging → prod` (see **Work Item States ↔ Environments** in CLAUDE.md).
+
+### Attaching Deployment Scripts
+
+A script that has to be run by hand — a SQL migration, a data backfill, a rename — is useless to the next environment if it only lives in the repo: `/promote`, `/cherry-pick` and `/deploy-release` find scripts on the **work item**, never in the diff. So every one this change adds or modifies is attached to the work item now, not left for someone to remember.
+
+List the files the PR adds or modifies (`git diff --name-only --diff-filter=AM {BASE_BRANCH}...HEAD`) and pick out the ones a person runs by hand, once per environment. The test: if the UAT checklist, the PR, or your report tells someone to run it, it's one of these. App code, tests, build tooling and migrations the app or pipeline applies by itself are not. Each one should already be in the approved plan's **Data Changes** section with its reason for not being automated. A hand-run script that isn't there still gets attached, but say plainly that it wasn't in the plan.
+
+Attach each one per **Deployment Scripts** in CLAUDE.md — upload through the REST API (the MCP server can only download), link it as an `AttachedFile` whose comment holds the repo path and the exact run command with the environment as a placeholder, and replace a stale same-name attachment rather than adding a second copy. Never attach a file with a connection string, key, password, or sensitive field value in it.
+
+Report it on one line per script — `📜 Attached to AB#{id}: {file} — {how to run}` — or `No deployment scripts in this change` when there are none. A failed upload does not undo the PR; say `⚠️ NOT attached: {file} → AB#{id}` with the error and keep going.
 
 ### Closing Related Tasks
 
@@ -452,7 +469,7 @@ For each task being processed, prompt for completed hours:
 
 **Wait for the user's response on every task.** Accept the suggested/current value (enter), a new numeric value, or `skip` to leave that one untouched.
 
-Once the user has answered, update each task in a **single** `wit_update_work_item` call per task:
+Once the user has answered, update each task in a **single** `wit_work_item_write` (action `update`) call per task:
 - `Microsoft.VSTS.Scheduling.CompletedWork` → the agreed value
 - `Microsoft.VSTS.Scheduling.RemainingWork` → `0`
 - `Microsoft.VSTS.Scheduling.OriginalEstimate` → only if it is still empty; set it to the agreed completed hours so the Task isn't left with no estimate at all. Never overwrite an estimate that's already there — the gap between estimate and actual is the useful signal.
@@ -557,6 +574,7 @@ Present **one combined UAT checklist grouped by story** (Step 9 rules). Wait for
 
 1. Push the feature branch and create **one PR**: title `AB#{feature-id}: {feature title}`, source `feature/...`, target `BASE_BRANCH`.
 2. Link the **Feature and every implemented story** to the PR.
-3. Run **Closing Related Tasks** (Step 10) once, covering the child Tasks of every implemented story — one combined table, then the usual per-task hour prompts. Every story that got a Task in F4 has one to close here; a story whose Task creation was skipped gets one created and closed now, as in Step 10.
-4. Move each implemented story to `Code Review` (same fallback rules as Step 10). **Do not change the Feature's state** — the Feature is a parent container; it advances only when its child stories are verified/closed, not when the PR goes up for review.
-5. The Step 10 closing rule applies unchanged: only child **Tasks** are ever closed — here at PR creation, never the stories and never the Feature. Don't enable "Complete associated work items" when the PR is merged; it would transition the stories and the Feature along with the Tasks.
+3. Run **Attaching Deployment Scripts** (Step 10) over the whole feature diff. Each script goes on the **story** whose change needs it — never on the Feature, which promotions don't gate.
+4. Run **Closing Related Tasks** (Step 10) once, covering the child Tasks of every implemented story — one combined table, then the usual per-task hour prompts. Every story that got a Task in F4 has one to close here; a story whose Task creation was skipped gets one created and closed now, as in Step 10.
+5. Move each implemented story to `Code Review` (same fallback rules as Step 10). **Do not change the Feature's state** — the Feature is a parent container; it advances only when its child stories are verified/closed, not when the PR goes up for review.
+6. The Step 10 closing rule applies unchanged: only child **Tasks** are ever closed — here at PR creation, never the stories and never the Feature. Don't enable "Complete associated work items" when the PR is merged; it would transition the stories and the Feature along with the Tasks.

package/templates/commands/plan-backlog.md

@@ -27,7 +27,7 @@ If the user types `list`, call `mcp__azure-devops__core_list_projects` and prese
 
 ## Step 2: Query the Backlog
 
-Run a WIQL query via `mcp__azure-devops__wit_query_by_wiql` to find candidate stories. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
+Run a WIQL query via `mcp__azure-devops__wit_query` (action `wiql`) to find candidate stories. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
 
 ```sql
 SELECT [System.Id], [System.Title], [System.State],
@@ -55,7 +55,7 @@ and stop.
 
 ## Step 3: Filter Out Stories That Already Have Child Tasks
 
-For each candidate from Step 2, fetch the work item with `mcp__azure-devops__wit_get_work_item` expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
+For each candidate from Step 2, fetch the work item with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
 
 Present a one-line summary of what was skipped:
 
@@ -175,7 +175,7 @@ Approve? (yes / edit / skip / cancel-all)
 
 ### 5e. Create the child task
 
-Create the approved task with `mcp__azure-devops__wit_create_work_item`:
+Create the approved task with `mcp__azure-devops__wit_work_item_write` (action `create`):
 
 - **project**: the chosen project
 - **workItemType**: `Task`
@@ -187,7 +187,7 @@ Create the approved task with `mcp__azure-devops__wit_create_work_item`:
   - `System.AreaPath` — copy from the parent
   - `System.AssignedTo` — copy from the parent (pass the parent's `uniqueName` / email if its `System.AssignedTo` value is an identity object). If the parent is unassigned, leave this field unset rather than failing.
 
-Then link the new task as a child of the parent with `mcp__azure-devops__wit_add_child_work_items` (or fall back to `wit_work_items_link` with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
+Then link the new task as a child of the parent with `mcp__azure-devops__wit_work_item_write` (action `add_child`) (or fall back to `wit_work_item_link_write` (action `link`) with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
 
 If the create or link call fails, report the failure and ask the user whether to continue with the next story or abort the loop.
 

package/templates/commands/plan-sprint.md

@@ -44,7 +44,7 @@ and stop.
 
 ## Step 3: Query the Sprint
 
-Run a WIQL query via `mcp__azure-devops__wit_query_by_wiql` using the **literal iteration path** from Step 2:
+Run a WIQL query via `mcp__azure-devops__wit_query` (action `wiql`) using the **literal iteration path** from Step 2:
 
 ```sql
 SELECT [System.Id], [System.Title], [System.State],
@@ -73,7 +73,7 @@ and stop.
 
 ## Step 4: Filter Out Items That Already Have Child Tasks
 
-For each candidate from Step 3, fetch the work item with `mcp__azure-devops__wit_get_work_item` expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
+For each candidate from Step 3, fetch the work item with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
 
 Present a one-line summary of what was skipped:
 
@@ -196,7 +196,7 @@ For unpointed items, the header line reads `(no points — estimated from descri
 
 ### 6e. Create the child task
 
-Create the approved task with `mcp__azure-devops__wit_create_work_item`:
+Create the approved task with `mcp__azure-devops__wit_work_item_write` (action `create`):
 
 - **project**: the chosen project
 - **workItemType**: `Task`
@@ -208,7 +208,7 @@ Create the approved task with `mcp__azure-devops__wit_create_work_item`:
   - `System.AreaPath` — copy from the parent
   - `System.AssignedTo` — copy from the parent (pass the parent's `uniqueName` / email if its `System.AssignedTo` value is an identity object). If the parent is unassigned, leave this field unset rather than failing.
 
-Then link the new task as a child of the parent with `mcp__azure-devops__wit_add_child_work_items` (or fall back to `wit_work_items_link` with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
+Then link the new task as a child of the parent with `mcp__azure-devops__wit_work_item_write` (action `add_child`) (or fall back to `wit_work_item_link_write` (action `link`) with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
 
 If the create or link call fails, report the failure and ask the user whether to continue with the next item or abort the loop.
 

package/templates/commands/promote.md

@@ -98,14 +98,16 @@ Show them with the gate check, before the confirmation:
 ```
 📜 Scripts to run with this promotion:
 
-| Work Item | Script |
-|-----------|--------|
-| AB#1234 | 2026-09-11_add_delivery_index.sql |
-| AB#1240 | backfill-tenant-flags.ps1 |
+| Work Item | Script | How to run |
+|-----------|--------|------------|
+| AB#1234 | 2026-09-11_add_delivery_index.sql | sqlcmd -S <server> -d Compass -i 2026-09-11_add_delivery_index.sql |
+| AB#1240 | backfill-tenant-flags.ps1 | — |
 
 Download them from the work items. This command does not run them.
 ```
 
+`How to run` is the attachment's comment (`attributes.comment` on the relation) — `/implement` and `/rework` write the run command there when they attach a script. Show `—` when it is empty.
+
 If nothing carries an attachment, say `No deployment scripts attached` on one line and move on.
 
 **Reported, never enforced.** A script does not block the promotion and does not change the gate check: the attachment may already have been run, may be a reference copy, may not be a script at all. Listing it is the whole job — the person deploying decides.

package/templates/commands/quote-backlog.md

@@ -91,7 +91,7 @@ If the user types `list`, call `mcp__azure-devops__core_list_projects` and prese
 
 ## Step 2: Query the Backlog
 
-Run a WIQL query via `mcp__azure-devops__wit_query_by_wiql` to find candidate items. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
+Run a WIQL query via `mcp__azure-devops__wit_query` (action `wiql`) to find candidate items. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
 
 ```sql
 SELECT [System.Id], [System.Title], [System.State],
@@ -203,7 +203,7 @@ For each item in the batch, do all of 3a–3e before presenting anything. Collec
 
 ### 3a. Fetch the full work item
 
-Fetch with `mcp__azure-devops__wit_get_work_item` expanding `relations`. Capture: title, type, description, acceptance criteria, tags, `System.CreatedBy` (display name + unique name — needed for the comment draft), child items, and any linked PRs, commits, or branches.
+Fetch with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. Capture: title, type, description, acceptance criteria, tags, `System.CreatedBy` (display name + unique name — needed for the comment draft), child items, and any linked PRs, commits, or branches.
 
 ### 3b. Completeness review
 
@@ -368,8 +368,8 @@ Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / apply rewrite N / cance
 
 Only for approved items, in batch order:
 
-1. **Set Story Points and move to Dev Ready** (items with a proposed number): in one `mcp__azure-devops__wit_update_work_item` call, set `Microsoft.VSTS.Scheduling.StoryPoints` **and** `System.State` = `Dev Ready`. The state change applies only to `User Story`, `Bug`, and `Hot Fix` types, and never moves an item backward — if an item is somehow already past Dev Ready, set the points only and note it. Touch no other field — assignee, iteration, and tags stay as they are.
-2. **Send unquotable User Stories back to Design Review** (approved `User Story` items with **no** proposed points, where the blocker is missing information): set `System.State` = `Design Review` via `mcp__azure-devops__wit_update_work_item`. Do this **before** posting the comment in step 4, so the creator's notification arrives with the item already back in their queue. Rules:
+1. **Set Story Points and move to Dev Ready** (items with a proposed number): in one `mcp__azure-devops__wit_work_item_write` (action `update`) call, set `Microsoft.VSTS.Scheduling.StoryPoints` **and** `System.State` = `Dev Ready`. The state change applies only to `User Story`, `Bug`, and `Hot Fix` types, and never moves an item backward — if an item is somehow already past Dev Ready, set the points only and note it. Touch no other field — assignee, iteration, and tags stay as they are.
+2. **Send unquotable User Stories back to Design Review** (approved `User Story` items with **no** proposed points, where the blocker is missing information): set `System.State` = `Design Review` via `mcp__azure-devops__wit_work_item_write` (action `update`). Do this **before** posting the comment in step 4, so the creator's notification arrives with the item already back in their queue. Rules:
 
    - **`User Story` only.** Do not attempt this on a `Bug` or a `Hot Fix` — those types have no `Design Review` state, so the update fails at runtime in the middle of the batch. They take step 3 instead.
    - Only from `Design Approved` — **never move an item backward past the design stage.** An item at `Dev Ready`, or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready for Staging`, `Staging`, `Ready to Deploy`, …), keeps its state; note it in the summary instead.
@@ -387,8 +387,8 @@ Only for approved items, in batch order:
    - Skip items whose only finding is **needs to be split** — nothing is missing, so no tag.
    - Touch no other field — points stay empty; assignee, iteration, and state stay as they are.
 
-4. **Post the comment** (items with an approved draft): add it with `mcp__azure-devops__wit_add_work_item_comment` (or the server's work-item comment tool). Use the mention syntax the server supports so the creator is notified; otherwise lead with their display name as drafted. For a story that just moved to Design Review, the comment must say so — the creator needs to know why it left their Design Approved column. For a bug that just got the `needs-info` tag, the comment must say that too, and say that removing the tag re-queues it.
-5. **Apply the rewrite** (only items the user marked `apply rewrite N`): update `System.Description` (and `System.Title` if the rewrite included one) via `wit_update_work_item`, and adjust the comment to say the rewrite was applied ("rewrote the description/AC per the above — please review") rather than suggesting it. Never apply a rewrite the user didn't explicitly mark.
+4. **Post the comment** (items with an approved draft): add it with `mcp__azure-devops__wit_work_item_comment_write` (action `add`) (or the server's work-item comment tool). Use the mention syntax the server supports so the creator is notified; otherwise lead with their display name as drafted. For a story that just moved to Design Review, the comment must say so — the creator needs to know why it left their Design Approved column. For a bug that just got the `needs-info` tag, the comment must say that too, and say that removing the tag re-queues it.
+5. **Apply the rewrite** (only items the user marked `apply rewrite N`): update `System.Description` (and `System.Title` if the rewrite included one) via `wit_work_item_write` (action `update`), and adjust the comment to say the rewrite was applied ("rewrote the description/AC per the above — please review") rather than suggesting it. Never apply a rewrite the user didn't explicitly mark.
 
    **Guard on `Microsoft.VSTS.Common.AcceptanceCriteria`:** write it only if the item's AC field was **non-empty** when fetched in 3a. Re-check the fetched value at write time — if it was blank, drop AC from the update payload and write the other fields. Blank means no criteria at all: empty string, whitespace, an empty HTML shell like `<div></div>` or `<p><br></p>`, **or the process template's placeholder tip text** (`💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`). The placeholder is the one that bites — it is a stored, non-empty field value that means the exact opposite of what its length suggests.
 

package/templates/commands/quote.md

@@ -111,7 +111,7 @@ After displaying the estimate, ask the user: *"Want me to set Story Points = {n}
 
 Only update the work item if the user explicitly says yes. Do not modify anything otherwise.
 
-When the user agrees, in the **same** `wit_update_work_item` call:
+When the user agrees, in the **same** `wit_work_item_write` (action `update`) call:
 
 1. Set `Microsoft.VSTS.Scheduling.StoryPoints` to the agreed value (the user's number wins if they adjusted it).
 2. Set `System.State` to `Dev Ready` — **but only if** the work item type is `User Story`, `Bug`, or `Hot Fix` **and** the item is not already past Dev Ready in the workflow (e.g. `Active`, `Code Review`, `Testing`, `Staging`, `Ready to Deploy`). Never move an item backward — if it's already past Dev Ready, set the points only and mention the state was left alone.
@@ -134,7 +134,7 @@ In the CSI Development process template, `Bug` and `Hot Fix` have **no design st
 
 > *"I can't size this until {what's missing}. Want me to move AB#{id} back to Design Review so it's out of the next `/quote-backlog` sweep until the creator responds?"*
 
-**Wait for the user.** Only update the work item if they say yes. Then set `System.State` = `Design Review` with `mcp__azure-devops__wit_update_work_item`. Rules:
+**Wait for the user.** Only update the work item if they say yes. Then set `System.State` = `Design Review` with `mcp__azure-devops__wit_work_item_write` (action `update`). Rules:
 
 - **`User Story` only** — never a Bug, Hot Fix, Feature, or Task. A Bug takes 5b; the update would fail on it anyway.
 - **Never move an item backward past the design stage.** Only from `Design Approved`; if it's already `Dev Ready` or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready for Staging`, `Staging`, `Ready to Deploy`, …), leave the state alone and say so — someone is already working on it, and a state bounce there does real damage.
@@ -146,7 +146,7 @@ In the CSI Development process template, `Bug` and `Hot Fix` have **no design st
 
 > *"I can't size this until {what's missing} — and a Bug has no design state to send it back to. Want me to tag AB#{id} `needs-info` so it drops out of the next `/quote-backlog` sweep? Removing the tag is what re-queues it — a reply alone leaves it excluded, though `/quote-backlog`'s stale-tag audit will surface it."*
 
-**Wait for the user.** Only update the work item if they say yes. Then add the tag with `mcp__azure-devops__wit_update_work_item`. Rules:
+**Wait for the user.** Only update the work item if they say yes. Then add the tag with `mcp__azure-devops__wit_work_item_write` (action `update`). Rules:
 
 - **Append to `System.Tags`, never replace it.** Take the current tag list captured in Step 1, append `needs-info`, and write the whole semicolon-separated list back. Writing the field bare wipes tags someone else set — `release-{N}`, triage labels, scope hints.
 - Already tagged `needs-info` → no-op; say it's already there.

package/templates/commands/rework.md

@@ -36,13 +36,13 @@ Save the PR's `creationDate` as `LAST_PR_DATE` — everything after this timesta
 
 ### New Comments
 
-Read the work item comments via `wit_list_work_item_comments`. Filter to only comments created **after** `LAST_PR_DATE`. These contain the rework feedback.
+Read the work item comments via `wit_work_item` (action `list_comments`). Filter to only comments created **after** `LAST_PR_DATE`. These contain the rework feedback.
 
 For each new comment, check for embedded images (`<img>` tags with `src` URLs pointing to Azure DevOps attachments). **Download and view every embedded image** using WebFetch — they often contain screenshots of bugs, visual issues, or annotated UI showing what needs to change.
 
 ### Description & Acceptance Criteria Changes
 
-Read the work item revisions via `wit_list_work_item_revisions`. Check if the **description** or **acceptance criteria** fields were modified **after** `LAST_PR_DATE`.
+Read the work item revisions via `wit_work_item` (action `list_revisions`). Check if the **description** or **acceptance criteria** fields were modified **after** `LAST_PR_DATE`.
 
 - If changed: extract the **current** description and acceptance criteria, and note what was added or modified
 - If unchanged: still read the current description and acceptance criteria — a comment may reference something that was in the original requirements but missing from the implementation
@@ -123,7 +123,7 @@ Each question below is about a cost that is cheap now and expensive once the cod
 | 2 | **Is each piece in the right layer?** Domain / Application / Infrastructure / API boundaries hold — no business rules in a controller, no Mongo or EF types in Domain, no HTTP concepts below API. | An `IMongoCollection<T>` parameter on a Domain method |
 | 3 | **What is the simplest plan that still meets every AC?** State it, then adopt it or say in one line why the heavier one is needed. | An interface with exactly one implementation, added "for testability" |
 | 4 | **What else touches the files being modified?** Name the callers. A change to a shared contract, DTO, or response shape is a breaking change until proven otherwise. | Editing a shared DTO with no note about its other consumers |
-| 5 | **What happens to data that already exists?** New required fields, schema changes, and backfills each need an answer for rows written before this change. | A non-nullable field added with no default and no backfill |
+| 5 | **What happens to data that already exists?** New required fields, schema changes, and backfills each need an answer for rows written before this change — and the answer should run itself: the project's run-once migration mechanism if it has one, not a script someone has to remember in every environment (see **Deployment Scripts** in CLAUDE.md). | A non-nullable field added with no default and no backfill; a `backfill.js` to run by hand on test, staging and prod when the API already runs one-time migrations at startup |
 | 6 | **How does it fail?** Partial failure, concurrent callers, a retried request. Is the operation idempotent, and does it need to be? | A multi-step write with no story for a crash between steps |
 | 7 | **Does it hold at real data volume?** Queries inside loops, unbounded result sets, a missing index, a list endpoint with no paging. | A `foreach` over accounts issuing one query each |
 | 8 | **Is it safe?** Authorization on every new endpoint, and **no sensitive field** (TIN, SSN, EIN, TaxId, BankAccountNumber, RoutingNumber, any `Encrypted*`) read, logged, returned, or projected — see the sensitive-data rule in CLAUDE.md. | A new endpoint returning a whole entity because it was convenient |
@@ -158,6 +158,10 @@ Present the plan to the user:
 ### Files to Delete (if any)
 - `path/to/old/file.cs` — {why it's being removed}
 
+### Data Changes (if any)
+- {what changes in existing data} — **automated** by {the project's run-once mechanism}: `{file}`
+- {what changes in existing data} — **hand-run** `{script path}`, because {which Deployment Scripts reason applies}. Attached to the work item when the PR goes up.
+
 ### Unit Tests
 - `path/to/new.tests.cs` — covers {scenario the rework adds or fixes}
 - `path/to/existing.tests.cs` — updates assertions for {changed behavior}
@@ -236,7 +240,7 @@ Enter the estimated hours for this task (press enter to accept {n}):
 
 If the user provided hours (suggested or overridden):
 
-1. Call `mcp__azure-devops__wit_create_work_item`:
+1. Call `mcp__azure-devops__wit_work_item_write` (action `create`):
    - **workItemType**: `Task`
    - **title**: `Rework AB#{id} — round {N}`
    - **fields**: JSON Patch document setting:
@@ -262,8 +266,9 @@ If the user provided hours (suggested or overridden):
      - `System.AreaPath` — same as the parent
      - `System.IterationPath` — same as the parent
      - `System.AssignedTo` — same as the parent (copy the parent's `System.AssignedTo` value; pass the `uniqueName` / email if the parent's value is an identity object). If the parent is unassigned, leave this field unset rather than failing.
+     - `System.State` — `Active`, since the rework starts right now (fall back to the template's in-progress equivalent, or leave it at the default and note it). A rework Task left at `New` while the work is underway misreports the board.
 
-2. Link the new Task as a child of the parent work item via `wit_work_items_link`:
+2. Link the new Task as a child of the parent work item via `wit_work_item_link_write` (action `link`):
    - **type**: `Child` (the parent → child link from the parent's perspective; equivalent to `Parent` from the task's perspective)
    - **source**: parent work item ID
    - **target**: new task ID
@@ -282,6 +287,18 @@ The work item already has a branch from the previous PR. Switch to it:
 
 If the PR was completed/merged and the branch was deleted, create a new branch from the PR's target branch following the same naming convention as `/implement` Step 4.
 
+### Move the Work Item to Active
+
+Once you are on the branch, move the work item (User Story, Bug, Hot Fix, or other single work item — **never** a Feature) to `Active` via `wit_work_item_write` (action `update`):
+- **path**: `/fields/System.State`
+- **value**: `Active`
+
+Rework restarts implementation, so the item must leave `Code Review` / `Rework` and go back to in-progress for the duration of this round — Step 12 hands it back to `Code Review` when the fixes are pushed. Without this the item sits in a review state while it is actively being worked, and the board lies.
+
+If the work item is already `Active`, skip the update. If the project's process template does not have an `Active` state (the update call returns an invalid-state error), fall back in this order: `In Progress` → `Doing` → leave the current state and warn the user that the state could not be advanced automatically. Do not silently swallow the error.
+
+After the update, **read the work item back** (`wit_work_item`, action `get`) and confirm `System.State` actually changed. If it didn't, say so explicitly — do not proceed reporting the item as in progress when the board still shows it otherwise.
+
 ## Step 7: Implement
 
 1. **Implement** the rework using backend and/or frontend agents according to the approved plan
@@ -375,9 +392,10 @@ Wait for the user's response before proceeding. Do NOT push until confirmed.
 ## Step 12: Push and Update
 
 1. Push the changes: `git push`
-2. **Do not post a rework summary comment.** Do not add a summary of what changed to the work item Discussion (`wit_add_work_item_comment`) or as a PR thread. The pushed commits and the PR diff are the record of what changed — a prose summary duplicates them and clutters the work item. If the reviewer left specific PR comment threads, reply on those threads directly (that is what `/resolve-feedback` and `/fix-review` do); otherwise post nothing.
-3. **Close related Tasks and log hours** — see "Closing Related Tasks" below. This includes the rework Task created in Step 5 as well as any other child Tasks that became `Completed` as a result of this rework round.
-4. **Move the work item back to `Code Review`** via `wit_update_work_item`:
+2. **Do not post a rework summary comment.** Do not add a summary of what changed to the work item Discussion (`wit_work_item_comment_write` (action `add`)) or as a PR thread. The pushed commits and the PR diff are the record of what changed — a prose summary duplicates them and clutters the work item. If the reviewer left specific PR comment threads, reply on those threads directly (that is what `/resolve-feedback` and `/fix-review` do); otherwise post nothing.
+3. **Attach deployment scripts.** Run `/implement`'s **Attaching Deployment Scripts** step against this branch — diff it against the PR's target branch (`git diff --name-only --diff-filter=AM {target}...HEAD`), so a script the original PR added and never attached is caught too. A script this rework changed is already attached in its old form: replace that attachment, don't add a second copy — a promotion that lists both versions invites someone to run the stale one. Same rules and report lines as in `/implement` (see **Deployment Scripts** in CLAUDE.md).
+4. **Close related Tasks and log hours** — see "Closing Related Tasks" below. This includes the rework Task created in Step 5 as well as any other child Tasks that became `Completed` as a result of this rework round.
+5. **Move the work item back to `Code Review`** via `wit_work_item_write` (action `update`):
    - **path**: `/fields/System.State`
    - **value**: `Code Review`
 
@@ -440,7 +458,7 @@ For each task being processed, prompt for completed hours:
 
 **Wait for the user's response on every task.** Accept the suggested/current value (enter), a new numeric value, or `skip` to leave that one untouched.
 
-Once the user has answered, update each task via `wit_update_work_item`:
+Once the user has answered, update each task via `wit_work_item_write` (action `update`):
 - `Microsoft.VSTS.Scheduling.CompletedWork` → the agreed value
 - `Microsoft.VSTS.Scheduling.RemainingWork` → `0`
 - `System.State` → `Closed` (fall back to `Done` if the project's task template uses Agile; warn if neither is valid)

package/templates/commands/track.md

@@ -49,7 +49,7 @@ Deployed to:
 Catch these up? (yes/no)
 ```
 
-If the user says yes, set `System.State` on each lagging item to the expected state via `wit_update_work_item` — never backward, never on a Feature or Task — and report `Was → Now`.
+If the user says yes, set `System.State` on each lagging item to the expected state via `wit_work_item_write` (action `update`) — never backward, never on a Feature or Task — and report `Was → Now`.
 
 ## If Pipeline (e.g., `/track pipeline` or `/track build`):
 

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -185,10 +185,48 @@ How the commands use this table:
 
 #### Deployment Scripts
 
-A SQL migration or a backfill script is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in — test, then staging, then prod. The promotion carries the code, never the script.
+A SQL migration, a data backfill, a rename script — anything someone has to **run by hand** against an environment — is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in — test, then staging, then prod. The promotion carries the code, never the script.
 
 `/promote`, `/cherry-pick` and `/deploy-release` therefore read the carried items' attachments (`wit_work_item` `action: get`, `expand: "Relations"`) and list any that look like something to run: an `AttachedFile` whose extension is **not** a document, image or video (`.docx .xlsx .csv .pdf .png .jpg .mp4` and friends). Everything else counts — the rule is loose on purpose, because a filename glanced at and dismissed costs seconds while a migration nobody ran costs an environment. The list appears before the confirmation, in the PR description, and again once the pipeline is green, which is when it actually has to be run.
 
+**Automate first — a hand-run script is the fallback.** When a change needs existing data corrected, backfilled or renamed, Claude plans it through the project's own run-once migration mechanism if it has one: a seeder that records finished migrations (COMPASS's `DataSeeder` and its `dataMigrations` collection), EF Core migrations applied at startup, DbUp, a migration step the pipeline already runs. Those run by themselves on every environment's deploy, after the new code is live, with the app's own connection string — nothing to remember, nothing to attach. A hand-run script is right only when the change can't live there, and the plan names which reason applies:
+
+- the project has no such mechanism — building one is its own work item, never folded into this one;
+- the script creates the database or tenant the app would run in (provisioning);
+- it touches something outside the app's own data stores (Azure resources, another system);
+- a person has to check the result before it is applied.
+
+**Claude always attaches the hand-run script it writes.** Committing it to the repo is not enough: the promotion commands look for scripts on the work item, never in the repo, so an unattached script is reported as `No deployment scripts attached` and goes unrun in staging or prod. Whenever Claude writes one — in `/implement`, `/rework`, or any other session — or tells someone to run one that isn't attached yet, it attaches it before finishing:
+
+- **Which files.** A file in the change that a person runs by hand, once per environment: `.sql`, a Mongo script, a `.sh` / `.ps1` / `.py` / `.js` data fix. The test: if the UAT checklist, the PR, or Claude's report tells someone to run it, it gets attached. Not app code, not tests or build tooling, not a migration the app or the pipeline applies by itself.
+- **Which work item.** The one whose change needs it. In a Feature run, the child story — never the Feature.
+- **The comment says how to run it.** The attachment comment carries the repo path and the exact command, with the environment as a placeholder (e.g. `scripts/tenant-provisioning/rename-manager-roles.sh — after each environment's deploy: RMR_CONFIRM='apply <Env>' scripts/…/rename-manager-roles.sh apply <Env>`). Whoever deploys to prod next month won't have this session.
+- **No secrets in the file.** Never attach a script with a connection string, key, password, or sensitive field value in it — the script reads those from the environment. If it can't, stop and tell the user instead of attaching.
+- **Replace, don't duplicate.** If an attachment with the same filename is already on the item, compare it with the repo copy (`curl` the attachment's `url` into `diff`). Identical → leave it. Different → swap it in one PATCH (`remove` the old relation by its index, then `add` the new one), so a promotion never lists two versions of one script.
+
+The Azure DevOps MCP server can only *download* attachments, so the upload goes through the REST API with an `az` token. The org and project GUID come from the work item's own `url` (`https://dev.azure.com/{org}/{projectId}/_apis/wit/workItems/{id}`):
+
+```bash
+TOKEN=$(az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv)
+BASE="https://dev.azure.com/{org}/{projectId}/_apis/wit"
+
+# 1. Upload the bytes — the response JSON carries the attachment "url"
+curl -sS -X POST "$BASE/attachments?fileName={file name}&api-version=7.1" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/octet-stream" \
+  --data-binary @"{repo path}"
+
+# 2. Link it to the work item. The body goes in a scratch file, because the run command
+#    in the comment usually has quotes that break inline JSON:
+#    [{"op":"test","path":"/rev","value":{rev from a fresh get}},
+#     {"op":"add","path":"/relations/-","value":{"rel":"AttachedFile","url":"{attachment url}",
+#      "attributes":{"comment":"{repo path} — {how to run}"}}}]
+curl -sS -X PATCH "$BASE/workitems/{id}?api-version=7.1" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json-patch+json" \
+  --data-binary @"{scratch dir}/attach-patch.json"
+```
+
+Never print the token. If `az` has no session, swap the bearer header for `-u ":$AZURE_DEVOPS_PAT"`; if neither works, ask the user to run `! az login`. A failed attachment never blocks the PR, and it is never skipped quietly — the summary says `⚠️ NOT attached: {file} → AB#{id}` so it can be fixed before the first promotion.
+
 **Reported, never enforced.** A script never blocks a promotion and never changes the gate check — it may already have been run, or be a reference copy. The person deploying decides; the commands only make sure nobody finds out afterwards.
 
 #### Verifier Assignment