codebyplan 1.11.1 → 1.12.0

package/templates/context/testing/e2e.md

@@ -0,0 +1,303 @@
+---
+scope: org-shared
+---
+
+# E2E Shared Workflow Contract
+
+Loaded by every `cbp-e2e-*` specialist agent. Defines the shared Input/Output contract,
+pre-flight loop, failure classification, screenshot rules, dispatch routing, and
+never-silently-skip obligations. Framework-specific commands live in each agent's body.
+
+## Input Contract
+
+Passed by the dispatching skill (`/cbp-round-execute` Step 5, `/cbp-checkpoint-check`
+Step 5b, or `/cbp-checkpoint-plan` Step 4 discovery probe). The dispatching skill reads
+`.codebyplan/e2e.json` and injects `framework`, `app`, `platforms`, and credential var
+names — agents do NOT auto-detect platform; the config is authoritative.
+
+```yaml
+input:
+  repo_id: string                            # UUID — used to resolve tech_stack from DB
+  round_number: number                       # 1-based; 0 is the sentinel for whole_checkpoint_mode
+  files_changed: [{path, action}]
+  prior_round_files_changed:                 # Required when round_number >= 2
+    - path: string
+      action: string
+      user_approved: boolean
+  whole_checkpoint_mode: boolean             # Default false. When true, run full pages_affected
+  test_strategy:
+    platform: string
+    e2e_framework: string                    # playwright | maestro | webdriverio | xcuitest | vscode-test
+  pages_affected: string[]                   # Routes or screen names changed
+  has_auth: boolean
+  dev_server_port: number | null
+  framework: string                          # From .codebyplan/e2e.json — authoritative
+  app: string                                # App path (e.g. apps/web)
+  platforms: string[]                        # e.g. ["web"] | ["ios","android"] | ["desktop"]
+  credential_vars:                           # Env var names to probe at Step 6.5.1
+    email: string | null
+    password: string | null
+```
+
+## Output Contract
+
+```yaml
+output:
+  status: 'completed' | 'failed'          # 'blocked' is NOT valid — resolve via AskUserQuestion
+  tests_written: [{path, action: 'created' | 'modified'}]
+  tests_run: boolean                      # MUST be true when status == 'completed'
+  test_results:
+    passed: number
+    failed: number
+    skipped: number
+    failures:
+      - test_name: string
+        error: string
+        file: string
+        category: 'env' | 'auth' | 'access' | 'flake' | 'real' | 'visual_regression'
+        classification_reason: string
+  framework_configured: boolean
+  preflight:
+    dev_server:     { required: bool, ok: bool, port: number | null, notes: string }
+    simulator:      { required: bool, ok: bool, device: string | null, notes: string }
+    built_binary:   { required: bool, ok: bool, path: string | null, notes: string }
+    env_vars:       { required: string[], missing: string[], ok: bool }
+    auth_probe:     { ran: bool, ok: bool, probe_path: string | null, error: string | null }
+  screenshots:
+    - test_name: string
+      path: string                        # Absolute or repo-relative path to PNG
+      page_or_screen: string
+      viewport: 'desktop' | 'mobile' | 'tablet' | 'device'
+      is_new: bool
+      baseline_diff_pct: number | null
+  user_interactions: [{question, answer}]
+  tech_stack_reconciliation:
+    db_framework: string | null
+    fs_framework: string | null
+    resolution: 'follow_db' | 'follow_fs' | 'configure_missing' | 'skip_app' | 'no_mismatch' | 'no_db_data'
+    decided_at: string
+  round2_skip_set:
+    - spec_path: string
+      reason: string
+  whole_checkpoint_aggregated: boolean
+  critical_issues:
+    - type: string
+      spec_path: string | null
+      reason: string
+```
+
+## Step 5.1 — Page Filter (Round 2+, non-checkpoint mode)
+
+When `round_number >= 2` AND `whole_checkpoint_mode === false`:
+
+1. Build `unapproved_files` from `prior_round_files_changed` where `user_approved === false`.
+2. For each page in `pages_affected[]`, derive contributing source files:
+   - Next.js: `app/<route>/page.tsx` + layout chain + imported components
+   - Expo / React Native: screen file + imported components
+   - Tauri: route component + Rust handler files
+   - Fallback: any file whose path starts with the page's directory
+3. A page **survives** when ANY contributing file is in `unapproved_files`.
+4. A page **is skipped** when ALL contributing files are user-approved.
+5. Record skipped pages in `round2_skip_set[]`.
+6. Replace `pages_affected` with the surviving subset.
+
+When `round_number === 1` OR `whole_checkpoint_mode === true`, use `pages_affected` verbatim.
+
+## Step 6.5 — Pre-flight (MANDATORY)
+
+Never proceed with `tests_run: false`. Resolve every failing check via `AskUserQuestion`
+in a loop — re-probe after user confirmation. An explicit abort returns `status: 'failed'`
+with the blocking preflight field populated.
+
+### 6.5.1 Environment Variables
+
+Check `apps/{app}/.env.local` and process env. Framework-specific required var names come
+from the `credential_vars` input field (the dispatching skill reads them from
+`.codebyplan/e2e.json`). Naming conventions:
+
+- Playwright uses `E2E_TEST_*` (avoids collision with non-E2E `TEST_*` vars).
+- Maestro/XCUITest stay on `TEST_*` per `rules/maestro-auth-state-reset.md`.
+
+For any missing var:
+
+> "Missing required E2E env vars: `{names}`. Set them in `apps/{app}/.env.local` now,
+> then reply 'ready'. (Or reply 'skip' to abort this e2e run.)"
+
+**Hard rule**: Specs MUST NOT contain in-spec env skip gates (`test.skip(!process.env.X, ...)`)
+— those bypass preflight and produce zero-assertion runs. See `rules/e2e-mandatory.md`.
+
+### 6.5.2 Runtime Readiness
+
+Framework-specific probes are in each agent's body. General obligations:
+
+- Playwright: dev server responding at `baseURL` port (curl HTTP 200/3xx).
+- Maestro (iOS): booted simulator (`xcrun simctl list devices booted | grep Booted`).
+- Maestro (Android): connected device/emulator (`adb devices | grep -w device`).
+- WebDriverIO: built Tauri binary present at the path in `wdio.conf.ts`.
+- XCUITest: `xcodebuild -list` returns the scheme; Expo prebuild artifacts present.
+- vscode-test: compiled test JS present (`e2e/**/*.test.js`).
+
+On any failure, `AskUserQuestion` with remediation steps; re-probe after "ready". Never
+silently skip a required runtime prerequisite.
+
+**Port alignment (Playwright only)**: parse `playwright.config.ts` `baseURL` and compare
+to `.codebyplan/server.json` `port_allocations[]` for the app. On mismatch ask which is
+correct before running.
+
+### 6.5.3 Auth Probe (only when `has_auth`)
+
+Run the dedicated auth probe — not the full suite. Probe paths per framework are in each
+agent's body.
+
+If the probe fails, classify the reason (see Step 7.5 below) and ask:
+
+> "Auth probe failed: `{category}` — `{error_summary}`. Common causes: wrong credentials,
+> expired state, auth backend paused, captcha. Options: (1) delete storage state + retry,
+> (2) fix credentials + reply 'ready', (3) abort e2e."
+
+On "ready", re-run the probe. Loop up to 3 times before escalating with a new
+`AskUserQuestion` that summarises all 3 attempts' errors.
+
+## Step 7.5 — Failure Classification
+
+For each failed test, assign exactly one category:
+
+| Category | Signals | Resolution |
+|---|---|---|
+| `env` | `process.env.X is undefined`, `ECONNREFUSED`, missing config | Loop to Step 6.5.1 |
+| `auth` | Login-page redirect, 401 after credential submit, `invalid_grant`, `email_not_confirmed` | AskUserQuestion per Step 6.5.3 |
+| `access` | 403/404 on an accessible route, RLS denial text, missing seed data | AskUserQuestion: "Test failed with access error: `{error}`. Options: (1) fix + reply steps, (2) abort." |
+| `flake` | Timeout on first run, passes on immediate retry, network jitter | Retry up to 3 times before reclassifying to `real` |
+| `visual_regression` | `toHaveScreenshot` pixel-diff exceeded threshold | Do NOT retry. Include baseline + actual paths in `screenshots[]` with `baseline_diff_pct`. Do NOT auto-accept baselines. |
+| `real` | Assertion failure on app behavior (wrong text, state, navigation) | Attempt fix (selector, timeout, assertion), max 3 attempts, then report |
+
+`env`, `auth`, `access` failures MUST NOT count toward `test_results.failed` until
+preflight passes — they block the run instead.
+
+## Screenshot Collection Rule
+
+After every run, enumerate all PNGs produced and populate `screenshots[]`. Framework-
+specific paths are in each agent's body. Every entry requires:
+`{test_name, path, page_or_screen, viewport, is_new, baseline_diff_pct}`.
+
+Screenshots flow to `cbp-frontend-ui` invoked by `/cbp-round-execute` Step 5b with
+`phase: 'screenshot_review'` — NOT inline by `round-executor` Step 3.8 (which runs
+`phase: 'style_only'` without e2e output).
+
+**Baselines are never auto-accepted.** A `toHaveScreenshot` diff is `visual_regression`;
+the user decides via QA whether to update baselines.
+
+## Completion Rule
+
+`status: 'completed'` is allowed ONLY when:
+
+- `tests_run === true`
+- `preflight.*.ok === true` for every required prerequisite
+- Every failure has `category` other than `env`, `auth`, or `access`
+
+Otherwise return `status: 'failed'`.
+
+## Never-Silently-Skip Rules
+
+- Missing simulator / server / binary / env / auth → always `AskUserQuestion`, never `tests_run: false`.
+- No testable targets despite `has_ui_work` → return `status: 'failed'` with reason "no testable targets".
+- All-skipped run (`passed === 0 && skipped > 0` for a spec in `files_changed`) → `status: 'failed'`, add `critical_issues[]` entry `{type: 'e2e_all_skipped', ...}`.
+- User aborts preflight → `status: 'failed'`, add `critical_issues[]` entry `{type: 'preflight_aborted', ...}`.
+
+## Dispatch / Eligibility Routing Contract
+
+The dispatching skill (`/cbp-round-execute` Step 5 or `/cbp-checkpoint-check` Step 5b)
+selects one specialist per app. Config is in `.codebyplan/e2e.json` (authoritative).
+
+| `framework` in e2e.json | Agent spawned | Typical app type |
+|---|---|---|
+| `playwright` | `cbp-e2e-playwright` | Next.js web routes |
+| `maestro` | `cbp-e2e-maestro` | Expo / React Native (android + ios) |
+| `webdriverio` | `cbp-e2e-tauri` | Tauri desktop |
+| `vscode-test` | `cbp-e2e-vscode` | VS Code extension |
+| `xcuitest` | `cbp-e2e-xcuitest` | Native iOS (system dialogs, HealthKit, watchOS) |
+
+**Eligibility is config-driven.** A framework is **eligible** in a round when its
+`.codebyplan/e2e.json` entry has `enabled === true` AND `auto_run === true` AND its `app`
+source path intersects the round's `files_changed` (repo root for single-app repos). An
+eligible framework's specialist MUST run — see `rules/e2e-mandatory.md` for the opt-out
+contract and the `e2e_eligible_skipped` hard-fail.
+
+An agent is NOT spawned when ANY of the following hold:
+
+- `testing_profile` is `claude_only` or `backend` (no UI surface) — a short-circuit hint, applied before reading `e2e.json`.
+- The framework's `enabled` or `auto_run` is `false`, or the `app` path does not intersect `files_changed`.
+- `frameworks` in `e2e.json` is absent or empty (no e2e configured) — zero eligible, no hard-fail.
+- `platforms[]` in `e2e.json` does not include the current CI target (e.g., iOS-only config skipped on a Linux runner without a simulator) — a recorded valid skip per `rules/e2e-mandatory.md`.
+
+`has_ui_work` and `testing_profile` (beyond the `claude_only` / `backend` short-circuit) are
+**hints only** — they never suppress an eligible framework. Config is authoritative.
+
+**Multi-app monorepos**: the dispatching skill reads `e2e.json` per app path and may
+spawn multiple specialists in the same round (one per eligible framework). Agents run in
+parallel with `cbp-testing-qa-agent`. Each specialist's output is stored under
+`round.context.e2e_outputs[framework]` (a framework-keyed map); `/cbp-round-execute` Step 5b
+aggregates `screenshots[]` across all entries before the `cbp-frontend-ui` review.
+
+**whole_checkpoint_mode dispatch** (`/cbp-checkpoint-check` Step 5b and `/cbp-checkpoint-plan`
+Step 4): pass `round_number: 0`, `whole_checkpoint_mode: true`, and the aggregated
+`files_changed` union. The agent ignores `prior_round_files_changed` in this mode.
+
+This contract is the single source of truth for dispatch logic. Config-driven dispatch is
+implemented in `/cbp-round-execute` Step 5 and `/cbp-checkpoint-check` Step 5b (CHK-145); the
+routing table above is the authoritative reference those gates match. Enforcement (the
+`e2e_eligible_skipped` hard-fail and the no-in-spec-env-skip gate) lives in
+`rules/e2e-mandatory.md`.
+
+## Playwright Auth Provisioning Convention
+
+Every repo with Playwright auth ships:
+
+- `scripts/provision-e2e-user.ts` — idempotent script creating the canonical E2E user
+  and (for multi-tenant repos) a `test` subdomain. Wired to `pnpm e2e:provision`.
+- `.env.local.example` — lists every env var `globalSetup` requires.
+- CI secrets: `E2E_TEST_EMAIL`, `E2E_TEST_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
+  `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (or legacy `_ANON_KEY`).
+
+Per-repo specifics (email, vault name, remaining-spec migration list) live in the repo's
+own `docs/e2e-setup.md`, not in this shared file.
+
+## Auth State Gitignore
+
+Before writing any storage state under `playwright/.auth/`, `tests/.auth/`, or
+`e2e/.auth/`, verify the path is in the nearest `.gitignore`. If absent, ADD the entry
+first. Auth state files contain live session cookies — committing one is a credential
+leak. See `rules/playwright-auth-gitignore.md`.
+
+## Supabase Parallelism (Playwright)
+
+When `NEXT_PUBLIC_SUPABASE_URL` references a remote project (not localhost), set
+`workers: 1` in `playwright.config.ts` to prevent auth/RLS races. Not needed with a
+local Supabase emulator. Detect via: `grep -E "127\.0\.0\.1|localhost" apps/{app}/.env.local | grep SUPABASE_URL`.
+
+## Mock Server for Server-Side Fetch
+
+`page.route()` intercepts browser-process requests only. For Next.js server actions,
+route handlers, or middleware (Node-process fetch), spin up a real local HTTP server in
+`globalSetup` and point the dev server at it via `webServer.env`. See
+`rules/playwright-server-side-mocking.md`.
+
+## Cold-Start Warmup (Playwright / Next.js)
+
+Next.js dev mode (Turbopack) compiles routes lazily. Add a warmup fetch at the end of
+`globalSetup`, after mock server starts, before specs run. Use `redirect: 'manual'` for
+auth-protected routes. Wrap in `try/catch` — warmup is best-effort.
+
+## Locator Hygiene (Playwright)
+
+Prefer stable accessibility-driven selectors (`getByRole`, `getByLabel`, `getByTestId`)
+over positional CSS selectors (`.locator('.class').nth(N)`). After `page.goto()` inside
+a loop, snapshot text/href BEFORE navigation rather than holding stale `Locator` handles.
+
+## Visual Baseline Workflow
+
+| Situation | What happens |
+|---|---|
+| No baseline (new screen) | Playwright creates on first run; test passes; `cbp-frontend-ui` at Step 5b reviews semantically. |
+| Baseline exists, diff ≤ threshold | Test passes. |
+| Baseline exists, diff > threshold | `visual_regression` failure. Agent does NOT retry. `cbp-frontend-ui` at Step 5b flags it; `/cbp-round-end` Step 3b constructs user QA item. User decides: fix-task or `--update-snapshots`. |

