@chris1807/claude-kit 2.1.44 → 2.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.44",
+  "version": "2.1.45",
   "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/quote-backlog.md

@@ -13,7 +13,10 @@ This command walks the **backlog** of a chosen Azure DevOps project, finds user
 
 **Hard batch limit: 10 items per run.** If more qualify, process the first 10 (by backlog rank) and report how many remain.
 
-**Nothing is written to Azure DevOps — no points, no comments — until the user has seen the full batch and approved.** This command never modifies code and never reassigns items. The only state change it makes: when approved points are written to an item, that item also moves to **Dev Ready** (see Step 5).
+**Nothing is written to Azure DevOps — no points, no comments — until the user has seen the full batch and approved.** This command never modifies code and never reassigns items. It makes exactly two kinds of state change, both in Step 5:
+
+- an item that **gets points** moves to **Dev Ready**;
+- an item that **can't be quoted** because information is missing moves back to **Design Review**, so the next sweep doesn't pick it up again while the creator is still working on it.
 
 Treat `$ARGUMENTS` as an optional project name (e.g. `/quote-backlog CSI Development`). If provided, skip the project prompt in Step 1.
 
@@ -34,7 +37,7 @@ Nothing is written to Azure DevOps until you approve the batch — every option
 | `all` | Everything proposed gets applied |
 | `1,2,4` | Only those numbered items get applied; the rest are recorded as skipped |
 | `edit N` | I pause on item N so you can change my proposal, then re-show it |
-| `skip N` | Item N is dropped from the batch; I re-ask about the rest |
+| `skip N` | Item N is dropped from the batch — nothing written, so it stays in Design Approved and shows up again next sweep |
 | `apply rewrite N` | Item N's rewrite is written **onto the work item** instead of only suggested |
 | `cancel` | Stop with zero changes |
 
@@ -42,6 +45,7 @@ Numbers refer to the `#` column of the summary table, not to AB# ids — so `1,2
 
 **What approval writes:**
 - **Story Points** on items that got a number — each also moves from Design Approved to **Dev Ready**
+- **Design Review** on items that couldn't be quoted — anything blocked on missing information goes back to the creator's queue so the next sweep skips it
 - **Comments** to the creators of items where something was found
 - **Rewrites** — description, and a tightened version of AC that already exist — only for items you explicitly marked `apply rewrite N`
 
@@ -169,6 +173,13 @@ Use the **modified Fibonacci scale**: `1, 2, 3, 5, 8, 13, 21`. Anything larger t
 
 Fold in what 3d found — code reconnaissance that shrinks or grows the work changes the number. For items classified **Blocking gaps** or **appears already implemented**, propose **no points** — the comment is the deliverable for those.
 
