@chris1807/claude-kit 2.1.26 → 2.1.29

package/README.md

@@ -28,7 +28,7 @@ Every session Claude learns from your feedback and gets better at helping you sp
 | **Global Agents** | 13 | `~/.claude/agents/` (your machine, all projects) | backend, frontend, legacy (Lucee/CFML), manager, mockup, reviewer, test-runner, build-validator, lint-checker, uat-generator, azure-ops, security-auditor, api-tester |
 | **Project Agents** | 3 | `.claude/agents/` (in the project) | deployer, db-admin, devops-tracker |
 | **Hooks** | 9 | `.claude/hooks/` (in the project) | Secret blocker, sensitive data blocker (Bash + MCP + output), protected files, auto-format, test suggestions, UAT reminder, self-improve |
-| **Slash Commands** | 13 | `.claude/commands/` (in the project) | `/implement`, `/review`, `/resolve-feedback`, `/deploy`, `/create-release`, `/deploy-release`, `/add-to-release`, `/cherry-pick`, `/promote`, `/rollback`, `/status`, `/cleanup-branches`, `/close-orphan-tasks`, `/quote`, `/explain` |
+| **Slash Commands** | 21 | `.claude/commands/` (in the project) | `/implement`, `/review`, `/deep-review`, `/resolve-feedback`, `/fix-review`, `/deploy`, `/create-release`, `/deploy-release`, `/add-to-release`, `/cherry-pick`, `/promote`, `/rollback`, `/status`, `/cleanup-branches`, `/close-orphan-tasks`, `/quote`, `/explain` |
 | **MCP Servers** | Up to 6 | `.mcp.json` (in the project) | **Azure DevOps** (work items, repos, pipelines, wiki), Playwright, MongoDB/SQL/Postgres, Teams, Stripe, Azure CLI |
 | **Workflow Template** | 1 | Appended to `CLAUDE.md` | Documents the full development process |
 | **Settings** | 1 | `.claude/settings.json` (in the project) | Registers all hooks and MCP servers |
@@ -637,7 +637,9 @@ Claude reviews for:
 |---------|-------|-------------|
 | `/implement` | `/implement AB#1234` | Read work item → summarize → approve plan → implement → quality checks → UAT → PR |
 | `/review` | `/review 142` | Full code review on a PR with inline comments |
+| `/deep-review` | `/deep-review 142` | Deep, Ultracode-orchestrated review: checks out the branch, builds/tests it, verifies every requirement, checks for regressions, flags out-of-scope changes, then comments + votes |
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
+| `/fix-review` | `/fix-review 142` | Fix everything flagged on a PR — human reviewer comments and automated `/review` findings alike: implement in severity order, validate, push, resolve threads |
 | `/deploy` | `/deploy "message"` | Commit, push, trigger pipeline if on environment branch |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 iteration with tags |
 | `/deploy-release` | `/deploy-release 23 staging` | Cherry-pick release work items to environment via PR |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.26",
+  "version": "2.1.29",
   "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/deep-review.md

