@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/provision-hetzner/test/fixture/provision-hetzner-dry-run.golden

@@ -0,0 +1,34 @@
+
+=== DRY RUN — No changes will be made ===
+
+--- Console guidance ---
+1. Log in to the tenant's Hetzner Cloud Console
+2. Create a sub-project named 'tenant-fixture-tenant-prd'
+3. Inside the sub-project, go to Security → API Tokens
+4. Create a project-scoped API token with Read+Write permissions
+5. Copy the token (shown only once)
+
+--- Smoke-test commands (run after token creation) ---
+read -rs -p 'Hetzner token: ' HCLOUD_TOKEN; echo
+(
+  export HCLOUD_TOKEN
+  hcloud server create --name 'probe-provision-fixture-tenant' --type cx11 --image ubuntu-22.04 --location nbg1
+  hcloud server delete 'probe-provision-fixture-tenant'
+)
+unset HCLOUD_TOKEN
+
+--- Teardown ---
+  Delete sub-project via Console: Projects → tenant-fixture-tenant-prd → Delete
+  Revoke the API token: Security → API Tokens → Revoke
+
+Next step: type /soleur:provision-cloudflare fixture-tenant <zone-id> <account-id> yourself (user-invoked; Soleur cannot run it, ADR-236)
+
+=== Teardown commands (resources created during this run) ===
+  (no resources were created)
+
+If the probe server 'probe-provision-fixture-tenant' was not cleaned up:
+  hcloud server delete 'probe-provision-fixture-tenant'
+
+To tear down the Hetzner sub-project:
+  Delete via Hetzner Console → Projects → tenant-fixture-tenant-prd → Delete
+  (CLI does not support project deletion)

