mandrel 1.93.0 → 2.0.0

package/.agents/skills/stack/backend/stripe-integration/SKILL.md

@@ -1,57 +0,0 @@
----
-name: stripe-integration
-description:
-  Implements secure Stripe payments and subscription billing. Use when handling
-  card data (PCI compliance via Elements/Checkout), verifying webhook
-  signatures, attaching `idempotencyKey` to mutations, or treating the
-  server-side webhook as the source of truth for entitlement changes.
-vendor: stripe
----
-
-# Skill: Stripe Payments & Billing
-
-## Policy Capsule
-
-- Never let raw card data touch your servers; collect payment details through Stripe Elements or Checkout.
-- Treat the server-side webhook as the source of truth for entitlement changes; never trust client-side success redirects.
-- Verify the `Stripe-Signature` header against the raw request body using the configured webhook secret before parsing any payload.
-- Attach an `idempotencyKey` to every Stripe API mutation to prevent duplicate charges on retry.
-- Use the official `stripe` Node SDK for backend calls; do not hand-roll HTTP requests.
-- Store Stripe object IDs (Customer, Price, Subscription) in your database — never store PCI-sensitive card data.
-- Log Stripe event IDs for traceability, but exclude sensitive customer data from logs.
-- Use Stripe's test environment and test cards for all development and QA.
-
-Standard procedures for secure and robust payment + subscription billing
-integration using Stripe.
-
-## 1. Core Principles
-
-- **PCI Compliance:** Never let sensitive card data touch your servers. Use
-  Stripe Elements or Checkout.
-- **Webhooks are Mandatory:** Never rely on successful client-side redirects to
-  confirm payments. Always verify via webhooks. Webhook handlers MUST verify the
-  `Stripe-Signature` header using the raw request body and the configured
-  webhook secret before parsing any data.
-- **Idempotency:** Every Stripe API mutation MUST include an `idempotencyKey` to
-  prevent duplicate charges or state changes during network retries.
-- **Server is Source of Truth:** Never trust client-side success states for
-  granting access or upgrading tiers; always rely on the asynchronous
-  server-side webhook to update the database.
-
-## 2. Technical Standards
-
-- **Stripe SDK:** Use the official `stripe` Node.js library for backend
-  operations.
-- **Elements / Checkout:** Use Stripe Elements for custom-branded checkout or
-  Checkout for the fastest implementation.
-- **Error Handling:** Gracefully handle payment failures, card declines, and
-  expired sessions.
-
-## 3. Best Practices
-
-- **Test Mode:** Use Stripe's test environment and test card numbers for all
-  development and QA.
-- **Logging:** Log Stripe event IDs for troubleshooting, but exclude any
-  sensitive customer data.
-- **Sub-records:** Store Stripe IDs (Customer ID, Price ID, Subscription ID) in
-  your database, not PCI-sensitive data.

package/.agents/skills/stack/backend/stripe-integration/scripts/listen-stripe.sh

@@ -1,9 +0,0 @@
-#!/bin/bash
-# Description: Forwards Stripe webhooks to the local Cloudflare Worker environment.
-# Prerequisite: Ensure stripe-cli is installed and authenticated.
-
-echo "Starting Stripe webhook forwarding to local Hono API..."
-echo "Ensure your worker is running on port 8787"
-
-# Replace 8787 with the actual port your local Cloudflare worker uses
-stripe listen --forward-to localhost:8787/v1/webhooks/stripe

package/.agents/skills/stack/backend/turso-sqlite/SKILL.md

@@ -1,48 +0,0 @@
----
-name: turso-sqlite
-description:
-  Develops with Turso's distributed SQLite (libSQL) platform. Use when working
-  with the `@libsql/client` driver — leverage edge replicas for low-latency
-  reads, route writes to the primary, and use parameterized queries plus a
-  versioned migration tool (drizzle-kit, atlas) for schema changes.
-vendor: turso
----
-
-# Skill: Turso (SQLite)
-
-## Policy Capsule
-
-- Use the `@libsql/client` driver for all database operations; do not mix in other SQLite clients.
-- Always use parameterized queries (`?` or `:name`); never interpolate user input into SQL strings.
-- Route reads to the nearest edge replica and writes to the primary; do not write to a replica.
-- Manage schema changes through a versioned migration tool (`drizzle-kit`, `atlas`) checked into git; never hand-mutate production schema.
-- Reuse the libSQL client instance within a worker invocation to avoid repeated handshake overhead.
-- Audit slow queries with `EXPLAIN QUERY PLAN` and add indexes where the plan shows a full scan on a large table.
-
-Rules for developing with Turso's distributed SQLite database platform.
-
-## 1. Core Principles
-
-- **Edge Efficiency:** Leverage Turso's low-latency distribution for edge
-  applications.
-- **SQLite Simplicity:** Use standard SQL syntax. SQLite is powerful—don't
-  over-engineer with complex ORMs unless necessary.
-- **Replication:** Understand the primary/replica architecture for
-  geographically distributed workloads.
-
-## 2. Technical Standards
-
-- **Driver Usage:** Use the `@libsql/client` driver for all database operations.
-- **Parameterized Queries:** Never use string interpolation for queries. Always
-  use placeholders (`?` or `:name`) to prevent SQL injection.
-- **Migrations:** Use a structured migration tool (e.g., `drizzle-kit` or
-  `atlas`) to manage schema changes versioned in git.
-
-## 3. Best Practices
-
-- **Connection Management:** Reuse database client instances within a worker
-  invocation to minimize handshake overhead.
-- **Read-Local, Write-Primary:** Direct read operations to the nearest replica
-  and write operations to the primary instance.
-- **Profiling:** Use `EXPLAIN QUERY PLAN` to audit slow queries and ensure
-  proper indexing of large tables.

