mandrel 1.57.0

package/.agents/skills/stack/frontend/tailwind-v4/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: tailwind-v4
+description:
+  Implements maintainable styling with Tailwind CSS v4. Use when writing
+  styles in v4 projects — CSS-first configuration via `@theme` blocks (never
+  `tailwind.config.ts/js`), mobile-first breakpoints, full class names (no
+  string interpolation), and no arbitrary `p-[13px]`-style values.
+vendor: tailwind
+---
+
+# Skill: Tailwind CSS v4
+
+## Policy Capsule
+
+- Configure the theme via CSS-first `@theme` blocks; never use `tailwind.config.ts` or `tailwind.config.js` in v4 projects.
+- Prefer atomic utility classes (`flex`, `p-4`, `text-lg`) over hand-written CSS classes.
+- Use mobile-first breakpoints (`sm:`, `md:`, `lg:`, `xl:`); never write desktop-first overrides.
+- Define `hover:`, `focus-visible:`, and `active:` states explicitly on every interactive element.
+- Arbitrary values (`p-[13px]`) are prohibited — map one-off values to a `@theme` CSS variable instead.
+- Never build utility classes by string interpolation (e.g. `text-${color}`); always use full literal class names so the compiler detects them.
+- Adhere to the design system's spacing, color, and typography tokens defined in `@theme` variables.
+- For repeated UI patterns, extract a component or a CSS `@apply` block — do not let class strings bloat in JSX.
+
+Rules for implementing high-performance, maintainable styling using the latest
+Tailwind CSS specification.
+
+## 1. Core Principles
+
+- **CSS-First Configuration:** Use CSS variables for theme customization within
+  the `@theme` block. **NEVER** use `tailwind.config.ts` or `tailwind.config.js`
+  in v4 projects.
+- **Modern Syntax:** Leverage the new `@theme` directive, fluid design
+  utilities, and lightning-fast compilation.
+- **Token Consistency:** Strictly adhere to the design system's spacing, color,
+  and typography tokens defined in the CSS variables.
+
+## 2. Technical Standards
+
+- **Utility Usage:** Prefer atomic utility classes (`flex`, `p-4`, `text-lg`)
+  over custom CSS classes.
+- **Responsive Design:** Use mobile-first breakpoints (`sm:`, `md:`, `lg:`,
+  `xl:`).
+- **Interactive States:** Explicitly define `hover:`, `focus-visible:`, and
+  `active:` states for all interactive elements to ensure a premium feel.
+- **Arbitrary Values:** **STRICTLY PROHIBITED** (`p-[13px]`) unless explicitly
+  required by a one-off legacy asset. Always map unique values to a temporary
+  CSS variable in the `@theme` block instead.
+
+## 3. Best Practices
+
+- **Class Ordering:** Use the standard Tailwind class ordering (Layout -> Box
+  Model -> Typography -> Visual -> Misc).
+- **Component Patterns:** For repeated UI patterns (e.g., buttons), use a
+  dedicated component or a reusable `@apply` block in a CSS file to avoid
+  class-string bloat.
+- **Dynamic Classes:** Never use string interpolation to create utility classes
+  (e.g., `text-${color}`). Always use full class names to ensure the compiler
+  detects them.

package/.agents/skills/stack/frontend/ui-accessibility-engineer/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ui-accessibility-engineer
+description:
+  Enforces mobile-first Tailwind CSS and strict WCAG 2.1 AA compliance for
+  user-facing UI. Use when building UI components — utility classes only (no
+  custom CSS or inline `style={{}}`), mobile-first breakpoints, visible focus
+  states, alt text, and 4.5:1 contrast.
+vendor: tailwind
+---
+
+# UI/UX Accessibility & Styling Engineer
+
+## Policy Capsule
+
+- Style only with Tailwind utility classes; never write custom CSS files or inline `style={{}}` objects in components.
+- Follow mobile-first responsive design: default classes target mobile, `md:` / `lg:` prefixes scale up.
+- Give every interactive element a visible focus state (`focus:ring`, `focus-visible:*`).
+- Provide meaningful `alt` text on every image; empty `alt=""` only for purely decorative imagery.
+- Meet WCAG 2.1 AA contrast: minimum 4.5:1 for normal text, 3:1 for large text.
+- Ensure every interactive element is reachable and triggerable via keyboard alone.
+- Use semantic HTML elements (`<button>`, `<nav>`, `<main>`) before reaching for ARIA roles.
+
+**Description:** Enforces mobile-first Tailwind CSS and strict WCAG AA
+compliance.
+
+**Instruction:** You are building user-facing interfaces.
+
+- Strictly use Tailwind CSS utility classes. DO NOT write custom CSS or inline
+  `style={{}}` objects.
+- Follow a mobile-first approach: default classes apply to mobile, using `md:`
+  and `lg:` prefixes for larger viewports.
+- Enforce WCAG 2.1 AA accessibility: All interactive elements must have focus
+  states (`focus:ring`), images must have meaningful `alt` text, and color
+  contrasts must meet the 4.5:1 ratio.

