@chris1807/claude-kit 2.1.59 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.59",
+  "version": "2.2.0",
   "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/cherry-pick.md

@@ -33,6 +33,37 @@ Fetch each work item from Azure DevOps via MCP. Compare each one's `System.State
 Cherry-pick {count} work items to {environment}? Items behind the gate: include / drop / cancel
 ```
 
+### Step 1b: Scripts That Have to Be Run
+
+A deployment script — a SQL migration, a data backfill, a PowerShell step — is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in. A promotion carries the code; it does not carry the script, and nothing in the PR says one exists. That is how an environment ends up half-deployed.
+
+Fetch each carried work item with its attachments — `wit_work_item` `action: get`, `expand: "Relations"`, one call per item (`get_batch` has no `expand`) — and keep every relation whose `rel` is `AttachedFile` and whose filename extension is **not** a document, image or video:
+
+```
+.xlsx .xls .xlsm .xlsb .csv  .docx .doc .docm  .pdf
+.png .jpg .jpeg .gif .bmp .ico .svg .webp .tiff .tif
+.mp4 .mov .avi .webm .mkv .wmv .flv .m4v
+```
+
+Everything else counts, extensionless files included. The rule is deliberately loose, because the two mistakes do not cost the same: a filename someone glances at and dismisses costs seconds, a migration nobody ran costs an environment.
+
+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 |
+
+Download them from the work items. This command does not run them.
+```
+
+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.
+
 Wait for confirmation. `drop` removes flagged items from this cherry-pick only.
 
 ## Step 2: Find Commits
@@ -91,7 +122,7 @@ Cherry-picking:
    - **sourceRefName**: `refs/heads/cherry-pick/<date>-to-<environment>`
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Cherry-pick AB#1234, AB#1235 → {Environment}`
-   - **description**: List all work items with IDs and titles
+   - **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`
 
 ## Step 6: Pick Who Verifies Each Group (before the merge)
@@ -319,3 +350,10 @@ Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stake
 ```
 
 If the user said `stop watching`, or an update fails, leave the rest alone, say exactly which items were and were not updated, and note that `/track` will flag the lag later.
+
+If any carried item had a deployment script (Step 1b), repeat it here — this is the moment it has to run, and the list is stale in the scroll-back by now:
+
+```
+📜 Still to run on {environment}: AB#1234 2026-09-11_add_delivery_index.sql, AB#1240 backfill-tenant-flags.ps1
+```
+

package/templates/commands/deploy-release.md

@@ -74,6 +74,37 @@ Include them anyway, or drop them from this deploy? (include / drop / cancel)
 
 Wait for the answer. `drop` removes them from **this deploy only** — they stay in the release.
 
+## Step 3b: Scripts That Have to Be Run
+
+A deployment script — a SQL migration, a data backfill, a PowerShell step — is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in. A promotion carries the code; it does not carry the script, and nothing in the PR says one exists. That is how an environment ends up half-deployed.
+
+Fetch each carried work item with its attachments — `wit_work_item` `action: get`, `expand: "Relations"`, one call per item (`get_batch` has no `expand`) — and keep every relation whose `rel` is `AttachedFile` and whose filename extension is **not** a document, image or video:
+
+```
+.xlsx .xls .xlsm .xlsb .csv  .docx .doc .docm  .pdf
+.png .jpg .jpeg .gif .bmp .ico .svg .webp .tiff .tif
+.mp4 .mov .avi .webm .mkv .wmv .flv .m4v
+```
+
+Everything else counts, extensionless files included. The rule is deliberately loose, because the two mistakes do not cost the same: a filename someone glances at and dismisses costs seconds, a migration nobody ran costs an environment.
+
+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 |
+
+Download them from the work items. This command does not run them.
+```
+
+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.
+
 ## Step 4: Confirm
 
 ```
