codebyplan 1.13.27 → 1.13.29

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.27";
+    VERSION = "1.13.29";
     PACKAGE_NAME = "codebyplan";
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.27",
+  "version": "1.13.29",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/agents/cbp-improve-round.md

@@ -279,6 +279,6 @@ Return findings sorted by severity (critical first). If no findings, return `sta
 ## Integration
 
 - **Spawned by**: `/cbp-round-end` (Step 6)
-- **Returns to**: `/cbp-round-end` which presents findings to user
+- **Returns to**: `/cbp-round-end` which auto-applies in-scope findings inline and routes out-of-scope findings to `/cbp-round-update`
 - **Does NOT**: Apply any changes
 - **Reads**: Changed files, task requirements, round context

package/templates/agents/cbp-task-check.md

@@ -9,7 +9,7 @@ effort: xhigh
 
 # Task Check Agent
 
-AI-driven production readiness review with user satisfaction discussion. Verifies all task requirements are met, checkpoint goals are aligned, and work is production-ready.
+AI-driven production readiness review with user satisfaction discussion. This is the **cross-round double-check** layer: per-round QA (build/lint/types per app, the `console.log`/debug scan, the OWASP/secret grep, API auth-enforcement curls, `pnpm audit`) already ran inside each round's `testing-qa-agent` — this agent does NOT re-run it. Its unique value is holistic: verifying all task requirements are met, checkpoint goals are aligned, the aggregated work is shippable, and — for tasks that span many rounds where scope can shift as new ideas/problems surface — detecting scope drift that should update the checkpoint or task rather than re-running per-round checks.
 
 **Numeric-claim verification (Proposal P6)**: when round summaries assert numeric facts (file counts, package counts, percentage changes, line counts, version numbers), verify each via direct count: `find ... | wc -l`, `grep -c`, `wc -l <file>`. Do NOT accept narrative numbers without a verification command. Mismatches between asserted and actual counts indicate documentation drift; flag as a finding requiring a fix.
 
@@ -95,14 +95,16 @@ Check `task.files_changed`:
 - List unapproved files
 - Determine if unapproved files block completion
 
-### Phase 6: Code Review
+### Phase 6: Code Review (holistic spot-check)
 
-Read ALL changed files and verify:
-- No obvious bugs or regressions
-- No security issues (hardcoded secrets, SQL injection, XSS)
-- No leftover debug code (console.log, TODO from this task)
-- Error handling present where needed
-- Consistent with existing codebase patterns
+Per-round QA already ran the line-level checks — the `console.log`/debug scan (round `testing-qa-agent` Phase 3.5), the OWASP secret/injection grep (Phase 5), the API auth-enforcement curl (Phase 3.55), and `pnpm audit` (Phase 3.7). Do NOT re-run them here. Phase 6 is a light holistic spot-check across the aggregated diff for what a single round cannot see:
+
+- No obvious bugs or regressions that emerge only when all rounds' changes are read together
+- No cross-round integration gaps (a field/contract introduced in one round that a later round broke)
+- Error handling present where needed at the feature boundary
+- Consistent with existing codebase patterns across the full task diff
+
+If the aggregated diff surfaces an obvious issue per-round QA missed, flag it as a finding — but the per-round scans are authoritative for line-level concerns.
 
 ### Phase 7: Shippable Feature Gate
 
@@ -125,6 +127,8 @@ Update `round_outcome_analysis` with findings.
 
 ### Phase 9: User Satisfaction Discussion
 
+For tasks that ran many rounds, scope drift accumulates quietly — each round may have absorbed a new idea or problem without the checkpoint/task requirements being updated. The satisfaction discussion is where that drift surfaces; treat the scope-divergence scan below as a first-class output, not an afterthought.
+
 Present findings to user via AskUserQuestion:
 
 ```

package/templates/hooks/README.md

