@chris1807/claude-kit 2.1.44 → 2.1.46

package/package.json

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

@@ -161,6 +161,78 @@ Once the branch is created, move the work item (User Story, Bug, Hot Fix, or oth
 
 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.
 
+### 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.
+
+Right after moving the work item to `Active`, look at its child Tasks (relations of type `System.LinkTypes.Hierarchy-Forward` whose target's `System.WorkItemType` is `Task`). A Task counts as **open** if its state is **not** `Closed`, `Done`, or `Removed`.
+
+**Never do this for a Feature.** Features don't carry Tasks of their own — the Feature path creates them per child story in F4.
+
+#### If an open child Task already exists
+
+Use it. **Do not create a second one** — one Task per story, always. Two touch-ups, then move on:
+
+- If it's still `New`, move it to `Active` alongside the parent.
+- If `Microsoft.VSTS.Scheduling.OriginalEstimate` is empty, propose hours (below) and, once the user agrees, set both `OriginalEstimate` and `RemainingWork` to that value.
+
+If **more than one** open Task exists, don't guess — list them and ask which one this run should log against. Leave the others alone.
+
+#### If there is no open child Task, create exactly one
+
+This includes the case where child Tasks exist but every one of them is already closed — a closed Task is not somewhere to log new work.
+
+Propose the hours from the parent's Story Points (this mirrors `/plan-backlog` Step 5b — keep the two tables in sync):
+
+| Points | Hour budget |
+|--------|-------------|
+| 1  |  3 hrs  |
+| 2  |  6 hrs  |
+| 3  | 10 hrs  |
+| 5  | 16 hrs  |
+| 8  | 28 hrs  |
+| 13 | 48 hrs  |
+| 21 | 75 hrs  |
+
+Calibrated for a **senior developer** at ~6 productive hours per day — the discount is already in the numbers, so don't apply a second one. Round non-Fibonacci point values up to the nearest row. Add 20–30% for `spike` / `research` / `unknown-stack` tags.
+
+If the work item has **no Story Points**, estimate the hours from the plan just approved in Step 3 — files to create and modify, plus the unit tests listed — using the same senior calibration. Say which basis you used.
+
+Show the proposal and **wait for the user**:
+
+```
+AB#{id} has no open child Task — one is needed to log hours against.
+
+| Task title                                   | Hours |
+|----------------------------------------------|-------|
+| {PREFIX} - Implement: {short summary}        |  16   |
+
+Basis: {n} story points → {n}h  (or: no points — estimated from the approved plan)
+
+Create it? (yes / edit / skip)
+```
+
+- `yes` → create it
+- `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`:
+
+- **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
+- **fields**:
+  - `Microsoft.VSTS.Scheduling.OriginalEstimate` — the agreed hours (as a number)
+  - `Microsoft.VSTS.Scheduling.RemainingWork` — the same value
+  - `System.AreaPath` and `System.IterationPath` — copy from the parent
+  - `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).
+
+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.
+
+Remember the Task ID. Step 10 closes it.
+
 ## Step 5: Implement
 
 1. **Implement** using backend and/or frontend agents according to the approved plan
@@ -275,11 +347,13 @@ Wait for the user's response before proceeding. Do NOT create a PR until confirm
 
    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.
 
-> **PR completion closes the Task only.** When this PR is later completed/merged, only the child **Task** may be closed — never the parent User Story or Bug. Azure DevOps's "Complete associated work items" option transitions *every* linked work item (including the parent this PR is linked to), so do **not** enable it when completing the PR. Close the child Task explicitly instead; the parent stays in `Code Review` until QA/UAT and any sibling Tasks are done.
+> **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` until QA/UAT and any sibling Tasks are done.
 
 ### Closing Related Tasks
 
-After the PR is created, find every child Task of this work item (relations of type `System.LinkTypes.Hierarchy-Forward` where the target's `System.WorkItemType` is `Task`). Skip this step if there are no child Tasks.
+After the PR is created, find every child Task of this work item (relations of type `System.LinkTypes.Hierarchy-Forward` where the target's `System.WorkItemType` is `Task`).
+
+There should be at least one open Task — Step 4 guarantees it. If there are **no** child Tasks at all (the user chose `skip` in Step 4, or the create call failed), create one now so the work that just shipped is recorded: same fields and prefix convention as Step 4, hours proposed the same way, then close it in the same pass. Say plainly that you're creating it after the fact.
 
 For each child Task, capture:
 - ID, title, state
@@ -330,12 +404,15 @@ 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 in a **single** `wit_update_work_item` 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.
 - `System.State` → `Closed` (fall back to `Done` if the project's task template uses Agile; warn if neither is valid)
 
-Confirm with a summary line per task: `Closed AB#xxxx — {hours}h logged`.
+Confirm with a summary line per task: `Closed AB#xxxx — {hours}h logged (estimate was {n}h)`.
+
+**The Task closes now, at PR creation — not at merge.** The work is done and the hours are known; waiting until merge means the hours get logged days later, or not at all.
 
 ## Feature Workflow (ordered story waves)
 
@@ -393,6 +470,18 @@ For each wave in ascending order:
 1. **Explore & plan** each story in the wave (Step 3 rules; Ultracode fan-outs apply per story if opted in). Present **one combined plan** with a section per story — each section covering approach, files, unit tests, and agents — plus a note on any files touched by more than one story in the wave (a conflict warning). **One approval gate per wave**; wait for the user.
 2. **Implement:**
    - **Move every story in the wave to `Active`** first (same rules and fallbacks as "Move the Work Item to Active" in Step 4). The Feature's state is never changed.
+   - **Ensure each story in the wave has an open child Task** (Step 4's "Ensure an Open Child Task Exists" rules, applied per story — Tasks hang off the stories, never off the Feature). Batch the proposals into **one** table covering the whole wave and take a single approval, so parallel agents never wait on a prompt:
+
+     ```
+     Stories in this wave with no open child Task:
+
+     | Story    | Task title                              | Hours | Basis   |
+     |----------|-----------------------------------------|-------|---------|
+     | AB#1235  | COM - Implement: export endpoint        |  10   | 3 pts   |
+     | AB#1236  | COM - Implement: export screen          |  16   | 5 pts   |
+
+     Create these? (yes / edit N / skip N / skip all)
+     ```
    - **Single-story wave** → implement directly on the feature branch in the main loop (Step 5).
    - **Multi-story wave** → isolate each story in its own worktree so parallel agents never clobber each other:
 
@@ -420,6 +509,6 @@ 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.
+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 PR-completion rule applies unchanged: when the PR merges, only child **Tasks** may be closed — never the stories or the Feature.
+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.

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
 
@@ -231,7 +232,9 @@ Hot Fix work items follow the same automated checks (build, lint, tests, review)
 
 Running `/implement` on a **Feature** implements its child User Stories in **waves** driven by the `Custom.Order` field: stories sharing the same order value are implemented **in parallel** (one agent per story, each in an isolated git worktree), and waves run sequentially in ascending order so later stories build on earlier ones. All work merges into a single `feature/AB#<id>-...` branch; quality checks, code review, UAT, and one PR happen at the feature level, and every implemented story is linked to that PR. Stories without a `Custom.Order` value run in a final catch-all wave (flagged for confirmation first).
 
-**Work item states:** `/implement` moves the work item to `Active` when implementation starts — for a single work item (User Story, Bug, Hot Fix) right after the branch is created; for a Feature, each child story goes `Active` as its wave begins. When the PR is created, each implemented child **User Story** moves to `Code Review` — the **Feature's state is never changed**. The Feature is a parent container; it advances only as its child stories are verified/closed. When the PR merges, only child **Tasks** are closed — never the stories or the Feature.
+**Work item states:** `/implement` moves the work item to `Active` when implementation starts — for a single work item (User Story, Bug, Hot Fix) right after the branch is created; for a Feature, each child story goes `Active` as its wave begins. When the PR is created, each implemented child **User Story** moves to `Code Review` — the **Feature's state is never changed**. The Feature is a parent container; it advances only as its child stories are verified/closed. Only child **Tasks** are ever closed — never the stories or the Feature.
+
+**Hours live on the Task.** `/implement` will not implement a story that has no open child Task: if there isn't one, it proposes a title and an hour estimate (from the story's points, same mapping `/plan-backlog` uses) and creates it once the user agrees — exactly one per story, inheriting the parent's assignee, area, and iteration. When the PR is created, that Task is closed with the hours worked logged to `CompletedWork` and `RemainingWork` zeroed. Closing happens at **PR creation**, not at merge, so hours are recorded while they're still known. Never enable Azure DevOps's "Complete associated work items" when merging — it transitions the parent too.
 
 #### Slash Commands Reference
 
@@ -239,7 +242,7 @@ All deployment and release operations are available as slash commands:
 
 | Command | Usage | What It Does |
 |---|---|---|
-| `/implement` | `/implement AB#1234` | Summarize work item → approve plan → implement → PR. On a Feature: child stories in `Custom.Order` waves, same-order stories in parallel |
+| `/implement` | `/implement AB#1234` | Summarize work item → approve plan → ensure an open child Task with hours → implement → PR (closes the Task, logs hours). On a Feature: child stories in `Custom.Order` waves, same-order stories in parallel |
 | `/review` | `/review 142` | Automated code review on a PR |
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/deploy` | `/deploy "commit message"` | Commit, push, trigger pipeline |
@@ -252,8 +255,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 |