@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/plan-stub-checker/references/preservation-contract.md

@@ -0,0 +1,24 @@
+# Preservation Contract
+
+Applies to **every phase**. Read before auditing or proposing anything.
+
+## Never do in this pass
+
+- **Remove** features, routes, screens, handlers, or props. Dead-looking code → *proposal for approval*, never delete unilaterally. Handlers may be wired dynamically — run the false-positive pass first.
+- **Fabricate** data, content, endpoints, env keys, or schema. No invented table names, columns, API routes, or DSNs. Unknown → `[NEEDS REAL TARGET]`, leave code untouched.
+- **Guess** codebase facts. Ground every claim in a file you read; cite path + line. Can't verify → say so.
+- **Change I/O or business logic** silently unless a wiring change is explicitly proposed + approved.
+- **Break** public APIs, props, routes, or payload shapes without flagging as breaking + migration note.
+- **Implement wiring** in this pass. Proposals only.
+
+## Before any file change proposal
+
+State in one line **what currently works there that must keep working**.
+
+## Classification buckets
+
+| Classification | Meaning |
+|----------------|---------|
+| **Confirmed stub/dead** | Evidence in code — empty handler, mock data in prod path, missing fetch |
+| **Potentially unwired** | Likely stub but needs runtime or flag context |
+| **Review required** | Dynamic invocation, registry, feature-flag — uncertain; conservative default |