package/.agents/skills/stack/frontend/astro/SKILL.md

@@ -1,62 +0,0 @@
----
-name: astro
-description:
-  Builds ultra-fast content-driven websites with Astro. Use when defaulting to
-  SSG, opting into SSR only for dynamic data, picking the most restrictive
-  `client:*` hydration directive, leveraging Server Islands (`server:defer`),
-  Astro Actions for type-safe mutations, and the Content Layer with Zod-
-  validated collections.
-vendor: astro
----
-
-# Skill: Astro (Iron)
-
-## Policy Capsule
-
-- Default to SSG; opt into SSR only when a route requires per-request dynamic data.
-- Ship zero JS by default — `.astro` components must not bundle client JavaScript unless a `client:*` directive is set explicitly.
-- For personalized or dynamic islands, prefer `server:defer` (Server Islands) over shipping a fully hydrated client island.
-- Use the most restrictive hydration directive that meets the interaction: `client:load` only for immediate interactivity, `client:visible` for below-the-fold, `client:idle` for non-critical logic.
-- Handle data mutations and form submissions through Astro Actions, not ad-hoc fetch handlers, to preserve type safety.
-- Source content through the Content Layer API with Zod-validated collections in `src/content/config.ts`.
-- Use the built-in `<Image />` and `<Picture />` components for image optimization rather than raw `<img>` tags.
-- Inject SEO metadata (`title`, `meta`, `og:image`, `canonical`) from a shared layout component.
-
-Guidelines and best practices for building ultra-fast content-driven websites
-using Astro.
-
-## 1. Core Principles
-
-- **Static First:** Default to SSG (Static Site Generation). Use SSR only when
-  dynamic user data or real-time interaction is required.
-- **Island Architecture:** Use standard HTML for most of the page.
-- **Server Islands (Astro 5):** Use the `server:defer` directive for components
-  that depend on personalized or dynamic data.
-- **Astro Actions:** Use built-in Actions for all data mutations and form
-  submissions to ensure type-safety.
-- **Zero JS by Default:** Ensure components use `.astro` syntax and do not ship
-  any JavaScript to the client unless explicitly requested via `client:*`
-  directives.
-
-## 2. Technical Standards
-
-- **Component Structure:**
-  - Logic (JS/TS) in the component script (top `---` fence).
-  - Markup in the HTML template.
-  - Scoped CSS in the `<style>` block.
-- **Content Layer API:** Always use the new Content Layer for data sourcing.
-  Manage collections via `src/content/config.ts` with Zod schema validation for
-  all metadata.
-- **Hydration Directives:** Use the most restrictive directive possible:
-  - `client:load` for immediate interactivity.
-  - `client:visible` for elements below the fold.
-  - `client:idle` for non-critical logic.
-
-## 3. Best Practices
-
-- **Image Optimization:** Always use the `<Image />` or `<Picture />` components
-  for automatic format conversion and resizing.
-- **Metadata/SEO:** Use a layout component to inject standard SEO tags (`title`,
-  `meta`, `og:image`, `canonical`).
-- **View Transitions:** Use Astro's built-in view transitions for SPA-like
-  navigation without the performance overhead.

package/.agents/skills/stack/frontend/astro-react-island-strategist/SKILL.md

@@ -1,30 +0,0 @@
----
-name: astro-react-island-strategist
-description:
-  Maintains strict boundaries between Astro server components and React client
-  islands in hybrid Astro/React workspaces. Use when keeping `.astro` files
-  for static HTML/SEO and `.tsx` for interactive islands — embed React only
-  with explicit `client:*` directives and pass serializable props.
-vendor: astro
----
-
-# Astro & React Island Strategist
-
-## Policy Capsule
-
-- Use `.astro` files for static HTML generation, routing, and SEO; do not reach for React when Astro suffices.
-- Use React `.tsx` files only for genuinely interactive UI islands, not for static rendering.
-- Embed a React component in Astro only with an explicit `client:*` directive (`client:load`, `client:idle`, `client:visible`).
-- Pick the most restrictive `client:*` directive that satisfies the interaction — prefer `client:idle` or `client:visible` over `client:load` whenever possible.
-- Pass only serializable data as props across the Astro → React island boundary; never pass functions or class instances.
-
-**Description:** Maintains strict boundaries between Astro server components and
-React client islands.
-
-**Instruction:** For the `@repo/web` workspace:
-
-- Use `.astro` files strictly for static HTML generation, routing, and SEO.
-- Use React `.tsx` files ONLY for highly interactive UI components (islands).
-- When embedding a React component in an Astro file, you MUST explicitly use
-  client directives (e.g., `client:load` or `client:idle`).
-- Only pass serializable data as props from Astro to React.