package/.agents/skills/stack/qa/audit-accessibility/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: audit-accessibility
+description:
+  Audits sites and apps for WCAG 2.1 Level AA compliance using automated and
+  manual testing tools. Use when running an accessibility audit or building a
+  remediation plan — semantic HTML, contrast, focus management, keyboard
+  reachability, and axe-core integration in Vitest/Playwright.
+---
+
+# Skill: Accessibility Audit (A11y)
+
+## Policy Capsule
+
+- Use semantic HTML (`<nav>`, `<main>`, `<header>`, `<button>`) before reaching for ARIA roles.
+- Maintain a minimum 4.5:1 contrast for normal text and 3:1 for large text.
+- Ensure a visible focus indicator on every focusable element and a logical tab order across the page.
+- Use `aria-label`, `aria-labelledby`, and `aria-describedby` only when semantic HTML cannot express the intent.
+- Treat automated scans as 40–50% coverage only; follow every audit with manual keyboard and screen-reader checks.
+- Integrate `axe-core` into Vitest or Playwright runs so a11y regressions are caught in CI.
+- Give every `<img>` an `alt` attribute — empty for decorative, descriptive for functional.
+- Verify every interactive element is reachable and triggerable via keyboard alone.
+
+Protocols for ensuring WCAG 2.1 Level AA compliance using automated and manual
+testing tools.
+
+## 1. Core Principles
+
+- **Inclusive Design:** The application must be usable by everyone, regardless
+  of disability.
+- **Automated First, Not Only:** Use tools to catch 40-50% of issues, then
+  follow with manual keyboard and screen reader checks.
+
+## 2. Technical Standards
+
+- **Semantic HTML:** Use correct tags (e.g., `<nav>`, `<main>`, `<header>`,
+  `<button>`) to provide native accessibility features.
+- **Contrast Ratios:** Maintain a minimum 4.5:1 contrast for normal text and 3:1
+  for large text.
+- **Focus Management:** Ensure a visible focus indicator is always present and
+  the tab order is logical.
+- **ARIA Labels:** Use `aria-label`, `aria-labelledby`, and `aria-describedby`
+  only when standard HTML is insufficient.
+
+## 3. Best Practices
+
+- **pa11y/axe:** Integrate `axe-core` into Vitest/Playwright tests for automated
+  regressions.
+- **Alt Text:** Every image must have an `alt` attribute (empty for decorative
+  images, descriptive for functional ones).
+- **Keyboard Navigation:** Every interactive element must be reachable and
+  triggerable via keyboard alone.