package/skills/plan-test-coverage/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: plan-test-coverage
+description: >
+  Plan-only, user-story-driven test coverage audit. Use when "test coverage
+  plan", "traceability matrix", "fake-green tests", or "what's not tested".
+  Mutation score → test-mutation.
+license: MIT
+effort: high
+---
+
+# Test Coverage Audit + Plan (User-Story-Driven)
+
+**Degree of freedom: MIXED** — story derivation and fake-green judgment are HIGH;
+coverage commands run exactly. Stay **plan-only**. No tests written in this pass.
+
+**Role:** Senior QA / test engineer.
+
+**Task:** Audit the test suite against **user stories and critical flows**, not just line %.
+Find untested, weakly tested, and fake-green tests. Build traceability matrix + burndown.
+**Audit & plan only — do not write tests in this pass.**
+
+## This skill vs neighbors
+
+| Skill | Does |
+|-------|------|
+| **plan-test-coverage** (this) | Story-driven coverage plan |
+| `test-unit` | Write unit/integration tests (execution) |
+| `test-qa` | Live QA crawl |
+| `test-playwright` | E2E verification after changes |
+| `workflow-spec-tdd` | Spec + TDD during feature build |
+| `plan-stub-checker` | Finds unwired UI — feed into critical-path tests here |
+
+**Loop position:** `plan-stub-checker` → wiring approval → **plan-test-coverage** → `plan-perf-audit` / `plan-security-audit` → `plan-docs-sync`
+
+## How to reason (every plan item)
+
+1. **Propose** — the given/when/then spec for a gap or a fake-green replacement
+2. **Risk** — critical flow ships untested, or a green suite that cannot fail
+3. **Keep-working** — stories that already have honest, asserting tests
+4. **Phase** — Critical+fake-green → Error-edge → Important → Minor (do not execute)
+
+## Worked example
+
+> **Propose:** add an e2e for "authed user exports data" covering the newly wired Settings control; replace `expect(true).toBe(true)` in `export.test.ts`.
+> **Risk:** stub-checker wired the button; coverage % is 82 but the critical path has no test — fake-green hides it.
+> **Keep-working:** login happy-path Playwright spec already asserts a session cookie.
+> **Phase:** Phase 1 — Critical uncovered + fake-green.
+> **Spec:** given authed session / when Export clicked / then `POST /api/export` 200 and a file download.
+
+---
+
+## ⛔ Preservation Contract
+
+Read `references/preservation-contract.md`. Acknowledge in output #1.
+
+---
+
+## References
+
+| File | Contents |
+|------|----------|
+| `references/methodology.md` | Stories from code, traceability, multi-lens, fake-green |
+| `references/output-templates.md` | Matrix, burndown, phased plan |
+
+---
+
+## Phase flow
+
+```
+0. Derive user stories from code (FIRST)
+1. Inventory existing tests + coverage baseline
+2. Traceability matrix (story ↔ test)
+3. Multi-lens coverage audit
+4. Fake-green / weak-test detection
+5. Burndown + phased coverage plan
+6. Guardrails (mutation CI, coverage ratchet)
+7. Research citations
+```
+
+Detail: `references/methodology.md`
+
+Delegate an inventory pass to a subagent only when it is sizeable, independent of the others, and its raw output (coverage reports, test listings) has no place in the plan; brief it with the exact commands and the columns to return. It writes no tests, like this pass. Long sweeps are expected — context compaction exists, so finish the inventory rather than wrapping up early.
+
+---
+
+## Phase 0 — Stories from code (before judging coverage)  [HIGH freedom]
+
+Reconstruct what the app **promises** from routes, handlers, flows — not invented stories.
+
+Each story: acceptance criteria + criticality + cited implementing code.
+
+---
+
+## Phase 1 — Test inventory  [LOW freedom — run exactly]
+
+Discover test files; map to stories. Run coverage tool if available:
+
+```
+npm test -- --coverage
+npx vitest run --coverage
+```
+
+Not run → `[NEEDS RUN]` with command to run.
+
+---
+
+## Phase 2 — Traceability matrix  [HIGH freedom]
+
+Core artifact. Every critical story with no test = top-priority gap.
+
+Template: `references/output-templates.md`
+
+---
+
+## Phase 3–4 — Depth + fake-green  [HIGH freedom]
+
+Judge branch/path/risk/integration/error paths — not just line %.
+
+Flag fake-green: over-mocks, `expect(true)`, implementation-detail tests.
+
+Recommend mutation testing on critical modules for blind spots.
+
+---
+
+## Burndown + plan  [HIGH freedom — plan only]
+
+Phases:
+
+1. Critical uncovered + fake-green (especially newly wired stubs from stub-checker)
+2. Error/edge + integration boundaries
+3. Important stories
+4. Minor branches
+
+Per gap: given/when/then spec + "what must keep working". **Plan only.**
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — stories cited from routes/handlers; coverage numbers from a real run or `[NEEDS RUN]`
+2. **plan-only** — no tests written, deleted, or skipped
+3. **severity/phase justified** — untested critical stories and fake-green outrank line-% gaps
+4. **right-owner** — mutation score / assertion theater → `test-mutation`; writing tests → `test-unit` / `test-playwright`; unwired UI → `plan-stub-checker`
+5. **no-false-safety** — coverage % is not depth; never invent stories or counts
+
+---
+
+## Required output (in order)
+
+1. Preservation-contract acknowledgment
+2. Derived user stories + AC + criticality (cited)
+3. Existing-test inventory + baseline or `[NEEDS RUN]`
+4. Traceability matrix
+5. Multi-lens coverage audit
+6. Fake-green / weak-test findings
+7. Burndown table
+8. Coverage + enhancement plan, phased
+9. Guardrails/tooling
+10. Research notes + citations
+11. Open questions / `[NEEDS PRODUCT INPUT]` / `[NEEDS RUN]`
+
+End the turn with a standalone recap in chat: the two or three highest-impact gaps (untested critical stories and fake-green first) and the first phase to approve. The plan is the deliverable — write it before the recap.
+
+---
+
+## Rules
+
+- Plan only — do not write tests until approved.
+- User stories first, from real code.
+- Coverage ≠ single %. Judge depth + mutation honesty.
+- Never fabricate stories, tests, or numbers.
+- Separate true gap vs test-quality issue.

package/skills/plan-test-coverage/references/methodology.md

