codebyplan 1.13.38 → 1.13.39

package/templates/skills/cbp-map-architecture/SKILL.md

@@ -0,0 +1,170 @@
+---
+scope: org-shared
+name: cbp-map-architecture
+description: Orchestrate architecture map generation for one or all modules. Spawns the cbp-map-architecture agent per module, writes per-module .md files to .claude/architecture/, regenerates INDEX.md and graph.md, and stamps each module via the CLI. Idempotent — safe to re-run.
+argument-hint: '[--module <path>] [--deep <path,...>]'
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
+---
+
+# Map Architecture
+
+Generate or refresh the `.claude/architecture/` map for one or all repository modules.
+Idempotent — re-running regenerates stale or missing maps without touching fresh ones.
+
+Distinct from `/cbp-refresh-arch-map` (TASK-3: drift-scoped refresh that only re-runs
+modules whose stamped SHA has since changed). This skill maps **all** target modules
+unconditionally, or a specific subset when `--module` is given.
+
+## Arguments
+
+`$ARGUMENTS` accepts:
+
+| Flag | Description |
+|------|-------------|
+| `--module <path>` | Map a single module (e.g. `apps/web`). Omit to map all discovered modules. |
+| `--deep <path,...>` | Comma-separated list of modules to map at `deep` depth. All others default to `skeleton`. |
+
+## Instructions
+
+### Step A: Discover target modules
+
+1. Run `codebyplan arch-map status` (Bash) to enumerate all discovered modules and their
+   current map presence + freshness. Capture the output.
+2. If `--module <path>` was given, restrict the target list to that one module.
+3. Parse `--deep <path,...>` into a set of paths that should be mapped at `deep` depth.
+   All other targets default to `skeleton`.
+
+Output:
+```yaml
+targets:
+  - path: string      # module path relative to repo root
+    depth: skeleton|deep
+    has_map: boolean  # from arch-map status output
+```
+
+### Step B: Spawn the cbp-map-architecture agent per module
+
+For each module in `targets[]`:
+
+1. Derive the map-file slug from the module path:
+   - Replace `/` with `-`
+   - Normalize a leading `.` to `dot-` (e.g. `.github` → `dot-github.md`)
+   - Example: `apps/web` → `apps-web.md`
+
+2. Spawn the `cbp-map-architecture` agent (via Task tool) with input:
+   ```yaml
+   module_path: <path>
+   depth: skeleton|deep
+   ```
+
+3. Receive the agent's returned map content (a full `.claude/architecture/<slug>.md`
+   text block, starting with `---` YAML frontmatter).
+
+4. Write the content to `.claude/architecture/<slug>.md` using the Write tool.
+   Create the `.claude/architecture/` directory if it does not yet exist.
+
+Modules may be spawned concurrently (parallel Task calls) when there are multiple targets
+with no inter-module dependency. The agent is read-only and safe to parallelize.
+
+### Step C: Regenerate INDEX.md and graph.md
+
+After all per-module map files are written:
+
+**INDEX.md** — regenerate `.claude/architecture/INDEX.md` from scratch:
+
+1. Read all `.claude/architecture/*.md` files (excluding INDEX.md and graph.md).
+2. For each file, parse the YAML frontmatter fields: `module`, `depth`,
+   `generated_from_sha`, `generated_at`.
+3. Derive the short SHA: first 8 chars of `generated_from_sha`, or `unset` if null.
+4. Derive the date: `YYYY-MM-DD` portion of `generated_at`, or `unset` if null.
+5. Write INDEX.md following the canonical format from `context/architecture/arch-map-spec.md`:
+
+```markdown
+# Architecture Map Index
+
+Grep-friendly registry of per-module architecture maps. Layout convention in `context/architecture/arch-map-spec.md`.
+
+| Module | Depth | SHA | Generated | Map File |
+|--------|-------|-----|-----------|----------|
+| <module> | <depth> | <sha_short> | <date> | <map_file> |
+```
+
+**graph.md** — regenerate `.claude/architecture/graph.md` from scratch:
+
+1. For each map file, read the `## 4. Dependencies (In / Out)` section.
+2. Extract "Consumes" entries — each named module becomes an edge: `<module> -> <dependency>`.
+3. Collect all edges into a Set keyed on the exact `"<from> -> <to>"` string, then write each unique edge once. graph.md lists each directed edge exactly once — duplicate declarations across multiple maps are deduplicated at write time.
+4. Write graph.md following the canonical format from `context/architecture/arch-map-spec.md`:
+
+```markdown
+# Architecture Dependency Graph
+
+Adjacency list of cross-module edges. Each entry: `<from> -> <to>`.
+Generated from the `Dependencies (In / Out)` sections of individual map files
+(first-party `@codebyplan/*` workspace imports, verified against each module's `package.json`).
+
+Scope: edges are TypeScript workspace package imports only. Runtime/service dependencies
+(shared schema directories, HTTP calls between apps) are documented per-map in
+`## 4. Dependencies (In / Out)` and are intentionally NOT graphed here — a module with
+no edge is not necessarily isolated; consult its map file for runtime coupling.
+
+## Edges
+
+<module-A> -> <module-B>
+<module-A> -> <module-C>
+<module-B> -> <module-D>
+```
+
+If no dependency edges are found, write the header only (empty Edges section is valid).
+
+### Step D: Stamp each freshly written module
+
+For each module written in Step B, run:
+
+```bash
+codebyplan arch-map stamp <module-path>
+```
+
+This updates `.codebyplan/architecture.json` with the current git SHA and timestamp,
+and mirrors those values into the map file's YAML frontmatter.
+
+If `--depth` should be recorded explicitly (e.g. `deep`), pass `--depth <deep|skeleton>`:
+
+```bash
+codebyplan arch-map stamp <module-path> --depth <depth>
+```
+
+### Step E: Report
+
+Print a summary:
+- Modules mapped (count + list)
+- INDEX.md row count
+- graph.md edge count
+- Any modules that were skipped or blocked (with reason)
+
+## Idempotency Notes
+
+- Re-running this skill over an already-mapped module regenerates the map from scratch.
+  There is no "skip if fresh" logic here — use `/cbp-refresh-arch-map` (TASK-3) when
+  you want drift-scoped re-runs that skip fresh modules.
+- `codebyplan arch-map stamp` is idempotent — stamping the same SHA twice is a no-op in
+  practice (the values overwrite with the same content).
+
+## Failure Modes
+
+| Condition | Action |
+|-----------|--------|
+| `cbp-map-architecture` agent returns `blocked` for a module | Write a warning to INDEX.md row; continue with remaining modules |
+| `.claude/architecture/` directory creation fails | Surface as blocked — check file-system permissions |
+| `codebyplan arch-map status` not available | Surface as blocked — run `npx codebyplan arch-map status` to verify CLI is installed |
+
+## Integration
+
+- **Triggered by**: user invocation (`/cbp-map-architecture [args]`)
+- **Spawns**: `cbp-map-architecture` agent (one per module)
+- **Calls**: `codebyplan arch-map status`, `codebyplan arch-map stamp`
+- **Writes**: `.claude/architecture/<slug>.md`, `.claude/architecture/INDEX.md`, `.claude/architecture/graph.md`
+- **Updates**: `.codebyplan/architecture.json` (via stamp CLI)
+- **Consultation contract**: `.claude/context/architecture-map.md`
+- **Artifact spec**: `.claude/context/architecture/arch-map-spec.md`
+- **Related skill**: `/cbp-refresh-arch-map` — drift-scoped refresh (TASK-3)

package/templates/skills/cbp-refresh-arch-map/SKILL.md

@@ -0,0 +1,191 @@
+---
+scope: org-shared
+name: cbp-refresh-arch-map
+description: Drift-scoped refresh of the .claude/architecture/ map — re-runs the cbp-map-architecture agent for ONLY the modules whose stamped git SHA has changed, regenerates INDEX.md + graph.md, and re-stamps. Idempotent; no-op when no module has drifted.
+argument-hint: '[--module <path>]'
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
+---
+
+# Refresh Architecture Map (drift-scoped)
+
+Re-generate ONLY the architecture maps that have gone stale. A module is **stale**
+when its source has been committed past the git SHA recorded in
+`.codebyplan/architecture.json` — exactly what `codebyplan arch-map drift` reports.
+
+Distinct from `/cbp-map-architecture` (which maps **all** target modules
+unconditionally, or a named subset). This skill is the cheap incremental path: it
+touches nothing that is already fresh, preserving each stale module's existing
+depth (`skeleton` / `deep`) from the manifest.
+
+This is the freshness loop the session-start drift nudge points at — when a session
+starts and N modules are stale, you run this to bring the maps current in one pass.
+
+## Arguments
+
+`$ARGUMENTS` accepts:
+
+| Flag | Description |
+|------|-------------|
+| `--module <path>` | Refresh a single module even if drift does not flag it (force re-run). When omitted, the drifted set from `codebyplan arch-map drift` is the target list. |
+
+## Instructions
+
+### Step A: Compute the stale set
+
+1. Run `codebyplan arch-map drift` (Bash) and capture the output. Each drifted module
+   is printed on a `DRIFTED  <path>` line (the CLI is hook-safe — it exits 0 and prints
+   `All stamped modules are fresh.` when nothing has drifted).
+2. Read `.codebyplan/architecture.json` (Read) to recover each module's stored `depth`
+   and `map_file`. The manifest is the source of truth for depth — a drift refresh MUST
+   preserve the depth the module was originally mapped at, never silently downgrade a
+   `deep` map to `skeleton`.
+3. Build the target list:
+   - Default: every `DRIFTED  <path>` module from Step A.1.
+   - `--module <path>` given: just that one module (look up its depth in the manifest;
+     default `skeleton` if it has no manifest entry yet).
+
+```yaml
+targets:
+  - path: string            # module path relative to repo root
+    depth: skeleton|deep    # preserved from architecture.json
+    map_file: string        # .claude/architecture/<slug>.md from the manifest
+```
+
+### Step B: No-op short-circuit
+
+If the target list is empty (drift reported `All stamped modules are fresh.` and no
+`--module` override was given), print and STOP:
+
+```
+✓ All architecture maps are fresh — nothing to refresh.
+```
+
+Do NOT spawn agents, regenerate INDEX/graph, or re-stamp. An empty drift set is a
+legitimate success state, not an error.
+
+### Step C: Re-run the agent for each stale module
+
+For each module in `targets[]`:
+
+1. Spawn the `cbp-map-architecture` agent (via Task tool) with input:
+   ```yaml
+   module_path: <path>
+   depth: <preserved depth from the manifest>
+   ```
+2. Receive the agent's returned map content (a full `.claude/architecture/<slug>.md`
+   text block, opening with `---` YAML frontmatter).
+3. Write the content to the module's `map_file` path using the Write tool (overwrites
+   the stale map). The agent returns `generated_from_sha: null` / `generated_at: null`
+   in the frontmatter — Step E's `stamp` fills those in.
+
+Stale modules are independent and read-only to analyze, so spawn them concurrently
+(parallel Task calls) when there is more than one.
+
+If the agent returns `blocked` for a module (e.g. the module path no longer exists),
+skip it, record the reason for Step F, and continue with the rest.
+
+### Step D: Regenerate INDEX.md and graph.md (wholesale)
+
+INDEX.md and graph.md are derived from the FULL set of map files, so regenerate both
+from scratch after the stale maps are rewritten — unaffected rows/edges are reproduced
+unchanged because their source map files did not move.
+
+**INDEX.md** — rebuild `.claude/architecture/INDEX.md`:
+
+1. Read all `.claude/architecture/*.md` files (excluding INDEX.md and graph.md).
+2. Parse each file's frontmatter: `module`, `depth`, `generated_from_sha`, `generated_at`.
+   Note: freshly-rewritten maps still carry `null` SHA/date here — that is corrected by
+   Step E (stamp), so regenerate INDEX.md AFTER stamping, or re-read post-stamp.
+3. Short SHA = first 8 chars of `generated_from_sha`, or `unset` if null. Date =
+   `YYYY-MM-DD` of `generated_at`, or `unset` if null.
+4. Write the canonical header + one row per module (format in
+   `context/architecture/arch-map-spec.md`):
+
+```markdown
+# Architecture Map Index
+
+Grep-friendly registry of per-module architecture maps. Layout convention in `context/architecture/arch-map-spec.md`.
+
+| Module | Depth | SHA | Generated | Map File |
+|--------|-------|-----|-----------|----------|
+| <module> | <depth> | <sha_short> | <date> | <map_file> |
+```
+
+**graph.md** — rebuild `.claude/architecture/graph.md`:
+
+1. For each map file, read its `## 4. Dependencies (In / Out)` section.
+2. Each "Consumes" entry becomes a directed edge `<from> -> <to>`.
+3. Deduplicate edges by the exact `"<from> -> <to>"` string — each unique edge once.
+4. Write the canonical format (header only is valid when there are no edges):
+
+```markdown
+# Architecture Dependency Graph
+
+Adjacency list of cross-module edges. Each entry: `<from> -> <to>`.
+Generated from the `Dependencies (In / Out)` sections of individual map files
+(first-party `@codebyplan/*` workspace imports, verified against each module's `package.json`).
+
+Scope: edges are TypeScript workspace package imports only. Runtime/service dependencies
+(shared schema directories, HTTP calls between apps) are documented per-map in
+`## 4. Dependencies (In / Out)` and are intentionally NOT graphed here — a module with
+no edge is not necessarily isolated; consult its map file for runtime coupling.
+
+## Edges
+
+<module-A> -> <module-B>
+<module-A> -> <module-C>
+<module-B> -> <module-D>
+```
+
+### Step E: Re-stamp each refreshed module
+
+For each successfully rewritten module, run:
+
+```bash
+codebyplan arch-map stamp <module-path> --depth <preserved-depth>
+```
+
+This records the current git SHA + timestamp in `.codebyplan/architecture.json` and
+mirrors them into the map file's frontmatter, clearing the drift. Pass `--depth` so a
+`deep` map is never re-recorded as `skeleton`.
+
+After stamping, regenerate INDEX.md once more (or re-read the now-stamped frontmatter)
+so its SHA/date columns reflect the fresh stamps rather than the transient `null` state.
+
+### Step F: Report
+
+Print a summary:
+- Modules refreshed (count + list, with depth)
+- Modules skipped/blocked (with reason), if any
+- INDEX.md row count, graph.md edge count
+- A final `codebyplan arch-map drift` run confirming zero remaining drift
+
+## Idempotency Notes
+
+- Running this skill twice in a row is safe: the second run finds zero drift and
+  short-circuits at Step B.
+- `codebyplan arch-map stamp` is idempotent — re-stamping the same SHA overwrites with
+  identical values.
+- This skill never touches fresh modules — that is the entire point of the drift gate.
+  Use `/cbp-map-architecture` when you want to regenerate everything regardless of drift.
+
+## Failure Modes
+
+| Condition | Action |
+|-----------|--------|
+| `codebyplan arch-map drift` reports `No stamped modules found` | No maps exist yet — direct the user to `/cbp-map-architecture` to generate the initial maps, then STOP |
+| `cbp-map-architecture` agent returns `blocked` for a module | Skip it, record the reason in the Step F report, continue with the rest |
+| `.codebyplan/architecture.json` missing or unparseable | Surface as blocked — the manifest is required to recover per-module depth; run `/cbp-map-architecture` first |
+| `codebyplan arch-map` CLI not available | Surface as blocked — run `npx codebyplan arch-map status` to verify the CLI is installed |
+
+## Integration
+
+- **Triggered by**: user invocation (`/cbp-refresh-arch-map [--module <path>]`); nudged by the `/cbp-session-start` Step 1.55 architecture-map drift line
+- **Spawns**: `cbp-map-architecture` agent (one per stale module)
+- **Calls**: `codebyplan arch-map drift`, `codebyplan arch-map stamp`
+- **Reads**: `.codebyplan/architecture.json` (per-module depth + map_file)
+- **Writes**: `.claude/architecture/<slug>.md` (stale modules only), `.claude/architecture/INDEX.md`, `.claude/architecture/graph.md`
+- **Updates**: `.codebyplan/architecture.json` (via stamp CLI)
+- **Consultation contract**: `.claude/context/architecture-map.md`
+- **Artifact spec**: `.claude/context/architecture/arch-map-spec.md`
+- **Related skill**: `/cbp-map-architecture` — full (non-drift) generation

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 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.
+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.55 may surface a one-line architecture-map 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.55 → 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
 
@@ -91,6 +91,34 @@ Surface — never block — when this worktree's source-monorepo `.claude/` infr
 
 Fully non-blocking; every failure path falls through with no output.
 
+### Step 1.55: Architecture-Map Drift Check
+
+Surface — never block — when this repo's generated `.claude/architecture/` maps have
+gone stale (a mapped module's source was committed past the SHA stamped in
+`.codebyplan/architecture.json`). Runs after the infra-drift check (Step 1.5) and may add
+one line to the Step 6 output. This is the freshness nudge for the architecture-map
+pipeline (mirrors the infra-drift pattern; the analog for first-party code maps):
+
+- **No manifest** — `.codebyplan/architecture.json` absent → skip silently (the repo has
+  no maps yet; nothing to drift-check).
+- **Manifest present** — run the drift probe best-effort and count drifted modules:
+
+  ```bash
+  npx codebyplan arch-map drift 2>/dev/null | grep -c '^[[:space:]]*DRIFTED' || true
+  ```
+
+  If the count is `> 0`, hold this single line for Step 6:
+
+  ```
+  ⚠ .claude/architecture is N module(s) stale — run /cbp-refresh-arch-map
+  ```
+
+  A count of `0` (all maps fresh, no stamped modules, or any probe failure) emits nothing.
+
+Fully non-blocking; every failure path falls through with no output. The `arch-map` CLI is
+itself hook-safe (exits 0 on any internal error), so a missing or too-old `codebyplan`
+binary simply yields a zero count and no line.
+
 ### Step 1.6: Package Freshness Gate
 
 Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch. Runs AFTER the infra-drift check (Step 1.5) and BEFORE session activation (Step 3).
@@ -227,6 +255,9 @@ Session active | Worktree: [worktree_id or "unregistered"]
 
 [⚠ resolve-worktree: <error_kind> — local state is broken; routing may be unreliable. Run `npx codebyplan setup` to repair. — only when error_kind is non-null and not tuple_miss]
 
+[⚠ .claude/ infra is N behind — run /cbp-refresh-infra — only when Step 1.5 found drift]
+[⚠ .claude/architecture is N module(s) stale — run /cbp-refresh-arch-map — only when Step 1.55 found drift]
+
 Previous session: [title or "none"]
   Pending: [pending items from previous log, or "—"]
 
@@ -253,7 +284,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); `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
+- **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 arch-map drift` + `.codebyplan/architecture.json` presence (Step 1.55 architecture-map drift nudge, non-blocking); `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/reference/surface-supabase.md

@@ -35,8 +35,8 @@ This is **always interactive**. The orchestrator does NOT silently apply migrati
 
 1. **List pending migrations**:
    ```bash
-   PROJECT_REF=$(jq -r '.surfaces.supabase.project_ref' .codebyplan/shipment.json)
-   LAST_VERSION=$(jq -r '.surfaces.supabase.last_shipped_migration_version // ""' .codebyplan/shipment.json)
+   PROJECT_REF=$(jq -r '.shipment.surfaces.supabase.project_ref' .codebyplan/shipment.json)
+   LAST_VERSION=$(jq -r '.shipment.surfaces.supabase.last_shipped_migration_version // ""' .codebyplan/shipment.json)
 
    PENDING=$(ls supabase/migrations/*.sql | sort)
    if [ -n "$LAST_VERSION" ]; then
@@ -116,7 +116,7 @@ This is **always interactive**. The orchestrator does NOT silently apply migrati
 7. **Update the last-shipped marker**:
    ```bash
    LAST_APPLIED=$(echo "$PENDING" | tail -1 | xargs basename)
-   jq --arg v "$LAST_APPLIED" '.surfaces.supabase.last_shipped_migration_version = $v' .codebyplan/shipment.json > .codebyplan/shipment.json.tmp
+   jq --arg v "$LAST_APPLIED" '.shipment.surfaces.supabase.last_shipped_migration_version = $v' .codebyplan/shipment.json > .codebyplan/shipment.json.tmp
    mv .codebyplan/shipment.json.tmp .codebyplan/shipment.json
    ```
 

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

@@ -126,7 +126,7 @@ The skill's job is to verify these credentials EXIST and are valid; never to sto
 Run the verification step from the surface reference. For Vercel, this is:
 
 ```bash
-vercel inspect "$(jq -r '.surfaces."vercel-web".project_id' .codebyplan/shipment.json)" 2>&1 | head -20
+vercel inspect "$(jq -r '.shipment.surfaces."vercel-web".project_id' .codebyplan/shipment.json)" 2>&1 | head -20
 ```
 
 If verification passes, mark the surface as configured. If it fails, surface the error and offer to retry the failing step.

package/templates/skills/cbp-ship-configure/reference/railway-backend.md

@@ -161,7 +161,7 @@ railway domain
 Verify:
 
 ```bash
-PROJECT_ID=$(jq -r '.surfaces."railway-backend".project_id' .codebyplan/shipment.json)
+PROJECT_ID=$(jq -r '.shipment.surfaces."railway-backend".project_id' .codebyplan/shipment.json)
 railway status --json | jq
 # Expect: project + service info matching saved IDs
 ```
@@ -171,7 +171,7 @@ Test deploy:
 ```bash
 railway up --detach
 # Wait, then verify URL responds
-URL=$(jq -r '.surfaces."railway-backend".url' .codebyplan/shipment.json)
+URL=$(jq -r '.shipment.surfaces."railway-backend".url' .codebyplan/shipment.json)
 curl -sI "$URL/health" | head -1
 ```
 

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

@@ -98,7 +98,7 @@ Write `.codebyplan/shipment.json`:
 Verify:
 
 ```bash
-PROJECT_ID=$(jq -r '.surfaces."vercel-web".project_id' .codebyplan/shipment.json)
+PROJECT_ID=$(jq -r '.shipment.surfaces."vercel-web".project_id' .codebyplan/shipment.json)
 vercel inspect "$PROJECT_ID" --json | jq -r '.name, .latestDeployments[0].readyState'
 ```
 

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

@@ -80,12 +80,13 @@ If `branch_deleted === true`, run a conditional Supabase preview-branch teardown
 > 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`.
+- Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id`.
+- Call `mcp__supabase__list_branches` with the resolved `project_id`.
 - 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.
+- Never delete the branch where `is_default` is true in the `list_branches` response (the production/parent project branch) or any other persistent/long-lived branch.
 - This coordinates safely with `/cbp-checkpoint-end` — the existence-checked delete makes any second attempt a harmless no-op.
 
 ## Key Rules

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

@@ -169,12 +169,13 @@ Parse the JSON output and store: `pr_url`, `merge_commit`, `branch_deleted`, `fe
 When `branch_deleted === true` in the ship JSON:
 
 - Read `FEAT_BRANCH` from the `feat_branch` field in the ship JSON — NOT from `git branch --show-current`. By the time Step 7.3 runs, `codebyplan ship` has already checked out the base branch, so the live branch is the base, not the feat branch.
-- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id`.
+- Call `mcp__supabase__list_branches` with the resolved `project_id`.
 - 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 outcome.
 - 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 non-success response): emit a non-blocking warning that the Supabase preview branch for `FEAT_BRANCH` may still exist and should be verified in the dashboard. Never treat an API failure as a not-found success.
-- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+- Never delete the branch where `is_default` is true in the `list_branches` response (the production/parent project branch) or any other persistent/long-lived branch.
 
 ### Step 7.5: Complete Standalone Task
 

package/templates/skills/cbp-supabase-migrate/SKILL.md

@@ -125,11 +125,7 @@ already provisioned the branch. Capture it as `PREVIEW_PROJECT_REF` and jump str
 
 ### Idempotency check (list before create)
 
-Call `mcp__supabase__list_branches` with the parent `project_id` `rrvtrumtkhrsbhcyrwvf`. The
-parent `project_id` for MCP calls is the same ref string stored in `.codebyplan/shipment.json`
-`surfaces.supabase.project_ref` — Supabase uses that one ref as both the project identifier
-and the branch target. Scan the returned list for an entry whose `name` exactly equals
-`$BRANCH` (slashes included — `feat/CHK-144-...` is a valid Supabase branch name).
+Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id` for all MCP calls in this step. The parent `project_id` is the same ref that Supabase uses as both the project identifier and the branch target. Call `mcp__supabase__list_branches` with the resolved `project_id`. Scan the returned list for an entry whose `name` exactly equals `$BRANCH` (slashes included — `feat/CHK-144-...` is a valid Supabase branch name).
 
 - **Match found**: capture its `project_ref` as `PREVIEW_PROJECT_REF`. Skip creation; proceed
   to "Record connection". This is the idempotent reuse path (covers a branch the GitHub
@@ -148,7 +144,7 @@ Cost confirmation is mandatory before creating a branch — never bypass it:
    stays empty.
 
 After cost is confirmed, call `mcp__supabase__create_branch`:
-- `project_id`: `rrvtrumtkhrsbhcyrwvf` (parent project ref)
+- `project_id`: the resolved parent project ref (`.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`, falling back to the first line of `supabase/.temp/project-ref`)
 - `name`: `$BRANCH` (verbatim — slashes included)
 - `confirm_cost_id`: the same id from the `get_cost` response that was passed to `confirm_cost`