package/.agents/skills/stack/qa/gherkin-authoring/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: gherkin-authoring
+description:
+  Authors `.feature` files that stay business-readable, translate cleanly from
+  PRD acceptance criteria, and reuse a shared step-definition library. Use
+  when writing or editing scenarios — the SSOT enforcement rules live in
+  `.agents/rules/gherkin-standards.md`; this skill shows authors how to apply
+  them.
+---
+
+# Skill: gherkin-authoring
+
+## Policy Capsule
+
+- Write `Given` clauses as stative preconditions, `When` as a single business action, and `Then` as a user-visible outcome.
+- Allow exactly one `When` per scenario; if you need two, split into two scenarios.
+- Never assert on HTTP status codes, SQL state, DOM selectors, URLs, or JSON payloads inside `.feature` prose — push those to contract tests.
+- Tag every Scenario or Outline with exactly one canonical `@domain-*` tag and the appropriate risk/platform tags from the gherkin-standards taxonomy.
+- Use `Background` only when every scenario in the file genuinely shares the precondition with no per-scenario variation.
+- Reuse existing step definitions: grep the steps tree for the verb stem before authoring a new step.
+- Author one scenario per PRD acceptance criterion; for bounded matrices, use a Scenario Outline with ≤12 Examples rows.
+- Use third-person present-tense, role-qualified actors (`the billing-admin`), never first person.
+
+Guidance for authoring `.feature` files that stay business-readable, translate
+cleanly from PRD acceptance criteria, and reuse a shared step-definition
+library. The enforcement rules — tag taxonomy, forbidden patterns, Outline
+conventions, selector discipline, step reuse — live in
+[`.agents/rules/gherkin-standards.md`](../../../../rules/gherkin-standards.md),
+which is the SSOT. This skill shows authors **how** to apply those rules; read
+the rule file for the **what**. Runtime wiring for Playwright consumers is
+covered by [`playwright-bdd`](../playwright-bdd/SKILL.md); test-layer scope is
+covered by
+[`testing-standards.md`](../../../../rules/testing-standards.md).
+
+## 1. Canonical Given / When / Then Phrasing
+
+`.feature` prose is written for a product-minded reader, not a test harness.
+Each clause has exactly one job:
+
+- **Given** — a precondition that is *already true* when the scenario starts.
+  Stative, past or present tense. No actions.
+  - Good: `Given a signed-in account-owner with an unpaid invoice`.
+  - Bad: `Given the user clicks the login button` (that's a When).
+- **When** — the single business action under test. One verb, one actor, one
+  event. Splitting a When into multiple clauses is almost always wrong — move
+  the extra clauses into Given.
+  - Good: `When they issue the invoice`.
+  - Bad: `When they log in and issue the invoice and download the PDF`.
+- **Then** — an observable, user-visible outcome. Assert what the *user* sees
+  or what the *business* records, not what the system emits internally.
+  - Good: `Then the invoice appears in the issued invoices list`.
+  - Bad: `Then a 201 is returned` (forbidden; see
+    [gherkin-standards § Forbidden Patterns](../../../../rules/gherkin-standards.md#forbidden-patterns)).
+- **And / But** — continuation clauses. They inherit the mood of the most
+  recent Given/When/Then. Never start a scenario with And/But.
+
+Voice and tense:
+
+- Third-person, present tense. `the user`, `an admin`, `a billing-admin`
+  (role-qualified nouns, not "I" or "we").
+- One clause, one fact. Comma-chained facts hide compound assertions.
+- Numbers and identifiers go in `Examples` tables or fixtures, not inline
+  prose. Prose should read the same whether the underlying fixture has 1 or
+  10,000 rows.
+
+## 2. Translating PRD Acceptance Criteria to Scenarios
+
+PRD ACs are the raw material. The authoring move is **one AC → one scenario**
+unless the AC encodes a matrix (in which case it becomes a Scenario Outline —
+see §3).
+
+Walkthrough — a PRD AC from a billing feature:
+
+> **AC-3:** When a billing-admin issues an invoice for a customer with a
+> negative balance, the system rejects the issue and shows an error naming the
+> outstanding amount.
+
+Translation steps:
+
+1. **Identify the domain.** Billing → tag the scenario `@domain-billing`.
+2. **Identify the actor and precondition.** "billing-admin", "customer with a
+   negative balance" → two Givens.
+3. **Identify the single action.** "issues an invoice" → one When.
+4. **Identify the observable outcome.** "rejects the issue and shows an error
+   naming the outstanding amount" → two Thens. The first asserts the business
+   outcome (rejection); the second asserts the user-visible detail (error
+   names the amount).
+5. **Pick the risk tag.** If the originating ticket was `risk::high`, add
+   `@risk-high`. Smoke tag only if this is a critical path on every PR.
+
+Resulting scenario:
+
+```gherkin
+@domain-billing @risk-high
+Scenario: Issuing an invoice is rejected when the customer has a negative balance
+  Given a signed-in billing-admin
+  And a customer with a negative account balance
+  When the billing-admin issues an invoice for that customer
+  Then the issue is rejected
+  And the rejection message names the outstanding amount
+```
+
+Heuristics:
+
+- If a single AC needs more than **one When**, it is really two ACs. Split
+  before you write.
+- If a Then starts with "and the database has…" or "and the API returned…",
+  you have crossed into step-definition or contract-test territory. Rewrite
+  it as user-visible language or move the assertion to a contract test (see
+  [testing-standards](../../../../rules/testing-standards.md)).
+- If an AC says "the system logs X", that's an engineering non-functional
+  requirement — not a BDD scenario. Cover it with a focused unit or
+  integration test, not a `.feature` file.
+- When a PRD AC is phrased negatively ("non-admins cannot export"), prefer a
+  Scenario Outline if there are multiple negative roles; write a plain
+  Scenario if there is exactly one.
+
+## 3. Background vs. Given — and Outline vs. Multi-Scenario
+
+Two authoring decisions that authors routinely get wrong.
+
+### 3.1 Background vs. Given
+
+`Background` runs before **every** scenario in the file. Use it only when:
+
+- Every scenario in the file genuinely shares the precondition, **and**
+- The precondition has no per-scenario variation (no `<placeholders>`,
+  no per-scenario data).
+
+Prefer a per-scenario Given when:
+
+- Only some scenarios need the precondition. A Background that applies to
+  four out of five scenarios is a Background for none of them; move it.
+- The precondition varies by role, plan tier, or fixture shape. Variation
+  belongs in a Scenario Outline's Examples, not in Background.
+- Readers cannot understand the scenario without scrolling up to read
+  Background. Background is a shortcut; if it hurts readability, inline it.
+
+Rule of thumb: if you find yourself writing *"except in the admin scenario,
+where the Background step is actually…"*, delete the Background.
+
+### 3.2 Scenario Outline vs. multiple Scenarios
+
+Use `Scenario Outline` when the **same behavior** is exercised across a
+**bounded matrix** (roles, plan tiers, locales). The shape of the scenario —
+Givens, When, Thens — is identical; only the data varies.
+
+Use multiple `Scenario` blocks when:
+
+- The Givens differ structurally (not just in value).
+- The When verb differs.
+- The Then outcomes differ in kind, not just in value. "Delivered vs.
+  denied" is one outcome column (see Outline skeleton in
+  [gherkin-standards § Scenario Outline Conventions](../../../../rules/gherkin-standards.md#scenario-outline-conventions)).
+  "Email is sent vs. invoice is issued vs. account is suspended" are three
+  different scenarios.
+
+Scale guardrails (also in gherkin-standards):
+
+- Keep `Examples` tables under ~12 rows. Larger tables hide distinct
+  behaviors behind a shared skeleton.
+- Split `Examples` by tag when rows need different tags (e.g. `@risk-high`
+  on admin rows only).
+
+## 4. Step-Definition Library Structure
+
+Authoring scenarios and maintaining steps are the same job split across two
+files. The library layout below keeps that coupling visible.
+
+### 4.1 Layout
+
+```text
+tests/
+  steps/
+    _common/          # actor, auth, navigation — reused across every domain
+      auth.steps.ts
+      navigation.steps.ts
+    billing/          # one directory per @domain-* tag
+      invoices.steps.ts
+      subscriptions.steps.ts
+    auth/
+      signin.steps.ts
+    _deprecated/      # steps pending migration; see §4.4
+```
+
+- One directory per `@domain-*` tag. `_common/` holds cross-cutting steps
+  (sign-in, navigation, generic waits handled at the fixture layer).
+- Files are named by the noun the steps act on
+  (`invoices.steps.ts`, not `billing-steps-1.ts`). A new noun is a new file.
+- Avoid deep nesting. Two levels (`steps/<domain>/<noun>.steps.ts`) is the
+  ceiling for most projects.
+
+### 4.2 Naming
+
+Step text follows the scenario text verbatim — if the scenario reads `the
+invoice appears in the issued invoices list`, the step regex matches exactly
+that phrase. Divergence between scenario prose and step text is a bug.
+
+- Parameterize only over values that vary across scenarios. A step that
+  accepts `{string}` for a literal that is always the same value is over-
+  parameterized; bake the constant in and rename the step.
+- Role-qualified actors (`{actor}`) read better than generic `{string}`.
+  Define a custom parameter type that resolves `account-owner`, `billing-admin`,
+  `viewer` to fixtures.
+- Keep step implementations ≤20 lines. Longer implementations indicate a
+  missing helper (domain fixture, page object, API client).
+
+### 4.3 Reuse Before Authoring
+
+The non-negotiable workflow is in
+[gherkin-standards § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write):
+grep the step tree for the verb stem before writing anything new. In practice:
+
+1. Search for the verb: `rg -n "issues? an invoice" tests/steps`.
+2. If the phrase exists, **change your scenario** to use that phrase. Do not
+   fork a near-duplicate step.
+3. If a near-match exists, extend the existing step (add a parameter, widen
+   the regex) and update every call site in the same PR.
+4. Only when no reasonable match exists, add a new step in the correct
+   domain directory.
+
+### 4.4 Deprecation
+
+When a step is superseded:
+
+1. Move the old definition into `steps/_deprecated/` and annotate it with a
+   one-line comment naming the replacement.
+2. Migrate every call site to the replacement in the same PR.
+3. Delete the `_deprecated/` entry when the migration lands.
+
+Never leave two live step definitions that mean the same thing. Parallel
+vocabularies rot the suite faster than any other source of maintenance cost.
+
+## 5. Authoring Checklist
+
+Before opening a PR that adds or edits a `.feature` file:
+
+- [ ] Every Scenario/Outline carries exactly one `@domain-*` tag.
+- [ ] No forbidden patterns (SQL, status codes, selectors, URLs, payloads,
+      framework names, explicit waits) appear in prose.
+- [ ] Each scenario has exactly one `When`.
+- [ ] `Then` clauses assert user-visible outcomes, not implementation.
+- [ ] `Background` is justified (applies to every scenario in the file).
+- [ ] If a Scenario Outline is used, the matrix is bounded (≤12 rows) and the
+      shape is truly identical across rows.
+- [ ] Every step phrase grep-matches an existing step definition **or** is
+      accompanied by a new step definition in the right domain directory.
+- [ ] Reads standalone — a product reader who has never seen the codebase can
+      understand the intent without opening a step file.
+
+## 6. Cross-References
+
+- SSOT rules: [`.agents/rules/gherkin-standards.md`](../../../../rules/gherkin-standards.md).
+- Runtime wiring: [`playwright-bdd`](../playwright-bdd/SKILL.md).
+- Browser-level conventions: [`playwright`](../playwright/SKILL.md).
+- Test-layer scope: [`testing-standards.md`](../../../../rules/testing-standards.md).
+- Example feature: [`examples/invoice-issue.feature`](./examples/invoice-issue.feature).

package/.agents/skills/stack/qa/gherkin-authoring/examples/invoice-issue.feature

@@ -0,0 +1,41 @@
+@domain-billing
+Feature: Issuing invoices
+  Billing admins and account owners issue invoices to customers. The system
+  rejects issues that violate account-state or role constraints and records
+  successful issues on the customer's timeline.
+
+  Background:
+    Given the billing workspace is configured with the default tax profile
+
+  @smoke
+  Scenario: A billing-admin issues an invoice for a customer in good standing
+    Given a signed-in billing-admin
+    And a customer with a zero account balance
+    When the billing-admin issues an invoice for that customer for 500 USD
+    Then the invoice appears in the issued invoices list
+    And the customer's timeline shows the invoice was issued
+
+  @risk-high
+  Scenario: Issuing is rejected when the customer has a negative balance
+    Given a signed-in billing-admin
+    And a customer with a negative account balance
+    When the billing-admin issues an invoice for that customer
+    Then the issue is rejected
+    And the rejection message names the outstanding amount
+
+  Scenario Outline: <user-role> access to invoice issuing
+    Given a signed-in <user-role>
+    And a customer with a zero account balance
+    When they attempt to issue an invoice for that customer
+    Then the attempt is <issue-outcome>
+
+    Examples:
+      | user-role      | issue-outcome |
+      | account-owner  | accepted      |
+      | billing-admin  | accepted      |
+      | viewer         | denied        |
+
+    @risk-high
+    Examples:
+      | user-role      | issue-outcome |
+      | external-audit | denied        |

package/.agents/skills/stack/qa/lighthouse-baseline/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: lighthouse-baseline
+description:
+  Codifies the capture-and-check baseline pattern for long-running quality
+  signals (Lighthouse scores, bundle size, p95 latency, runtime memory). Use
+  when wiring a new metric that needs a baseline file, paired :capture /
+  :check npm scripts, a tolerance-bounded gate, and a weekly refresh
+  cadence — the goal is a hard CI signal that ratchets only with intent.
+---
+
+# Skill: Lighthouse-Style Quality Baseline
+
+## Policy Capsule
+
+- Use this pattern only for numeric, run-to-run-comparable signals with directional intent (higher-is-better or lower-is-better) and meaningful noise variance.
+- Commit one canonical `baselines/<name>.json` per signal — never combine multiple metrics into a single baseline file.
+- Provide paired `<name>:capture` and `<name>:check` npm scripts; `:capture` writes the baseline, `:check` compares with tolerance and exits non-zero on regression.
+- Implement a `--self-test` mode that runs the comparator against known-good and known-regression fixtures so CI verifies the gate itself.
+- Pick tolerance from observed run-to-run spread (~2σ); tolerance of 0 flaps and trains reviewers to rubber-stamp refreshes.
+- Refresh baselines through deliberate, human-reviewed commits with the `baseline-refresh:` subject prefix; never auto-refresh on every CI run.
+- Run a weekly scheduled `:capture` workflow that opens a PR only when drift exceeds tolerance.
+- Keep baselines under source control — never store them in `temp/` or `coverage/` or anything covered by `.gitignore`.
+
+Pattern for promoting an episodic measurement into a long-running quality
+signal. The audit-lighthouse / audit-performance / audit-bundle-size
+workflows produce a snapshot. This skill is for the next step: turning that
+snapshot into a baseline a CI gate can ratchet against.
+
+## When to reach for this
+
+Reach for this pattern when **all** of these hold:
+
+- The signal is **numeric and comparable** across runs (a score, a duration,
+  a byte count). Boolean pass/fail signals belong in a normal lint, not a
+  baseline.
+- The signal has **noise floor variance** between runs, so equality checks
+  would flap. You need a tolerance band.
+- The signal has **directional intent** — bigger is worse (bundle KB, p95
+  ms) or bigger is better (Lighthouse score). The gate enforces direction;
+  a refresh moves the line on purpose.
+- Refreshing the baseline should be a **deliberate commit**, reviewed like
+  any other change. Auto-refreshing on every CI run defeats the gate.
+
+If the signal is binary or one-shot (e.g. "page returns 200", "alt-text
+present"), stay in the audit-* workflow space — don't spin up a baseline
+for it.
+
+## Anatomy
+
+The five pieces every baseline of this shape carries:
+
+1. **`baselines/<name>.json`** — canonical snapshot committed to the repo.
+   One file per signal. JSON, not YAML or TOML — diff tooling handles it
+   uniformly.
+2. **`<name>:capture` npm script** — runs the measurement, writes the new
+   snapshot to a temp path. Never overwrites the canonical baseline
+   directly. Operator-driven.
+3. **`<name>:check` npm script** — runs the measurement, compares against
+   `baselines/<name>.json` with a tolerance, exits non-zero on regression.
+   Wired into the close-validation gate chain (see `buildDefaultGates` in
+   `lib/close-validation.js`) and into the PR gate.
+4. **`--self-test` flag** — every check script accepts `--self-test`,
+   which runs the comparator against synthetic inputs (a known-good and a
+   known-regression fixture) and asserts the gate's verdict matches. CI
+   runs this on every PR so a comparator bug can't silently mask a real
+   regression.
+5. **Weekly cadence workflow** — a scheduled CI job that runs `:capture`,
+   diffs against the committed baseline, opens a PR if drift is real
+   (above tolerance) or a comment if it is within band. Intent-driven
+   refresh: the PR is the place to argue the regression is justified.
+
+## Worked example: Lighthouse Performance score
+
+`baselines/lighthouse-performance.json`:
+
+```json
+{
+  "$schema": "../.agents/schemas/baseline-numeric.schema.json",
+  "metric": "lighthouse.categories.performance",
+  "value": 92,
+  "direction": "higher-is-better",
+  "tolerance": 2,
+  "capturedAt": "2026-05-06T00:00:00Z",
+  "capturedFrom": {
+    "url": "https://preview.example.com/",
+    "lighthouseVersion": "12.2.1",
+    "formFactor": "desktop"
+  }
+}
+```
+
+Two npm scripts in `package.json`:
+
+```jsonc
+{
+  "scripts": {
+    "lighthouse:capture": "node scripts/lighthouse-baseline.js --capture",
+    "lighthouse:check":   "node scripts/lighthouse-baseline.js --check"
+  }
+}
+```
+
+The script implements three modes:
+
+- `--capture` — Run Lighthouse, write `baselines/lighthouse-performance.json`.
+- `--check` — Run Lighthouse, compare to the committed baseline. Exit 0 if
+  the value is within `(baseline ± tolerance)` or improving. Exit 1 if the
+  value falls below `(baseline − tolerance)` for higher-is-better metrics,
+  or above `(baseline + tolerance)` for lower-is-better metrics.
+- `--self-test` — Skip the real measurement. Run the comparator against
+  fixtures (e.g. known-good=92, known-regression=87). Assert that the gate
+  verdicts match the expected pass/fail. Exit 0 on success.
+
+## Gate hint shape
+
+When the `:check` script fails, the error message must point at the exact
+remediation path. A working hint:
+
+```text
+Lighthouse performance score 87 is below baseline 92 (tolerance ±2).
+Either: (a) fix the regression, or (b) if the drop is justified, run
+`npm run lighthouse:capture` and commit the refreshed baseline with a
+`baseline-refresh:` tagged subject (non-empty body explaining why).
+```
+
+The `baseline-refresh:` subject prefix mirrors the existing CRAP / MI
+convention so the same commit-tag tooling already validating those
+baselines extends to this one.
+
+## Weekly cadence
+
+`.github/workflows/lighthouse-weekly.yml` (or the equivalent for your CI):
+
+```yaml
+on:
+  schedule:
+    - cron: "0 14 * * 1"   # Mondays 14:00 UTC
+  workflow_dispatch: {}
+
+jobs:
+  refresh:
+    steps:
+      - run: npm run lighthouse:capture
+      - run: |
+          if git diff --quiet baselines/lighthouse-performance.json; then
+            echo "No drift; baseline still valid."
+            exit 0
+          fi
+          # Drift exists — open a PR with the refreshed baseline.
+          gh pr create --title "baseline-refresh: lighthouse perf" \
+            --body "Auto-captured weekly baseline. Review the diff and merge if intentional."
+```
+
+The cadence is weekly, not daily — a daily refresh creates so many PRs
+that reviewers stop reading them. The point is for a reviewer to read the
+diff and say "yes, this is the new floor" or "no, that regression
+shouldn't be in main."
+
+## Tolerance picking
+
+Tolerance encodes "what's noise". Pick it from the **observed run-to-run
+spread** on a known-good build, not a vibe:
+
+1. Capture the metric ten times against the same artifact.
+2. Take the standard deviation σ.
+3. Set tolerance ≈ 2σ. That gates real regressions without flapping on
+   warmup variance.
+
+If σ is bigger than the regressions you care about, the metric is too
+noisy for this pattern — invest in stabilising the measurement (warm-up
+runs, pinned hardware, controlled network) before adding the gate.
+
+## Anti-patterns
+
+- **Auto-refresh on every CI run.** Defeats the gate; every regression
+  becomes the new normal. Refreshes must be commits.
+- **Tolerance = 0.** Flaps on warmup noise, training reviewers to
+  rubber-stamp `baseline-refresh:` PRs without reading them. Then a real
+  regression sneaks through.
+- **No `--self-test`.** A bug in the comparator silently disables the
+  gate. The self-test is the gate's gate.
+- **Multiple metrics in one baseline file.** Couples unrelated drifts. A
+  bundle-size regression shouldn't block a Lighthouse refresh. One signal
+  per file.
+- **Baseline lives in `temp/` or `coverage/`.** The baseline is source of
+  truth — committed and reviewed. Anything under `temp/` or in `.gitignore`
+  is a snapshot, not a baseline.
+
+## Cross-references
+
+- Existing baseline-shape conventions in this framework:
+  `baselines/maintainability.json`, `baselines/crap.json`,
+  `baselines/lint.json`. Their `:update` / `:check` script pairs and the
+  `baseline-refresh:` commit-subject contract are the prior art this
+  skill generalises.
+- The audit-lighthouse workflow (`/audit-lighthouse`) produces the
+  one-shot Lighthouse snapshot that feeds the first `:capture`. Run it
+  once to confirm the script's measurement matches the workflow's, then
+  promote to a baseline.