@@ -0,0 +1,54 @@
+# Traceability & Coverage Methodology
+
+## Phase 0 — Derive stories from code
+
+For each feature area:
+
+- *As a [user], I want [action], so that [outcome]* + **acceptance criteria**
+- Tie to implementing code (route/screen/handler/query) — cited
+- Criticality: **Critical** (auth, payments, mutations, RLS reads, irreversible) / Important / Minor
+- Unknown intent → `[NEEDS PRODUCT INPUT]`
+
+## Phase 1 — Inventory tests
+
+```
+Glob: **/*.{test,spec}.{ts,tsx,js,jsx}
+Glob: **/__tests__/**
+Glob: **/e2e/** **/playwright/**
+```
+
+Map each suite to story/feature. Run suite + coverage if available → baseline or `[NEEDS RUN]`.
+
+## Phase 2 — Traceability matrix (core artifact)
+
+| Story | Acceptance criteria | Criticality | Implementing code | Existing test(s) | Coverage verdict | Test-quality verdict |
+
+Coverage verdict: Covered / Partial / **Uncovered**
+
+## Phase 3 — Multi-lens coverage (not just %)
+
+- Statement/branch/condition — happy path only?
+- Path/flow — full journeys (guest vs auth, success vs failure)?
+- Risk — crash-prone / irreversible / security paths first?
+- Integration — Supabase, RLS, payment/auth boundaries (real or proper mocks)?
+- Error/edge — failures, empty, network, permission denials
+
+## Phase 4 — Fake-green detection
+
+- `expect(true)` or no meaningful assertion
+- Over-mocked — mocks the unit under test
+- Tests implementation detail, not behavior
+- Skipped-but-counted, never exercised
+- **Mutation testing** on critical modules — surviving mutants = blind spots
+
+## Guardrails (research-backed)
+
+- Traceability matrix maintained: new story → mapped test
+- Risk-based targets, not blind 100% line chase
+- Mutation testing in CI on critical modules (kill-rate)
+- Coverage gate ratchet in CI; test in same PR as feature
+- Unit / integration / e2e layers; behavior + acceptance criteria
+
+## Chain position
+
+After `plan-stub-checker` wiring approval → **plan-test-coverage** locks behavior before perf/security hardening and docs sync.

package/skills/plan-test-coverage/references/output-templates.md

@@ -0,0 +1,34 @@
+# Output Templates
+
+## Story list (Phase 0)
+
+```markdown
+### Story S-01 [Critical]
+- As a … I want … so that …
+- Acceptance criteria: …
+- Code: path:line
+```
+
+## Coverage baseline
+
+| Metric | Value | Tool | `[NEEDS RUN]` |
+|--------|-------|------|---------------|
+| Line % | … | vitest/jest/coverage | |
+| Branch % | … | | |
+
+## Traceability matrix
+
+| Story | AC | Criticality | Code | Test(s) | Coverage | Quality |
+
+## Burndown
+
+| Story/Area | Gap type | Criticality | Evidence | Proposed test (G/W/T) | Severity | Effort | Risk |
+
+Gap types: uncovered / partial / fake-green / missing-edge
+
+## Phased plan
+
+1. Critical uncovered + fake-green on critical paths (esp. newly wired stubs)
+2. Error/edge + integration boundaries
+3. Important stories
+4. Minor branches

package/skills/plan-test-coverage/references/preservation-contract.md

@@ -0,0 +1,15 @@
+# Preservation Contract
+
+## Never do in this pass
+
+- **Fabricate** stories, tests, or coverage numbers. Stories from real features (routes, handlers) cited in code. Coverage from real run or `[NEEDS RUN]`.
+- **Claim** a test exists or passes without reading it.
+- **Delete or weaken** existing tests — flawed tests get fix proposals; removal needs approval.
+- **Change app code** for testability in this pass — note refactor as proposal.
+- **Enshrine bugs** — wrong behavior flagged, not locked in tests.
+- **Write tests** in this pass. Specs (given/when/then) on approval.
+
+## Buckets
+
+- **True coverage gap** — story has no/partial test
+- **Test-quality issue** — fake-green, over-mocked, implementation-detail test