package/templates/hooks/cbp-statusline.mjs

@@ -118,6 +118,7 @@ function main() {
     rate_limits: true,
     repo_pr: true,
     worktree: true,
+    infra_drift: true,
     no_color: false,
   };
   try {
@@ -136,6 +137,7 @@ function main() {
           "rate_limits",
           "repo_pr",
           "worktree",
+          "infra_drift",
         ]) {
           if (typeof parsed.lines[k] === "boolean") cfg[k] = parsed.lines[k];
         }
@@ -374,6 +376,48 @@ function main() {
     }
   }
 
+  // ============================================================
+  // LINE 7 — Infra drift (monorepo feat branches behind main)
+  // ============================================================
+  // Only the codebyplan monorepo (templates/ present) on a feat branch can carry
+  // stale .claude/ infra. No fetch — counts against the cached origin/main only.
+  if (shouldShow("INFRA_DRIFT", cfg.infra_drift)) {
+    if (
+      BRANCH.startsWith("feat/") &&
+      fs.existsSync(
+        path.join(root, "packages", "codebyplan-package", "templates")
+      )
+    ) {
+      let behind = 0;
+      try {
+        behind = parseInt(
+          execFileSync(
+            "git",
+            [
+              "-C",
+              root,
+              "rev-list",
+              "--count",
+              "HEAD..origin/main",
+              "--",
+              ".claude",
+              "packages/codebyplan-package/templates",
+            ],
+            { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+          ).trim(),
+          10
+        );
+      } catch {
+        behind = 0;
+      }
+      if (Number.isFinite(behind) && behind > 0) {
+        out.push(
+          `${C.YELLOW}⚠ infra ${behind} behind${C.RST} ${C.DIM}→ /cbp-refresh-infra${C.RST}`
+        );
+      }
+    }
+  }
+
   process.stdout.write(out.length ? out.join("\n") + "\n" : "");
 }
 

