codebyplan 1.13.38 → 1.13.40

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-merge-main/SKILL.md

@@ -122,10 +122,7 @@ This check is intentionally placed BEFORE Step 2's `git merge`: catching collisi
 
 1. List conflicted files and lock the count: `N=$(git diff --name-only --diff-filter=U | wc -l)`. `N` is the canonical conflict count used by Step 3.5 fallback message and Step 5 output; it stays fixed at the initial value across loop-backs.
 
-2. Load cross-reference context. Via MCP, gather all active CHK/TASK file ownership:
-   - `get_checkpoints(repo_id)` filtered to `status IN ('pending', 'active', 'in_progress')`.
-   - For each active checkpoint, also call `get_tasks(checkpoint_id)` and collect every `task.files_changed[].path` — checkpoint-bound task file ownership lives here, NOT on the checkpoint itself.
-   - `get_tasks(repo_id, standalone: true)` filtered to `status IN ('pending', 'in_progress')` — adds standalone-task file ownership.
+2. Load cross-reference context. Read local state files for per-task file ownership: `.codebyplan/state/checkpoints/<id>.json` (filtered to `status IN ('pending', 'active', 'in_progress')`) and `.codebyplan/state/checkpoints/<id>/tasks/*.json` (collect every `task.files_changed[].path`). On miss run `npx codebyplan sync` once and re-read. Use MCP `get_checkpoints` (active-filter multi-checkpoint scan) / `get_tasks` as documented break-glass when the state dir is absent and sync fails — the full cross-checkpoint scan requires MCP when local state is unavailable.
 
    Build a map `path -> [referencing CHK-NNN TASK-N + brief context]` by matching each conflicted path against:
    - `checkpoint.context.files_to_change[]` (checkpoint-level plan)
@@ -221,7 +218,7 @@ Return control to the caller. **This skill NEVER pushes** — the caller decides
   - `/cbp-task-complete` Step 5.5 (mandatory pre-push, after task commit)
   - `/cbp-checkpoint-end` Step 0 (mandatory pre-shipment)
   - User-invocable manually
-- **Reads**: `.codebyplan/git.json`, MCP `get_checkpoints`, MCP `get_tasks`, git state
+- **Reads**: `.codebyplan/git.json`, local state `.codebyplan/state/checkpoints/<id>.json` + `.../tasks/<id>.json`; on miss `npx codebyplan sync` once; MCP `get_checkpoints` (active-filter multi-checkpoint scan) / MCP `get_tasks` as documented break-glass when the state dir is absent and sync fails (full cross-checkpoint scan). Git state.
 - **Writes**: git merge commit (no MCP writes; no remote push)
 - **Spawns**: none (`/cbp-git-commit` is inline-triggered at Step 0 dirty-tree handling)
 - **Network**: contacts `origin` via `git fetch`. Offline = abort.

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-round-check/SKILL.md

@@ -15,14 +15,14 @@ Inspect the resolved identifier from argument parsing to determine the task kind
 |-----------------|------|
 | `{task}-{round}` (2-segment, e.g. `45-2`) | `standalone` |
 | `{chk}-{task}-{round}` (3-segment, e.g. `141-3-1`) | `checkpoint` |
-| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. (Kind-detection is MCP-unavoidable — no identifier yet means no local path to probe; subsequent operations are local-first per the rows below.) |
 
 Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
