codebyplan 1.13.23 → 1.13.25

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

@@ -54,6 +54,8 @@ Pass `--dry-run` through if the skill was invoked with a dry-run arg.
 
 Parse JSON from Step 3. Report `pr_url`, `merge_commit`, `branch_deleted`. If `checks_failed: true`, surface `checks_failure_reason` and stop.
 
+> **gh false-negative workaround.** `codebyplan ship` can report `checks_failed: true` when the underlying `gh` query reads a stale/mismatched check field (it queries `conclusion`/`state` and the GitHub API can lag). Before treating the stop as final, verify the real status: `gh pr checks <PR> --watch`. If every required check is green, merge manually with `gh pr merge <PR> --merge` — add `--admin` ONLY to escape a transient secondary-rate-limit loop, never to bypass a genuinely-failing gate. Never auto-merge silently on a `checks_failed` report; this verification is a manual decision.
+
 If `bumps[]` is present with any non-skipped entry, surface a **Version bumps** line per package — `<name>: <currentVersion> → <nextVersion>` — so the user sees what this PR will publish on merge.
 
 If `branch_deleted === true`, run a conditional Supabase preview-branch teardown for the feat branch that was just merged:

package/templates/skills/cbp-standalone-task-create/SKILL.md

@@ -17,7 +17,7 @@ Create a new standalone task — independent of any checkpoint. Gathers user con
 
 ## Identifier Notation
 
-Standalone tasks use a bare number (e.g. `45` = standalone TASK-45). There is no checkpoint segment. Canonical notation follows `.claude/rules/notation-consistency.md`.
+Standalone tasks use a bare number (e.g. `45` = standalone TASK-45). There is no checkpoint segment. Canonical notation follows `cbp-round-start` Step 0 "CHK / TASK / ROUND Identifier Notation Vocabulary".
 
 ## Instructions
 

package/templates/skills/cbp-task-check/SKILL.md

@@ -35,7 +35,7 @@ Inline-fallback is NOT a quality downgrade trapdoor — every Phase from the age
 
 ### Step 1: Parse `$ARGUMENTS`
 
-Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+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 |
 |-------|-------|-------------|

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

@@ -14,7 +14,7 @@ Complete the current task. Auto-triggered by `/cbp-task-testing` when all tests
 
 ### Step 1: Parse `$ARGUMENTS`
 
-Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+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 |
 |-------|-------|-------------|

package/templates/skills/cbp-task-create/SKILL.md

@@ -17,7 +17,7 @@ Create a new task within the active checkpoint. Gathers user context, analyzes e
 
 ## Identifier Notation
 
-This skill operates on the **active** checkpoint resolved via MCP `get_current_task` and does not accept a positional identifier argument. The task it creates gets its `number` from the next-available slot within the active checkpoint (checkpoint-bound). Canonical chk-task-round notation — used in prose, error messages, and cross-references — follows `.claude/rules/notation-consistency.md` "CHK / TASK / ROUND Identifier Notation": `108-1` (CHK-108 TASK-1), `108-1-2` (round 2 of CHK-108 TASK-1).
+This skill operates on the **active** checkpoint resolved via MCP `get_current_task` and does not accept a positional identifier argument. The task it creates gets its `number` from the next-available slot within the active checkpoint (checkpoint-bound). Canonical chk-task-round notation — used in prose, error messages, and cross-references — follows `cbp-round-start` Step 0 "CHK / TASK / ROUND Identifier Notation Vocabulary": `108-1` (CHK-108 TASK-1), `108-1-2` (round 2 of CHK-108 TASK-1).
 
 **Bare-number argument**: if a bare number (e.g. `42`) is provided with no checkpoint context, this skill cannot resolve it to a checkpoint-bound task:
 
@@ -61,6 +61,55 @@ Use MCP `get_tasks` for the checkpoint. Review:
 - Task statuses (completed, in_progress, pending)
 - Dependencies between tasks
 