package/templates/hooks/cbp-statusline.py

@@ -80,7 +80,8 @@ def main():
     # ---- Config: line toggles + no_color -------------------------------------
     cfg = {
         "identity": True, "context": True, "cost": True,
-        "rate_limits": True, "repo_pr": True, "worktree": True, "no_color": False,
+        "rate_limits": True, "repo_pr": True, "worktree": True,
+        "infra_drift": True, "no_color": False,
     }
     try:
         with open(os.path.join(root, ".codebyplan", "statusline.json"), "r", encoding="utf-8") as fh:
@@ -90,7 +91,7 @@ def main():
                 cfg["no_color"] = parsed["no_color"]
             lines = parsed.get("lines")
             if isinstance(lines, dict):
-                for k in ["identity", "context", "cost", "rate_limits", "repo_pr", "worktree"]:
+                for k in ["identity", "context", "cost", "rate_limits", "repo_pr", "worktree", "infra_drift"]:
                     if isinstance(lines.get(k), bool):
                         cfg[k] = lines[k]
     except Exception:
@@ -321,6 +322,27 @@ def main():
             l6 += " %s%s%s" % (DIM, wt_path_disp, RST)
             out.append(l6)
 
+    # ===== LINE 7 — Infra drift (monorepo feat branches behind main) =====
+    # Only the codebyplan monorepo (templates/ present) on a feat branch can carry
+    # stale .claude/ infra. No fetch — counts against the cached origin/main only.
+    if should_show("INFRA_DRIFT", cfg["infra_drift"]):
+        if branch.startswith("feat/") and os.path.isdir(
+            os.path.join(root, "packages", "codebyplan-package", "templates")
+        ):
+            behind = 0
+            try:
+                res = subprocess.run(
+                    ["git", "-C", root, "rev-list", "--count", "HEAD..origin/main",
+                     "--", ".claude", "packages/codebyplan-package/templates"],
+                    stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+                )
+                if res.returncode == 0:
+                    behind = int(res.stdout.strip() or "0")
+            except Exception:
+                behind = 0
+            if behind > 0:
+                out.append("%s⚠ infra %d behind%s %s→ /cbp-refresh-infra%s" % (YELLOW, behind, RST, DIM, RST))
+
     sys.stdout.write(("\n".join(out) + "\n") if out else "")
 
 

