codebyplan 1.13.24 → 1.13.26

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

@@ -12,7 +12,7 @@ Activate the session, open a fresh session log, and surface the previous log's p
 
 ## Instructions
 
-Run Steps 0 through 5.8 silently (no intermediate output) — except Step 0 aborts the session on MCP failure, Step 1.4 may surface a one-line fast-forward note or warning, Step 1.5 may surface a one-line infra-drift nudge, Step 1.6 may run an install-and-halt path, Step 4.5 may auto-resume a handoff and exit session-start entirely (no Step 6 output), and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 1.5 → 1.6 → 3 → 4 → 4.5 → 5 → 5.7 → 5.8 → 6 → 7.) Produce ONE output block at Step 6, then auto-trigger or stop per Step 7.
+Run Steps 0 through 5.8 silently (no intermediate output) — except Step 0 aborts the session on MCP failure, Step 1.4 may surface a one-line fast-forward note or warning, Step 1.5 may surface a one-line infra-drift nudge, Step 1.6 may run an install-and-halt path, Step 1.7 may surface a one-line LSP binary nudge, Step 4.5 may auto-resume a handoff and exit session-start entirely (no Step 6 output), and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 1.5 → 1.6 → 1.7 → 3 → 4 → 4.5 → 5 → 5.7 → 5.8 → 6 → 7.) Produce ONE output block at Step 6, then auto-trigger or stop per Step 7.
 
 ### Step 0: MCP Health Gate
 
@@ -130,6 +130,16 @@ Parse `$VERSION_JSON` as JSON and branch on the result:
 
 **Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so `version-status` returns `guarded:false` there and this gate fires exactly as on a feat branch. That is deliberate — the update lands on whatever branch the worktree is currently resting on (the "update the branch they're on, except main/canonical" decision), not an accidental halt.
 
+### Step 1.7: LSP Binary Nudge
+
+Surface — never block — any language-server binaries still missing for this repo's tech stack. Runs after the freshness gate (Step 1.6) and before session activation (Step 3); may add one line per missing binary to the Step 6 output. Fully non-blocking — every failure path falls through with no output.
+
+```bash
+LSP_NUDGE=$(npx codebyplan lsp --check 2>/dev/null || true)
+```
+
+`codebyplan lsp --check` reads the committed `.codebyplan/lsp.json` (written by a prior project-scope `codebyplan claude install`/`update`), re-checks each LSP server binary on PATH, prunes any now-resolved `.codebyplan/todo/session-start/` nudge file, and prints ONE install-hint line per still-missing binary (e.g. `npm i -g typescript-language-server`). When `.codebyplan/lsp.json` is absent or every binary is already on PATH, it prints nothing. If `$LSP_NUDGE` is non-empty, hold each line for the Step 6 output prefixed with `LSP:`; otherwise skip silently.
+
 ### Step 3: Update Session State
 
 Use MCP `update_session_state` with action `activate`. This deactivates all other repos automatically.
@@ -224,6 +234,8 @@ Ownership: [total_count] active CHK(s), [owned_count] owned by this worktree
 [Owned: CHK-NNN (title), … — only when owned_count > 0]
 [Cross-worktree: CHK-ZZZ (name), … — only when total_count > owned_count]
 
+[LSP: <install hint> — one line per still-missing LSP binary held from Step 1.7, only when LSP_NUDGE is non-empty]
+
 [⚠ Worktree unregistered — run `npx codebyplan setup` to register — only when WORKTREE_ID is null and no resolver distress was already shown]
 ```
 
@@ -241,7 +253,7 @@ Three-branch gate using `owned_count` and `total_count` from Step 5.8:
 
 - **Triggered by**: user invocation, `/clear` recovery
 - **Resolves**: `npx codebyplan resolve-worktree --json` (worktree id + distress signal; non-tuple-miss distress is non-blocking at session-start)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check` (Step 0 hard gate), MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` (two calls: `{ repo_id, status: 'active' }` for the Step 5.8 ownership partition; `{ repo_id }` unfiltered for the Step 4.5 freshness probe, which may resolve a non-active checkpoint), MCP `get_tasks` / `get_rounds` for the Step 4.5 freshness probe; `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift); `npx codebyplan version-status` (Step 1.6 package-freshness gate). Reads at Step 3 and later (session-state, session logs, checkpoints, tasks/rounds) do NOT fire on a Step 0 MCP hard-fail or the Step 1.6 update-and-halt path
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check` (Step 0 hard gate), MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` (two calls: `{ repo_id, status: 'active' }` for the Step 5.8 ownership partition; `{ repo_id }` unfiltered for the Step 4.5 freshness probe, which may resolve a non-active checkpoint), MCP `get_tasks` / `get_rounds` for the Step 4.5 freshness probe; `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift); `npx codebyplan version-status` (Step 1.6 package-freshness gate); `npx codebyplan lsp --check` (Step 1.7 LSP binary nudge — reads `.codebyplan/lsp.json`, non-blocking). Reads at Step 3 and later (session-state, session logs, checkpoints, tasks/rounds) do NOT fire on a Step 0 MCP hard-fail or the Step 1.6 update-and-halt path
 - **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate) — both SKIPPED on a Step 0 MCP hard-fail and on the Step 1.6 update-and-halt path
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval at Step 5.7 or the Step 1.6 update path), `handoff.command` (on fresh handoff hit at Step 4.5), `/cbp-todo` (auto fall-through when owned_count >= 1 or total_count === 0; STOPS with no trigger when total_count >= 1 AND owned_count === 0; NOT triggered on a Step 0 hard-fail or the Step 1.6 update-and-halt path)

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

@@ -62,7 +62,7 @@ References:
 **Supabase — branching integration** (run AFTER Step 5 — Verify completes for the
 supabase surface; do NOT invoke during Steps 1–4): once Step 5 has finished and
 `shipment.surfaces.supabase` is persisted, run
-`jq '.shipment.surfaces.supabase.branching_configured // empty' .codebyplan.json`.
+`jq '.shipment.surfaces.supabase.branching_configured // empty' .codebyplan/shipment.json`.
 If empty, invoke `/cbp-supabase-setup` (GitHub integration, required-status-check,
 persistent branch). Delegate fully — do NOT duplicate steps inline. If already set,
 note as already-done in the Step 6 report.

package/templates/skills/cbp-ship-configure/reference/supabase.md

@@ -174,11 +174,11 @@ project_id = "xyzwabcd"   # 8-char ref from `supabase --experimental branches li
 ```
 
 Replace `development` and `xyzwabcd` with the actual integration branch name and project
-ref for this repo (confirmed in `.codebyplan.json` `branch_config.integration`).
+ref for this repo (confirmed in `.codebyplan/git.json` `branch_config.integration`).
 
 ### Idempotency marker
 
-Written to `.codebyplan.json` after setup completes:
+Written to `.codebyplan/shipment.json` after setup completes:
 
 ```json
 {

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.