@ryuenn3123/agentic-senior-core 6.15.1 → 6.16.0

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/tdd-cycle.md

@@ -0,0 +1,62 @@
+# Test-Driven Development (TDD) Cycle
+
+TDD is an architectural discipline for writing deterministic, verifiable software. The Iron Law of TDD governs all development:
+
+> **THE IRON LAW:** No production code shall be written without a failing test first.
+
+---
+
+## 1. The Three Phases of TDD
+
+```
+     ┌────────────────────────────────────────────────────────┐
+     ▼                                                        │
+┌───────────┐          ┌───────────┐          ┌────────────┐  │
+│  1. RED   │ ───────► │ 2. GREEN  │ ───────► │ 3. REFACTOR│ ─┘
+└───────────┘          └───────────┘          └────────────┘
+Write failing test     Write minimum          Clean up design
+Verify failure mode    code to pass           Keep suite green
+```
+
+### Phase 1: RED (Observe the Failure)
+1. Write a focused, minimal test specifying the single desired behavior.
+2. Run the test command fresh.
+3. **Inspect the failure reason:** The test must fail because the feature does not exist or the assertion fails.
+   - *Failure check:* If the test fails due to a syntax error, unhandled import crash, or missing fixture before the assertion runs, fix the test setup first.
+   - *Pass check:* If the test passes immediately without new code, either the behavior already exists, or the test assertion is meaningless.
+
+### Phase 2: GREEN (Minimum Code to Pass)
+1. Write the minimum production code required to satisfy the assertion.
+2. Do not implement future requirements, speculative edge cases, or premature abstractions.
+3. Run the test command fresh and confirm it passes with exit code 0.
+
+### Phase 3: REFACTOR (Improve Structure)
+1. Remove duplication, extract helpers, or simplify naming.
+2. Maintain identical external behavior.
+3. Rerun the test suite after every structural change.
+
+---
+
+## 2. Whole-Suite Verification Gate
+
+Passing an isolated test is insufficient. Local changes frequently break adjacent modules.
+
+Before claiming any task or feature complete:
+1. Run the entire test suite (`ascx npm test`, `ascx pytest`, `ascx go test ./...`, or `ascx cargo test`).
+2. Read the exit code directly from the runner.
+3. If any existing test fails, diagnose whether the failure is a genuine regression or a broken outdated contract. Never weaken assertions to force a green run.
+
+---
+
+## 3. Rationalization Prevention Table
+
+Developers and AI models frequently invent excuses to skip tests. Every excuse has a known failure mode:
+
+| Rationalization | Fallacy | Operational Reality |
+|---|---|---|
+| *"The change is too simple to test."* | Small changes cause silent regressions. | One-line fixes produce 30% of production breakages. Write the 3-line test. |
+| *"I'll write tests after the code works."* | Confirmation bias tests. | Tests written after implementation mirror the existing code bugs and test implementation details rather than contracts. |
+| *"It's just UI / frontend wiring."* | Visual wiring has state logic. | Form validation, button states, and error handling are pure logic and fully testable. |
+| *"Mocking this dependency is too hard."* | Architecture smells. | Difficulty in testing indicates tight coupling. Extract the business logic into a pure function and test that. |
+| *"I verified it manually in the console."* | Ephemeral validation. | Manual checks disappear the moment you close the session. Automated tests protect future refactors permanently. |
+

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/test-design.md