package/templates/hooks/cbp-statusline.sh

@@ -15,7 +15,7 @@
 #
 # DISPLAY OPTIONS (team-shared, committed)
 #   .codebyplan/statusline.json -> { "lines": {identity,context,cost,rate_limits,
-#                                    repo_pr,worktree}, "no_color": bool }
+#                                    repo_pr,worktree,infra_drift}, "no_color": bool }
 #
 # ENV-VAR OVERRIDES (env > config > default)
 #   CBP_STATUSLINE_HIDE_IDENTITY=1     suppress line 1 (folder, branch, model, effort, …)
@@ -24,6 +24,7 @@
 #   CBP_STATUSLINE_HIDE_RATE_LIMITS=1  suppress line 4 (5h / 7d rate limits)
 #   CBP_STATUSLINE_HIDE_REPO_PR=1      suppress line 5 (repo host/owner/name, PR)
 #   CBP_STATUSLINE_HIDE_WORKTREE=1     suppress line 6 (worktree name/branch/path)
+#   CBP_STATUSLINE_HIDE_INFRA_DRIFT=1  suppress line 7 (.claude infra commits behind main)
 #   CBP_STATUSLINE_NO_COLOR=1          strip all ANSI colour codes (also honoured by $NO_COLOR)
 #
 # TEST SEAMS (no effect in normal use)
