@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/lgpd-compliance-audit/SKILL.md

@@ -0,0 +1,448 @@
+---
+name: lgpd-compliance-audit
+description: LGPD (Lei Geral de Proteção de Dados — Brazilian GDPR equivalent) compliance audit. PII identification, consent tracking, right-to-erasure verification, audit log requirements, and incident reporting templates. Use before exposing any user-data-handling project to production.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [lgpd, anpd, right-to-erasure, data-subject-request, cookie-consent, pii]
+  tool_reminders:
+    [
+      LGPD applies to ANY system processing PII of Brazilian residents — even if your company is foreign-based,
+      This skill is operational guidance not legal advice — for regulated sectors (financial,
+      health) consult an LGPD lawyer before going to production,
+      Cookie consent must be revocable AND the revocation must propagate to backend (not just localStorage),
+      Right-to-erasure (Art. 18 V) requires actually deleting data — not soft-deleting. Soft-delete only works if user explicitly consents to retention for legal/contractual purposes,
+      ANPD breach notification window is 'reasonable time' (interpreted by precedent ~72h) — start the incident clock the moment you discover the leak,
+    ]
+---
+
+# LGPD Compliance Audit Skill
+
+**Mission:** Before any Merlin project that processes personal data of
+Brazilian residents goes to production (or after a regulator inquiry), run
+this audit checklist to identify gaps in LGPD compliance, document the
+remediations needed, and produce evidence of due diligence.
+
+**Important disclaimer:** This skill is operational guidance based on public
+research, the LGPD text (Lei nº 13.709/2018), and ANPD guidance. It is NOT
+legal advice. For regulated sectors (financial, health, children's data) or
+high-stakes deployments, consult a Brazilian LGPD lawyer before relying on
+this audit.
+
+---
+
+## When this skill activates
+
+- A project that captures user data is approaching production launch
+- After a data breach or suspected PII exposure
+- During quarterly compliance reviews
+- Before signing a contract with a Brazilian client that requires LGPD attestation
+- When a user mentions LGPD, GDPR, "dados pessoais", or "ANPD"
+- During `engineering-audit` of a project handling PII
+
+---
+
+## What LGPD requires (the 10 minimum bars)
+
+Per the LGPD (Lei nº 13.709/2018) and ANPD guidance, every system processing
+PII of Brazilian residents must:
+
+1. **Lawful basis** for each PII processing activity (Art. 7 — 10 hypotheses incl. consent, legitimate interest, contract, legal obligation)
+2. **Transparency** — clear privacy policy explaining what data is collected, why, and with whom shared (Art. 9)
+3. **Purpose limitation** — data used only for the declared purposes (Art. 6 I)
+4. **Data minimization** — collect only what's necessary (Art. 6 III)
+5. **Consent records** — when consent is the lawful basis, persist proof (timestamp, version, IP, user agent) (Art. 8 §1)
+6. **Right of access** — user can request all data held about them (Art. 18 II)
+7. **Right of correction** — user can fix incorrect data (Art. 18 III)
+8. **Right of deletion** — user can request erasure when there's no other lawful basis to retain (Art. 18 VI)
+9. **Right of portability** — user can export their data in interoperable format (Art. 18 V)
+10. **Breach notification** — to ANPD AND affected users, in "reasonable time" (Art. 48)
+
+The audit verifies each of these 10 bars in code + UI + documentation.
+
+---
+
+## Audit protocol — 6 phases
+
+### Phase 1 — Data inventory (find the PII)
+
+For every database table, every API endpoint, and every form, identify:
+
+| Field type      | LGPD classification                                          | Examples                                                                                                        |
+| --------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| Common PII      | Article 5 I — "personal data"                                | Name, email, phone, address, IP address, cookies                                                                |
+| Sensitive PII   | Article 5 II — "sensitive personal data" — extra protections | CPF (national ID), RG, race, religion, health, sexual orientation, biometric, political views, union membership |
+| Children's data | Article 14 — strictest protections                           | Any PII of users under 18                                                                                       |
+| Anonymized      | Article 5 XI — usually out of scope                          | Hashed/aggregated data with no re-identification path                                                           |
+| Pseudonymized   | Article 5 V — reduced but not zero scope                     | Tokenized or encrypted at rest with key separation                                                              |
+
+**Audit query templates (Postgres):**
+
+```sql
+-- 1. Find all columns that look like PII
+SELECT
+  table_schema, table_name, column_name, data_type
+FROM information_schema.columns
+WHERE table_schema = 'public'
+  AND (
+    column_name ~ '(email|phone|telefone|cpf|cnpj|rg|name|nome|address|endereco|ip|user_agent|birthday|nascimento|gender|race|religion|health|saude)'
+    OR column_name LIKE '%_email' OR column_name LIKE '%_phone'
+  )
+ORDER BY table_name, column_name;
+
+-- 2. Find tables that store PII without timestamp tracking
+-- (Required for retention policy enforcement)
+SELECT table_name FROM information_schema.tables t
+WHERE table_schema = 'public'
+  AND NOT EXISTS (
+    SELECT 1 FROM information_schema.columns c
+    WHERE c.table_schema = t.table_schema
+      AND c.table_name = t.table_name
+      AND c.column_name IN ('created_at', 'updated_at')
+  );
+
+-- 3. Find sensitive PII (CPF, etc.) and verify it's encrypted or properly authorized
+SELECT table_name, column_name FROM information_schema.columns
+WHERE table_schema = 'public'
+  AND column_name IN ('cpf', 'rg', 'cnh', 'passport', 'health_data');
+-- For each result, verify: is data encrypted at rest? Is access RBAC-controlled?
+```
+
+**Output:** PII inventory document at `.merlin-core/thoughts/shared/research/<date>-pii-inventory.md`
+
+### Phase 2 — Lawful basis mapping
+
+For each PII column identified, document the lawful basis:
+
+| Column              | Table             | Lawful basis                    | Justification                                             |
+| ------------------- | ----------------- | ------------------------------- | --------------------------------------------------------- |
+| `email`             | `users`           | Contract execution (Art. 7 V)   | Required to deliver the service the user signed up for    |
+| `phone`             | `orders`          | Contract execution (Art. 7 V)   | Needed for delivery coordination                          |
+| `cpf`               | `invoices`        | Legal obligation (Art. 7 II)    | Required for nota fiscal emission per Brazilian tax law   |
+| `analytics_id`      | `events`          | Legitimate interest (Art. 7 IX) | Service improvement; balanced against minimal user impact |
+| `marketing_consent` | `consent_records` | Consent (Art. 7 I)              | Explicit opt-in for marketing emails                      |
+
+**Red flags during this phase:**
+
+- ❌ "We collect this just in case" → no lawful basis → DELETE the field
+- ❌ "We collect this for marketing" but no consent record → ADD consent flow OR delete
+- ❌ Sensitive PII (CPF, health) collected via "implicit consent" → REQUIRES explicit consent
+- ❌ Children's data collected without parental consent verification → BLOCK launch
+
+### Phase 3 — Consent mechanism verification
+
+#### 3.1 Cookie consent banner
+
+Required if site uses ANY non-essential cookie (analytics, marketing,
+remarketing, A/B testing).
+
+**Audit checklist:**
+
+- [ ] Banner appears on first visit (no prior consent)
+- [ ] Banner BLOCKS non-essential cookies until user choice (essential cookies OK)
+- [ ] Banner offers granular control (analytics yes/no, marketing yes/no)
+- [ ] Banner offers "Reject all" with equal prominence to "Accept all"
+- [ ] Choice is persisted (localStorage at minimum)
+- [ ] **Choice is sent to backend** + recorded in `consent_records` table with: user_id (or session_id), consent_type, version, granted/revoked, ip_address, user_agent, granted_at, revoked_at
+- [ ] User can REVOKE consent later (settings page or footer link)
+- [ ] Revocation propagates to backend AND clears related cookies AND stops further processing
+
+**Common gap:** A ConsentBanner component exists in the UI but the
+`consent_records` table is EMPTY (0 entries) — frontend doesn't call the
+backend. This is a real LGPD gap.
+
+#### 3.2 Form-level consent
+
+For any form that collects PII for purposes beyond contract execution
+(marketing, analytics, third-party sharing):
+
+- [ ] Checkbox is UNCHECKED by default
+- [ ] Checkbox text is specific (not "I agree to terms" — must specify the actual purpose)
+- [ ] Multiple purposes get multiple checkboxes (don't bundle)
+- [ ] Submission stores the consent record with timestamp + version
+- [ ] User receives confirmation of what they consented to (email or thank-you page)
+
+#### 3.3 Consent versioning
+
+When privacy policy or terms change materially, existing consent records
+become invalid for the new processing. The system must:
+
+- [ ] Tag each consent record with `version` of the policy at consent time
+- [ ] Detect when a user's consent is on an outdated version
+- [ ] Re-prompt the user before proceeding with processing under new terms
+
+### Phase 4 — Data subject rights (DSR) endpoints
+
+Verify implementation of the 7 user rights:
+
+| Right                            | LGPD article | Endpoint pattern                             | Example status                                      |
+| -------------------------------- | ------------ | -------------------------------------------- | --------------------------------------------------- |
+| Confirmation of processing       | Art. 18 I    | `GET /me/data-status`                        | ❌ Missing                                          |
+| Access (data export)             | Art. 18 II   | `GET /me/data-export` (ZIP/JSON download)    | ❌ Missing                                          |
+| Correction                       | Art. 18 III  | `PATCH /me/profile`                          | ⚠️ Profile fields editable, not all PII             |
+| Anonymization/blocking           | Art. 18 IV   | `POST /me/data-anonymize`                    | ❌ Missing                                          |
+| Portability                      | Art. 18 V    | `GET /me/data-export` (interoperable format) | ❌ Missing                                          |
+| Deletion (right to be forgotten) | Art. 18 VI   | `DELETE /me/account`                         | ❌ Missing — only addresses can be deleted          |
+| Information about sharing        | Art. 18 VII  | Privacy policy section                       | ⚠️ Privacy policy exists; sharing list not explicit |
+
+**Audit code pattern:**
+
+```bash
+# Search for endpoints related to user data rights
+grep -rE "(data-export|data-erasure|account.delete|me/profile|right-to-erasure|gdpr|lgpd)" \
+  --include="*.ts" --include="*.js" --include="*.py" .
+
+# Verify deletion is HARD delete (not soft) for LGPD compliance
+grep -rE "(soft.delete|deleted_at|is_deleted)" --include="*.ts" --include="*.sql" .
+# Soft delete is only LGPD-compliant if user CONSENTS to retention for legal purposes
+```
+
+**Critical:** Deletion must be CASCADE — user_id deletion propagates to all
+tables that reference it (orders, audit_logs, consent_records, etc.). Verify
+foreign key constraints have `ON DELETE CASCADE` or explicit cleanup logic.
+
+### Phase 5 — Audit logging compliance
+
+LGPD doesn't explicitly require audit logs but practical compliance demands
+them. ANPD investigations expect to see:
+
+- WHO accessed PII (admin, employee, system process)
+- WHEN they accessed it (ISO 8601 timestamp)
+- WHAT they accessed (entity_type + entity_id)
+- WHY they accessed it (action type or business justification)
+- FROM WHERE (IP address)
+- WITH WHAT (user_agent)
+
+**Audit query:**
+
+```sql
+-- Coverage rate: % of PII-touching operations that produce an audit_logs entry
+SELECT
+  COUNT(*) FILTER (WHERE action LIKE '%_pii%') AS pii_actions_logged,
+  -- Compare against estimated PII operations (orders created, users updated, etc.)
+  (SELECT COUNT(*) FROM orders) + (SELECT COUNT(*) FROM users) AS estimated_pii_operations,
+  ROUND(100.0 * COUNT(*) FILTER (WHERE action LIKE '%_pii%') /
+    NULLIF((SELECT COUNT(*) FROM orders) + (SELECT COUNT(*) FROM users), 0), 1) AS coverage_pct
+FROM audit_logs;
+```
+
+**Common gap:** 1 audit log entry total (only `payment_webhook_reconciliation`).
+This is an obvious gap — see `audit-logging-middleware` skill (Tier 3 roadmap).
+
+### Phase 6 — Breach response readiness
+
+LGPD Art. 48 requires breach notification to ANPD AND affected users in
+"reasonable time" (precedent ~72 hours). The system must support:
+
+- [ ] Detection capability — log review, alerting on anomalies
+- [ ] Investigation capability — can we determine WHO was affected?
+- [ ] Notification capability — can we email all affected users within 72h?
+- [ ] Documentation — incident response runbook
+- [ ] Contact for ANPD — designated DPO (Data Protection Officer) per Art. 41
+
+**Verify:**
+
+```bash
+# Is there a documented DPO contact?
+grep -rE "(dpo|encarregado|data.protection.officer)" docs/ README.md
+
+# Is there a breach response runbook?
+test -f .merlin-core/thoughts/shared/runbooks/lgpd-breach-response.md
+```
+
+---
+
+## Concrete artifacts produced by this audit
+
+After running the 6 phases, generate these documents in
+`.merlin-core/thoughts/shared/compliance/`:
+
+1. **`pii-inventory.md`** — every PII column in every system, with type and lawful basis
+2. **`consent-mechanism-audit.md`** — cookie banner, form consents, versioning status
+3. **`dsr-endpoints-status.md`** — implementation status of each user right
+4. **`audit-log-coverage.md`** — current % coverage + gaps
+5. **`breach-readiness-checklist.md`** — what's in place + what's missing
+6. **`lgpd-gaps-priority-matrix.md`** — ranked remediation plan with timelines
+
+---
+
+## Example findings (anonymized)
+
+This walkthrough is drawn from a real e-commerce audit (anonymized here as
+"AcmeShop"). Initial LGPD posture:
+
+| Bar                     | Status      | Evidence                                                                                 |
+| ----------------------- | ----------- | ---------------------------------------------------------------------------------------- |
+| 1. Lawful basis         | ⚠️ Implicit | Privacy policy exists but doesn't enumerate basis per data type                          |
+| 2. Transparency         | ✅          | A PrivacyPolicy page exists — Lei 13.709/2018 referenced                                 |
+| 3. Purpose limitation   | ⚠️          | No documented purpose register                                                           |
+| 4. Data minimization    | ✅          | Cart only requires name/phone/email — no CPF (deliberate design decision)                |
+| 5. Consent records      | ❌          | Table exists (`consent_records`) — has 0 entries (frontend doesn't persist)              |
+| 6. Right of access      | ❌          | No `/me/data-export` endpoint                                                            |
+| 7. Right of correction  | ⚠️          | Profile fields editable; not all PII                                                     |
+| 8. Right of deletion    | ❌          | Only addresses can be deleted via `DELETE /auth/addresses/:id`; no full account deletion |
+| 9. Right of portability | ❌          | No export endpoint                                                                       |
+| 10. Breach notification | ❌          | No DPO documented; no runbook                                                            |
+
+**Priority remediation:**
+
+1. **Persist cookie consent to DB** (4h work — already have a ConsentBanner component + consent_records table; just need to wire `POST /consent/grant` in backend and call from frontend)
+2. **Implement `DELETE /me/account`** (8h — cascades through orders/cart/audit_logs)
+3. **Implement `GET /me/data-export`** (6h — JSON dump of all user-related rows)
+4. **Designate DPO + add to privacy policy** (1h — write contact email, add to `/privacidade` page)
+5. **Document breach response runbook** (2h — use `incident-response-runbook` skill template, Tier 3 roadmap)
+6. **Tighten DMARC to `p=quarantine`** then `p=reject`
+7. **Audit log middleware** (4h via `audit-logging-middleware` skill, Tier 3)
+
+---
+
+## Common gotchas
+
+### Gotcha #1 — "We anonymize, so LGPD doesn't apply"
+
+LGPD Art. 12: anonymization must be IRREVERSIBLE. If you can re-identify
+(via cross-reference with other tables, or with the original key in another
+system), it's pseudonymized — still in scope. True anonymization is rare in
+practice.
+
+### Gotcha #2 — Cookie consent in localStorage only
+
+ANPD has fined companies for "consent" that only lives client-side. The
+backend must have proof of consent (record with timestamp, IP, version).
+localStorage is for UX (don't show the banner again); the legal record is
+server-side.
+
+### Gotcha #3 — "Soft delete" of users
+
+Setting `deleted_at = NOW()` is NOT a LGPD-compliant deletion unless the
+user consents to retention for a specific legal/contractual purpose
+(e.g., tax records require 5-year retention). Default to HARD DELETE.
+
+### Gotcha #4 — Third-party processors (e.g., MercadoPago, Resend)
+
+You're responsible for ensuring your processors are LGPD-compliant. Have a
+DPA (Data Processing Agreement) with each. Most major providers have public
+DPAs — link them from your privacy policy.
+
+### Gotcha #5 — International data transfers
+
+If you send PII to servers outside Brazil (e.g., AWS us-east-1, OpenAI),
+LGPD Art. 33 requires safeguards (adequacy decision, Standard Contractual
+Clauses, or other mechanism). Document your data flow geography.
+
+### Gotcha #6 — Children's data
+
+Anyone under 18 needs parental consent (Art. 14). If your service doesn't
+gate by age, you may be processing children's data unknowingly. Verify with
+an age check OR explicit "this service is for 18+" prominently displayed.
+
+### Gotcha #7 — Right to erasure has limits
+
+LGPD Art. 16 allows retention even after deletion request for: legal
+obligation (tax, financial records), research (anonymized), legitimate
+interest (with documented balancing test), or contract execution. But the
+default must be DELETE; retention requires justification.
+
+---
+
+## Composable templates
+
+### Privacy policy section template
+
+```markdown
+## Seus direitos (Art. 18 LGPD)
+
+Você tem o direito de:
+
+1. **Acessar** seus dados — solicite via `me@<domain>` ou painel de conta
+2. **Corrigir** dados incorretos — edite no painel de conta ou solicite via email
+3. **Excluir** seus dados — clique em "Excluir minha conta" no painel ou solicite via email; processamos em até 15 dias úteis
+4. **Portar** seus dados — baixe em formato JSON via "Exportar meus dados" no painel
+5. **Revogar consentimento** — desmarque opções no painel "Privacidade"; processamento cessa imediatamente
+6. **Saber com quem compartilhamos** — veja seção "Compartilhamento" abaixo
+
+Contato do Encarregado (DPO): `dpo@<domain>` | Tel: <numero>
+
+Reclamações podem ser feitas à ANPD: gov.br/anpd
+```
+
+### `consent_records` schema template
+
+```sql
+CREATE TABLE consent_records (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,  -- nullable for anonymous consents (cookies)
+  session_id VARCHAR(64),  -- for pre-auth cookie consent
+  consent_type VARCHAR(50) NOT NULL,  -- 'cookies_essential' | 'cookies_analytics' | 'cookies_marketing' | 'newsletter' | 'data_processing' | ...
+  version VARCHAR(20) NOT NULL,  -- privacy policy / terms version at time of consent
+  granted BOOLEAN NOT NULL,  -- true = granted, false = revoked
+  granted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  revoked_at TIMESTAMPTZ,
+  ip_address INET,
+  user_agent TEXT,
+  metadata JSONB
+);
+
+CREATE INDEX idx_consent_user ON consent_records(user_id);
+CREATE INDEX idx_consent_session ON consent_records(session_id);
+CREATE INDEX idx_consent_type ON consent_records(consent_type);
+```
+
+### `POST /consent/grant` endpoint template
+
+```typescript
+// firebase/functions/src/modules/consent/consent.functions.ts
+export async function grantConsent(req: Request, res: Response) {
+  const { consent_type, version, granted } = req.body;
+
+  // Validate consent_type against allowlist
+  const validTypes = [
+    "cookies_essential",
+    "cookies_analytics",
+    "cookies_marketing",
+    "newsletter",
+    "data_processing",
+  ];
+  if (!validTypes.includes(consent_type))
+    return res.status(400).json({ error: "invalid consent_type" });
+
+  await db.query(
+    `
+    INSERT INTO consent_records (user_id, session_id, consent_type, version, granted, ip_address, user_agent)
+    VALUES ($1, $2, $3, $4, $5, $6, $7)
+  `,
+    [
+      req.user?.id ?? null,
+      req.headers["x-session-id"],
+      consent_type,
+      version,
+      granted,
+      req.ip,
+      req.headers["user-agent"],
+    ],
+  );
+
+  res.json({ ok: true });
+}
+```
+
+---
+
+## Related skills
+
+- **`engineering-audit`** — security axis includes LGPD checks (high-level)
+- **`database-provision`** — `consent_records` table schema reference
+- **`audit-logging-middleware`** (Tier 3 roadmap) — provides the audit_logs coverage required by Phase 5
+- **`incident-response-runbook`** (Tier 3 roadmap) — provides the breach response template required by Phase 6
+- **`secret-safe-commit`** — prevents PII leaks via committed credentials
+
+---
+
+## References
+
+- [Lei nº 13.709/2018 (LGPD) — full text](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm)
+- [ANPD — Autoridade Nacional de Proteção de Dados](https://www.gov.br/anpd/pt-br)
+- [Guia ANPD para tratamento de dados pessoais por agentes de tratamento de pequeno porte](https://www.gov.br/anpd/pt-br/documentos-e-publicacoes/guia-tratamento-pequeno-porte.pdf)
+- [Comparison LGPD vs GDPR](https://www.privacy.com.br/blog/lgpd-x-gdpr) — most patterns transfer

package/.merlin-core/skills/general/load-testing/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: load-testing
+description: Load-test HTTP APIs with Locust. Produces p50/p95/p99 latency, error rate, and regression-vs-baseline verdicts. Primary target v0.1 is the Gestao Merlin Dashboard API.
+license: Apache-2.0
+compatibility: Requires Python 3.9+ and locust>=2.43. Install with 'pip install -r .merlin-core/skills/general/load-testing/requirements.txt'.
+metadata:
+  author: merlin-framework
+  version: "0.1.0"
+  auto_activate: [load-test, locust, p95-latency, benchmark-api]
+  file_triggers:
+    [
+      "locustfile*.py",
+      ".merlin-core/skills/general/load-testing/**",
+      "tests/benchmarks/baseline.*.json",
+    ]
+  tool_reminders:
+    [
+      Locust is NOT stdlib — install via requirements.txt before running,
+      Dashboard API has no auth — do NOT add Bearer tokens to the Dashboard locustfile,
+      v0.1 targets Dashboard API GET endpoints only (POSTs have side effects and are deferred),
+      Always run headless in CI — use --headless with -u -r -t flags,
+    ]
+---
+
+# Load Testing with Locust
+
+Load-testing skill for verifying HTTP API performance under concurrent user load. Produces latency percentiles, error rates, and regression-vs-baseline verdicts for Quinn's quality pipeline.
+
+## Decision Tree: When to Run a Load Test
+
+```
+Does the PR touch dashboard/backend/src/routes/**?
+  YES → Run load test before Quinn's final verdict
+  NO → Does the PR add a new HTTP endpoint anywhere?
+    YES → Add a task for it in locustfile_dashboard.py, then run
+    NO → Skip load testing
+```
+
+Docs-only, frontend-only, and pure-refactor PRs that don't change API behavior can skip load tests.
+
+## Quickstart: Local Headless Run
+
+Requires Python 3.9+ and a virtualenv:
+
+```bash
+# Create venv (once)
+python -m venv .merlin-core/skills/general/load-testing/.venv
+
+# Activate (POSIX)
+source .merlin-core/skills/general/load-testing/.venv/bin/activate
+
+# Activate (Windows)
+.merlin-core/skills/general/load-testing/.venv/Scripts/activate
+
+# Install
+pip install -r .merlin-core/skills/general/load-testing/requirements.txt
+
+# Run (spawns the dashboard backend, runs Locust, writes reports)
+python .merlin-core/skills/general/load-testing/scripts/run_local.py \
+  --users 100 --spawn-rate 10 --runtime 3m
+```
+
+Outputs land in `.ai/load-tests/<ISO-timestamp>/`:
+
+- `run_stats.csv`, `run_failures.csv`, `run_stats_history.csv` — raw Locust CSVs
+- `report.html` — per-endpoint latency dashboard
+- Plus a symlink-or-copy `.ai/load-tests/LATEST.json` consumed by the Layer 2 PR gate
+
+## Quickstart: Docker Compose Run
+
+Reproducible run in three containers (dashboard + locust master + 1 worker):
+
+```bash
+docker compose -f .merlin-core/skills/general/load-testing/docker/docker-compose.locust.yml up --build
+```
+
+Locust UI becomes available at `http://localhost:8089` with host pre-filled to `http://app:3939`.
+
+## Scripting a New Target
+
+Copy `templates/locustfile_dashboard.py` as your starting point. Each task is a method decorated with `@task(weight)` — higher weights run more often. Always:
+
+1. Use the `name=` kwarg on `self.client.get(...)` to group requests by endpoint (not by path-with-IDs).
+2. Import `threshold_hook` at the top (it installs the `@events.quitting` listener that enforces p95/error-rate gates).
+3. Set `host` to the default target URL.
+
+## Thresholds & Baselines
+
+**Thresholds** (configured via env vars, enforced by `threshold_hook.py`):
+
+| Env var                 | Default | Meaning                                              |
+| ----------------------- | ------- | ---------------------------------------------------- |
+| `LOCUST_P95_MAX_MS`     | 1500    | Exit non-zero if total-suite p95 exceeds this        |
+| `LOCUST_ERROR_RATE_MAX` | 0.01    | Exit non-zero if total-suite error rate exceeds this |
+
+**Regressions** (enforced by `compare_baseline.py`):
+
+- Per-endpoint: `delta = (current_p95 - baseline_p95) / baseline_p95`
+- Ignored if `baseline_p95_ms < 50` (noise floor — too volatile on shared CI runners)
+- FAIL if any eligible endpoint has `delta > 0.20` (20%)
+
+See `tests/benchmarks/README.md` for baseline management.
+
+## Integration with Quinn (QA Agent)
+
+Quinn invokes this skill when a PR changes `dashboard/backend/src/routes/**` or adds a new API route. She emits one of three verdicts based on `.ai/load-tests/LATEST.json`:
+
+- **PASS** — all thresholds met AND `regression_ok === true`
+- **CONDITIONAL PASS** — thresholds met, regression delta 10–20% on any endpoint
+- **FAIL** — threshold breach OR regression > 20%
+
+## Integration with Layer 2 PR Gate
+
+`.merlin-core/core/quality-gates/layer2-pr-automation.js` reads `.ai/load-tests/LATEST.json` when present. If the file exists, a `load-test-regression` check is added to the PR gate. Absent file → no check added (backwards-compatible).

package/.merlin-core/skills/general/load-testing/docker/Dockerfile.dashboard

@@ -0,0 +1,21 @@
+FROM node:22-alpine
+WORKDIR /app
+
+# Copy workspace manifests first for layer caching
+COPY dashboard/package.json dashboard/package-lock.json ./dashboard/
+COPY dashboard/backend/package.json ./dashboard/backend/
+COPY dashboard/shared/package.json ./dashboard/shared/
+
+RUN cd dashboard && npm ci --omit=dev
+
+# Copy source
+COPY dashboard/backend ./dashboard/backend
+COPY dashboard/shared ./dashboard/shared
+
+WORKDIR /app/dashboard/backend
+RUN npm run build
+
+ENV PORT=3939
+ENV NODE_ENV=test
+EXPOSE 3939
+CMD ["node", "dist/index.js"]

package/.merlin-core/skills/general/load-testing/docker/docker-compose.locust.yml

@@ -0,0 +1,39 @@
+services:
+  app:
+    build:
+      context: ../../../../..
+      dockerfile: .merlin-core/skills/general/load-testing/docker/Dockerfile.dashboard
+    ports:
+      - "3939:3939"
+    environment:
+      - NODE_ENV=test
+      - PORT=3939
+
+  locust-master:
+    image: locustio/locust:2.43.4
+    ports:
+      - "8089:8089"
+    volumes:
+      - ../templates:/mnt/locust:ro
+      - ./results:/mnt/results
+    environment:
+      - PYTHONPATH=/mnt/locust
+    command: >
+      -f /mnt/locust/locustfile_dashboard.py
+      --master
+      --host http://app:3939
+    depends_on:
+      - app
+
+  locust-worker:
+    image: locustio/locust:2.43.4
+    volumes:
+      - ../templates:/mnt/locust:ro
+    environment:
+      - PYTHONPATH=/mnt/locust
+    command: >
+      -f /mnt/locust/locustfile_dashboard.py
+      --worker
+      --master-host locust-master
+    depends_on:
+      - locust-master

package/.merlin-core/skills/general/load-testing/requirements.txt

@@ -0,0 +1 @@
+locust>=2.43,<3.0