package/.agents/skills/stack/frontend/expo-react-native-developer/SKILL.md

@@ -1,29 +0,0 @@
----
-name: expo-react-native-developer
-description:
-  Prevents DOM element usage in React Native (Expo) workspaces. Use when
-  writing components for Expo apps — `<View>`, `<Text>`, `<TouchableOpacity>`
-  instead of `<div>`/`<span>`/`<p>`, no `window`/`document`, and styling
-  through the project's established solution.
-vendor: expo
----
-
-# Expo React Native Developer
-
-## Policy Capsule
-
-- Never use HTML DOM elements (`<div>`, `<span>`, `<p>`, `<button>`, etc.) inside Expo or React Native components.
-- Use React Native primitives instead: `<View>`, `<Text>`, `<TouchableOpacity>`, `<Pressable>`, `<ScrollView>`.
-- Never reference browser globals (`window`, `document`, `localStorage`) in React Native code paths.
-- Route all styling through the project's established styling solution; do not introduce a parallel CSS pipeline.
-- Treat the `@repo/mobile` workspace as DOM-free — any DOM symbol that appears is a hallucination and must be replaced.
-
-**Description:** Prevents DOM element usage in React Native.
-
-**Instruction:** For the `@repo/mobile` workspace:
-
-- YOU MUST NOT use HTML DOM elements like `<div>`, `<span>`, or `<p>`.
-- Use strict React Native primitives: `<View>`, `<Text>`, `<TouchableOpacity>`,
-  etc.
-- Ensure all styling uses the established styling solution.
-- Never use `window` or `document` objects.

package/.agents/skills/stack/frontend/google-analytics-v4/SKILL.md

@@ -1,50 +0,0 @@
----
-name: google-analytics-v4
-description:
-  Implements privacy-compliant event tracking with Google Analytics 4. Use
-  when wiring analytics that must comply with GDPR/CCPA via Consent Mode V2 —
-  `snake_case` event names, no PII to GA servers, GTM-driven event firing,
-  and DebugView verification before deploy.
-vendor: google
----
-
-# Skill: Google Analytics 4 (GA4)
-
-## Policy Capsule
-
-- Implement Consent Mode V2 and respect GDPR/CCPA; never send PII to GA servers.
-- Track meaningful business actions (e.g. `start_checkout`, `share_article`) rather than relying solely on page views.
-- Use `snake_case` for every event name and parameter — GA4 enforces this convention.
-- Fire all events through Google Tag Manager rather than embedding measurement IDs directly in application code.
-- Define critical user attributes (e.g. `user_type`, `pricing_plan`) as custom dimensions on the GA4 property.
-- Verify every new event in GA4 DebugView before deploying to production.
-- Filter development and internal traffic out of the production GA4 property.
-- Keep IP anonymization enabled and configure cross-domain tracking when traffic spans multiple origins.
-
-Guidelines for privacy-compliant and data-driven event tracking using GA4.
-
-## 1. Core Principles
-
-- **Privacy Compliance:** Adhere to GDPR and CCPA. Implement Consent Mode V2 and
-  never send PII to GA servers.
-- **Event-Driven:** Focus on meaningful user actions (e.g., "start_checkout",
-  "share_article") rather than just page views.
-- **Data Accuracy:** Filter out development and internal traffic from production
-  property data.
-
-## 2. Technical Standards
-
-- **GTM Integration:** Use Google Tag Manager for event firing to decouple
-  marketing tags from core application code.
-- **Custom Dimensions:** Define critical data points (e.g., `user_type`,
-  `pricing_plan`) as custom dimensions in the GA4 property.
-- **Enhanced Measurement:** Leverage GA4's built-in tracking for scrolls,
-  outbound clicks, and site searches.
-
-## 3. Best Practices
-
-- **Naming Convention:** Use `snake_case` for event names and parameters.
-- **Debug View:** Use the GA4 DebugView in the browser to verify events fire
-  correctly before deploying.
-- **Anonymization:** Ensure IP anonymization is enabled (default in GA4) and
-  cross-domain tracking is configured if necessary.

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

@@ -1,58 +0,0 @@
----
-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

@@ -1,34 +0,0 @@
----
-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

@@ -1,51 +0,0 @@
----
-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/lighthouse-baseline/SKILL.md

@@ -1,199 +0,0 @@
----
-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/gates.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.