@@ -104,7 +105,7 @@ eval "$(echo "$INPUT" | jq -r '
 
 # ---- Config: line toggles + no_color from .codebyplan/statusline.json --------
 CFG_IDENTITY=true; CFG_CONTEXT=true; CFG_COST=true
-CFG_RATE_LIMITS=true; CFG_REPO_PR=true; CFG_WORKTREE=true; CFG_NO_COLOR=false
+CFG_RATE_LIMITS=true; CFG_REPO_PR=true; CFG_WORKTREE=true; CFG_INFRA_DRIFT=true; CFG_NO_COLOR=false
 CBP_CFG="$CBP_ROOT/.codebyplan/statusline.json"
 if [ -f "$CBP_CFG" ] && command -v jq >/dev/null 2>&1; then
   # Use `!= false` / `== true` (NOT jq `//`): the `//` operator treats an explicit
@@ -117,6 +118,7 @@ if [ -f "$CBP_CFG" ] && command -v jq >/dev/null 2>&1; then
     "CFG_RATE_LIMITS=\(.lines.rate_limits != false)",
     "CFG_REPO_PR=\(.lines.repo_pr != false)",
     "CFG_WORKTREE=\(.lines.worktree != false)",
+    "CFG_INFRA_DRIFT=\(.lines.infra_drift != false)",
     "CFG_NO_COLOR=\(.no_color == true)"
   ' "$CBP_CFG" 2>/dev/null)"
 fi