+### Step 3.5: Immediate Issue Capture Contract
+
+#### Default to Current Scope
+
+Discovered issues MUST be captured. The default target is current scope (round → task → checkpoint); standalone tasks are RARE.
+
+#### How to Capture (top-down routing — use the first row that fits)
+
+| Situation | Action |
+|-----------|--------|
+| Trivial inline fix (≤5 min, mechanical, scope-clean) | Apply in the CURRENT round per `cbp-round-end` reference `findings-presentation.md` "Trivial-Resolution Exception" |
+| Related to the current task's domain | Create a new ROUND in the current task |
+| Fits the current checkpoint goal but is meaningfully separate | Create a new TASK in the current checkpoint via `create_task(checkpoint_id)` |
+| Large enough to need multiple tasks AND fits no current checkpoint | Create a NEW CHECKPOINT via `create_checkpoint` |
+| Genuinely orphan work — off-axis from all active checkpoints AND user has explicitly confirmed standalone | Create a STANDALONE task via `create_task(repo_id)` — rare |
+| Timed re-check waiting on upstream fix | Standalone task with `context.re_check_date` |
+
+Standalone routing requires explicit user confirmation — silence is NOT confirmation.
+
+#### Consolidation Before Creation (MANDATORY)
+
+Before calling `create_task` for a finding, run a two-step dedup + bundle check:
+
+**Step 1 — Dedup against pending standalone tasks:**
+
+```
+mcp__codebyplan__get_tasks(repo_id, standalone=true, status="pending")
+```
+
+Compare the proposed task to each pending standalone task on these match dimensions:
+
+| Match dimension | Action if matched |
+|-----------------|-------------------|
+| Same target file(s) | STOP — `update_task` to append, do not create new |
+| Same feature / module | STOP — `update_task` to append, do not create new |
+| Same root cause (e.g. "prettier drift", "router bug") | STOP — `update_task` to append, do not create new |
+| Same dependency / advisory | STOP — `update_task` to append, do not create new |
+
+If a match is found, surface it to the user before appending:
+
+```
+Found existing pending task TASK-[N]: [title]
+This finding overlaps on [dimension]. Append to TASK-[N] instead of creating new? (yes / no — create separately)
+```
+
+Default to append. Only create a separate task if the user explicitly says no, OR if the existing task is in_progress / completed (in which case use `context.related_task_ids[]` on the new task to cross-reference).
+
+**Step 2 — Bundle within the same agent invocation:** If a single agent run surfaces 2+ findings that share any match dimension, MERGE them into a SINGLE `create_task` call. Do NOT loop and create one task per finding.
+
 ### Step 4: Analyze Codebase Context
 
 Brief inline analysis:

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

@@ -15,7 +15,7 @@ Start a task by loading context from the database and preparing for work.
 
 ### Step 1: Parse `$ARGUMENTS`
 
-Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+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 |
 |-------|-------|-------------|
