@chris1807/claude-kit 2.1.48 → 2.1.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.48",
+  "version": "2.1.49",
   "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/create-work-item.md

@@ -320,9 +320,27 @@ A description that is one long paragraph of plain prose is not acceptable — ev
 - **Key terms, values, and outcomes** in each sentence are wrapped in `**bold**` (renders as `<strong>...</strong>`). Bold the noun phrase that carries the claim, not the whole sentence.
 - **Code identifiers** — method names, class names, field names, file paths, route paths, JSON keys, env vars, commit hashes, IDs, literal values like `true` / `null` / numeric thresholds — are wrapped in `` `code spans` `` (renders as `<code>...</code>`).
 - **Lists** are used instead of comma-separated prose whenever the draft contains 2+ parallel items (steps, files, references, acceptance criteria).
-- **Section headings** (`### Description`, `### Acceptance Criteria`, etc.) are kept — they become `<h3>` and structure the rendered output.
+- **Section headings** *inside a field's own content* are kept — they become `<h3>` and structure the rendered output. The draft's **top-level** section headings are different: they are routing labels, not content, and the heading is dropped when its section becomes its own field (see below).
 
-Apply this pass to every section (Description, Acceptance Criteria, Steps to Reproduce, Expected/Actual Behavior, Environment/Scope, Open Questions). Apply it equally to Bugs and User Stories.
+Apply this pass to every section (Description, Acceptance Criteria, Steps to Reproduce, Expected/Actual Behavior, Environment/Scope, Open Questions). Apply it equally to Bugs, Hot Fixes, and User Stories.
+
+### Split the draft into fields — acceptance criteria never go in the description
+
+The Step 3 draft is **one document for the user to read**, not the shape of one field. Before rendering, split it section by section and route each section to its own Azure DevOps field:
+
+| Draft section | Goes to | Notes |
+|---|---|---|
+| `### Description` | `System.Description` | Plus the mockup `<img>`, user-supplied images, `Production Impact` (Hot Fix), `Out of Scope`, and `Open Questions` |
+| `### Acceptance Criteria` | `Microsoft.VSTS.Common.AcceptanceCriteria` | **Never** also in the description |
+| `### Steps to Reproduce` | `Microsoft.VSTS.TCM.ReproSteps` (Bug / Hot Fix) | Falls back to the description only if the type doesn't expose the field |
+| `### Expected Behavior`, `### Actual Behavior` | `Microsoft.VSTS.TCM.ReproSteps` | Rendered beneath the repro steps |
+| `### Out of Scope`, `### Environment / Scope`, `### Open Questions` | `System.Description` | These keep their `<h3>` headings — they have no field of their own |
+
+**The rendered `System.Description` must not contain an "Acceptance Criteria" heading or its criteria** — not as `<h3>`, not as `<strong>`, not as a bolded line, not "for readability", not "so it reads as a complete document". Azure DevOps renders the AC field as its own section on the work item form, so a copy in the description gives the reader two lists that drift apart while leaving the real field empty. It also breaks estimation: an empty AC field is exactly what `/quote`, `/quote-backlog`, and `/plan-backlog` read to decide an item can't be sized, so criteria in the wrong field make a fully-specified story look unestimable and bounce it back to its creator.
+
+**Drop the section's own heading when it becomes a field.** `Microsoft.VSTS.Common.AcceptanceCriteria` holds the criteria list alone — an `<ol>` or `<ul>`, not `<h3>Acceptance Criteria</h3>` followed by the list. Same for `ReproSteps`. The field label is already on the form.
+
+**Always write the AC field explicitly — never leave the placeholder.** Some process templates seed a new item's `Microsoft.VSTS.Common.AcceptanceCriteria` with tip text like `💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`. That is a **placeholder, not content**, and it reads as non-empty to every downstream sweep — an item carrying it looks like it has acceptance criteria when it has none. Include the field in the create call for every Bug, Hot Fix, and User Story; writing it is what clears the placeholder.
 
 ### Call the create API
 
@@ -333,7 +351,7 @@ Call `mcp__azure-devops__wit_create_work_item` with:
 - **title**: the approved title (with prefix)
 - **fields**: a JSON Patch document setting:
   - `System.Description` — the rendered HTML description (with embedded mockup `<img>` and any user-supplied images)
-  - `Microsoft.VSTS.Common.AcceptanceCriteria` — the rendered HTML acceptance criteria block
+  - `Microsoft.VSTS.Common.AcceptanceCriteria` — the rendered criteria list and **only** the criteria (no `<h3>Acceptance Criteria</h3>` wrapper, and no copy of it in `System.Description`). Always include this field for a Bug, Hot Fix, or User Story — writing it is what clears the process template's placeholder tip
   - `Microsoft.VSTS.Scheduling.StoryPoints` — the points agreed in Step 4 (omit entirely if the user skipped, and **always** for a Feature)
   - For Features:
     - Render `Business Value`, `Scope`, `Out of Scope`, and `Success Criteria` into the description. Put `Success Criteria` in `Microsoft.VSTS.Common.AcceptanceCriteria` **only if** the process template exposes that field on Feature — if the create call rejects it, fold the block into the description and retry rather than dropping it.