@@ -401,3 +403,21 @@ if should_show WORKTREE "$CFG_WORKTREE"; then
     printf "%b\n" "$L6"
   fi
 fi
+
+# ============================================================
+# LINE 7 — Infra drift (monorepo feat branches behind main)
+# ============================================================
+# Only the codebyplan monorepo (templates/ present) on a feat branch can carry
+# stale .claude/ infra. No fetch — counts against the cached origin/main only.
+if should_show INFRA_DRIFT "$CFG_INFRA_DRIFT"; then
+  case "$BRANCH" in
+    feat/*)
+      if [ -d "$CBP_ROOT/packages/codebyplan-package/templates" ]; then
+        BEHIND="$(git -C "$CBP_ROOT" rev-list --count HEAD..origin/main -- .claude packages/codebyplan-package/templates 2>/dev/null)"
+        if [ -n "$BEHIND" ] && [ "$BEHIND" -gt 0 ] 2>/dev/null; then
+          printf "%b\n" "${YELLOW}⚠ infra ${BEHIND} behind${RST} ${DIM}→ /cbp-refresh-infra${RST}"
+        fi
+      fi
+      ;;
+  esac
+fi

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

@@ -19,12 +19,14 @@ _get_limit() {
     /CHANGELOG.md|*/CHANGELOG.md|*/user-input.md|/.claude/docs/research/*) echo ""; return;;
     # Managed .claude/ files
     /.claude/rules/*.md)                                echo "100 200"; return;;
+    /.claude/context/testing/e2e.md)                    echo "300 600"; return;;   # consolidated E2E shared-workflow + dispatch contract (CHK-145)
     /.claude/context/*.md|/.claude/context/*/*.md)      echo "200 400"; return;;
     /.claude/skills/*/SKILL.md)                         echo "300 600"; return;;
     /.claude/skills/*/reference/*.md)                   echo "200 400"; return;;
     /.claude/skills/*/examples/*.md|/.claude/skills/*/templates/*) echo "100 200"; return;;
     /.claude/agents/*/AGENT.md)                         echo "400 800"; return;;
     /.claude/agents/*/*.md)                             echo "200 400"; return;;
+    /.claude/agents/*.md)                               echo "400 800"; return;;
     /.claude/hooks/*.sh)                                echo "150 300"; return;;
     /.claude/docs/architecture/*.md|/.claude/docs/server/*.md) echo "200 400"; return;;
     /.claude/docs/stack/*/index.md|/.claude/docs/stack/*/guide.md) echo "150 300"; return;;

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

@@ -62,7 +62,8 @@ run_case() {
 
 # ===== Good fixtures (must exit 0) =====
 run_case "good-skill"   good/skill.md /.claude/skills/cbp-fixture/SKILL.md 0
-run_case "good-agent"   good/agent.md /.claude/agents/cbp-fixture/AGENT.md 0
+run_case "good-agent"      good/agent.md /.claude/agents/cbp-fixture/AGENT.md 0
+run_case "good-agent-flat" good/agent.md /.claude/agents/cbp-fixture.md 0
 run_case "good-rule"    good/rule.md  /.claude/rules/cbp-fixture.md 0
 run_case "good-hook"    good/hook.sh  /.claude/hooks/cbp-fixture.sh 0
 

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

@@ -12,6 +12,7 @@ TEMPLATE=""
 case "$REL_PATH" in
   /.claude/skills/*)              TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-skill/reference/cbp-quality.md" ;;
   /.claude/agents/*/AGENT.md)     TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-agent/reference/cbp-quality.md" ;;