@@ -0,0 +1,75 @@
+# Test Design & Architecture
+
+Tests are executable specifications. Poorly designed tests produce false confidence, brittle maintenance overhead, and resistance to refactoring.
+
+---
+
+## 1. Test Behavior, Not Implementation
+
+Tests must verify external contracts and observable behavior, never internal implementation mechanics.
+
+### 1.1 The Black-Box Principle
+- **Test against public boundaries:** Input arguments, returned values, emitted events, persisted database state, or HTTP responses.
+- **Never assert on internal plumbing:** Do not inspect private class variables, call counts on internal private methods, or local temporary variables.
+- **The Refactoring Test:** If you rewrite an internal algorithm without changing inputs or outputs, your tests should remain completely green. If internal refactoring breaks tests, the tests are coupled to implementation details.
+
+---
+
+## 2. Mocking Discipline & External Boundaries
+
+Mocking is a technique for isolating external unmanaged systems, not an excuse to avoid running real code.
+
+### 2.1 The Iron Rule of Mocking
+> **Never mock the unit under test.**
+> Mock *only* external boundaries: third-party HTTP services, payment gateways, message brokers, system clock, or operating system hardware calls.
+
+### 2.2 Mocking Hierarchy
+Prefer real code or robust test doubles over fragile call-count mocks:
+
+1. **Real Implementation (Preferred):** Use the actual domain code, real validation functions, and real in-memory data structures.
+2. **In-Memory Fakes:** A working in-memory repository or fake mailer that stores sent emails in an array. Fakes preserve semantic behavior without network overhead.
+3. **Boundary Stubs:** Fixed responses for external third-party HTTP endpoints (e.g., Stripe API, GitHub OAuth).
+4. **Spy/Call Mocks (Use with caution):** Asserting `expect(spy).toHaveBeenCalledWith(...)` couples tests to internal call order. Use only when the side-effect *is* the contract (e.g., verifying an audit log event was dispatched).
+
+---
+
+## 3. Test Isolation & Hermetic State
+
+Every test must run in complete isolation.
+
+- **Zero Test Order Dependency:** Tests must succeed when run in isolation, sequentially, or shuffled in random order (`--randomize`).
+- **Teardown Shared Resources:** If a test modifies an environment variable (`process.env.NODE_ENV`), writes to a database, or creates a temporary file on disk, it must restore or delete the resource in an explicit `afterEach` or `finally` block.
+- **No Shared Mutable Fixtures:** Never mutate a shared global object across multiple tests. Use factory functions (`createUser()`) that return fresh independent instances for every test.
+
+---
+
+## 4. Test Structure: The AAA Pattern
+
+Structure every test into three distinct, visually separated phases:
+
+```typescript
+describe('TransferService', () => {
+  it('deducts balance from sender and credits receiver on successful transfer', async () => {
+    // 1. Arrange: Setup fresh state and dependencies
+    const sender = await createTestAccount({ balance: 1000 });
+    const receiver = await createTestAccount({ balance: 200 });
+    const service = new TransferService();
+
+    // 2. Act: Execute the single behavior under test
+    const result = await service.transfer({
+      fromId: sender.id,
+      toId: receiver.id,
+      amount: 300,
+    });
+
+    // 3. Assert: Verify the observable outcome
+    expect(result.status).toBe('COMPLETED');
+    expect(await getBalance(sender.id)).toBe(700);
+    expect(await getBalance(receiver.id)).toBe(500);
+  });
+});
+```
+
+- **One primary action per test:** Keep the `Act` step to a single method invocation.
+- **Specific assertions:** Avoid vague assertions like `expect(result).toBeDefined()`. Assert concrete values.
+

package/.agents/plugins/agentic-senior-core/skills/asc-test/references/uat.md

@@ -0,0 +1,62 @@
+# User Acceptance Testing (UAT) & Requirements Verification
+
+User Acceptance Testing verifies that software fulfills real operational requirements from the perspective of the end user, rather than merely passing isolated unit tests.
+
+---
+
+## 1. Requirements to Acceptance Criteria (Given/When/Then)
+
+Every user requirement or feature ticket must be broken down into concrete, testable acceptance criteria using Given/When/Then structure:
+
+```gherkin
+Scenario: Developer revokes an active API key
+  Given an authenticated developer with 2 active API keys
+  When the developer clicks "Revoke" on key "prod-analytics-key"
+  And confirms the revocation in the confirmation dialog
+  Then key "prod-analytics-key" is marked as inactive immediately
+  And requests using that key return HTTP 401 Unauthorized
+  And the remaining key continues to function normally
+```
+
+---
+
+## 2. Structured Acceptance Verification Matrix
+
+When preparing for release or completing a feature milestone, verify all user journeys against an Acceptance Matrix:
+
+| Requirement ID | Scenario / User Journey | Input / Action | Expected Result | Verification Method | Status |
+|---|---|---|---|---|---|
+| UAT-AUTH-01 | Login with valid credentials | Post valid email + password | Redirects to `/dashboard`, session cookie set | E2E Playwright test | PASS |
+| UAT-AUTH-02 | Login with rate-limited account | 6 failed attempts within 60s | HTTP 429, displays lockout banner with timer | Integration test | PASS |
+| UAT-BILL-01 | Upgrade from Free to Pro tier | Submit Stripe checkout session | Workspace tier reflects Pro, features unlock | Webhook integration test | PASS |
+| UAT-DATA-01 | Export audit log with 10k rows | Click "Export CSV" | Streams CSV file within 2s, memory < 50MB | Benchmark test | PASS |
+
+---
+
+## 3. Ephemeral Verification Artifacts (Zero Project Disk Clutter)
+
+Verification records, testing matrices, and UAT notes belong in the agent conversation artifacts directory (`brain/<id>/`), never in the user's project workspace.
+
+- **Strict Invariant:** Never write `UAT.md`, `test-checklist.json`, `PRD.md`, or temporary gate files to the user repository root unless explicitly instructed by the user.
+- **Reporting:** Present UAT findings clearly in direct chat messages or structured session artifacts.
+
+---
+
+## 4. The Edge Case Quad
+
+Never sign off on acceptance testing by verifying only the primary happy path. Every scenario must be verified against four operational vectors:
+
+1. **Happy Path:** Standard, valid user input under normal network conditions.
+2. **Boundary Values:**
+   - 0 records (empty list / table).
+   - 1 record (single item formatting, no awkward pluralization).
+   - Maximum capacity (pagination boundary, payload size limits).
+3. **Invalid & Malicious Input:**
+   - Empty strings, whitespace-only fields, oversized payloads.
+   - SQL / script injection vectors (`<script>`, `' OR 1=1`).
+   - Unicode, emojis, and non-ASCII characters.
+4. **Failure & Degraded Mode:**
+   - Database connection timeout.
+   - Third-party webhook failure.
+   - Client network disconnection mid-mutation.
+