@@ -0,0 +1,196 @@
+Deeply review PR #$ARGUMENTS in the current project — a local, checkout-based, Ultracode-orchestrated version of `/review`. Does everything `/review` does, plus: checks out the branch, verifies every requirement is implemented, confirms nothing else broke, and flags any changes the developer made that fall outside the work item. Follow this workflow:
+
+## Always Use Ultracode
+
+This command **always orchestrates its analysis-heavy phases with the `Workflow` tool** — you do not wait to be asked, and you do not need the `ultracode` keyword. The slash command runs in the main loop, which has the `Workflow` tool, so fan-out is available throughout. This is the deep-review counterpart to `/review`: where `/review` reads the PR diff over MCP, `/deep-review` checks the branch out locally and runs a far more exhaustive, multi-agent analysis.
+
+What this means in practice:
+
+- **Fan out the read / analyze / verify work** — rework-context detection (Step 2), per-acceptance-criterion coverage (Step 5), regression analysis (Step 6), scope/unwanted-change detection (Step 7), and the review dimensions (Step 8) are run as `Workflow` scripts with one agent per independent unit (per prior PR, per acceptance criterion, per impacted subsystem, per review dimension). Each agent returns **structured findings** via a `schema`; you synthesize the results in the main loop.
+- **Never fan out an interactive gate, a write, or a vote.** Every user prompt (Steps 7, 9, 10) and every PR mutation — posting comments, voting (Steps 10–11) — stays in the **main loop**. Workflow agents here are **read-only analysts** — they use MCP read tools, `Read`, `Grep`, and `Bash` for read-only inspection (builds, tests, `git diff`), and they return data. They do not post comments, vote, switch branches, write code, or ask the user anything.
+- **Stay in the loop between phases.** Run one `Workflow` per phase, read its results, present/await the user as the steps require, then launch the next phase's workflow. This is several short workflows in sequence — not one monolithic run that tries to swallow the approval gates.
+- **Review uses the canonical find → adversarially-verify pipeline** (Step 8): fan out per dimension, then spawn skeptic verifiers per finding and drop findings the majority refute, so only confirmed issues reach the user. Use the `reviewer` agent type for the dimension agents (`agentType: 'reviewer'`) so they inherit its review rules.
+
+If the `Workflow` tool is somehow unavailable, fall back to running each phase sequentially in the main loop — the output is identical, just slower.
+
+## Step 1: Resolve the PR, Work Item, and Branch
+
+Handle `$ARGUMENTS` as a PR id (e.g. `142`).
+
+1. **Read the PR** via `repo_get_pull_request_by_id` — capture the **source branch**, **target branch**, title, description, and status.
+2. **Read the linked work item** and gather the full description and acceptance criteria. Download and view every embedded image in the description / acceptance criteria via `WebFetch` — visual requirements (mockups, expected UI, error states) are part of the spec and you cannot verify "implemented properly" without seeing them.
+3. **Read the full diff** via `repo_get_pull_request_changes` — understand every file the PR touches. This is the canonical list of what the developer changed.
+
+## Step 2: Check Out the Branch Locally
+
+Unlike `/review`, this command works against the real working tree so it can build, test, and inspect the full code — not just the diff hunks.
+
+1. Stash or confirm a clean working tree first. If the working tree is dirty, **stop and tell the user** — do not stash their work without asking.
+2. `git fetch` then `git checkout <source-branch>` and `git pull` to get the exact code under review.
+3. Compute the review diff range against the target branch: `git merge-base <target-branch> HEAD` → use `git diff <merge-base>..HEAD` as the authoritative diff for all later steps. This is more reliable than the MCP diff for local analysis and matches what will actually merge.
+4. Confirm to the user which branch and commit you are reviewing:
+
+   ```
+   Reviewing PR #{id} — {title}
+     Source branch: {source}  @ {short-sha}
+     Target branch: {target}
+     Work item:     AB#{wi} — {wi title}
+     Files changed: {n}
+   ```
+
+If checkout fails (branch deleted after merge, etc.), tell the user and offer to fall back to a diff-only review (the `/review` behavior) instead.
+
+## Step 3: Detect Rework Context — do this BEFORE judging acceptance criteria
+
+A small diff does not mean a small feature. The PR you are reviewing may be a rework that only addresses targeted feedback, while the bulk of the implementation already shipped in earlier PRs. Judging acceptance criteria against the current diff alone will produce false "not met" findings.
+
+> **Ultracode:** Fan out with `Workflow` — one agent per PR linked to the work item, each fetching its details and classifying it. Synthesize in the main loop.
+
+For each PR linked to the work item (via `relations` / artifact links), fetch its details and classify:
+- **This PR** — the one being reviewed.
+- **Prior merged PRs** — `status: completed` and merged before this PR was created. Their changes are already in the target branch.
+- **Prior abandoned PRs** — ignore for acceptance-criteria coverage; their code is not in the target branch.
+
+Also scan the work item comments for rework feedback posted after the most recent prior merged PR. That feedback is what the current PR is expected to address.
+
+Treat the PR as a **rework** if any prior merged PR exists for this work item, OR if the work item has rework feedback comments dated after a prior PR. Otherwise treat it as an **initial PR**.
+
+## Step 4: Build and Test the Checked-Out Branch
+
+Because the branch is local, prove it actually works before judging it — a PR that does not build or whose tests fail is not mergeable regardless of how the code reads.
+
+1. **Build** every affected project with the `build-validator` agent. Record pass/fail and any errors.
+2. **Run the full test suite** with the `test-runner` agent — every unit test in the repo, plus integration tests, not just tests touched by this PR. A failure in an unrelated test is a regression signal for Step 6.
+3. **Run lint** — ESLint and `dotnet format` via the `lint-checker` agent.
+
+Capture the results; do not fix anything (this command is read-only on the code). Build/test/lint failures become findings in the Step 8 summary, flagged **critical**.
+
+## Step 5: Verify Every Requirement Is Implemented — Deep AC Coverage
+
+This is the core of `/deep-review`: confirm **nothing in the spec was missed** and everything was **implemented properly**, not just superficially present.
+
+> **Ultracode:** Fan out with `Workflow` — **one agent per acceptance criterion**. Each agent reads the relevant code in the checked-out tree and returns `{ac, status, evidence, gaps}` where:
+> - `status` ∈ `met-this-pr` | `met-prior-pr` | `partial` | `not-met` | `not-applicable`
+> - `evidence` — the specific file(s)/line(s) and test(s) that prove the AC is satisfied
+> - `gaps` — anything required by the AC (including details only visible in the embedded images) that is missing, stubbed, or only partially done
+>
+> Evaluate coverage against the **cumulative work**, not just this diff:
+> - **Initial PR**: every AC must be satisfied by this PR's diff.
+> - **Rework PR**: an AC may be satisfied by (prior merged PRs already in the target branch) + (this PR's diff). Mark those `met-prior-pr` — do not flag them as missing — but re-check any AC whose area this PR's diff touches, for regression.
+>
+> Collect all results in the main loop. Any `partial` or `not-met` AC is a blocking finding.
+
+For a rework PR with a small diff, also ask the focused question: **does this diff correctly address the rework feedback, and does it avoid regressing the prior implementation?** — not "does this diff implement every AC from scratch?"
+
+## Step 6: Confirm It Didn't Break Other Code — Regression Analysis
+
+Verify the change is safe beyond the lines it touched.
+
+> **Ultracode:** Fan out with `Workflow` — one agent per subsystem or shared component the diff could affect (callers of changed methods, shared DTOs/interfaces, database schema or query shape changes, public API contracts, config/env changes). Each agent returns `{area, impact, risk, evidence}`. Seed the agents with: (a) the full-suite test results from Step 4, (b) the list of changed symbols, and (c) `grep` for usages of every changed public symbol. Synthesize a regression risk table in the main loop.
+
+Specifically check:
+- **Changed shared code** — for every public method/class/interface/DTO the diff modifies, find its other callers and confirm the change is backward-compatible or all callers were updated.
+- **Test fallout** — any failing test from Step 4 in an area this PR didn't intend to change is a regression; surface it as **critical**.
+- **Environment configuration parity** — if the diff adds or changes any key in `appsettings.*.json` or `.env*`, every parallel environment file (Development/Staging/QA/Production for backend; `.env.development`/`.env.staging`/`.env.production`/`.env.example` for React) must have a corresponding entry, or the omission must be called out. Build a (key × environment) table and flag any missing cell as **critical**. A pipeline variable group, Key Vault, or App Configuration counts as a valid source for an environment — verify it exists rather than assume it.
+
+## Step 7: Detect Unwanted / Out-of-Scope Changes — and Confirm With the User
+
+The developer should have changed **only** what the work item requires. Catch anything extra — accidental commits, debug code, unrelated refactors, formatting churn, vendored files, secrets, commented-out blocks, or scope creep.
+
+> **Ultracode:** Fan out with `Workflow` — one agent per changed file (or per logical group of files). Each agent answers: *does this change map to an acceptance criterion or the work item's stated intent?* and returns `{file, mapsToAC, classification, rationale}` where `classification` ∈ `in-scope` | `incidental-ok` (e.g. an unavoidable import or a generated file) | `out-of-scope` | `suspicious` (debug code, leftover TODO, commented-out blocks, stray console/Debug logging, unrelated dependency bumps, large reformat-only diffs). Synthesize in the main loop into a single scope table.
+
+Present every out-of-scope or suspicious change to the user and **wait for a decision** — do not silently fold these into the review:
+
+```
+## Out-of-Scope / Unexpected Changes in PR #{id}
+
+These changes do not map to any acceptance criterion on AB#{wi}:
+
+| # | File | What changed | Why it looks out of scope |
+|---|------|--------------|---------------------------|
+| 1 | {file} | {summary} | {e.g. unrelated refactor of an untouched module} |
+| 2 | {file} | {summary} | {e.g. leftover console.log / commented-out code} |
+| 3 | {file} | {summary} | {e.g. dependency bump unrelated to this work item} |
+
+For each, tell me how to treat it:
+- "ok 1,3"        → accepted as intentional; I won't flag them
+- "flag 2"        → I'll raise it as a review finding (severity I'll pick by type)
+- "ok all" / "flag all"
+```
+
+**Wait for the user's response.** Items the user marks `ok` are dropped from the findings. Items marked `flag` (or anything genuinely dangerous — a committed secret, disabled security check, or `.env` with real values — which you should flag as **critical** regardless of the user's call, while telling them why) carry into the Step 8 review summary. If there are no out-of-scope or suspicious changes, state that and skip the prompt.
+
+## Step 8: Review for Quality — find → adversarially-verify
+
+> **Ultracode:** Run the review as a `Workflow` find → verify pipeline. **Find:** fan out one agent per dimension (below), each scoped to the Step 2 diff range and returning structured findings. **Verify:** for each finding, spawn independent skeptic agents prompted to *refute* it (default to refuted if uncertain); drop any finding the majority refute. Only confirmed findings reach the user. Use `agentType: 'reviewer'` for the dimension agents.
+
+Review dimensions:
+- Clean Architecture boundaries (Domain has no infrastructure dependencies)
+- Tenant/`organizationId` enforcement on all database queries
+- Missing unit or integration tests for new code
+- `any` types in TypeScript (should be properly typed)
+- Security issues (OWASP Top 10, hardcoded secrets, SQL/NoSQL injection, exposed PII)
+- Error handling (are exceptions caught appropriately?)
+- Naming conventions and code style consistency
+- Breaking changes or backwards compatibility issues (cross-reference Step 6)
+- **CLAUDE.md compliance** — sensitive-data rules, work-item prefix conventions, branching, anything the project's CLAUDE.md mandates
+
+Fold in the carried-over findings from Steps 4 (build/test/lint), 5 (AC gaps), 6 (regressions, env parity), and 7 (flagged out-of-scope changes).
+
+## Step 9: Draft the Comments and Summary
+
+**Draft (do not post yet) the inline comments** for every confirmed finding. For each, capture: file path, line number, severity, and the exact comment body.
+
+**Draft (do not post yet) the PR-level summary comment** with:
+- **PR type**: Initial PR or Rework (and if rework, the prior merged PR numbers and the rework feedback addressed)
+- **Build / Test / Lint**: pass/fail from Step 4
+- Overall assessment (ready to merge / needs changes)
+- Count of issues by severity (critical / warning / suggestion)
+- **Acceptance criteria checklist** — each item marked `met (this PR)` / `met (prior PR #N)` / `partial` / `not met` / `not applicable`, with the evidence or gap from Step 5
+- **Regression assessment** — from Step 6 (impacted areas + result)
+- **Out-of-scope changes** — what was found and how it was dispositioned in Step 7
+- **Rework feedback checklist** (rework PRs only) — each item addressed / not addressed
+- Test coverage assessment
+
+## Step 10: Preview Everything and Wait for Approval
+
+**Preview every comment to me and wait for approval before posting anything to the PR.** Show:
+
+```
+Deep review drafted — nothing has been posted to PR #{id} yet.
+
+## Inline comments ({count})
+1. {file}:{line} [{severity}] — {comment body}
+2. ...
+
+## PR summary comment
+{full summary body as it will appear on the PR}
+
+Reply with one of:
+- "approve" → post all inline comments and the summary exactly as shown above
+- "skip"    → post nothing
+- "edit <number>: <new text>" or "skip <numbers>" → revise/drop specific items, then I'll re-preview before posting
+```
+
+**Wait for my response. Never post any comment to the PR until I reply "approve".** If I edit or skip individual items, apply the changes and re-preview the full set before asking again. "skip" with no numbers means post nothing at all — move directly to Step 11 without posting.
+
+## Step 11: Post and Vote
+
+If I approved, post the inline comments and the summary to the PR. If I skipped, post nothing. Either way, then ask me:
+
+```
+{Comments posted to PR #{id}. | No comments posted (skipped).}
+- PR type: {Initial | Rework of prior PR(s) #N, #M}
+- Build/Test/Lint: {pass | fail — detail}
+- X critical issues
+- Y warnings
+- Z suggestions
+- Acceptance criteria: A met this PR, B met in prior PRs, C partial, D not met
+- Regressions: {none | detail}
+- Out-of-scope changes: {none | E accepted, F flagged}
+- Rework feedback (if rework): G/H addressed
+
+Approve, Request Changes, or skip the vote?
+```
+
+Wait for my response before submitting any vote on the PR. Then restore the user's original branch if you switched away from it in Step 2 (tell them before doing so).