package/skills/plan-uiux-unification/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: plan-uiux-unification
+description: >
+  Plan-only UI/UX and design-system audit that emits a unification burndown;
+  no code until a phase is approved. Use when "audit UI without fixing", "UI
+  burndown", or "IA audit before redesign". Apply now → housekeep-design.
+license: MIT
+effort: high
+---
+
+# UI/UX & Design-System Audit + Unification Plan
+
+**Degree of freedom: MIXED** — IA and unification plan are judgment; token
+greps and inventory globs run exactly. Stay **plan-only**. No UI edits until approved.
+
+**Role:** Senior frontend/mobile architect + design-systems engineer.
+
+**Task:** Deep, exhaustive, *non-destructive* audit. Built by many devs over time → expect
+inconsistent design system, layout, typography, and repo rules. Find every violation,
+document it, produce a burndown + enhancement plan. **Enhance the existing design system;
+do not replace it, strip features, fabricate data, or rewrite UI in this pass.**
+
+## This skill vs neighbors
+
+| Skill | Does |
+|-------|------|
+| **plan-uiux-unification** (this) | Plan only — full inventory, burndown, roadmap; no fixes |
+| `audit-responsive` | Linearized desktop / breakpoint IA — audit then fix |
+| `audit-uiux-design-system` | Visual/token/component audit; may recommend or fix |
+| `audit-ux` | Heuristics, flows, microcopy quality |
+| `enhance-web-ui` / `enhance-web-ux` | Implement visual/UX improvements |
+| `design-system` | Build or extend the design system itself |
+
+**Chain:** Step 1 of six-skill plan loop — see `docs/PLAN-LOOPS.md`  
+**Execute:** `audit-responsive` (layout/IA) → `enhance-web-ux` / `enhance-web-ui` → `test-playwright`
+
+## How to reason (every plan item)
+
+1. **Propose** — token, primitive, layout, or voice change against the existing DS
+2. **Risk** — brand-break, a11y fail, or a rewrite that strips a feature
+3. **Keep-working** — surfaces and tokens that already match the canonical system
+4. **Phase** — P0 broken/a11y → structural → polish (do not execute)
+
+## Worked example
+
+> **Propose:** replace raw `#1a1a1a` on `/pricing` CTA with the documented primary token (`bg-fg` or equivalent).
+> **Risk:** 14 hex literals on the highest-traffic page; brand-breaking vs the token SSOT.
+> **Keep-working:** `components/ui/Button` already uses semantic tokens.
+> **Phase:** P0 — brand-breaking hex on a conversion surface.
+> **Canonical fix:** value-for-value token swap; no copy or layout rewrite.
+
+---
+
+## ⛔ Preservation Contract
+
+Read `references/preservation-contract.md` in full before Phase 0.
+
+**Acknowledge in output #1** — restate what you will NOT do:
+
+- No feature/route/screen/state/prop/handler removal
+- No fabricated data, content, copy, or API fields
+- Every codebase claim cites a file path you read
+- Preserve I/O boundaries + business logic unless explicitly proposed + approved
+- No silent breaking changes to public APIs, props, or routes
+- This pass **plans**; visual/UX changes are proposals only
+
+---
+
+## Phase flow (do not skip)  [HIGH freedom]
+
+```
+0. Context & IA (before any layout talk)
+1. Design-system ground truth
+2. Full surface inventory
+3. Per-surface deep audit
+4. Burndown (prioritized + risk)
+5. Unification & enhancement plan
+6. Best-practice research (cite current year)
+```
+
+Detailed instructions: `references/phase-workbook.md`  
+Templates: `references/output-templates.md`
+
+---
+
+## Phase 0 — Context & IA FIRST  [HIGH freedom]
+
+Before pixels: user goal, primary task, key action, IA map (primary/secondary/tertiary),
+content relationships, progressive disclosure.
+
+**Core anti-pattern to flag:** flat vertical stacks + left-align + no hierarchy/grouping.
+
+**Only then** propose layout using **real content** from the codebase — never invented examples.
+
+---
+
+## Phase 1 — Design-system ground truth  [HIGH freedom]
+
+Auto-detect (read actual files):  [LOW freedom — run exactly]
+
+```
+Glob: **/tailwind.config.*
+Glob: **/globals.css **/tokens.* **/theme.*
+Glob: **/components/ui/**
+Grep: "STYLEGUIDE|CONTRIBUTING" glob "**/*.md"
+```
+
+Critique: enhance (missing semantic tokens, thin scales) vs enforce (violations of existing rules).
+Multiple systems → name canonical vs legacy + collision points.
+
+Output short **design-system spec** (current state + proposed enhancements).
+
+---
+
+## Phase 2 — Surface inventory  [HIGH freedom]
+
+Exhaustive checklist table — every route, modal, drawer, toast, empty/loading/error state,
+auth/onboarding, responsive + dark per surface. Mark audited only after Phase 3 review.
+
+Delegate an inventory pass to a subagent only when it is sizeable, independent of the others, and its raw output (glob lists, token-grep counts) has no place in the plan; brief it with the exact commands and the columns to return. It edits nothing, like this pass. Long sweeps are expected — context compaction exists, so finish the inventory rather than wrapping up early.
+
+See inventory template in `references/output-templates.md`.
+
+---
+
+## Phase 3 — Per-surface audit  [HIGH freedom]
+
+For each surface, log violations by category:
+
+- IA & hierarchy · Tokens · Typography · Layout/spacing
+- Content & tone (rewrites preserve meaning)
+- AI-generic aesthetic tells
+- Components (duplicates → consolidation *proposals*)
+- Interaction/states · Accessibility (WCAG 2.2)
+- Conflicting/deprecated systems · Tech debt (removal needs confirmation)
+
+**Three buckets:** violates documented rule · subjective improvement · needs DS enhancement
+
+**Token sweep (quantify for burndown):**  [LOW freedom — run exactly]
+
+```
+Grep: "#[0-9a-fA-F]{3,8}" glob "*.{tsx,jsx,vue,css}"
+Grep: "style=\\{" glob "*.{tsx,jsx}" output_mode "count"
+Grep: "className=.*\\b(p|m|gap|text|rounded)-\\[" glob "*.{tsx,jsx}" output_mode "count"
+```
+
+Optional visual verification: read `protocol-browser-anti-stall` and
+`references/playwright-session-coordination.md` in that skill before playwright-cli.
+Plan-only — screenshots for evidence, not fixes.
+
+---
+
+## Phase 4 — Burndown  [HIGH freedom — plan only]
+
+Table columns:
+
+`Surface | Violation | Category | Severity (P0–P3) | Effort (S/M/L) | Risk (Low/Med/High) | Canonical fix | File path(s)`
+
+P0 = broken/inaccessible/brand-breaking · P3 = cosmetic. Quantify where possible.
+
+---
+
+## Phase 5 — Unification plan  [HIGH freedom — plan only]
+
+- Consolidate DS conflicts; deprecate loser + migration path
+- High-traffic layouts driven by Phase 0 IA + real content
+- Content/voice guideline (tone, errors, CTAs, jargon glossary)
+- Token migration / codemod strategy (value-for-value)
+- Primitive consolidation as proposals with dependency checks
+- Guardrails: lint rules, no raw hex, visual regression, PR checklist
+- Phased roadmap: quick wins → structural → polish (each revertible)
+
+---
+
+## Phase 6 — Research  [HIGH freedom]
+
+Firecrawl / web for **current year** best practices — search each named standard as written rather than answering from memory; cite sources:
+
+- Token architecture (semantic/layered, W3C DTCG)
+- IA + visual hierarchy · UX writing · anti-AI-slop aesthetics · WCAG 2.2
+
+Note where this app diverges from research.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — every violation cites a path you read; no invented copy
+2. **plan-only** — no UI/token edits, no PRs
+3. **severity/phase justified** — P0 is broken/inaccessible/brand-breaking, not taste
+4. **right-owner** — linearized breakpoint IA → `audit-responsive`; apply-now token cleanup → `housekeep-design`; per-page heuristics → `audit-ux`
+5. **no-false-safety** — `[NEEDS REAL CONTENT]` stays open; never fabricate examples to fill IA
+
+---
+
+## Required output (in order)
+
+1. Preservation-contract acknowledgment
+2. Context & IA summary (per area)
+3. Design-system spec (current + enhancements)
+4. Surface inventory checklist
+5. Per-surface violation log
+6. Burndown table (with risk column)
+7. Unification + enhancement plan + phased roadmap (+ content/voice guide)
+8. Guardrails / tooling recommendations
+9. Research notes + citations
+10. Open questions / `[NEEDS REAL CONTENT]` list
+
+Deliver as a single markdown doc (or canvas for large repos), then end the turn with a standalone recap in chat: the two or three highest-impact violations and the first phase to approve. The document is the deliverable — write it before the recap. **Do not open PRs or edit UI code**
+unless the user explicitly approves execution in a follow-up.
+
+---
+
+## Rules
+
+- **Plan only — do not fix yet.** User approves before execution.
+- **IA before layout. Hierarchy first, pixels second.**
+- **Enhance, don't replace.** Preserve every feature + all real content/data.
+- **Never fabricate.** Cite real paths/lines. Unverifiable → say so.
+- Surface unreachable or token source missing → say so, don't guess.
+- Before proposing any file change: one line on what must keep working there.
+
+---
+
+## MCP integration
+
+| MCP | Use |
+|-----|-----|
+| Firecrawl | Phase 6 research, anti-AI-slop patterns, WCAG/token governance |
+| Playwright browser | Optional Phase 3 visual evidence; own named session (`-s=…`) per `protocol-browser-anti-stall` |
+| Context7 | Component library / Tailwind docs when naming canonical primitives |
+| Sequential Thinking | Not needed — the IA map and collision analysis go in the deliverable |