+| Get task | local state (break-glass: `get_current_task`) | `get_current_standalone_task(repo_id)` |
+| Get rounds | local state (break-glass: `get_rounds`) | `get_standalone_rounds(standalone_task_id)` |
 | Add round | `add_round(task_id, ...)` | `add_standalone_round(standalone_task_id, ...)` |
 | Update round | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
 | Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?, caller_worktree_id)` ⚠️ `caller_worktree_id` is REQUIRED for standalone |
@@ -38,8 +38,8 @@ Run automated checks independently with mandatory execution. Updates round QA. H
 
 Use Kind Detection above to set KIND. Then:
 
-- **checkpoint KIND**: MCP `get_current_task(repo_id)` to find active task, then `get_rounds(task_id)` to find the in-progress round.
-- **standalone KIND**: MCP `get_current_standalone_task(repo_id)` to find active task, then `get_standalone_rounds(standalone_task_id)` to find the in-progress round.
+- **checkpoint KIND**: Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first) to find active task, then read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` to find the in-progress round. If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task(repo_id)` + `get_rounds(task_id)` when state dir is absent and sync fails.
+- **standalone KIND**: MCP `get_current_standalone_task(repo_id)` to find active task, then `get_standalone_rounds(standalone_task_id)` to find the in-progress round. (Standalone KIND still uses MCP until a later task.)
 
 ### Step 2: Determine Project Root
 
@@ -83,7 +83,9 @@ Scan all captured output for:
 
 ### Step 6: Save QA Results
 
-Update round QA via MCP `update_round(round_id, qa: ...)` (checkpoint KIND) or `update_standalone_round(standalone_round_id, qa: ...)` (standalone KIND):
+Update round QA:
+- **checkpoint KIND**: `codebyplan round update --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id> --qa '<json>'` (CLI write-through: local state file + REST). Break-glass fallback: MCP `update_round(round_id, qa: ...)` when the CLI is unavailable.
+- **standalone KIND**: MCP `update_standalone_round(standalone_round_id, qa: ...)`. (Standalone KIND still uses MCP until a later task.)
 
 ```json
 {
@@ -123,6 +125,8 @@ If soft failures only: `Run /cbp-round-start to trigger auto-fix, or fix manuall
 
 ## Integration
 
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND)
-- **Writes**: MCP `update_round` / `update_standalone_round` (qa field) — per KIND
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; run `npx codebyplan sync` if missing; break-glass: MCP `get_current_task` / `get_rounds`)
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task` / `get_standalone_rounds` (standalone KIND still uses MCP until a later task)
+- **Writes (checkpoint KIND)**: `codebyplan round update` (qa field). Break-glass: MCP `update_round`.
+- **Writes (standalone KIND)**: MCP `update_standalone_round` (qa field). (Standalone KIND still uses MCP until a later task.)
 - **Standalone**: Can be run independently at any time

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

@@ -15,14 +15,14 @@ Inspect the resolved identifier from argument parsing to determine the task kind
 |-----------------|------|
 | `{task}-{round}` (2-segment, e.g. `45-2`) | `standalone` |
 | `{chk}-{task}-{round}` (3-segment, e.g. `141-3-1`) | `checkpoint` |
-| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. (Kind-detection is MCP-unavoidable — no identifier yet means no local path to probe; subsequent operations are local-first per the rows below.) |
 
 Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
+| Get task | local state (break-glass: `get_current_task`) | `get_current_standalone_task(repo_id)` |
+| Get rounds | local state (break-glass: `get_rounds`) | `get_standalone_rounds(standalone_task_id)` |
 | Update round | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
 | Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?, caller_worktree_id)` ⚠️ `caller_worktree_id` is REQUIRED for standalone |
 
@@ -69,9 +69,9 @@ Given the parse from Step 1:
 
 | Parse | Resolution path |
 |-------|-----------------|
-| `{chk}-{task}-{round}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}`. MCP `get_tasks(checkpoint_id)` → filter `number === {task}`. MCP `get_rounds(task_id)` → filter `number === {round}`. |
-| `{task}-{round}` | MCP `get_standalone_rounds` via `get_current_standalone_task` or direct task lookup → filter `number === {round}`. |
-| _(empty)_ | Use Kind Detection: checkpoint KIND → MCP `get_current_task(repo_id)` + `get_rounds(task_id)`; standalone KIND → MCP `get_current_standalone_task(repo_id)` + `get_standalone_rounds(standalone_task_id)`. |
+| `{chk}-{task}-{round}` | **checkpoint KIND** — Read `.codebyplan/state/checkpoints/<checkpointId>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_checkpoints(repo_id)` → `get_tasks` → `get_rounds` when state dir is absent and sync fails. Filter by `number` fields to match `{chk}`, `{task}`, `{round}`. |
+| `{task}-{round}` | **standalone KIND** — MCP `get_standalone_rounds` via `get_current_standalone_task` or direct task lookup → filter `number === {round}`. (Standalone KIND still uses MCP until a later task.) |
+| _(empty)_ | Use Kind Detection: **checkpoint KIND** → Read `.codebyplan/state/` local files for active task + latest round (break-glass: MCP `get_current_task(repo_id)` + `get_rounds(task_id)`); **standalone KIND** → MCP `get_current_standalone_task(repo_id)` + `get_standalone_rounds(standalone_task_id)`. |
 
 If no task found: `No active task. Nothing to complete.`
 
@@ -108,7 +108,7 @@ This is the **single** explicit reconcile owned by this skill. (The `cbp-mcp-rou
 
 Calculate duration from the round's `started_at` to now in minutes.
 
-- **checkpoint KIND**: MCP `complete_round(round_id, duration_minutes)`.
+- **checkpoint KIND**: `codebyplan round complete --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id>` (CLI write-through: local state file + REST). Break-glass fallback: MCP `complete_round(round_id, duration_minutes)` when the CLI is unavailable. Note: the CLI does not accept `duration_minutes`; the backend computes duration server-side.
 - **standalone KIND**: MCP `complete_standalone_round(standalone_round_id, duration_minutes, caller_worktree_id)`. ⚠️ `caller_worktree_id` is REQUIRED — resolve via `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`. If `CALLER_WT` is empty, surface this warning and ask the user to confirm before proceeding:
 
   ```
@@ -145,7 +145,11 @@ Calculate duration from the round's `started_at` to now in minutes.
     another round.
     ```
 
