@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/test-unit/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: test-unit
+description: >
+  Write unit and integration tests for a named module or change. Use when
+  "write unit tests" or "add tests for this function". Coverage plan →
+  plan-test-coverage. Mutation score → test-mutation. Browser check →
+  test-playwright.
+license: MIT
+---
+
+# test-unit — Write tests that would notice a break
+
+**Degree of freedom: MIXED** — which cases to write `[HIGH freedom]`;
+detect-then-match existing harness `[LOW freedom — run exactly]`. This skill
+**writes tests**. Coverage theater / mutation score → `test-mutation`.
+
+Write effective, maintainable unit tests from the project's actual
+framework, production error data, and current best practices.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|:------|:-----|
+| **test-unit** (this) | **Write** the tests |
+| `test-mutation` | Survivors / assertion theater — hand off the score |
+| `plan-test-coverage` | What *should* be tested — plan only, no harness |
+| `test-playwright` | Live this-diff PDCA, not unit files |
+| `test-qa` | Story/CRUD QA in a headed browser |
+
+## How to reason (each test you add)
+
+1. **Observe** — target function, existing pattern, Sentry gap if any
+2. **Interpret** — behavior under test vs implementation detail
+3. **Classify** — write (public/edge/error) / skip (trivial/third-party/markup)
+4. **Severity** — prod-error gap and money/auth paths first
+
+## Worked example
+
+> **Observe:** Sentry `TypeError` in `parsePrice`; `parsePrice.test.ts` only
+> asserts the happy path; coverage 91%.
+> **Interpret:** suite executes the file but never the empty/malformed branch.
+> **Classify:** write the missing edge cases here — do not declare coverage done.
+> **Handoff:** if the new tests still wouldn't catch a `>`/`>=` flip → `test-mutation`.
+
+---
+
+## Step 0: Auto-Detect Test Environment  [LOW freedom — match the harness]
+
+### 0a. Detect Test Framework
+
+Read the dependency manifest (`package.json`, `requirements.txt`,
+`pyproject.toml`, `go.mod`, `Cargo.toml`, `build.gradle`, `Gemfile`):
+
+| Framework | Detection Signal |
+|-----------|-----------------|
+| **Vitest** | `vitest` in devDependencies, `vitest.config.ts` |
+| **Jest** | `jest` in devDependencies, `jest.config.*`, `"jest"` key |
+| **Testing Library** | `@testing-library/react`, `@testing-library/vue`, etc. |
+| **Playwright** | `@playwright/test`, `playwright.config.ts` |
+| **Cypress** | `cypress`, `cypress.config.*` |
+| **pytest** | `pytest` in requirements, `conftest.py` |
+| **Go test** | `_test.go`, `go test` in Makefile |
+| **RSpec** | `rspec` in Gemfile, `spec/` |
+| **JUnit** | `junit` in build.gradle, `src/test/` |
+
+### 0b. Discover Existing Test Patterns
+
+```
+Glob: **/*.test.{ts,tsx,js,jsx} → JS/TS test files
+Glob: **/*.spec.{ts,tsx,js,jsx} → JS/TS spec files
+Glob: **/test_*.py → Python
+Glob: **/*_test.go → Go
+Glob: **/spec/**/*_spec.rb → Ruby
+```
+
+Read 2–3 existing tests: imports/utilities, `describe`/`it` vs `test`,
+mock style (`vi.mock`, `jest.mock`, `unittest.mock`), setup/teardown,
+assertion library (`expect`, `assert`, `chai`).
+
+### 0c. Detect Test Configuration
+
+Glob `vitest.config.*`, `jest.config.*`, `pytest.ini`, `conftest.py`,
+`setup.cfg`, `.nycrc*`, `c8.config.*`. Extract coverage thresholds, test
+dirs, global setup, module aliases.
+
+### 0d. Check Coverage Status
+
+If c8 / istanbul/nyc / coverage.py is configured, grep `package.json`
+scripts for `coverage` / `c8` / `nyc` / `istanbul`.
+
+### 0e. Record Discovery
+
+```
+TEST ENVIRONMENT:
+- Framework: [Vitest/Jest/pytest/etc. + version]
+- Assertion style: [expect/assert/chai]
+- Component testing: [Testing Library/Enzyme/none]
+- Mock pattern: [vi.mock/jest.mock/unittest.mock]
+- Coverage tool: [c8/nyc/coverage.py/none]
+- Coverage threshold: [X% or not configured]
+- Test directory: [__tests__/tests/spec/co-located]
+- Existing tests: [count]
+- Config file: [path]
+```
+
+---
+
+## Step 1: Research Testing Best Practices  [HIGH freedom]
+
+Context7 for the detected framework + each major testing dep (`vitest`,
+`@testing-library/react`, `msw`):
+
+```json
+context7:resolve-library-id
+{ "libraryName": "<DETECTED_FRAMEWORK>", "query": "unit testing best practices" }
+```
+
+Then `context7:query-docs` for mocking, setup, teardown.
+
+Firecrawl — one current-year search, scrape the most authoritative result:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<FRAMEWORK> unit testing best practices [current year]",
+ "limit": 5, "sources": [{ "type": "web" }]
+}
+```
+
+Optional second query: `<framework> mocking API calls` or `React Testing
+Library component testing patterns [current year]`.
+
+---
+
+## Step 2: Analyze Coverage Gaps (Sentry Integration)  [HIGH freedom]
+
+```json
+sentry:search_issues
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "query": "unresolved errors from the last 30 days",
+ "projectSlugOrId": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "limit": 25
+}
+```
+
+For each issue: stack-trace file → `Glob: **/<filename>.test.*` → does a
+test cover the failing path? No file, or happy-path-only → prioritize it.
+
+```
+COVERAGE GAP ANALYSIS:
+- Production errors without tests: [count]
+ 1. [file] — [error type] — [frequency] — NO TEST FILE
+ 2. [file] — [error type] — [frequency] — test exists but missing edge case
+- Highest-impact files to test: [ordered list]
+```
+
+---
+
+## Step 3: Write Tests  [HIGH freedom]
+
+### Test Structure (AAA Pattern)
+
+```typescript
+describe('ComponentOrModule', () => {
+ describe('methodOrBehavior', () => {
+ it('should [expected behavior] when [condition]', () => {
+ // Arrange
+ const input = createTestData();
+ // Act
+ const result = functionUnderTest(input);
+ // Assert
+ expect(result).toEqual(expectedOutput);
+ });
+ });
+});
+```
+
+### Naming Conventions
+
+Co-locate or mirror the source tree:
+
+| Source File | Test File |
+|-------------|-----------|
+| `src/utils/formatDate.ts` | `src/utils/formatDate.test.ts` |
+| `src/components/Button.tsx` | `src/components/Button.test.tsx` |
+| `app/services/user.py` | `tests/services/test_user.py` |
+
+Descriptions: `should [behavior] when [condition]`.
+
+### What to Test
+
+**DO test:** public API / exported functions; business/domain rules; edge
+and boundary values; error/failure modes; user interactions; state
+transitions; data transformations.
+
+**DON'T test:** private methods / internal state; third-party internals;
+trivial getters/setters; framework behavior; CSS classes or DOM structure
+(behavior, not markup).
+
+### Edge Cases to Cover
+
+| Category | Test Values |
+|----------|------------|
+| Empty | `null`, `undefined`, `""`, `[]`, `{}` |
+| Boundary | `0`, `-1`, `Number.MAX_SAFE_INTEGER`, `Number.MIN_SAFE_INTEGER` |
+| Type confusion | String where number expected, array where object expected |
+| Unicode | Emoji, CJK, RTL, zero-width spaces |
+| Concurrency | Rapid successive calls, races |
+| Network | Timeout, 404, 500, empty body, malformed JSON |
+| Dates | Midnight, DST, leap years, timezone boundaries |
+
+---
+
+## Step 4: Match the repo's patterns  [HIGH freedom]
+
+Write mocks, component, hook, and route-handler tests in the shape the existing suite uses (Step 0b) and the framework docs describe (Step 1). Generic templates per category live in [references/details.md](references/details.md) for repos with no precedent.
+
+---
+
+## Step 5: Test Data Management  [HIGH freedom]
+
+### Use Factories
+
+```typescript
+const createUser = (overrides: Partial<User> = {}): User => ({
+ id: crypto.randomUUID(),
+ name: 'Test User',
+ email: 'test@example.com',
+ role: 'user',
+ createdAt: new Date('2024-01-01'),
+ ...overrides,
+});
+
+const admin = createUser({ role: 'admin' });
+const inactive = createUser({ status: 'inactive', name: 'Inactive User' });
+```
+
+### Use Meaningful Data
+
+```typescript
+// Bad — meaningless
+const data = { a: 'b', c: 'd' };
+// Good — realistic and descriptive
+const user = { name: 'Jane Doe', email: 'jane@example.com', role: 'admin' };
+```
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Wrote tests** — this skill does not stop at a plan
+2. **Behavior not markup** — no className / private internals
+3. **Matched harness** — same runner, naming, mock style as existing files
+4. **Isolated + deterministic** — factories, no shared mutable
+5. **Mutation theater not claimed** — score → `test-mutation`
+
+## Further reading
+
+- [Avoid Shared Mutable State and more](references/details.md)

package/skills/test-unit/references/details.md

@@ -0,0 +1,267 @@
+### Avoid Shared Mutable State
+
+```typescript
+// Bad — tests can interfere with each other
+const users = [createUser()];
+
+// Good — fresh data per test
+let users: User[];
+beforeEach(() => {
+  users = [createUser()];
+});
+```
+
+---
+
+## Step 6: Database-Aware Tests (Supabase Integration)
+
+If the project uses Supabase, verify test data matches the actual schema:
+
+```json
+supabase:execute_sql
+{
+  "query": "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = '<TABLE_BEING_TESTED>' ORDER BY ordinal_position"
+}
+```
+
+Use this to ensure:
+- Test factories produce data matching actual column types
+- Nullable fields are tested with both values and null
+- Enum values in tests match actual database enums
+- Foreign key relationships are correctly represented
+
+---
+
+## Output: Test Plan Report
+
+After analyzing the codebase and production errors, produce:
+
+```markdown
+## Test Plan — [Project Name]
+
+### Environment
+- Framework: [detected]
+- Coverage tool: [detected]
+- Current coverage: [if available]
+
+### Production Error Coverage Gaps
+| Error | Source File | Test Exists | Priority |
+|-------|-----------|-------------|----------|
+| [TypeError: Cannot read...] | [src/utils/parse.ts] | No | HIGH |
+| [NetworkError: timeout] | [src/api/client.ts] | Yes (missing edge case) | MEDIUM |
+
+### Recommended Tests (Priority Order)
+
+#### 1. [file path] — [why this file needs tests]
+- Test: [description of test case]
+- Test: [description of test case]
+
+#### 2. [file path] — [why]
+- Test: [description]
+
+### Research Findings Applied
+- [Pattern from research]: applied to [which tests]
+- [Best practice]: [how it informed the test strategy]
+```
+
+---
+
+## Quick Reference
+
+```bash
+# Run all tests
+npm test                    # or: pnpm test, yarn test
+python -m pytest            # Python
+go test ./...               # Go
+
+# Run specific file
+npx vitest src/utils/formatDate.test.ts
+npx jest --testPathPattern formatDate
+python -m pytest tests/test_format.py
+
+# Run with coverage
+npx vitest --coverage
+npx jest --coverage
+python -m pytest --cov=src
+
+# Watch mode
+npx vitest --watch
+npx jest --watch
+
+# Run matching pattern
+npx vitest -t "should format"
+npx jest -t "should format"
+python -m pytest -k "test_format"
+```
+
+---
+
+## Checklist
+
+- [ ] Test environment auto-detected (framework, config, patterns)
+- [ ] Research completed (Context7 docs, Firecrawl best practices)
+- [ ] Production errors checked (Sentry coverage gaps identified)
+- [ ] Tests follow AAA pattern (Arrange, Act, Assert)
+- [ ] Descriptive test names (`should [behavior] when [condition]`)
+- [ ] Edge cases covered (null, empty, boundary, error)
+- [ ] Mocks reset between tests (`beforeEach` cleanup)
+- [ ] No test interdependency (each test runs in isolation)
+- [ ] Tests are fast (mock external dependencies)
+- [ ] Tests are deterministic (no random, no time-dependent without fakes)
+- [ ] Test data uses factories (no hardcoded shared state)
+- [ ] Coverage gaps from Sentry addressed
+
+## Testing patterns by category
+
+Generic templates for repos with no precedent. Prefer the shape the existing suite already uses.
+
+### Pure Functions
+
+```typescript
+describe('formatCurrency', () => {
+  it('should format positive amounts', () => {
+    expect(formatCurrency(1234.5)).toBe('$1,234.50');
+  });
+  it('should handle zero', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+  it('should handle negative amounts', () => {
+    expect(formatCurrency(-100)).toBe('-$100.00');
+  });
+  it('should handle very large numbers', () => {
+    expect(formatCurrency(999999999.99)).toBe('$999,999,999.99');
+  });
+});
+```
+
+### Async Functions
+
+```typescript
+describe('fetchUser', () => {
+  it('should return user data for valid id', async () => {
+    const user = await fetchUser('123');
+    expect(user).toEqual({ id: '123', name: 'John Doe' });
+  });
+  it('should throw for non-existent user', async () => {
+    await expect(fetchUser('invalid')).rejects.toThrow('User not found');
+  });
+  it('should handle network timeout', async () => {
+    vi.useFakeTimers();
+    const promise = fetchUser('123');
+    vi.advanceTimersByTime(30000);
+    await expect(promise).rejects.toThrow('timeout');
+    vi.useRealTimers();
+  });
+});
+```
+
+### Mocking
+
+```typescript
+// Vitest
+import { vi } from 'vitest';
+vi.mock('./emailService', () => ({
+ sendEmail: vi.fn().mockResolvedValue({ success: true }),
+}));
+
+// Jest
+jest.mock('./emailService');
+
+// MSW (API mocking — preferred for HTTP)
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+const server = setupServer(
+ http.get('/api/users/:id', ({ params }) => {
+ return HttpResponse.json({ id: params.id, name: 'Test User' });
+ })
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+### React Components (Testing Library)
+
+```tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+describe('LoginForm', () => {
+ it('should submit with valid credentials', async () => {
+ const onSubmit = vi.fn();
+ const user = userEvent.setup();
+ render(<LoginForm onSubmit={onSubmit} />);
+ await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+ await user.type(screen.getByLabelText(/password/i), 'password123');
+ await user.click(screen.getByRole('button', { name: /sign in/i }));
+ await waitFor(() => {
+ expect(onSubmit).toHaveBeenCalledWith({
+ email: 'test@example.com', password: 'password123',
+ });
+ });
+ });
+
+ it('should show validation error for invalid email', async () => {
+ const user = userEvent.setup();
+ render(<LoginForm onSubmit={vi.fn()} />);
+ await user.type(screen.getByLabelText(/email/i), 'invalid');
+ await user.click(screen.getByRole('button', { name: /sign in/i }));
+ expect(screen.getByText(/valid email/i)).toBeInTheDocument();
+ });
+
+ it('should disable submit button while loading', () => {
+ render(<LoginForm onSubmit={vi.fn()} isLoading />);
+    expect(screen.getByRole('button', { name: /sign in/i })).toBeDisabled();
+  });
+});
+```
+
+### Custom Hooks
+
+```typescript
+import { renderHook, act } from '@testing-library/react';
+
+describe('useCounter', () => {
+  it('should start with initial value', () => {
+    const { result } = renderHook(() => useCounter(10));
+    expect(result.current.count).toBe(10);
+  });
+  it('should increment', () => {
+    const { result } = renderHook(() => useCounter(0));
+    act(() => result.current.increment());
+    expect(result.current.count).toBe(1);
+  });
+  it('should not go below zero', () => {
+    const { result } = renderHook(() => useCounter(0));
+    act(() => result.current.decrement());
+    expect(result.current.count).toBe(0);
+  });
+});
+```
+
+### API Route Handlers (Next.js / Node)
+
+```typescript
+describe('POST /api/users', () => {
+  it('should create user with valid data', async () => {
+    const req = new Request('http://localhost/api/users', {
+      method: 'POST',
+      body: JSON.stringify({ name: 'Test', email: 'test@example.com' }),
+    });
+    const response = await POST(req);
+    const data = await response.json();
+    expect(response.status).toBe(201);
+    expect(data).toMatchObject({ name: 'Test', email: 'test@example.com' });
+  });
+  it('should return 422 for invalid email', async () => {
+    const req = new Request('http://localhost/api/users', {
+      method: 'POST',
+      body: JSON.stringify({ name: 'Test', email: 'invalid' }),
+    });
+    const response = await POST(req);
+    expect(response.status).toBe(422);
+  });
+});
+```

package/skills/test-visual-regression/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: test-visual-regression
+description: >
+  Set up Playwright screenshot baselines and CI diffing so UI changes fail
+  pixel by pixel instead of by eye. Use when "add visual regression tests" or
+  "catch UI regressions". Functional clicks → test-playwright.
+license: MIT
+---
+
+# test-visual-regression — Screenshot baselines that stay green
+
+**Degree of freedom: MIXED** — what to baseline `[HIGH freedom]`;
+determinism loop and 3× clean runs `[LOW freedom — run exactly]`.
+playwright-cli / project runner — never Playwright MCP.
+
+Establish a screenshot baseline for important UI states and wire diffing so
+unintended visual change fails CI.
+
+**Functional tests prove the button works; visual tests prove it didn't move,
+shrink, lose styling, or overlap the next element.**
+
+Use **playwright-cli** (`npx --yes @playwright/cli@latest`) and the project's
+Playwright test runner — never Playwright MCP. Read
+`protocol-browser-anti-stall` before any headed session.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **test-visual-regression** (this) | Pixel baselines + CI diff artifacts |
+| `test-playwright` | Drive the app like a user; fix functional pain |
+| `audit-responsive` | Find linearized layout; this *locks* the fix |
+| `audit-ui-states` | Design empty/error states; this *locks* them |
+| `audit-uiux-design-system` | Token/component compliance (not screenshot CI) |
+| `test-qa` | Exploratory CRUD QA |
+
+## How to reason
+
+1. **Observe** — which surface, viewport, and state; what is volatile
+2. **Interpret** — will this pixel-lock a bug, or fail every run on a timestamp?
+3. **Classify** — baseline / exclude / mask
+4. **Severity** — unmasked volatile content = harness will be abandoned
+
+## Worked example
+
+> **Observe:** dashboard spec screenshots the whole page; a relative
+> "Updated 3s ago" label sits in the header.
+> **Interpret:** every CI run diffs that label.
+> **Classify:** must mask (or freeze time) — not a product regression.
+> **Fix:** `mask` the timestamp; prove ≥3 consecutive local runs with zero diff.
+
+---
+
+## Phase 0 — Detect the setup  [HIGH freedom]
+
+- Test runner: Playwright test / Vitest / Storybook + Chromatic/Loki
+- Existing snapshot config
+- Route list or story catalog
+- CI provider (usually GitHub Actions)
+
+Prefer the repo's existing Playwright. Do not add a second visual vendor if
+Playwright screenshots already work.
+
+---
+
+## Phase 1 — Choose what to baseline (not everything)  [HIGH freedom]
+
+- **Key screens** at 375 / 768 / 1440 (`audit-responsive` breakpoints)
+- **State matrix** from `audit-ui-states`: empty, error, loaded
+- **DS primitives:** button/input/card variants
+- **Both color schemes** if dark mode exists
+
+Exclude volatile content (timestamps, live feeds, mid-animation). Mask or
+freeze it — otherwise every run is a false positive.
+
+---
+
+## Phase 2 — Determinism (or the suite gets abandoned)  [LOW freedom — 3× clean]
+
+- Seeded fixtures, never live/random content
+- Freeze time; `prefers-reduced-motion`; disable transitions
+- Wait for fonts + images + network idle
+- Mask dates/avatars via the tool's mask API
+- Pin viewport, device-scale-factor, browser version
+- Same environment locally and in CI (container) so host fonts don't diff
+
+Prove stability: **≥3 consecutive local runs with zero diff** before calling
+the harness done.
+
+---
+
+## Phase 3 — Wire the loop  [HIGH freedom]
+
+- Commit baselines after a human reviews them (a broken screen locks the bug)
+- CI required check; upload expected / actual / diff artifacts
+- Intentional UI changes update snapshots in the same PR (`--update-snapshots`)
+- Small anti-aliasing threshold only — never wide enough to hide real shifts
+
+Save ad-hoc captures under `.playwright-mcp/`, not the repo root.
+
+---
+
+## Definition of Done
+
+- [ ] Tooling + snapshot config in place
+- [ ] Baseline scoped to key screens × breakpoints + critical states + DS primitives
+- [ ] Volatile regions masked; 3× local runs clean
+- [ ] Baselines human-reviewed
+- [ ] CI check + triptych artifacts
+- [ ] Update path documented
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **3× clean locally** — fewer is not "done"
+2. **Human reviewed baselines** — a broken screen must not be locked
+3. **Threshold tight** — anti-alias only; never hide real shifts
+4. **Right owner** — functional clicks stay on `test-playwright`
+5. **Artifacts** under `.playwright-mcp/` for ad-hoc; baselines in the harness dir
+
+## Output format
+
+1. **Baseline plan** — captured / excluded / why
+2. **Determinism checklist** — flakiness source → neutralization
+3. **CI wiring** — check, artifacts, update path
+4. Implement the harness; present artifact location
+
+## Related
+
+- `audit-responsive` / `audit-ui-states` — what to lock
+- `test-playwright` / `test-qa` — functional, not pixel
+- `protocol-browser-anti-stall` — headed sessions
+- `audit-cicd` — CI minutes / artifact retention

package/skills/thirdparty-emil-design-eng/ATTRIBUTION.md

@@ -0,0 +1,20 @@
+# Attribution — thirdparty-emil-design-eng
+
+| Field | Value |
+|-------|-------|
+| **Upstream** | [emilkowalski/skills](https://github.com/emilkowalski/skills) |
+| **Upstream path** | `skills/emil-design-eng/SKILL.md` |
+| **Author** | Emil Kowalski |
+| **License** | [MIT](https://github.com/emilkowalski/skills/blob/main/LICENSE) — Copyright (c) 2026 Emil Kowalski |
+| **Local name** | `thirdparty-emil-design-eng` |
+| **Curated in** | [kenji](https://github.com/kensaurus/skills) |
+
+## Update policy
+
+1. Pull the latest `SKILL.md` from upstream.
+2. Replace `references/emil-design-eng.md` with the upstream body beginning
+   at `## Initial Response`; keep the thin local `SKILL.md` loader.
+3. Adjust only the final local attribution link to `../ATTRIBUTION.md`.
+4. Run the repository validation and install smoke test.
+
+Do **not** add Kenji-specific "Check Existing First" sections to upstream content — keep this skill faithful to the source.

package/skills/thirdparty-emil-design-eng/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: thirdparty-emil-design-eng
+description: >
+  Third-party skill — Emil Kowalski's design-engineering notes (animation
+  craft, Sonner-style components). Use when the user names emil-design-eng or
+  asks for that philosophy. Motion pass → enhance-motion.
+---
+
+# Design Engineering
+
+> **Third-party skill** (upstream-maintained). See [ATTRIBUTION.md](ATTRIBUTION.md).
+> Upstream: [emilkowalski/skills](https://github.com/emilkowalski/skills) · Local name: `thirdparty-emil-design-eng`
+
+Before responding, read
+[`references/emil-design-eng.md`](references/emil-design-eng.md) **in full**
+and follow it as the authoritative playbook. It contains the required initial
+response, review format, animation guidance, accessibility rules, and checklist.
+
+The upstream body is kept in that single canonical reference file so future
+syncs remain diff-able without loading 600+ lines into the routing surface.
+Only local attribution links are adjusted for the reference location.