package/.agents/plugins/agentic-senior-core/skills/asc-ui/SKILL.md

@@ -1,204 +1,91 @@
 ---
 name: asc-ui
 description: >
-  Trigger this skill when the user is working on: user interfaces, UI components, UX design, frontend layouts, microcopy, typography, design systems, modals, forms, tables, dashboards, empty states, or error UI. Also trigger when the user says: "design this page", "clean up this UI", "write UI copy", "fix UI slop", "make it look professional", "too verbose", "improve the design", "bikin UI", "rapikan tampilan", "tulisan UI berlebihan", "terlalu kaku", "jangan kayak AI", "bahasanya aneh". Also trigger when creating or editing files matching: `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `*.blade.php`, `*.css`, or UI component files.
+  Trigger this skill when working on: UI components, UX design, layouts, microcopy, typography, design systems, modals, forms, tables, dashboards, empty states, or error UI. Also trigger when the user says: "design this page", "clean up UI", "write UI copy", "fix UI slop", "make it look professional", "too verbose", "improve the design", "broken on mobile", "bikin UI", "rapikan tampilan", "tulisan UI berlebihan", "tampilan di hp rusak", "terlalu kaku", "jangan kayak AI". Also trigger when creating or editing files matching: `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `*.blade.php`, `*.css`, or UI component files.
 ---
 
-# Universal UI/UX Engineering & Anti-Slop Guidelines
+# Universal UI/UX Engineering & Anti-Slop Router
 
-Universal engineering and microcopy standards for human-grade, scannable, and robust digital interfaces. Eliminates generic "AI Slop" — verbose text, redundant headings, corporate filler, awkward foreign loanwords, and cookie-cutter layouts.
-
-Grounded in: Nielsen Norman Group (Microcopy & Scannability), Refactoring UI (Hierarchy & Spacing), Apple HIG & Google Material Design 3 (Action Semantics & Tone), and W3C Internationalization / Localization Best Practices.
+Staff-grade design engineering for resilient, scannable, human-grade interfaces. Enforces the visual floor and routes deep craft guidance on demand.
 
 ---
 
-## 1. UX Microcopy & Text De-sloppification
-
-LLMs naturally gravitate toward corporate marketing fluff and redundant explanations. In functional UI (dashboards, forms, settings, tables, dialogs), text is a tool for orientation and action, not a brochure.
-
-### The Redundancy Elimination Rule (Kill Useless Subtitles)
-- **Zero Echo Subtitles:** If a heading or label is self-explanatory (e.g., *"Payment Methods"*, *"Invoice History"*, *"Team Members"*), **NEVER** add an explanatory subtitle repeating the heading's words (e.g., *"Manage, view, and organize all your payment methods here"*).
-- **Subtitle Criterion:** A subtitle is permitted **ONLY** if it contains an essential technical constraint or irreversible risk:
-  - *Allowed:* *"API keys are shown once upon creation and cannot be retrieved later."*
-  - *Forbidden:* *"View and manage your API keys to authenticate requests."*
-- **Field Helper Text:** Only describe formatting constraints or privacy rules (e.g., `Max 10MB (PDF, PNG)`). Do not re-explain the field name (`Enter your email address here`).
-
-### The 50% Word Reduction Rule
-- Cut default AI-generated copy by at least 50%. Strip preamble, conversational filler, and passive voice.
-- **Before (AI Slop):** *"In order to successfully proceed with saving your profile changes, please make sure all required fields are accurately filled out."*
-- **After (Clean UI):** *"Fill out all required fields to save."*
-
-### Active, Imperative Action Labels (Buttons & Controls)
-- **Direct Verb + Noun:** Use concise, concrete verbs indicating the immediate outcome: `Save`, `Delete Project`, `Export CSV`, `Send Invite`, `Upgrade Plan`.
-- **Banned Action Phrases:** Never use `Click here to...`, `Press to...`, `Proceed`, or vague single words like `Submit` or `OK` when a descriptive verb exists.
-
-### Banned Marketing Buzzwords in Functional UI
-Never use hyperbolic adjectives in application interfaces:
-- **Forbidden:** `seamless`, `seamlessly`, `effortless`, `effortlessly`, `empower`, `robust`, `revolutionize`, `dynamic`, `all-in-one`, `supercharge`, `elevate`, `unlock the power of`, `at your fingertips`, `cutting-edge`.
-- Treat an admin dashboard or business tool with utilitarian dignity. Describe the system state neutrally.
+## 1. The Quality Floor (Non-Negotiable Bans)
+
+Every UI edit must satisfy these 15 rules without exception:
+
+1. **Token discipline:** All colors, spacing, and typography must resolve through declared design tokens or CSS variables. Zero raw hex codes (`#6366f1`) or arbitrary inline pixel values.
+2. **Animation safety:** Never use `transition: all`. Never animate layout dimensions (`width`, `height`, `top`, `left`). Animate only GPU properties (`transform`, `opacity`).
+3. **Reduced motion:** Every CSS animation or transition must respect `@media (prefers-reduced-motion: reduce)`.
+4. **Focus visibility:** Never strip focus indicators (`outline-none`) without an immediate high-contrast `:focus-visible` replacement.
+5. **No hallucinated material:** Never invent metrics, testimonials, customer quotes, or fake partner logos.
+6. **No eyebrows or kicker tags:** Headings carry their own weight. Never place `text-[11px] uppercase tracking-wider` micro-labels above titles.
+7. **No AI cliché gradients:** Never use purple-to-blue/indigo gradients or text clipping (`bg-clip-text text-transparent`).
+8. **No card-in-card nesting:** Never nest rounded bordered cards inside other rounded cards.
+9. **Single elevation declaration:** Choose either a 1px border OR an elevation shadow, never both (ban the ghost card).
+10. **Mobile viewport unit:** Use `min-h-dvh` or `100dvh` for full-height containers, never `100vh` or `h-screen`.
+11. **Mobile containment:** Set `overflow-x: clip` on root shells. Never leak horizontal scrolling.
+12. **Touch targets:** Minimum 44×44px hit target with $\ge$ 8px clearance for all interactive touch controls.
+13. **Contrast floor:** Meet WCAG 2.2 AA (4.5:1 normal text, 3:1 large text and UI component boundaries).
+14. **Single-language purity:** Never mix languages on one surface; ban hybrid neologisms (`di-submit`, `meng-generate`).
+15. **Icon semantics:** Never use raw unicode or emojis as icons. Use dedicated SVG icons; mark decorative icons `aria-hidden="true"`.
+16. **Substance over restraint:** Stripping slop is only half the job. Replace removed ornaments with real substance: strong typographic scale contrast, full-field color anchors, and authentic interface fragments. Never leave an empty, sterile wireframe void.
 
 ---
 
-## 2. Language Purity & Localization Discipline
-
-AI frequently creates "localization slop" by mixing languages, fabricating awkward hybrid loanwords, or inserting literal dictionary translations that sound unnatural to native speakers.
-
-### Strict Single-Language Consistency
-- **Zero Hybrid Code-Switching:** The UI must maintain 100% language purity for its target locale. Never mix English tech slang into non-English interfaces unless it is an established international symbol (e.g., `ID`, `URL`, `API`).
-  - *Forbidden (Gado-gado/Jaksel):* *"Submit formulir Anda untuk meng-empower efisiensi dashboard."*
-  - *Correct (Indonesian):* *"Kirim formulir untuk memperbarui data ringkasan."*
-  - *Correct (English):* *"Submit the form to update dashboard data."*
-
-### No Artificial Hybrid Neologisms
-- Never create unidiomatic grammatical Frankenstein words by attaching native affixes to English stems:
-  - *Forbidden:* `meng-generate`, `di-submit`, `meng-approve`, `di-cancel`, `men-delete`.
-  - *Use established native terms:* `membuat / menghasilkan`, `kirim`, `setujui`, `dibatalkan`, `hapus`.
+## 2. Pre-Flight & Material Inventory
 
-### Deterministic Microcopy Glossary
-- Never exhibit "Thesaurus Syndrome" (swapping words across dialogs to avoid repetition). Control labels must remain mechanically deterministic across every screen:
-  - Cancellation must always be `Batal` (ID) or `Cancel` (EN) — never alternate with `Urungkan`, `Tutup`, or `Kembali` for identical actions.
-  - Deletion must always be `Hapus` (ID) or `Delete` (EN).
-  - Saving must always be `Simpan` (ID) or `Save` (EN).
-
-### Dynamic Text Expansion Budget
-- Non-English translations (Indonesian, German, French, Spanish) are typically 20% to 40% longer than English equivalents.
-- Containers, button labels, table headers, and badges must never have rigid fixed pixel widths (`w-[120px]`) that cause text clipping or awkward multi-line wrapping. Use flexible flex/grid layouts with sensible min-widths and text truncation (`truncate` with title tooltips) where appropriate.
+Before declaring markup, inspect the workspace:
+1. **Design Tokens:** Read project CSS variables, Tailwind configuration, or existing components in `components/` or `ui/`. If `DESIGN.md` exists, read it (read-only). Never create or edit persistent checkpoint files.
+2. **Take the Material Inventory:**
+   - **Real:** Concrete numbers, existing endpoints, actual data attributes.
+   - **Pictures:** Actual screenshots and product visual assets.
+   - **Absent:** Missing quotes, missing logos, or unverified metrics—these are omitted entirely.
 
 ---
 
-## 3. Visual Craft & Generative Layout Engineering
-
-AI default interfaces suffer from **Distributional Convergence** (regression to the statistical average of training data). Without disciplined direction, models default to either the *AI Starter Pack* (purple gradients, 3 identical cards, floating drop shadows) or the *Sterile Default* (flat, depressing white wireframes with zero character).
-
-Follow these design engineering heuristics to construct purposeful, high-craft digital interfaces:
-
-### The Anti-Sterile & Anti-Template Rule
-- **Never Replace Slop with Sterile Voids:** Stripping all decoration does not equal good design. An interface must possess tactile depth, distinct typographic rhythm, and clear surface relationships.
-- **No Second-Order Template Clones:** Never force every screen into a trendy Bento Grid or dark-mode clone. Choose layout geometry derived strictly from the **data shape** and **user task**.
-
-### 1. Form Follows Data Shape (Layout Inference)
-Analyze the primary data model and user goal before declaring any container markup:
-- **Quantitative / Comparative Data (Metrics, ledgers, logs, transactions):**
-  - *Archetype:* **Dense Data Matrix**.
-  - *Pattern:* High-density tables or compact list rows with sticky headers, hairline borders (`border-b border-border/40`), zebra striping or hover highlights, and right-aligned metrics using `tabular-nums font-mono`.
-  - *Forbidden:* Packaging individual transaction records into giant cards with fluffy padding.
-- **Relational / Hierarchical Entities (Settings, file explorers, entity management):**
-  - *Archetype:* **Master-Detail Two-Pane Canvas**.
-  - *Pattern:* Contextual fixed-width left rail (navigation/entity list) paired with a fluid, high-density right canvas for inspection and action.
-- **Procedural / Single-Task Flows (Onboarding, checkouts, complex multi-step forms):**
-  - *Archetype:* **Focused Single-Task Stream**.
-  - *Pattern:* Centered single-column container (`max-w-xl` / `max-w-2xl`) with progressive disclosure, clear step indicators, and zero peripheral sidebar noise to prevent distraction.
-- **Temporal / Event-Driven Records (Audit logs, status updates, activity history):**
-  - *Archetype:* **Linear Timeline Ledger**.
-  - *Pattern:* Vertical line rail with timestamp anchors, compact status chips, and contextual user badges.
-- **High-Impact Narrative / Showcase (Landing pages, project overviews):**
-  - *Archetype:* **Asymmetric Visual Anchor**.
-  - *Pattern:* 7-column editorial narrative anchor (heavy typography + primary action) offset against a 5-column interactive preview or live metric widget.
-
-### 2. The Single Focal Anchor Principle (Anti-Cardocalypse)
-- **Eliminate Equal-Weight Monotony:** Never place 3 or 4 cards with identical dimensions, identical icons, and identical visual weight side by side.
-- **Establish One Primary Focal Point:** Every screen or section must possess exactly ONE visual hero that pulls the eye first (e.g., the primary telemetry chart, the key operational metric, or the main action trigger).
-- **Subordinate Supporting Elements:** All surrounding widgets must intentionally recede: use lower contrast text (`text-muted-foreground`), lighter borders, or muted background surfaces (`bg-muted/40`).
-
-### 3. Tactile Surface Craft & Stepped Tones (Beyond Drop Shadows)
-Avoid excessive fuzzy drop shadows (`shadow-lg`, `shadow-xl`) that make UI float disconnected from reality. Build physical depth via border-driven architecture and stepped surfaces:
-- **Stepped Surface Tones (3-Tier Depth):**
-  - *Base Canvas:* Neutral floor (`bg-slate-50` in light; `bg-zinc-950` / `bg-neutral-950` in dark).
-  - *Structural Containers / Cards:* Elevated surface (`bg-white` in light; `bg-zinc-900` / `bg-neutral-900` in dark).
-  - *Inset / Subdued Wells:* Recessed areas for search bars, code blocks, or secondary filters (`bg-slate-100/70` in light; `bg-zinc-800/40` in dark).
-- **Hairline Alpha Borders:** Separate structural surfaces with crisp 1px borders using opacity: `border-slate-200/80` (light) or `border-zinc-800` / `border-white/[0.08]` (dark).
-- **Physical Top-Edge Inset:** For dark surfaces, provide a crisp physical sheen using an inset highlight: `shadow-[inset_0_1px_0_rgba(255,255,255,0.06)]` instead of exterior glows.
-
-### 4. Color Discipline & The 60-30-10 Rule
-- **Lock the Palette to 3-5 Tokens:** Never scatter disparate colors across cards.
-- **60% Dominant Neutral:** Canvas background and large negative space (tinted neutral like slate, zinc, or warm stone; never stark dead `#000000` or `#FFFFFF`).
-- **30% Structural Neutral:** Card surfaces, borders, navigation bars, and dividers.
-- **10% Purposeful Accent:** Dedicated brand accent color.
-- **Accent Exclusivity:** The accent hue is reserved strictly for interactive triggers (Primary CTA, active tab indicator, unread dot, selected checkbox). **NEVER** use the accent color as card wallpaper, gradient fills, or decorative borders.
-
-### 5. Micro-Typography & Scannability
-- **Weight Contrast Before Size Jumps:** Build visual hierarchy by combining font weight (`font-bold` vs `font-normal`) and tracking (`tracking-tight` on large headings; `tracking-normal` on body) before inflating font size to absurd dimensions.
-- **Tabular Numerals Everywhere:** Every metric, balance, percentage, timestamp, and count **MUST** use `tabular-nums` (and preferably `font-mono` where appropriate) to prevent optical horizontal jitter when values update.
-- **Eyebrow Micro-Labels:** Anchor section headers and data clusters with compact category tags: `text-[11px] font-semibold uppercase tracking-wider text-muted-foreground`.
-
-### 6. The Banned AI Visual Starter Pack
-Explicitly forbid these generic AI clichés:
-- **No Purple-to-Cyan/Indigo Gradients:** Ban unprompted glowing violet/teal hero washes.
-- **No Gratuitous Glassmorphism:** Never slap `backdrop-blur-md bg-white/10` across functional tables and forms where it ruins text contrast.
-- **No Bouncy/Distracting Hover Scales:** Avoid `hover:scale-105` or springy transforms on utilitarian buttons. Use snappy, mechanical micro-feedback (`transition-colors duration-150` or `active:scale-[0.98]`).
-- **No Meaningless Generic Badges:** Eliminate fake floating pills like "AI Powered" or generic "Beta" chips scattered for decoration.
+## 3. Surface Modes & Ambition Scaling
 
----
+Determine visual posture from the **surface**, not the product brand:
 
-## 4. State Quad & Feedback Architecture
-
-Every asynchronous view or mutation must deterministically handle all states:
-
-### The Data State Quad
-1. **Loading State:** Render proportional skeleton screens matching the actual layout shape (never a single generic spinner in the middle of a blank canvas).
-2. **Empty State:**
-   - Maximum 1 direct sentence stating reality + 1 primary action button.
-   - *Good:* *"No active projects. [Create Project]"*
-   - *Forbidden:* Flowery essays (*"Your workspace is a blank canvas awaiting your creative brilliance..."*).
-3. **Error State:**
-   - Factual description of what failed + 1 clear recovery button (`[Retry]`).
-   - *Good:* *"Unable to load invoices. [Retry]"*
-   - *Forbidden:* Apologetic colloquialisms (*"Oopsie! Something went wrong on our end..."*).
-4. **Populated State:** High-density, cleanly structured data presentation.
-
-### Action Mutation Feedback
-- Every mutation button (submit, delete, update) **MUST** immediately reflect a pending state:
-  - Disable the button (`disabled`).
-  - Show an inline spinner or change text to ongoing action (`Saving...`).
-- Display clear, localized toast or banner confirmation upon completion with actionable retry on failure.
-- Never silently swallow mutation errors. Wrap critical route widgets in localized React/Vue Error Boundaries.
+- **Operate (`references/modes/operate.md`):** Dashboards, settings, data tables, developer tools. Prioritizes dense scannability, master-detail rails, `tabular-nums`, and inline progressive disclosure.
+- **Persuade (`references/modes/persuade.md`):** Landing pages, pricing tiers, conversion flows. 80-word viewport budget, asymmetric postures, single signature element, zero equal-weight 3-card grids.
+- **Read (`references/modes/read.md`):** Documentation, changelogs, knowledge bases. 65–75ch measure (`max-w-prose`), dual-rail navigation, syntax-highlighted code blocks.
+- **Experience (`references/modes/experience.md`):** Showcases, portfolios, interactive galleries. Receding interface chrome, full-bleed visual canvas, tactile exploration.
 
 ---
 
-## 5. Mobile-First Responsive Reflow & Touch Ergonomics
-
-Mobile layout is a distinct, intentional reflow — not the desktop layout squeezed into a narrow viewport.
-
-### Intentional Reflow Over Shrunken Desktops
-- **Re-stack and Re-order:** When the viewport narrows, multi-column grids must collapse into a clean, single-column stack. Side-by-side card grids must never squeeze horizontally until text wraps into 2-letter lines.
-- **Content-Driven Breakpoints:** Place breakpoints where content begins to stress or break readability, never based on a rigid list of marketing device specs (e.g., iPhone 14 width). Test by dragging viewports smoothly across the full 320px–1024px range.
-- **Mobile Section Padding:** Desktop padding scales (96px, 128px) create absurd vertical wastelands on phones. Reduce section vertical padding to a mobile register (typically 32px–48px / `py-8` to `py-12`).
+## 4. Scope Classification: Refine vs. Redesign
 