package/templates/commands/fix-review.md

@@ -0,0 +1,172 @@
+Fix everything flagged on a pull request. Usage: `/fix-review <pr-id>` (or `/fix-review` to auto-detect from the current branch).
+
+This command fixes **anything a reviewer raised on the PR** — whether the reviewer is a person leaving inline comments or the automated `/review` / `/deep-review` pass that posts severity-tagged findings. It reads every open comment, plans a concrete fix for each, validates, pushes, and resolves the threads. The default disposition is **fix it** — if the reviewer flagged something, you make the change.
+
+**How this differs from `/resolve-feedback`:** `/resolve-feedback` is triage-oriented — it weighs each thread as fix / reply-only / defer and is built for back-and-forth conversation with a reviewer. `/fix-review` is fix-oriented — its job is to burn down the whole list of flagged items and get the PR mergeable, defaulting every flagged item to a code fix unless it's genuinely wrong or out of scope. Use `/resolve-feedback` when you mostly want to *discuss* the feedback; use `/fix-review` when you want to *clear* it. Neither touches work-item state, hours, or UAT — that's `/rework`.
+
+## Step 1: Identify the Pull Request
+
+Parse `$ARGUMENTS`:
+
+- **PR id given** (`142`, `#142`, `!142`) — strip non-digits and use as the PR id.
+- **No argument** — find the PR for the current branch:
+  1. Get current branch via `git rev-parse --abbrev-ref HEAD`.
+  2. Call `repo_list_pull_requests_by_repo_or_project` filtered to `sourceRefName: refs/heads/<branch>` and `status: active`.
+  3. If exactly one match, use it. If zero or multiple, ask the user which PR id to target — do not guess.
+
+Fetch the PR via `repo_get_pull_request_by_id`. Record:
+- `pullRequestId`, `title`, `status`
+- `sourceRefName` (the branch holding the fixes) and `targetRefName`
+- Linked work item id(s) from artifact links — used only for context, not modified by this command.
+
+## Step 2: Collect Everything Flagged
+
+Call `repo_list_pull_request_threads` for the PR, then read each thread's comments via `repo_list_pull_request_thread_comments`. Gather **every open thing a reviewer raised** — both human reviewer comments and automated `/review` / `/deep-review` findings.
+
+**Include a thread when all of these are true:**
+- `status` is `active` or `pending` (statuses `1` or `6`). Skip `fixed`, `wontFix`, `closed`, `byDesign` — those are already handled.
+- It contains at least one real reviewer comment (`commentType: text`), not a system thread (vote changes, build status, policy violations, work-item link additions — these are `commentType: system`).
+- It is not authored exclusively by the PR author talking to themselves with no reviewer or automated-review input. Use the PR `createdBy.id` to identify the author.
+
+This captures both sources:
+- **Human reviewer comments** — free-form prose, often without a severity tag. Infer severity from the language ("this will crash" → critical; "consider renaming" → suggestion); when unclear, default to **warning**.
+- **Automated review findings** — `/review` / `/deep-review` post inline comments in the form `{file}:{line} [{severity}] — {body}` plus a PR-level summary comment with "X critical / Y warnings / Z suggestions" and an acceptance-criteria checklist. Read that summary comment too, and use it to recover any finding raised only in the summary, not as an inline comment.
+
+For each flagged item, capture:
+- `threadId`
+- **source** — human reviewer vs. automated review (so the reply can be worded appropriately)
+- **severity** — critical / warning / suggestion (inferred for human comments as above)
+- `threadContext` — `filePath`, `rightFileStart.line` / `leftFileStart.line` (may be null for PR-level threads)
+- the comment body — what's wrong and any suggested fix. If a comment body contains an `<img src="...">` pointing to an Azure DevOps attachment, download and view it via WebFetch before proposing a fix — reviewers often paste screenshots that carry the real context.
+
+If there are zero qualifying threads, tell the user `No open reviewer feedback on PR #{id}.` and stop.
+
+## Step 3: Switch to the PR Branch
+
+Before reading code or proposing fixes, make sure local state matches the PR:
+
+1. `git fetch`
+2. If the current branch ≠ `sourceRefName` (stripping `refs/heads/`): `git checkout <source-branch>`. If the branch does not exist locally, `git checkout -b <source-branch> origin/<source-branch>`.
+3. `git pull --ff-only` — refuse to proceed on a dirty or diverged working tree; ask the user to resolve it first rather than auto-stashing or force-resetting.
+
+## Step 4: Plan the Fixes
+
+Order the items by severity — **critical first, then warning, then suggestion**. For each, read the referenced code (use `threadContext.filePath` + line, or locate it from the comment body for PR-level threads) and decide one of — **defaulting to fix**, because the point of this command is to clear what reviewers flagged:
+
+- **fix** (the default) — apply the change the reviewer asked for. Capture which files will be touched and a one-line description of the change. Reach for this for anything actionable, whether it came from a person or the automated review.
+- **disagree** — the comment is wrong or already addressed in the current code. Do not silently skip; capture a short rebuttal to post as a reply, and leave the thread for the reviewer to adjudicate. Use sparingly — a human reviewer flagged it for a reason, so only disagree when you're confident.
+- **defer** — valid but genuinely out of scope for this round (e.g. a large refactor a suggestion asks for). Capture why; reply and leave the thread active.
+
+Present the full plan to the user before touching any code:
+
+```
+PR #{id}: {title}
+Branch: {source-branch} → {target-branch}
+Flagged items: {count}  ({n} critical, {m} warning, {k} suggestion)
+
+## Item 1 — [CRITICAL] {file}:{line}  (or "PR-level" if no file context)
+Flagged by: {reviewer name | automated review}
+> {comment excerpt — first ~200 chars}
+
+Proposed action: FIX
+Files to change:
+  - {path} — {what changes}
+Reply on resolve: "{short summary that will be posted with the resolution}"
+
+## Item 2 — [WARNING] {file}:{line}
+Flagged by: {reviewer name}
+> {comment excerpt}
+
+Proposed action: DISAGREE (already handled / incorrect)
+Reply: "{rebuttal text}"
+
+## Item 3 — [SUGGESTION] {file}:{line}
+Flagged by: {automated review}
+> {comment excerpt}
+
+Proposed action: DEFER (out of scope for this round)
+Reply: "{text explaining why this will be handled separately}"
+
+---
+Approve this plan? (yes / edit <n>: <change> / skip <n> / no)
+```
+
+**Wait for the user's response.** Apply edits and re-present until the user replies `yes`. `skip <n>` removes an item from this round entirely — it stays active on the PR and gets no reply.
+
+## Step 5: Implement the Fixes
+
+For each finding marked **fix** in the approved plan, in severity order:
+
+1. Make the code change. Use the `backend` / `frontend` / `legacy` agents when the change is non-trivial; small targeted edits can go through `Edit` directly.
+2. Add or update tests when the fix changes observable behavior. A finding that says "this doesn't handle empty input" implies a missing test case — add it. Do not add tests for pure rename/comment/formatting fixes.
+
+Implement all fixes before moving to validation — batching keeps the build/test cycle short.
+
+## Step 6: Validate
+
+Run in this order. Stop and fix on the first failure before continuing.
+
+1. **Build** — via the `build-validator` agent. Build must be clean.
+2. **Lint** — `dotnet format` for `.cs` changes, ESLint for `.ts`/`.tsx` changes (only on touched files; full-repo lint runs are wasteful here).
+3. **Tests** — run the test suites that cover the files you touched (`test-runner` agent). If a touched file has no test coverage, call that out in the final summary rather than silently skipping.
+
+If validation fails after a reasonable fix attempt, stop and report — do not push broken code to clear a finding.
+
+## Step 7: Confirm Before Pushing
+
+Show the user exactly what will happen next:
+
+```
+Validation passed.
+
+Changes ready to push to {source-branch}:
+{git diff --stat output}
+
+About to:
+  1. git push origin {source-branch}
+  2. For each FIX finding:       reply with the resolution summary + mark as Fixed (status 2)
+  3. For each DISAGREE finding:  reply with the rebuttal + leave status Active
+  4. For each DEFER finding:     reply with the deferral note + leave status Active
+
+Proceed? (yes / no)
+```
+
+**Wait for `yes`.** Anything else aborts without pushing or touching the PR.
+
+## Step 8: Push and Update the PR
+
+1. `git push origin <source-branch>`.
+2. For each finding in the approved plan, in order:
+   - Call `repo_reply_to_comment` with the reply text. Reference the new commit SHA in FIX replies (e.g. `Fixed in {sha} — {one-line summary of what changed}`).
+   - Call `repo_update_pull_request_thread` to set `status`:
+     - **fix** → `fixed` (2)
+     - **disagree** → leave as `active` (only the reply was posted — the user/reviewer adjudicates)
+     - **defer** → leave as `active`
+3. After every finding has been processed, post one PR-level summary comment via `repo_create_pull_request_thread` (new top-level thread, status `closed`):
+
+   ```
+   Addressed reviewer feedback in {sha}:
+   - {N} fixed ({critical/warning/suggestion breakdown})
+   - {D} disagreed (left active for adjudication)
+   - {K} deferred ({reason summary})
+   ```
+
+   Skip the summary comment if only one finding was touched — the reply on that thread already says everything.
+
+4. Do **not** change the work item state, do **not** create Tasks, do **not** log hours, do **not** vote on the PR. Those belong to `/rework` and to the reviewer.
+
+## Step 9: Final Report
+
+Print to the user:
+
+```
+PR #{id} — reviewer feedback addressed
+  Branch:        {source-branch} ({sha})
+  Fixed:         {N} finding(s)  ({n} critical, {m} warning, {k} suggestion)
+  Disagreed:     {D} finding(s)
+  Deferred:      {K} finding(s)
+  Files touched: {file count}
+  Tests added/updated: {test file count, or "none — no behavior change"}
+```
+
+If any finding was disagreed or deferred, list those thread ids explicitly so the user can adjudicate or file a follow-up. If any critical finding remains unfixed for any reason, call that out prominently — a PR with open critical findings should not merge.

package/templates/commands/implement.md

@@ -243,6 +243,8 @@ 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.
+
 ### 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.

package/templates/commands/rework.md

@@ -323,6 +323,8 @@ Wait for the user's response before proceeding. Do NOT push until confirmed.
 
    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. Do not silently swallow the error.
 
+> **PR completion closes the Task only.** When the 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 the 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.
+
 ### Closing Related Tasks
 
 After pushing, 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.