mandrel 1.57.0

package/.agents/skills/stack/qa/playwright/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: playwright
+description:
+  Robust E2E browser testing with Playwright. Use when writing browser-driven
+  tests — leverage auto-waiting (no `waitForTimeout`), prefer user-visible
+  locators (`getByRole`, `getByText`, `getByLabel`) over CSS/XPath, reuse
+  `storageState` for auth, and enable trace-on-first-retry for CI debugging.
+vendor: playwright
+---
+
+# Skill: Playwright
+
+## Policy Capsule
+
+- Rely on Playwright's auto-waiting; never use `waitForTimeout` or hardcoded sleeps to paper over flakes.
+- Prefer user-visible locators (`getByRole`, `getByText`, `getByLabel`) over CSS selectors or XPath.
+- Reuse `storageState` to seed authenticated scenarios; do not repeat login flows in every test.
+- Use `toHaveScreenshot()` for critical visual surfaces; treat snapshot diffs as intentional reviews, not auto-refreshes.
+- Write tests independent of one another so they run in parallel; clean up shared state in fixtures, not afterwards.
+- Enable `trace: 'on-first-retry'` (or `'retain-on-failure'`) so CI failures are debuggable in the Trace Viewer.
+- Use a unique data set per test run, or tear down state explicitly, to prevent cross-test contamination.
+
+Standard operating procedures for robust, end-to-end (E2E) browser testing.
+
+## 1. Core Principles
+
+- **End-to-End focus:** Test the application as a user would, through the
+  browser.
+- **Auto-waiting:** Leverage Playwright's built-in auto-waiting instead of
+  hardcoded `waitForTimeout` calls.
+- **Resilience:** Write tests that survive minor UI changes (e.g., color tweaks)
+  by using robust selectors.
+
+## 2. Technical Standards
+
+- **Locators:** Use user-visible locators (e.g., `getByRole`, `getByText`,
+  `getByLabel`) over brittle CSS selectors or XPath.
+- **State Management:** Use `storageState` to reuse authentication between
+  tests, avoiding repetitive login flows.
+- **Visual Testing:** Use `toHaveScreenshot()` for critical UI layouts to detect
+  visual regressions.
+
+## 3. Best Practices
+
+- **Parallelism:** Ensure tests are independent so they can run concurrently to
+  reduce CI time.
+- **Tracing:** Enable trace recording on failure to quickly debug CI issues with
+  the Playwright Trace Viewer.
+- **Test Data:** Use a unique data set per test run or clean up state to prevent
+  cross-contamination.