package/skills/plan-uiux-unification/references/output-templates.md

@@ -0,0 +1,67 @@
+# Output Templates
+
+## Surface inventory checklist
+
+| Surface | Route / entry | Sub-screens / states | Mobile | Dark | Audited |
+|---------|---------------|----------------------|--------|------|---------|
+| Example | `/settings` | tabs, empty, error | ✓ | ✓ | ☐ |
+
+Include: modals, drawers, sheets, popovers, tooltips, toasts, tabs, accordions, auth, onboarding, skeleton/loading/error/403/404.
+
+## Burndown table
+
+| Surface | Violation | Category | Severity (P0–P3) | Effort (S/M/L) | Risk (Low/Med/High) | Canonical fix | File path(s) |
+|---------|-----------|----------|----------------|-----------------|---------------------|---------------|--------------|
+
+**Severity:** P0 = broken/inaccessible/brand-breaking · P3 = cosmetic  
+**Risk:** flags fixes that touch working behavior  
+**Quantify** where possible (e.g. "37 hardcoded colors across 12 files")
+
+## Phase 0 — IA summary (per major area)
+
+```markdown
+### [Area name]
+- **User goal:** …
+- **Primary task / key action:** …
+- **IA map:** primary / secondary / tertiary content
+- **Relationships:** group together · progressive disclosure · noise
+- **Current anti-pattern:** (e.g. flat vertical stack, left-align, no hierarchy)
+- **Proposed layout direction:** columns/cards/whitespace — using **real content** from code
+```
+
+## Design-system spec (short)
+
+```markdown
+### Canonical source
+- Tokens: [paths]
+- Theme: [tailwind.config / globals.css / tokens.ts]
+- Primitives: [component paths]
+- Lint / STYLEGUIDE: [paths]
+
+### Gaps (enhance, don't replace)
+- Missing semantic tokens: …
+- Weak scales: elevation / type / spacing: …
+
+### Competing systems
+| System | Where used | Status (canonical / legacy) | Collision points |
+```
+
+## Phased roadmap
+
+```markdown
+### Phase A — Quick wins (reviewable, revertible)
+- …
+
+### Phase B — Structural (token migration, primitive consolidation proposals)
+- …
+
+### Phase C — Polish (high-traffic layouts from Phase 0 IA)
+- …
+```
+
+## Guardrails checklist
+
+- [ ] ESLint / Stylelint token rules
+- [ ] No raw hex rule
+- [ ] Visual regression snapshots
+- [ ] PR checklist items