+  /.claude/agents/*.md)           TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-agent/reference/cbp-quality.md" ;;
   /.claude/docs/research/*/1-*)   TEMPLATE="/docs/templates/.claude/docs/research/1-problem.md" ;;
   /.claude/docs/research/*/2-*)   TEMPLATE="/docs/templates/.claude/docs/research/2-claude-default.md" ;;
   /.claude/docs/research/*/3-*)   TEMPLATE="/docs/templates/.claude/docs/research/3-official-docs.md" ;;

package/templates/rules/README.md

@@ -34,7 +34,14 @@ The `install`/`update`/`uninstall` flow handles these files identically to how i
 
 ## Current status
 
-Zero rules are shipped today. The wiring is in place so future PRs can land curated rules through the same install/update/uninstall flow as other templates.
+Four rules are shipped:
+
+| Rule file | Summary |
+|---|---|
+| `scope-vocabulary.md` | Canonical scope-marker enum (`org-shared` / `project-shared` / `repo-only:<name>`) enforced by three validators |
+| `context-file-loading.md` | Context-file load contract — who loads what, when, and how missing files are handled |
+| `todo-backend.md` | Todos queue contract, six DB-layer workflow invariants, and writer obligations for MCP mutators |
+| `supabase-branch-lifecycle.md` | Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle — lazy create on first DB change, delete wherever the git branch is removed |
 
 ## Contributing a rule
 

package/templates/rules/context-file-loading.md

@@ -14,8 +14,11 @@ paths:
 | Context File | Loaded By | Phase | Purpose |
 |--------------|-----------|-------|---------|
 | `context/testing/unit.md` | `cbp-round-executor` | Step 3.6 | Unit test patterns per framework |
-| `context/testing/e2e.md` | `cbp-test-e2e-agent` | Entry | E2E framework setup + spec patterns |
+| `context/testing/e2e.md` | `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest` | Entry | Shared contract: Input/Output, preflight, failure classification, dispatch routing |
 | `context/testing/e2e.md` | `cbp-testing-qa-agent` | Preflight | Env var list per framework |
+| `context/testing/e2e.md` | `cbp-checkpoint-plan` | Step 4 | Discovery probe dispatch contract |
+| `context/testing/e2e.md` | `cbp-round-execute` | Step 5 | E2E specialist dispatch routing |
+| `context/testing/e2e.md` | `cbp-checkpoint-check` | Step 5b | Whole-checkpoint e2e dispatch |
 | `context/testing/eslint.md` | `cbp-task-planner` | Phase 1.5 | ESLint Compliance Checklist |
 | `context/testing/eslint.md` | `cbp-improve-round` | Phase 1.5 | Config-file compliance audit |
 | `context/mcp-docs.md` | `cbp-task-planner` | Phase 2.6 | MCP library doc lookup contract — per-dependency consultation via DocsByPlan MCP tools (resolve_library_id → search_chunks/lookup_symbol → get_chunk) |