-Persist a breadcrumb on the round via `update_round` / `update_standalone_round` per KIND: `round.context.round_complete = { staged_count, unstaged_count, route, decided_at }`.
+Persist a breadcrumb on the round:
+- **checkpoint KIND**: `codebyplan round update --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id> --context '<json>'` (CLI write-through). Break-glass fallback: MCP `update_round(round_id, ...)` when the CLI is unavailable.
+- **standalone KIND**: MCP `update_standalone_round(standalone_round_id, ...)` (standalone KIND still uses MCP until a later task).
+
+Payload: `round.context.round_complete = { staged_count, unstaged_count, route, decided_at }`.
 
 ## Key Rules
 
@@ -159,6 +163,8 @@ Persist a breadcrumb on the round via `update_round` / `update_standalone_round`
 
 - **Gates**: `ask`-tier `Skill(cbp-round-complete)` permission prompt — the harness confirms before the skill runs; a decline makes NO writes. There is no in-skill AskUserQuestion.
 - **Triggered by**: `/cbp-round-update` (auto, clean triage), or user manually
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND); delegates git+approval sync to `npx codebyplan round sync-approvals`
-- **Writes**: MCP `complete_round` / `complete_standalone_round` (per KIND); `update_round` / `update_standalone_round` (`round_complete` breadcrumb); round+task `files_changed` written by the CLI
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `.codebyplan/state/checkpoints/<id>/tasks/<id>.json`, `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; run `npx codebyplan sync` if missing; break-glass: MCP `get_current_task` / `get_rounds`). Delegates git+approval sync to `npx codebyplan round sync-approvals`.
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task` / `get_standalone_rounds` (standalone KIND still uses MCP until a later task).
+- **Writes (checkpoint KIND)**: `codebyplan round complete` (Step 3); `codebyplan round update` (Step 4 breadcrumb). Break-glass: MCP `complete_round` / `update_round`. Round+task `files_changed` written by the CLI sync-approvals.
+- **Writes (standalone KIND)**: MCP `complete_standalone_round` / `update_standalone_round` (standalone KIND still uses MCP until a later task).
 - **Triggers**: `/cbp-task-check` (checkpoint KIND, all files approved), `/cbp-standalone-task-check` (standalone KIND, all files approved), `/cbp-round-input` (some files unapproved — fires independent of staging count)

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

@@ -27,8 +27,9 @@ This skill operates on the **active** task/round resolved via MCP `get_current_t
 
 ### Step 1: Get Current Task and Round
 
-Use MCP `get_current_task` with repo_id (pass `checkpoint_id` if known to avoid disambiguation) to find the active task.
-Use MCP `get_rounds` for the task to find the in-progress round.
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first) to find the active task. If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task` when the state dir is absent and sync fails (daemon-dead + CLI-unavailable).
+
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` (local-first) to find the in-progress round. Same sync / break-glass pattern (MCP `get_rounds` as fallback).
 
 Load round context with all outputs (executor_output, testing_qa_output, reviewer_output).
 
@@ -70,11 +71,9 @@ Merge with previous rounds (supersede items for re-modified files, preserve veri
 
 ### Step 4: Update Task Files and QA
 
-Update via MCP:
-
-- `update_task(task_id, files_changed: [...])` — merge with existing
-- `update_round(round_id, files_changed: [...], qa: {items: [auto_qa items + default_checklist items]})` — round-specific
-- `update_task(task_id, qa: {items: [auto_qa items + default_checklist items]})` — aggregated
+- **Round files + QA**: `codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --files-changed <json> --qa <json>` (CLI write-through: local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` + REST). Break-glass fallback: MCP `update_round` when the CLI is unavailable.
+- **Task files_changed merge**: `codebyplan task update --id <task-id> --checkpoint-id <uuid> --files-changed <json>` (CLI write-through: local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` + REST). Break-glass fallback: MCP `update_task` when the CLI is unavailable.
+- **Task QA aggregated**: `codebyplan task update --id <task-id> --checkpoint-id <uuid> --qa <json>` (same CLI write-through). Break-glass: MCP `update_task`.
 
 ### Step 5: Present Summary
 
@@ -149,7 +148,7 @@ Example tables and the in-scope/out-of-scope classification: see `reference/find
 Step 7 already auto-applied in-scope findings and logged them to `round.context.inline_fix_log`. Now record any out-of-scope findings and route:
 
 1. **Polish-spiral stop-gate** (round 2+ only): if this is round 2 or later AND the prior round also ended with code-review fixes, surface a one-line stop-gate via AskUserQuestion — *defer remaining polish to a follow-up task* vs *continue with another round*. This is a genuine user decision about scope (it guards against endless low-value polish loops), not a flow-control prompt. Skip on round 1.
-2. Save out-of-scope findings (those NOT auto-applied in Step 7) to round context via MCP `update_round`:
+2. Save out-of-scope findings (those NOT auto-applied in Step 7) to round context via `codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --context <json>` (break-glass: MCP `update_round`):
    ```json
    {
      "context": {
@@ -169,7 +168,7 @@ Step 7 already auto-applied in-scope findings and logged them to `round.context.
 ## Integration
 
 - **Triggered by**: `/cbp-round-execute` (auto, after all waves + testing complete)
-- **Reads**: MCP `get_current_task`, `get_rounds`, round context
-- **Writes**: MCP `update_round`, `update_task` (files_changed, qa, findings)
+- **Reads**: `.codebyplan/state/checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task` / `get_rounds` as break-glass)
+- **Writes**: `codebyplan round update` (Step 4 round files/QA, Step 8 findings; break-glass: MCP `update_round`), `codebyplan task update` (Step 4 files_changed + QA aggregated; break-glass: MCP `update_task`)
 - **Spawns**: `cbp-improve-round` (code quality review)
 - **Triggers**: `/cbp-round-update` (auto, after findings handled)

