codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-round-input/SKILL.md

@@ -0,0 +1,165 @@
+---
+scope: org-shared
+name: cbp-round-input
+description: Gather input for a new round with deep analysis of unapproved work
+argument-hint: [chk-task-round | task-round | requirements-text]
+effort: xhigh
+---
+
+# Round Input Command
+
+Gathers input for a new round. Performs deep analysis of unapproved files, requirements coverage, and testing-QA failures before formulating requirements. Follow-up rounds get the same depth as round 1.
+
+## When Used
+
+- After `/cbp-round-update` routes here (unapproved files)
+- After `/cbp-round-execute` Step 6 routes here (structural failure or retry-exhausted hard-fail)
+- After `/clear` + `/cbp-todo` reloads context and triggers this
+- When user wants to start a new round with specific changes
+
+## Instructions
+
+### Step 1: Parse `$ARGUMENTS`
+
+Try the numeric identifier regex first: `^[0-9]+(-[0-9]+){0,2}$`
+
+| Shape | Segments | Resolves to |
+|-------|----------|-------------|
+| `{task}` (e.g. `45`) | 1 | Standalone TASK-{task} next round (matches cbp-task-start standalone convention) |
+| `{chk}-{task}` (e.g. `108-1`) | 2 | CHK-{chk} TASK-{task} next round (round number implicit — round-input creates a new round) |
+| `{chk}-{task}-{round}` (e.g. `108-1-2`) | 3 | CHK-{chk} TASK-{task} targeting ROUND-{round} (existing round context) |
+| _(no match / empty)_ | — | Free-text requirements (passed through to Step 5) OR empty → use `get_current_task` |
+
+If the argument matches the numeric regex, resolve the target task/round from DB. If no match (or empty), treat the argument as free-text requirements and proceed to Step 2 for context (free-text path still runs deep analysis before Step 5).
+
+#### Worked examples
+
+- `round-input 45` → standalone TASK-45 next round
+- `round-input 108-1` → CHK-108 TASK-1 next round
+- `round-input 108-1-2` → CHK-108 TASK-1 ROUND-2
+- `round-input` (no arg) → active task via `get_current_task`
+- `round-input Fix the broken lint rule in the auth module` → free-text requirements (numeric regex fails → falls through to free-text path)
+
+> **Note on 2-segment divergence**: `round-input 108-1` resolves to **CHK-108 TASK-1** (targeting that task's next round). This diverges from `/cbp-round-start` where the 2-segment `108-1` means **standalone TASK-108 ROUND-1**. Round-input always operates on a task-level context (it creates a new round on a task), so the round number is implicit and 2 segments are interpreted as `{chk}-{task}`. To target a standalone task here, use the 1-segment form `45`. To target a specific existing round, use the 3-segment form `108-1-2`.
+
+### Step 2: Deep Analysis (MANDATORY — always runs)
+
+**2a:** Load task via MCP `get_current_task` (pass `checkpoint_id` if known to avoid disambiguation) — get `files_changed`, `requirements`, `context`, `qa`
+
+**2b:** Load all rounds via MCP `get_rounds(task_id)` — get previous round context, testing-qa output
+
+**2c:** Identify unapproved files from `task.files_changed` where `user_approved === false`
+
+**2d:** Read the content of each unapproved file (using Read tool, max 5 files, first 100 lines each)
+
+**2e:** Cross-reference with task requirements — for each requirement, is it met or missed?
+
+**2f:** Extract testing-qa failures from latest round context (`context.testing_qa_output`)
+
+**2g:** Extract code review findings from latest round context (`context.improve_round_findings`).
+These are user-accepted findings from `improve-round` agent — bugs, logic errors, edge cases
+that the user agreed should be fixed. Include them as high-priority requirements.
+
+**2h:** Identify root causes — not "file X is wrong" but "requirement Y was not met because Z"
+
+**2i:** Produce structured analysis summary
+
+### Step 3: Present Analysis
+
+Show the analysis to the user:
+
+```
+## Follow-up Round Analysis
+
+### Unapproved Files ([N])
+| File | Action | Issue |
+|------|--------|-------|
+| path | modified | [what's wrong based on reading the file] |
+
+### Requirements Coverage
+| Requirement | Status | Gap |
+|-------------|--------|-----|
+| [req] | met/missed | [what's missing] |
+
+### Testing-QA Issues (from previous round)
+- [issue 1 from testing-qa output]
+- [issue 2]
+
+### Code Review Findings (from improve-round)
+| # | Severity | File | Issue |
+|---|----------|------|-------|
+| [findings accepted by user in previous round-end] |
+
+### Root Causes
+1. [root cause with explanation]
+2. [root cause with explanation]
+```
+
+### Step 4: Choose Mode
+
+**If `round.context.auto_loop_mode === true` on the prior round**: skip the AskUserQuestion below. Auto-pick "Start round with these findings" using the analysis directly. Set the next round's `auto_loop_mode = true`, carry `auto_loop_index` and `auto_loop_cap` forward into round-start args.
+
+**Else (manual mode — flag absent or false)**, ask user via AskUserQuestion:
+
+- **Start round with these findings** — use analysis as requirements
+- **Discuss first** — open conversation about the analysis
+- **Adjust** — user provides their own requirements
+
+If "Discuss first": enter open discussion about the analysis. When direction is clear, proceed to Step 5.
+If "Adjust": user provides their own requirements, merged with analysis context.
+
+### Step 5: Formulate Requirements
+
+Based on the analysis + user input, create detailed requirements that:
+
+- Reference specific root causes identified in Step 2
+- Include full task requirements context
+- Are as thorough as round 1 (not quick fixes)
+- Include checkpoint and task context for the planner
+
+**Under `auto_loop_mode`**: requirements come VERBATIM from the prior round's `improve_round_findings[]` and `testing_qa_output` failures, treated as a flat list. Test failures are listed first (they block shipping); reviewer findings follow. Both sets are included unchanged — do not re-summarise or re-prioritise either. The auto-loop transcribes the prior reviewer's output directly.
+
+### Step 6: Update Context (if direction changed)
+
+If the new round requirements change the task direction:
+
+1. Update task context via MCP `update_task(task_id, context: { ... })`:
+   - Add new decisions to `context.decisions[]`
+   - Update `context.discoveries[]` if applicable
+2. If checkpoint-level changes needed, update checkpoint context via MCP `update_checkpoint`
+
+### Step 7: Auto-trigger Round Start
+
+Pass the new requirements to `/cbp-round-start`:
+
+```
+Starting new round with updated requirements...
+```
+
+Trigger `/cbp-round-start` with the round requirements as arguments.
+
+**Under `auto_loop_mode`**: pass `auto_loop_mode: true`, `auto_loop_index: N`, `auto_loop_cap: C` into round-start's args/context so round-start Step 4 can persist them on the new round and downstream skills (round-execute, round-end) read them.
+
+## Fallback: Context Recovery
+
+If this command is triggered **directly** (not via `/cbp-todo`) and no context is available in the session:
+
+1. Read `.codebyplan/repo.json` for `repo_id`
+2. Use MCP `get_current_task` to load checkpoint + task
+3. Use MCP `get_rounds(task_id)` to load round history
+4. Continue from Step 2 (deep analysis handles all context loading)
+
+## Key Rules
+
+- **Deep analysis is MANDATORY** — always runs, even if arguments provided (for context)
+- **Analysis reads from DB (MCP)**, not conversation history
+- **Follow-up rounds get same depth as round 1** — no quick-fix behavior
+- **Never ask to git add** — file approval is handled by `/cbp-round-update`
+- **Update all context locations** — task, checkpoint, and round should all have consistent information
+
+## Integration
+
+- **Triggered by**: `/cbp-round-update` (auto, unapproved files), `/cbp-round-execute` (auto, on hard-fail after retry exhausted), `/cbp-todo` (after /clear), user manually
+- **Reads**: MCP `get_current_task`, `get_rounds`, file contents (Read tool)
+- **Writes**: MCP `update_task` (context), `update_checkpoint` (context, if needed)
+- **Triggers**: `/cbp-round-start` (auto)

package/templates/skills/cbp-round-start/SKILL.md

@@ -0,0 +1,222 @@
+---
+scope: org-shared
+name: cbp-round-start
+description: Start a round — planning phase only
+triggers: [cbp-round-execute]
+argument-hint: [chk-task-round | task-round | requirements-text]  # e.g. `108-1-2`, `45-2`, or free-text from /cbp-round-input
+effort: xhigh
+---
+
+# Round Start Command
+
+Planning phase for a new round. Analyzes context, creates plan, gets user approval. NO execution or testing — those are separate commands.
+
+## Inline-Fallback for Planner Spawn Failure
+
+If the `cbp-task-planner` agent spawn fails for any reason (`API Error: Extra usage required`, monthly Agent usage cap, provider 5xx, rate limit, context overflow), the orchestrator MUST follow the canonical inline-fallback procedure documented in `skills/cbp-round-end/SKILL.md` "Inline-fallback for any spawn failure".
+
+Procedure summary (pointer back to canonical):
+
+1. Detect the failure class from the error string; record `round.context.planner_findings.spawn_failure = { class, error_message, decided_at }`.
+2. Walk the planner's documented Phase 0-8 checklist inline using `Read` / `Grep` / `Bash` / MCP `get_*` — `agents/cbp-task-planner.md` is the inline script. Phase 1.5 (Requirement Premise Verification) and Phase 4.7 (Migration Shape-Distribution Pre-Flight) are MANDATORY in fallback mode — these are the gates the agent uniquely enforces; skipping them produces unverified plans.
+3. Populate the planner's output contract (`approved_plan` shape: `files_to_modify[]`, `deliverables`, `specialist_needs`, `round_type`, `shape_distribution` if applicable, `context_summary`) with `mode: 'inline_fallback'`.
+4. Apply the pre-emptive-skip rule: when the same failure class fired in the previous spawn of this session, skip the spawn attempt entirely and go straight to inline.
+5. Continue the skill — do NOT abort. The plan still requires user approval at Step 9.
+
+Inline-fallback is NOT a quality downgrade trapdoor — Phase 1.5 row-by-row verification is mandatory. A fallback plan that skipped premise verification is a regression caught by the next session's cbp-improve-round.
+
+## Pipeline
+
+```
+/cbp-round-start (planning) → [user approval] → /cbp-round-execute (auto)
+```
+
+**Auto-loop mode**: when `round.context.auto_loop_mode === true` flows in from `/cbp-round-input`, Step 6 (Q&A) and Step 8 (user approval) skip user prompts. See cbp-round-update SKILL.md Step 6 (auto-loop decision) and cbp-round-end SKILL.md Step 8 for the full contract.
+
+## Instructions
+
+### Step 0: Parse `$ARGUMENTS` shape
+
+Disambiguate the argument up front. Three input shapes (see `.claude/rules/notation-consistency.md` "CHK / TASK / ROUND Identifier Notation"):
+
+| Shape | Regex | Meaning |
+|-------|-------|---------|
+| `{chk}-{task}-{round}` (e.g. `108-1-2`) | `^[0-9]+-[0-9]+-[0-9]+$` | **Identifier**: targets round {round} of CHK-{chk} TASK-{task}. Sets `target_checkpoint`, `target_task`, `target_round`. |
+| `{task}-{round}` (e.g. `45-2`) | `^[0-9]+-[0-9]+$` | **Identifier**: targets round {round} of standalone TASK-{task}. Sets `target_task`, `target_round` (no checkpoint). |
+| Non-empty, non-identifier-shaped | — | **Free-text round requirements** (the round-input passthrough path). |
+| _(empty)_ | — | No identifier, no requirements text — derive task/round from `get_current_task` / `get_rounds`. |
+
+Malformed identifier shapes (`108-`, `-1-2`, `108--1`, `abc-1`) — surface this error and stop, mirroring `/cbp-task-start`'s error vocabulary:
+
+```
+round-start: invalid argument `{value}`. Expected:
+  108-1-2  → round 2 of CHK-108 TASK-1
+  45-2     → round 2 of standalone TASK-45
+  (free-text) → round requirements (typical from /cbp-round-input)
+  (empty)  → derive from active task/round state
+```
+
+#### Worked examples
+
+- `round-start 108-1-2` → resolve CHK-108 TASK-1, target round 2
+- `round-start 45-2` → resolve standalone TASK-45, target round 2
+- `round-start 108-1` → **standalone TASK-108 round 1** (NOT CHK-108 TASK-1). The 2-segment form means `{task}-{round}`; checkpoint-bound round-targeting requires all three numbers (`108-1-2`). If you got here trying to target CHK-108 TASK-1, you want `108-1-2` (specifying a round number) or `/cbp-task-start 108-1` (specifying just a task).
+- `round-start "Implement OAuth flow per CHK-X plan"` → free-text path; current-task/round derivation from state
+- `round-start` (empty) → derive from `get_current_task` / `get_rounds`; round 1 uses `task.requirements`
+- `round-start 108-` → error: malformed identifier
+- `round-start -1-2` → error: malformed identifier
+- `round-start abc-1` → error: malformed identifier
+
+> **Mental-model warning**: `task-start` and `round-start` interpret the SAME `108-1` argument differently. `task-start 108-1` → CHK-108 TASK-1 (checkpoint-bound task). `round-start 108-1` → standalone TASK-108 round 1 (because round-start needs three numbers for a checkpoint-bound round). When in doubt, write all three: `round-start 108-1-2`.
+
+### Step 1: Get Current Task
+
+If Step 0 produced an identifier (`target_task` set): resolve directly per the identifier (bound or standalone) — MCP `get_checkpoints` + `get_tasks`, or `get_tasks(standalone: true)`.
+
+Otherwise: use MCP `get_current_task` with repo_id (pass checkpoint_id if known to avoid disambiguation) to find the active checkpoint and in-progress task.
+
+If no in-progress task and Step 0 produced no identifier, show error: `No active task. Run /cbp-task-start first.`
+
+### Step 2: Determine Round Number
+
+If Step 0 produced `target_round`: use that as the round number directly (may target an existing round for resume, or N+1 for a new round — disambiguate by checking MCP `get_rounds`).
+
+Otherwise: use MCP `get_rounds` for the task; count existing rounds; next is N+1.
+
+### Step 3: Gather Round Requirements
+
+**If Step 0 parsed an identifier**: this skill was invoked to resume/start a specific round. Requirements come from existing round data (when the round exists) or task.requirements (for new round 1) — `$ARGUMENTS` is the identifier itself, NOT requirements text.
+
+**Else (free-text path), if round number is 1:**
+
+- Use `task.requirements` as the primary requirements
+- If `$ARGUMENTS` provided (free-text), merge as additional context
+
+**Else (free-text path), if round number > 1:**
+
+1. If `$ARGUMENTS` provided (from `/cbp-round-input`): use as round requirements
+2. If NO arguments: show error - `Round 2+ requires input. Run /cbp-round-input first.`
+
+### Step 4: Create Round in DB
+
+Use MCP `add_round`:
+- `task_id`: current task ID
+- `number`: next round number
+- `status`: "in_progress"
+- `started_at`: now (ISO format)
+- `triggered_by`: `"user"` | `"claude"` | `"auto_loop"` — `auto_loop` when `auto_loop_mode === true` flows in from round-input; `claude` when auto-triggered by testing failure; `user` otherwise
+- `requirements`: round requirements from Step 3
+- `context`: when `auto_loop_mode === true`, persist `auto_loop_mode: true`, `auto_loop_index: N`, `auto_loop_cap: C` into `round.context` (carried forward from round-input args)
+
+### Step 5: Load Context from DB
+
+Load from checkpoint and task:
+- Checkpoint context (decisions, dependencies, constraints, goal)
+- Task context and requirements
+- Resources from checkpoint and task (documentation links, API docs, guides)
+- Previous round results (files_changed, QA results)
+- For round 2+: load the latest completed round's `context.testing_qa_output` and `context.executor_output` via `get_rounds` response
+- Identify unapproved files from task.files_changed (where user_approved === false)
+
+### Step 6: First Round Analysis (Round 1 only)
+
+For the first round only:
+
+1. Analyze the task context and requirements thoroughly
+2. Identify any ambiguities or gaps
+3. If questions are needed, ask user via AskUserQuestion (max 4 per batch)
+4. If task context changes from Q&A answers:
+   - Update task context via MCP `update_task(task_id, context: {...})`
+   - Save Q&A decisions as `context.decisions[]`
+
+Skip this step for round 2+ (context already established via `/cbp-round-input`).
+
+**If `auto_loop_mode === true`, skip Q&A regardless of round number** — the auto-loop already has authoritative requirements from the prior round's findings (round 1 is always manual in practice, but the rule is explicit so future round-1 auto-loops follow it).
+
+### Step 7: Spawn Task Planner Agent
+
+Spawn `cbp-task-planner` agent with:
+```yaml
+input:
+  task_number: N
+  round_number: N
+  requirements: task.requirements
+  round_requirements: [round-specific input from Step 3]
+  checkpoint: {id, title, goal, context}
+  task: {id, title, requirements, context}
+  previous_rounds: {count, files_pending, files_changed, testing_qa_output, unapproved_files}
+```
+
+**Round 2+ context**: The planner receives the previous round's testing-qa output and list of unapproved files.
+
+**Priority**: If `round_requirements` is set (round 2+), the planner focuses on those specific goals while respecting `task.requirements` as context.
+
+Wait for planner output.
+
+### Step 8: User Approval
+
+Present the plan to user:
+
+```
+## Round [N] Plan
+
+**Goal**: [goal]
+
+### Steps:
+1. [step]
+2. [step]
+...
+
+### Files to modify:
+| File | Action | Purpose |
+|------|--------|---------|
+| ... | ... | ... |
+```
+
+**Wave table** — when `approved_plan.waves[]` contains ≥2 entries, render a wave summary table BEFORE the files table:
+
+```
+### Execution Waves
+| Wave | Agent type | Files | Depends on | Skill preloads |
+|------|-----------|-------|-----------|----------------|
+| web-ui | cbp-round-executor | 7 | — | cbp-frontend-design, cbp-frontend-a11y |
+| backend-api | cbp-round-executor | 4 | — | — |
+```
+
+Single-wave plans present the existing flat plan view (no wave table) — backward compatible.
+
+**If `auto_loop_mode === true`**: skip the AskUserQuestion below; auto-approve the plan. Log `round.context.plan_approval = { mode: "auto_loop", auto_approved_at: <ISO> }`. Surface a one-line note in the chat output: `"Auto-approved under auto_loop_mode (round N of cap C)"` so the user can see the loop is active. Proceed to Step 9.
+
+**Else (manual mode)**, ask user via AskUserQuestion with explicit options:
+
+1. **Yes** — approve and start execution
+2. **No — needs changes** — user provides feedback, revise the plan (re-run Step 7 with feedback)
+3. **No — totally wrong** — discard plan, return to `/cbp-round-input` for new requirements
+
+**If "Yes"**: proceed to Step 9.
+**If "Needs changes"**: collect user feedback, re-spawn `cbp-task-planner` with feedback as constraint, present revised plan, ask again.
+**If "Totally wrong"**: save rejection reason to round context, auto-trigger `/cbp-round-input`.
+
+### Step 9: Auto-trigger Round Execute
+
+On approval, save planner output to round context via MCP `update_round`, then trigger `/cbp-round-execute`.
+
+```
+Plan approved. Starting execution phase...
+```
+
+## Key Rules
+
+- **Planning ONLY** — no code execution, no testing
+- Planner gets full context (checkpoint + task + previous rounds)
+- Round 1 auto-triggered from `/cbp-task-start`
+- Round 2+ triggered from `/cbp-round-input`
+- Claude NEVER git adds files in round commands
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_rounds`
+- **Writes**: MCP `add_round`, `update_round`, `update_task` (context only)
+- **Spawns**: `cbp-task-planner`
+- **Triggers**: `/cbp-round-execute` (auto, on plan approval)
+- **Triggered by**: `/cbp-task-start` (round 1), `/cbp-round-input` (round 2+)

package/templates/skills/cbp-round-update/SKILL.md

@@ -0,0 +1,163 @@
+---
+scope: org-shared
+name: cbp-round-update
+description: Check file approvals, complete round, and route to next step
+argument-hint: [chk-task-round | task-round]
+triggers: [cbp-round-input, cbp-task-check]
+effort: low
+---
+
+# Round Update Command
+
+Checks file approval status, completes the round, and routes to next step. NEVER asks the user to git add or stage anything — it only reads current state.
+
+## HARD GATE — Every Step Must Execute
+
+Step 2 (sync-approvals CLI) MUST exit 0. If it fails, do NOT proceed to Step 3. Before completing the round, verify:
+
+- [ ] `codebyplan round sync-approvals` exited 0
+
+If this is false: DO NOT proceed to Step 3.
+
+## Instructions
+
+### Step 1: Parse `$ARGUMENTS`
+
+Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}-{task}-{round}` (e.g. `108-1-2`) | `^[0-9]+-[0-9]+-[0-9]+$` | Checkpoint-bound: CHK-{chk} TASK-{task} ROUND-{round} |
+| `{task}-{round}` (e.g. `45-2`) | `^[0-9]+-[0-9]+$` | Standalone: standalone TASK-{task} ROUND-{round} |
+| _(empty)_ | — | Use MCP `get_current_task` / `get_rounds` to find the active task and latest round |
+
+Anything else is malformed — surface this error and stop:
+
+```
+round-update: invalid argument `{value}`. Expected:
+  108-1-2  → CHK-108 TASK-1 ROUND-2 (checkpoint-bound)
+  45-2     → standalone TASK-45 ROUND-2
+  (empty)  → active task and latest round
+```
+
+Error cases: `abc`, `108-`, `-1`, anything with whitespace or non-numeric characters. Note that `108-1` is **valid** here — it resolves to standalone TASK-108 ROUND-1 per the 2-segment task-round form. To target a checkpoint-bound round, use the 3-segment form `108-1-2`.
+
+#### Worked examples
+
+- `round-update 108-1-2` → CHK-108 TASK-1 ROUND-2
+- `round-update 45-2` → standalone TASK-45 ROUND-2
+- `round-update` (no arg) → active task and latest in-progress round via `get_current_task` + `get_rounds`
+- `round-update abc` → error: malformed
+
+### Step 1.5: Get Current Task and Round
+
+Given the parse from Step 1:
+
+| Parse | Resolution path |
+|-------|-----------------|
+| `{chk}-{task}-{round}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}`. MCP `get_tasks(checkpoint_id)` → filter `number === {task}`. MCP `get_rounds(task_id)` → filter `number === {round}`. |
+| `{task}-{round}` | MCP `get_tasks(repo_id, standalone: true)` → filter `number === {task}`. MCP `get_rounds(task_id)` → filter `number === {round}`. |
+| _(empty)_ | MCP `get_current_task(repo_id)` to find active task. MCP `get_rounds(task_id)` to find latest round (in-progress or completed). |
+
+If no task found: `No active task. Nothing to update.`
+
+### Step 2: Sync git diff + approvals via CLI
+
+Run:
+
+```
+npx codebyplan round sync-approvals --round-id <round_id> --task-id <task_id>
+```
+
+The CLI auto-resolves the worktree id, parses `git status --short`, merges drift + staging + web-UI flag, and writes both round and task.
+
+Read the stdout JSON: `{ added, stale_marked, reactivated, total_files }`.
+
+If the command exits non-zero, surface the stderr and STOP. Do NOT proceed to Step 3.
+
+### Step 3: Complete Round
+
+Calculate duration from `started_at` to now in minutes.
+Use MCP `complete_round(round_id, duration_minutes)`.
+
+### Step 4: Auto-Loop Decision
+
+Read the latest round's `improve_round_findings[]` and `testing_qa_output.totals.hard_fail`. If EITHER is non-clean (findings non-empty OR `hard_fail === true`), the auto-loop must spawn the next round automatically.
+
+Procedure:
+
+1. Compute `next_index = (round.context.auto_loop_index ?? 0) + 1`.
+2. **If `next_index > (round.context.auto_loop_cap ?? 5)`**: surface the cap-exhausted prompt via AskUserQuestion (options: extend cap, stop loop / drop into round-input, close task as-is). Persist `round.context.auto_loop_cap_exhausted = { user_choice, decided_at }` and route per choice.
+3. **Otherwise**: persist `round.context.auto_loop_decision = { spawned_next: true, next_index, decided_at }` on the CURRENT round via `update_round` (audit trail), then auto-trigger `/cbp-round-input` with NO AskUserQuestion. Pass `auto_loop_mode: true`, `auto_loop_index: next_index`, `auto_loop_cap: (prior cap ?? 5)` forward — round-start Step 4 persists them on the new round.
+
+If BOTH signals are clean, fall through to Step 5 (exit routing).
+
+### Step 5: Exit Routing
+
+**5a: Count files** — Display: `"Files: X total, Y approved, Z pending"`
+
+**5b: Route with four branches** (Step 4 already handled the dirty-loop case; Step 5 is the clean-exit path).
+
+**Branch D — IF `round.context.round_type === 'survey'` (checked FIRST):**
+
+Survey rounds produce no file diff; A/B/C predicates assume `files_changed[]` non-empty. Survey routing is decided by `improve_round_findings[]` instead:
+
+- `improve_round_findings[]` non-empty → auto-trigger `/cbp-round-input`
+- `improve_round_findings[]` empty → auto-trigger `/cbp-task-check`
+
+Output: `"## Round [N] Complete — Survey Round"` with duration, files=0, findings count, routing message. Skip Branches A/B/C.
+
+**Branch A — ELSE IF all files have `user_approved: true`:**
+
+```
+## Round [N] Complete - All Files Approved
+
+**Duration**: [N] minutes
+**Files**: [X] total, [X] approved, 0 pending
+```
+
+Surface AskUserQuestion (clean-exit user-gate):
+
+- **(a) close & complete round** → auto-trigger `/cbp-task-check`
+- **(b) start new round** → auto-trigger `/cbp-round-input`
+
+Persist `round.context.auto_loop_exit = { staged_count, unstaged_count, route, decided_at }`.
+
+**Branch B — ELSE IF unapproved files exist AND every unapproved file has `claude_approved: true` AND `testing_qa_output.totals.hard_fail: false` AND no `improve_round_findings[]`:**
+
+The clean-but-unstaged staging-gate case. Mode-dependent:
+
+- **Auto-loop exit** (the completed round had `auto_loop_mode === true` on its context AND Step 4 fell through here with BOTH signals clean): surface the Branch A clean-exit user-gate — do NOT auto-trigger `/cbp-round-input`. Branch B's entry condition already requires `no improve_round_findings[]`, so the auto-loop's verbatim-from-findings procedure has no input to formulate requirements from; auto-triggering round-input would loop on an empty input. Persist `round.context.auto_loop_exit.degenerate_empty_findings: true` (degenerate sub-case: no findings to feed round-input, so surface the clean-exit user-gate above instead of auto-triggering).
+- **Manual round**: emit staging-gate prompt and STOP. User stages files (never-git-add rule) and re-invokes; command then falls into Branch A.
+
+Manual-mode prompt:
+
+```
+## Round [N] Complete — Files Pending Staging
+
+**Files**: [X] total, [Y] approved, [Z] pending
+
+### Pending (passed all checks; not yet staged):
+- [path]
+
+Stage them (`git add <path>`) and re-run `/cbp-round-update` to proceed.
+Waiting for user to stage files.
+```
+
+**Branch C — ELSE (unapproved AND outstanding findings or `claude_approved: false`):**
+
+Unreachable in the auto-loop path — Step 4 catches it first. Retained for MANUAL invocation. Output `## Round [N] Complete - [Z] Files Pending` with file counts and list of unapproved paths; auto-trigger `/cbp-round-input`.
+
+## Key Rules
+
+- **Step 2 (CLI) must exit 0** — if it fails, STOP. The merge semantics are enforced by the CLI.
+- **Step 4 owns the dirty-loop case**; Step 5 owns the clean-exit case. Step 5 Branch C is for manual invocation only.
+- **NEVER ask user to git add files** — only reads staging status. **NEVER stage files** — Claude does not touch git staging area.
+- Auto-triggered by `/cbp-round-end`, or run manually by user.
+
+## Integration
+
+- **Triggered by**: `/cbp-round-end` (auto), or user manually
+- **Reads**: MCP `get_current_task`, `get_rounds`; delegates git+approval sync to `npx codebyplan round sync-approvals`
+- **Writes**: MCP `update_round` (auto_loop_decision / auto_loop_exit / auto_loop_cap_exhausted), `complete_round`; round+task files_changed written by CLI
+- **Triggers**: `/cbp-round-input` (Step 4 dirty-loop spawn; Branch A 'b' choice; Branch B auto-loop-exit; Branch C manual), `/cbp-task-check` (Branch A 'a' choice; Branch D survey-clean), staging-gate stop (Branch B manual mode), cap-exhausted prompt routes from Step 4 (any of the three options)