@@ -392,6 +410,13 @@ If a story fails to create or link, report which ones succeeded and which didn't
 
 ## Step 10: Confirm
 
+**Read the item back first.** Fetch it with `mcp__azure-devops__wit_work_item` (`action: get`, fields `System.Description` and `Microsoft.VSTS.Common.AcceptanceCriteria`) and check two things:
+
+1. The criteria are in `Microsoft.VSTS.Common.AcceptanceCriteria` — not the placeholder tip, not empty.
+2. `System.Description` contains no "Acceptance Criteria" heading and none of the criteria.
+
+If either 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.
+
 After creation, report:
 
 ```
@@ -402,6 +427,7 @@ Created AB#{id}: {title}
   State: {Dev Ready | New}
   URL: {work item URL}
   Mockup attached: {yes / no}
+  Acceptance criteria: {n} criteria in the AC field (verified — none in the description)
   Open questions: {count}
 {Features only:}
   Child stories: {n created | none — add them later with /plan-backlog}

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

@@ -44,6 +44,11 @@ Present what exists today, so the user is editing against reality and not memory
 {end for Bugs}
 ```
 
+**Two things read as "this item has acceptance criteria" when it doesn't.** Check for both before showing the item, and say plainly which one you found:
+
+- **The field holds the process template's placeholder** — tip text like `💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`. Treat that as **empty** and display it as `(none — placeholder text only)`.
+- **The criteria are in `System.Description`** under an "Acceptance Criteria" heading, with the real field empty or placeholder-filled. This is the misfiled case. Display the criteria where they actually live, flag it, and offer the repair described in Step 7 — moving them costs the user nothing and unblocks estimation.
+
 For a **Feature**, append the current wave layout:
 
 ```
@@ -195,6 +200,15 @@ Default the comment question to **yes** for any item past `New`, and **no** for
 
 Render every Markdown section to HTML first — Azure DevOps description and acceptance criteria fields do not render Markdown. Use the conversion table and the **emphasis and code spans** rules from `/create-work-item` Step 8: bold the noun phrase carrying each claim, wrap identifiers in `<code>`, use lists for 2+ parallel items, keep `### Headings` as `<h3>`. Preserve existing `<img>` tags exactly.
 
+**Route each section to its own field**, per the field-routing table in `/create-work-item` Step 8. The rule that matters most here: **acceptance criteria go in `Microsoft.VSTS.Common.AcceptanceCriteria`, never in `System.Description`.** When you rewrite AC, write the criteria list alone into that field — no `<h3>Acceptance Criteria</h3>` wrapper — and make sure the description you write back carries no copy of them. Editing an item is the moment this gets silently undone: it is easy to render the whole reviewed document into the description and leave the AC field as it was.
+
+**Repair misfiled criteria when you find them.** If Step 2 found the criteria living in the description (or the AC field holding only placeholder tip text), fix it as part of this edit even when the user didn't ask — it is the same content, moved to the field Azure DevOps and every kit sweep actually read:
+
+- Write the criteria into `Microsoft.VSTS.Common.AcceptanceCriteria`, overwriting the placeholder.
+- Strip the "Acceptance Criteria" heading and its list out of `System.Description` in the same call, so the two fields don't both hold a copy.
+- Say so in the change set and in the Step 8 confirmation: `Acceptance criteria: moved from Description → AC field (3 criteria)`. Never move criteria silently; the user needs to see that the description shrank.
+- This is a **move, not a rewrite** — the criteria text is unchanged unless the user separately approved a reword.
+
 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.

package/templates/commands/quote-backlog.md

@@ -145,7 +145,7 @@ Score the item against this checklist:
 |-------|---------------------------|
 | **Title prefix** | Follows the project's `PREFIX - Title` convention (e.g. `COM -`, `PAY -`) |
 | **Description** | States what is being built and why — not just a one-line restatement of the title |
-| **Acceptance criteria** | Present, testable, unambiguous. Each AC could become a UAT step. Record whether the field is **empty** or merely **weak** — that distinction decides whether AC can be rewritten (3g) or must go back to the creator (3f) |
+| **Acceptance criteria** | Present, testable, unambiguous. Each AC could become a UAT step. Record whether the field is **empty** or merely **weak** — that distinction decides whether AC can be rewritten (3g) or must go back to the creator (3f). Two traps: the process template's **placeholder tip text** counts as **empty**, and criteria are sometimes **misfiled into `System.Description`** with the AC field left empty — check the description before declaring AC missing, and say where they actually are in the comment |
 | **Design artifacts** (User Story) | For UI work: a mockup, screenshot, or design link is attached or referenced (the story is Design Approved — the design should be findable) |
 | **Repro steps** (Bug) | The steps to reproduce, the expected result, and the actual result are all present. A bug swept at `New` has had no design pass, so this is the row that decides whether it's estimable — **a bug with no repro steps is a blocking gap** |
 | **Scope** | Small enough to point (would land at ≤ 21); no hidden second feature buried in the AC |
@@ -316,7 +316,7 @@ Only for approved items, in batch order:
 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.
 
-   **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, or an empty HTML shell like `<div></div>` or `<p><br></p>`.
+   **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.
 
 If a write fails, report the failure and ask whether to continue with the remaining items or stop.