codebyplan 1.5.1 → 1.8.0

package/templates/hooks/README.md

@@ -0,0 +1,236 @@
+# Hooks
+
+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 Notification events are wired. (`SessionStart`, `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.
+
+---
+
+## Hooks included
+
+### `cbp-statusline.sh` — auto-registered via `settings.project.base.json`
+
+Renders up to 6 structured lines below Claude Code's prompt area. Reads JSON from stdin (Claude Code's `statusLine` stream) and emits ANSI-coloured output. All fields from the Claude Code `statusLine` schema are parsed in a single `jq` invocation.
+
+**Render lines:**
+
+- **Line 1 — Identity**: single prefix (`wt:NAME` / `session:NAME` / `agent:NAME`, priority order); model display name and id; `effort:LEVEL` (when set); `thinking:on` (only when thinking is enabled); `style:NAME` (when output style is not "default"); `v:VERSION`; `[VIM_MODE]`
+- **Line 2 — Context**: 20-character progress bar (green / yellow / red at 50% / 75%); `used% / ctx_size`; per-call token breakdown — `in:N out:N cache_cr:N cache_rd:N` (from `context_window.current_usage`); `⚠ 200k+` banner when `exceeds_200k_tokens` is true
+- **Line 3 — Cost**: session cost in USD; total wall duration (`dur:`) and API-only duration (`api:`) via human-readable format; lines added/removed
+- **Line 4 — Rate limits**: `5h: PCT% (resets in Xh)` and `7d: PCT% (resets in Xd)` with relative-time helper; colour-coded green / yellow / red at 60% / 80%; emitted only when at least one window has a non-zero `resets_at` epoch
+- **Line 5 — Repo / PR**: `host/owner/name` (from `workspace.repo`); `PR #N <review_state> <url>` (when `pr.number` is present); emitted when at least one segment is present
+- **Line 6 — Worktree**: `name @ branch (was: original_branch)` and truncated path; emitted only when `worktree.name` is present
+
+**Env-var toggles** — set any to `1` to suppress that section:
+
+| Variable | Suppresses |
+|---|---|
+| `CBP_STATUSLINE_HIDE_IDENTITY` | Line 1 — model / session / agent identity |
+| `CBP_STATUSLINE_HIDE_CONTEXT` | Line 2 — context bar, token breakdown |
+| `CBP_STATUSLINE_HIDE_COST` | Line 3 — cost, duration, lines changed |
+| `CBP_STATUSLINE_HIDE_RATE_LIMITS` | Line 4 — 5h / 7d rate-limit windows |
+| `CBP_STATUSLINE_HIDE_REPO_PR` | Line 5 — repo identity and PR |
+| `CBP_STATUSLINE_HIDE_WORKTREE` | Line 6 — worktree name / branch / path |
+| `CBP_STATUSLINE_NO_COLOR` | Strip all ANSI colour codes (also honoured by `$NO_COLOR`) |
+
+**Sample invocation** (pipe mock JSON, run from the hooks directory; `NO_COLOR=1` shown so the comment-output below matches verbatim without ANSI codes):
+
+```bash
+echo '{"model":{"display_name":"Opus","id":"claude-opus-4"},"context_window":{"used_percentage":25,"context_window_size":200000,"current_usage":{"input_tokens":50000,"output_tokens":1000,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}}' \
+  | NO_COLOR=1 bash cbp-statusline.sh
+# Opus (claude-opus-4)
+# ▓▓▓▓▓░░░░░░░░░░░░░░░ 25%/200.0K in:50.0K out:1.0K cache_cr:0 cache_rd:0
+# $0.0000 dur:0s api:0s +0 -0 lines
+```
+
+Pure renderer — no project state read, no commands run. Works on any host.
+
+**Blocks vs warns**: neither — it only renders. Cannot fail your workflow.
+
+**Opt out**: set `CBP_STATUSLINE_HIDE_*` env vars to suppress individual sections, or remove the `statusLine` block from your `.claude/settings.json`.
+
+---
+
+### `maestro-yaml-validate.sh` — PreToolUse, matcher `Edit|Write|MultiEdit`
+
+Validates [Maestro](https://maestro.mobile.dev) flow YAML files (`*/maestro/flows/*.yaml`, `*/maestro/flows/*.yml`) at edit time, against the property allowlist of your locally installed `maestro` CLI version. Catches properties the CLI will reject at flow-run time so you find out at edit time, not after `maestro test` fails.
+
+**Blocks vs warns**: blocks (exit 2) when the edited content uses a known-rejected property under a known command (e.g., `timeout` under `assertVisible` in maestro 1.x / 2.x).
+
+**Skips when**: the file isn't under `*/maestro/flows/`; or `maestro` isn't on `$PATH` (no enforcement, no failure).
+
+**Maintain**: when maestro upgrades, re-validate the `KNOWN_REJECTED` array against [maestro.mobile.dev/api-reference/commands](https://maestro.mobile.dev/api-reference/commands).
+
+**Opt out**: disable the plugin's hooks via your settings.json `hooks{}` block override, or disable the plugin entirely.
+
+---
+
+### `test-coverage-gate.sh` — PreToolUse, matcher `Bash` (git commit)
+
+When you run `git commit`, this hook scans newly-added (`--diff-filter=A`) `.ts` / `.tsx` / `.js` / `.jsx` files and blocks the commit if any source file lacks a sibling test companion.
+
+Recognised test conventions:
+
+| Convention                 | Example                            |
+| -------------------------- | ---------------------------------- |
+| Sibling                    | `foo.ts` ↔ `foo.test.ts`           |
+| Sibling spec               | `foo.ts` ↔ `foo.spec.ts`           |
+| Co-located                 | `foo.ts` ↔ `__tests__/foo.test.ts` |
+| Test staged in same commit | `foo.ts` + `foo.test.ts` both new  |
+
+**Skipped automatically**: test files themselves; `index.ts` / `index.tsx` barrel exports; `*.d.ts` / `types.ts` / files under `types/`; files under `.claude/`, `docs/`, `supabase/`; `*.config.*`, `*.json`, `*.md`, `*.yaml`, `*.sh`, `*.scss`, `*.css`. (These are skip-only patterns — harmless when your repo doesn't have them.)
+
+**Blocks vs warns**: blocks (exit 2) when source files lack tests. Stderr names every offending file and the expected test paths.
+
+**Modified files** with no tests are NOT blocked — only newly-added ones. Pre-existing gaps surface via your test-coverage tooling instead.
+
+**Opt out**: don't ship a hook override; structure your tests to one of the recognised conventions; or for a one-off, `git commit --no-verify` (host-level bypass — use sparingly).
+
+---
+
+### `pre-commit-quality-gate.sh` — PreToolUse, matcher `Bash` (git commit)
+
+Three gates fired during `git commit`. Each scans the staged diff and blocks the commit if its gate fails.
+
+**Gate 3 — Greenfield ESLint configs ship clean.** When a newly-added `eslint.config.{mjs,js,cjs,ts}` is staged, the hook walks up to the owning `package.json`, runs `./node_modules/.bin/eslint .` in that package, and blocks if any warning or error is reported. Enforces the convention that brand-new ESLint configs land at zero warnings.
+
+**Gate 4 — No skip-only test files.** When a newly-added `*.{test,spec}.{ts,tsx,js,jsx}` is staged, the hook counts `describe(`, `it(`, `test(` declarations vs `.skip(` / `.todo(` declarations. If a file has only skipped / todo tests and no live tests, the commit is blocked. Prevents skip-only masquerading that satisfies `test-coverage-gate.sh` while testing nothing.
+
+**Gate 5 — TypeScript compiles in owning package.** _Opt-in only._ Set `CBP_PRECOMMIT_TYPECHECK=1` in your shell to enable. Groups staged `.ts` / `.tsx` files by owning `package.json`, runs `tsc --noEmit -p <pkg>/tsconfig.json` per package, and blocks if any package fails. Off by default because typecheck can take 30–60s on large packages — enable in CI or before shipping.
+
+**Blocks vs warns**: all three gates block (exit 2). Stderr names the failing gate, the file, and the exact local command to reproduce.
+
+**Skipped automatically**: any gate skips silently when its required binary (`eslint`, `tsc`) is missing.
+
+**Opt out**: same as test-coverage-gate — restructure to satisfy the gate, override the hook in your settings, or use `--no-verify` sparingly. Disable Gate 5 simply by not setting `CBP_PRECOMMIT_TYPECHECK`.
+
+---
+
+### `lint-format-on-edit.sh` — PostToolUse, matcher `Edit|Write`
+
+After every Edit or Write, formats the changed file with Prettier and runs ESLint `--fix` against it. Auto-fixable issues are applied silently; remaining ESLint errors are surfaced to stderr so Claude sees them inline on the next iteration.
+
+Walks up from the edited file to the nearest `package.json` and uses that package's local `node_modules/.bin/prettier` and `node_modules/.bin/eslint`. Falls back to the repo root's binaries if a package-local copy isn't present.
+
+**File-type gate**:
+
+| Extensions                                            | Format | Lint   |
+| ----------------------------------------------------- | ------ | ------ |
+| `.ts` `.tsx` `.js` `.jsx` `.mjs` `.mts` `.cjs` `.cts` | yes    | yes    |
+| `.scss` `.css` `.json` `.md` `.yml` `.yaml`           | yes    | no     |
+| anything else                                         | exit 0 | exit 0 |
+
+**Skipped paths**: `node_modules/`, `.next/`, `dist/`, `build/`, `.git/`, `coverage/`, `.turbo/`.
+
+**Blocks vs warns**: never blocks — exit 0 always. Errors are stderr-only so Claude can act on them in-loop.
+
+**ESLint config-load failures** (exit 2 from eslint, e.g. preset collision, missing plugin) trigger a one-time loud banner per package per session. Subsequent edits in the same broken package emit a quiet one-line reminder. The marker file lives under `${TMPDIR}/cbp-lint-config-fail/` and clears between sessions.
+
+**Requires `${CLAUDE_PROJECT_DIR}` env var** — Claude Code provides this. If unset (older host or unusual launch), the hook exits 0 silently as a no-op.
+
+**Opt out**: same patterns as the gate hooks — settings.json override or plugin disable.
+
+---
+
+### `notify.sh` — Notification, matcher `*`
+
+Sends a desktop notification when Claude Code emits a notification event (waiting for input, task complete, etc.). Title is `[<project-name>] Claude Code`; body is the notification message; clicking the notification focuses VS Code at the project directory (macOS only).
+
+**Cross-platform graceful skip**: exits 0 silently when `terminal-notifier` is not on `$PATH`. Linux, Windows, and macOS hosts without Homebrew see a no-op — no errors, no warnings.
+
+**VS Code click action**: only attached when running on macOS (`$OSTYPE` matches `darwin*`) AND the `code` CLI is on `$PATH`. On other hosts the notification still fires but is non-clickable.
+
+**Install hint** (macOS): `brew install terminal-notifier`. On other platforms the hook is a no-op — substitute your own notification mechanism via a settings.json override if desired.
+
+**Blocks vs warns**: never blocks — exit 0 always. Notification hooks must never block Claude.
+
+**Opt out**: settings.json override or plugin disable.
+
+---
+
+### `auto-test-hooks.sh` — PostToolUse, matcher `Edit|Write`
+
+Triggers `test-hooks.sh` automatically when any `*/hooks/*.sh` file is edited. Catches accidental breakage of the plugin's own hooks (or your project's `.claude/hooks/` if you author your own) at edit time, before the broken hook runs against future tool calls.
+
+Recursion-guarded: edits to `test-hooks.sh` and `auto-test-hooks.sh` themselves don't re-trigger the suite.
+
+**Blocks vs warns**: blocks (exit 1) when `test-hooks.sh` reports any failure. Stderr names which check failed.
+
+**Skips when**: the edited file isn't under a `*/hooks/` path; or the file is `test-hooks.sh` / `auto-test-hooks.sh` itself.
+
+**Opt out**: settings.json override removing this entry. The associated `test-hooks.sh` can still be run manually via `bash ${CLAUDE_PLUGIN_ROOT}/hooks/test-hooks.sh`.
+
+### `cbp-mcp-migration-guard.sh` — PreToolUse, matcher `mcp__codebyplan__(update_task|complete_task|update_checkpoint|create_checkpoint|create_task)`
+
+Warns once per session when a legacy `.codebyplan.json` file still exists at the repo root — the pre-CHK-120 single-file config that has since been partitioned into the `.codebyplan/` directory. Fires on CodeByPlan MCP mutation tools so the reminder surfaces during normal planning work.
+
+**Blocks vs warns**: never blocks — exits 0 on every path, so the MCP call always proceeds. Advisory only.
+
+**Skips when**: no legacy `.codebyplan.json` is present at the repo root; or the reminder has already been emitted once this session.
+
+**Opt out**: settings.json override removing this entry.
+
+---
+
+### `validate-git-stash-deny.sh` — PreToolUse, matcher `Bash`
+
+Denies any `git stash` command (including `git -C <dir> stash` and `git stash pop/apply`). Git stash is banned because it hides work-in-progress in a place that's easy to lose; the hook points you to safe alternatives (`git diff <ref>`, `git show <ref>:<path>`, `git worktree add`).
+
+**Blocks vs warns**: blocks (exit 2) when the `Bash` command contains a `git stash` invocation. Stderr names the alternatives.
+
+**Skips when**: the command is any non-`git-stash` Bash call (exit 0).
+
+**Opt out**: settings.json override removing this entry, or plugin disable.
+
+---
+
+### `cbp-mcp-worktree-inject.sh` — PreToolUse, matcher `mcp__codebyplan__(update_task|complete_task|complete_round|update_checkpoint)`
+
+Auto-injects `caller_worktree_id` into CodeByPlan MCP mutation calls when it's missing, resolving it via `npx codebyplan resolve-worktree` (with `--fallback-from-branch`). Closes the manual worktree-pinning workaround so MCP writes pass the server-side worktree pre-guard without hand-editing every call.
+
+**Blocks vs warns**: neither — emits an `updatedInput` to add the field when resolvable, otherwise passes the call through unchanged (graceful passthrough preserves backwards-compat).
+
+**Skips when**: the call already carries `caller_worktree_id`, or no worktree can be resolved (both → clean passthrough). A no-op in repos that don't use the CodeByPlan MCP.
+
+**Opt out**: settings.json override removing this entry, or plugin disable.
+
+---
+
+### `cbp-mcp-round-sync.sh` — PostToolUse, matcher `mcp__codebyplan__complete_round`
+
+After a `complete_round` MCP call succeeds, reconciles the round's `files_changed[]` against `git status`: new files in the diff are added (unapproved), and approval records no longer in the diff are flagged `removed_from_diff` (never deleted — lifecycle preserved).
+
+**Blocks vs warns**: never blocks — exit 0 always. A PostToolUse sync hook must never abort Claude.
+
+**Skips when**: the CodeByPlan CLI/API isn't reachable, or there's nothing to reconcile (clean exit 0). A no-op in repos that don't use the CodeByPlan MCP.
+
+**Opt out**: settings.json override removing this entry, or plugin disable.
+
+---
+
+## Supporting (not registered)
+
+### `test-hooks.sh` — invoked by `auto-test-hooks.sh`
+
+Test suite for the plugin's 10 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`, `notify`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-worktree-inject`, `cbp-mcp-round-sync`) 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`.
+
+---
+
+## Hooks NOT included and why
+
+The CodeByPlan repo ships a larger hook set internally; the following are intentionally **not** in this plugin because they encode CodeByPlan-specific authoring conventions, hardcoded identities, or environment assumptions that don't generalise to plugin consumers:
+
+| Hook                                                                                                     | Why dropped                                                                                                                                                                                                                                                                |
+| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `validate-structure.sh` + `validate-structure-{lib,patterns,templates,scope,lengths,smoke}.sh` (7 files) | Tightly coupled to CodeByPlan's `.claude/` layout conventions (kebab-case, scope markers, `/cbp-*` slash-command notation, research phase 1-8 layout). REPO_ROOT walks up from the script location; in plugin layout that resolves to plugin root, not the user's project. |
+| `validate-context-usage.sh`                                                                              | Same family as validate-structure — enforces CodeByPlan's `context/` referencing conventions.                                                                                                                                                                              |
+| `validate-git-commit.sh`                                                                                 | Hardcodes `midevyou <midevyosauhing@gmail.com>` as the only allowed commit author. Would block every plugin user's commits.                                                                                                                                                |
+
+If you need any of these for your own workflow, copy the source from the [CodeByPlan repo](https://github.com/midevyou/codebyplan) under `.claude/hooks/` and adapt to your environment.

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

@@ -0,0 +1,44 @@
+#!/bin/bash
+# @hook: PostToolUse Edit|Write
+# Hook: PostToolUse for Edit|Write on hook files
+# Purpose: Run test-hooks.sh when a plugin hook file is modified.
+#
+# Exit 0 = tests pass (or not a hook file)
+# Exit 1 = tests failed (blocks the edit)
+
+set -e
+
+HOOKS_DIR="$(dirname "$0")"
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only act on hook files under /.claude/hooks/; avoids matching node_modules/*/hooks/
+if echo "$FILE_PATH" | grep -qE '/\.claude/hooks/[^/]+\.sh$'; then
+  BASENAME=$(basename "$FILE_PATH")
+  case "$BASENAME" in
+    test-hooks.sh|auto-test-hooks.sh)
+      exit 0
+      ;;
+  esac
+
+  echo ""
+  echo "Hook file modified: $FILE_PATH"
+  echo "Running automated hook tests..."
+
+  if bash "$HOOKS_DIR/test-hooks.sh"; then
+    echo "All hook tests passed."
+    exit 0
+  else
+    echo ""
+    echo "HOOK TESTS FAILED!"
+    echo "The hook modification broke existing functionality."
+    exit 1
+  fi
+fi
+
+exit 0

package/templates/hooks/cbp-lint-format-on-edit.sh

@@ -0,0 +1,159 @@
+#!/bin/bash
+# @hook: PostToolUse Edit|Write
+# Hook: Auto-format and auto-fix lint on edited source files
+# Purpose: Continuous Prettier + ESLint --fix after every Edit/Write.
+#          Auto-fixable issues get fixed silently; remaining ESLint errors
+#          are piped to stderr so Claude sees them inline.
+#
+# Exit 0 = always (non-blocking; errors shown via stderr, not an Edit block)
+#
+# Performance: uses --cache, direct binary paths (no pnpm-exec startup cost).
+# First edit per package: ~1-3s. Subsequent edits on same package: <500ms.
+
+set -e
+
+# Use Claude Code's project-dir env var as REPO_ROOT.
+# When unset (rare — older host or unusual launch), exit silently as a no-op.
+REPO_ROOT="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+# Read JSON input from stdin
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
+
+# No path / file gone → silent exit
+[ -z "$FILE_PATH" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+# ── File-type gate ───────────────────────────────────────────────────────
+case "$FILE_PATH" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.mts|*.cjs|*.cts)
+    LINT_ENABLED=1
+    FORMAT_ENABLED=1
+    ;;
+  *.scss|*.css|*.json|*.md|*.yml|*.yaml)
+    LINT_ENABLED=0
+    FORMAT_ENABLED=1
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# ── Skip ignored directories ─────────────────────────────────────────────
+case "$FILE_PATH" in
+  */node_modules/*|*/.next/*|*/dist/*|*/build/*|*/.git/*|*/coverage/*|*/.turbo/*)
+    exit 0
+    ;;
+esac
+
+# ── Skip templates directory (prevents one-direction Prettier drift) ─────
+case "$FILE_PATH" in
+  */packages/codebyplan-package/templates/*.md)
+    exit 0
+    ;;
+esac
+
+# ── Find owning workspace package (walk up from file) ────────────────────
+PKG_DIR="$(dirname "$FILE_PATH")"
+while [ "$PKG_DIR" != "$REPO_ROOT" ] && [ "$PKG_DIR" != "/" ] && [ -n "$PKG_DIR" ]; do
+  if [ -f "$PKG_DIR/package.json" ]; then
+    break
+  fi
+  PKG_DIR="$(dirname "$PKG_DIR")"
+done
+[ -f "$PKG_DIR/package.json" ] || PKG_DIR="$REPO_ROOT"
+
+# ── Prettier: format first (fast, idempotent) ────────────────────────────
+if [ "$FORMAT_ENABLED" = "1" ]; then
+  PRETTIER_BIN=""
+  if [ -x "$PKG_DIR/node_modules/.bin/prettier" ]; then
+    PRETTIER_BIN="$PKG_DIR/node_modules/.bin/prettier"
+  elif [ -x "$REPO_ROOT/node_modules/.bin/prettier" ]; then
+    PRETTIER_BIN="$REPO_ROOT/node_modules/.bin/prettier"
+  fi
+  if [ -n "$PRETTIER_BIN" ]; then
+    (cd "$PKG_DIR" && "$PRETTIER_BIN" --write --log-level=error "$FILE_PATH" >/dev/null 2>&1) || true
+  fi
+fi
+
+# ── ESLint --fix + report remaining ──────────────────────────────────────
+if [ "$LINT_ENABLED" = "1" ]; then
+  # Only run if the package has an ESLint flat config
+  ESLINT_CONFIG=""
+  for name in eslint.config.mjs eslint.config.js eslint.config.cjs eslint.config.ts; do
+    if [ -f "$PKG_DIR/$name" ]; then
+      ESLINT_CONFIG="$PKG_DIR/$name"
+      break
+    fi
+  done
+
+  if [ -n "$ESLINT_CONFIG" ]; then
+    ESLINT_BIN=""
+    if [ -x "$PKG_DIR/node_modules/.bin/eslint" ]; then
+      ESLINT_BIN="$PKG_DIR/node_modules/.bin/eslint"
+    elif [ -x "$REPO_ROOT/node_modules/.bin/eslint" ]; then
+      ESLINT_BIN="$REPO_ROOT/node_modules/.bin/eslint"
+    fi
+
+    if [ -n "$ESLINT_BIN" ]; then
+      # --fix writes auto-fixable changes AND outputs remaining issues.
+      # ESLint exit codes:
+      #   0 = clean (no errors, no warnings, or only auto-fixed)
+      #   1 = lint errors / warnings remain after --fix (per-file diagnostics)
+      #   2 = config-load failure (preset collision, missing plugin, ESM/CJS resolution, etc.)
+      # Capture exit code distinctly — config errors must NOT be silently swallowed.
+      # Disable set -e for this block so the exit-code capture is reliable
+      # (otherwise `VAR=$(failing-cmd)` would terminate the script on lint errors).
+      set +e
+      LINT_OUTPUT=$(cd "$PKG_DIR" && "$ESLINT_BIN" --fix --cache --no-error-on-unmatched-pattern "$FILE_PATH" 2>&1)
+      LINT_EXIT=$?
+      set -e
+
+      case "$LINT_EXIT" in
+        0)
+          # Clean — silent
+          :
+          ;;
+        1)
+          # Per-file diagnostics — surface to stderr (Claude reads this)
+          if [ -n "$LINT_OUTPUT" ] && echo "$LINT_OUTPUT" | grep -qE '(error|warning)'; then
+            echo "[lint-format-on-edit] ESLint issues in ${FILE_PATH#$REPO_ROOT/}:" >&2
+            echo "$LINT_OUTPUT" >&2
+          fi
+          ;;
+        2|*)
+          # Config-load failure or unknown error — LOUD banner so config drift
+          # cannot persist silently across many rounds. Cache a marker file in
+          # /tmp so the loud banner only fires ONCE per package per session —
+          # repeat edits in the same broken package emit a one-line reminder.
+          MARKER_DIR="${TMPDIR:-/tmp}/cbp-lint-config-fail"
+          mkdir -p "$MARKER_DIR" 2>/dev/null
+          PKG_HASH=$(echo -n "$PKG_DIR" | shasum | cut -c1-12)
+          MARKER_FILE="$MARKER_DIR/$PKG_HASH"
+          if [ ! -f "$MARKER_FILE" ]; then
+            touch "$MARKER_FILE" 2>/dev/null
+            echo "" >&2
+            echo "╔════════════════════════════════════════════════════════════════════╗" >&2
+            echo "║  ⚠  ESLint CONFIGURATION ERROR — lint-on-edit hook is degraded    ║" >&2
+            echo "╠════════════════════════════════════════════════════════════════════╣" >&2
+            echo "║  Package: ${PKG_DIR#$REPO_ROOT/}" >&2
+            echo "║  Exit code: $LINT_EXIT (config-load failure)" >&2
+            echo "║  Effect: NO lint coverage in this package until fixed." >&2
+            echo "║  This banner fires ONCE per session per package; subsequent" >&2
+            echo "║  edits in the same package emit a 1-line reminder only." >&2
+            echo "╚════════════════════════════════════════════════════════════════════╝" >&2
+            echo "$LINT_OUTPUT" >&2
+            echo "" >&2
+          else
+            echo "[lint-format-on-edit] ESLint config still broken in ${PKG_DIR#$REPO_ROOT/} (banner shown earlier this session)." >&2
+          fi
+          ;;
+      esac
+    fi
+  fi
+fi
+
+exit 0

package/templates/hooks/cbp-maestro-yaml-validate.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# @event: PreToolUse
+# @matcher: Edit|Write|MultiEdit
+# Validate maestro flow YAML against the installed CLI's accepted property set.
+# Catches properties the CLI will reject at flow-run time so authors find out at
+# edit time, not after a failed `maestro test` invocation.
+#
+# Source-of-truth: maestro CLI itself. The hook reads the local CLI version and
+# applies a known-rejected-property allowlist for that version.
+
+set -euo pipefail
+
+INPUT_JSON="$(cat)"
+TOOL_NAME="$(echo "$INPUT_JSON" | jq -r '.tool_name // empty')"
+FILE_PATH="$(echo "$INPUT_JSON" | jq -r '.tool_input.file_path // empty')"
+
+# Only enforce on .yaml/.yml files under apps/*/maestro/flows/
+case "$FILE_PATH" in
+  */maestro/flows/*.yaml|*/maestro/flows/*.yml) ;;
+  *) exit 0 ;;
+esac
+
+# Bail if the file doesn't exist yet (Write of a brand new file — content lives in tool_input)
+NEW_CONTENT=""
+if [ "$TOOL_NAME" = "Write" ]; then
+  NEW_CONTENT="$(echo "$INPUT_JSON" | jq -r '.tool_input.content // empty')"
+elif [ "$TOOL_NAME" = "Edit" ]; then
+  NEW_CONTENT="$(echo "$INPUT_JSON" | jq -r '.tool_input.new_string // empty')"
+elif [ "$TOOL_NAME" = "MultiEdit" ]; then
+  NEW_CONTENT="$(echo "$INPUT_JSON" | jq -r '[.tool_input.edits[].new_string] | join("\n")')"
+fi
+
+[ -z "$NEW_CONTENT" ] && exit 0
+
+# Locate the maestro CLI. Skip if not installed (developer may not have it locally).
+MAESTRO_BIN="$(command -v maestro 2>/dev/null || true)"
+[ -z "$MAESTRO_BIN" ] && exit 0
+
+# Capture installed version (best-effort — maestro version output format has shifted).
+MAESTRO_VERSION="$("$MAESTRO_BIN" --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unknown")"
+
+# Known-rejected property catalog. Keyed by command name; properties listed here
+# fire a hook warning when they appear under that command in the YAML.
+#
+# Maintenance: when maestro upgrades, validate this list against the new CLI's
+# documentation (https://maestro.mobile.dev/api-reference/commands). Add new
+# properties here when the CLI starts accepting them; remove them when the CLI
+# drops them.
+declare -a KNOWN_REJECTED=(
+  # property:command_context
+  "timeout:assertVisible"           # maestro 1.x / 2.x rejects timeout on assertVisible (use waitForAnimationToEnd or maxRetries instead)
+  "timeout:assertNotVisible"        # same
+  "delay:tapOn"                     # use waitForAnimationToEnd or static wait
+)
+
+VIOLATIONS=""
+for entry in "${KNOWN_REJECTED[@]}"; do
+  prop="${entry%%:*}"
+  cmd="${entry##*:}"
+  # Match patterns like:
+  #   - assertVisible:
+  #       id: foo
+  #       timeout: 5000
+  # The check is heuristic — it looks for `cmd` followed by a block containing `prop:`.
+  # False-positive risk on similarly-named commands; the warning includes the matched line.
+  match="$(echo "$NEW_CONTENT" | awk -v c="$cmd" -v p="$prop" '
+    /^[[:space:]]*-?[[:space:]]*'"$cmd"':/ { in_block = 1; depth = 0; next }
+    in_block && /^[[:space:]]*[a-zA-Z]/ {
+      indent = match($0, /[^ ]/) - 1
+      if (depth == 0) depth = indent
+      if (indent < depth) { in_block = 0; next }
+      if ($0 ~ "^[[:space:]]*"p":") {
+        printf "    line %d (under `%s`): %s\n", NR, c, $0
+      }
+    }
+  ')"
+  if [ -n "$match" ]; then
+    VIOLATIONS="${VIOLATIONS}  - Property \`${prop}\` not accepted under \`${cmd}\` (rejected by maestro ${MAESTRO_VERSION}):\n${match}\n"
+  fi
+done
+
+if [ -n "$VIOLATIONS" ]; then
+  cat >&2 <<EOF
+[hook] maestro-yaml-validate: properties rejected by installed maestro CLI
+
+File: $FILE_PATH
+Maestro CLI: $MAESTRO_VERSION
+
+Detected:
+$(printf '%b' "$VIOLATIONS")
+The flow will throw 'Unknown Property' when invoked. Either:
+  - Remove the unsupported properties (consult https://maestro.mobile.dev/api-reference/commands)
+  - Upgrade the CLI if a newer version supports them
+  - Update the KNOWN_REJECTED list in this hook if the property is now supported
+
+EOF
+  exit 2
+fi
+
+exit 0

package/templates/hooks/cbp-mcp-migration-guard.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# @scope: org-shared
+# @hook: PreToolUse for MCP mutation tools
+# Hook: PreToolUse for MCP mutation tools
+# Purpose: Warn once per session if a legacy .codebyplan.json exists at repo root (post-CHK-120).
+# Warns once per session if legacy .codebyplan.json exists at repo root (post-CHK-120 case).
+# Exits 0 on all paths — never blocks the MCP call.
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+case "$TOOL_NAME" in
+  *update_task|*complete_task|*update_checkpoint|*create_checkpoint|*create_task) ;;
+  *) exit 0 ;;
+esac
+
+# Dedup across PreToolUse subprocess invocations: env exports do not survive
+# between hook firings, so use a $PPID-keyed sentinel file in /tmp instead.
+# Sentinel is unlinked when the parent (Claude Code) process exits via /tmp
+# cleanup; harmless if it lingers.
+SENTINEL="/tmp/.cbp-migration-warned-${PPID}"
+[ -f "$SENTINEL" ] && exit 0
+: > "$SENTINEL"
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+[ -z "$REPO_ROOT" ] && exit 0
+LEGACY_FILE="$REPO_ROOT/.codebyplan.json"
+[ ! -f "$LEGACY_FILE" ] && exit 0
+
+echo "cbp: legacy .codebyplan.json detected at repo root. Run: npx codebyplan sync to migrate to the .codebyplan/ directory layout (one-time, automatic). Continuing MCP call." >&2
+
+exit 0

package/templates/hooks/cbp-mcp-round-sync.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# @scope: org-shared
+# Hook: PostToolUse mcp__codebyplan__complete_round
+# Purpose: After complete_round succeeds, delegate git-diff drift merge,
+#          staging-status flip, and web-UI flag sync to the codebyplan CLI.
+#          Replaces the inline jq merge + curl PATCH with a single CLI call.
+#
+# Delegates to: npx codebyplan round sync-approvals
+#   - Git-diff drift merge (in/not-in DB vs git)
+#   - Staging-status → user_approved flip
+#   - Hook-auto-staged override (lint-format-on-edit.sh detection)
+#   - Web-UI flag (app_file_approval_by_user) consumption + reset
+#   - Writes both PATCH /api/rounds/${ROUND_ID} and PATCH /api/tasks/${TASK_ID}
+#
+# Flags:
+#   --dry-run  Pass through to CLI (prints merged payload, no API writes).
+#              Used by fixture-based smoke tests.
+#
+# Exit 0 always — non-fatal; errors go to stderr only.
+
+DRY_RUN=false
+if [ "${1:-}" = "--dry-run" ]; then
+  DRY_RUN=true
+fi
+
+INPUT=$(cat)
+
+# Only fire on PostToolUse for complete_round
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL_NAME" = "mcp__codebyplan__complete_round" ] || exit 0
+
+# Check if the tool call succeeded (non-error response)
+# PostToolUse stdin shape: {tool_name, tool_input, tool_response}
+# tool_response may be a JSON string or object — handle both
+TOOL_RESPONSE=$(echo "$INPUT" | jq -r '.tool_response // empty' 2>/dev/null)
+if [ -z "$TOOL_RESPONSE" ]; then
+  exit 0
+fi
+
+# If tool_response is a string (MCP text content), parse it
+if echo "$TOOL_RESPONSE" | jq -e 'type == "string"' >/dev/null 2>&1; then
+  TOOL_RESPONSE=$(echo "$TOOL_RESPONSE" | jq -r '.' 2>/dev/null)
+fi
+
+# Detect error responses: look for "error" key or error indicators
+RESPONSE_ERROR=$(echo "$TOOL_RESPONSE" | jq -r '.error // empty' 2>/dev/null)
+if [ -n "$RESPONSE_ERROR" ]; then
+  echo "cbp-mcp-round-sync: complete_round returned error, skipping sync" >&2
+  exit 0
+fi
+
+# Extract round_id from the response
+ROUND_ID=$(echo "$TOOL_RESPONSE" | jq -r '.id // .round_id // empty' 2>/dev/null)
+if [ -z "$ROUND_ID" ]; then
+  # Try to extract from tool_input instead
+  ROUND_ID=$(echo "$INPUT" | jq -r '.tool_input.round_id // .tool_input.id // empty' 2>/dev/null)
+fi
+if [ -z "$ROUND_ID" ]; then
+  echo "cbp-mcp-round-sync: could not extract round_id, skipping sync" >&2
+  exit 0
+fi
+
+# Extract TASK_ID from tool_response (parent task ref)
+TASK_ID=$(echo "$TOOL_RESPONSE" | jq -r '.task_id // empty' 2>/dev/null)
+if [ -z "$TASK_ID" ]; then
+  echo "cbp-mcp-round-sync: could not extract task_id, skipping sync" >&2
+  exit 0
+fi
+
+# Delegate to the codebyplan CLI (single source of truth for merge semantics)
+CMD_ARGS=("round" "sync-approvals" "--round-id" "$ROUND_ID" "--task-id" "$TASK_ID")
+[ "$DRY_RUN" = "true" ] && CMD_ARGS+=("--dry-run")
+
+if npx codebyplan "${CMD_ARGS[@]}" 2>&1; then
+  echo "cbp-mcp-round-sync: synced via CLI for round ${ROUND_ID}" >&2
+else
+  echo "cbp-mcp-round-sync: CLI sync failed for round ${ROUND_ID} (non-fatal)" >&2
+fi
+exit 0