package/templates/skills/cbp-round-execute/SKILL.md

@@ -27,8 +27,9 @@ This skill operates on the **active** task/round resolved via MCP `get_current_t
 
 ### Step 1: Get Current Task and Round
 
-Use MCP `get_current_task` with repo_id (pass checkpoint_id if known) to find the active task.
-Use MCP `get_rounds` for the task to find the in-progress round.
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first) to find the active task. If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task` when the state dir is absent and sync fails (daemon-dead + CLI-unavailable).
+
+Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` (local-first) to find the in-progress round. Same sync / break-glass pattern (MCP `get_rounds` as fallback).
 
 If no in-progress round: `No active round. Run /cbp-round-start first.`
 
@@ -182,7 +183,7 @@ Per-wave hard-fail signal — true when ANY hold:
 **All waves hard_fail: false** → proceed to Step 7. **Any wave hard_fail: true**:
 
 - **Simple fixes** (type errors, lint, missing imports, test assertion fixes, e2e `real`-category with clear code-side root cause, no prior re-trigger this round) → save failure details to round context; retrigger the failing wave's executor; re-run testing-qa AND the eligible `cbp-e2e-*` specialists for that wave.
-- **Structural OR already re-triggered once OR e2e preflight aborts OR `e2e_eligible_skipped`** → save failure context via MCP `update_round`; auto-trigger `/cbp-round-input`. STOP.
+- **Structural OR already re-triggered once OR e2e preflight aborts OR `e2e_eligible_skipped`** → save failure context via `codebyplan round update` (break-glass: MCP `update_round`); auto-trigger `/cbp-round-input`. STOP.
 
 ## Inline execution fallback
 
@@ -194,7 +195,7 @@ When `cbp-testing-qa-agent` spawn fails OR the resolved `testing_profile` is `cl
 
 ### Step 7: Save Executor Output
 
-Update round context via MCP `update_round`:
+`codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --context <json>` (CLI write-through: local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` + REST). Break-glass fallback: MCP `update_round` when the CLI is unavailable.
 
 - `context`: { ...existing, executor_output, testing_qa_output, e2e_eligible, e2e_outputs, frontend_ui_review }
 
@@ -220,8 +221,8 @@ Trigger `/cbp-round-end`.
 
 ## Integration
 
-- **Reads**: MCP `get_current_task`, `get_rounds`
-- **Writes**: MCP `update_round` (context with executor_output + testing_qa_output + e2e_eligible + e2e_outputs + frontend_ui_review)
+- **Reads**: `.codebyplan/state/checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task` / `get_rounds` as break-glass)
+- **Writes**: `codebyplan round update --id <uuid> --task-id <uuid> --checkpoint-id <uuid>` (Steps 6+7 — context with executor_output + testing_qa_output + e2e_eligible + e2e_outputs + frontend_ui_review; break-glass: MCP `update_round`)
 - **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of the `cbp-e2e-*` specialists), the `cbp-e2e-*` specialists (config-driven dispatch per `context/testing/e2e.md`, one per eligible framework in `.codebyplan/e2e.json`), `cbp-database-agent` (if DB work), `cbp-security-agent` (if security review needed)
 - **Skill invocations**: `cbp-frontend-ui` at Step 5b with `phase: 'screenshot_review'` (post-e2e)
 - **Triggers**: `/cbp-round-end` (auto)