package/skills/plan-uiux-unification/references/phase-workbook.md

@@ -0,0 +1,85 @@
+# Phase Workbook (detailed)
+
+## Phase 0 — Context & IA FIRST
+
+For each major area, from actual code:
+
+- User goal, primary task, key action on the screen
+- IA map: content, grouping, importance (primary/secondary/tertiary), first-scan priority
+- Content relationships: belongs together, progressive disclosure, noise
+- **Only then** propose layout. **Hierarchy drives layout, not the reverse.**
+- Name anti-patterns explicitly: everything stacked vertically + left-aligned with no hierarchy/grouping → core finding
+- Propose layouts (columns, cards, whitespace, alignment, emphasis) using **real content** from the repo
+
+## Phase 1 — Design-system ground truth
+
+- Read canonical tokens: color, spacing, radius, elevation, type scale, z-index
+- Theme config: Tailwind / CSS vars / `tokens.ts` / platform theme
+- Component primitives, `CONTRIBUTING` / `STYLEGUIDE` / lint rules
+- Critique: incomplete vs inconsistent vs weak — **enhance** (missing semantic tokens) vs **enforce**
+- Multiple competing systems → canonical vs legacy/deprecated + collision map
+- Output short **design-system spec** (current + proposed enhancements)
+
+## Phase 2 — Full surface inventory
+
+Enumerate every surface; mark audited only after review:
+
+- All routes/screens + nested sub-screens/flows
+- Modals, dialogs, drawers, bottom sheets, popovers, tooltips, toasts, action sheets
+- Side panels, tabs, accordions, expandable sections
+- Empty / loading / skeleton / error / not-found / permission states
+- Auth, onboarding, settings sub-screens
+- Responsive breakpoints (mobile sizes, orientation, safe areas) + dark/light per surface
+
+**Discovery commands (adapt to stack):**
+
+```
+Glob: **/app/**/page.{tsx,jsx,vue,svelte}
+Glob: **/routes/**/*.{tsx,jsx}
+Glob: **/screens/**/*.{tsx,jsx}
+Grep: "Modal|Dialog|Drawer|Sheet|Popover|Toast" glob "*.{tsx,jsx,vue}"
+```
+
+## Phase 3 — Per-surface audit categories
+
+Log violations per surface:
+
+| Category | Examples |
+|----------|----------|
+| IA & hierarchy | flat stacks, left-align, missing grouping, no primary action, poor scan path |
+| Tokens | hardcoded hex/px, off-scale spacing, non-token colors, ad-hoc shadows/radii |
+| Typography | family/size/weight/line-height off scale |
+| Layout/spacing | grid/container widths, padding rhythm, alignment, safe areas |
+| Content & tone | jargon, dev-speak, inconsistent voice; rewrites preserve meaning |
+| AI-generic look | centered hero, 3 equal cards, indigo gradients, emoji bullets, no POV |
+| Components | one-off reimplementations, divergent variants, duplicates |
+| Interaction/states | hover/focus/active/pressed/disabled, loading/error/empty, gestures |
+| Accessibility | contrast, focus order, ARIA, keyboard/SR, alt text, touch targets (WCAG 2.2) |
+| Conflicting/deprecated | competing systems, deprecated components/APIs/deps |
+| Tech debt | dead code, `!important`, inline escapes, copy-paste drift, TODO/HACK |
+
+Optional live pass: read `protocol-browser-anti-stall` + `playwright-session-coordination` before playwright-cli.
+
+## Phase 4 — Burndown
+
+See `output-templates.md`. Group by severity; quantify; include risk column.
+
+## Phase 5 — Unification & enhancement plan
+
+- Target DS: consolidate conflicts, deprecate loser + migration path, additions for Phase 1 gaps
+- High-traffic screens: layouts from Phase 0 IA + real content + grouping rationale
+- Content/voice guideline: tone, reading level, error/empty/CTA phrasing, jargon→plain glossary
+- Token migration / codemod: value-for-value, no visual change unless intended
+- Primitive consolidation as **proposals** with dependency checks
+- Regression guardrails: lint, token lint, visual regression, PR checklist
+- Phased roadmap: quick wins → structural → polish; each phase independently reviewable + revertible
+
+## Phase 6 — Best-practice research (current year)
+
+Use Firecrawl / web research; cite findings; note where this app diverges:
+
+- Design-system governance + token architecture (layered/semantic, W3C DTCG)
+- IA + visual hierarchy
+- UX writing / plain language
+- Avoiding generic "AI-generated" aesthetic
+- Accessibility (WCAG 2.2)