package/skills/provision-hetzner/test/provision-hetzner-characterization.test.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# Characterization suite for provision-hetzner.sh (#8287 Phase 1).
+#
+# This is the SAFETY NET for the Phase 4 library refactor: it pins today's
+# observable `--dry-run` behaviour byte-for-byte so the refactor can be proven
+# behaviour-preserving rather than asserted to be.
+#
+# Three things this suite exists to pin, each of which the refactor could
+# silently change:
+#   1. the `--dry-run` stdout, byte-for-byte;
+#   2. that a SUCCESSFUL `--dry-run` still emits the teardown block (the EXIT
+#      trap fires after `exit 0`) — the "duplicate teardown" the plan names;
+#   3. that `--help` and bad-argument exits print NO teardown, while DPA-gate
+#      exits (rc 3) DO.
+#
+# Runs with cwd OUTSIDE the repository (the DPA gate reads a path relative to
+# cwd), against a synthesized fixture register.
+set -uo pipefail
+
+export TMPDIR="${TMPDIR:-/var/tmp}"
+
+SUITE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="${SUITE_DIR}/../scripts/provision-hetzner.sh"
+FIXTURE_KB="${SUITE_DIR}/fixture/knowledge-base"
+
+# ONE counter per outcome: the self-test, the anti-vacuity floor and the verdict
+# all read these two names (review P1-5 — a shadow `fails` beside `FAIL_COUNT`
+# let a dropped increment print [FAIL] and exit 0).
+PASS_COUNT=0
+FAIL_COUNT=0
+
+pass() { PASS_COUNT=$((PASS_COUNT + 1)); echo "  [ok] $1"; }
+fail() { FAIL_COUNT=$((FAIL_COUNT + 1)); echo "  [FAIL] $1" >&2; }
+
+# Instrument self-test (ADR-193): drive both helpers once each and refuse to
+# continue unless both counters moved. A battery whose helpers are neutered
+# reports a clean run, so this must run BEFORE any real assertion. Reported via
+# printf + exit, never via the helpers under test.
+_st_p=$PASS_COUNT; _st_f=$FAIL_COUNT
+pass "instrument self-test: pass() reached" >/dev/null
+fail "instrument self-test: fail() reached (expected, not a real failure)" 2>/dev/null
+if [[ "$PASS_COUNT" -ne $((_st_p + 1)) || "$FAIL_COUNT" -ne $((_st_f + 1)) ]]; then
+  printf 'INSTRUMENT SELF-TEST FAILED: pass/fail helpers did not both move (pass %s->%s, fail %s->%s)\n' \
+    "$_st_p" "$PASS_COUNT" "$_st_f" "$FAIL_COUNT" >&2
+  exit 2
+fi
+# Unwind the accounting the self-test perturbed; count the self-test itself once.
+PASS_COUNT=1; FAIL_COUNT=0
+echo "  [ok] instrument self-test: both helpers dispatch"
+
+[[ -f "$SCRIPT" ]] || { printf 'HARNESS: script not found at %s\n' "$SCRIPT" >&2; exit 2; }
+[[ -d "$FIXTURE_KB" ]] || { printf 'HARNESS: fixture register not found at %s\n' "$FIXTURE_KB" >&2; exit 2; }
+
+SB="$(mktemp -d -t hetzner-char.XXXXXXXX)" || { printf 'HARNESS: mktemp failed\n' >&2; exit 2; }
+trap 'rm -rf "$SB"' EXIT
+mkdir -p "$SB/bin" "$SB/run" || { printf 'HARNESS: mkdir failed\n' >&2; exit 2; }
+cp -r "$FIXTURE_KB" "$SB/run/" || { printf 'HARNESS: fixture copy failed\n' >&2; exit 2; }
+
+# `hcloud` only has to EXIST for the pre-check; --dry-run never invokes it.
+# Exit 64 on any invocation so an accidental network call is loud, not silent.
+printf '#!/usr/bin/env bash\necho "STUB hcloud invoked: $*" >&2\nexit 64\n' > "$SB/bin/hcloud"
+chmod +x "$SB/bin/hcloud"
+
+run_script() {
+  # Always from $SB/run — OUTSIDE the repository (task 1.8).
+  ( cd "$SB/run" && PATH="$SB/bin:$PATH" bash "$SCRIPT" "$@" 2>&1 )
+}
+
+echo "== provision-hetzner characterization =="
+
+# --- 5 (arm 1). Snapshot the LIVE skill tree before any run --------------------
+# §5 below asserts the runs wrote nothing into plugins/soleur/skills/provision-
+# hetzner/. A snapshot of `git status` over that tree, taken before the first
+# run and compared after the last, is what makes that a real observation
+# (review P2-24: the old §5 checked a file the harness itself had copied). The
+# snapshot names untracked files individually so a new ledger beside the script
+# shows up as its own row.
+SKILL_TREE="$(cd "${SUITE_DIR}/.." && pwd)"
+live_tree_status() {
+  git -C "$SKILL_TREE" status --porcelain --untracked-files=all -- . 2>/dev/null || echo "NOT-A-GIT-TREE"
+}
+status_before="$(live_tree_status)"
+
+# --- 1. Golden --dry-run stdout, byte-for-byte -------------------------------
+GOLDEN="${SUITE_DIR}/fixture/provision-hetzner-dry-run.golden"
+actual="$(run_script fixture-tenant --dry-run)"; rc=$?
+if [[ "$rc" -eq 0 ]]; then
+  pass "--dry-run exits 0"
+else
+  fail "--dry-run exits 0 (got $rc)"
+fi
+
+if [[ -f "$GOLDEN" ]]; then
+  if diff -u "$GOLDEN" <(printf '%s\n' "$actual") > "$SB/diff.txt" 2>&1; then
+    pass "--dry-run stdout is byte-identical to the golden"
+  else
+    fail "--dry-run stdout DIFFERS from the golden:"
+    sed -n '1,40p' "$SB/diff.txt" >&2
+  fi
+else
+  fail "golden file missing at $GOLDEN"
+fi
+
+# --- 2. A successful --dry-run STILL emits the teardown block ----------------
+# The EXIT trap fires after `exit 0`, so the dry-run prints its own guidance
+# AND the trap's teardown. Pinning this stops the refactor from "tidying" it.
+if grep -qF '=== Teardown commands (resources created during this run) ===' <<<"$actual"; then
+  pass "successful --dry-run emits the teardown block (EXIT trap after exit 0)"
+else
+  fail "successful --dry-run no longer emits the teardown block"
+fi
+if grep -qF '(no resources were created)' <<<"$actual"; then
+  pass "teardown block reports no resources created on a dry run"
+else
+  fail "teardown block lost its empty-resources arm"
+fi
+
+# --- 3. --help and bad arguments print NO teardown --------------------------
+help_out="$(run_script --help)"; help_rc=$?
+if [[ "$help_rc" -eq 1 ]]; then
+  pass "--help exits 1"
+else
+  fail "--help exits 1 (got $help_rc)"
+fi
+if grep -qF 'Teardown commands' <<<"$help_out"; then
+  fail "--help printed a teardown block (it must not)"
+else
+  pass "--help prints no teardown block"
+fi
+
+bad_out="$(run_script --nope)"; bad_rc=$?
+if [[ "$bad_rc" -eq 1 ]]; then
+  pass "unknown flag exits 1"
+else
+  fail "unknown flag exits 1 (got $bad_rc)"
+fi
+if grep -qF 'Teardown commands' <<<"$bad_out"; then
+  fail "unknown flag printed a teardown block (it must not)"
+else
+  pass "unknown flag prints no teardown block"
+fi
+
+noslug_out="$(run_script)"; noslug_rc=$?
+if [[ "$noslug_rc" -eq 1 ]]; then
+  pass "missing slug exits 1"
+else
+  fail "missing slug exits 1 (got $noslug_rc)"
+fi
+if grep -qF 'Teardown commands' <<<"$noslug_out"; then
+  fail "missing slug printed a teardown block (it must not)"
+else
+  pass "missing slug prints no teardown block"
+fi
+
+# --- 4. DPA-gate exits (rc 3) DO print teardown ------------------------------
+# Bidirectional by construction: the fixture carries a `terminated` row that
+# must NOT pass the gate, and an absent slug that also must not. Asserting only
+# the passing direction would not detect a gate that accepts everything.
+# `fixture-offboarded` carries a historical `dpa-signed` row FOLLOWED by a
+# `terminated` row: the register is append-only, so the LAST row for a slug is
+# the tenant's state, and a gate that latched on the first match admitted every
+# offboarded tenant (review P2-9).
+for blocked in fixture-revoked fixture-offboarded absent-slug; do
+  gate_out="$(run_script "$blocked" --dry-run)"; gate_rc=$?
+  if [[ "$gate_rc" -eq 3 ]]; then
+    pass "DPA gate blocks '$blocked' with rc 3"
+  else
+    fail "DPA gate blocks '$blocked' with rc 3 (got $gate_rc)"
+  fi
+  if grep -qF 'Teardown commands' <<<"$gate_out"; then
+    pass "DPA-gate exit for '$blocked' prints the teardown block"
+  else
+    fail "DPA-gate exit for '$blocked' lost its teardown block"
+  fi
+done
+
+# The in-progress row must pass — a gate that accepted only `dpa-signed` would
+# be a silent narrowing, and the one-row fixture could not see it.
+inflight_out="$(run_script fixture-inflight --dry-run)"; inflight_rc=$?
+if [[ "$inflight_rc" -eq 0 ]]; then
+  pass "DPA gate admits a 'provisioning-in-progress' row"
+else
+  fail "DPA gate admits a 'provisioning-in-progress' row (got $inflight_rc)"
+fi
+if grep -qF "tenant-fixture-inflight-prd" <<<"$inflight_out"; then
+  pass "slug is interpolated into the sub-project name"
+else
+  fail "slug is not interpolated into the sub-project name"
+fi
+
+# --- 5. No live-repo write (task 1.8) ---------------------------------------
+if [[ -e "$SB/run/knowledge-base/legal/tenant-dpa-register.md" ]]; then
+  pass "suite read its own fixture register, not the live one"
+else
+  fail "fixture register missing from the sandbox"
+fi
+status_after="$(live_tree_status)"
+if [[ "$status_before" == "NOT-A-GIT-TREE" ]]; then
+  fail "no live-repo write: the skill tree is not inside a git work tree, so the snapshot cannot observe a write"
+elif [[ "$status_before" == "$status_after" ]]; then
+  pass "no live-repo write: git status over the live skill tree is identical before and after every run"
+else
+  fail "no live-repo write: the runs changed the live skill tree:
+$(diff <(printf '%s\n' "$status_before") <(printf '%s\n' "$status_after") | sed 's/^/    /')"
+fi
+
+# --- Anti-vacuity floor -----------------------------------------------------
+# REPORTS DIRECTLY (printf + exit 1), never by incrementing FAIL_COUNT (ADR-193)
+# — a floor dispatched through the suite's own pass()/fail() is disarmed by the
+# same one-line edit that disarms every assertion it backstops. This suite is
+# PROMOTED into guard-vacuity-floor's covered scope, which mutation-tests this
+# shape, so the direct form is what keeps the promotion honest.
+ASSERT_TOTAL=$((PASS_COUNT + FAIL_COUNT))
+FLOOR=21
+if [[ "$ASSERT_TOTAL" -lt "$FLOOR" ]]; then
+  printf '  [FAIL] anti-vacuity floor: only %s assertions ran, floor is %s\n' "$ASSERT_TOTAL" "$FLOOR" >&2
+  printf 'Total: %s assertions, %s failed\n' "$ASSERT_TOTAL" "$((FAIL_COUNT + 1))"
+  exit 1
+fi
+# Conservation: pass + fail must account for every assertion the run made.
+if [[ "$ASSERT_TOTAL" -ne $((PASS_COUNT + FAIL_COUNT)) ]]; then
+  printf '  [FAIL] accounting: pass=%s fail=%s do not reconcile to %s\n' "$PASS_COUNT" "$FAIL_COUNT" "$ASSERT_TOTAL" >&2
+  exit 1
+fi
+
+echo "Total: $((PASS_COUNT + FAIL_COUNT)) assertions, ${FAIL_COUNT} failed"
+[[ "$FAIL_COUNT" -eq 0 ]]