-### Responsive Units & Viewport Traps
-- **Dynamic Viewport Height (`dvh`):** Never use `100vh` for full-screen hero or drawer elements on mobile. Mobile browser chrome (address and navigation bars) dynamically expands and collapses, causing `100vh` to trigger involuntary page scrolling and button clipping. Use `min-h-dvh` or `h-dvh`.
-- **Fluid Typography:** Avoid rigid fixed-pixel headings (`font-size: 48px`). Use fluid typography (`clamp(1.5rem, 4vw + 1rem, 2.75rem)`) or explicit responsive font classes (`text-2xl sm:text-4xl lg:text-5xl`).
-
-### Touch Targets & Thumb-Zone Ergonomics
-- **44x44px Minimum Touch Target:** Every interactive element (buttons, icon links, checkbox toggles, chips) must have a touch target of at least 44x44px (`min-h-[44px] min-w-[44px]`). If an icon is small (16px), pad its container (`p-3`).
-- **Touch Clearance:** Maintain at least 8px spacing between adjacent touch targets to eliminate accidental mis-taps.
-- **Reachability:** Place primary mobile actions (submit, filters, navigation) within comfortable thumb reach (bottom sheets, sticky action bars) rather than marooning them at the extreme top corners.
-
-### Zero Horizontal Scroll Leaks
-- The entire mobile page must maintain zero horizontal overflow.
-- **Tables & Code Blocks:** Wrap wide tables and code blocks in dedicated horizontal scroll containers (`overflow-x-auto max-w-full`) with visible scroll indications, preventing them from blowing out the body width.
-- **Long Unbroken Strings:** Protect against email addresses, hashes, or URLs overflowing cards using `break-words` or `truncate`.
+- **Refinement:** Preserves layout structure, component APIs, DOM hierarchy, and color tokens. Polishes padding rhythm, contrast, microcopy, and state completeness.
+- **Redesign:** Replaces the visual hierarchy, typographic pairing, and surface mode while strictly preserving data bindings, event handlers, and business logic.
 
 ---
 
-## 6. Human Accessibility & Contrast Engine (WCAG 2.2 AA)
+## 5. On-Demand Reference Library
 
-An interface that excludes users with diverse vision, motor, or device constraints is structurally broken.
+Load these references only when working on that specific domain:
 
-### Mathematical Contrast Minimums
-Always meet WCAG 2.2 AA contrast ratios:
-- **Normal Body Text (< 18px or regular < 14px bold):** Minimum **4.5:1** contrast against adjacent background.
-- **Large Text (>= 18px or bold >= 14px):** Minimum **3.0:1** contrast.
-- **Non-Text Components & States:** Minimum **3.0:1** for input borders, focus indicators, status badges, and active icons against their background (WCAG 1.4.11).
+| Topic | Reference Path |
+|---|---|
+| Waivable defaults & waiver syntax | [references/reflexes.md](references/reflexes.md) |
+| Typography, line-height & tabular numbers | [references/craft/typography.md](references/craft/typography.md) |
+| Color tokens, 60-30-10 & elevation | [references/craft/color-surfaces.md](references/craft/color-surfaces.md) |
+| Micro-interactions & GPU motion | [references/craft/motion.md](references/craft/motion.md) |
+| Native surfaces (selection, caret, scrollbars) | [references/craft/browser-surfaces.md](references/craft/browser-surfaces.md) |
+| 50% reduction, active verbs & i18n | [references/copy-i18n.md](references/copy-i18n.md) |
+| Responsive reflow, dvh & touch targets | [references/mobile-responsive.md](references/mobile-responsive.md) |
+| WCAG 2.2 AA contrast & keyboard operability | [references/accessibility.md](references/accessibility.md) |
+| The Data State Quad & mutation feedback | [references/states-feedback.md](references/states-feedback.md) |
+| Anti-convergence, 3 Waves of Tells & Mirror Test | [references/divergence.md](references/divergence.md) |
+| Structured UI audit matrix | [references/redesign-audit.md](references/redesign-audit.md) |
 
-### The Grey-on-Grey Hallucination Trap
-Human eyes consistently overestimate contrast on subtle grey pairs:
-- `#777777` on pure white (`#FFFFFF`) produces **4.48:1** (FAILS normal text AA; minimum safe pure gray is `#767676` which achieves 4.54:1).
-- `#555555` on pure black (`#000000`) produces **2.82:1** (FAILS all text AA).
-- When placing text over gradient backgrounds or images, add a solid scrim or compute contrast at the lightest/darkest coordinate point, not just the center.
-
-### Keyboard Operability & Focus Rings
-- **Zero Stripped Focus Rings:** Never write `outline: none` or `focus:outline-none` without an immediate high-contrast `:focus-visible` replacement (`focus-visible:ring-2 focus-visible:ring-offset-2`). Stripping focus breaks keyboard navigation completely.
-- **No Mouse-Only Patterns:** Never gate critical functionality behind hover (`:hover`) without an equivalent keyboard or touch focus trigger.
-- **Dialog Escape Hatch:** Every modal, drawer, or dropdown must close immediately upon pressing the `Escape` key and restore keyboard focus to the triggering element.
+---
 
+## 6. Verification & Handoff Sweep
 
+Before completing any UI task, run this mechanical check:
+1. **State Quad:** Loading skeleton, empty state, error with retry, and populated data are all handled.
+2. **Pending Feedback:** Buttons disable and display feedback during ongoing mutations.
+3. **Contrast & Focus:** Verify keyboard tab flow and high-contrast `:focus-visible` styling.
+4. **Lint Check:** Verify changes against `hooks/lib/known-ui-slop-patterns.json`.