@@ -158,7 +158,7 @@ Skip this step if the task title and requirements contain no CVE ID (`CVE-YYYY-N
 1. Run `pnpm audit --json` from the monorepo root. If it fails (network, registry), surface the error and stop — do NOT start a CVE task without a clean snapshot.
 2. Parse the advisory list from the JSON output.
 3. Call MCP `get_tasks(repo_id)`; for each advisory, match by ID in task title/requirements.
-4. For every advisory with no matching open task, call MCP `create_task` per `immediate-issue-capture.md`.
+4. For every advisory with no matching open task, call MCP `create_task` per `cbp-task-create` Step 3.5 "Immediate Issue Capture Contract".
 5. Report the sweep result:
    ```
    ## CVE/GHSA Audit Sweep

package/templates/skills/cbp-task-testing/SKILL.md

@@ -25,7 +25,7 @@ Per-wave `testing-qa-agent` runs inside `/cbp-round-execute` Step 5. This skill
 
 ### Step 1: Parse `$ARGUMENTS`
 
-Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+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 |
 |-------|-------|-------------|
@@ -170,7 +170,7 @@ For each finding, record: `{category, file, description, severity: 'low'|'medium
 
 Findings with severity `medium` or `high` feed the Step 9 problem classification. `low` findings are recorded in `task_testing_output` for the record but do not block.
 
-If any finding points to a need that exceeds task scope (e.g. a utility worth extracting for the wider codebase, a convention the repo should adopt globally), route per `immediate-issue-capture.md` "How to Capture" — default to a NEW TASK in the current checkpoint, not a standalone task. Standalone routing applies only when the finding is genuinely off-axis from every active checkpoint AND the user has confirmed standalone routing.
+If any finding points to a need that exceeds task scope (e.g. a utility worth extracting for the wider codebase, a convention the repo should adopt globally), route per `cbp-task-create` Step 3.5 "Immediate Issue Capture Contract — How to Capture" — default to a NEW TASK in the current checkpoint, not a standalone task. Standalone routing applies only when the finding is genuinely off-axis from every active checkpoint AND the user has confirmed standalone routing.
 
 ### Step 7: Separate Claude-Testable vs User-Testable
 

package/templates/skills/cbp-todo/SKILL.md

@@ -44,7 +44,7 @@ With `USER_ID` resolved, call MCP `get_todos({ repo_id, user_id, worktree_id })`
 
 - The head carries `command`, `instructions`, `state`, `metadata`, `worktree_id`, `checkpoint_id`, `task_id`.
 - The routing context (checkpoint/task) lives in **`rows[0].metadata`**.
-- `get_todos` is **pure-read** — `apps/todo-worker` is the sole regen authority. NEVER call `regenerate_todos_for_repo`.
+- `get_todos` is **pure-read** — `apps/todo-worker` is the sole regen authority. NEVER call `get_next_action` or `regenerate_todos_for_repo`.
 - Empty array, or `USER_ID` unavailable → go to Step 3 (empty-queue fallback).
 
 Queue `command` values may use the `/codebyplan:<name>` plugin-namespace form (e.g. `/codebyplan:round-start`); treat each as the matching `/cbp-<name>` skill for the Step 2 matrix.
@@ -76,6 +76,39 @@ Options:
 
 `<short-uuid>` = first 8 chars of the worktree UUID. Caller unresolved → render "this one" as `(unresolved / —)`. Name lookup miss → show the UUID alone. Wait for the user. NEVER propose reassigning the checkpoint to the caller worktree.
 
+### Step 1.55: Stale-Entity Guard
+
+Ownership passed (Step 1.5). Now guard against a lagging queue routing into already-finished work — the queue head (`rows[0]`) is produced by the todo-worker and can be stale (`health_check.todos_freshness_ok === false` is the signal), so a head command may target a checkpoint or task that was completed/cancelled since the queue was last regenerated. Reuse the `status` + task statuses already loaded in Step 1.5 — no extra reads, and NEVER call `get_next_action` or `regenerate_todos_for_repo` (an empty/stale queue is reconciled by the todo-worker, never re-derived here).
+
+Reject the auto-trigger when EITHER holds:
+
+- The target checkpoint's `status` is `completed` or `cancelled`.
+- Every task returned by `get_tasks(checkpoint_id)` (loaded in Step 1.5) has status `completed` or `cancelled` — no actionable task remains.
+
+On reject, surface the mismatch — naming the head command and the stale entity — then **STOP** (do not auto-trigger the head command). Use the variant matching the trigger condition:
+
+- Checkpoint itself `completed`/`cancelled`:
+
+```
+⚠ Stale queue head: <command> targets CHK-<NNN> which is <status>.
+The todo queue has not caught up. Options:
+  A) /cbp-todo — re-resolve the queue
+  B) /cbp-checkpoint-create — start new work
+  C) /cbp-session-end
+```
+
+- Checkpoint still active but every task `completed`/`cancelled`:
+
+```
+⚠ Stale queue head: <command> targets CHK-<NNN> — all tasks are completed/cancelled, no actionable work remains.
+The todo queue has not caught up. Options:
+  A) /cbp-todo — re-resolve the queue
+  B) /cbp-checkpoint-create — start new work
+  C) /cbp-session-end
+```
+
+Skip this gate when the routing target has no checkpoint (idle — see Step 3) or the command is `/cbp-session-start`.
+
 ### Step 1.6: Checkpoint Planning Gate
 
 Ownership passed (Step 1.5). Now gate on the checkpoint's planning + activation state — reusing the `plan` + `status` + task count loaded in Step 1.5 — so work never starts on a half-baked or un-activated checkpoint. Evaluate two rules in order (Rule A wins if both could match):
@@ -154,11 +187,11 @@ Wait for the user. Do not auto-trigger `/cbp-session-end` — session wrap-up is
 
 ### Step 4: Display and Auto-trigger
 
-Reached only when the Step 1.5 ownership gate allowed routing to continue and the Step 1.6 planning gate fell through (no hand-off). Show `rows[0].instructions` (so the user sees what is happening), then auto-trigger `rows[0].command` (its `/cbp-<name>` form).
+Reached only when the Step 1.5 ownership gate allowed routing to continue, the Step 1.55 stale-entity guard did not reject, and the Step 1.6 planning gate fell through (no hand-off). Show `rows[0].instructions` (so the user sees what is happening), then auto-trigger `rows[0].command` (its `/cbp-<name>` form).
 
 ## Integration
 
 - **Called by**: `/cbp-session-start`, `/cbp-task-complete`, `/cbp-checkpoint-complete`, manual, after `/clear`
 - **Resolves**: `npx codebyplan resolve-worktree --json` (worktree id + distress signal), `npx codebyplan whoami --json` (user id)
 - **Reads**: MCP `get_todos`, `get_current_task`, `get_rounds`, `get_checkpoints`, `get_tasks`, `get_worktrees`
-- **Triggers**: `rows[0].command` (auto, after the Step 1.5 ownership gate); Step 1.6 overrides to `/cbp-checkpoint-plan` (unplanned) or `/cbp-checkpoint-start` (planned-but-pending)
+- **Triggers**: `rows[0].command` (auto, after the Step 1.5 ownership gate and Step 1.55 stale-entity guard pass, and the Step 1.6 planning gate falls through); Step 1.55 overrides to STOP (stale completed/cancelled entity); Step 1.6 overrides to `/cbp-checkpoint-plan` (unplanned) or `/cbp-checkpoint-start` (planned-but-pending)

package/templates/skills/cbp-todo/qa-regression.md

@@ -12,8 +12,9 @@ Repo under test: `2ff6d405-39c5-47b8-a6d1-59f998ac0537`. Resolve a real `user_id
 
 ## Preconditions
 
