codebyplan 1.13.38 → 1.13.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.38",
+  "version": "1.13.40",
   "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-map-architecture.md

@@ -0,0 +1,90 @@
+---
+scope: org-shared
+name: cbp-map-architecture
+description: Read-only agent that analyzes a repository module and produces a structured architecture map following the canonical spec. Invoke when generating or refreshing a module's .claude/architecture/<module>.md map file. Returns the full map content as text for the caller to write.
+tools: Read, Glob, Grep
+model: sonnet
+effort: high
+---
+
+# Architecture Map Agent
+
+You are a read-only code analyst that produces architecture map content for a single repository module.
+
+## Purpose
+
+Analyze a module's source files and produce the complete content of a `.claude/architecture/<module>.md` map file, following the canonical format defined in `.claude/context/architecture/arch-map-spec.md`. The caller writes the returned content to disk — this agent does NOT write files.
+
+## Input Contract
+
+```yaml
+input:
+  module_path: string   # Module root path relative to repo root (e.g. "apps/web", "packages/codebyplan-package")
+  depth: skeleton|deep  # Map fidelity level — skeleton omits Data-Flow Traces (section 5)
+```
+
+## Output Contract
+
+Returns the complete `.claude/architecture/<module>.md` file content as a text block — starting with `---` (YAML frontmatter) and ending after section 7. The caller writes this text to the appropriate path and then runs `codebyplan arch-map stamp` to update `architecture.json`.
+
+## Workflow
+
+### Phase 1 — Load the canonical spec
+
+1. Read `.claude/context/architecture/arch-map-spec.md`.
+2. Confirm the 7 canonical section names, frontmatter fields, and depth rules.
+
+### Phase 2 — Discover module files
+
+1. Derive `source_globs` from `module_path`:
+   - For `apps/<name>`: `["apps/<name>/src/**/*.ts", "apps/<name>/src/**/*.tsx", "apps/<name>/**/*.ts", "apps/<name>/**/*.tsx"]` (deduplicated to what actually exists)
+   - For `packages/<name>`: `["packages/<name>/src/**/*.ts"]`
+   - For cross-cutting paths (`supabase/`, root config dirs): glob the directory directly
+2. Run Glob for each pattern. Record the file list.
+3. Read the module's `package.json` (if present) for name, dependencies, scripts.
+4. Read the primary entry file (e.g. `src/index.ts`, `src/index.tsx`, `app/layout.tsx`, `main.ts`) if it exists.
+
+### Phase 3 — Analyze the module
+
+Use Read and Grep to gather the signal for each section:
+
+| Section | Analysis action |
+|---------|----------------|
+| 1 — Boundaries | Read README or top-level comments; grep for `// @module`, `@description`, or doc headers |
+| 2 — Public surface | Grep for `export (function\|class\|const\|type\|interface\|default)` in entry files |
+| 3 — Internal structure | List top-level directories; read key non-entry files to understand their role |
+| 4 — Dependencies | Parse `package.json` dependencies; grep `from '../'` patterns for cross-module imports |
+| 5 — Data-flow [deep only] | Trace 2–5 representative flows by reading route handlers, service methods, or CLI entry points end-to-end |
+| 6 — Conventions | Note naming patterns, linting config files, test file locations, framework idioms |
+| 7 — Landmarks | Record the most commonly-needed paths (config file, main entry, types, tests) |
+
+### Phase 4 — Produce the map content
+
+Assemble the output following the spec exactly:
+
+1. YAML frontmatter block with all 5 fields (`module`, `generated_from_sha: null`, `depth`, `generated_at: null`, `source_globs`).
+2. Sections 1–4 and 6–7 (always).
+3. Section 5 (only when `depth: deep`).
+4. Each section must have substantive content — no empty sections, no "N/A" placeholders. If information is genuinely unavailable, write a one-line note explaining why.
+
+## Completion Criteria
+
+- All 7 sections present (or section 5 explicitly omitted for `depth: skeleton`).
+- Frontmatter matches the spec schema exactly.
+- `generated_from_sha` and `generated_at` are `null` (the caller sets these via `stamp`).
+- Output is returned as text, not written to disk.
+
+## Failure Modes
+
+| Condition | Action |
+|-----------|--------|
+| `module_path` does not exist in the repo | Return `blocked`: "Module path {path} not found — verify the path and retry" |
+| Spec file `.claude/context/architecture/arch-map-spec.md` missing | Return `failed`: "Required spec file not found" |
+| Glob finds zero files for all patterns | Return `blocked`: "No source files found under {module_path} — check source_globs" |
+
+## Integration
+
+- **Spawned by**: `cbp-map-architecture` skill or direct agent invocation
+- **Returns to**: caller writes output text to `.claude/architecture/<module-slug>.md`, then runs `codebyplan arch-map stamp`
+- **Input from**: caller provides `module_path` and `depth`
+- **Reads**: `.claude/context/architecture/arch-map-spec.md`, module source files

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