package/.agents/skills/stack/qa/playwright-bdd/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: playwright-bdd
+description:
+  Wires Gherkin `.feature` files to Playwright via the `playwright-bdd`
+  library. Use when running BDD scenarios on a Playwright runtime — pairs
+  with the `gherkin-authoring` skill (scenario prose) and the `playwright`
+  skill (browser conventions). Drives execution by tag expression with
+  trace-first debugging and Playwright-native sharding.
+vendor: playwright
+---
+
+# Skill: playwright-bdd
+
+## Policy Capsule
+
+- Complete the pre-authoring grep-for-existing-steps checklist before writing any new scenario text; record the matches in your output.
+- Keep `.feature` files free of Playwright API calls — scenarios describe intent, step definitions translate to browser actions.
+- Generate step bindings into a dedicated directory (e.g. `.features-gen/`) and add it to `.gitignore`; never commit generated specs.
+- Drive runs by tag expression (`--grep "@smoke and not @flaky"`), not filename globs; use the canonical `@smoke`/`@risk-high`/`@platform-*`/`@domain-*` taxonomy.
+- Inject fixtures via `createBdd` rather than pulling singletons from module scope; reset persistent state through fixture teardown, not stray `After` hooks.
+- Reuse `storageState` for authenticated scenarios — create a logged-in user fixture instead of repeating login steps in `Background`.
+- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) enabled; reproduce failures by `@scenario-id` tag, not by title.
+- Shard with Playwright's native `--shard=i/N`; never partition by tag expression across CI jobs.
+
+Guidance for running Gherkin `.feature` files against Playwright via
+`playwright-bdd`. Pairs with the `gherkin-authoring` skill (scenario prose) and
+the `playwright` skill (browser-level conventions); this skill covers the wiring
+between them.
+
+> **Version:** consumers pick their own `playwright-bdd` version. This skill
+> documents behavioral constraints, not a pinned release.
+
+## Pre-authoring checklist (mandatory)
+
+The agent MUST complete every item below AND MUST include the results in its
+output report BEFORE any scenario text is written. See
+[§ Step Reuse — Grep Before You Write](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write)
+for rationale.
+
+1. Run `rg` against the project's steps directory and list every step signature
+   you will reuse. Format: one `Given/When/Then "…"` per line.
+2. For each scenario line you plan to author, identify the matching existing
+   step. For any line with no match, either rephrase to reuse an existing step
+   or record it as a gap. Do NOT author new step definitions during scenario
+   authoring.
+3. State the canonical domain tag and platform tag you will apply (or note
+   "Cross-Platform → no platform tag" per `gherkin-standards.md`).
+4. Confirm the AC's `data-testid`, URL, and payload hints will be stripped from
+   scenario prose.
+
+If you cannot complete every item, stop and report — do not proceed to scenario
+authoring.
+
+## 1. Core Principles
+
+- **One source of truth per scenario:** `.feature` files describe intent; step
+  definitions translate intent into Playwright calls. Never author browser
+  actions in `.feature` prose.
+- **Deterministic tag filtering:** every scenario carries enough tags that any
+  CI shard can be selected by a tag expression without inspecting file paths.
+- **Fixture-per-scenario isolation:** scenarios must not share mutable state.
+  Treat each scenario as a fresh browser context.
+- **Trace-first debugging:** keep the Playwright Trace Viewer workflow intact —
+  `playwright-bdd` wraps Playwright, it does not replace its diagnostics.
+
+## 2. Config Patterns
+
+- Generate step-definition bindings into a dedicated output directory (commonly
+  `.features-gen/`) and add it to `.gitignore`. Do not commit generated specs.
+- Point `playwright.config.ts` at the generated directory via `testDir`; keep a
+  single `defineBddConfig` block that lists `features` and `steps` paths.
+- Register the Cucumber HTML/JSON reporter alongside the Playwright HTML
+  reporter so a headless CI invocation emits machine-readable evidence
+  alongside the agent-driven `/qa-run-harness` sweep.
+- Use Playwright projects (not Cucumber profiles) for browser matrix fan-out —
+  keeps sharding, retries, and trace config in one place.
+
+## 3. Fixture Composition
+
+- Extend Playwright's `test` via `playwright-bdd`'s `createBdd` so fixtures
+  (auth state, API clients, seeded data) are injected into `Given`/`When`/
+  `Then` callbacks by name, not pulled from module-level singletons.
+- Layer fixtures: base Playwright fixtures → domain fixtures (authenticated
+  user, seeded tenant) → scenario-scoped helpers. Each layer depends only on the
+  layer below.
+- Reset persistent state with fixture teardown, not with `After` hooks buried in
+  step files — teardown order is then deterministic and visible in the fixture
+  graph.
+- Reuse `storageState` for authenticated scenarios; create a "logged-in user"
+  fixture rather than repeating login steps in `Background`.
+
+## 4. Tag-Filtered Execution
+
+- Drive runs via tag expressions, not filename globs:
+  `npx bddgen && npx playwright test --grep "@smoke and not @flaky"`.
+- Use the canonical tag taxonomy defined in
+  [`.agents/rules/gherkin-standards.md`](../../../../rules/gherkin-standards.md#tag-taxonomy)
+  (`@smoke`, `@risk-high`, `@platform-*`, `@domain-*`). Do not invent parallel
+  tag vocabularies in the runner config; extend via `@domain-*` only.
+- Wire tag-filtered headless runs to a single npm script so operators never
+  reconstruct the generate-then-run sequence by hand; the agent-driven
+  `/qa-run-harness` selector mirrors the same tag expressions for browser sweeps.
+- Fail the run if generation produces zero matching scenarios — a silent empty
+  suite is worse than a red build.
+
+## 5. Debug & Trace Workflow
+
+- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) in the Playwright
+  config. `playwright-bdd` preserves the trace attachment because each scenario
+  maps to a Playwright test.
+- Reproduce a single failing scenario with `--grep "@scenario-id"` rather than
+  the scenario title — titles change, tags are stable.
+- Open traces with `npx playwright show-trace` against the artifact produced
+  under `test-results/`; the trace timeline annotates each `Given`/`When`/
+  `Then` step, which is the primary debug affordance.
+- For step-definition bugs, run with `PWDEBUG=1` to drop into the inspector at
+  the failing step — do not add `page.pause()` calls inside step files.
+
+## 6. Sharding & CI Notes
+
+- Shard with Playwright's native `--shard=i/N`; do not partition by tag
+  expression across jobs — tag-sharding makes flake triage non-deterministic.
+- Run `bddgen` once per job before `playwright test`; cache the generated
+  directory only if the cache key includes every `.feature` and step file.
+- Publish the Cucumber HTML/JSON report as the evidence artifact consumed by the
+  `epic-testing` helper, alongside the Playwright HTML report and any trace
+  zips.
+- Quarantine `@flaky` scenarios with a dedicated job that does not gate the
+  merge queue; do not silently retry flakes in the main suite.
+
+## Recommended invocation template
+
+Use this template when invoking a subagent to author a `.feature` file from an
+Acceptance Criterion.
+
+```text
+You are an AI coding agent. Your sole task is to invoke the
+**stack/qa/playwright-bdd** skill (defined in this repo) to author one new
+acceptance scenario from a single Acceptance Criterion. You receive nothing
+about this codebase except the AC text and the skill itself — you must
+discover everything else (existing step library, naming conventions, etc.)
+through the skill's prescribed workflow.
+
+Follow the skill's guidance precisely. Your output will be evaluated
+against `.agents/rules/gherkin-standards.md`.
+
+**Skill to invoke.** Read `.agents/skills/stack/qa/playwright-bdd/SKILL.md`
+and follow it. Also read `.agents/rules/gherkin-standards.md` (which the
+skill references).
+
+**The Acceptance Criterion (your sole input).** {{AC_TEXT}}
+
+**Your task.**
+1. Read the skill and the gherkin rule.
+2. Per the skill's "Step Reuse — Grep Before You Write" section, grep
+   {{STEPS_DIR}} to discover the existing step vocabulary BEFORE
+   authoring. List the matches you found.
+3. Author a NEW `.feature` file at {{OUTPUT_PATH}} that covers this AC.
+4. You are FORBIDDEN from editing any file under {{STEPS_DIR}}. This
+   task tests scenario authorship and step REUSE. If a step you need does
+   not exist, you must either rephrase the scenario to reuse what exists,
+   or report that as a gap (do not silently invent).
+5. Tag the feature/scenario per the canonical taxonomy in
+   `gherkin-standards.md`.
+6. Honor every "Forbidden Patterns" rule. `data-testid` hints in the AC
+   parentheses are for the step-definition layer; they MUST NOT appear in
+   your scenario text.
+
+**Report back.** Sections A–E: discovered steps, exact `.feature` content,
+step-coverage analysis, forbidden-patterns self-audit, uncertainty/gaps.
+```
+
+This template encodes the invocation prompt used in the Epic C pilot of
+dsj1984/athlete-portal, where a general-purpose subagent — given only an AC and
+a pointer to this skill — produced a publishable scenario on the first attempt
+with **zero Forbidden-Patterns violations**, reused **4 of 5** needed steps from
+the existing library, and surfaced the single remaining step as a clean, named
+gap rather than inventing one. Future maintainers: resist the urge to "simplify"
+this template. Its explicit grep-before-author step, the hard prohibition on
+editing the steps directory, and the mandated gap-report section are what forced
+those outcomes.
+
+## 7. Cross-References
+
+- Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
+- Browser-level conventions: `.agents/skills/stack/qa/playwright/SKILL.md`.
+- Operator entry point: `.agents/workflows/qa-run-harness.md`.
+- Evidence handoff: `.agents/workflows/helpers/epic-testing.md`.