@@ -2,7 +2,7 @@
 
 The `codebyplan` npm package ships a small, portable set of Claude Code hooks. They run in your project, use only generic primitives (`git rev-parse`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`), and degrade gracefully (exit 0) when their preconditions aren't met.
 
-Hook registration lives in [`hooks/hooks.json`](./hooks.json) — SessionStart, PreToolUse, and PostToolUse events are wired. (`Notification`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
+Hook registration lives in [`hooks/hooks.json`](./hooks.json) — PreToolUse, PostToolUse, and UserPromptSubmit events are wired. (`Notification`, `SessionStart`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
 
 **`cbp-statusline.sh` is auto-wired via `settings.project.base.json`.** The `statusLine` block is shipped inside `templates/settings.project.base.json` and merged into the consumer's `.claude/settings.json` automatically by `codebyplan claude install` (and on every `codebyplan claude update`). No manual copy-paste is required.
 
@@ -224,13 +224,32 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 ---
 
+### `cbp-context-window-notify.sh` — UserPromptSubmit
+
+Injects a one-time notice into Claude's context when the session's total token usage
+(input + cache-creation + cache-read tokens from the last assistant message) crosses
+`CBP_CONTEXT_WARN_TOKENS` (default: 200000). Reads the JSONL transcript directly — not the
+statusline payload — so the model itself, not just the status bar, is aware of a large window.
+
+**Blocks vs warns**: never blocks — exits 0 on every path. Advisory only.
+
+**Skips when**: `transcript_path` or `session_id` is absent from stdin, the transcript file does
+not exist, or usage cannot be parsed (degrades to 0, below threshold).
+
+**Re-arms**: the latch `${TMPDIR:-/tmp}/cbp-ctxwin-<session_id>.latched` is removed when usage
+drops below threshold (e.g. after `/compact` or `/clear`), so the notice re-fires on the next crossing.
+
+**Opt out**: set `CBP_CONTEXT_WARN_TOKENS` very high, or remove the `UserPromptSubmit` entry from settings.
+
+---
+
 ## Supporting (not registered)
 
 ### `test-hooks.sh` — invoked by `auto-test-hooks.sh`
 
 Test suite for the plugin's 9 registered hooks. Runs two passes:
 
-1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
+1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`, `cbp-context-window-notify`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
 2. **Functional smoke tests** — each hook is invoked with synthetic stdin matching its fast-path / graceful-degrade input; all must exit 0.
 
 Not in `hooks.json` — invoked indirectly via `auto-test-hooks.sh` on hook edits, or directly via `bash ${CLAUDE_PLUGIN_ROOT}/hooks/test-hooks.sh`.

package/templates/hooks/cbp-context-window-notify.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# @scope: org-shared
+# Hook: UserPromptSubmit
+# Purpose: Emit a one-time notice into Claude's context when the session's total
+#          context-window usage crosses CBP_CONTEXT_WARN_TOKENS (default 200000).
+#          Reads the last assistant message.usage from the JSONL transcript
+#          (input + cache_creation + cache_read) — independent of the statusline,
+#          so the model itself, not just the status bar, knows the window is large.
+#          Latches per session so the notice fires once; re-arms after /clear or
+#          /compact drops usage below the threshold. Always exits 0 — never blocks.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""' 2>/dev/null)
+
+[ -z "$TRANSCRIPT" ] && exit 0
+[ -z "$SESSION_ID" ] && exit 0
+[ ! -f "$TRANSCRIPT" ] && exit 0
+
+THRESHOLD="${CBP_CONTEXT_WARN_TOKENS:-200000}"
+LATCH="${TMPDIR:-/tmp}/cbp-ctxwin-${SESSION_ID}.latched"
+
+TOTAL=$(tail -n 400 "$TRANSCRIPT" \
+  | jq -rR 'fromjson? | select(.message.usage != null)
+      | (.message.usage
+         | ((.input_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0)))' \
+  2>/dev/null | tail -1) || TOTAL=0
+
+TOTAL="${TOTAL:-0}"
+
+if [ "$TOTAL" -ge "$THRESHOLD" ] 2>/dev/null; then
+  [ -f "$LATCH" ] && exit 0
+  touch "$LATCH"
+  jq -n --argjson tokens "$TOTAL" --argjson threshold "$THRESHOLD" \
+    '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:("Context-window notice: total token usage has reached \($tokens) (threshold \($threshold)). The window is large — consider /compact or /clear, and be deliberate about large new reads.")}}'
+  exit 0
+fi
+
+rm -f "$LATCH" 2>/dev/null || true
+exit 0

package/templates/hooks/cbp-mcp-round-sync.sh

@@ -5,6 +5,15 @@
 #          staging-status flip, and web-UI flag sync to the codebyplan CLI.
 #          Replaces the inline jq merge + curl PATCH with a single CLI call.
 #
+# Trigger context (CHK-197): complete_round is now called by /cbp-round-complete
+# (the permission-gated finalizer), which already runs `sync-approvals` once
+# BEFORE completing the round. This hook firing afterward is the expected
+# post-complete safety net — it catches approval drift between that pre-complete
+# sync and the approval_locked write; it is NOT a duplicate run to remove.
+# NOTE: this hook matches complete_round only; complete_standalone_round is NOT
+# covered, so standalone rounds rely solely on /cbp-round-complete's pre-complete
+# sync (pre-existing coverage gap, documented here intentionally — not fixed).
+#
 # Delegates to: npx codebyplan round sync-approvals
 #   - Git-diff drift merge (in/not-in DB vs git)
 #   - Staging-status → user_approved flip

package/templates/hooks/cbp-test-hooks.sh

@@ -255,6 +255,125 @@ fi
 
 echo ""
 
+# ===== HOOK SMOKE TESTS — cbp-context-window-notify =====
+echo "## Hook Smoke Tests — cbp-context-window-notify"
+
+HOOK="$HOOKS_DIR/cbp-context-window-notify.sh"
+FIXTURES_CTX="$HOOKS_DIR/__test-fixtures__/cbp-context-window-notify"
+
+if [ ! -f "$HOOK" ]; then
+  test_result "cbp-context-window-notify.sh present" "passed" "missing"
+else
+
+  # Case 1: over-threshold → exit 0 AND stdout has .hookSpecificOutput.additionalContext
+  ISO=$(mktemp -d)
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/over-threshold.jsonl" --arg s "sid-over-$$" \
+    '{transcript_path:$t,session_id:$s}')
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.additionalContext' >/dev/null 2>&1; then
+    test_result "cbp-context-window-notify.sh over-threshold exits 0 + emits additionalContext JSON" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh over-threshold exits 0 + emits additionalContext JSON" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+  rm -rf "$ISO"
+
+  # Case 2: under-threshold → exit 0 AND empty stdout
+  ISO=$(mktemp -d)
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/under-threshold.jsonl" --arg s "sid-under-$$" \
+    '{transcript_path:$t,session_id:$s}')
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-context-window-notify.sh under-threshold exits 0 + empty stdout" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh under-threshold exits 0 + empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 3: latch — fire once (over), second identical call (same session_id, same TMPDIR) → empty stdout
+  ISO=$(mktemp -d)
+  SID="sid-latch-$$"
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/over-threshold.jsonl" --arg s "$SID" \
+    '{transcript_path:$t,session_id:$s}')
+  echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" >/dev/null 2>&1
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-context-window-notify.sh latch suppresses second over-threshold call" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh latch suppresses second over-threshold call" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 4: re-arm — fire over (creates latch), then under → latch file removed
+  ISO=$(mktemp -d)
+  SID="sid-rearm-$$"
+  STDIN_OVER=$(jq -n --arg t "$FIXTURES_CTX/over-threshold.jsonl" --arg s "$SID" \
+    '{transcript_path:$t,session_id:$s}')
+  STDIN_UNDER=$(jq -n --arg t "$FIXTURES_CTX/under-threshold.jsonl" --arg s "$SID" \
+    '{transcript_path:$t,session_id:$s}')
+  echo "$STDIN_OVER" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" >/dev/null 2>&1
+  echo "$STDIN_UNDER" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" >/dev/null 2>&1
+  LATCH_FILE="$ISO/cbp-ctxwin-${SID}.latched"
+  if [ ! -f "$LATCH_FILE" ]; then
+    test_result "cbp-context-window-notify.sh re-arm removes latch on under-threshold" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh re-arm removes latch on under-threshold" "passed" "failed (latch still present)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 5: cache-expired → exit 0 AND emits additionalContext JSON
+  ISO=$(mktemp -d)
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/cache-expired.jsonl" --arg s "sid-cache-$$" \
+    '{transcript_path:$t,session_id:$s}')
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.additionalContext' >/dev/null 2>&1; then
+    test_result "cbp-context-window-notify.sh cache-expired exits 0 + emits additionalContext JSON" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh cache-expired exits 0 + emits additionalContext JSON" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 6: graceful-degrade — empty stdin → exit 0
+  ISO=$(mktemp -d)
+  EXIT_CODE=$(echo '' | TMPDIR="$ISO" bash "$HOOK" >/dev/null 2>&1; echo $?)
+  if [ "$EXIT_CODE" = "0" ]; then
+    test_result "cbp-context-window-notify.sh graceful-degrade empty stdin exits 0" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh graceful-degrade empty stdin exits 0" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 7: malformed-line tolerance — a malformed/partial transcript line must NOT
+  # abort the hook (D3 "always exit 0"); the valid over-threshold line is still parsed
+  # (jq -rR 'fromjson?') and the notice still fires. The fixture lives only under
+  # .claude/hooks/__test-fixtures__; guard on its presence so this case stays
+  # byte-identical with the templates copy (which ships no __test-fixtures__ tree).
+  if [ -f "$FIXTURES_CTX/malformed.jsonl" ]; then
+    ISO=$(mktemp -d)
+    STDIN=$(jq -n --arg t "$FIXTURES_CTX/malformed.jsonl" --arg s "sid-malformed-$$" \
+      '{transcript_path:$t,session_id:$s}')
+    OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+    EXIT_CODE=$?
+    if [ "$EXIT_CODE" = "0" ] \
+       && echo "$OUTPUT" | jq -e '.hookSpecificOutput.additionalContext' >/dev/null 2>&1; then
+      test_result "cbp-context-window-notify.sh malformed-line tolerance exits 0 + emits additionalContext JSON" "passed" "passed"
+    else
+      test_result "cbp-context-window-notify.sh malformed-line tolerance exits 0 + emits additionalContext JSON" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+    fi
+    rm -rf "$ISO"
+  else
+    test_result "cbp-context-window-notify.sh malformed-line tolerance (fixture absent — templates runtime)" "passed" "passed"
+  fi
+
+fi
+
+echo ""
+
 # ===== SUMMARY =====
 echo "=== TEST SUMMARY ==="
 echo -e "Passed: ${GREEN}$PASSED${NC}"

package/templates/hooks/hooks.json

@@ -1,5 +1,15 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-context-window-notify.sh"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",

package/templates/settings.project.base.json

@@ -55,7 +55,8 @@
       "Skill(cbp-checkpoint-create)",
       "Skill(cbp-checkpoint-check)",
       "Skill(cbp-checkpoint-complete)",
-      "Skill(cbp-round-update)",
+      "Skill(cbp-round-complete)",
+      "Skill(cbp-round-execute)",
       "Skill(cbp-session-end)",
       "Skill(cbp-task-complete)",
       "Skill(cbp-standalone-task-create)",
@@ -114,9 +115,9 @@
       "Skill(cbp-refresh-infra)",
       "Skill(cbp-round-check)",
       "Skill(cbp-round-end)",
-      "Skill(cbp-round-execute)",
       "Skill(cbp-round-input)",
       "Skill(cbp-round-start)",
+      "Skill(cbp-round-update)",
       "Skill(cbp-session-start)",
       "Skill(cbp-setup-e2e)",
       "Skill(cbp-setup-eslint)",

package/templates/skills/cbp-build-cc-mode/SKILL.md

@@ -31,19 +31,20 @@ Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-dat
 
 | skill             | model  | effort | reason                                                                                                            |
 | ----------------- | ------ | ------ | ----------------------------------------------------------------------------------------------------------------- |
-| cbp-round-end         | sonnet | high   | Spawns cbp-improve-round agent; skill body summarises + presents user findings-decision — lighter than xhigh suffices |
+| cbp-round-end         | sonnet | high   | Spawns cbp-improve-round agent; auto-applies in-scope findings + routes out-of-scope to round-update — lighter than xhigh suffices |
 | cbp-task-check        | sonnet | high   | Thin orchestrator over spawned cbp-task-check agent; inline-fallback path keeps Opus for safety                       |
 | cbp-checkpoint-update | sonnet | high   | Status updates + context patches mostly; lighter than xhigh                                                       |
 | cbp-ship-main         | sonnet | high   | Production-impacting PR creation; keep Opus reasoning but drop effort                                             |
 | cbp-merge-main        | sonnet | high   | Long-lived-branch integration merge — surgical conflict resolution, no authoring                                  |
 
-### Haiku-low skills (9)
+### Haiku-low skills (10)
 
 `model: haiku` + `effort: low`. Pure mechanical / dispatch / templated work.
 
 | skill                  | model | effort | reason                                                                                   |
 | ---------------------- | ----- | ------ | ---------------------------------------------------------------------------------------- |
-| cbp-round-update           | haiku | low    | Pure mechanical: read git status, check approvals, route per rules                       |
+| cbp-round-update           | haiku | low    | Pure mechanical: triage round state (claude_approved/findings/hard_fail), route to round-complete or round-input |
+| cbp-round-complete         | haiku | low    | Pure mechanical: sync-approvals git-add reconcile, complete round, route per unapproved count |
 | cbp-round-check            | haiku | low    | Run build/lint/types commands, parse output, update QA                                   |
 | cbp-todo                   | haiku | low    | Dispatch: single MCP call + route to next command                                        |
 | cbp-checkpoint-complete    | haiku | low    | Pure finalization — mark completed, write summary; judgment happened in checkpoint-check |

package/templates/skills/cbp-build-cc-settings/reference/cbp-permission-policy.md

@@ -22,7 +22,7 @@ Precedence is `deny > ask > allow`; arrays union across scopes (managed/user/pro
 
 ### `allow` — the autonomous workflow surface
 
-- **Non-lifecycle, non-shipment `/cbp-*` skills** — authoring (`cbp-build-cc-*`), frontend (`cbp-frontend-*`), git (`cbp-git-*`, `cbp-merge-main`, `cbp-refresh-infra`), round work (`cbp-round-check`/`-end`/`-execute`/`-input`/`-start`), setup/configure (`cbp-setup-*`, `cbp-ship-configure`, `cbp-supabase-*`), task prep (`cbp-task-check`/`-create`/`-start`/`-testing`, `cbp-standalone-task-check`/`-testing`), planning (`cbp-checkpoint-plan`/`-update`), plus `cbp-session-start` and `cbp-todo`. Invoking a skill is the intended mode of operation; the gated side effects happen inside via the Bash/MCP tools the skill calls, which carry their own tiering. The lifecycle/state-transition skills are the exception — they live in `ask` (next section).
+- **Non-lifecycle, non-shipment `/cbp-*` skills** — authoring (`cbp-build-cc-*`), frontend (`cbp-frontend-*`), git (`cbp-git-*`, `cbp-merge-main`, `cbp-refresh-infra`), round work (`cbp-round-check`/`-end`/`-input`/`-start`/`-update` — `cbp-round-update` is autonomous triage that only reads round state and routes to `cbp-round-complete` or `cbp-round-input`, so it runs without a prompt), setup/configure (`cbp-setup-*`, `cbp-ship-configure`, `cbp-supabase-*`), task prep (`cbp-task-check`/`-create`/`-start`/`-testing`, `cbp-standalone-task-check`/`-testing`), planning (`cbp-checkpoint-plan`/`-update`), plus `cbp-session-start` and `cbp-todo`. Invoking a skill is the intended mode of operation; the gated side effects happen inside via the Bash/MCP tools the skill calls, which carry their own tiering. The lifecycle/state-transition and plan-approval skills are the exception — they live in `ask` (next section).
 - **All `mcp__codebyplan__*` reads** (`get_*`, `list_*`, `search_*`, `health_check`, `lookup_symbol`, `resolve_library_id`, `get_chunk`).
 - **Routine workflow-write MCP tools** the pipeline calls many times per task: create/update/complete checkpoint, task, and round; session log + session-state writes; `create_worktree`, `add_library`, `flag_stale_chunk`, `update_server_config`, `update_eslint_repo_config`, `update_task_template`. Gating these with `ask` would make the autonomous workflow unusable.
 - **Read/safe CLI commands** (both `codebyplan X` and `npx codebyplan X`): `whoami`, `resolve-worktree`, `statusline`, `ports`, `tech-stack`, `eslint`, `round`, `help`, `--version`.
@@ -30,7 +30,8 @@ Precedence is `deny > ask > allow`; arrays union across scopes (managed/user/pro
 ### `ask` — the deliberate confirm-gate
 
 - **Production-shipment skills**: `cbp-ship`, `cbp-ship-main`, `cbp-checkpoint-end` — these promote/deploy to production, so they prompt even in an otherwise auto-allowed setup.
-- **Lifecycle / state-transition skills**: `cbp-checkpoint-start`, `cbp-checkpoint-create`, `cbp-checkpoint-check`, `cbp-checkpoint-complete`, `cbp-round-update`, `cbp-session-end`, `cbp-task-complete`, `cbp-standalone-task-create`, `cbp-standalone-task-start`, `cbp-standalone-task-complete` — these open or close checkpoints, tasks, rounds, and sessions (advancing workflow state in the database), so they stop for explicit confirmation rather than running autonomously.
+- **Lifecycle / state-transition skills**: `cbp-checkpoint-start`, `cbp-checkpoint-create`, `cbp-checkpoint-check`, `cbp-checkpoint-complete`, `cbp-round-complete`, `cbp-session-end`, `cbp-task-complete`, `cbp-standalone-task-create`, `cbp-standalone-task-start`, `cbp-standalone-task-complete` — these open or close checkpoints, tasks, rounds, and sessions (advancing workflow state in the database), so they stop for explicit confirmation rather than running autonomously. `cbp-round-complete` is the permission-gated round finalizer (reconciles the user's `git add`s, completes the round, routes onward); its `ask` prompt replaces the in-skill confirmation that used to live in `cbp-round-update` — which is now an autonomous, `allow`-tier triage step.
+- **Plan-approval gate**: `cbp-round-execute` — the round plan is approved by confirming this `ask` prompt rather than via an in-skill AskUserQuestion. `cbp-round-start` runs its planning Q&A, then hands off to `cbp-round-execute`; the permission prompt is the user's go/no-go on the plan.
 - **Destructive / admin MCP tools**: `delete_session_log`, `delete_worktree`, `create_repo`, `release_assignment`. (The launch and member-admin tools were dropped from the MCP surface in CHK-180 — those concerns are web-app only now.)
 - **Mutating / external / clobber-risk CLI commands** (both prefixes): `setup`, `login`, `logout`, `upgrade-auth`, `config` (can overwrite committed `.codebyplan/` files), `branch` (rewrites branch config), `ship`, `claude` (`install`/`update`/`uninstall` overwrite `.claude/`).
 

package/templates/skills/cbp-build-cc-skill/reference/cbp-quality.md

@@ -88,7 +88,7 @@ A skill should do one thing in the pipeline. If a skill both plans AND executes,
 If the skill is part of a chain, show it:
 
 ```
-/cbp-round-start (planning) → [user approval] → /cbp-round-execute (auto)
+/cbp-round-start (planning) → /cbp-round-execute (ask-tier permission = plan approval)
 ```
 
 ### Approval Gates

package/templates/skills/cbp-merge-main/SKILL.md

@@ -42,7 +42,7 @@ Triggered by `/cbp-task-start` (Step 3.6, optional stale-check), `/cbp-task-comp
      - **Cancel** — abort the skill.
    - `unstaged_dirty=false AND staged_present=true` → print one informational line and proceed to Step 1:
      `Staged changes detected — proceeding with merge.`
-     (Pre-staged files will be included in the merge commit at Step 2 — this is intentional; the caller already approved them via /cbp-round-update.)
+     (Pre-staged files will be included in the merge commit at Step 2 — this is intentional; the caller already approved them via /cbp-round-complete.)
    - `unstaged_dirty=false AND staged_present=false` → proceed silently to Step 1.
    - Either `git diff` command exits with code ≥ 2 (git hard error — not-a-repo, detached HEAD with no commits, index lock, corrupt object store): surface the raw error output and STOP. Do NOT proceed to Step 1.
 

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

@@ -0,0 +1,164 @@
+---
+scope: org-shared
+name: cbp-round-complete
+description: Reconcile user git-add approvals, complete the round, and route to the next step
+argument-hint: [chk-task-round | task-round]
+triggers: [cbp-task-check, cbp-standalone-task-check, cbp-round-input]
+effort: low
+---
+
+## Kind Detection
+
+Inspect the resolved identifier from argument parsing to determine the task kind:
+
+| Identifier shape | KIND |
+|-----------------|------|
+| `{task}-{round}` (2-segment, e.g. `45-2`) | `standalone` |
+| `{chk}-{task}-{round}` (3-segment, e.g. `141-3-1`) | `checkpoint` |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. |
+
+Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
+
+| Operation | `checkpoint` KIND | `standalone` KIND |
+|-----------|------------------|-------------------|
+| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
+| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
+| Update round | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
+| Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?, caller_worktree_id)` ⚠️ `caller_worktree_id` is REQUIRED for standalone |
+
+# Round Complete Command
+
+The **permission-gated finalizer** for a round that `/cbp-round-update` triaged as clean. It reconciles which files the **user** approved via `git add`, completes the round, and routes to the next step.
+
+This skill is gated by an `ask`-tier `Skill(cbp-round-complete)` permission rule in `settings.json`. **The permission prompt IS the user confirmation** — there is NO AskUserQuestion inside this skill. If the user declines the permission, the skill does not run: nothing is synced, no round is completed, and the user can stage files and re-invoke (directly or by re-running `/cbp-round-update`) when ready.
+
+## 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 `cbp-round-start` Step 0 "CHK / TASK / ROUND Identifier Notation Vocabulary"):
+
+| 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 Kind Detection to find active task and latest round |
+
+Anything else is malformed — surface this error and stop:
+
+```
+round-complete: 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
+```
+
+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`.
+
+### 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_standalone_rounds` via `get_current_standalone_task` or direct task lookup → filter `number === {round}`. |
+| _(empty)_ | Use Kind Detection: checkpoint KIND → MCP `get_current_task(repo_id)` + `get_rounds(task_id)`; standalone KIND → MCP `get_current_standalone_task(repo_id)` + `get_standalone_rounds(standalone_task_id)`. |
+
+If no task found: `No active task. Nothing to complete.`
+
+### Step 2: Sync git diff + approvals via CLI
+
+Reconcile which files the user has approved by staging them. Run:
+
+```
+npx codebyplan round sync-approvals --round-id <round_id> --task-id <task_id>
+```
+
+The CLI auto-resolves the caller worktree id with the following precedence:
+1. `--caller-worktree-id <uuid>` override (if passed — skips all resolution)
+2. Per-device branch-keyed cache (`.codebyplan/worktree.local.json`)
+3. In-process tuple API call: `POST /worktrees/resolve` using `(device_id, repo_path, branch)`
+
+On the write path (non `--dry-run`), if the worktree id cannot be resolved the CLI **hard-fails with exit 1** and prints an actionable message. To pre-populate the cache:
+
+```
+npx codebyplan resolve-worktree --cache
+```
+
+If this worktree is not yet registered, run `npx codebyplan setup` first, then re-run `/cbp-round-complete`.
+
+The CLI parses `git status --short`, merges drift + staging + web-UI flag, and writes both round and task (forwarding `caller_worktree_id` on both writes so the server honors the feat-worktree lock). A **cleanly staged** file (`git add`-ed, no further unstaged changes) becomes `user_approved: true`.
+
+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.
+
+This is the **single** explicit reconcile owned by this skill. (The `cbp-mcp-round-sync.sh` PostToolUse hook fires again right after Step 3's `complete_round` — see the note below — but that is the existing post-complete safety net, not a duplicate run to schedule here.)
+
+### Step 3: Complete the Round
+
+Calculate duration from the round's `started_at` to now in minutes.
+
+- **checkpoint KIND**: MCP `complete_round(round_id, duration_minutes)`.
+- **standalone KIND**: MCP `complete_standalone_round(standalone_round_id, duration_minutes, caller_worktree_id)`. ⚠️ `caller_worktree_id` is REQUIRED — resolve via `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`. If `CALLER_WT` is empty, surface this warning and ask the user to confirm before proceeding:
+
+  ```
+  Warning: could not resolve caller_worktree_id (npx codebyplan resolve-worktree returned empty).
+  The complete_standalone_round call may be rejected by the pre-guard. Proceed anyway? (yes / no)
+  ```
+
+  If the user confirms yes, proceed with `caller_worktree_id: ""`. If no, stop.
+
+`complete_round` / `complete_standalone_round` sets the round `completed`, locks all `file_changes` for the round (`approval_locked: true`), and returns `unapproved_files[]` + `unapproved_count`. Hold those for routing.
+
+> **PostToolUse hook note**: completing the round fires the `cbp-mcp-round-sync.sh` PostToolUse hook (matcher `mcp__codebyplan__complete_round`), which runs `sync-approvals` once more as a post-complete safety net for any approval drift between Step 2 and the lock. This is **expected** and is not double-processing — Step 2 is the pre-complete reconcile that makes `unapproved_count` accurate for routing; the hook is the existing catch-up. Note the hook matches `complete_round` only — `complete_standalone_round` is **not** covered by it (a pre-existing gap), so standalone rounds rely solely on this skill's Step 2 reconcile.
+
+### Step 4: Route
+
+**4a — Count files** — Display: `"Round N complete — Files: X total, Y approved, Z pending"`.
+
+**4b — Route on `unapproved_count`** (from Step 3's `complete_round` response):
+
+- **`unapproved_count === 0`** (every file user-approved): the user has signed off on the whole round.
+  - checkpoint KIND → auto-trigger `/cbp-task-check`.
+  - standalone KIND → auto-trigger `/cbp-standalone-task-check`.
+- **`unapproved_count > 0`** (user withheld approval on some files): the unstaged files are the signal that more work is wanted on them. Auto-trigger `/cbp-round-input` — its Step 2 deep analysis reads exactly those `user_approved === false` files and formulates the next round's requirements. This route is **independent of how many files are staged**; round-input is reachable even when zero files were staged.
+
+  - **Degenerate auto-loop guard**: if the just-completed round had `round.context.auto_loop_mode === true` AND it was a clean exit (no `improve_round_findings[]`, no hard-fail — which is why `/cbp-round-update` triaged it to round-complete in the first place), do NOT auto-trigger `/cbp-round-input`. Its auto-loop path transcribes the prior round's findings verbatim, and a clean round has none — auto-triggering would spin on an empty input. Instead surface the clean-exit note below and STOP; the user stages the pending files and re-invokes (or runs `/cbp-round-input` manually). Persist `round.context.round_complete.degenerate_auto_loop_exit = true`.
+
+    ```
+    ## Round N Complete — Auto-loop finished clean
+
+    **Files**: X total, Y approved, Z pending
+
+    Pending files passed all checks; they are just not staged. Stage them
+    (`git add <path>`) to finish the task, or run /cbp-round-input to start
+    another round.
+    ```
+
+Persist a breadcrumb on the round via `update_round` / `update_standalone_round` per KIND: `round.context.round_complete = { staged_count, unstaged_count, route, decided_at }`.
+
+## Key Rules
+
+- **Permission prompt = confirmation** — gated by `ask`-tier `Skill(cbp-round-complete)`. NEVER add an AskUserQuestion to confirm running; the harness prompt is the gate. A declined permission is a clean no-op.
+- **Step 2 (CLI) must exit 0** — if it fails, STOP before `complete_round`. The merge semantics are enforced by the CLI.
+- **NEVER ask the user to git add files** — Step 2 only reads staging status. **NEVER stage files** — Claude does not touch the git staging area; the user's `git add` is the approval signal.
+- **standalone KIND Step 3**: `caller_worktree_id` is REQUIRED for `complete_standalone_round` — always resolve and pass it.
+- **Auto-triggered by `/cbp-round-update`** (clean triage), or run manually by the user.
+
+## Integration
+
+- **Gates**: `ask`-tier `Skill(cbp-round-complete)` permission prompt — the harness confirms before the skill runs; a decline makes NO writes. There is no in-skill AskUserQuestion.
+- **Triggered by**: `/cbp-round-update` (auto, clean triage), or user manually
+- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND); delegates git+approval sync to `npx codebyplan round sync-approvals`
+- **Writes**: MCP `complete_round` / `complete_standalone_round` (per KIND); `update_round` / `update_standalone_round` (`round_complete` breadcrumb); round+task `files_changed` written by the CLI
+- **Triggers**: `/cbp-task-check` (checkpoint KIND, all files approved), `/cbp-standalone-task-check` (standalone KIND, all files approved), `/cbp-round-input` (some files unapproved — fires independent of staging count)