codebyplan 1.13.14 → 1.13.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.14",
+  "version": "1.13.16",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/agents/cbp-e2e-maestro.md

@@ -38,7 +38,7 @@ env:
   TEST_EMAIL: ${TEST_EMAIL}
   TEST_PASSWORD: ${TEST_PASSWORD}
   APP_ID: com.yourorg.yourapp
-screenshotsDir: maestro/screenshots
+screenshotsDir: e2e/screenshots/maestro
 ```
 
 ## Shared Login Flow
@@ -158,8 +158,31 @@ delete + confirm + verify removed.
 - takeScreenshot: "flow-name-after-state"
 ```
 
-Screenshots written to `maestro/screenshots/` (via `screenshotsDir` in `config.yaml`).
-Enumerate: `maestro/screenshots/*.png`.
+Screenshots written to `e2e/screenshots/maestro/` (via `screenshotsDir` in `config.yaml`).
+Committed path convention: `e2e/screenshots/maestro/{flow}-{state}.png` (repo root).
+This path is intentionally outside `apps/web/e2e/screenshots/` (which is gitignored).
+
+After the flow completes, `git add e2e/screenshots/maestro/` to track new PNGs.
+
+**`is_new` detection**: `git ls-files --error-unmatch <path>` exits non-zero → `is_new: true`.
+
+Enumerate committed PNGs: `e2e/screenshots/maestro/*.png`.
+
+## e2e_gallery Population
+
+After the run, for each committed PNG in `e2e/screenshots/maestro/*.png`, emit one
+`e2e_gallery[]` entry:
+
+```yaml
+- test_name: string          # Maestro flow filename (e.g. "dashboard")
+  page_or_screen: string     # screen / flow name
+  framework: maestro
+  committed_path: string     # repo-relative: e2e/screenshots/maestro/{flow}-{state}.png
+  is_new: boolean            # detected via git ls-files
+  baseline_diff_pct: null    # Maestro does not produce pixel diffs
+```
+
+Include this in the specialist output alongside `screenshots[]`.
 
 ## Run Command
 

package/templates/agents/cbp-e2e-playwright.md

@@ -189,7 +189,8 @@ test.describe("Home page", () => {
 ```ts
 await expect(page).toHaveScreenshot("state-name.png", { maxDiffPixelRatio: 0.001 });
 ```
-Baselines live beside spec under `{spec}.spec.ts-snapshots/`. Committed to git.
+Baselines live beside spec under `{spec}.spec.ts-snapshots/`. Committed path:
+`apps/{app}/e2e/{spec}.spec.ts-snapshots/{name}-{browser}.png`.
 
 **Diagnostic** (intermediate states):
 ```ts
@@ -199,9 +200,29 @@ await page.screenshot({
 });
 ```
 
-Enumerate PNGs: `test-results/**/*.png` and `{spec}.spec.ts-snapshots/`.
+Enumerate committed PNGs: `{spec}.spec.ts-snapshots/**/*.png` (NOT `test-results/` — those are transient).
 
-**Never run `--update-snapshots` automatically.** A diff is a `visual_regression` failure.
+**`is_new` detection**: `git ls-files --error-unmatch <committed_path>` exits non-zero →
+`is_new: true` (auto-committed first-run baseline; `git add` the file). Exit zero → `is_new: false`.
+
+**Never run `--update-snapshots` automatically.** A diff on an existing baseline is a `visual_regression` failure.
+
+## e2e_gallery Population
+
+After the run, for each committed PNG in `{spec}.spec.ts-snapshots/**/*.png`, emit one
+`e2e_gallery[]` entry. For `screenshots[].viewport`: default to `'desktop'`; set `'mobile'`
+when the playwright.config project/device emulation indicates a mobile viewport (e.g. `devices['iPhone 14']`).
+
+```yaml
+- test_name: string          # test title from test.info().title
+  page_or_screen: string     # route / screen name
+  framework: playwright
+  committed_path: string     # repo-relative path to the .spec.ts-snapshots PNG
+  is_new: boolean            # detected via git ls-files (see above)
+  baseline_diff_pct: number | null  # from Playwright diff output; null when is_new
+```
+
+Include this in the specialist output alongside `screenshots[]`.
 
 ## Run Command
 

package/templates/agents/cbp-e2e-tauri.md

@@ -148,10 +148,33 @@ For CRUD: create + verify visible; edit + verify; delete + confirm + verify remo
 ## Screenshot Capture
 
 ```ts
-await browser.saveScreenshot(`./e2e/screenshots/${testName}-${state}.png`);
+await browser.saveScreenshot(
+  `./e2e/screenshots/webdriverio/${testName}-${state}.png`
+);
 ```
 
-Enumerate: `e2e/screenshots/*.png`.
+Committed path convention: `{app-dir}/e2e/screenshots/webdriverio/{spec}-{state}.png`.
+After the run, `git add {app-dir}/e2e/screenshots/webdriverio/` to track new PNGs.
+
+**`is_new` detection**: `git ls-files --error-unmatch <path>` exits non-zero → `is_new: true`.
+
+Enumerate committed PNGs: `{app-dir}/e2e/screenshots/webdriverio/**/*.png`.
+
+## e2e_gallery Population
+
+After the run, for each committed PNG under `{app-dir}/e2e/screenshots/webdriverio/`, emit one
+`e2e_gallery[]` entry:
+
+```yaml
+- test_name: string          # spec describe/it label
+  page_or_screen: string     # window / view name
+  framework: webdriverio
+  committed_path: string     # repo-relative: {app-dir}/e2e/screenshots/webdriverio/{spec}-{state}.png
+  is_new: boolean            # detected via git ls-files
+  baseline_diff_pct: null    # WebDriverIO does not produce pixel diffs
+```
+
+Include this in the specialist output alongside `screenshots[]`.
 
 ## Run Command
 

package/templates/agents/cbp-e2e-vscode.md

@@ -162,10 +162,35 @@ snapshots to `test-fixtures/`.
 ## Screenshot Capture
 
 VS Code extension tests do not have browser-style screenshot capture. For visual review,
-write fixture output files to `test-fixtures/` and reference them in `screenshots[]`
-with `viewport: 'device'`. `baseline_diff_pct: null` for all entries.
+write fixture output PNGs to the committed dir:
 
-Enumerate screenshots: `apps/vscode/test-fixtures/**/*.png`.
+Committed path convention: `{app-dir}/e2e/screenshots/vscode/{suite}-{test}.png`.
+
+This dir **may be empty** for behavior-only tests that produce no visual output (SD-3).
+When capturing PNGs is possible, write them there and `git add` them.
+
+Enumerate committed PNGs: `{app-dir}/e2e/screenshots/vscode/**/*.png` (may be empty).
+
+## e2e_gallery Population
+
+Always emit `e2e_gallery[]` in the specialist output — even when empty (never omit the field):
+
+```yaml
+e2e_gallery: []   # empty for behavior-only extensions with no PNG output
+```
+
+When committed PNGs do exist, emit one entry per PNG:
+
+```yaml
+- test_name: string          # suite/test name
+  page_or_screen: string     # VS Code view / panel name
+  framework: vscode-test
+  committed_path: string     # repo-relative: {app-dir}/e2e/screenshots/vscode/{suite}-{test}.png
+  is_new: boolean            # detected via git ls-files
+  baseline_diff_pct: null    # vscode-test does not produce pixel diffs
+```
+
+Include this in the specialist output alongside `screenshots[]`.
 
 ## Run Command
 

package/templates/agents/cbp-e2e-xcuitest.md

@@ -168,11 +168,40 @@ screenshot.lifetime = .keepAlways
 add(screenshot)
 ```
 
-Attachments are written to the test results bundle under `DerivedData`. Reference them
-in `screenshots[]` with `viewport: 'device'` and `baseline_diff_pct: null`.
+Attachments are written to the test results bundle under `DerivedData`. After the run,
+export them to the committed path using `xcrun xcresulttool`:
 
-Enumerate: `~/Library/Developer/Xcode/DerivedData/**/Attachments/*.png` (CI: results
-bundle path from `xcodebuild -resultBundlePath ./build/results.xcresult`).
+```bash
+# Export all attachments from the result bundle to committed dir
+xcrun xcresulttool export \
+  --path ./build/results.xcresult \
+  --output-path {app-dir}/e2e/screenshots/xcuitest \
+  --type directory
+```
+
+Committed path convention: `{app-dir}/e2e/screenshots/xcuitest/{TestClass}/{testMethod}-{n}.png`.
+After export, `git add {app-dir}/e2e/screenshots/xcuitest/` to track new PNGs.
+
+**`is_new` detection**: `git ls-files --error-unmatch <path>` exits non-zero → `is_new: true`.
+
+Enumerate committed PNGs: `{app-dir}/e2e/screenshots/xcuitest/**/*.png`.
+
+## e2e_gallery Population
+
+After export, for each committed PNG under `{app-dir}/e2e/screenshots/xcuitest/`, emit one
+`e2e_gallery[]` entry:
+
+```yaml
+- test_name: string          # TestClass/testMethod
+  page_or_screen: string     # screen name inferred from the attachment name
+  framework: xcuitest
+  committed_path: string     # repo-relative: {app-dir}/e2e/screenshots/xcuitest/{TestClass}/{testMethod}-{n}.png
+  is_new: boolean            # detected via git ls-files
+  baseline_diff_pct: null    # XCUITest does not produce pixel diffs
+```
+
+Include this in the specialist output alongside `screenshots[]` (which retains the
+`DerivedData` transient path for diagnostic reference).
 
 ## Run Command
 
@@ -181,9 +210,16 @@ xcodebuild test \
   -workspace ios/YourApp.xcworkspace \
   -scheme YourApp \
   -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
+  -resultBundlePath ./build/results.xcresult \
   TEST_EMAIL="$TEST_EMAIL" \
   TEST_PASSWORD="$TEST_PASSWORD" \
   | xcbeautify
+# Then export attachments to committed dir:
+xcrun xcresulttool export \
+  --path ./build/results.xcresult \
+  --output-path {app-dir}/e2e/screenshots/xcuitest \
+  --type directory
+git add {app-dir}/e2e/screenshots/xcuitest/
 ```
 
 ## pnpm Script

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

@@ -84,6 +84,8 @@ Review all QA items across all rounds:
 
 **E2E pass vs skipped distinction**: When reading `auto_qa.items[]` for `check: 'e2e'`, do NOT conflate `status: 'pass'` with `status: 'skipped'`. A spec that ran with `passed === 0 && skipped > 0` for any path touching `files_changed` is a hard fail, not a pass — verdict text MUST explicitly call this out: "E2E spec authored but assertions did not execute (skip-gated)." Do NOT issue a READY verdict on a zero-assertion e2e run; route to a fix round per `rules/e2e-mandatory.md`.
 
+**Committed-screenshot check**: For any round where `round.context.e2e_eligible[]` is non-empty, verify `round.context.e2e_gallery[]` is non-empty. Refuse a READY verdict when it is empty — verdict text: "E2E ran but produced zero committed screenshots — open a fix round per `rules/e2e-mandatory.md` § Committed-Screenshot Enforcement." Sole exception: when `vscode-test` is the ONLY eligible framework, an empty `e2e_gallery[]` is allowed (SD-3, behavior-only extensions).
+
 List any pending or failed items. Determine if they are blockers.
 
 ### Phase 5: File Approval Check

package/templates/context/testing/e2e.md

@@ -70,6 +70,13 @@ output:
       viewport: 'desktop' | 'mobile' | 'tablet' | 'device'
       is_new: bool
       baseline_diff_pct: number | null
+  e2e_gallery:                           # ADDITIVE alongside screenshots[]; consumed by TASK-3 / checkpoint-end
+    - test_name: string
+      page_or_screen: string
+      framework: string                  # playwright | maestro | xcuitest | webdriverio | vscode-test
+      committed_path: string             # repo-relative; MUST be git-tracked after the run
+      is_new: boolean                    # true => no prior baseline; auto-captured+committed this run
+      baseline_diff_pct: number | null   # null for non-playwright frameworks
   user_interactions: [{question, answer}]
   tech_stack_reconciliation:
     db_framework: string | null
@@ -174,18 +181,57 @@ For each failed test, assign exactly one category:
 `env`, `auth`, `access` failures MUST NOT count toward `test_results.failed` until
 preflight passes — they block the run instead.
 
+## Committed-Screenshot Mandate
+
+Every eligible e2e run MUST persist relevant screenshots to the framework's committed
+directory (tracked in git). Transient dirs (e.g. `test-results/`, `DerivedData`) are for
+diagnostics only — they are NOT the committed path.
+
+| Framework | Committed path |
+|---|---|
+| playwright | `apps/{app}/e2e/{spec}.spec.ts-snapshots/{name}-{browser}.png` |
+| maestro | `e2e/screenshots/maestro/{flow}-{state}.png` (repo root) |
+| xcuitest | `{app-dir}/e2e/screenshots/xcuitest/{TestClass}/{testMethod}-{n}.png` |
+| webdriverio | `{app-dir}/e2e/screenshots/webdriverio/{spec}-{state}.png` |
+| vscode-test | `{app-dir}/e2e/screenshots/vscode/{suite}-{test}.png` (SD-3: may be empty for behavior-only extensions) |
+
+SD-3: the vscode-test committed dir may be empty for behavior-only extensions (no visual surface); the agent must still emit `e2e_gallery: []` explicitly. `cbp-task-check` Phase 4 treats an empty `e2e_gallery[]` as allowed when `vscode-test` is the ONLY eligible framework.
+
+**Gitignore caution**: root `.gitignore` ignores `apps/web/e2e/screenshots/`. For the `{app-dir}`-relative frameworks (xcuitest, webdriverio, vscode-test), `{app-dir}` MUST NOT resolve to `apps/web` — committed PNGs there would be silently dropped from git. Remedy: use a non-ignored subdir (e.g. `apps/web/e2e/baselines/<framework>/`). A `.gitignore` negation (`!apps/web/e2e/screenshots/<framework>/`) does NOT work — git does not recurse into an ignored parent directory, so PNGs in that subdir would be silently dropped on a fresh checkout. Maestro (repo-root `e2e/screenshots/maestro/`) is already safe.
+
+`is_new` detection: `git ls-files --error-unmatch <path>` exits non-zero → `is_new: true`
+(no committed baseline exists yet; auto-capture and `git add`). Exit zero → `is_new: false`.
+
+## Auto-New / Gated-Changed Update Model
+
+**NEW screens** (`is_new === true`): the specialist auto-captures the PNG and runs
+`git add <committed_path>`. The test passes; `cbp-frontend-ui` Step 5b reviews semantically.
+No user gate required for first-run capture.
+
+**EXISTING baselines that visually diff** (`is_new === false`, `baseline_diff_pct > threshold`):
+classify as `visual_regression`. Do NOT auto-update. Surface as a blocking accept-or-fix gate
+at `/cbp-round-end` Step 7. The user must explicitly approve (`--update-snapshots`) or open a
+fix task. This relaxes the prior always-manual contract ONLY for new screens.
+
 ## 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}`.
+After every run, enumerate all committed PNGs and populate BOTH `screenshots[]` and
+`e2e_gallery[]`. Framework-specific paths are in each agent's body. Every `screenshots[]`
+entry requires: `{test_name, path, page_or_screen, viewport, is_new, baseline_diff_pct}`.
+Every `e2e_gallery[]` entry requires: `{test_name, page_or_screen, framework, committed_path,
+is_new, baseline_diff_pct}`. `committed_path` MUST be a git-tracked path after the run.
+
+`/cbp-round-execute` Step 5b aggregates `e2e_gallery[]` across all specialists and stores it
+in `round.context.e2e_gallery`. TASK-3 / checkpoint-end consumes this aggregated gallery to
+upload images to the DB.
 
 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.
+**Changed baselines are never auto-accepted.** A `toHaveScreenshot` diff on an existing
+baseline is `visual_regression`; the user decides via QA whether to update baselines.
+New-screen auto-capture (above) is the only exception to the always-manual contract.
 
 ## Completion Rule
 
@@ -237,7 +283,9 @@ An agent is NOT spawned when ANY of the following hold:
 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.
+aggregates `screenshots[]` and `e2e_gallery[]` across all entries before the
+`cbp-frontend-ui` review. The aggregated `e2e_gallery[]` is persisted separately to
+`round.context.e2e_gallery` for consumption by TASK-3 / checkpoint-end.
 
 **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
@@ -298,6 +346,6 @@ a loop, snapshot text/href BEFORE navigation rather than holding stale `Locator`
 
 | 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`. |
+| No baseline (new screen, `is_new: true`) | Playwright creates on first run; auto-committed; `git add` runs; `e2e_gallery[].is_new: true`; `cbp-frontend-ui` Step 5b reviews semantically. No user gate. |
+| Baseline exists, diff ≤ threshold | Test passes; `is_new: false`; `baseline_diff_pct` recorded. |
+| Baseline exists, diff > threshold | `visual_regression` failure; `is_new: false`. Agent does NOT retry. `cbp-frontend-ui` Step 5b flags it; `/cbp-round-end` Step 3b constructs user QA item. User decides: fix-task or `--update-snapshots`. |

package/templates/hooks/README.md

@@ -226,7 +226,7 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 ### `cbp-cmux-workspace-sync.sh` — SessionStart, matcher `*`
 
-On every session start, syncs the active [cmux](https://github.com/nicholasgasior/cmux) workspace title to the current git branch and the workspace description to the repo folder basename (the directory that contains `.git/`).
+On every session start, syncs the active [cmux](https://github.com/nicholasgasior/cmux) workspace title to the current git branch, the workspace description to the repo folder basename (the directory that contains `.git/`), and applies the workspace color from `.codebyplan/cmux.json` via `cmux workspace-action --action set-color`. All three actions are delegated to `codebyplan cmux-sync`. If no `workspace_color` is configured, a one-line nudge is printed to stdout prompting the user to run `/cbp-setup-cmux`.
 
 **Blocks vs warns**: never blocks — exit 0 on every path. A SessionStart hook must never prevent a session from opening.
 
@@ -252,6 +252,28 @@ After any Bash tool call that contains a `git checkout` or `git switch` invocati
 
 ---
 
+### Auto dev server (`codebyplan cmux-serve`)
+
+At the start of each round, `cbp-round-execute` (Step 2a) calls `codebyplan cmux-serve --files "<round files>"` to auto-start the dev server for any app whose source files are touched. The subcommand probes each allocated port via `node:net`, starts a `cmux new-split` terminal pane + sends the dev command for any non-listening app, then opens a browser pane. If the port is already listening (another worktree) it only opens the browser pane. No hook registration is needed — the skill invokes the subcommand directly. Gated by `auto_dev_server` in `.codebyplan/cmux.json`; no-op outside cmux.
+
+---
+
+### Status surface (`codebyplan cmux-status`)
+
+The lifecycle skills push CodeByPlan development state into the cmux workspace sidebar via `codebyplan cmux-status`. No hook registration is needed — the skills invoke the subcommand directly:
+
+| Skill | What is pushed |
+| --- | --- |
+| `cbp-task-start` (Step 4.5) | `--checkpoint "CHK-NNN: title" --task "TASK-N: title"` |
+| `cbp-task-complete` (Step 7.3) | `--task "TASK-N: title done" --progress completed/total` |
+| `cbp-round-execute` (Step 3d) | `--qa "R{n} {status}"` where status ∈ completed / blocked / re-triggering |
+
+**`auto_status` toggle.** Gated by the `auto_status` field in `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). When `auto_status` is `false`, every call is a no-op. Default is `true` (enabled).
+
+**No-op outside cmux.** `codebyplan cmux-status` checks for `$CMUX_WORKSPACE_ID` before doing anything. Outside a cmux workspace it exits immediately — safe to call unconditionally from skills and hooks.
+
+---
+
 ## Supporting (not registered)
 
 ### `test-hooks.sh` — invoked by `auto-test-hooks.sh`

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

@@ -12,7 +12,7 @@
 _SUB='(templates|examples|reference|scripts)/[a-z0-9.-]+\.(md|sh|json|ya?ml)'
 enforce_path_pattern '^/\.claude/skills/' "^/\.claude/skills/[a-z0-9-]+/(SKILL\.md|[a-z0-9-]+\.md|${_SUB})$" 'Invalid skill path' "Pattern: /.claude/skills/{name}/SKILL.md | /.claude/skills/{name}/{file}.md | /.claude/skills/{name}/(templates|examples|reference|scripts)/{file}.{md,sh,json,yaml}"
 enforce_path_pattern '^/\.claude/agents/' "^/\.claude/agents/([a-z0-9-]+\.md|[a-z0-9-]+/(AGENT\.md|[a-z0-9-]+\.md|${_SUB}))$" 'Invalid agent path' "Pattern: /.claude/agents/{name}.md | /.claude/agents/{name}/AGENT.md | /.claude/agents/{name}/{file}.md | /.claude/agents/{name}/(templates|examples|reference|scripts)/{file}.{md,sh,json,yaml}"
-enforce_path_pattern '^/\.claude/rules/' '^/\.claude/rules/[a-z-]+\.md$' 'Invalid native rule path' 'Pattern: /.claude/rules/{name}.md'
+enforce_path_pattern '^/\.claude/rules/' '^/\.claude/rules/[a-z0-9-]+\.md$' 'Invalid native rule path' 'Pattern: /.claude/rules/{name}.md'
 if match_path '^/\.claude/hooks/' && ! match_path '^/\.claude/hooks/__test-fixtures__/'; then
   if ! match_path '^/\.claude/hooks/[a-z-]+\.sh$'; then
     block 'Invalid hook path' 'Pattern: /.claude/hooks/{name}.sh'

package/templates/rules/e2e-mandatory.md

@@ -61,10 +61,27 @@ A spec that ran with `passed === 0 && skipped > 0` for any path touching `files_
 **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.
 
+## Committed-Screenshot Enforcement
+
+An eligible e2e run that produces **zero committed screenshots** for any `pages_affected`
+path it touched is a defect — not a valid pass. Every framework must write at least one
+PNG to its committed dir (per the table in `context/testing/e2e.md` § Committed-Screenshot
+Mandate) and `git add` it before reporting `status: 'completed'`.
+
+`cbp-task-check` refuses a READY verdict when `e2e_gallery[]` is empty AND the round
+touched UI source paths for an eligible framework — sole exception: `vscode-test`-only
+rounds (SD-3, behavior-only extensions; see below). The fix path is the same as for a
+zero-assertion run: open a fix round that captures the missing committed screenshots.
+
+The sole exception is `vscode-test`: the committed dir may be empty when the extension
+has no visual output (behavior-only tests). Agents must still define the dir and report
+`e2e_gallery: []` explicitly — not omit the field.
+
 ## 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.
+  committed-screenshot mandate, auto-new/gated-changed model, and dispatch routing table.
+- `agents/cbp-task-check.md` — enforces the zero-assertion hard-fail and the empty
+  `e2e_gallery[]` 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.

package/templates/settings.project.base.json

@@ -88,7 +88,9 @@
       "Bash(codebyplan ship:*)",
       "Bash(npx codebyplan ship:*)",
       "Bash(codebyplan claude:*)",
-      "Bash(npx codebyplan claude:*)"
+      "Bash(npx codebyplan claude:*)",
+      "Bash(codebyplan upload-e2e-images:*)",
+      "Bash(npx codebyplan upload-e2e-images:*)"
     ],
     "allow": [
       "Skill(cbp-build-cc-agent)",
@@ -122,12 +124,23 @@
       "Skill(cbp-round-update)",
       "Skill(cbp-session-end)",
       "Skill(cbp-session-start)",
+      "Skill(cbp-setup-cmux)",
       "Skill(cbp-setup-e2e)",
       "Skill(cbp-setup-eslint)",
       "Skill(cbp-ship-configure)",
+      "Skill(cbp-standalone-task-check)",
+      "Skill(cbp-standalone-task-complete)",
+      "Skill(cbp-standalone-task-create)",
+      "Skill(cbp-standalone-task-start)",
+      "Skill(cbp-standalone-task-testing)",
       "Skill(cbp-supabase-branch-check)",
       "Skill(cbp-supabase-migrate)",
       "Skill(cbp-supabase-setup)",
+      "Skill(cbp-standalone-task-check)",
+      "Skill(cbp-standalone-task-complete)",
+      "Skill(cbp-standalone-task-create)",
+      "Skill(cbp-standalone-task-start)",
+      "Skill(cbp-standalone-task-testing)",
       "Skill(cbp-task-check)",
       "Skill(cbp-task-complete)",
       "Skill(cbp-task-create)",
@@ -189,6 +202,10 @@
       "Bash(npx codebyplan resolve-worktree:*)",
       "Bash(codebyplan cmux-sync:*)",
       "Bash(npx codebyplan cmux-sync:*)",
+      "Bash(codebyplan cmux-status:*)",
+      "Bash(npx codebyplan cmux-status:*)",
+      "Bash(codebyplan cmux-serve:*)",
+      "Bash(npx codebyplan cmux-serve:*)",
       "Bash(codebyplan version-status:*)",
       "Bash(npx codebyplan version-status:*)",
       "Bash(codebyplan statusline:*)",

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

@@ -113,6 +113,22 @@ If `/cbp-ship` reports `aborted_at` (user aborted) or any surface failed verific
 
 If the repo has zero configured surfaces (very early-stage), `/cbp-ship` exits with `## No deployable surfaces configured` — that's a success state, continue to cleanup.
 
+### Step 7.5: Upload E2E Screenshots to DB (best-effort)
+
+After `/cbp-ship` completes successfully, upload the checkpoint's new/changed committed E2E screenshots to the CodeByPlan DB so they can be reviewed per-checkpoint in the web UI (CHK-171). This step is **best-effort and non-blocking** — a failure here MUST NOT halt shipment or cleanup.
+
+```bash
+npx codebyplan upload-e2e-images "$CHECKPOINT_ID" --repo-id "$REPO_ID" --base-branch "$BASE" --json
+```
+
+The command collects only the PNGs added/changed on the feat branch vs `$BASE` (this checkpoint's own e2e work — not the whole baseline set), POSTs them to `POST /api/checkpoint-images`, and the endpoint stores each file + patches `checkpoints.e2e_screenshots`. Capture the outcome into `E2E_IMAGES_UPLOADED` for Step 10:
+
+- Exit 0 with uploaded paths → `{ count: <n>, stored_paths: [...], skipped: false }`.
+- Exit 0 with `No new/changed e2e screenshots found` → `{ count: 0, stored_paths: [], skipped: true }`.
+- Non-zero exit → `{ count: 0, stored_paths: [], skipped: true, error: "<stderr summary>" }`; emit a non-blocking warning and continue to Step 8.
+
+`--repo-id` defaults to `repo_id` from `.codebyplan/repo.json` when omitted.
+
 ### Step 8: Stale Feat Branch Cleanup
 
 After successful shipment, identify stale remote feat branches:
@@ -202,7 +218,8 @@ context.shipment: {
   skipped: [...],           // populated by /cbp-ship — surfaces explicitly skipped
   stale_branches_cleaned: [list of deleted git branches],
   feat_branch_deleted: true/false,
-  supabase_branches_deleted: [list of Supabase preview branch names removed in Steps 8–9]
+  supabase_branches_deleted: [list of Supabase preview branch names removed in Steps 8–9],
+  e2e_images_uploaded: E2E_IMAGES_UPLOADED   // from Step 7.5 — { count, stored_paths, skipped, error? } (CHK-171)
 }
 ```
 

package/templates/skills/cbp-frontend-ui/SKILL.md

@@ -41,8 +41,8 @@ input:
       path: string                          # Repo-relative or absolute path to PNG
       page_or_screen: string
       viewport: 'desktop' | 'mobile' | 'tablet' | 'device'
-      is_new: bool                          # No baseline existed (new screen)
-      baseline_diff_pct: number | null      # Pixel-diff % vs Playwright baseline
+      is_new: bool                          # true = no prior committed baseline; auto-captured+committed this run
+      baseline_diff_pct: number | null      # Pixel-diff % vs committed baseline (null for non-playwright frameworks)
 ```
 
 ## Output Contract
@@ -167,9 +167,10 @@ If no design source PNGs exist for the changed pages, skip this phase.
 For each screenshot in `e2e_screenshots[]`:
 
 1. **Read the PNG via the Read tool** (Claude multimodal — the PNG is shown to the model directly). Do not use Bash to inspect bytes.
-2. **Check baseline regression** (`baseline_diff_pct != null`):
-   - If `baseline_diff_pct > 0.1%`: emit finding `{category: 'baseline_regression', severity: 'critical', file: {path}, screenshot: {path}, issue: 'Pixel diff vs committed baseline: {diff_pct}%', suggestion: 'Inspect the diff PNG (same folder, -diff suffix). Either fix the regression or, if intentional, run `playwright test --update-snapshots` and commit the new baseline.'}`
-   - Do NOT auto-update baselines. The user must explicitly approve via QA.
+2. **Check new vs changed baseline**:
+   - `is_new === true`: screenshot was auto-captured and committed this run (no prior baseline). Review semantically only — no regression to flag. Populate `screenshot_review.new_screens_reviewed`.
+   - `is_new === false` AND `baseline_diff_pct > 0.1%`: emit finding `{category: 'baseline_regression', severity: 'critical', file: {path}, screenshot: {path}, issue: 'Pixel diff vs committed baseline: {diff_pct}%', suggestion: 'Inspect the diff PNG (same folder, -diff suffix). Either fix the regression or, if intentional, run `playwright test --update-snapshots` and commit the new baseline.'}`
+   - Do NOT auto-update changed baselines. The user must explicitly approve via QA.
 3. **Semantic review of rendered output** (both new screens and existing):
    - **Text overflow / truncation** — text clipped, ellipsis in unintended places, buttons cut off
    - **Unstyled elements** — unbranded default fonts, missing styles (flash of unstyled content captured), default blue links
@@ -237,7 +238,8 @@ Go beyond fixing violations — actively improve visual quality. If spacing coul
 - Token compliance checked
 - Spacing consistency verified
 - **All `e2e_screenshots` reviewed** (when provided) — rendered output checked for overflow, unstyled elements, missing imagery, contrast, layout breaks, loading/error artifacts, design-source fidelity
-- Baseline regressions surfaced (never auto-accepted)
+- New-screen baselines reviewed semantically (`is_new === true` — auto-committed, no user gate)
+- Changed-baseline regressions surfaced (never auto-accepted; `is_new === false` AND diff > threshold)
 - Critical/warning issues auto-fixed where possible (styling only, in-scope only)
 - Findings categorized by severity
 
@@ -258,5 +260,5 @@ Go beyond fixing violations — actively improve visual quality. If spacing coul
 - **Also invoked by**: `/cbp-checkpoint-check` with screenshots aggregated from a whole-checkpoint e2e run
 - **Consumes**: `e2e_screenshots[]` aggregated from `round.context.e2e_outputs[*].screenshots` (populated by the `cbp-e2e-*` specialists at `/cbp-round-execute` Step 5)
 - **Output written to**: `round.context.frontend_ui_review` — when invoked twice per round, the second invocation merges with the first
-- **Downstream gate**: this skill emits `findings[]` only. Baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (baselines never auto-accepted); rendered-visual critical findings are surfaced in the Step 7 findings presentation.
+- **Downstream gate**: this skill emits `findings[]` only. Changed-baseline-regression findings (`is_new === false`) surface as a BLOCKING gate at `/cbp-round-end` Step 7 (never auto-accepted); new-screen baselines (`is_new === true`) are auto-committed and reviewed semantically only; rendered-visual critical findings are surfaced in the Step 7 findings presentation.
 - **Paired with**: `frontend-design` (pre-implementation aesthetic decision), `frontend-ux` (interaction-quality self-review, also Step 3.8)