codebyplan 1.13.39 → 1.13.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.39",
+  "version": "1.13.41",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {
@@ -45,7 +45,9 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@napi-rs/keyring": "^1.1.6"
+    "@napi-rs/keyring": "^1.1.6",
+    "@supabase/supabase-js": "^2.106.0",
+    "ws": ">=8.20.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",

package/templates/agents/cbp-cc-executor.md

@@ -2,7 +2,7 @@
 scope: org-shared
 name: cbp-cc-executor
 description: Authoring executor for `.claude/` infrastructure. Applies approved changes across rules, skills, agents, context, CLAUDE.md, settings, and hooks — with update-first discipline, scope-marker enforcement, and length-limit awareness. Callable by the main conversation, `/cbp-checkpoint-end`, and `round-executor` (for in-scope `.claude/` infra deliverables).
-tools: Read, Write, Edit, Glob, Grep, Skill, Task, AskUserQuestion, mcp__codebyplan__create_task
+tools: Read, Write, Edit, Glob, Grep, Skill, Task, AskUserQuestion, Bash(npx codebyplan task create *)
 model: sonnet
 effort: xhigh
 ---
@@ -134,7 +134,7 @@ Record every applied change with `authored_via` and `status`.
 
 - **Downgrade `create` → `update`** — apply silently, note in output.
 - **Unclear fit between two existing files** — `AskUserQuestion` with the two candidates and their descriptions.
-- **Change exceeds this invocation's scope** (e.g. proposal implies a broader refactor) — create a task via MCP `create_task` per `cbp-task-create` Step 3.5 "Immediate Issue Capture Contract", record in `deferred_changes` with `task_id_created`.
+- **Change exceeds this invocation's scope** (e.g. proposal implies a broader refactor) — create a task via CLI write-through `codebyplan task create --checkpoint-id <id> ...` per `cbp-task-create` Step 3.5 "Immediate Issue Capture Contract"; MCP `create_task` as documented break-glass when CLI unavailable. Record in `deferred_changes` with `task_id_created`.
 - **Hook or settings change with cross-environment implications** — require explicit `scope` field from caller; if missing or ambiguous, ask.
 
 ### Phase 5: Post-Apply Sanity
@@ -197,7 +197,7 @@ Block-limit violations are non-negotiable — split before applying.
 - **Signed creates, edited updates** — creates route through build-cc skills (they embed the signature); updates use direct Edit on already-signed files.
 - **Never create agents** — only `update`. Agent creation requires a planning-level decision outside the fix pipeline.
 - **Length limits are enforced pre-apply** — refuse to produce a file that will fail the block limit.
-- **Surface, don't silently swallow** — ambiguity → `AskUserQuestion`; out-of-scope → MCP `create_task`.
+- **Surface, don't silently swallow** — ambiguity → `AskUserQuestion`; out-of-scope → CLI `codebyplan task create` (MCP `create_task` as documented break-glass).
 - **Fresh inventory per invocation** — never reuse a cached inventory from a prior call.
 
 ## Integration
@@ -206,5 +206,5 @@ Block-limit violations are non-negotiable — split before applying.
 - **Reads**: `.claude/` inventory, `validate-structure-lengths.sh`, target files
 - **Writes**: `.claude/` files (via `/cbp-build-cc-*` skills for creates, direct Edit for updates)
 - **Calls skills**: `/cbp-build-cc-rule`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`
-- **Creates tasks**: via MCP `create_task` when a change exceeds invocation scope
+- **Creates tasks**: via CLI write-through `codebyplan task create` when a change exceeds invocation scope; MCP `create_task` as documented break-glass when CLI unavailable
 - **Enforced by**: `validate-structure-lengths.sh` (length), `validate-structure-scope.sh` (scope marker), `validate-structure-patterns.sh` (path layout)

package/templates/agents/cbp-database-agent.md

@@ -2,7 +2,7 @@
 scope: org-shared
 name: cbp-database-agent
 description: Supabase database specialist. Handles migrations, RLS policies, type generation, and schema changes. Spawned as sub-executor by round-executor when plan includes DB work.
-tools: Read, Write, Edit, Glob, Grep, Bash, mcp__claude_ai_Supabase__*
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__supabase__apply_migration, mcp__supabase__execute_sql, mcp__supabase__list_tables, mcp__supabase__list_migrations, mcp__supabase__get_advisors, mcp__supabase__generate_typescript_types, mcp__supabase__search_docs
 model: sonnet
 effort: xhigh
 ---
@@ -70,10 +70,10 @@ Before any DB mutation, perform all three pre-flight checks in order:
 
    Return `blocked` status with the cause list so the round-executor can surface it to the user.
 
-3. **Main Project Guard.** Before executing ANY operation against the resolved `project_ref` (migration apply, RLS policy change, type generation, advisor calls, or type reads), read the main project_ref from `.codebyplan.json`:
+3. **Main Project Guard.** Before executing ANY operation against the resolved `project_ref` (migration apply, RLS policy change, type generation, advisor calls, or type reads), read the main project_ref from `.codebyplan/shipment.json`:
 
    ```bash
-   jq -r '.shipment.surfaces.supabase.project_ref' .codebyplan.json
+   jq -r '.shipment.surfaces.supabase.project_ref' .codebyplan/shipment.json
    ```
 
    If the `project_ref` resolved above matches this value, the agent is targeting the
@@ -187,6 +187,16 @@ For access pattern changes:
 3. Follow existing patterns in the project for policy naming
 4. Test with: `execute_sql` to verify policy exists
 
+**Security requirements (official Supabase alignment):**
+
+- Authorization predicates read `app_metadata` / `raw_app_meta_data`, never `user_metadata` / `raw_user_meta_data` — the latter is user-editable and basing a policy on it is a privilege-escalation hole.
+- `update` policies must declare BOTH a `using` clause and a `with check` clause. `using` gates which existing rows are updatable; `with check` gates the new row values. Omitting `with check` lets a caller rewrite a row (e.g. reassign its owner) to a value that escapes the policy.
+- `auth.role()` is deprecated — scope policies to roles with the `to` clause (`to authenticated`, `to anon`) instead of comparing `auth.role()` inside the predicate.
+- Views in an exposed schema must be created with `security_invoker = true` (Postgres 15+); otherwise the view runs as its owner and bypasses the querying user's row-level security.
+- Prefer `security invoker` functions. A `security definer` function bypasses row-level security and runs as its owner — reserve it for the recursion-break helper in Step 2.75, keep it in a non-exposed schema, guard it with an `auth.uid()` ownership check, and harden `search_path` per `rules/migration-security.md`.
+- Capture any ad-hoc schema change made interactively via `execute_sql` during iteration back into a migration file (Step 2) — never leave a change preview-branch-only.
+- When the correct syntax for a policy, view, or function construct is uncertain, call `search_docs` to consult authoritative Supabase documentation before authoring.
+
 ### Step 4: Generate TypeScript Types
 
 After schema changes:
@@ -225,5 +235,6 @@ Populate all output contract fields. Include every file changed.
 
 - **Spawned by**: `round-executor` (as sub-executor when plan includes DB work)
 - **Returns to**: `round-executor`
-- **Tools**: Supabase MCP tools (`apply_migration`, `execute_sql`, `list_tables`, `list_migrations`, `generate_typescript_types`), Bash for CLI commands
+- **Tools**: Supabase MCP tools (`apply_migration`, `execute_sql`, `list_tables`, `list_migrations`, `get_advisors`, `generate_typescript_types`, `search_docs`), Bash for CLI commands
 - **Rule**: `migration-infrastructure.md` — cross-agent mandate for migration push verification, backfill, and error resolution
+- **Official skills** (vendored, for deeper guidance): `supabase` — Supabase security checklist, MCP surface, RLS/auth policy authoring; `supabase-postgres-best-practices` — Postgres query optimization, schema/index design, RLS performance.

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

@@ -212,16 +212,6 @@ If modifying managed files (`.claude/*`, `.claude/docs/architecture/*`, etc.):
 
 **Why:** Routing commands do this automatically. If you bypass routing, you MUST do source consultation manually. Skills contain coding patterns and conventions that must be followed.
 
-### Step 2.4: Architecture Map Consultation
-
-For ANY module you are about to edit (app code or managed files), check for a pre-computed architecture map:
-
-1. For each path in `files_to_modify`, derive its module and Glob `.claude/architecture/<module-slug>.md`.
-2. If a map exists, read it BEFORE Step 3 — it surfaces the module's boundaries, internal structure, dependencies, and where-things-live landmarks, reducing broad file-system scans.
-3. If `.claude/architecture/` is absent or the module has no map, proceed without it (not a blocker).
-
-See `.claude/context/architecture-map.md` for the full consultation contract. Unlike Step 2 (managed files only), this step fires for every round regardless of file type.
-
 ### Step 2.5: Search Before Creating
 
 For each file with action `create` in `files_to_modify`:
@@ -610,6 +600,8 @@ Which would you prefer?
 - **Spawned by**: `/cbp-round-execute` Step 3 (single-wave 3-AGENT path or per-wave 3-WAVE path)
 - **Returns to**: `/cbp-round-execute` which collects output and runs per-wave `cbp-testing-qa-agent`
 - **Depends on**: `cbp-task-planner` agent (provides approved plan)
+- **Reads**: All task/round context arrives via the Input Contract (approved plan from `/cbp-round-start`). When the executor needs to read additional round or task state, read `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_*` tools when the state dir is absent and sync fails.
+- **Writes**: DB-side mutations are surfaced as `improvements_noted` entries for the orchestrator to execute (executor frontmatter excludes MCP DB tools — see Step 0.2 carve-out).
 - **May spawn**: `cbp-database-agent` (Supabase operations), `general-purpose` (background batch writes), and `cbp-cc-executor` (in-scope `.claude/` infra deliverables, `source: 'round-executor'`) as sub-executors. (NOT any `cbp-e2e-*` specialist — e2e is orchestrator-owned, spawned by `/cbp-round-execute` Step 5 per the Step 0.2 carve-out.)
 
 ## Structure Knowledge

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

@@ -216,3 +216,5 @@ When no divergence is detected, set `scope_divergence_detected: false` and proce
 
 - **Spawned by**: `/cbp-task-check` command
 - **Returns to**: `/cbp-task-check` which routes based on verdict
+- **Reads**: All task, checkpoint, and rounds data arrives via the Input Contract (passed by `/cbp-task-check`). Local `.codebyplan/state/` files are the preferred source when `/cbp-task-check` pre-fetches context — read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` and `rounds/*.json` (local-first; break-glass: MCP `get_*` tools when state dir is absent and sync fails). The agent itself reads only filesystem content (changed files) via the Read tool — it never calls MCP or CLI directly.
+- **Writes**: None — review only, never edits.

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

@@ -376,11 +376,6 @@ delegation_hint:
 
 Read `.claude/rules/*.md` and relevant architecture docs.
 
-If `.claude/architecture/` contains map file(s) for the target module(s), read them before
-finalizing scope — they provide pre-computed structural context (boundaries, dependencies,
-landmarks) that reduces the need for broad file-system scans. See
-`.claude/context/architecture-map.md` for the consultation contract.
-
 ### Phase 4: Clarify Requirements (Context-First)
 
 Before any AskUserQuestion call, check (1) `checkpoint.context`, (2) `task.context`, (3) codebase via Grep/Glob/Read. Only ask if all three fail. When asking, prefix with `Checked: [sources]. Not found. Asking: [question]`. If a question IS answered in context, use that answer directly — do not re-ask.
@@ -590,3 +585,5 @@ Use TaskCreate for plan step visibility.
 
 - **Spawned by**: `/cbp-round-start` (Step 5)
 - **Returns to**: `/cbp-round-start` for user approval
+- **Reads**: All DB state arrives via the Input Contract (pre-fetched by `/cbp-round-start`). Local `.codebyplan/state/` files are the preferred source when `/cbp-round-start` reads context before passing it in. Break-glass: MCP `get_*` tools when the state dir is absent and sync fails (daemon-dead + CLI-unavailable). The planner itself never calls MCP or the CLI directly (frontmatter excludes those tools).
+- **Writes**: None — planner never mutates DB state.

package/templates/hooks/README.md

@@ -2,7 +2,7 @@
 
 The `codebyplan` npm package ships a small, portable set of Claude Code hooks. They run in your project, use only generic primitives (`git rev-parse`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`), and degrade gracefully (exit 0) when their preconditions aren't met.
 
-Hook registration lives in [`hooks/hooks.json`](./hooks.json) — PreToolUse, PostToolUse, and UserPromptSubmit events are wired. (`Notification`, `SessionStart`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
+Hook registration lives in [`hooks/hooks.json`](./hooks.json) — PreToolUse, PostToolUse, UserPromptSubmit, and SessionStart events are wired. (`Notification`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
 
 **`cbp-statusline.sh` is auto-wired via `settings.project.base.json`.** The `statusLine` block is shipped inside `templates/settings.project.base.json` and merged into the consumer's `.claude/settings.json` automatically by `codebyplan claude install` (and on every `codebyplan claude update`). No manual copy-paste is required.
 
@@ -243,13 +243,25 @@ drops below threshold (e.g. after `/compact` or `/clear`), so the notice re-fire
 
 ---
 
+### `cbp-session-start-hook.sh` — SessionStart
+
+Hydrates the local-first state mirror at session start: runs `codebyplan sync` (full hydrate when cold, delta pull otherwise) and `codebyplan watch start` (idempotent — pidfile + process-alive check) so the per-worktree Realtime down-sync daemon is running for the session.
+
+**Blocks vs warns**: never blocks — exit 0 always. All command errors are swallowed.
+
+**Skips when**: no `.codebyplan/repo.json` in the project directory (not a CodeByPlan repo), or the CLI is unauthenticated/offline (both subcommands self-guard and the hook ignores their failures).
+
+**Opt out**: settings.json override removing the `SessionStart` entry, or plugin disable.
+
+---
+
 ## Supporting (not registered)
 
 ### `test-hooks.sh` — invoked by `auto-test-hooks.sh`
 
 Test suite for the plugin's 9 registered hooks. Runs two passes:
 
-1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`, `cbp-context-window-notify`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
+1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`, `cbp-context-window-notify`, `cbp-session-start-hook`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
 2. **Functional smoke tests** — each hook is invoked with synthetic stdin matching its fast-path / graceful-degrade input; all must exit 0.
 
 Not in `hooks.json` — invoked indirectly via `auto-test-hooks.sh` on hook edits, or directly via `bash ${CLAUDE_PLUGIN_ROOT}/hooks/test-hooks.sh`.

package/templates/hooks/cbp-session-start-hook.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# @scope: org-shared
+# Hook: SessionStart
+# Purpose: Hydrate .codebyplan/state/ via `codebyplan sync` and ensure the
+#          per-worktree watch daemon is running. Hook-safe: all errors
+#          swallowed, always exits 0. No-op when unauthenticated/offline.
+#
+# Runtime bound: the registered settings entry carries "timeout": 30 so the
+# Claude Code hook runtime kills a hung sync/start — never shell-wrap with
+# `timeout` (absent on macOS). `codebyplan sync` self-bounds its HTTP calls;
+# `watch start` returns immediately after the detached spawn.
+#
+# Concurrency: `codebyplan watch start` is atomically idempotent — it takes an
+# exclusive-create .pid.lock (O_EXCL) around the pidfile check + spawn, so two
+# SessionStart hooks firing together in the same worktree start at most one
+# daemon (the loser exits 0 with "start already in progress").
+
+# Resolve the project dir: Claude Code sets CLAUDE_PROJECT_DIR; fall back to pwd.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# No-op when not inside a codebyplan repo (sentinel file absent).
+if [ ! -f "$PROJECT_DIR/.codebyplan/repo.json" ]; then
+  exit 0
+fi
+
+# Hydrate state cache from backend (no-op offline / unauthenticated).
+npx codebyplan sync >/dev/null 2>&1 || true
+
+# Ensure per-worktree watch daemon is running (no-op when already up).
+npx codebyplan watch start >/dev/null 2>&1 || true
+
+exit 0

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

@@ -59,15 +59,20 @@ CHECKED=0
 SKIPPED=0
 
 while IFS= read -r FILE; do
-  # Skip test files themselves
-  if echo "$FILE" | grep -qE '\.(test|spec)\.(ts|tsx|js|jsx)$'; then
+  # Skip test files themselves. The leading [.-] class also matches framework
+  # spec conventions that suffix the marker with a dash — e.g. NestJS
+  # `*.e2e-spec.ts` (dot-form `.spec.ts` plus dash-form `-spec.ts`/`-test.ts`).
+  if echo "$FILE" | grep -qE '[.-](test|spec)\.(ts|tsx|js|jsx)$'; then
     continue
   fi
 
-  # Skip files under a __tests__/ or __mocks__/ directory — fixtures, helpers,
-  # setup, manual mocks, and other test infrastructure are imported by the test
-  # files that exercise them; requiring a dedicated .test.ts is nonsensical.
-  if echo "$FILE" | grep -qE '/__tests__/|/__mocks__/'; then
+  # Skip files under a __tests__/, __mocks__/, or top-level test/ directory —
+  # fixtures, helpers, setup (seed.ts, load-env.ts), manual mocks, and other
+  # test infrastructure are imported by the test files that exercise them;
+  # requiring a dedicated .test.ts for a fixture is nonsensical. `/test/` covers
+  # the NestJS e2e convention (apps/<app>/test/*.e2e-spec.ts) alongside the
+  # __tests__/ and __mocks__/ layouts.
+  if echo "$FILE" | grep -qE '/__tests__/|/__mocks__/|/test/'; then
     SKIPPED=$((SKIPPED + 1))
     continue
   fi
@@ -88,6 +93,15 @@ while IFS= read -r FILE; do
     continue
   fi
 
+  # Skip NestJS framework wrappers — *.module.ts are dependency-injection wiring
+  # barrels and *.decorator.ts are metadata-only; behavior lives in the
+  # providers/handlers they wire, which carry their own specs. Same category as
+  # the index barrel skip above.
+  if echo "$FILE" | grep -qE '\.(module|decorator)\.(ts|js)$'; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
   # Skip Next.js App Router framework files — page/layout/loading/error/route/
   # etc. are framework-convention wrappers, not logic-bearing modules. Same
   # category as the barrel/index skip above: behavior lives in the components

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

@@ -455,6 +455,78 @@ fi
 
 echo ""
 
+# ===== HOOK SMOKE TESTS — cbp-session-start-hook =====
+echo "## Hook Smoke Tests — cbp-session-start-hook (CHK-178)"
+
+SESSION_START_HOOK="$HOOKS_DIR/cbp-session-start-hook.sh"
+
+if [ ! -f "$SESSION_START_HOOK" ]; then
+  test_result "cbp-session-start-hook.sh present" "passed" "missing"
+else
+  test_result "cbp-session-start-hook.sh present" "passed" "passed"
+
+  # Header/@scope check
+  FIRST_LINE=$(head -1 "$SESSION_START_HOOK")
+  if echo "$FIRST_LINE" | grep -q '^#!/'; then
+    test_result "cbp-session-start-hook.sh has shebang" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh has shebang" "passed" "missing"
+  fi
+
+  if grep -q '@scope: org-shared' "$SESSION_START_HOOK"; then
+    test_result "cbp-session-start-hook.sh has @scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh has @scope: org-shared" "passed" "missing"
+  fi
+
+  # Syntax check
+  if bash -n "$SESSION_START_HOOK" 2>/dev/null; then
+    test_result "cbp-session-start-hook.sh bash -n syntax ok" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh bash -n syntax ok" "passed" "failed"
+  fi
+
+  # Graceful-degrade: run in a temp dir without .codebyplan/repo.json — hook
+  # must exit 0 (no-op) without invoking npx (stub npx as a no-op in PATH).
+  ISO=$(mktemp -d)
+  # Create a stub npx in a temp bin dir so npx invocations are harmless no-ops.
+  STUB_BIN=$(mktemp -d)
+  printf '#!/bin/bash\nexit 0\n' > "$STUB_BIN/npx"
+  chmod +x "$STUB_BIN/npx"
+  ACTUAL_EXIT=$(CLAUDE_PROJECT_DIR="$ISO" PATH="$STUB_BIN:$PATH" bash "$SESSION_START_HOOK" >/dev/null 2>&1; echo $?)
+  # In the no-repo.json path npx must NOT be invoked at all — use a recording
+  # stub marker dir to assert zero invocations.
+  rm -rf "$ISO" "$STUB_BIN"
+  if [ "$ACTUAL_EXIT" = "0" ]; then
+    test_result "cbp-session-start-hook.sh graceful-degrade (no repo.json) exits 0" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh graceful-degrade (no repo.json) exits 0" "passed" "failed (exit=$ACTUAL_EXIT)"
+  fi
+
+  # Positive path: with .codebyplan/repo.json present, the hook must invoke
+  # `npx codebyplan sync` AND `npx codebyplan watch start` (recording stub
+  # writes each invocation's args to a marker file), and still exit 0.
+  ISO=$(mktemp -d)
+  STUB_BIN=$(mktemp -d)
+  MARKER="$STUB_BIN/invocations.log"
+  mkdir -p "$ISO/.codebyplan"
+  printf '{}' > "$ISO/.codebyplan/repo.json"
+  printf '#!/bin/bash
+echo "$@" >> "%s"
+exit 0
+' "$MARKER" > "$STUB_BIN/npx"
+  chmod +x "$STUB_BIN/npx"
+  ACTUAL_EXIT=$(CLAUDE_PROJECT_DIR="$ISO" PATH="$STUB_BIN:$PATH" bash "$SESSION_START_HOOK" >/dev/null 2>&1; echo $?)
+  if [ "$ACTUAL_EXIT" = "0" ] && grep -q "codebyplan sync" "$MARKER" 2>/dev/null && grep -q "codebyplan watch start" "$MARKER" 2>/dev/null; then
+    test_result "cbp-session-start-hook.sh positive path invokes sync + watch start, exits 0" "passed" "passed"
+  else
+    test_result "cbp-session-start-hook.sh positive path invokes sync + watch start, exits 0" "passed" "failed (exit=$ACTUAL_EXIT)"
+  fi
+  rm -rf "$ISO" "$STUB_BIN"
+fi
+
+echo ""
+
 # ===== SUMMARY =====
 echo "=== TEST SUMMARY ==="
 echo -e "Passed: ${GREEN}$PASSED${NC}"

package/templates/hooks/hooks.json

@@ -1,5 +1,16 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-session-start-hook.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [

package/templates/hooks/validate-structure-patterns.sh

@@ -9,9 +9,11 @@
 
 # ===== Path-pattern enforcement =====
 # Each row: enforce_path_pattern <prefix> <full_pattern> <block_msg> <expected_hint>
-_SUB='(templates|examples|reference|scripts)/[a-z0-9.-]+\.(md|sh|json|ya?ml)'
-enforce_path_pattern '^/\.claude/skills/' "^/\.claude/skills/[a-z0-9-]+/(SKILL\.md|[a-z0-9-]+\.md|${_SUB})$" 'Invalid skill path' "Pattern: /.claude/skills/{name}/SKILL.md | /.claude/skills/{name}/{file}.md | /.claude/skills/{name}/(templates|examples|reference|scripts)/{file}.{md,sh,json,yaml}"
-enforce_path_pattern '^/\.claude/agents/' "^/\.claude/agents/([a-z0-9-]+\.md|[a-z0-9-]+/(AGENT\.md|[a-z0-9-]+\.md|${_SUB}))$" 'Invalid agent path' "Pattern: /.claude/agents/{name}.md | /.claude/agents/{name}/AGENT.md | /.claude/agents/{name}/{file}.md | /.claude/agents/{name}/(templates|examples|reference|scripts)/{file}.{md,sh,json,yaml}"
+# references/ (plural) + assets/ subdirs and leading-underscore filenames (e.g. references/_sections.md)
+# are carried by vendored upstream skills (.claude/skills/supabase*, supabase-postgres-best-practices).
+_SUB='(templates|examples|reference|references|scripts|assets)/[a-z0-9._-]+\.(md|sh|json|ya?ml)'
+enforce_path_pattern '^/\.claude/skills/' "^/\.claude/skills/[a-z0-9-]+/(SKILL\.md|PROVENANCE\.md|CHANGELOG\.md|[a-z0-9-]+\.md|${_SUB})$" 'Invalid skill path' "Pattern: /.claude/skills/{name}/SKILL.md | /.claude/skills/{name}/(PROVENANCE|CHANGELOG).md | /.claude/skills/{name}/{file}.md | /.claude/skills/{name}/(templates|examples|reference|references|scripts|assets)/{file}.{md,sh,json,yaml}"
+enforce_path_pattern '^/\.claude/agents/' "^/\.claude/agents/([a-z0-9-]+\.md|[a-z0-9-]+/(AGENT\.md|PROVENANCE\.md|CHANGELOG\.md|[a-z0-9-]+\.md|${_SUB}))$" 'Invalid agent path' "Pattern: /.claude/agents/{name}.md | /.claude/agents/{name}/AGENT.md | /.claude/agents/{name}/(PROVENANCE|CHANGELOG).md | /.claude/agents/{name}/{file}.md | /.claude/agents/{name}/(templates|examples|reference|references|scripts|assets)/{file}.{md,sh,json,yaml}"
 enforce_path_pattern '^/\.claude/rules/' '^/\.claude/rules/[a-z0-9-]+\.md$' 'Invalid native rule path' 'Pattern: /.claude/rules/{name}.md'
 if match_path '^/\.claude/hooks/' && ! match_path '^/\.claude/hooks/__test-fixtures__/'; then
   if ! match_path '^/\.claude/hooks/[a-z-]+\.sh$'; then

package/templates/hooks/validate-structure.sh

@@ -48,10 +48,11 @@ esac
 FILENAME=$(basename "$FILE_PATH" ".$EXT")
 
 if match_path '^/(\.claude|docs)/'; then
-  # Skip special naming patterns (SKILL/AGENT/CLAUDE/MEMORY/TASK-N/CHK-NNN/date/week-N/research phase/README/INDEX)
+  # Skip special naming patterns (SKILL/AGENT/CLAUDE/MEMORY/TASK-N/CHK-NNN/date/week-N/research phase/README/INDEX/PROVENANCE/CHANGELOG)
+  # PROVENANCE/CHANGELOG: uppercase filenames carried by vendored upstream skills (e.g. .claude/skills/supabase/*)
   # CHK formats: CHK-001 (generic) or CHK-H001/CHK-A001/CHK-B001 (launch: Homepage/Application/Backdoor)
   # INDEX: grep-native registry filename used by the architecture-map pipeline (.claude/architecture/INDEX.md) and vendor docs
-  if ! echo "$FILENAME" | grep -qE '^(SKILL|AGENT|CLAUDE|MEMORY|TASK-[1-9]|[0-9]{2}-[0-9]{2}-[0-9]{2}-CHK-([0-9]{3}|[HAB][0-9]{3})|CHK-([0-9]{3}|[HAB][0-9]{3})|[0-9]{2}-[0-9]{2}-[0-9]{2}|week-[0-9]+|[1-8]-|README|INDEX)'; then
+  if ! echo "$FILENAME" | grep -qE '^(SKILL|AGENT|CLAUDE|MEMORY|TASK-[1-9]|[0-9]{2}-[0-9]{2}-[0-9]{2}-CHK-([0-9]{3}|[HAB][0-9]{3})|CHK-([0-9]{3}|[HAB][0-9]{3})|[0-9]{2}-[0-9]{2}-[0-9]{2}|week-[0-9]+|[1-8]-|README|INDEX|PROVENANCE|CHANGELOG)'; then
     if echo "$FILENAME" | grep -qE '[A-Z]|_'; then
       block "Filename must be kebab-case (lowercase with hyphens)" "Got: $FILENAME, Expected: $(echo "$FILENAME" | tr '[:upper:]' '[:lower:]' | tr '_' '-')"
     fi

package/templates/settings.project.base.json

@@ -133,6 +133,8 @@
       "Skill(cbp-task-start)",
       "Skill(cbp-task-testing)",
       "Skill(cbp-todo)",
+      "Skill(supabase)",
+      "Skill(supabase-postgres-best-practices)",
       "mcp__codebyplan__get_checkpoints",
       "mcp__codebyplan__get_current_task",
       "mcp__codebyplan__get_eslint_presets",
@@ -194,6 +196,16 @@
       "Bash(npx codebyplan lsp:*)",
       "Bash(codebyplan round:*)",
       "Bash(npx codebyplan round:*)",
+      "Bash(codebyplan sync:*)",
+      "Bash(npx codebyplan sync:*)",
+      "Bash(codebyplan watch:*)",
+      "Bash(npx codebyplan watch:*)",
+      "Bash(codebyplan checkpoint:*)",
+      "Bash(npx codebyplan checkpoint:*)",
+      "Bash(codebyplan task:*)",
+      "Bash(npx codebyplan task:*)",
+      "Bash(codebyplan session:*)",
+      "Bash(npx codebyplan session:*)",
       "Bash(codebyplan help:*)",
       "Bash(npx codebyplan help:*)",
       "Bash(codebyplan --version:*)",

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

@@ -14,17 +14,17 @@ Full re-evaluation: compares initial ideas vs delivered work, aggregates files a
 
 ### Step 1: Identify Checkpoint
 
-**If arguments provided:** Parse `$ARGUMENTS` for CHK-NNN format, extract number. Use MCP `get_checkpoints` to find by number.
+**If arguments provided:** Parse `$ARGUMENTS` for CHK-NNN format, extract number. Scan `.codebyplan/state/checkpoints/*.json` to find by `number` field (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`).
 
-**If NO arguments:** Use MCP `get_current_task` to get the active checkpoint.
+**If NO arguments:** Read `.codebyplan/state/session/current.json` to get the active checkpoint (fallback: MCP `get_current_task`).
 
 If no checkpoint found, show error and stop.
 
 ### Step 2: Load All Data
 
-1. Get checkpoint details (context, research, qa, ideas, goal, user_context)
-2. Use MCP `get_tasks` for the checkpoint
-3. For each task, use MCP `get_rounds` to get all rounds
+1. Read `.codebyplan/state/checkpoints/<id>.json` for checkpoint details (context, research, qa, ideas, goal, user_context). Break-glass: MCP `get_checkpoints`.
+2. Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks`).
+3. For each task, read round files under `.codebyplan/state/checkpoints/<id>/tasks/<taskId>/rounds/*.json` (fallback: MCP `get_rounds`).
 
 ### Step 3: Before/After Comparison
 
@@ -109,7 +109,7 @@ Aggregate the files touched across all tasks (reusing Step 4's deduplicated tabl
      credential_vars: [from e2e.json — env var names only, never secrets]
    ```
 
-   Hold each specialist's output keyed by framework (an `e2e_outputs[framework]` map) for this skill's aggregation — checkpoint-check has no MCP round, so this lives in-memory during the run (persist to `checkpoint.context` via `update_checkpoint` at Step 7 if a durable record is needed). `test_strategy` is intentionally omitted — the agent resolves it from `.codebyplan/e2e.json` and the DB tech-stack record.
+   Hold each specialist's output keyed by framework (an `e2e_outputs[framework]` map) for this skill's aggregation — checkpoint-check has no MCP round, so this lives in-memory during the run (persist to `checkpoint.context` via the Step 7 CLI write-through — `codebyplan checkpoint update` — if a durable record is needed). `test_strategy` is intentionally omitted — the agent resolves it from `.codebyplan/e2e.json` and the DB tech-stack record.
 
 3. **Wait for all specialists to complete.** Each agent's output carries `whole_checkpoint_aggregated: true` confirming whole-checkpoint formatting.
 
@@ -120,7 +120,7 @@ Aggregate the files touched across all tasks (reusing Step 4's deduplicated tabl
    Continue to Step 6.
 
 5. **On fail** (any framework `f`: `e2e_outputs[f].status === 'failed'` OR `e2e_outputs[f].test_results.failed > 0`): build a failure summary from `e2e_outputs[*].test_results.failures[]` aggregated and grouped by `category`. Surface via `AskUserQuestion`:
-   - **(a) Create fix-task in CHK-{NNN} (recommended)** — invoke MCP `create_task` with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_outputs[*].screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` can verify failure premises. Per `cbp-round-end` reference `findings-presentation.md` "Infra Issue Absorption Contract — Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
+   - **(a) Create fix-task in CHK-{NNN} (recommended)** — run `codebyplan task create` (CLI write-through; break-glass: MCP `create_task`) with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_outputs[*].screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` can verify failure premises. Per `cbp-round-end` reference `findings-presentation.md` "Infra Issue Absorption Contract — Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
    - **(b) Surface as warning only — proceed to checkpoint-end** — append `| Checkpoint E2E | warning | N failures (deferred) |` to Step 5 QA Summary; continue to Step 6.
    - **(c) Halt — review manually** — STOP and wait for the user.
 
@@ -145,7 +145,7 @@ If unapproved files exist:
 
 ### Step 7: Save Results
 
-Update checkpoint via MCP `update_checkpoint`:
+Update checkpoint via `codebyplan checkpoint update --id <id> --qa <json> --context <json>` (CLI write-through; break-glass: MCP `update_checkpoint`):
 - `qa`: aggregated QA results
 - `context`: add `check_results` with before/after, file summary, assessment
 
@@ -155,6 +155,6 @@ If all clear, auto-trigger `/cbp-checkpoint-end`.
 
 ## Integration
 
-- **Reads**: MCP `get_checkpoints`, `get_tasks`, `get_rounds`, `get_current_task`
-- **Writes**: MCP `update_checkpoint` (qa, context)
+- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json`, `checkpoints/<id>/tasks/<taskId>/rounds/*.json`, `session/current.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_checkpoints`, `get_tasks`, `get_rounds`, `get_current_task`)
+- **Writes**: `codebyplan checkpoint update --qa ... --context ...` (CLI write-through; break-glass: MCP `update_checkpoint`)
 - **Triggers**: `/cbp-checkpoint-end` (auto, if ready) or STOPS for `/cbp-task-create` (if issues)

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

@@ -19,7 +19,7 @@ Parse the argument:
 | Shape | Regex | Resolves to |
 |-------|-------|-------------|
 | `{chk}` (e.g. `108`) | `^[0-9]+$` | Target CHK-{chk} |
-| _(empty)_ | — | Use MCP `get_current_task` to find the active checkpoint |
+| _(empty)_ | — | Resolve from local state per Step 1.5/2 (MCP `get_current_task` break-glass) — the active checkpoint |
 
 Anything else is malformed — surface this error and stop:
 
@@ -42,8 +42,8 @@ Given the parse from Step 0.5:
 
 | Parse | Resolution path |
 |-------|-----------------|
-| `{chk}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}` (must exist). |
-| _(empty)_ | MCP `get_current_task` with repo_id. Get the active checkpoint. If no active checkpoint, show error and stop. |
+| `{chk}` | Scan `.codebyplan/state/checkpoints/*.json` for `number === {chk}` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). |
+| _(empty)_ | Read `.codebyplan/state/session/current.json` for the active checkpoint (fallback: MCP `get_current_task`). If no active checkpoint, show error and stop. |
 
 ### Step 2: Verify Checkpoint End Has Run
 
@@ -59,7 +59,7 @@ Stop here.
 
 ### Step 2.5: Verify All Tasks Complete
 
-Use MCP `get_tasks` for the checkpoint. Verify all tasks have status `completed`.
+Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks`). Verify all tasks have status `completed`.
 
 If incomplete tasks remain:
 ```
@@ -82,7 +82,7 @@ If any critical failures, warn the user but don't block.
 
 ### Step 4: Complete Checkpoint
 
-Use MCP `complete_checkpoint(checkpoint_id)`.
+Run `codebyplan checkpoint complete --id <checkpoint-id>` (CLI write-through: updates `.codebyplan/state/checkpoints/<id>.json` + REST; break-glass: MCP `complete_checkpoint`).
 
 This automatically:
 - Sets status to `completed`
@@ -105,5 +105,5 @@ This automatically:
 ## Integration
 
 - **Triggered by**: `/cbp-checkpoint-end` (auto, after successful shipment)
-- **Reads**: MCP `get_current_task`, `get_tasks`, `get_rounds`
-- **Writes**: MCP `complete_checkpoint`
+- **Reads**: `.codebyplan/state/session/current.json`, `checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_current_task`, `get_tasks`, `get_rounds`)
+- **Writes**: `codebyplan checkpoint complete --id <id>` (CLI write-through; break-glass: MCP `complete_checkpoint`)

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

@@ -20,7 +20,7 @@ Runs INLINE. This is the **mechanical** stage only: capture raw user input, infe
 
 ### Step 1: Check for Existing Checkpoint Data
 
-Source `repo_id` from `.codebyplan/repo.json`. If `$ARGUMENTS` contains a checkpoint number, load it via MCP `get_checkpoints`. If the checkpoint already has `ideas[]` with descriptions, reuse `ideas[].description` (do not re-ask) and skip Step 2.
+Source `repo_id` from `.codebyplan/repo.json`. If `$ARGUMENTS` contains a checkpoint number, read `.codebyplan/state/checkpoints/` to find the matching file by `number` field (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_checkpoints` when the state dir is absent and sync fails. If the checkpoint already has `ideas[]` with descriptions, reuse `ideas[].description` (do not re-ask) and skip Step 2.
 
 ### Step 2: Get Checkpoint Description
 
@@ -71,14 +71,16 @@ Record the choice; it drives both the create call (Step 8) and the plan→start
 
 ### Step 7: Determine Next Checkpoint Number
 
-MCP `get_checkpoints` for the repo; highest `number` + 1.
+Scan `.codebyplan/state/checkpoints/*.json` for the highest `number` field + 1. If state dir is absent, run `npx codebyplan sync` once. Break-glass fallback: MCP `get_checkpoints` when sync fails.
 
 ### Step 8: Create Checkpoint Row
 
-MCP `create_checkpoint`:
-- `repo_id` (from `.codebyplan/repo.json`), `number`, `title`, `goal`, `deadline`, `status: "pending"`
-- `ideas`: `[{ description: <raw user text> }]`
-- `worktree_id`: the resolved worktree from Step 6 **only if the user chose "claim"**; omit when "leave open"
+`codebyplan checkpoint create` (CLI write-through: writes `.codebyplan/state/checkpoints/<id>.json` + REST). Pass flags:
+- `--repo-id` (from `.codebyplan/repo.json`), `--number`, `--title`, `--goal`, `--deadline`, `--status pending`
+- `--ideas` JSON `[{ description: <raw user text> }]`
+- `--worktree-id` the resolved worktree **only if the user chose "claim"**; omit when "leave open"
+
+Break-glass fallback: MCP `create_checkpoint` when the CLI is unavailable.
 
 This is the first identity-stamping point — when claiming, passing `worktree_id` here engages the CHK-104 hard-lock from birth. No `context`, `research`, `plan`, or tasks are written here.
 
@@ -93,7 +95,7 @@ git checkout -b "feat/CHK-{NNN}-{slug}" "origin/$BASE" 2>/dev/null \
 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.)
+Slug: lowercase, dash-joined, punctuation dropped, ≤40 chars. Persist the branch via `codebyplan checkpoint update --id <checkpoint-id> --branch-name "feat/CHK-{NNN}-{slug}"` (CLI write-through; break-glass: MCP `update_checkpoint`). (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.
 
@@ -113,6 +115,6 @@ Auto-trigger `/cbp-checkpoint-plan {NNN}` in the same context. This skill create
 ## Integration
 
 - **Runs inline**: mechanical setup only — no assessment, research, Q&A, plan, or tasks
-- **Reads**: MCP `get_checkpoints`; `.codebyplan/repo.json`, `.codebyplan/git.json`; `npx codebyplan resolve-worktree`
-- **Writes**: MCP `create_checkpoint` (description-only ideas + deadline + optional worktree_id), `update_checkpoint` (branch_name)
+- **Reads**: `.codebyplan/state/checkpoints/*.json` (local-first; `npx codebyplan sync` if stale; MCP `get_checkpoints` break-glass); `.codebyplan/repo.json`, `.codebyplan/git.json`; `npx codebyplan resolve-worktree`
+- **Writes**: `codebyplan checkpoint create` (description-only ideas + deadline + optional worktree_id), `codebyplan checkpoint update --branch-name` (break-glass: MCP `create_checkpoint` / `update_checkpoint`)
 - **Triggers**: `/cbp-checkpoint-plan` (auto)