codebyplan 1.11.2 → 1.12.0

package/package.json

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

package/templates/hooks/cbp-statusline.mjs

@@ -118,6 +118,7 @@ function main() {
     rate_limits: true,
     repo_pr: true,
     worktree: true,
+    infra_drift: true,
     no_color: false,
   };
   try {
@@ -136,6 +137,7 @@ function main() {
           "rate_limits",
           "repo_pr",
           "worktree",
+          "infra_drift",
         ]) {
           if (typeof parsed.lines[k] === "boolean") cfg[k] = parsed.lines[k];
         }
@@ -374,6 +376,48 @@ function main() {
     }
   }
 
+  // ============================================================
+  // LINE 7 — Infra drift (monorepo feat branches behind main)
+  // ============================================================
+  // Only the codebyplan monorepo (templates/ present) on a feat branch can carry
+  // stale .claude/ infra. No fetch — counts against the cached origin/main only.
+  if (shouldShow("INFRA_DRIFT", cfg.infra_drift)) {
+    if (
+      BRANCH.startsWith("feat/") &&
+      fs.existsSync(
+        path.join(root, "packages", "codebyplan-package", "templates")
+      )
+    ) {
+      let behind = 0;
+      try {
+        behind = parseInt(
+          execFileSync(
+            "git",
+            [
+              "-C",
+              root,
+              "rev-list",
+              "--count",
+              "HEAD..origin/main",
+              "--",
+              ".claude",
+              "packages/codebyplan-package/templates",
+            ],
+            { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+          ).trim(),
+          10
+        );
+      } catch {
+        behind = 0;
+      }
+      if (Number.isFinite(behind) && behind > 0) {
+        out.push(
+          `${C.YELLOW}⚠ infra ${behind} behind${C.RST} ${C.DIM}→ /cbp-refresh-infra${C.RST}`
+        );
+      }
+    }
+  }
+
   process.stdout.write(out.length ? out.join("\n") + "\n" : "");
 }
 

package/templates/hooks/cbp-statusline.py

@@ -80,7 +80,8 @@ def main():
     # ---- Config: line toggles + no_color -------------------------------------
     cfg = {
         "identity": True, "context": True, "cost": True,
-        "rate_limits": True, "repo_pr": True, "worktree": True, "no_color": False,
+        "rate_limits": True, "repo_pr": True, "worktree": True,
+        "infra_drift": True, "no_color": False,
     }
     try:
         with open(os.path.join(root, ".codebyplan", "statusline.json"), "r", encoding="utf-8") as fh:
@@ -90,7 +91,7 @@ def main():
                 cfg["no_color"] = parsed["no_color"]
             lines = parsed.get("lines")
             if isinstance(lines, dict):
-                for k in ["identity", "context", "cost", "rate_limits", "repo_pr", "worktree"]:
+                for k in ["identity", "context", "cost", "rate_limits", "repo_pr", "worktree", "infra_drift"]:
                     if isinstance(lines.get(k), bool):
                         cfg[k] = lines[k]
     except Exception:
@@ -321,6 +322,27 @@ def main():
             l6 += " %s%s%s" % (DIM, wt_path_disp, RST)
             out.append(l6)
 
+    # ===== LINE 7 — Infra drift (monorepo feat branches behind main) =====
+    # Only the codebyplan monorepo (templates/ present) on a feat branch can carry
+    # stale .claude/ infra. No fetch — counts against the cached origin/main only.
+    if should_show("INFRA_DRIFT", cfg["infra_drift"]):
+        if branch.startswith("feat/") and os.path.isdir(
+            os.path.join(root, "packages", "codebyplan-package", "templates")
+        ):
+            behind = 0
+            try:
+                res = subprocess.run(
+                    ["git", "-C", root, "rev-list", "--count", "HEAD..origin/main",
+                     "--", ".claude", "packages/codebyplan-package/templates"],
+                    stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+                )
+                if res.returncode == 0:
+                    behind = int(res.stdout.strip() or "0")
+            except Exception:
+                behind = 0
+            if behind > 0:
+                out.append("%s⚠ infra %d behind%s %s→ /cbp-refresh-infra%s" % (YELLOW, behind, RST, DIM, RST))
+
     sys.stdout.write(("\n".join(out) + "\n") if out else "")
 
 

package/templates/hooks/cbp-statusline.sh

