codebyplan 1.13.55 → 1.13.57

package/package.json

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

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

@@ -132,7 +132,8 @@ One subdirectory per app module. Shared flows under `_shared/`. Probe under `_pr
 
 ## Spec-Writing Patterns
 
-**One flow per screen/feature.** Steps:
+**One flow per screen/feature.** A flow that only taps and asserts visibility is NOT done —
+prove behavior:
 
 ```yaml
 appId: ${APP_ID}
@@ -141,15 +142,97 @@ tags:
 ---
 - runFlow: _shared/login.yaml
 - assertVisible: "Dashboard"
-- takeScreenshot: "dashboard-loaded"
-- tapOn: "Create"
+- waitForAnimationToEnd
+- assertNoDefectsWithAI:       # AI visual-defect check — see AI Assertions below
+    optional: false
+- takeScreenshot: "dashboard-loaded"   # NEW states only — see Visual Baselines
+- tapOn:
+    text: "Create"
+    enabled: true              # state selector — waits for interactivity, catches broken gating
 - assertVisible: "New item"
-- takeScreenshot: "create-modal-open"
 ```
 
 Use text-based targeting first (`tapOn: "Button"`); use testID when ambiguous
-(`tapOn: { id: "btn" }`). For CRUD: create + verify visible; edit + verify updated;
-delete + confirm + verify removed.
+(`tapOn: { id: "btn" }`). `text`/`id` are REGEX by default — escape `$` and `[`; quote
+`YES`/`NO`/`ON`/`OFF` (unquoted they parse as YAML booleans).
+
+**Assertion depth requirements**:
+
+- **State selectors prove logic**: `enabled`, `checked`, `focused`, `selected` — e.g. assert
+  Submit is `enabled: false` before required fields are filled, `enabled: true` after.
+- **Data round-trips** via `copyTextFrom` + `assertTrue`: copy the value on screen A
+  (snapshot into `output.*` via `evalScript` before the next copy overwrites
+  `maestro.copiedText`), navigate, assert screen B shows the same value.
+- **Persistence proof** for create/edit flows — after the UI reports success, verify via
+  `runScript` `http.get` against the backend API (`json()` parse + `assertTrue` on the
+  field), or at minimum kill + relaunch and re-assert:
+
+  ```yaml
+  - killApp
+  - launchApp: { stopApp: false }
+  - assertVisible: ${output.createdTitle}
+  ```
+
+- For CRUD: create + verify (round-trip); edit + verify updated; delete + confirm + verify
+  removed.
+
+## Visual Baselines (assertScreenshot)
+
+Committed PNGs under `e2e/screenshots/maestro/` are BASELINES, not run artifacts.
+
+- **New state** (`git ls-files --error-unmatch <path>` exits non-zero): `waitForAnimationToEnd`,
+  then `takeScreenshot: "{flow}-{state}"` and `git add` the PNG (auto-new model).
+- **Existing baseline**: do NOT retake/overwrite. Assert against it:
+
+  ```yaml
+  - waitForAnimationToEnd
+  - assertScreenshot:
+      path: e2e/screenshots/maestro/{flow}-{state}.png
+      thresholdPercentage: 95
+  ```
+
+  On failure classify `visual_regression`: capture the live screen under a transient
+  diagnostic name (`{flow}-{state}-actual`, written to `--test-output-dir`), report it in
+  `screenshots[]`, and NEVER overwrite the committed baseline. The user accepts the change at
+  `/cbp-verify`; only then is the baseline re-captured and re-added.
+- `baseline_diff_pct` stays `null` (Maestro reports threshold pass/fail, not a percentage);
+  set `is_new` per git tracking as before.
+
+## AI Assertions (assertNoDefectsWithAI / assertWithAI)
+
+Maestro's AI commands screenshot the current screen and detect rendering defects (cut-off
+text, overlapping elements, mis-centered content). Run `assertNoDefectsWithAI` at every
+primary screen state; use `assertWithAI` for states selectors can't express:
+
+```yaml
+- assertNoDefectsWithAI:
+    optional: false
+- assertWithAI:
+    assertion: The 6-digit verification input is visible with all six boxes empty.
+    optional: false
+```
+
+**Critical**: AI commands default to `optional: true` (warn-only — a detected defect does
+NOT fail the flow). ALWAYS set `optional: false`.
+
+**Auth preflight (Step 6.5.1 addition)**: AI commands require Maestro auth — a `maestro login`
+session or `MAESTRO_CLOUD_API_KEY` (a free account suffices; the legacy `MAESTRO_CLI_AI_KEY`
+BYO-key path is retired). Probe before authoring AI steps. When unavailable, ask the user once
+(provide key / skip AI), record `ai_checks: 'unavailable'` in the output, omit AI commands,
+and rely on `assertScreenshot` baselines — never let an AI step fail a run on a missing key.
+AI artifacts (`ai-report-*.html`, `ai-*.json`) land under `--test-output-dir`; reference them
+in `critical_issues[].reason` when a defect is found.
+
+## Anti-Patterns
+
+- `waitForAnimationToEnd` is NOT an assertion — it succeeds even on timeout; always pair it
+  with a real assert or screenshot.
+- Don't wrap whole flows in `retry` (hides product flakiness); bound `repeat` loops with
+  `times` + `while` together.
+- No `point:` coordinate taps — device-dependent; combine attribute + relational selectors instead.
+- Don't max out timeouts ("60s everywhere") — defaults catch performance regressions.
+- Platform limits: `back` is Android/Web only; airplane-mode commands are Android-only;
+  Android `inputText` is ASCII-only; system biometric/HealthKit dialogs need XCUITest.
 
 ## Screenshot Capture
 
@@ -161,7 +244,9 @@ Screenshots written to `e2e/screenshots/maestro/` (via `screenshotsDir` in `conf
 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.
+After the flow completes, `git add` each NEW PNG individually — never `git add` the whole
+directory (that silently stages drifted baselines; existing states are gated by
+`assertScreenshot`, see Visual Baselines).
 
 **`is_new` detection**: `git ls-files --error-unmatch <path>` exits non-zero → `is_new: true`.
 
@@ -186,9 +271,13 @@ Include this in the specialist output alongside `screenshots[]`.
 ## Run Command
 
 ```bash
-maestro test maestro/flows/{module}/{flow}.yaml --format=junit --output maestro/results.xml
+maestro test maestro/flows/{module}/{flow}.yaml --format junit --output maestro/results.xml \
+  --test-output-dir maestro/output
 ```
 
+`maestro/output/` holds transient diagnostics (AI reports, `-actual` regression captures) —
+gitignore it; committed baselines live only under `e2e/screenshots/maestro/`.
+
 ## pnpm Scripts
 
 ```json

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

@@ -21,7 +21,7 @@ accordingly.
 ## Install
 
 ```bash
-pnpm add -D @playwright/test
+pnpm add -D @playwright/test @axe-core/playwright
 pnpm exec playwright install chromium
 # CI with system deps:
 pnpm exec playwright install --with-deps chromium
@@ -265,32 +265,123 @@ port from `.codebyplan/server.local.json` (worktree overlay, checked first) then
 `.codebyplan/server.json` (committed base). On mismatch ask which is correct, then propose
 an Edit to align them.
 
+## Quality Fixture (MANDATORY)
+
+`apps/{app}/e2e/fixtures.ts` — the single `test` source for ALL specs. It auto-enforces the
+console-clean mandate (an `{ auto: true }` fixture runs in every test with zero per-spec
+opt-in) and provides the axe builder. Create it if absent; when touching an existing spec
+that still imports from `@playwright/test`, migrate its import.
+
+```ts
+import { test as base, expect } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+// Known, triaged errors only — every entry needs a comment linking its fix task.
+const ALLOWED_CONSOLE: RegExp[] = [];
+
+type QualityFixtures = {
+  consoleGuard: void;
+  makeAxeBuilder: () => AxeBuilder;
+};
+
+export const test = base.extend<QualityFixtures>({
+  consoleGuard: [
+    async ({ page, baseURL }, use) => {
+      const errors: string[] = [];
+      page.on("console", (msg) => {
+        if (msg.type() === "error" && !ALLOWED_CONSOLE.some((re) => re.test(msg.text())))
+          errors.push(`console.error: ${msg.text()}`);
+      });
+      page.on("pageerror", (err) => errors.push(`pageerror: ${err.message}`));
+      page.on("requestfailed", (req) => {
+        // Own-origin, non-aborted failures only (cancelled prefetches are noise)
+        if (baseURL && req.url().startsWith(baseURL) && req.failure()?.errorText !== "net::ERR_ABORTED")
+          errors.push(`requestfailed: ${req.method()} ${req.url()} — ${req.failure()?.errorText}`);
+      });
+      await use();
+      expect(errors, "console/page errors captured during test").toEqual([]);
+    },
+    { auto: true },
+  ],
+  makeAxeBuilder: async ({ page }, use) => {
+    await use(() => new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]));
+  },
+});
+export { expect };
+```
+
+Collected errors from failing tests feed the `console_errors[]` output field (see Output
+Additions below).
+
 ## Spec-Writing Patterns
 
-**One spec file per page/flow.** Mandatory per spec:
+**One spec file per page/flow.** Specs import `{ test, expect }` from the quality fixture
+(`./fixtures` or relative path) — NEVER directly from `@playwright/test`.
 
-- Smoke test: loads, title correct, no console errors.
-- Primary user flow: main interaction.
+Mandatory per spec — a spec that only proves elements are visible is NOT done:
+
+- Smoke test: loads, title correct (the console guard fails it on any console/page error).
+- Primary user flow: main interaction **with a behavior proof** (below).
 - Visual regression: `toHaveScreenshot` at every primary state.
+- Structure: `toMatchAriaSnapshot` on the primary state — catches hierarchy/label/role
+  breakage without pixel fragility.
+- Accessibility: one axe scan per page state, zero violations.
+
+### Functional Proof (mutations)
 
-For forms: fill + submit + verify success; validation errors.
-For CRUD: create + verify; edit + verify; delete + confirm + verify.
+Every flow that mutates state MUST prove the mutation happened — asserting the optimistic UI
+is not proof:
 
 ```ts
-import { test, expect } from "@playwright/test";
+// 1. Prove the API call succeeded
+const resp = page.waitForResponse((r) => r.url().includes("/api/items") && r.request().method() === "POST");
+await page.getByRole("button", { name: "Create" }).click();
+expect((await resp).status()).toBeLessThan(400);
+
+// 2. Prove persistence — reload and re-assert (or poll the API for eventual consistency)
+await page.reload();
+await expect(page.getByRole("listitem").filter({ hasText: itemName })).toBeVisible();
+// await expect.poll(async () => (await page.request.get(`/api/items/${id}`)).status()).toBe(200);
+```
 
-test.describe("Home page", () => {
-  test.beforeEach(async ({ page }) => {
-    await page.goto("/");
-  });
+### Error-State Proof (forms / CRUD)
 
-  test("loads and shows heading", async ({ page }) => {
-    await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
-    await expect(page).toHaveScreenshot("home-loaded.png", { maxDiffPixelRatio: 0.001 });
-  });
+At least one test per form/CRUD spec injects a failure and asserts the rendered error UI —
+error paths are where untested UIs break in production:
+
+```ts
+await page.route("**/api/items", (r) => r.fulfill({ status: 500 }));
+await page.getByRole("button", { name: "Create" }).click();
+await expect(page.getByRole("alert")).toContainText(/failed|went wrong/i);
+```
+
+### Permission / RLS Proof
+
+When the route is role-gated, include one denial test (lower-privilege storage state or
+seeded non-member): assert the explicit denial UI or redirect — a blank render is a bug,
+not a pass.
+
+### Accessibility Scan
+
+```ts
+test("a11y: dashboard has no WCAG A/AA violations", async ({ page, makeAxeBuilder }) => {
+  await page.goto("/dashboard");
+  const results = await makeAxeBuilder().analyze();
+  expect(results.violations).toEqual([]);
 });
 ```
 
+Known issues are excluded via `.disableRules([...])` with a comment linking the fix task —
+never by deleting the scan.
+
+### Anti-Patterns (reject in review)
+
+- `page.waitForTimeout(...)` — web-first assertions auto-retry; hard sleeps mask races.
+- `expect(await locator.isVisible()).toBe(true)` — one-shot, no retry; use `await expect(locator).toBeVisible()`.
+- `.nth(n)` / `.first()` positional selection — except the documented SCSS-module fallback.
+- In-spec env skips (`test.skip(!process.env.X, ...)`) — forbidden per `rules/e2e-mandatory.md`.
+- Visibility-only assertions after a mutation — see Functional Proof.
+
 ## Screenshot Capture
 
 **Baseline regression** (preferred):
@@ -332,6 +423,18 @@ when the playwright.config project/device emulation indicates a mobile viewport
 
 Include this in the specialist output alongside `screenshots[]`.
 
+## Output Additions (Playwright)
+
+Beyond the shared contract, ALWAYS report:
+
+- `console_errors[]` — every entry the console guard collected on failed tests
+  (`{test_name, type: 'console' | 'pageerror' | 'requestfailed', text}`). Empty array on a
+  clean run — never omit the field.
+- `a11y` — `{scanned_pages: string[], violations: [{rule, impact, page}]}` aggregated from
+  the axe scans. A `status: 'completed'` output with non-empty `violations` is inconsistent —
+  fix in-scope or classify the failures as category `a11y`; `codebyplan e2e verify-round`
+  hard-fails the inconsistency.
+
 ## Run Command
 
 ```bash

package/templates/agents/cbp-verify-reviewer.md

@@ -202,6 +202,14 @@ The deterministic e2e gate (`codebyplan e2e verify-round`) and the unit/lint/typ
 here). If the diff touches an e2e-eligible UI surface, note it in `summary` so the orchestrator
 confirms its gate ran — but do not assert a build/test result this agent did not run.
 
+E2E verdict gates (refuse `READY` per `rules/e2e-mandatory.md`): a zero-assertion run
+(`passed === 0 && skipped > 0` on a touched path); an empty `e2e_gallery[]` when the round
+touched UI for an eligible framework (sole exception: `vscode-test`-only rounds with explicit
+`e2e_gallery: []`); a `status: 'completed'` e2e output carrying non-empty `console_errors[]`
+or `a11y.violations[]`. Treat a `{type: 'shallow_coverage'}` critical issue on a mutation
+surface as a real finding (visibility-only specs prove rendering, not behavior) — severity
+`medium` minimum, routed to a follow-up round.
+
 ### Phase 6: Build Findings, Verdict & Routing
 
 Assign severity by impact: `critical` (runtime error / data corruption / security), `high`

package/templates/context/testing/e2e.md

@@ -54,7 +54,7 @@ output:
       - test_name: string
         error: string
         file: string
-        category: 'env' | 'auth' | 'access' | 'flake' | 'real' | 'visual_regression'
+        category: 'env' | 'auth' | 'access' | 'flake' | 'real' | 'visual_regression' | 'console_error' | 'a11y'
         classification_reason: string
   framework_configured: boolean
   preflight:
@@ -77,6 +77,17 @@ output:
       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
+  console_errors:                        # REQUIRED for playwright (empty array on a clean run);
+    - test_name: string                  # null/omitted for frameworks without console capture
+      type: 'console' | 'pageerror' | 'requestfailed'
+      text: string
+  a11y:                                  # REQUIRED for playwright; null/omitted otherwise
+    scanned_pages: string[]
+    violations:
+      - rule: string                     # axe rule id (e.g. color-contrast)
+        impact: string                   # critical | serious | moderate | minor
+        page: string
+  ai_checks: 'ran' | 'unavailable' | null  # maestro only — AI assertion availability (see agent body)
   user_interactions: [{question, answer}]
   tech_stack_reconciliation:
     db_framework: string | null
@@ -177,12 +188,32 @@ For each failed test, assign exactly one category:
 | `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. |
+| `visual_regression` | `toHaveScreenshot` / `assertScreenshot` diff exceeded threshold | Do NOT retry. Include baseline + actual paths in `screenshots[]` with `baseline_diff_pct`. Do NOT auto-accept baselines. |
+| `console_error` | Console guard collected console/page/request errors during the flow | App defect — fix in-scope or report; never allowlist without a linked fix task |
+| `a11y` | Axe scan reported WCAG A/AA violations | Do NOT retry. Report rule ids in `a11y.violations`; fix in-scope or surface at `/cbp-verify` |
 | `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.
 
+## Functional Assertion Mandate
+
+Visibility-only specs are NOT sufficient coverage — they prove rendering, not behavior.
+Every spec/flow covering a mutation (create / edit / delete / submit) MUST include at
+least one behavior proof:
+
+- **network success proof** — response-status assertion on the mutating call
+  (`waitForResponse` in Playwright; `runScript` `http.*` in Maestro), AND/OR
+- **persistence proof** — reload / kill-and-relaunch / direct API re-read showing the
+  change survived, PLUS
+- **one error-state test per form/CRUD surface** — inject a failure (`page.route` 500 in
+  Playwright) and assert the rendered error UI.
+
+When a suite's assertions are entirely visibility/navigation-level, the specialist MUST
+report `critical_issues[]` entry `{type: 'shallow_coverage', ...}` — the run may pass, but
+the gap is flagged for the next round. `cbp-verify-reviewer` treats `shallow_coverage` on a
+mutation surface as a finding, not noise.
+
 ## Committed-Screenshot Mandate
 
 Every eligible e2e run MUST persist relevant screenshots to the framework's committed
@@ -215,6 +246,11 @@ classify as `visual_regression`. Do NOT auto-update. Surface as a blocking accep
 at `/cbp-verify` (round scope). The user must explicitly approve (`--update-snapshots`) or open a
 fix task. This relaxes the prior always-manual contract ONLY for new screens.
 
+The model applies to ALL screenshot-capable frameworks, not just Playwright: Maestro gates
+existing baselines with `assertScreenshot` against the committed PNG (the agent never
+retakes/overwrites an existing baseline; acceptance = re-capture + `git add` after user
+approval at `/cbp-verify`).
+
 ## Screenshot Collection Rule
 
 After every run, enumerate all committed PNGs and populate BOTH `screenshots[]` and
@@ -242,6 +278,11 @@ New-screen auto-capture (above) is the only exception to the always-manual contr
 - `tests_run === true`
 - `preflight.*.ok === true` for every required prerequisite
 - Every failure has `category` other than `env`, `auth`, or `access`
+- `console_errors[]` is empty and `a11y.violations[]` is empty (where the framework reports
+  them — Playwright always does). Non-empty values with `status: 'completed'` are
+  inconsistent and hard-fail `codebyplan e2e verify-round` (`console_errors_reported`,
+  `a11y_violations_reported`); either fix in-scope or return `status: 'failed'` with the
+  matching failure category.
 
 Otherwise return `status: 'failed'`.
 

package/templates/github-workflows/ci.yml

@@ -17,9 +17,10 @@
 # Two jobs:
 #   ci         SOFT tier (authoritative required check) — the baseline-tolerant
 #              inner loop: lint, typecheck, test, build across the repo.
-#   ci-strict  HARDCORE tier (report-only) — whole-repo ABSOLUTE GREEN via
-#              `codebyplan check --scope merged --no-baseline`. Non-blocking for
-#              now; flip to a required check once the repo is absolute-green.
+#   ci-strict  HARDCORE tier — whole-repo ABSOLUTE GREEN via
+#              `codebyplan check --scope merged --no-baseline`. Report-only by
+#              default; set `workflow.strict_check_enforced: true` in
+#              `.codebyplan/ci.json` to make it a real gate (then enforce-check).
 
 name: CI
 
@@ -69,19 +70,21 @@ jobs:
       - name: Build
         run: pnpm turbo build
 
-  # ── HARDCORE strict tier (report-only) ──────────────────────────────────────
+  # ── HARDCORE strict tier ────────────────────────────────────────────────────
   # Whole-repo ABSOLUTE GREEN: `codebyplan check --scope merged --no-baseline`
   # ignores .check-baseline.json entirely, so ANY failing package (lint,
-  # typecheck, test) fails this job. This is the future checkpoint→main gate.
+  # typecheck, test) fails this job. This is the checkpoint→main gate.
   #
-  # report-only until apps/web baseline is burned down; flip to required after.
-  # `continue-on-error: true` keeps it non-blocking — the `ci` job above stays
-  # the authoritative required check. Do NOT wire this job as a branch-protection
-  # required check until the whole repo is absolute-green.
+  # report-only vs enforced is driven by `.codebyplan/ci.json`
+  # `workflow.strict_check_enforced` (scaffold-ci-workflow substitutes the
+  # tokens below): when false (default) the job name carries " (report-only)"
+  # and `continue-on-error: true` keeps it non-blocking; when true the suffix is
+  # dropped and `continue-on-error: false` makes it a real gate. Only flip the
+  # flag once the whole repo is absolute-green AND the job has run green in CI,
+  # then add it to branch protection via `codebyplan ci enforce-check`.
   ci-strict:
-    name: Strict whole-repo green (report-only)
-    runs-on: ubuntu-latest
-    continue-on-error: true
+    name: Strict whole-repo green{{STRICT_NAME_SUFFIX}}
+    runs-on: ubuntu-latest{{STRICT_CONTINUE_ON_ERROR_LINE}}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -112,10 +115,12 @@ jobs:
       # In the monorepo run the freshly-built bundle directly (the bin shim may
       # be missing because dist/cli.js did not exist at install time); in a
       # consumer repo that path is absent, so fall back to the installed bin.
+      # --concurrency=1 serializes turbo so the whole-repo matrix does not
+      # CPU-starve timing-sensitive test suites into flaky timeouts on the runner.
       - name: Strict check (no baseline)
         run: |
           if [ -f packages/codebyplan-package/dist/cli.js ]; then
-            node packages/codebyplan-package/dist/cli.js check --scope merged --no-baseline
+            node packages/codebyplan-package/dist/cli.js check --scope merged --no-baseline --concurrency=1
           else
-            pnpm exec codebyplan check --scope merged --no-baseline
+            pnpm exec codebyplan check --scope merged --no-baseline --concurrency=1
           fi

package/templates/hooks/cbp-statusline.mjs

@@ -420,9 +420,6 @@ function main() {
   if (shouldShow("PACKAGE_FRESHNESS", cfg.package_freshness)) {
     let guarded = false;
     let installed = "";
-    let newer = false;
-    let latest = "";
-    let inSync = true;
 
     const cachePath = path.join(
       root,
@@ -444,9 +441,6 @@ function main() {
           } else {
             installed =
               typeof cache.installed === "string" ? cache.installed : "";
-            newer = cache.newer === true;
-            latest = typeof cache.latest === "string" ? cache.latest : "";
-            inSync = cache.in_sync !== false;
           }
         }
       } catch {
@@ -466,21 +460,14 @@ function main() {
         guarded = true;
       } else {
         try {
-          const mRaw = fs.readFileSync(manifestPath, "utf8");
-          const mParsed = JSON.parse(mRaw);
-          const mVer =
-            typeof mParsed?.version === "string" ? mParsed.version : "";
+          // Reading + parsing the manifest validates it — unreadable/invalid
+          // JSON falls into the catch below and hides the segment. (The
+          // manifest-vs-installed ⟳ nag was removed in CHK-195.)
+          JSON.parse(fs.readFileSync(manifestPath, "utf8"));
           const pRaw = fs.readFileSync(pkgPath, "utf8");
           const pParsed = JSON.parse(pRaw);
-          const iVer =
+          installed =
             typeof pParsed?.version === "string" ? pParsed.version : "";
-          installed = iVer;
-          if (mVer && iVer && mVer !== iVer) {
-            // manifest ≠ installed → .claude is out of sync. The ⟳ nag was removed
-            // (CHK-195); only the bare version renders. inSync is retained for the
-            // guard shape but no longer drives any output.
-            inSync = false;
-          }
         } catch {
           // Can't read files → hide segment.
           guarded = true;
@@ -492,6 +479,26 @@ function main() {
       const L8 = `${C.DIM}cbp${C.RST} ${installed}`;
       out.push(L8);
     }
+
+    // Settings-contract violations (read from cache regardless of guard state).
+    if (fs.existsSync(cachePath)) {
+      try {
+        const cacheRaw2 = fs.readFileSync(cachePath, "utf8");
+        const cache2 = JSON.parse(cacheRaw2);
+        if (cache2 && typeof cache2 === "object") {
+          const settingsMissing = cache2.settings_missing === true;
+          const settingsIgnored = cache2.settings_ignored === true;
+          if (settingsMissing) {
+            out.push(`${C.RED}⚠ settings.json missing!${C.RST}`);
+          }
+          if (settingsIgnored) {
+            out.push(`${C.YELLOW}⚠ settings.json gitignored!${C.RST}`);
+          }
+        }
+      } catch {
+        // Unreadable / invalid → no indicators
+      }
+    }
   }
 
   process.stdout.write(out.length ? out.join("\n") + "\n" : "");

package/templates/hooks/cbp-statusline.py

@@ -401,6 +401,19 @@ def main():
             l8 = "%scbp%s %s" % (DIM, RST, _installed)
             out.append(l8)
 
+        # Settings-contract violations (read from cache regardless of guard state).
+        if os.path.isfile(cache_path):
+            try:
+                with open(cache_path, "r", encoding="utf-8") as fh:
+                    cache2 = json.load(fh)
+                if isinstance(cache2, dict):
+                    if cache2.get("settings_missing") is True:
+                        out.append("%s⚠ settings.json missing!%s" % (RED, RST))
+                    if cache2.get("settings_ignored") is True:
+                        out.append("%s⚠ settings.json gitignored!%s" % (YELLOW, RST))
+            except Exception:
+                pass  # Unreadable / invalid → no indicators
+
     sys.stdout.write(("\n".join(out) + "\n") if out else "")
 
 

package/templates/hooks/cbp-statusline.sh

@@ -494,4 +494,16 @@ if should_show PACKAGE_FRESHNESS "$CFG_PACKAGE_FRESHNESS"; then
     L8="${DIM}cbp${RST} ${_CBP_INSTALLED}"
     printf "%b\n" "$L8"
   fi
+
+  # Settings-contract violations (read from cache regardless of guard state).
+  if [ -f "$CBP_STATUS_CACHE" ] && command -v jq >/dev/null 2>&1; then
+    _CBP_SETTINGS_MISSING="$(jq -r '.settings_missing == true' "$CBP_STATUS_CACHE" 2>/dev/null)"
+    _CBP_SETTINGS_IGNORED="$(jq -r '.settings_ignored == true' "$CBP_STATUS_CACHE" 2>/dev/null)"
+    if [ "$_CBP_SETTINGS_MISSING" = "true" ]; then
+      printf "%b\n" "${RED}⚠ settings.json missing!${RST}"
+    fi
+    if [ "$_CBP_SETTINGS_IGNORED" = "true" ]; then
+      printf "%b\n" "${YELLOW}⚠ settings.json gitignored!${RST}"
+    fi
+  fi
 fi

package/templates/rules/e2e-mandatory.md

@@ -73,6 +73,27 @@ The sole exception is `vscode-test`: the committed dir may be empty when the ext
 has no visual output (behavior-only tests). Agents must still define the dir and report
 `e2e_gallery: []` explicitly — not omit the field.
 
+## Quality-Capture Mandates
+
+A green run that captured no quality signals is not evidence. Per framework:
+
+- **playwright**: every spec imports `test` from the shared quality fixture
+  (`e2e/fixtures.ts`) — console/pageerror guard auto-active in every test; one axe WCAG A/AA
+  scan per page state. The output MUST carry `console_errors[]` (empty on clean) and `a11y`
+  per `context/testing/e2e.md`.
+- **maestro**: existing committed screenshots are baselines — gate them with
+  `assertScreenshot` (never retake/overwrite); run `assertNoDefectsWithAI` with
+  `optional: false` at primary states when Maestro auth is available (the default
+  `optional: true` is warn-only and forbidden; record `ai_checks: 'unavailable'` when auth
+  is absent).
+- A `status: 'completed'` output carrying non-empty `console_errors[]` or
+  `a11y.violations[]` is inconsistent — `codebyplan e2e verify-round` hard-fails it
+  (`console_errors_reported`, `a11y_violations_reported`).
+
+Mutation flows MUST carry a behavior proof per `context/testing/e2e.md` § Functional
+Assertion Mandate (network success proof / persistence proof / error-state test);
+visibility-only suites are flagged `{type: 'shallow_coverage'}` in `critical_issues[]`.
+
 ## Cross-References
 
 - `context/testing/e2e.md` — Input/Output contract, pre-flight loop, failure classification,

package/templates/rules/two-tier-ci.md

@@ -47,13 +47,21 @@ The branch model is **feat→main direct**; `.codebyplan/git.json` has `integrat
 IS the per-checkpoint feat branch. The hardcore tier runs against that feat branch's merged
 state before it lands on main; do not assume a staging/integration hop exists.
 
-## Report-Only Rollout
+## Strict-Tier Enforcement (report-only ⇄ enforced)
 
-The whole-repo hardcore CI **job** lands **report-only first** (`continue-on-error: true`) and is
-flipped to a required check ONLY after the `apps/web` baseline is burned down. Until then,
-`--scope merged --no-baseline` is advisory in CI — surfaced, not enforced — so a pre-existing
-`apps/web` red does not block a merge while the baseline is still being paid down. Locally,
-`cbp-verify` still runs and reports it.
+The whole-repo hardcore CI **job** (`ci-strict`) is config-driven via `.codebyplan/ci.json`
+`workflow.strict_check_enforced`, which `codebyplan ci scaffold-workflow` substitutes into the
+generated `.github/workflows/ci.yml`:
+
+- **`false` (default)** — report-only: the job carries the " (report-only)" name suffix and
+  `continue-on-error: true`, so `--scope merged --no-baseline` is advisory in CI — surfaced, not
+  enforced. A repo whose baseline is still red keeps merging while it pays the baseline down.
+- **`true`** — enforced: the suffix is dropped and `continue-on-error` is omitted (defaults to
+  `false`), making the job a real gate. Flip ONLY after the whole repo is absolute-green AND the
+  job has already run green in CI, then wire the check name `Strict whole-repo green` into branch
+  protection via `codebyplan ci enforce-check --check-name "Strict whole-repo green"`.
+
+Locally, `cbp-verify` runs and reports the same check regardless of the flag.
 
 ## Cross-References