package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/accessibility.md

@@ -0,0 +1,102 @@
+# Accessibility Engineering & WCAG 2.2 Compliance
+
+Accessibility is not an afterthought or an optional overlay. It is the structural floor of web engineering. Every component must be perceivable, operable, understandable, and robust.
+
+---
+
+## 1. Contrast Ratios & The Grey-on-Grey Trap
+
+All text and critical visual indicators must meet WCAG 2.2 Level AA mathematical contrast floors.
+
+### 1.1 Contrast Floors
+- **Normal Body Text (< 18pt / 24px regular, < 14pt bold):** Minimum `4.5:1` contrast ratio against its background.
+- **Large Text ($\ge$ 18pt / 24px regular, $\ge$ 14pt bold):** Minimum `3:1` contrast ratio.
+- **UI Components & Graphical Boundaries:** Active input borders, toggle switches, and focus indicators require minimum `3:1` against adjacent background colors.
+
+### 1.2 The Dark Mode Grey-on-Grey Trap
+A frequent aesthetic failure is using low-contrast grey text for "subtle elegance":
+- **Failing example:** `text-zinc-500` (`#71717a`) on `bg-zinc-900` (`#18181b`) = **3.8:1** (Fails 4.5:1 AA for body copy).
+- **Compliant fix:** `text-zinc-400` (`#a1a1aa`) on `bg-zinc-900` = **6.2:1** (Passes AA).
+- **Light mode equivalent:** `text-zinc-400` (`#a1a1aa`) on `bg-white` = **2.6:1** (Fails). Must use `text-zinc-600` (`#52525b`, 5.7:1) or darker for readable secondary copy.
+
+---
+
+## 2. Focus Management & Keyboard Operability
+
+Every capability available via pointer must be fully operable via keyboard alone.
+
+### 2.1 The Focus-Visible Rule
+Never remove browser focus indicators without providing an immediate high-contrast replacement:
+
+```html
+<!-- BANNED: Strips focus visibility entirely -->
+<button class="outline-none">Action</button>
+
+<!-- ENFORCED: High-contrast focus ring on keyboard interaction -->
+<button class="focus:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-background">
+  Action
+</button>
+```
+
+### 2.2 Dialog Focus Traps & Escape Key Contract
+Any modal, drawer, or sheet must obey the modal contract:
+1. **Focus Trap:** When opened, focus moves to the first focusable element inside the modal. Keyboard `Tab` cycles strictly inside the dialog.
+2. **Escape Key Dismissal:** Pressing `Escape` must immediately close the dialog.
+3. **Return Focus:** Upon closing, focus must return to the element that triggered the dialog open event.
+4. **ARIA Metadata:** Outer container must declare `role="dialog"`, `aria-modal="true"`, and `aria-labelledby="dialog-title-id"`.
+
+---
+
+## 3. Accessible Form Controls
+
+Forms must convey intent, association, and error states programmatically.
+
+```html
+<div class="space-y-1.5">
+  <label for="user-email" class="text-sm font-medium text-foreground">
+    Work email
+  </label>
+  <input
+    id="user-email"
+    name="email"
+    type="email"
+    aria-invalid="true"
+    aria-describedby="email-error-msg"
+    class="w-full px-3 py-2 rounded-md border border-destructive bg-background text-foreground focus-visible:ring-2 focus-visible:ring-destructive"
+  />
+  <p id="email-error-msg" class="text-xs text-destructive flex items-center gap-1" role="alert">
+    <svg class="w-3.5 h-3.5" aria-hidden="true">...</svg>
+    <span>Enter a valid corporate email address (e.g. name@company.com).</span>
+  </p>
+</div>
+```
+
+- Every `<input>` must be explicitly linked via `for` and `id` to a `<label>`. Do not rely solely on `placeholder`.
+- Errors must use `role="alert"` and link via `aria-describedby`.
+- When invalid, set `aria-invalid="true"`.
+
+---
+
+## 4. Icon & Image Semantics
+
+1. **Decorative Icons:**
+   All decorative SVG icons alongside visible text must be hidden from screen readers:
+   ```html
+   <button>
+     <svg aria-hidden="true" class="w-4 h-4">...</svg>
+     <span>Download receipt</span>
+   </button>
+   ```
+
+2. **Standalone Icon Buttons:**
+   Buttons containing only an icon must supply an accessible name via `aria-label`:
+   ```html
+   <button type="button" aria-label="Delete document" class="p-2">
+     <svg aria-hidden="true" class="w-4 h-4">...</svg>
+   </button>
+   ```
+
+3. **Images:**
+   - Informative graphics, charts, and photos: descriptive `alt="Graph showing 42% revenue increase in Q3"`.
+   - Purely aesthetic background patterns or decorative dividers: empty `alt=""` so screen readers ignore them.
+