package/.agents/skills/stack/qa/qa-explore-driving/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: qa-explore-driving
+description:
+  Conventions for agent-driven exploratory QA driving — how the agent itself
+  drives a surface during `/qa-explore` (agent-led), as opposed to the
+  human-led `/qa-assist`. Use when the agent explores a running app via the
+  browser MCP (navigation-first, the default) or walks a static surface (the
+  documented interim until consumer persona-seeding lands), under a strictly
+  read-only capture invariant. The exploration procedure lives in
+  `.agents/workflows/qa-explore.md`; this skill is the driving-conventions
+  reference it leans on.
+---
+
+# Skill: qa-explore-driving
+
+## Policy Capsule
+
+- Drive the running app **by default** through the browser MCP, navigation-first: start at a root and reach each surface only via UI affordances — never URL-jump to a deep link.
+- Treat **static driving** (reading source, routes, and rendered markup without a live runtime) as the **documented interim** method, chosen at Plan time when a live runtime is not reachable — never the silent fallback.
+- Hold the **read-only capture invariant** absolutely: the agent makes no source edits and no product mutations while driving; the only write is appending to the `temp/qa/<sessionId>` ledger.
+- Authenticated driving depends on **consumer persona-seeding infrastructure that this Epic does not deliver**; without it, drive only the unauthenticated surface or fall back to static, and record the gap — never enter real credentials or fabricate a session.
+- Pick the driving method explicitly in the Plan phase (drive vs. static) and record it in the ledger; do not switch methods mid-surface without a new Plan note.
+- Every phase transition and every GitHub write is HITL-gated; the agent drives and captures, but never files or promotes findings autonomously.
+- Broken navigation, a missing affordance, or a guard redirect loop is a **finding**, not a workaround — record it and move on; do not route around it with a direct URL.
+- Scrub captured evidence (tokens, session cookies, PII) at the boundary via the shared redaction path before any finding reaches disk or GitHub.
+
+Guidance for the **agent-driven** half of exploratory QA. `/qa-explore` is the
+agent-led front-end (the agent drives, the operator watches); its human-led
+sibling is `/qa-assist` (the human drives, the agent scribes). The exploration
+**procedure** — argument parsing, phase gates, contract resolution, ledger
+plumbing — is the SSOT in
+[`qa-explore.md`](../../../../workflows/qa-explore.md); this skill shows **how**
+to apply the driving conventions that procedure depends on. The
+navigation-first execution and per-surface capture discipline are shared with
+[`qa-harness`](../qa-harness/SKILL.md) (the known-scenario sweep); browser
+instrumentation lives in
+[`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md);
+the read-only and no-PII boundaries are inviolable per
+[`security-baseline.md`](../../../../rules/security-baseline.md). Read this
+skill before driving a live surface; read the workflow for the phase order.
+
+## 1. Navigation-First Driving (the default)
+
+The agent reaches every surface the way a real user would. This is the
+load-bearing convention — it is what makes findings reflect a user-reachable
+state rather than an artifact of a deep link.
+
+- **Drive the running app by default.** When a live runtime is reachable, drive
+  it through the browser MCP (the chrome-devtools MCP surface). This is the
+  primary method; static driving is the interim alternative (§ 2), not the
+  norm.
+- **Start at a root.** Begin each surface at the app's home or dashboard and
+  reach the surface under test by clicking nav links, menu items, and buttons —
+  the same affordances a user has.
+- **Never URL-jump.** Do not navigate directly to a deep link to establish a
+  starting state. URL-jumping bypasses the app's real authorization and routing
+  flows, which both masks access-control gaps and produces findings that no
+  user could actually trigger.
+- **Broken navigation is a finding, not a workaround.** When an affordance is
+  missing, a nav link 404s, or a guard redirect loops, that is the finding. Do
+  not route around it with a direct URL — record it and move on.
+- **Observe, do not fabricate.** Use app-provided UI affordances to reach and
+  observe a surface. Never script the runtime to manufacture an outcome the
+  exploration is meant to discover.
+
+## 2. Static Driving — the Documented Interim
+
+Static driving is the **explicitly documented interim** method for when a live
+runtime is not reachable — most commonly because authenticated driving needs
+consumer persona-seeding infrastructure that does not yet exist (§ 4). It walks
+the surface from source, route definitions, and rendered markup rather than a
+running browser.
+
+- **Choose it at Plan time, never silently.** Static is a deliberate Plan-phase
+  decision recorded in the ledger ("method: static, reason: no reachable
+  authenticated runtime"), not an unannounced fallback the agent slips into
+  when the browser MCP hiccups.
+- **It is interim, not equivalent.** Static driving cannot exercise real
+  authorization, routing guards, or runtime console/network signal. Treat its
+  coverage as partial and say so in the ledger; a static pass does not close the
+  same coverage a driven pass would.
+- **Same read-only invariant.** Static driving reads source and routes; it makes
+  no edits. The read-only capture invariant (§ 3) applies identically.
+- **Promote to driving when the runtime lands.** Static is the bridge until the
+  consumer's persona-seeding infrastructure (§ 4) makes authenticated driving
+  possible. When that lands, re-run the surface driven; do not leave a surface
+  permanently static when it could be driven.
+
+## 3. The Read-Only Capture Invariant
+
+The agent-driven Capture phase is **strictly read-only**. This invariant is
+inviolable per [`security-baseline.md`](../../../../rules/security-baseline.md)
+and the Epic's security considerations — it is not a soft preference.
+
+- **No source edits.** The agent does not modify application code, config, or
+  tests while driving. Exploration observes; it never repairs.
+- **No product mutations.** The agent does not create, update, or delete product
+  data, submit destructive forms, or trigger irreversible actions to "see what
+  happens". When a surface's only path forward is a mutating action, record the
+  boundary as the finding and stop — do not cross it.
+- **The only write is the ledger.** The single permitted side effect of Capture
+  is appending finding lines to the session ledger under
+  `temp/qa/<sessionId>`. Everything else is observation.
+- **Scrub before persisting.** Strip tokens, session cookies, Authorization
+  headers, and PII from captured console and network evidence via the shared
+  redaction path **before** any finding reaches disk or GitHub. Captured
+  evidence is untrusted until scrubbed.
+- **HITL gates every write outward.** Phase transitions and GitHub writes
+  (ticket creation, promotion) happen only behind an operator confirmation gate.
+  The agent never files or promotes findings autonomously.
+
+## 4. Authenticated Driving Depends on Consumer Infra (Not Delivered Here)
+
+Driving an **authenticated** surface requires signing in as a seeded persona.
+That seeding — provisioning a test persona with the right org, role, and data
+so the agent can reach a logged-in surface navigation-first — is **consumer
+persona-seeding infrastructure that this Epic does not deliver**. It is an
+explicit non-goal of the `/qa-explore` rebuild.
+
+- **Unauthenticated surface only, by default.** Without persona-seeding infra in
+  the consumer project, drive only the surface reachable without sign-in, or
+  fall back to static driving (§ 2) for the authenticated surface. Record the
+  gap in the ledger so the partial coverage is visible.
+- **Never enter real credentials.** The agent MUST NOT type real usernames,
+  passwords, or tokens to reach an authenticated surface, and MUST NOT fabricate
+  or forge a session. This is a hard security boundary, not a convenience to
+  work around.
+- **The dependency is the consumer's to satisfy.** When a consumer wants driven
+  authenticated exploration, the consumer supplies a dev sign-in seam and seeded
+  personas (the same shape `qa-harness` resolves via its contract). Until then,
+  authenticated coverage is static or deferred — say which in the ledger.
+- **Surface the gap, don't paper over it.** A surface that could not be driven
+  because authenticated seeding is absent is itself a coverage signal worth
+  recording, not a silent skip.
+
+## 5. Cross-References
+
+- Run procedure (SSOT): [`qa-explore.md`](../../../../workflows/qa-explore.md).
+- Known-scenario sibling sweep: [`qa-harness`](../qa-harness/SKILL.md).
+- Browser instrumentation: [`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md).
+- Read-only / no-PII boundary: [`security-baseline.md`](../../../../rules/security-baseline.md).
+- Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: qa-harness
+description:
+  Conventions for the agent-driven QA harness that drives Gherkin scenarios
+  through a real browser. Use when executing `/qa-run-harness` or instrumenting
+  a live surface — covers navigation-first execution, per-surface console and
+  network capture, design-token visual checks, and the framework-generic
+  heuristic cards for turning signal into findings. The harness procedure lives
+  in `.agents/workflows/qa-run-harness.md`; this skill is the conventions
+  reference it leans on.
+---
+
+# Skill: qa-harness
+
+## Policy Capsule
+
+- Drive every scenario navigation-first: start at a root and reach the surface under test only via UI affordances — never URL-jump to a deep link to set up a `Given`.
+- Assert `Then` outcomes semantically against the accessibility snapshot (roles, accessible names, visible text); never via DOM/CSS/XPath selectors, HTTP status codes, response bodies, or DB rows.
+- Capture console and network per surface; turn each non-allowlisted console error and each failed/error-status request into one structured `F#` finding.
+- Filter console through `qa.consoleAllowlist` via `filterConsoleMessages`; treat the allowlist as a benign-noise filter, never as a security control to silence genuine errors.
+- Spot-check surfaces against `qa.designTokens` when set; flag gross token violations (off-palette colors, off-scale spacing/typography) as findings.
+- Scrub captured console and network of tokens, session cookies, and PII before rendering any finding — findings are posted to GitHub at approval time.
+- Bundle findings by likely root cause into a draft for operator sign-off; the harness never files tickets autonomously.
+- Resolve the `qa` contract first and fail loudly when it is absent or malformed; there is no auto-detection fallback and no headless degrade.
+
+Guidance for executing the agent-driven QA harness through a real browser (the
+chrome-devtools MCP surface). The harness **procedure** — argument parsing,
+step ordering, contract resolution sequence — is the SSOT in
+[`.agents/workflows/qa-run-harness.md`](../../../../workflows/qa-run-harness.md);
+this skill shows **how** to apply the instrumentation and inspection
+conventions that procedure depends on. The assertion-tier rules it enforces
+live in [`testing-standards.md`](../../../../rules/testing-standards.md)
+(§ Assertion Placement); scenario prose conventions live in
+[`gherkin-authoring`](../gherkin-authoring/SKILL.md); browser-locator
+discipline is shared with [`playwright`](../playwright/SKILL.md). Read this
+skill before instrumenting a live surface; read the workflow for the run order.
+
+## 1. Navigation-First Execution
+
+The harness reaches every surface the way a real user would. This is the
+load-bearing convention — it is what makes findings reflect a user-reachable
+state rather than an artifact of a deep link.
+
+- **Start at a root.** After sign-in, begin each scenario at the app's home or
+  dashboard. Reach the surface under test by clicking nav links, menu items,
+  and buttons — the same affordances a user has.
+- **Never URL-jump.** Do not `navigate_page` directly to a deep link to
+  establish a `Given`. URL-jumping bypasses the app's real authorization and
+  routing flows, which both masks access-control gaps and produces findings
+  that no user could actually trigger.
+- **Broken navigation is a finding, not a workaround.** When an affordance is
+  missing, a nav link 404s, or a guard redirect loops, that is the finding.
+  Do not route around it with a direct URL — record it and move on.
+- **Map Gherkin to browser actions.** `Given` establishes state by navigating
+  from the root (sign in as the persona, walk to the starting surface, seed via
+  UI where the manifest does not pre-seed). `When` performs the single user
+  action (`click`, `fill_form`, then `wait_for` the transition). Use
+  `evaluate_script` only for app-provided hooks — never to fabricate the
+  outcome a `Then` is meant to observe.
+
+### Semantic `Then` assertion
+
+Assert every `Then` against the accessibility snapshot from `take_snapshot`,
+matching on **roles, accessible names, labels, and visible text** that express
+the user-visible outcome — "a banner with text _Invoice sent_ is visible", "a
+row for _ACME Corp_ appears in the invoices table".
+
+- **Never** assert against brittle DOM/CSS/XPath selectors.
+- **Never** assert on HTTP status codes, response bodies, or DB rows inside a
+  scenario — those are contract-tier concerns (see
+  [`testing-standards.md` § Assertion Placement](../../../../rules/testing-standards.md#assertion-placement)).
+- A `Then` that can only be expressed as a wire-shape or DB check is a signal
+  the scenario is **mis-tiered**, not a license to break the semantic rule.
+
+Record each scenario's result (pass / fail / blocked), the surface it ended on,
+and a one-line user-visible symptom for any failure.
+
+## 2. Per-Surface Console & Network Capture
+
+Instrument each surface the moment you land on it, before moving on. Capture is
+**per surface** so evidence is attributable to a concrete user-reachable state.
+
+### 2.1 Console
+
+1. Capture with `list_console_messages` on the current surface.
+2. Filter through the contract's `consoleAllowlist` using
+   [`filterConsoleMessages`](../../../../scripts/lib/qa/console-allowlist.js).
+   The filter is the pure decision layer: it escalates only messages at level
+   `error` / `severe`, suppresses any message matched by an allowlist
+   substring pattern, and returns one structured finding per surviving error in
+   capture order (`F1`, `F2`, …).
+3. Each surviving console error becomes one `F#` finding. Non-error levels
+   (`log`, `info`, `debug`, `warning`) are never escalated.
+
+The allowlist is a **benign-noise filter, not a security control.** It exists
+to suppress known, expected, harmless console chatter (a third-party widget's
+deprecation notice, a dev-only HMR log). Never expand it to silence a genuine
+error signal — if a real error is noisy, fix the error, do not allowlist it.
+Allowlist matching is case-sensitive substring matching, so patterns stay
+readable in `.agentrc.json` without regex escaping; a blank pattern is ignored
+rather than matching everything.
+
+### 2.2 Network
+
+Capture with `list_network_requests` on the surface. Failed requests and
+error-status responses (4xx / 5xx) become findings alongside the
+console-derived set, sharing the same `F#` numbering across the surface.
+
+### 2.3 Design-token visual check
+
+When the contract's `designTokens` pointer is set (it defaults to `null`),
+spot-check the rendered surface against the token source. Flag **gross** token
+violations as findings — the goal is catching drift, not pixel-perfect audits:
+
+- **Color** — text or controls rendered in an off-palette color where a token
+  color is expected (a hard-coded `#3366ff` where the primary token is the
+  contract).
+- **Spacing** — padding/margins that visibly break the spacing scale (a
+  one-off `13px` gutter amid an 8px-based scale).
+- **Typography** — font families, sizes, or weights outside the type scale.
+
+A gross violation is one a designer would call a regression on sight; subtle
+sub-pixel differences are not harness findings. When `designTokens` is `null`,
+skip this check entirely — do not invent a token source.
+
+## 3. Findings — the `F#` Shape
+
+Every captured problem is normalized into the structured `F#` finding shape so
+the draft bundle stays diffable and the schema validates:
+
+```jsonc
+{
+  "id": "F1",                       // 1-based, assigned per surface across console+network
+  "classification": "console-error", // console-error | network-error | visual-token | ...
+  "surface": "/invoices",           // the user-reachable surface, not a deep link
+  "symptom": "...",                 // one-line user-visible / captured symptom
+  "likelyRootCause": null,          // heuristic card output (§4); null until enriched
+  "disposition": "follow-up",       // blocker | follow-up
+  "acceptance": null,               // AC this folds into, when known
+  "foldsInto": "F2",                // optional: another finding this is a duplicate facet of
+  "evidence": {
+    "console": [{ "level": "error", "text": "..." }],
+    "network": []
+  }
+}
+```
+
+- **Determinism is load-bearing.** Re-running the same selector over the same
+  captured console with the same allowlist yields the same findings in the same
+  order. Do not reorder or renumber findings between sweeps.
+- **Scrub before rendering.** Before any finding's `evidence` is rendered or
+  drafted, strip tokens, session cookies, Authorization headers, and PII from
+  the captured console and network per
+  [`security-baseline.md`](../../../../rules/security-baseline.md). Findings are
+  posted to GitHub at approval time — captured evidence is untrusted until
+  scrubbed.
+
+## 4. Framework-Generic Heuristic Cards
+
+The harness ships **framework-generic** root-cause heuristics — they reason
+about symptoms, not about any one frontend framework. Use a card to populate
+`likelyRootCause` and to set `disposition`. The cards are guidance, not a
+classifier: when a symptom matches none cleanly, leave `likelyRootCause: null`
+and let the operator triage from the symptom.
+
+| Symptom pattern | Likely root cause | Default disposition |
+| --- | --- | --- |
+| `404` / `Not Found` on a navigation or asset request | Dead route, broken link, or missing build artifact | follow-up (blocker if it breaks the scenario path) |
+| `401` / `403` reaching a surface the persona should see | Missing or over-tight authorization check; guard misconfig | blocker |
+| `500` / `502` / `503` on a user action | Server-side fault behind the action | blocker |
+| Uncaught `TypeError` / `ReferenceError` in console | Null/undefined dereference or missing binding in client code | blocker when it breaks the surface, else follow-up |
+| `Failed to fetch` / `NetworkError` / CORS-rejected request | Misconfigured CORS allowlist, wrong origin, or a downed dependency | follow-up |
+| Hydration / mismatch warning escalated to error | Server/client render divergence | follow-up |
+| Off-palette color, off-scale spacing/typography | Design-token drift — hard-coded value bypassing the token | follow-up |
+| Repeated identical console error across many surfaces | A shared component or global bootstrap fault | fold the duplicates into one finding via `foldsInto` |
+
+Heuristics for working the cards:
+
+- **Fold duplicates.** When the same error fires on many surfaces, emit one
+  finding and point the rest at it with `foldsInto` rather than filing N copies.
+- **Blocker vs. follow-up.** A finding is a **blocker** when it breaks the
+  scenario's user-visible outcome or exposes an authorization gap. Everything
+  else (noise that does not break the journey, cosmetic token drift) is a
+  **follow-up**.
+- **Symptom over diagnosis.** When unsure of the root cause, record the precise
+  symptom and leave `likelyRootCause: null`. A wrong guess is worse than an
+  honest "unknown" the operator can triage.
+
+## 5. Draft & Sign-Off (Never File Autonomously)
+
+Bundle findings **by likely root cause** into proposed follow-up tickets with
+`Depends-on` / `Blocks` relationships, then present the draft for operator
+approval. The harness **MUST NOT** create tickets autonomously — it stops at a
+draft. The operator-approval gate is the safety boundary against spurious
+filing. When the run was triggered from an Epic-testing context, hand the
+**approved** findings to the Epic-testing helper for attachment to the Epic's
+QA evidence ticket.
+
+## 6. Sign-In & Contract Discipline
+
+- **Resolve the `qa` contract first.** Before any browser work, resolve the
+  contract via `resolveQaContract(config)`. When the block is absent,
+  malformed, or missing a required field, the resolver **throws** — relay its
+  verbatim message and STOP. There is no auto-detection fallback.
+- **Dev seam only.** Sign in once per persona via the contract's `signInSeam`
+  (`kind: 'url'` dev seam or `kind: 'skill'`). **Never** enter real
+  credentials. Confirm authenticated state with a `take_snapshot` before
+  driving any scenario.
+- **No headless fallback.** The chrome-devtools MCP surface is a host-provided
+  runtime dependency. If it is unavailable, degrade with a clear error and stop
+  — never fall back to the retired headless BDD runner.
+
+## 7. Cross-References
+
+- Run procedure (SSOT): [`qa-run-harness.md`](../../../../workflows/qa-run-harness.md).
+- Console filter module: [`console-allowlist.js`](../../../../scripts/lib/qa/console-allowlist.js).
+- Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).
+- Scenario prose: [`gherkin-authoring`](../gherkin-authoring/SKILL.md).
+- Browser-locator discipline: [`playwright`](../playwright/SKILL.md).
+- Evidence scrubbing: [`security-baseline.md`](../../../../rules/security-baseline.md).

package/.agents/skills/stack/qa/vitest/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: vitest
+description:
+  Writes fast, isolated unit and integration tests with Vitest. Use when each
+  test must run on file-save without shared state — `vi.mock()` for external
+  deps, `vi.spyOn()` for call monitoring, AAA structure, and edge-case
+  coverage for null/undefined/boundary inputs.
+vendor: vitest
+---
+
+# Skill: Vitest
+
+## Policy Capsule
+
+- Keep each test independent — never share mutable state between tests; reset mocks in `afterEach`.
+- Mock external dependencies with `vi.mock()`; use `vi.spyOn()` only to observe call shape, not to replace logic.
+- Structure tests as Arrange / Act / Assert — do not interleave the three phases.
+- Use descriptive titles in the `describe('Component', () => { it('should [action] when [condition]') })` form.
+- Cover error paths, null/undefined inputs, and boundary conditions, not just the happy path.
+- Use snapshots only for large, stable data structures; avoid them for frequently changing UI to prevent snapshot fatigue.
+- Aim for 80%+ coverage on business logic and edge cases; audit with `vitest --coverage`.
+- Test observable behavior, not internal implementation details; refactors should not require rewriting passing tests.
+
+Guidelines for writing fast, reliable unit and integration tests.
+
+## 1. Core Principles
+
+- **Speed:** Tests should be fast enough to run on every file save.
+- **Isolation:** Each test must be independent. Avoid shared state between
+  tests.
+- **Confidence:** Tests should verify behavior, not implementation details.
+
+## 2. Technical Standards
+
+- **Mocking:** Use `vi.mock()` for external dependencies (APIs, network calls)
+  and `vi.spyOn()` for monitoring function calls.
+- **Snapshot Testing:** Use snapshots for large, stable data structures, but
+  avoid them for frequently changing UI components to prevent "snapshot
+  fatigue."
+- **Coverage:** Aim for 80%+ coverage on business logic and edge cases. Use
+  `vitest --coverage` for auditing.
+
+## 3. Best Practices
+
+- **Descriptive Titles:** Use the
+  `describe('Component/Utility', () => { it('should [action] when [condition]') })`
+  pattern.
+- **Arrange-Act-Assert (AAA):** Structure tests clearly into setup (Arrange),
+  execution (Act), and verification (Assert) phases.
+- **Edge Cases:** Always include tests for error states, null/undefined inputs,
+  and boundary conditions.