package/templates/rules/e2e-mandatory.md

@@ -0,0 +1,70 @@
+---
+scope: org-shared
+---
+
+# E2E Mandatory Run Contract
+
+E2E is **opt-out, not opt-in**. Whenever a framework configured in `.codebyplan/e2e.json`
+covers an app whose source changed in a round, the matching `cbp-e2e-*` specialist runs —
+there is no per-round decision to "add" e2e. This rule defines *when a run is obligatory*
+and *what makes a skip legitimate*. The companion Input/Output contract and the
+framework → agent dispatch routing table live in `context/testing/e2e.md`.
+
+## Opt-Out Contract
+
+A framework is **eligible** in a round when ALL hold:
+
+- `.codebyplan/e2e.json` `frameworks.{name}.enabled === true` AND `auto_run === true`.
+- The framework's `app` source path intersects the round's `files_changed` (repo root for
+  single-app repos).
+
+When eligible, `/cbp-round-execute` Step 5 spawns the matching specialist in parallel with
+`cbp-testing-qa-agent`; `/cbp-checkpoint-check` Step 5b does the same against the aggregated
+file union with `whole_checkpoint_mode: true`.
+
+`has_ui_work` and `testing_profile` are **hints only** — they short-circuit e2e *solely* for
+`claude_only` / `backend`-only rounds (no UI surface). For every other profile config is
+authoritative: a `has_ui_work === false` inference never suppresses an eligible framework.
+
+When `frameworks` is absent or empty, zero frameworks are eligible — no specialist runs and
+no hard-fail fires.
+
+## `e2e_eligible_skipped` Hard-Fail
+
+If a framework was eligible this round but no specialist ran AND no valid skip reason is
+recorded, the round **hard-fails** and `/cbp-round-execute` Step 6 auto-triggers
+`/cbp-round-input`. Silent skips are bugs, not conveniences — this is the enforcement behind
+the opt-out contract.
+
+**Valid skip reasons** (must be recorded in `round.context.e2e_outputs[framework]` or the
+round failure context):
+
+- User explicitly aborted preflight → specialist returns `status: 'failed'` with a
+  `critical_issues[].type === 'preflight_aborted'` entry.
+- Environmental block: `preflight.*.ok === false` (missing simulator / server / binary / env)
+  persists after the Step 6.5 AskUserQuestion loop — an env block, not a spec failure.
+- `platforms[]` in `e2e.json` excludes the current CI target (e.g. an iOS-only config on a
+  Linux runner with no simulator).
+- Round type is `survey` (no code executed).
+
+No other skip reason is valid. "Looked UI-light", "tests are slow", or "covered by unit
+tests" are NOT valid skips.
+
+## No In-Spec Env-Skip Gate
+
+Spec files MUST NOT contain in-spec env skip gates such as `test.skip(!process.env.X, ...)`.
+They bypass preflight, produce zero-assertion runs, and hide missing env vars behind a green
+check. Pre-flight (`context/testing/e2e.md` Step 6.5.1) is the only mechanism for
+env-conditional skipping.
+
+A spec that ran with `passed === 0 && skipped > 0` for any path touching `files_changed` is a
+**hard fail**, not a pass — `cbp-task-check` (`agents/cbp-task-check.md`) refuses a READY
+verdict on a zero-assertion e2e run and routes to a fix round per this rule.
+
+## Cross-References
+
+- `context/testing/e2e.md` — Input/Output contract, pre-flight loop, failure classification,
+  and the dispatch routing table (framework → agent).
+- `agents/cbp-task-check.md` — enforces the zero-assertion hard-fail at verdict time.
+- `skills/cbp-round-execute/SKILL.md` Step 5/6, `skills/cbp-checkpoint-check/SKILL.md` Step 5b
+  — the config-driven dispatch and `e2e_eligible_skipped` gate implementations.