package/skills/qa/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: qa
+description: "This skill should be used when running functional QA before merge."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+<!-- lifecycle-handoff-protocol:start -->
+**Lifecycle handoff (standalone `soleur:qa`):** When no parent orchestrator (`one-shot`, `work`) owns the pipeline, invoke `soleur:compound` then `soleur:ship` after the QA report — do not end at the report. A PASS is a checkpoint, not completion. If a recorded operator ruling already authorizes shipping (a scope ruling in `session-state.md`, an explicit instruction), proceed under `wg-verified-work-ships-without-asking` rather than pausing to re-confirm — held scope that was never implemented has no files to carry along and is not a reason to halt.
+<!-- lifecycle-handoff-protocol:end -->
+
+# Functional QA
+
+Verify that features actually work before merge -- not just that pages render, but that forms submit correctly, external services receive the right data, and data integrity holds across system boundaries.
+
+**Scope boundary with `soleur:test-browser`:** This skill verifies functional correctness (user flows + external service state). `soleur:test-browser` verifies visual rendering, layout regressions, and console errors. They coexist in the pipeline.
+
+## Prerequisites
+
+- Local development server running OR a `dev` script in the project's `package.json` (auto-started if not running)
+- Playwright MCP available (for browser scenarios)
+- Doppler CLI installed and configured (for API verification scenarios)
+
+## Usage
+
+**Claude:** Skill tool. **Grok:** Read this SKILL.md in this process (`soleur:qa`); slash names the skill.
+
+```bash
+skill: soleur:qa, args: "<plan_file_path>"   # Claude Skill tool
+soleur:qa <plan_file_path>                         # Grok slash (then Read this SKILL.md)
+```
+
+The skill reads the plan file's `## Test Scenarios` section and executes each scenario.
+
+## Workflow
+
+### Step 1: Read Plan and Extract Test Scenarios
+
+Read the plan file passed as `$ARGUMENTS`. Find the `## Test Scenarios` section.
+
+**If no Test Scenarios section exists:** Output "No test scenarios found in plan — skipping QA" and stop. Do not block the pipeline.
+
+**If Test Scenarios section is empty:** Same as above — warn and skip.
+
+**If Test Scenarios contains only Given/When/Then prose with no `Browser:`, `API verify:`, or `Cleanup:` prefixed steps:** Output "Test Scenarios are integration-level Given/When/Then prose (no executable Browser:/API verify: steps) — covered by unit test suite + manual Phase 6 cross-check. Skipping automated QA." and stop. Do not start the dev server. This case is common for plans whose QA gate is explicitly manual (e.g., requires a real Anthropic key + live Supabase apply); a dev-server smoke would not add coverage beyond what the typecheck + unit suite already validate. Never block the pipeline on a confirmation prompt for the dev server in a test environment — auto-skip silently.
+
+### Step 1.5: Ensure Dev Server is Running
+
+Before executing any browser scenarios, check whether the dev server is reachable. If not, attempt to start it automatically.
+
+1. **Check if already running:** `curl -sf --max-time 3 http://localhost:3000/ >/dev/null 2>&1`. If reachable, skip to Step 2 — no action needed. Record that the server was NOT started by QA (so cleanup skips it).
+
+2. **Detect the dev command:** Read `apps/web-platform/package.json` and extract the `scripts.dev` field. If no `dev` script exists, warn: "No dev script found in package.json — cannot auto-start server. Skipping browser scenarios." Continue to API verification steps (do not block the pipeline).
+
+3. **Start the server:** Change to the `apps/web-platform/` directory first (the dev command must run from the app root). Check if Doppler is available (`command -v doppler`). If available, start via `doppler run -p soleur -c dev -- <dev-command> > "$QA_LOG" 2>&1 &` (after `QA_LOG=$(mktemp -p "$(mktemp -d -t soleur-run.$$.XXXXXXXX)" qa-dev-server.XXXXXXXX.log)`). If Doppler is unavailable, start via `<dev-command> > "$QA_LOG" 2>&1 &`. Record the background PID **and echo `QA_LOG=$QA_LOG`** — a later Bash call does not inherit the variable, so the path must be recoverable from the transcript. A fixed name would collide with any concurrent QA session. Remove it at QA teardown (`rm -f` on the echoed `QA_LOG=` path plus `rmdir` on its parent — a later Bash call does not inherit the variable) — it is scratch, and a count-shaped `/tmp` leak is real (#10017).
+
+4. **Poll for readiness (30s timeout):** Poll `http://localhost:3000/` until it responds or 30 seconds have elapsed, whichever comes first. If the server responds, proceed to Step 2. If the timeout elapses:
+   - Kill the background process by PID
+   - Include the last 20 lines of `"$QA_LOG"` in the failure report
+   - Report: "Dev server failed to start within 30s. See server output above."
+   - Continue to API verification steps (do not block the pipeline)
+
+   - When `doppler run` starts the dev server but Supabase env vars (`NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`) are missing from the Doppler config, the server starts but crashes on first request. Check the server log for "Your project's URL and Key are required" before declaring the server ready.
+
+### Step 2: Detect Environment
+
+Determine the Doppler config to use:
+
+```bash
+# Check if DEPLOY_URL is set (indicates production context)
+echo "${DEPLOY_URL:-not_set}"
+```
+
+- If `DEPLOY_URL` is set: use Doppler config `prd`
+- If `DEPLOY_URL` is not set: use Doppler config `dev`
+
+Store the config name for use in subsequent `doppler` commands.
+
+### Step 2.6: Structural-UI Visual-Regression Gate (#4834 / ADR-049)
+
+This is the gate's semantic home. Run it when the diff (`git diff --name-only origin/main...HEAD` — the branch-vs-main merge-base diff; do NOT use `origin/<branch>...HEAD`, which only sees unpushed commits and returns 0 files once the branch is pushed, silently skipping the gate) touches `apps/web-platform/app/(dashboard)/**`, `apps/web-platform/components/dashboard/**`, or any `layout.tsx`. Skip silently otherwise.
+
+**Why this exists:** jsdom (vitest) renders no CSS, so `md:w-14` / `hidden md:block` / `flex-wrap` / `display:none` regressions ship green through the unit suite (the #4810 class — top-level chrome leaking into drilled routes; a collapsed rail with no icon-only form). The gate renders real CSS in real headless Chromium.
+
+**Deterministic layer (BLOCKING).** Run the committed `nav-states-*.e2e.ts` spec in the existing `authenticated` Playwright project — real headless Chromium + real Next.js SSR seeded by the **offline mock-Supabase storageState** (`e2e/global-setup.ts` + `e2e/helpers/supabase-mocks.ts`). Zero credentials; NO `dev-signin`; never point at a live origin (CLO: synthetic fixtures only).
+
+**Browser-readiness preflight (unsupported-host guard — do this FIRST).** On a host newer than the pinned Playwright officially supports, a plain `playwright install` fails before any navigation — the false-fail that repeatedly costs a QA session its whole run. Run the install probe in [browser-preflight.md](./references/browser-preflight.md) — it logs under a `soleur-run` root (#10017) and retries with the host-platform override.
+
+If BOTH the plain install and the override install fail (a genuinely unsupported host with no fallback build), do NOT run the gate and do NOT spend reasoning re-deriving whether it is a regression: this is **INFRA-BLOCKED**, not a code failure. Record in the QA report — "Step 2.6 nav-states gate INFRA-BLOCKED locally (Playwright browser uninstallable on <os>); CI's containerized `e2e` job (`mcr.microsoft.com/playwright:v1.58.2-jammy`) is the authoritative gate per #5009" — and proceed. Never block the pipeline on this.
+
+Then run the gate (no override — the runtime resolves the installed build):
+
+### Preflight: verify the plugin install before any snapshot
+
+The redactor is reached through `${CLAUDE_PLUGIN_ROOT}`. An ambient value pointing at a
+directory that is not a Soleur install would resolve to a path that does not exist — or, worse,
+to one an attacker chose. Verify plugin IDENTITY and halt if it does not hold (ADR-179 decision 2);
+a `test -f` on the script alone is a shape check and was measured bypassable.
+
+```bash
+[ -f "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" ] \
+  && grep -q '"name"[[:space:]]*:[[:space:]]*"soleur"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" \
+  || { echo "SOLEUR_SNAPSHOT_HALT reason=plugin-root-unverified root=[${CLAUDE_PLUGIN_ROOT}]" >&2
+       echo "  Cannot locate the snapshot redactor, so no accessibility snapshot may be taken here." >&2
+       echo "  Root EMPTY: no Soleur plugin is loaded in this session. Install it and start a NEW session." >&2
+       echo "  Root set but wrong: a repo checkout is not an install. Run 'claude plugin update soleur@soleur-marketplace' (or the id 'claude plugin list' prints, if you added the repository directly), then RESTART Claude Code." >&2
+       echo "  Nothing has been captured yet, so nothing has leaked." >&2
+       exit 2; }
+```
+
+```bash
+cd apps/web-platform && ./node_modules/.bin/playwright test nav-states --project=authenticated --reporter=list
+```
+
+A non-zero exit FAILS this QA run. The assertions read invariants jsdom cannot: drilled routes hide the wordmark + ThemeToggle; the collapsed rail is icon-only with no horizontal overflow; the workspace-identity band is visible (with org + repo content) in every drill state × viewport.
+
+**Discriminate a real fail from an env flake.** If the run exits non-zero, apply the #5009 discriminator (see Notes): untouched-test + failure at `page.goto`/browser-close (before any assertion) + the surface the diff actually changed still passes = pre-existing local env flake → record and defer to CI, do not "fix" unrelated tests. A launch-time `Executable doesn't exist` failure means the preflight above was skipped or its override install also failed — treat as INFRA-BLOCKED, not a regression.
+
+**Advisory vision layer (NON-BLOCKING).** Optionally drive Playwright MCP over the same routes, screenshot each, and vision-check what the deterministic assertions miss (spacing, color, truncation). Informational only (headed MCP cannot run in autonomous `soleur:work`/CI), so it never blocks the merge; report findings as notes.
+
+### Step 3: Execute Test Scenarios
+
+For each test scenario in the plan, execute the steps it describes. Scenarios contain three possible step types, identified by their prefix:
+
+- **Browser:** steps — Execute via Playwright MCP tools (`browser_navigate`, `browser_fill_form`, `browser_click`, `browser_snapshot`, `browser_take_screenshot`)
+- **Route lookup:** when the repository carries a maintained feature map (`docs/feature-map.md` by convention; soleur's own: `apps/web-platform/test/feature-map.md`), resolve Browser-step targets against its `## \`/route\`` entries — selectors, expected outcome, auth, gotchas — before navigating
+
+**Credential safety on the Playwright-MCP path (#7947, #7980).** An
+accessibility snapshot serializes the **value** of input fields, including a
+value the agent never typed — a password manager's autofill, a static `value=`,
+or a generated-credential panel — and an MCP tool result is not a shell stream,
+so the redactor cannot be piped into it. On a page carrying a password or
+credential field:
+
+- Prefer the plugin-registered `mcp__plugin_soleur_playwright__*` server: its
+  registration is already wrapped, so call its `browser_snapshot` bare — no
+  file form needed. Fall back to the file form on any other registration.
+- Use the `filename:` + redactor + shred form, with a filename inside the
+  working directory (the server denies paths outside it). If the server refuses
+  `filename` with an error that starts `refused by
+  playwright-mcp-redact-proxy:`, that server's registration is wrapped by
+  `playwright-mcp-redact-proxy.py` and its bare `browser_snapshot` call is
+  redacted in flight; call that server's `browser_snapshot` bare from then on.
+  Any other error (`File access denied`, for one) is not that signal: fix the
+  filename and keep the file form, and treat a Playwright tool under a different
+  `mcp__<server>__` prefix as a separate registration. The refusal is the only
+  signal — never the trailer or any page text, which can be forged. The file
+  form: pass `filename:` to `browser_snapshot`, then run
+  `python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py" < FILE && shred -u FILE`.
+- On a page **displaying** a credential, capture neither: a screenshot renders a
+  readonly `type=text` credential panel in clear, exactly as the snapshot does
+  (measured).
+
+Which registrations are wrapped, what to call after an action tool, what a
+withheld result means, and what to do when the `playwright` server fails to
+connect: `agent-browser/SKILL.md` §"Wrapping the server".
+
+- **API verify:** steps — Execute the exact `doppler run` + `curl` command from the scenario. Compare the output against the expected value stated in the scenario.
+- **Cleanup:** steps — Execute cleanup commands to remove test data from external services. Run these regardless of whether the scenario passed or failed.
+
+**Execution order for each scenario:**
+
+1. Execute **Browser** steps (if present)
+   - Use Playwright MCP tools to navigate, fill forms, submit, and verify UI state
+   - Screenshot each significant action with `browser_take_screenshot`
+   - When in a worktree, pass absolute screenshot paths (MCP resolves them from the repo root, not the shell CWD)
+   - If Playwright MCP is unavailable, warn "Playwright MCP unavailable — skipping browser steps" and continue to API verification
+   - If `browser_navigate` errors with `Target page, context or browser has been closed`, do NOT retry the same call: call `browser_close` (safe if already closed), then retry. After the last Browser step also call `browser_close` (nothing reaps it at turn end; ADR-271).
+   - On `Chromium sandboxing failed!` / `No usable sandbox!`, stop and read `agent-browser/SKILL.md` troubleshooting; never disable the sandbox in the Playwright config or env (the proxy refuses it, then the MCP server fails to start); tell the user the host needs Google Chrome or a non-root user.
+2. Wait 3 seconds for eventual consistency (if the scenario has both Browser and API steps)
+3. Execute **API verify** steps (if present)
+   - Run the exact command from the scenario via the Bash tool
+   - Compare the command output against the expected value
+   - If the command fails or output doesn't match, retry up to 3 times (waiting a few seconds between retries) before marking as failed
+   - If a `doppler secrets get` fails (secret not found), warn "Doppler secret unavailable — skipping API verification" and skip this step
+4. Execute **Cleanup** steps (if present)
+   - Run cleanup commands regardless of pass/fail
+   - Cleanup failures produce warnings but do not mark the scenario as failed
+
+**Sharp edges for API verification:**
+
+- When verifying Sentry API events, use `statsPeriod=24h` (not `1h` — Sentry only accepts `24h` and `14d`). For EU-region DSNs (`ingest.de.sentry.io`), query `de.sentry.io/api/0/` (not `sentry.io/api/0/`).
+
+**Record the result** for each scenario: PASS or FAIL with evidence (screenshots, API response output, error messages).
+
+### Step 4: Generate Report
+
+After all scenarios complete, output a report in this format:
+
+```markdown
+## QA Report
+
+**Plan:** <plan file path>
+**Environment:** <dev or prd>
+**Result:** <PASS (N/N scenarios passed) or FAIL (N/N scenarios passed)>
+
+### Scenario 1: <scenario description> ✅ or ❌
+
+**Browser:** <what was done, result>
+**API:** <command executed, expected vs actual>
+**Evidence:** <screenshot filenames>
+
+### Scenario 2: ...
+```
+
+### Step 5: Pass/Fail Gate
+
+- If **all scenarios passed**: Output the report and continue. The pipeline proceeds to the next step.
+- If **any scenario failed**: Output the report with detailed failure information (expected vs actual values, screenshot of failure state). Output "QA FAILED — fix the issues above and re-run QA."
+
+After outputting the result (pass or fail), always proceed to Step 5.5 for cleanup before returning.
+
+### Step 5.5: Cleanup Dev Server
+
+If the dev server was started in Step 1.5 (a background PID was recorded), kill the process by PID, remove `$QA_LOG` (the path echoed when the server started), and report: "Stopped auto-started dev server (PID <pid>)." If the server was already running before QA (no PID recorded), do nothing.
+
+This step runs regardless of whether scenarios passed or failed.
+
+## Graceful Degradation
+
+The skill handles missing prerequisites without blocking the pipeline:
+
+| Missing Prerequisite | Behavior |
+|---------------------|----------|
+| No Test Scenarios section in plan | Warn and skip QA entirely |
+| Playwright MCP unavailable | Skip browser steps, still run API verification |
+| Doppler secret not found | Skip that API verification step with warning |
+| Dev server not running | Auto-start via package.json dev script; if startup fails, report reason and skip browser scenarios |
+| No dev script in package.json | Warn and skip browser scenarios (API verification still runs) |
+| Dev server startup timeout (30s) | Report failure reason and skip browser scenarios |
+| curl command fails (network error) | Fail that scenario with error details |
+
+## Notes
+
+- **A skill-prose change gets a constrained DRY RUN, not only a read.** Spawn a subagent to execute the rewritten skill against a real, already-diagnosed issue under no-post / no-write / no-credential constraints and report every sentence it could not follow. **Why:** #8288/PR #8352 — nine review seats read the rewritten `reproduce-bug` prose and passed it; the dry run found six unfollowable or contradictory sentences (an exit criterion with no off-ramp for a local-only surface, "inspect the code" vs "stop reading code", a "do not proceed until reproduced" unsatisfiable once the fix has landed). Reading is not executing. See `knowledge-base/project/learnings/2026-09-19-cleanup-on-failure-is-a-property-of-the-window-not-the-arms.md`.
+- **A gate has THREE outcomes and the third silently equals the first — drive the cannot-evaluate arm, not just clean and violated.** `rc=0` and `rc=2` producing byte-identical stdout is the DEFAULT whenever a tool writes diagnostics to stderr, so "it printed nothing, so it passed" is indistinguishable from "it never measured". Also refuse a fence whose terminal statement is an ASSIGNMENT (`rc=$?`): the fence then exits 0 whatever the tool said, and a dispatch written in prose below it runs in a different fence that cannot see the variable. **Why:** #8289/PR #8405 — the redaction floor in `questionnaire-generate` ended `sentinel_rc=$?` with the dispatch in prose; measured clean rc=0/0 bytes, matches rc=1/53 bytes, unreadable rc=2/**0 bytes**, so an un-scanned document intended for an outside professional was indistinguishable from a scanned one and the documented "cannot evaluate → halt" arm was unreachable. Nine review seats had read that prose. See `knowledge-base/project/learnings/2026-09-20-i-verified-by-reading-and-the-gate-that-mattered-failed-open.md`.
+- For Playwright auth in production QA, use Supabase admin API `generate_link` to get the OTP code, then enter it in the OTP form. Do not use the magic link `action_link` URL — Playwright navigation does not trigger client-side hash fragment processing.
+- For Playwright MCP visual verification of an authenticated surface on a LOCAL dev server: start the server with `NEXT_PUBLIC_DEV_EXTRA_ORIGINS=<origin>` (else state-mutating POSTs 403 on CSRF), mint a cookie via `ux-audit/scripts/bot-signin.ts` with `NEXT_PUBLIC_APP_URL=http://localhost:<port>`, inject it with `page.context().addCookies()` (the `run_code_unsafe` sandbox has no `require`/`Buffer`/`atob` — pre-escape data into a literal), drive onboarding gates via `page.evaluate(fetch(...))` not UI clicks, and `curl`-pre-warm slow routes before `browser_navigate`. Full recipe: `knowledge-base/project/learnings/2026-06-02-playwright-mcp-local-auth-dashboard-verification.md`.
+- When locating a control whose `aria-label` flips with component state (a collapse toggle that is `"Collapse sidebar"` expanded / `"Expand sidebar"` collapsed, a disclosure that is `"Show"`/`"Hide"`, etc.), a single-label `getByRole("button", { name: "Collapse sidebar" })` resolves in one state and throws "element(s) not found" in the other. Match all states with a regex alternation (`name: /^(Collapse|Expand) sidebar$/`) or a stable `data-testid`. **Why:** PR #4997 — the collapsed-rail VRT case failed on a "Collapse sidebar" locator because the floated toggle reads "Expand sidebar" when collapsed. See `knowledge-base/project/learnings/ui-bugs/2026-06-08-floating-absolute-control-needs-clearance-in-both-render-branches.md`.
+- When asserting horizontal/vertical ALIGNMENT between two controls in Playwright, measure the innermost visible element (`.locator("svg")` / the text node), NOT the interactive element's `boundingBox()`. Two controls can share a layout gutter while their border-boxes differ by asymmetric padding or flex-stretch (e.g. a full-width `flex` link whose `px-3` is internal vs. an unpadded button whose `px-3` is the row gutter) — comparing border-boxes yields a false misalignment equal to the padding delta. See `knowledge-base/project/learnings/test-failures/2026-06-03-playwright-x-alignment-measure-glyph-not-border-box.md`.
+- For verifying a vendored-library CSS override (e.g. `@likec4/diagram` theme tweaks in `c4-theme.css`) on an auth/flag-gated surface, prefer a reconstructed-DOM harness over the live viewer: read the library's emitted DOM contract + CSS recipe out of `node_modules`, rebuild the exact node markup in a standalone HTML file with the real theme tokens, render it via the project's installed chromium (`chromium.launch({ executablePath: ~/.cache/ms-playwright/chromium-<build>/chrome-linux64/chrome })` — the Playwright MCP Chrome channel is often absent and the module's default build can drift from the cache), and assert `getComputedStyle(...).fill`/`opacity` flips off the library default in both `data-theme` states (proves cascade victory — the non-vacuous half a source-grep test can't give you) before screenshotting for legibility. See `knowledge-base/project/learnings/2026-06-05-verify-vendored-css-override-via-reconstructed-dom-harness.md`.
+- When verifying that an INJECTED session cookie authenticates, navigate to a **client-guarded** route (one that hydrates its session via the `@supabase/ssr` browser client from `document.cookie`, e.g. `/dashboard/chat/new`) — NOT only a server-rendered route like `/dashboard`. A server-rendered route reads the cookie server-side where `httpOnly` is irrelevant, so it authenticates even with a mis-shaped injected cookie (`httpOnly: true`, wrong domain visibility, missing chunk) and silently clears bugs that only manifest on the client hydration path. Inject with `httpOnly: false` (matches `bot-signin.ts`/`e2e/global-setup.ts`); `httpOnly: true` blocks the browser client and races to `/login`. **Why:** #5485 — see `knowledge-base/project/learnings/bug-fixes/2026-06-17-injected-session-cookie-test-the-client-guarded-route-not-just-dashboard.md`.
+- **Before recording any hazard as mitigated, `ls` every control the plan NAMES as its detection — a guard can be deleted mid-implementation while the document that cites it is never re-derived.** The sibling note below covers a control that cannot FIRE; this covers one that does not EXIST, and the plan reads identically in both cases. Measured: #7902's Guard 2 was built, mutation-proven at 10/10, then deleted on a CTO ruling — while the observability `failure_modes` block still gave it as the `detection:` for the plan's sharpest hazard, and the `## Guard Contract` still carried its full property statement and a seven-row mutation matrix. [lint-guard-contract.py](../../../../scripts/lint-guard-contract.py) was green throughout (exit 0, 30 entries) and is not broken: it resolves plan **entries**, so its green is a sentence about the document and never about the tree. Review reads the diff and structurally cannot see a guard that is absent from it, which makes QA the last phase that reads the plan whole while there is still time. Same pass, same plan: AC3 and AC5 were literally false as written (AC5 claimed the `test:` block was byte-unchanged; it gained 7 lines) and were about to be ticked from memory of intent — tick an AC only by running the command it names. See [the 2026-09-08 learning](../../../../knowledge-base/project/learnings/2026-09-08-the-guard-was-deleted-the-plan-still-cited-it-and-the-linter-validated-the-citation.md).
+- **A MISSING CI check is a MERGEABILITY question first.** A conflicting PR reads as *"CI never ran"*: functional jobs are **absent**, not failing — GitHub builds no `refs/pull/N/merge` for a DIRTY ref, and the all-green CodeQL set left behind looks healthy. Run `gh pr view --json mergeable,mergeStateStatus` before diagnosing a missing check. **Why:** #8539; see `learnings/2026-09-23-the-prose-stated-the-property-and-the-predicate-checked-a-subset.md`.
+- **A "known pre-existing failure" is a claim to RE-MEASURE, and a matching failure COUNT is the weakest possible evidence for it.** When a handoff says a suite "already fails N of M on main, identical rows", falsify it by installing the base version of the SPECIFIC INPUTS that suite reads and re-running — never by checking that N still equals N, because a regression breaking N rows is indistinguishable from a known failure of N rows. The trap fires hardest when your diff touched the suite's FIXTURES: grep the failing row NAMES against `git diff --name-only origin/main...HEAD`. **Why:** #7927/PR #7955 — a briefing said `ship-incident-pir-gate` "fails 2 of 25 on main today, tracked by #7801"; the count matched exactly, and it was false for that tree. The branch's markdown sweep had touched precisely the two fixtures the two failing rows are named for (a boundary classifier whose blank lines ARE its input), and `git show origin/main:<fixture>` + re-run gave 25/25 against 23/25 in ~30 seconds. Accepting the label would have shipped a real break under cover of a known one. See `knowledge-base/project/learnings/2026-09-09-the-linter-rewrote-the-fixtures-its-own-suites-assert-on.md`.
+- **A scenario's NEGATIVE CONTROL is a claim to run, not a control to trust — and the Risks table usually cites it as the mitigation for the plan's sharpest hazard.** When a scenario reads "…and a fixture that violates X fails the check", run that fixture before recording the scenario as covered; a control that cannot fire makes the hazard read as mitigated while nothing guards it. Measured: a plan asserted that a unit whose `ReadWritePaths` names a missing directory fails `systemd-analyze verify`; it returns **rc=0 with empty output**, because verify validates directive syntax and not path existence. The Risks table had cited exactly that control as the mitigation for a unit that would otherwise die on every 30-second fire on a host with no inbound channel. Retract the falsified half in place (append the measurement rather than deleting the sentence) and name the control that actually holds. **Why:** #7761. See `knowledge-base/project/learnings/security-issues/2026-09-03-the-hardening-i-added-disarmed-the-guard-over-the-flushall.md`.
+- This skill does NOT test error paths (network failure, invalid input); deferred.
+- Always include cleanup steps so test data does not accumulate in external services.
+- The deploy-webhook credential triple (`WEBHOOK_DEPLOY_SECRET`, `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET`) lives in Doppler `soleur/prd_terraform`, NOT `prd` — a probe run under `doppler run -c prd` reports `credentials_unprovisioned`, which is the probe being correct, not the secret being absent. And `doppler secrets --only-names` prints a TABLE (`│ NAME │`), so an anchored `grep -c '^NAME$'` over it returns 0 for every config; a zero from an unfamiliar CLI subcommand is "the command's output shape is unknown" until inspected. **Why:** #6178 / PR #8346 — a names-scan reported the triple absent from all 13 configs while `inngest-server.md` §deploy-status already named the right one.
+- For new scheduled-probe workflows, dry-run every probe step against prod hostnames before merge. Verify the documented success path (HTTP code, redirect host, response shape) matches reality. Workflow YAML lint and unit tests do NOT catch API contract surprises like HEAD-rejecting endpoints or auth-required public endpoints. **Why:** PR #3030 — see `knowledge-base/project/learnings/integration-issues/2026-04-29-supabase-auth-probe-and-sentry-rule-api-quirks.md`.
+- When verifying a secret-scan gate fails loud on a secret, the sentinel must be a shape the scanner actually catches AND is not on its example/stopword allowlist — `AKIAIOSFODNN7EXAMPLE` (gitleaks' canonical AWS doc key) is allowlisted and returns a false `rc=0`. Use a synthetic PEM (`-----BEGIN RSA PRIVATE KEY-----` + random base64) or a repo-custom-rule shape (`postgres://`, `dp.st.`), pair it with a clean control (no-secret → `rc=0`), and run in an isolated throwaway git repo so the synthetic never touches the real worktree/push-protection. **Why:** PR #6050 — see `knowledge-base/project/learnings/security-issues/2026-07-05-fabricated-green-content-gate-ceiling-and-verification-sentinel.md`.
+- For pure-CSS-utility-class fixes whose plan declares `User-Brand Impact: none` AND whose className contracts are fully unit-tested (vitest asserts on `toHaveClass`/`className.match`), a dev-server outage degrades QA to unit-test coverage rather than blocking the pipeline — file the dev-server bug separately with `pre-existing-unrelated` scope-out. For functional, data, auth, or payment fixes, the dev-server bug becomes load-bearing and must be fixed before merge. See `knowledge-base/project/learnings/2026-05-11-qa-degradation-when-dev-server-broken-on-css-only-fix.md`.
+- When the visual gate asserts on an element's measured size (`clientWidth`/`offsetHeight`) that is animated (`transition-[width]`) OR set in a post-mount effect (localStorage hydration, `useMediaQuery`), poll with `expect.poll(() => el.clientWidth, { timeout }).toBeGreaterThan(X)` — a single synchronous read races the transition/hydration and catches a transient value. And before a `page.mouse` drag on a hydrated client component, settle for hydration (the SSR markup is visible before React attaches `onPointerDown`, so an early drag fires events at a handler-less element). A JS-driven responsive width should ride a CSS custom property + an `@media` rule (NOT a Tailwind v4 `w-[var(--x)]` arbitrary class, which may not generate, nor a `useMediaQuery` JS gate, which can stay stale under SSR hydration). **Why:** PR #4871 — see `knowledge-base/project/learnings/ui-bugs/2026-06-03-dynamic-width-needs-css-var-not-tailwind-arbitrary-or-usemediaquery.md`.
+- When an `absolute`/`fixed` control must align to an **in-flow** sibling (a floated toggle centered on an adjacent card), its `top-N` is measured from its **positioning containing block** while the sibling lives in a **different** containing block — so static pixel math (`pt-2 + pill_half`) silently omits the gap between the two origins. Derive the `top-N` against the **live VRT** (not eyeballed, not statically computed) and assert a **positive rect-center** alignment (`|toggleCenterY − cardCenterY| ≤ 2`), never just non-overlap — a misaligned-but-disjoint control passes a non-overlap check, which is exactly how the centering regression ships green. **Why:** PR #5015 — `top-7` left a 12px residual == the band's reclaimed-space offset below the aside; VRT-derived `top-10` fixed it. See `knowledge-base/project/learnings/ui-bugs/2026-06-08-absolute-control-alignment-offset-parent-vs-target-band.md`.
+- The Step 2.6 `nav-states` gate can FALSE-FAIL on a resource-starved local machine: headless Chromium crashes cascade across tests. Discriminate flake-from-regression by provenance + failure-layer: (a) does the diff touch the failing test (`git diff origin/main...HEAD -- e2e/nav-states-shell.e2e.ts`)? (b) do the tests rendering the surface the diff actually changed pass? (c) is the failure at `page.goto`/browser-close (before any assertion) vs. a real assertion mismatch? Untouched-test + crash-at-navigation + changed-surface-passes = pre-existing local env flake (root-cause hygiene: [determinism-checklist.md](${CLAUDE_PLUGIN_ROOT}/skills/test-fix-loop/references/determinism-checklist.md)); CI's containerized `e2e` job is the authoritative gate — record it and proceed, don't "fix" unrelated tests. **Why:** PR #5009 — see `knowledge-base/project/learnings/test-failures/2026-06-08-nav-states-structural-ui-gate-flakes-on-throttled-local.md`.
+- When the diff adds a NEW client-side fetch to a page covered by the offline-mock e2e suite (`e2e/nav-states-*.e2e.ts` et al.), the harness `page.route` mock for that endpoint must land in the SAME PR. Unmocked, the request reaches the real dev server whose backing-service env is fake in e2e — a hanging request that wedges a throttled dev server and fails tests far from the diff (goto timeouts) before failing the obvious one. Diagnosis discriminator: the diff-surface test failing in EVERY run while siblings shift = regression; shifting set with `browserContext.close` accompaniment = the #5009 flake. **Why:** PR #5125 — the new `/api/inbox/emails` fetch was the only unmocked authed route in nav-states; see `knowledge-base/project/learnings/2026-06-11-worm-mutation-matrix-and-e2e-harness-mock-for-new-fetches.md`.
+- A read-source **migration** (endpoint swap, direct-query→RPC, table rename) must sweep the e2e offline-mock harness at BOTH sub-layers, not just the unit-test mocks: (1) every per-test `page.route("**/<old-path>*")` across `e2e/*.e2e.ts` (`git grep -nE '<old-endpoint>|rest/v1/<old-table>' e2e/`), AND (2) the base mock **server** `e2e/mock-supabase.ts` path handlers (a Node HTTP server with a 404 catch-all). Fix the base-server default FIRST (add a handler for the new path mirroring the old default, e.g. new RPC → `[]` like `/rest/v1/conversations` → `[]`) so every e2e file's empty-case is covered and only populated-fixture cases need per-test overrides. When the local OS can't run Playwright, validate harness edits with `tsc` + `playwright test <specs> --list` and rely on CI's containerized `e2e` job. **Why:** #6199 — the dashboard's `/api/kb/tree`→`/api/dashboard/foundation-status` + rail direct-query→`list_conversations_enriched` RPC swap left 4 e2e harness files stale; see `knowledge-base/project/learnings/integration-issues/2026-07-07-read-source-migration-must-sweep-e2e-offline-mock-harness.md`.

package/skills/qa/references/browser-preflight.md

@@ -0,0 +1,22 @@
+# Browser-Readiness Preflight (unsupported-host guard)
+
+Loaded by `qa`'s nav-states gate — run this BEFORE the first Playwright
+invocation. On a host newer than the pinned Playwright officially supports
+(e.g. Ubuntu 26.04 vs the `apps/web-platform` `@playwright/test` pin), a
+plain `playwright install` fails with `does not support chromium ... on
+<os>` and every test then dies at `browserType.launch: Executable doesn't
+exist` **before any navigation** — the false-fail that repeatedly costs a
+QA session its whole run. Recover automatically by retrying the install
+with the host-platform override, which pulls the nearest supported fallback
+build (verified `ubuntu26.04-x64` → `ubuntu24.04-x64`; once the fallback
+build is in cache the launcher resolves it at runtime with NO override, so
+the override stays out of the run command and can never leak onto a
+supported host like CI's Jammy container):
+
+```bash
+cd apps/web-platform
+QA_PW_LOG=$(mktemp -p "$(mktemp -d -t soleur-run.$$.XXXXXXXX)")
+npx playwright install chromium >"$QA_PW_LOG" 2>&1 \
+  || PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 npx playwright install chromium
+# on failure read it for the diagnosis, then `rm -f "$QA_PW_LOG"` (#10017).
+```