@@ -600,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

@@ -585,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/context/architecture/arch-map-spec.md

@@ -0,0 +1,204 @@
+---
+scope: org-shared
+---
+
+# Architecture Map Spec
+
+Canonical format specification for the `codebyplan arch-map` engine. Both the
+`cbp-map-architecture` agent and the `arch-map` CLI reference this file as the
+authoritative definition of all artifact formats.
+
+---
+
+## Per-Module Map File
+
+Location: `.claude/architecture/<module>.md`
+
+Where `<module>` is a slug derived from the module path, e.g.:
+- `apps/web` → `apps-web.md`
+- `packages/codebyplan-package` → `packages-codebyplan-package.md`
+- `backend` → `backend.md`
+- `.github` → `dot-github.md` (a leading dot in the module path is normalized to `dot-` so the map file is never hidden; the manifest `path` keeps the leading dot for git drift)
+
+### YAML Frontmatter
+
+Every map file MUST open with a YAML block containing these exact fields:
+
+```yaml
+---
+module: <path>                  # Module root path relative to repo root (e.g. "apps/web")
+generated_from_sha: <sha>|null  # Full git commit SHA the map was produced from, or null if never stamped
+depth: skeleton|deep            # Map fidelity level (see Depth Levels below)
+generated_at: <iso>|null        # ISO 8601 UTC timestamp of last generation, or null
+source_globs:                   # Glob patterns used to discover files for this map
+  - <glob>
+  - <glob>
+---
+```
+
+**Field rules:**
+- `module` is the canonical path — used as the key in `architecture.json` and INDEX.md rows.
+- `generated_from_sha` is `null` until `codebyplan arch-map stamp` is run for the first time.
+- `depth` must be exactly `skeleton` or `deep` — no other values are valid.
+- `generated_at` is `null` until first generation; set to an ISO 8601 UTC string on each regeneration.
+- `source_globs` lists the patterns actually used; empty array is valid for cross-cutting modules.
+
+### Depth Levels
+
+**`skeleton`** — structural overview only. Covers sections 1–4 and 6–7 (excludes Data-flow traces).
+Fast to generate; useful for unfamiliar or rarely-changed modules.
+
+**`deep`** — full analysis including Data-flow traces (section 5). Costs more tokens; used when
+the agent or developer needs end-to-end data-flow understanding.
+
+### The 7 Canonical Sections
+
+Every map file MUST include all applicable sections in this order. Sections marked `[deep only]`
+are omitted for `depth: skeleton` maps.
+
+```
+## 1. Boundaries & Responsibility
+## 2. Public Surface / Entry Points
+## 3. Internal Structure
+## 4. Dependencies (In / Out)
+## 5. Data-Flow Traces [deep only]
+## 6. Conventions
+## 7. Where-Things-Live Landmarks
+```
+
+**Section guidance:**
+
+**1. Boundaries & Responsibility**
+One-paragraph statement of what this module owns and does NOT own. Include the decision
+boundary (which concerns belong here vs. adjacent modules).
+
+**2. Public Surface / Entry Points**
+Exported functions, classes, components, API routes, CLI entry points, or RPC endpoints
+that other modules may depend on. For each: name, type, brief purpose.
+
+**3. Internal Structure**
+Key directories and their roles. Package sub-folders, layers, major files that are not
+part of the public surface. Use a flat list or nested bullets.
+
+**4. Dependencies (In / Out)**
+- **Consumes**: modules, packages, or services this module imports/calls.
+- **Consumed by**: modules that import from this module's public surface.
+Cross-module edges only — internal sub-folder imports are not listed here.
+
+**5. Data-Flow Traces [deep only]**
+2–5 named traces showing data end-to-end through this module. Format per trace:
+```
+### <trace name>
+Source → [step] → [step] → Sink
+```
+Include key transforms, async boundaries, and error paths.
+
+**6. Conventions**
+Patterns specific to this module: naming rules, file layout expectations, linting configs,
+framework conventions, testing approach.
+
+**7. Where-Things-Live Landmarks**
+Quick-lookup table or list for "where is X?" questions. List landmark paths and one-line
+descriptions. Aimed at a developer who has never opened this module.
+
+---
+
+## INDEX.md
+
+Location: `.claude/architecture/INDEX.md`
+
+The INDEX.md is the grep-native registry of all module maps in this repo. Format mirrors
+`vendor/INDEX.md` — one pipe-delimited row per module, designed so `grep <term> INDEX.md`
+produces a readable hit.
+
+### Row Format
+
+```
+| <module> | <depth> | <generated_from_sha_short> | <generated_at_date> | <map_file> |
+```
+
+- `<module>` — the `module` frontmatter value (e.g. `apps/web`)
+- `<depth>` — `skeleton` or `deep`
+- `<generated_from_sha_short>` — first 8 chars of `generated_from_sha`, or `unset` if null
+- `<generated_at_date>` — `YYYY-MM-DD` portion of `generated_at`, or `unset` if null
+- `<map_file>` — relative path from `.claude/architecture/` (e.g. `apps-web.md`)
+
+### Header
+
+```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 |
+|--------|-------|-----|-----------|----------|
+```
+
+Each module map added or updated MUST have a corresponding row upserted in INDEX.md.
+
+---
+
+## graph.md
+
+Location: `.claude/architecture/graph.md`
+
+Adjacency-list representation of cross-module dependency edges. Used for dependency impact
+analysis ("if I change module X, what else might be affected?").
+
+### Format
+
+```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>
+```
+
+**Rules:**
+- One edge per line: `<from> -> <to>` (exact module path values from frontmatter).
+- Edges are directed (A depends on B = A -> B).
+- Edges ARE deduplicated at write time by `/cbp-map-architecture` — each unique `<from> -> <to>` pair appears exactly once in graph.md, regardless of how many map files declare the same dependency.
+- The file is regenerated wholesale by both `/cbp-map-architecture` (full generation) and `/cbp-refresh-arch-map` (drift-scoped refresh) — it is not appended incrementally by the CLI (`arch-map status`/`drift` are read-only).
+- Edges represent first-party `@codebyplan/*` TypeScript workspace package imports only, verified against each module's `package.json`. Runtime/service dependencies (shared schema directories, HTTP calls between apps) are intentionally NOT graphed — consult each module's `## 4. Dependencies (In / Out)` section for runtime coupling.
+
+---
+
+## architecture.json
+
+Location: `.codebyplan/architecture.json`
+
+The committed manifest tracking which modules have been mapped and their freshness state.
+Written by `setup` (empty stub) and `config` (create-if-absent). Updated by
+`codebyplan arch-map stamp`.
+
+### Schema
+
+```json
+{
+  "version": 1,
+  "modules": [
+    {
+      "path": "apps/web",
+      "map_file": ".claude/architecture/apps-web.md",
+      "generated_from_sha": "abc12345def...",
+      "depth": "skeleton",
+      "generated_at": "2026-06-02T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+The TypeScript types for this schema are `ArchitectureConfig` and `ArchitectureModuleEntry`
+in `packages/codebyplan-package/src/lib/types.ts`.

package/templates/context/architecture-map.md

@@ -0,0 +1,117 @@
+---
+scope: org-shared
+---
+
+# Architecture Map Consultation Contract
+
+This file is the **consumer contract** for the `.claude/architecture/` per-module map
+files: what the artifacts are, when to read them, how to parse them, and what to do when
+they are absent. Artifact format spec is in `context/architecture/arch-map-spec.md`.
+
+## What the Architecture Map Is
+
+A committed set of per-module `.md` files under `.claude/architecture/` that record the
+structure, public surface, internal layout, dependencies, conventions, and landmarks of
+each repository module. They are authored by the `cbp-map-architecture` agent and stamped
+by the `codebyplan arch-map stamp` CLI.
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| Per-module map | `.claude/architecture/<module-slug>.md` | Full analysis of one module |
+| Index | `.claude/architecture/INDEX.md` | Grep-friendly registry of all mapped modules |
+| Dependency graph | `.claude/architecture/graph.md` | Cross-module dependency edges (adjacency list) |
+
+**Depth levels** (from the module's `depth:` frontmatter field):
+
+| Level | Sections included | When used |
+|-------|-------------------|-----------|
+| `skeleton` | 1–4, 6–7 (no data-flow traces) | Structural overview, unfamiliar or rarely-changed modules |
+| `deep` | 1–7 including data-flow traces | End-to-end understanding of active modules |
+
+**Slug derivation**: `apps/web` → `apps-web.md`; `.github` → `dot-github.md` (leading dot
+normalized to `dot-` so the map file is never hidden). The manifest `path` keeps the
+leading dot for git drift tracking.
+
+## When To Consult
+
+### cbp-task-planner — Phase 3: Check Rules and Architecture
+
+Before finalizing scope for the target module(s), check whether a map exists:
+
+1. Glob `.claude/architecture/<module-slug>.md` for each module in scope.
+2. If found, read the map file — sections 1–4 + 6–7 give structural context that reduces
+   the need for broad file-system scans; section 5 (deep maps) gives data-flow traces.
+3. Use the `## 4. Dependencies (In / Out)` section to identify cross-module impact that
+   the planner's Explore subagent might otherwise miss.
+
+### cbp-round-executor — Step 2.4: Architecture Map Consultation
+
+Before editing files in a module, check whether a map exists:
+
+1. Glob `.claude/architecture/<module-slug>.md` for the module being edited.
+2. If found, read the relevant sections before making changes — `## 7. Where-Things-Live
+   Landmarks` is the fastest orientation; `## 3. Internal Structure` disambiguates layout.
+3. The map is a pre-computed index — reading it replaces N individual file-reads for the
+   same structural signal.
+
+## How To Read
+
+```bash
+# Check whether a map exists for a module
+Glob: .claude/architecture/<module-slug>.md
+
+# Read the map
+Read: .claude/architecture/<module-slug>.md
+
+# Browse all mapped modules
+Read: .claude/architecture/INDEX.md
+
+# Inspect cross-module dependencies
+Read: .claude/architecture/graph.md
+```
+
+Parse sections per the spec in `context/architecture/arch-map-spec.md`:
+the 7 canonical section headings are `## 1. Boundaries & Responsibility` through
+`## 7. Where-Things-Live Landmarks`. A `skeleton` map omits `## 5. Data-Flow Traces`.
+
+YAML frontmatter fields: `module`, `generated_from_sha`, `depth`, `generated_at`,
+`source_globs`. Check `generated_from_sha` against HEAD if you need to know whether the
+map is stale (or run `codebyplan arch-map drift`).
+
+## If No Map Exists
+
+The map is **not a prerequisite** — its absence is NOT a blocker for planning or execution.
+
+- Proceed with the standard file-system analysis (Explore subagent / Read + Grep).
+- Optionally note in your output that `/cbp-map-architecture --module <path>` would
+  pre-compute structural context for future rounds.
+- Do NOT fail or block solely because a map is missing.
+
+## Agent Consumption Contract
+
+| Agent | Phase / Step | Action |
+|-------|-------------|--------|
+| `cbp-task-planner` | Phase 3 — Check Rules and Architecture | Glob for map; read if present before finalizing scope |
+| `cbp-round-executor` | Step 2.4 — Architecture Map Consultation | Glob for map; read if present before editing files in module |
+
+Both agents follow the same read-or-skip pattern: Glob → if found, Read → use signal;
+if absent, continue without blocking.
+
+## What This File Is NOT
+
+- Not the artifact format spec — that is `context/architecture/arch-map-spec.md`.
+- Not how to generate maps — use `/cbp-map-architecture` (map all/selected modules).
+- Not how to refresh stale maps — use `/cbp-refresh-arch-map` (drift-scoped refresh).
+- Not a substitute for reading the actual source files — the map is a pre-computed index,
+  not a replacement for code inspection when fine-grained detail is needed.
+
+## Related
+
+| Concern | Reference |
+|---------|-----------|
+| Artifact format spec | `context/architecture/arch-map-spec.md` |
+| Generate / regenerate maps | `/cbp-map-architecture` skill |
+| Refresh only drifted modules | `/cbp-refresh-arch-map` skill (TASK-3) |
+| CLI subcommands | `codebyplan arch-map status \| drift \| stamp` |
+| Always-loaded pointer rule | `.claude/rules/architecture-map.md` |
+| Loading rule registration | `.claude/rules/context-file-loading.md` |

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