@@ -147,7 +178,7 @@ Cherry-picking commits for Release #{N}:
    - **sourceRefName**: `refs/heads/release/{N}-to-<environment>`
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Release #{N} → {Environment}`
-   - **description**: List all work items included with their IDs and titles
+   - **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`
 
 ## Step 8: Pick Who Verifies Each Group (before the merge)
@@ -381,6 +412,13 @@ Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stake
 
 If the user said `stop watching`, or an update fails, leave the rest alone, say exactly which items were and were not updated, and note that `/track release {N}` will flag the lag later.
 
+If any carried item had a deployment script (Step 3b), repeat it here — this is the moment it has to run, and the list is stale in the scroll-back by now:
+
+```
+📜 Still to run on {environment}: AB#1234 2026-09-11_add_delivery_index.sql, AB#1240 backfill-tenant-flags.ps1
+```
+
+
 ## Step 11: Notify Team (if Teams MCP is configured)
 
 Send a notification to the project's Teams channel via the Microsoft Teams MCP server — once when the PR is created:

package/templates/commands/promote.md

@@ -79,6 +79,37 @@ Which? (1 / 2)
 
 For `main → dev` the gate is `Code Review`: an item still at `Code Review` whose commits are on `main` has had its PR merged, which is exactly right — not a warning. Features and Tasks are skipped. Items *ahead* of the gate are reported and left alone.
 
+## Step 3b: Scripts That Have to Be Run
+
+A deployment script — a SQL migration, a data backfill, a PowerShell step — is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in. A promotion carries the code; it does not carry the script, and nothing in the PR says one exists. That is how an environment ends up half-deployed.
+
+Fetch each carried work item with its attachments — `wit_work_item` `action: get`, `expand: "Relations"`, one call per item (`get_batch` has no `expand`) — and keep every relation whose `rel` is `AttachedFile` and whose filename extension is **not** a document, image or video:
+
+```
+.xlsx .xls .xlsm .xlsb .csv  .docx .doc .docm  .pdf
+.png .jpg .jpeg .gif .bmp .ico .svg .webp .tiff .tif
+.mp4 .mov .avi .webm .mkv .wmv .flv .m4v
+```
+
+Everything else counts, extensionless files included. The rule is deliberately loose, because the two mistakes do not cost the same: a filename someone glances at and dismisses costs seconds, a migration nobody ran costs an environment.
+
+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 |
+
+Download them from the work items. This command does not run them.
+```
+
+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.
+
 Then confirm: `Promote {count} commits from {source} to {target}? (yes/no)` — and wait.
 
 ## Step 4: Create PR
@@ -88,7 +119,7 @@ Create a PR directly from the source branch to the target branch via Azure DevOp
 - **sourceRefName**: `refs/heads/<source-branch>`
 - **targetRefName**: `refs/heads/<target-branch>`
 - **title**: `Promote {source} → {target}`
-- **description**: List all commits and associated work items being promoted
+- **description**: List all commits and associated work items being promoted, and — under a `Scripts to run` heading — any deployment scripts found in Step 3b, so whoever merges sees them without opening the work items
 
 Link the associated work items to the PR.
 
@@ -312,3 +343,10 @@ Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stake
 ```
 
 If the user said `stop watching`, or an update fails, leave the rest alone, say exactly which items were and were not updated, and note that `/track` will flag the lag later.
+
+If any carried item had a deployment script (Step 3b), repeat it here — this is the moment it has to run, and the list is stale in the scroll-back by now:
+
+```
+📜 Still to run on {target}: AB#1234 2026-09-11_add_delivery_index.sql, AB#1240 backfill-tenant-flags.ps1
+```
+

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -183,6 +183,14 @@ How the commands use this table:
 - **Assign the verifier at the same time.** The state change hands the item to a person, so the same three commands ask **before the merge** who each group of items should go to, then apply the assignee alongside the state once the pipeline is green. See **Verifier Assignment** below.
 - **Never assume the state list.** Confirm with `mcp__azure-devops__wit_work_item` (`action: get_type`) on an unfamiliar project before writing a state name — a bad name is accepted silently by a query and rejected only at write time.
 
+#### 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.
+
+`/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.
+
+**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
 
 Moving an item to `Testing`, `Staging`, or `Deployed` puts it on someone's plate, so `/promote`, `/cherry-pick`, and `/deploy-release` also change who owns it. The developer implemented it; from here on it belongs to whoever checks it in that environment.
@@ -303,10 +311,10 @@ All deployment and release operations are available as slash commands:
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/deploy` | `/deploy "commit message"` | Commit, push, trigger pipeline (only on `dev`/`test`/`staging`/`prod` — never on `main`) |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 |
-| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release to environment → PR → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
+| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → list deployment scripts → cherry-pick release to environment → PR → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
 | `/add-to-release` | `/add-to-release 24 AB#4599` | Add work items to existing release |
-| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items → PR → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
-| `/promote` | `/promote main dev` | Promote all code between environments (`main → dev → test → staging → prod`) → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
+| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → list deployment scripts → cherry-pick specific work items → PR → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
+| `/promote` | `/promote main dev` | Promote all code between environments (`main → dev → test → staging → prod`) → list deployment scripts → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
 | `/rollback` | `/rollback AB#1234 prod` | Revert commits on an environment |
 | `/track` | `/track release 24` | Check release, pipeline, environment, or work item status; flags work items whose state lags their environment |
 | `/where` | `/where AB#1234` | Show which environment branches contain a work item's commits |