@@ -15,7 +15,7 @@
 #
 # DISPLAY OPTIONS (team-shared, committed)
 #   .codebyplan/statusline.json -> { "lines": {identity,context,cost,rate_limits,
-#                                    repo_pr,worktree}, "no_color": bool }
+#                                    repo_pr,worktree,infra_drift}, "no_color": bool }
 #
 # ENV-VAR OVERRIDES (env > config > default)
 #   CBP_STATUSLINE_HIDE_IDENTITY=1     suppress line 1 (folder, branch, model, effort, …)
@@ -24,6 +24,7 @@
 #   CBP_STATUSLINE_HIDE_RATE_LIMITS=1  suppress line 4 (5h / 7d rate limits)
 #   CBP_STATUSLINE_HIDE_REPO_PR=1      suppress line 5 (repo host/owner/name, PR)
 #   CBP_STATUSLINE_HIDE_WORKTREE=1     suppress line 6 (worktree name/branch/path)
+#   CBP_STATUSLINE_HIDE_INFRA_DRIFT=1  suppress line 7 (.claude infra commits behind main)
 #   CBP_STATUSLINE_NO_COLOR=1          strip all ANSI colour codes (also honoured by $NO_COLOR)
 #
 # TEST SEAMS (no effect in normal use)
@@ -104,7 +105,7 @@ eval "$(echo "$INPUT" | jq -r '
 
 # ---- Config: line toggles + no_color from .codebyplan/statusline.json --------
 CFG_IDENTITY=true; CFG_CONTEXT=true; CFG_COST=true
-CFG_RATE_LIMITS=true; CFG_REPO_PR=true; CFG_WORKTREE=true; CFG_NO_COLOR=false
+CFG_RATE_LIMITS=true; CFG_REPO_PR=true; CFG_WORKTREE=true; CFG_INFRA_DRIFT=true; CFG_NO_COLOR=false
 CBP_CFG="$CBP_ROOT/.codebyplan/statusline.json"
 if [ -f "$CBP_CFG" ] && command -v jq >/dev/null 2>&1; then
   # Use `!= false` / `== true` (NOT jq `//`): the `//` operator treats an explicit
@@ -117,6 +118,7 @@ if [ -f "$CBP_CFG" ] && command -v jq >/dev/null 2>&1; then
     "CFG_RATE_LIMITS=\(.lines.rate_limits != false)",
     "CFG_REPO_PR=\(.lines.repo_pr != false)",
     "CFG_WORKTREE=\(.lines.worktree != false)",
+    "CFG_INFRA_DRIFT=\(.lines.infra_drift != false)",
     "CFG_NO_COLOR=\(.no_color == true)"
   ' "$CBP_CFG" 2>/dev/null)"
 fi
@@ -401,3 +403,21 @@ if should_show WORKTREE "$CFG_WORKTREE"; then
     printf "%b\n" "$L6"
   fi
 fi