+**An item that gets no points goes back to Design Review.** Whenever the reason for not pointing an item is *we need more information* — missing AC, contradictory description, unclear scope, or a possible duplicate the creator has to confirm — record that the item should move from `Design Approved` back to `Design Review` alongside its comment. That state is what keeps the next `/quote-backlog` run from re-analyzing an item that is still waiting on its creator; leaving it in `Design Approved` guarantees it comes back in the next batch unchanged.
+
+Two cases are the exception — no state change, because nothing is missing:
+
+- **Needs to be split** (the work is understood, it's just too big) — the item stays in `Design Approved`; the deliverable is the split proposal.
+- The user chooses to leave it alone at the Step 4 gate.
+
 ### 3f. Draft the creator comment (only if issues were found)
 
 If 3b–3d surfaced anything — gaps, a duplicate, a suggested approach change — draft a comment addressed to the item's creator (`System.CreatedBy`). Format:
@@ -183,7 +194,7 @@ If 3b–3d surfaced anything — gaps, a duplicate, a suggested approach change
 - This looks already implemented in AB#{id} / PR #{n} ({file or feature}) — can you confirm it's still needed?
 - Suggested approach change: {what the code shows, what to do instead}
 
-{Closing line: what's needed to make it estimable, or "Estimated at {n} points assuming {assumption} — correct me if that's wrong."}
+{Closing line: what's needed to make it estimable — and, when the item is going back to Design Review, say so plainly: "Moving this back to Design Review until that's answered — ping me and I'll re-quote it." Or, when it was pointed: "Estimated at {n} points assuming {assumption} — correct me if that's wrong."}
 ```
 
 **When the AC field is empty, report it — don't fill it.** Say the acceptance criteria are missing and that the item can't be estimated without them, and ask the creator for them. Never follow that with a drafted list, a "here's a starting point:" section, or criteria inferred from the title. Existing AC are a different case — those can be rewritten in 3g.
@@ -216,17 +227,20 @@ Show the whole batch **before writing anything**. Start with the summary table:
 Quote sweep — {project} backlog, Design Approved without Story Points
 Batch: {n} of {total} qualifying items{ — run /quote-backlog again for the next 10}
 
-| #  | ID       | Title                                  | Completeness  | Points | Comment | Rewrite |
-|----|----------|----------------------------------------|---------------|--------|---------|---------|
-| 1  | AB#4611  | COM - Payment reminder emails          | Complete      |   5    | —       | —       |
-| 2  | AB#4614  | COM - Bulk close inactive accounts     | Minor gaps    |   8    | yes     | —       |
-| 3  | AB#4617  | PAY - Refund webhook handling          | Blocking gaps |   —    | yes     | yes     |
-| 4  | AB#4620  | COM - Export audit log                 | Already done? |   —    | yes     | —       |
+| #  | ID       | Title                              | Completeness  | Points | State           | Comment | Rewrite |
+|----|----------|------------------------------------|---------------|--------|-----------------|---------|---------|
+| 1  | AB#4611  | COM - Payment reminder emails      | Complete      |   5    | → Dev Ready     | —       | —       |
+| 2  | AB#4614  | COM - Bulk close inactive accounts | Minor gaps    |   8    | → Dev Ready     | yes     | —       |
+| 3  | AB#4617  | PAY - Refund webhook handling      | Blocking gaps |   —    | → Design Review | yes     | yes     |
+| 4  | AB#4620  | COM - Export audit log             | Already done? |   —    | → Design Review | yes     | —       |
+| 5  | AB#4623  | COM - Rebuild the reporting module | Too large     |  split | unchanged       | yes     | —       |
 ```
 
+The **State** column is what will actually be written: `→ Dev Ready` for pointed items, `→ Design Review` for items that can't be quoted until the creator supplies something, and `unchanged` for anything else (a split proposal, or an item already past Dev Ready).
+
 Then a detail block per item — estimate reasoning (2–3 bullets), completeness findings, duplicate evidence with links/IDs, code notes, the **full text of any draft comment**, and the **full text of any suggested rewrite**. The user must be able to read every word that would be posted.
 
-Note above the prompt: **items that get points will also move to Dev Ready** — approving the points approves the state change.
+Note above the prompt: **approving an item approves its state change too** — pointed items move to Dev Ready, and items that couldn't be quoted move back to Design Review so the next sweep skips them. Name the items in each group so the user can see exactly which ones leave `Design Approved` and in which direction.
 
 Then ask:
 
@@ -236,11 +250,11 @@ Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / apply rewrite N / cance
 
 **Wait for the user.**
 
-- `all` → apply every proposed write (points and comments) in Step 5; rewrites stay inside the comments as suggestions
+- `all` → apply every proposed write (points, state changes, and comments) in Step 5; rewrites stay inside the comments as suggestions
 - `1,2,4` → apply only those items; the rest are recorded as skipped
 - `edit N` → ask what to change on item N (points value, comment text, or rewrite text), revise, re-show that item, ask again
 - `apply rewrite N` → write item N's rewrite directly onto the work item in Step 5 (instead of only suggesting it in the comment). This covers the description, the title if the rewrite included one, and rewritten AC **only where the item already had AC** — an empty AC field is never populated, under this or any other option
-- `skip N` → drop item N, re-ask for the rest
+- `skip N` → drop item N, re-ask for the rest. A skipped item gets **nothing** written — no comment, and no move to Design Review, so it stays in `Design Approved` and will reappear in the next sweep. Say that out loud when confirming a skip, so the user isn't surprised to see it again
 - `cancel` → stop with **zero changes** to Azure DevOps
 
 ## Step 5: Apply Approved Changes
@@ -248,8 +262,17 @@ 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. **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.
-3. **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.
+2. **Move unquotable items back to Design Review** (approved 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 3, so the creator's notification arrives with the item already back in their queue. Rules:
+
+   - Only for `User Story`, `Bug`, and `Hot Fix` types.
+   - 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 to Deploy`, …), keeps its state; note it in the summary instead.
+   - Skip items whose only finding is **needs to be split** — the work is understood, so nothing is missing; leave those in `Design Approved`.
+   - If the item is already in `Design Review`, this is a no-op — post the comment and move on.
+   - If the project's process template has no `Design Review` state (the update returns an invalid-state error), fall back in this order: `In Design` → `New` → leave the state alone and **warn the user** that the item will be picked up again by the next sweep. Do not silently swallow the error.
+   - Touch no other field — points stay empty, assignee, iteration, and tags stay as they are.
+
+3. **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 an item that just moved to Design Review, the comment must say so — the creator needs to know why it left their Design Approved column.
+4. **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>`.
 
@@ -262,23 +285,28 @@ If a write fails, report the failure and ask whether to continue with the remain
 
 Items analyzed:   {n} (of {total} qualifying — {remaining} left for the next run)
   ✓ Points set:   {n_pointed}  (total {sum} pts — each moved to Dev Ready)
+  ↩ Design Review: {n_design_review} not quoted — moved back to the creator, out of the next sweep
   ✓ Comments:     {n_comments} posted to creators
   ✓ Rewrites:     {n_rewrites_applied} applied, {n_rewrites_suggested} suggested in comments
   ⚑ AC missing:   {n_ac_missing} items sent back to the creator to write their acceptance criteria
-  ⏭ Skipped:      {n_skipped} ({reasons: user skipped / blocking gaps / possible duplicate})
+  ⏭ Skipped:      {n_skipped} left in Design Approved — will reappear next sweep ({reasons})
 
 Pointed items:
 - AB#4611: 5 pts
 - AB#4614: 8 pts (comment posted)
 - ...
 
-Flagged for the creator (no points yet):
+Moved back to Design Review (no points — waiting on the creator):
 - AB#4617: blocking gaps — AC missing failure cases
-- AB#4620: possibly already implemented in AB#4102
+- AB#4620: possibly already implemented in AB#4102 — needs confirmation
+
+Left in Design Approved:
+- AB#4623: too large to point — split proposal in the comment
+- AB#4625: you skipped it
 
 Next steps:
   /quote-backlog {project}   — process the next 10 qualifying items
   /quote AB#{id}             — re-estimate a single item after the creator responds
 ```
 
-Do not create tasks or assign items — those are downstream decisions. Pointed items are now Dev Ready, so `/plan-backlog` picks them up on its next run. Make no state change other than the points→Dev Ready move described in Step 5.
+Do not create tasks or assign items — those are downstream decisions. Pointed items are now Dev Ready, so `/plan-backlog` picks them up on its next run. Items moved to Design Review are out of the `Design Approved` query, so the next `/quote-backlog` run reaches genuinely new items instead of re-reviewing the ones still waiting on their creator — re-quote one with `/quote AB#{id}` once they respond, or let them move it back to Design Approved themselves. Make no state change other than the two described in Step 5.

package/templates/commands/quote.md

@@ -34,6 +34,8 @@ Adjust downward for: pure config changes, mechanical refactors with good test co
 
 If the item has child items, size each child as well and present the parent's total as the sum (rounded to the nearest Fibonacci number).
 
+**If the item can't be estimated at all, don't guess a number.** An item is *not estimable* when the gap is information only its creator can close — no acceptance criteria, a description that contradicts itself, scope you can't bound, or work that looks like it may already be done under another ticket. Report it as **needs more information**, list exactly what's missing, and go to Step 5 instead of Step 4. This is different from **needs to be split**: a split candidate is understood work that's simply too big, and it keeps its current state.
+
 ## Step 3: Display the Estimate
 
 Output a compact estimate — not a quote block. Format:
@@ -64,8 +66,20 @@ If an existing `Story Points` value is already set on the work item and your est
 
 If the work looks larger than 21 points, do not assign a number — instead report `**Estimate:** needs to be split` and suggest 2–4 candidate split points based on the acceptance criteria.
 
+If the item isn't estimable, report that instead of a number:
+
+```
+**AB#{id}: {title}**
+**Estimate:** needs more information
+
+**Blocking:**
+- {what's missing, and what you'd need to know to size it}
+```
+
 ## Step 4: Offer to Persist (Points + Dev Ready)
 
+This step applies when you produced a **number**. If the item was reported as *needs more information*, skip to Step 5.
+
 After displaying the estimate, ask the user: *"Want me to set Story Points = {n} on AB#{id}? (This will also move it to Dev Ready.)"*
 
 Only update the work item if the user explicitly says yes. Do not modify anything otherwise.
@@ -76,3 +90,23 @@ When the user agrees, in the **same** `wit_update_work_item` call:
 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`, `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.
 
 **Never change the state of a Feature or a Task** — if the sized item is a Feature, persist points only (or per-child points on the children, each of which does get Dev Ready if it qualifies).
+
+## Step 5: Offer to Send Unquotable Items Back (Design Review)
+
+When the item came out of Step 2 as **needs more information**, offer to move it back so it drops out of the estimating queue:
+
+> *"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.
+
+When they agree, set `System.State` = `Design Review` with `mcp__azure-devops__wit_update_work_item`. Rules:
+
+- Only for `User Story`, `Bug`, and `Hot Fix` types — **never** a Feature or a Task.
+- **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 to Deploy`, …), leave the state alone and say so — someone is already working on it, and a state bounce there does real damage.
+- Already in `Design Review` → no-op; say it's already there.
+- No `Design Review` state in the process template (the update returns an invalid-state error) → fall back in this order: `In Design` → `New` → leave the state alone and **warn** that the item will keep surfacing in backlog sweeps. Don't swallow the error.
+- Set **no** story points and touch no other field — assignee, iteration, and tags stay as they are.
+
+Why it matters: `/quote-backlog` sweeps `Design Approved` items with no points. An item left in `Design Approved` while waiting on its creator gets re-analyzed in every sweep, so moving it to `Design Review` is what keeps the next run reaching new items. Re-quote it with `/quote AB#{id}` once the creator responds.
+
+**Items that only need to be split keep their state** — the work is understood, so there's nothing to send back. Same for an item where you got a number: that path ends at Step 4.

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -112,6 +112,7 @@ These rules apply to **every** command or flow that creates or estimates work it
 1. **Every work item Claude creates gets a proposed story point estimate** — User Stories and Bugs are never created unpointed by default. Estimates use the modified Fibonacci scale (`1, 2, 3, 5, 8, 13, 21`), calibrated for a **senior developer working with Claude assistance** — no ramp-up padding; pad only for what seniority + Claude can't shortcut (novel work, missing AC, cross-team coordination, external dependencies).
 2. **The user must agree before points are written.** Claude proposes the number with a one-line rationale; the user confirms, adjusts (their number wins), or skips. Points are never set silently.
 3. **Setting points moves the item to Dev Ready.** Any time story points are written to a **User Story**, **Bug**, or **Hot Fix**, `System.State` is set to `Dev Ready` in the same update. Never for Features or Tasks (a Feature's state is never touched; Tasks carry hour estimates, not points), and never backward — an item already past Dev Ready keeps its state, with a note.
+4. **An item that can't be quoted goes back to Design Review.** When `/quote` or `/quote-backlog` can't produce a number because information is missing — no acceptance criteria, contradictory description, unbounded scope, or a possible duplicate the creator has to confirm — the item moves from `Design Approved` back to `Design Review` along with the feedback comment. This keeps the next backlog sweep from re-analyzing items still waiting on their creator. Same guards as rule 3: `User Story` / `Bug` / `Hot Fix` only, and only from `Design Approved` — an item at `Dev Ready` or anything `Active` or later keeps its state. An item that merely **needs to be split** keeps its state — the work is understood, nothing is missing.
 
 ### Branching Strategy
 
@@ -252,8 +253,8 @@ All deployment and release operations are available as slash commands:
 | `/status` | `/status release 24` | Check release, pipeline, or work item status |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose child tasks with hours |
 | `/plan-sprint` | `/plan-sprint [project]` | Sweep the current sprint for stories/bugs with no child tasks → propose one child task with hours per item |
-| `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for Design Approved items without points → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated; approved points also move the item to Dev Ready) |
-| `/quote` | `/quote AB#1234` | Estimate story points for one work item; on approval, sets the points and moves the item to Dev Ready |
+| `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for Design Approved items without points → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated). Pointed items move to Dev Ready; items that can't be quoted move back to **Design Review** so the next sweep skips them |
+| `/quote` | `/quote AB#1234` | Estimate story points for one work item; on approval, sets the points and moves the item to Dev Ready. If it can't be estimated, offers to move it back to **Design Review** |
 | `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Bug or User Story — proposes story points (user must agree) and creates pointed items in Dev Ready |
 | `/cleanup-branches` | `/cleanup-branches` | Delete merged branches |
 | `/close-orphan-tasks` | `/close-orphan-tasks [scope] [--dry-run]` | Close open Tasks whose parent is Ready to Deploy / Deployed / Closed |