-- `get_todos` is the only Step 1 read — confirm no `regenerate_todos_for_repo` call remains (`grep -n 'regenerate_todos_for_repo' SKILL.md` → no hits).
+- `get_todos` is the only Step 1 read — confirm no `get_next_action` / `regenerate_todos_for_repo` call remains (`grep -n 'get_next_action\|regenerate_todos_for_repo' SKILL.md` → no hits).
 - Step 0 uses `resolve-worktree --json` and `whoami --json`.
+- Step 1.55 (Stale-Entity Guard) must NOT call `get_next_action` or `regenerate_todos_for_repo` when rejecting a stale head — it reuses the checkpoint `status` + task statuses already loaded in Step 1.5 (the same grep above covers it).
 
 ## Scenario A — caller owns the work → auto-trigger
 
@@ -40,6 +41,12 @@ Repo under test: `2ff6d405-39c5-47b8-a6d1-59f998ac0537`. Resolve a real `user_id
 2. Step 3 fallback: `get_current_task({ repo_id, worktree_id })` / `get_checkpoints({ repo_id, worktree_id, status: 'active' })` surface a checkpoint whose `worktree_id` differs from the caller.
 3. **Expected**: the Step 1.5 ownership gate (applied to the fallback target) blocks the discovered work with the same "Work mismatch" message. NO auto-trigger. `regenerate_todos_for_repo` is never called.
 
+## Scenario D — stale queue head for a completed/cancelled entity → halt
+
+1. Caller owns the active checkpoint (Scenario A ownership holds), but the todo-worker queue is lagging — `health_check.todos_freshness_ok === false`. The `get_todos` head targets a checkpoint (or task) that has since been completed or cancelled.
+2. Step 1.5 loads the target checkpoint `status` + `get_tasks(checkpoint_id)` (already required for the ownership/planning gates — no extra reads).
+3. **Expected**: Step 1.55 rejects the auto-trigger — target checkpoint `status` is `completed`/`cancelled` (or every task is `completed`/`cancelled`) — surfaces the "Stale queue head" message naming the command + `CHK-NNN`[ `TASK-N`] + status, and STOPS. NO auto-trigger. NO `get_next_action` / `regenerate_todos_for_repo` call.
+
 ## Edge — both null
 
 Caller `WORKTREE_ID` empty AND target checkpoint `worktree_id` `null` → legitimate main-repo / unassigned work → auto-trigger allowed.