+
+# ============================================================
+# LINE 7 — Infra drift (monorepo feat branches behind main)
+# ============================================================
+# Only the codebyplan monorepo (templates/ present) on a feat branch can carry
+# stale .claude/ infra. No fetch — counts against the cached origin/main only.
+if should_show INFRA_DRIFT "$CFG_INFRA_DRIFT"; then
+  case "$BRANCH" in
+    feat/*)
+      if [ -d "$CBP_ROOT/packages/codebyplan-package/templates" ]; then
+        BEHIND="$(git -C "$CBP_ROOT" rev-list --count HEAD..origin/main -- .claude packages/codebyplan-package/templates 2>/dev/null)"
+        if [ -n "$BEHIND" ] && [ "$BEHIND" -gt 0 ] 2>/dev/null; then
+          printf "%b\n" "${YELLOW}⚠ infra ${BEHIND} behind${RST} ${DIM}→ /cbp-refresh-infra${RST}"
+        fi
+      fi
+      ;;
+  esac
+fi

package/templates/rules/README.md

@@ -34,7 +34,14 @@ The `install`/`update`/`uninstall` flow handles these files identically to how i
 
 ## Current status
 
-Zero rules are shipped today. The wiring is in place so future PRs can land curated rules through the same install/update/uninstall flow as other templates.
+Four rules are shipped:
+
+| Rule file | Summary |
+|---|---|
+| `scope-vocabulary.md` | Canonical scope-marker enum (`org-shared` / `project-shared` / `repo-only:<name>`) enforced by three validators |
+| `context-file-loading.md` | Context-file load contract — who loads what, when, and how missing files are handled |
+| `todo-backend.md` | Todos queue contract, six DB-layer workflow invariants, and writer obligations for MCP mutators |
+| `supabase-branch-lifecycle.md` | Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle — lazy create on first DB change, delete wherever the git branch is removed |
 
 ## Contributing a rule
 

package/templates/rules/supabase-branch-lifecycle.md

@@ -0,0 +1,99 @@
+---
+scope: org-shared
+description: Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle
+paths:
+  - "supabase/migrations/**"
+  - ".codebyplan/shipment.json"
+  - ".codebyplan/git.json"
+  - ".claude/skills/cbp-supabase-migrate/**"
+  - ".claude/skills/cbp-supabase-branch-check/**"
+  - ".claude/skills/cbp-checkpoint-end/**"
+  - ".claude/skills/cbp-git-worktree-remove/**"
+  - ".claude/skills/cbp-ship-main/**"
+---
+
+# Supabase Branch Lifecycle
+
+When a checkpoint or standalone task does DB work on its own feat branch, that branch gets
+a Supabase preview branch whose lifecycle mirrors the git branch — created on first DB
+change, deleted when the git branch is removed.
+
+## Contract
+
+Each feat branch that touches the database owns exactly one Supabase preview branch, named
+identically to the git branch. The git branch is the source of truth; the Supabase branch
+follows it.
+
+## Create (lazy)
+
+The Supabase branch is created by `cbp-supabase-migrate` (Step 2.3) on the **first DB
+change** for the branch — never eagerly at git-branch creation time. Creation is guarded
+by the skill's db_paths detection so the step fires only when the invocation actually
+touches the database.
+
+The branch is named **verbatim** after the git branch, slashes included (e.g.
+`feat/CHK-144-supabase-branch-lifecycle`). This identical naming is the linchpin: the
+GitHub branching integration reconciles to the same branch on PR open rather than creating
+a duplicate.
+
+After creation, the branch name and resulting `project_ref` are recorded on the parent
+checkpoint or standalone task context (via `mcp__codebyplan__update_checkpoint` /
+`mcp__codebyplan__update_task`) and may also be noted in `.codebyplan/shipment.json` so
+cleanup skills can discover and remove it without querying the API.
+
+## Delete
+
+The Supabase branch is removed wherever the git branch is deleted:
+
+| Skill | Trigger |
+|---|---|
+| `cbp-checkpoint-end` | stale-branch cleanup + current feat-branch delete on ship |
+| `cbp-git-worktree-remove` | worktree teardown removes the coupled Supabase branch |
+| `cbp-ship-main` | `branch_deleted` event after PR merge |
+
+Deletion is **existence-checked and idempotent** — a not-found response is treated as
+success. This tolerates the GitHub integration auto-deleting the preview branch on PR
+close before the skill runs.
+
+These skills use `delete_branch` (MCP tool), never `merge_branch`. Production migrations
+reach main via the existing merge path (GitHub rebuild / `last_shipped_migration_version`);
+there is no separate Supabase branch merge step.
+
+## Exclusions
+
+This lifecycle applies **only to feat branches**. It MUST NOT fire for:
+
+- The main/production branch (`branch_config.production`, default `"main"`)
+- Any branch listed in `branch_config.protected[]`
+- A standalone task running directly on the production branch
+- The integration branch (`branch_config.integration`) when non-null — it gets a persistent branch via `cbp-supabase-setup`, not a lazy ephemeral one.
+
+`cbp-supabase-migrate` Step 2.3 Guard 1 enforces this by reading `.codebyplan/git.json`
+and skipping provisioning when the current branch matches `$PRODUCTION`, `$PROTECTED`, or
+a non-null `$INTEGRATION`.
+
+## Guards
+
+Skills that delete Supabase branches MUST:
+
+1. Verify the branch name matches the feat branch being removed (never delete by
+   `project_ref` alone).
+2. Never delete the parent/production project (`rrvtrumtkhrsbhcyrwvf`) itself.
+3. Never delete a persistent/long-lived branch that does not correspond to the git branch
+   being torn down.
+
+## PR Gate (retained)
+
+`cbp-supabase-branch-check` runs as a required PR gate, independent of the create/delete
+coupling. By-name resolution works whether the branch was created by `cbp-supabase-migrate`
+or auto-created by the GitHub integration — both paths use the same branch name.
+
+## Skill Map
+
+| Role | Skill |
+|---|---|
+| Create (lazy) | `cbp-supabase-migrate` (Step 2.3) |
+| Delete | `cbp-checkpoint-end`, `cbp-git-worktree-remove`, `cbp-ship-main` |
+| PR gate | `cbp-supabase-branch-check` |
+
+Each skill in the Skill Map above carries an inline back-reference to this rule at its create or teardown step.

package/templates/settings.project.base.json

@@ -39,8 +39,7 @@
       "Bash(git push --force:*)",
       "Bash(git push -f:*)",
       "Bash(git checkout -- :*)",
-      "Bash(git add .:*)",
-      "Bash(git add -A:*)",
+      "Bash(git add:*)",
       "Bash(rm -rf:*)",
       "Bash(pnpm add:*)",
       "Bash(pnpm install:*)",

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

@@ -47,8 +47,7 @@ These values are part of the CBP baseline and should not be weakened:
       "Bash(git push --force:*)",
       "Bash(git push -f:*)",
       "Bash(git checkout -- :*)",
-      "Bash(git add .:*)",
-      "Bash(git add -A:*)",
+      "Bash(git add:*)",
       "Bash(rm -rf:*)",
       "Bash(pnpm add:*)",
       "Bash(pnpm install:*)",

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

@@ -95,6 +95,8 @@ git push -u origin "feat/CHK-{NNN}-{slug}"
 
 Slug: lowercase, dash-joined, punctuation dropped, ≤40 chars. Persist the branch via MCP `update_checkpoint(checkpoint_id, branch_name: "feat/CHK-{NNN}-{slug}")`. (The dedicated `/cbp-git-branch-feat-create` skill is the canonical config-driven helper if you prefer to delegate.)
 
+**Note — Supabase preview branch**: no Supabase branch is created here. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on this feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
+
 ### Step 10: Show Result + Auto-Trigger Plan
 
 ```

package/templates/skills/cbp-checkpoint-end/SKILL.md

@@ -141,13 +141,25 @@ C) Keep all
 
 Only delete with explicit user confirmation. Delete both local and remote:
 ```bash
-git branch -d "$BRANCH" 2>/dev/null
-git push origin --delete "$BRANCH"
+git branch -d "$BRANCH" && git push origin --delete "$BRANCH"
 ```
 
+Only after both the local and remote git delete above succeed, run a conditional Supabase preview-branch teardown for that branch name (do not suppress the delete output — a failed local delete must stay visible):
+
+> Lifecycle contract: see [[supabase-branch-lifecycle]].
+
+- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Scan the returned list for an entry whose `name` exactly equals `$BRANCH`.
+- If found: call `mcp__supabase__delete_branch` with its `branch_id`. Record the branch name in `SUPABASE_BRANCHES_DELETED[]`.
+- If not found: no-op silently — the GitHub integration may have already removed it on PR close; not-found is success, NOT an error.
+- If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$BRANCH` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
+- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+
+Accumulate all Supabase branch names removed across the loop in `SUPABASE_BRANCHES_DELETED`.
+
 ### Step 9: Current Feat Branch Cleanup
 
-Present comprehensive summary first (Step 10), then ask about current feat branch via AskUserQuestion:
+Before asking about the current feat branch, present a partial summary of what has shipped so far — runtime surfaces (from `/cbp-ship` Step 7), stale branches cleaned (Step 8), and the `SUPABASE_BRANCHES_DELETED` accumulated so far — then ask about the current feat branch via AskUserQuestion (the complete shipment record is finalised in Step 10):
 
 ```
 The current feat branch [BRANCH] has been fully merged.
@@ -166,6 +178,14 @@ git branch -d "$FEAT_BRANCH"
 git push origin --delete "$FEAT_BRANCH"
 ```
 
+After the feat branch git delete, run the same conditional Supabase teardown for `$FEAT_BRANCH`:
+
+- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Scan for an entry whose `name` exactly equals `$FEAT_BRANCH`.
+- If found: call `mcp__supabase__delete_branch` with its `branch_id`. Add `$FEAT_BRANCH` to `SUPABASE_BRANCHES_DELETED[]`.
+- If not found: no-op silently — idempotent, not-found is success.
+- If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$FEAT_BRANCH` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
+
 ### Step 10: Save Shipment Results and Summary
 
 Update checkpoint context via MCP `update_checkpoint`. The `shipment` block contains both branch promotion AND runtime surface results (from `/cbp-ship` Step 7):
@@ -177,8 +197,9 @@ context.shipment: {
   feat_to_base: { pr_url, merged: true/false },
   surfaces: [...],          // populated by /cbp-ship — per-surface deploy results
   skipped: [...],           // populated by /cbp-ship — surfaces explicitly skipped
-  stale_branches_cleaned: [list of deleted branches],
-  feat_branch_deleted: true/false
+  stale_branches_cleaned: [list of deleted git branches],
+  feat_branch_deleted: true/false,
+  supabase_branches_deleted: [list of Supabase preview branch names removed in Steps 8–9]
 }
 ```
 
@@ -198,6 +219,7 @@ Present summary:
 ### Branch Operations
 - Stale branches deleted: [N] ([list])
 - Feat branch: [deleted/kept]
+- Supabase preview branches deleted: [N] ([list from supabase_branches_deleted], or "none")
 
 ### Before/After Branch State
 - Before: [list of feat/* branches]

package/templates/skills/cbp-git-worktree-remove/SKILL.md

@@ -116,7 +116,12 @@ Only use `--force` if the user confirms.
 
 ### Step 9: Delete Branch (if requested)
 
-**Protected branch check:** If `$BRANCH_NAME` is `main`, `development`, or `preview` — refuse deletion and stop.
+**Protected branch check:** Read the protected set from `.codebyplan/git.json`:
+```bash
+PRODUCTION=$(jq -r '.branch_config.production // "main"' .codebyplan/git.json)
+PROTECTED=$(jq -r '.branch_config.protected[]? // empty' .codebyplan/git.json)
+```
+If `$BRANCH_NAME` equals `$PRODUCTION` or appears in `$PROTECTED` — refuse deletion and stop.
 
 **Checkpoint verification:** Before deleting a feat branch, verify that the associated checkpoint has completed via `/cbp-checkpoint-end`. If the checkpoint is still active, warn the user that unshipped work may be lost.
 
@@ -126,6 +131,17 @@ git branch -d "$BRANCH_NAME" && git push origin --delete "$BRANCH_NAME"
 
 Use `-d` (not `-D`) to prevent deleting unmerged work. If it fails because the branch is not fully merged, inform the user and ask if they want to force delete with `-D`.
 
+After the git branch delete succeeds, run a conditional Supabase preview-branch teardown for `$BRANCH_NAME`:
+
+> Lifecycle contract: see [[supabase-branch-lifecycle]].
+
+- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Scan the returned list for an entry whose `name` exactly equals `$BRANCH_NAME`.
+- If found: call `mcp__supabase__delete_branch` with its `branch_id`. Report "Supabase preview branch deleted: `$BRANCH_NAME`".
+- If not found: no-op silently — the GitHub integration may have already removed it on PR close; not-found is success, NOT an error.
+- If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$BRANCH_NAME` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
+- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+
 ### Step 10: Show Result
 
 ```

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 1.4 may surface a one-line fast-forward note or warning, and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 2 → 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 1.4 may surface a one-line fast-forward note or warning, Step 1.5 may surface a one-line infra-drift nudge, and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 1.5 → 2 → 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 Check
 
@@ -77,6 +77,31 @@ CURRENT="$(git rev-parse --abbrev-ref HEAD)"
 
 Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
 
+### Step 1.5: Infra Drift Check
+
+Surface — never block — when this worktree's CBP tooling has fallen behind. Runs after Step 1.4 and may add one line to the Step 6 output. Two mutually-exclusive concepts, keyed on repo type (`$PRODUCTION` is the branch resolved in Step 1.4):
+
+- **Monorepo (concept A)** — both `packages/codebyplan-package/templates/` and `scripts/infra-drift.mjs` exist. Step 1.4 skips the fetch on a feat branch, so refresh `origin/$PRODUCTION` best-effort first, then run the reporter:
+
+  ```bash
+  git fetch origin "$PRODUCTION" 2>/dev/null || true
+  node scripts/infra-drift.mjs 2>/dev/null || true
+  ```
+
+  The script self-guards (feat branch + behind > 0) and emits at most one `⚠ .claude/ infra is N behind — run /cbp-refresh-infra` line. Hold any output for Step 6.
+
+- **Consumer (concept B)** — no `templates/`, but an install manifest exists (`.claude/.cbp.manifest.json`, falling back to `.cbp-claude.manifest.json` then `.codebyplan-claude.manifest.json`). Compare its `version` to the latest published `codebyplan`, offline-safe:
+
+  ```bash
+  LATEST="$(npm view codebyplan version 2>/dev/null)"
+  ```
+
+  When `$LATEST` is non-empty and newer than the manifest `version`, hold one line for Step 6: `⚠ codebyplan {installed} → {LATEST} — run npx codebyplan@latest claude update`. Any failure (offline, npm absent) → silent.
+
+- **Neither** → skip silently.
+
+Concept B never fires in the monorepo — the `templates/` guard routes the source repo to concept A only (its manifest `version` is intentionally stale). Fully non-blocking; every failure path falls through with no output.
+
 ### Step 2: Check Dev Server
 
 **Skip if `server_type` is `"none"`.**
@@ -198,7 +223,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`, 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
+- **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`, 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) or the install manifest + `npm view codebyplan version` (Step 1.5 consumer drift)
 - **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate)
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval), `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)

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

@@ -52,6 +52,19 @@ 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.
 
+If `branch_deleted === true`, run a conditional Supabase preview-branch teardown for the feat branch that was just merged:
+
+> Lifecycle contract: see [[supabase-branch-lifecycle]].
+
+- Read `FEAT_BRANCH` from the `feat_branch` field in the Step 3 JSON output — NOT from `git branch --show-current`. By the time Step 4 runs, `codebyplan ship` has already checked out the base branch (unless `--keep-feat` was passed), so the live branch is the base, not the feat branch.
+- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Scan the returned list for an entry whose `name` exactly equals `$FEAT_BRANCH`.
+- If found: call `mcp__supabase__delete_branch` with its `branch_id`. Report the Supabase delete outcome alongside `pr_url` / `merge_commit` / `branch_deleted`.
+- If not found: no-op silently — the GitHub integration may have already removed the preview branch on PR close; not-found is success, NOT an error.
+- If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$FEAT_BRANCH` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
+- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+- This coordinates safely with `/cbp-checkpoint-end` — the existence-checked delete makes any second attempt a harmless no-op.
+
 ## Key Rules
 
 - **Read branch names from config** — never hardcode "main"

package/templates/skills/cbp-supabase-branch-check/SKILL.md

@@ -62,10 +62,10 @@ Infer `TARGET` when absent:
 
 ## Step 1 — Read DB Paths Config
 
-Read `.codebyplan.json` to obtain the configured DB path globs:
+Read `.codebyplan/shipment.json` to obtain the configured DB path globs:
 
 ```bash
-DB_PATHS=$(jq -r '.shipment.surfaces.supabase.db_paths[]? // empty' .codebyplan.json 2>/dev/null)
+DB_PATHS=$(jq -r '.shipment.surfaces.supabase.db_paths[]? // empty' .codebyplan/shipment.json 2>/dev/null)
 ```
 
 If `DB_PATHS` is empty, fall back to defaults:
@@ -80,11 +80,11 @@ Store each pattern as a separate entry for matching in Step 2.
 
 ## Step 2 — Detect DB-Path Changes
 
-Resolve the BASE branch from `TARGET`. Read `.codebyplan.json`:
+Resolve the BASE branch from `TARGET`. Read `.codebyplan/git.json`:
 
 ```bash
-INTEGRATION=$(jq -r '.branch_config.integration // "development"' .codebyplan.json)
-PRODUCTION=$(jq -r '.branch_config.production // "main"' .codebyplan.json)
+INTEGRATION=$(jq -r '.branch_config.integration // "development"' .codebyplan/git.json)
+PRODUCTION=$(jq -r '.branch_config.production // "main"' .codebyplan/git.json)
 ```
 
 Set `BASE`:
@@ -156,6 +156,13 @@ Store as `PROJECT_REF`.
 
 ## Step 4 — Handle Missing project_ref
 
+> **Note — Hybrid branch creation**: The preview branch may pre-exist as a CBP-created
+> branch (named identically to the git branch, provisioned lazily by `cbp-supabase-migrate`
+> on first DB change) rather than being auto-created by the GitHub integration on PR open.
+> The by-name resolution in Step 3 works identically for both creation paths because both
+> name the branch verbatim after the git branch. See [[supabase-branch-lifecycle]] for the
+> full lifecycle contract.
+
 If `PROJECT_REF` is empty after Step 3:
 
 - `MODE=pre_pr_create`: