chati-dev 3.2.4 → 3.3.0

package/framework/agents/plan/ux.md

@@ -82,6 +82,19 @@ Output: Interaction pattern library (text-based)
 
 ### Phase 4: Design System Definition
 ```
+PREREQUISITE: Reference Benchmarking (Directive 3)
+  → If user has provided reference URLs, analyze them first
+  → If no references provided, ask user before proceeding
+  → Produce reference-analysis.md
+
+RULE: No emojis anywhere (Directive 1)
+  → All icons from approved libraries (Flaticon UI, Lucide, Heroicons, Phosphor, Radix)
+  → Define icon token layer
+
+RULE: 100% tokenization target (Directive 2)
+  → Every value must be a named token
+  → Every element must be a component (Atomic Design)
+
 Following Atomic Design principles:
 
 Layer 1 — Design Tokens (Primitives):
@@ -91,6 +104,7 @@ Layer 1 — Design Tokens (Primitives):
   Borders: radius, width, style
   Shadows: elevation levels
   Breakpoints: responsive thresholds
+  Icons: size, stroke-width, color tokens
 
 Layer 2 — Semantic Tokens:
   Map primitives to meaning:
@@ -104,17 +118,45 @@ Layer 2 — Semantic Tokens:
   --color-background (light) -> --color-neutral-50
   --color-background (dark) -> --color-neutral-900
 
+  Icon semantic mapping:
+  --icon-action -> Lucide:plus / Flaticon:{id}
+  --icon-navigation -> Lucide:arrow-right / Flaticon:{id}
+  --icon-status-success -> Lucide:check-circle / Flaticon:{id}
+  --icon-status-error -> Lucide:x-circle / Flaticon:{id}
+
 Layer 3 — Component Tokens:
   --button-padding-x, --button-border-radius
   --card-shadow, --card-padding
   --input-border-color, --input-focus-ring
-
-Layer 4 — Component Patterns:
-  Button: variants (primary, secondary, ghost, danger)
-  Input: states (default, focus, error, disabled)
-  Card: layouts (simple, media, action)
-  Modal: sizes (sm, md, lg)
-  Table: responsive behavior
+  --icon-button-size, --icon-button-padding
+
+Layer 4 — Component Patterns (Atomic Design):
+  Atoms:
+    Button: variants (primary, secondary, ghost, danger), states (default, hover, active, focus, disabled, loading)
+    Input: states (default, focus, error, disabled)
+    Badge: variants (info, success, warning, error)
+    Avatar: sizes (sm, md, lg)
+    Icon: library reference + size + color token
+
+  Molecules:
+    SearchBar: Input + IconButton
+    FormField: Label + Input + HelperText + ErrorText
+    MenuItem: Icon + Label + Badge (optional)
+
+  Organisms:
+    Card: layouts (simple, media, action)
+    Modal: sizes (sm, md, lg)
+    Table: responsive behavior
+    Header: Logo + Navigation + Actions
+    Sidebar: MenuItems + Sections
+
+  Templates:
+    Page layouts with placeholder regions
+
+Layer 5 — Tokenization Audit:
+  Run Directive 2 tokenization completeness check
+  Report coverage percentages
+  Zero hardcoded values is the target
 ```
 
 ### Phase 5: Compile & Validate
@@ -152,24 +194,29 @@ Criteria (binary pass/fail):
 1. User flows defined for all primary personas
 2. Information architecture / sitemap present
 3. Interaction patterns defined (forms, loading, errors, empty)
-4. Design tokens defined (colors, typography, spacing minimum)
+4. Design tokens defined (colors, typography, spacing, icons minimum)
 5. Accessibility requirements specified (WCAG 2.1 AA minimum)
 6. Responsive strategy defined (breakpoints, behavior)
-7. Component patterns listed (at least buttons, inputs, cards)
+7. Component patterns listed with Atomic Design hierarchy (atoms, molecules, organisms)
 8. Dark mode strategy defined (even if "not needed" — document the decision)
 9. All UX decisions traceable to Brief user needs
 10. No placeholders ([TODO], [TBD]) in output
+11. Zero emojis in all output — icons from approved libraries only (Directive 1)
+12. Tokenization coverage >= 95% — no hardcoded visual values (Directive 2)
+13. Reference benchmarking completed OR explicitly waived by user (Directive 3)
+14. Visual direction is unique — font pairing, color palette, and layout archetype differ from permanent references and recent projects (Directive 4)
 
 Score = criteria met / total criteria
-Threshold: >= 95% (9/10 minimum)
+Threshold: >= 93% (13/14 minimum)
 ```
 
 ---
 
 ## Output
 
-### Artifact
-Save to: `chati.dev/artifacts/4-UX/ux-specification.md`
+### Artifacts
+1. Save to: `chati.dev/artifacts/4-UX/ux-specification.md`
+2. Save to: `chati.dev/artifacts/4-UX/reference-analysis.md` (if reference URLs provided)
 
 ```markdown
 # UX Specification — {Project Name}
@@ -217,13 +264,40 @@ Save to: `chati.dev/artifacts/4-UX/ux-specification.md`
 | --space-1 | 4px |
 | --space-2 | 8px |
 
-### Component Patterns
-{Button, Input, Card, Modal, Table patterns}
-
-## 5. Accessibility
+### Icon System
+| Context | Library | Icon ID | Size Token | Color Token |
+|---------|---------|---------|------------|-------------|
+| Navigation | {lib} | {id} | --icon-size-md | --icon-color-default |
+
+### Component Patterns (Atomic Design)
+#### Atoms
+{Button, Input, Badge, Avatar, Icon — with variants, states, tokens}
+
+#### Molecules
+{SearchBar, FormField, MenuItem — with composition rules}
+
+#### Organisms
+{Card, Modal, Table, Header, Sidebar — with responsive behavior}
+
+### Tokenization Audit
+| Category | Tokenized | Total | Coverage |
+|----------|-----------|-------|----------|
+| Colors | {n} | {n} | {%} |
+| Typography | {n} | {n} | {%} |
+| Spacing | {n} | {n} | {%} |
+| Shadows | {n} | {n} | {%} |
+| Icons | {n} | {n} | {%} |
+| **Overall** | {n} | {n} | **{%}** |
+
+## 5. Reference Benchmarking
+{Analysis of reference sites — see reference-analysis.md for full report}
+| Reference | Key Takeaway | Applied In |
+|-----------|-------------|------------|
+
+## 6. Accessibility
 {WCAG requirements, keyboard navigation, screen reader support}
 
-## 6. Responsive Strategy
+## 7. Responsive Strategy
 {Breakpoints, layout behavior per breakpoint}
 
 ## Traceability
@@ -240,7 +314,7 @@ agents:
   ux:
     status: completed
     score: {calculated}
-    criteria_count: 10
+    criteria_count: 14
     completed_at: "{timestamp}"
 current_agent: phases
 ```
@@ -278,7 +352,7 @@ On explicit `*help` request, display:
 | *help        | Show this table           | --                |
 +--------------+---------------------------+-------------------+
 
-Progress: Phase {current} of 6 -- {percentage}%
+Progress: Phase {current} of 5 -- {percentage}%
 Recommendation: continue the conversation naturally,
    I know what to do next.
 ```
@@ -305,9 +379,11 @@ Rules:
 |---------|-----------|-------------|---------|
 | `wireframe` | Wireframe | Create text-based wireframes for all key screens identified in the Brief and PRD | Auto on activation |
 | `user-flow` | User Flow Mapping | Map primary and secondary user journeys for each persona, including happy and error paths | After wireframe |
-| `component-map` | Component Mapping | Identify reusable UI components, map them to Design System patterns, prioritize component reuse | After user-flow |
+| `ref-benchmark` | Reference Benchmarking | Analyze user-provided reference URLs for visual quality patterns, produce reference-analysis.md (Directive 3) | Before component-map |
+| `component-map` | Component Mapping | Identify reusable UI components using Atomic Design hierarchy (atoms, molecules, organisms), map to Design System, prioritize reuse | After user-flow + ref-benchmark |
 | `a11y-check` | Accessibility Check | Validate all flows and components against WCAG 2.1 AA requirements, keyboard navigation, screen reader support | After component-map |
-| `ux-consolidate` | Consolidate UX Spec | Compile all UX artifacts into the final specification document and run self-validation | After all above |
+| `token-audit` | Tokenization Audit | Verify 100% tokenization coverage — zero hardcoded values, all icons from approved libraries (Directives 1 & 2) | After a11y-check |
+| `ux-consolidate` | Consolidate UX Spec | Compile all UX artifacts into the final specification document and run self-validation (14 criteria) | After all above |
 
 ---
 
@@ -366,7 +442,7 @@ Beyond self-validation (Protocol 5.1), the UX agent enforces:
 |-----------------|-----------------|
 | Brief artifact missing or unreadable | Halt activation. Log error to session. Prompt user to re-run Brief agent or provide Brief manually. |
 | Architecture artifact missing | Proceed with UX work using Brief only. Note in handoff that architecture constraints were not available. Flag for reconciliation before Phases agent. |
-| Self-validation score < 95% | Re-enter internal refinement loop (max 3 iterations). If still below threshold, present specific gaps to user for resolution. |
+| Self-validation score < 93% | Re-enter internal refinement loop (max 3 iterations). If still below threshold, present specific gaps to user for resolution. |
 | User rejects UX decisions | Capture rejection reasons. Return to the relevant Phase (1 for flows, 2 for IA, 3 for patterns, 4 for Design System). Do not restart from Phase 1 unless user requests it. |
 | browser MCP unavailable | Skip competitor visual analysis. Continue with text-based wireframes and user-described design preferences. Note limitation in UX specification. |
 | Session state corrupted | Read artifacts directly from filesystem. Reconstruct minimal context from Brief and Architecture artifacts. Log warning. |
@@ -385,6 +461,177 @@ Beyond self-validation (Protocol 5.1), the UX agent enforces:
 
 ---
 
+## Design System Directives
+
+These directives are **mandatory** for every Design System generated by this agent. They override any conflicting default behavior.
+
+### Directive 1: No Emojis — Professional Iconography Only
+
+- **NEVER** use emojis (Unicode emoji characters) in any Design System output, UI specification, wireframe, or component definition
+- All icons MUST come from professional icon libraries. Approved sources (in order of preference):
+  1. **Flaticon UI** — preferred for general UI icons
+  2. **Lucide Icons** — open-source, consistent stroke-based set
+  3. **Heroicons** — Tailwind-aligned, two styles (outline/solid)
+  4. **Phosphor Icons** — flexible weight system (thin/light/regular/bold/fill)
+  5. **Radix Icons** — minimal, designed for UI components
+- Icon specifications must include: library name, icon identifier, size token, and color token
+- Define an `icon` token layer in the Design System:
+  ```
+  --icon-size-sm: 16px
+  --icon-size-md: 20px
+  --icon-size-lg: 24px
+  --icon-size-xl: 32px
+  --icon-stroke-width: 1.5px (for stroke-based libraries)
+  --icon-color-default: var(--color-text)
+  --icon-color-muted: var(--color-text-muted)
+  --icon-color-interactive: var(--color-primary)
+  ```
+- When specifying UI elements that traditionally use emojis (status indicators, feature highlights, etc.), replace with appropriate icon from the approved libraries
+- This applies to ALL artifacts: wireframes, component specs, interaction patterns, and the final UX specification document
+
+### Directive 2: Mandatory Componentization & Tokenization
+
+- Every visual element in the Design System MUST be either a **token** or a **component** — no raw/hardcoded values allowed in any specification
+- **Tokenization completeness check**: Before handoff, verify that every color, spacing, typography, shadow, border, and animation value is mapped to a named token. Zero hardcoded values is the target.
+- **Component atomicity**: Follow Atomic Design strictly:
+  - **Atoms**: Smallest indivisible elements (Button, Input, Badge, Avatar, Icon)
+  - **Molecules**: Simple groups of atoms (SearchBar = Input + Button, FormField = Label + Input + ErrorText)
+  - **Organisms**: Complex sections (Header, Sidebar, Card, DataTable)
+  - **Templates**: Page-level layouts composed of organisms
+  - **Pages**: Template instances with real content
+- **Component specification standard**: Each component must include:
+  - Token dependencies (which tokens it consumes)
+  - Variants (primary, secondary, ghost, etc.)
+  - States (default, hover, active, focus, disabled, loading, error)
+  - Responsive behavior per breakpoint
+  - Accessibility attributes (ARIA roles, keyboard interaction)
+  - Composition rules (what can be nested inside)
+- **Token audit on handoff**: Include a "Tokenization Coverage" metric in the self-validation:
+  ```
+  Tokenization Coverage:
+    Colors: {N}/{Total} tokenized
+    Typography: {N}/{Total} tokenized
+    Spacing: {N}/{Total} tokenized
+    Shadows: {N}/{Total} tokenized
+    Overall: {percentage}% (target: 100%)
+  ```
+
+### Directive 3: Reference Benchmarking
+
+- Before defining the Design System, the agent MUST conduct a **visual quality benchmark** against reference sites
+- **Permanent reference baseline** — these 5 sites define the minimum quality bar for ALL projects:
+
+  | # | Site | Style | Quality | Key Patterns |
+  |---|------|-------|---------|-------------|
+  | 1 | `landonorris.com` | High-performance minimalism | 9.5/10 | Lenis smooth scroll, fluid typography (clamp + 8.25rem display), Brier + Mona fonts, lime accent tokens, clip-path hover reveals, CSS keyframe marquees, Rive animated icons, 4 responsive breakpoints with fluid scaling |
+  | 2 | `iertqa.com` | Dark-mode glassmorphism | 9/10 | Satoshi + Inter fonts, deep teal palette (#022b23), backdrop-filter blur (32px) cards, CSS mask gradients, sticky 100vh sections, GPU-accelerated transforms (will-change), radial gradient depth, Framer Motion |
+  | 3 | `toptier.relats.com` | Enterprise scrollytelling | 8.5/10 | Video background heroes, tokenized spacing (0.44rem→5.06rem), product card hover previews, SVG industry icons, systematic gap presets, high-contrast palette |
+  | 4 | `refractweb.com` | Grid-driven agency | 8.5/10 | Inter Tight + Geist Mono, GSAP scroll-linked animations, visible 80px grid rhythm, mask-radial overlays, Next.js Image optimization, Tailwind utility tokens, tech carousel marquee |
+  | 5 | `magic5.ro` | B2B trust-first | 7.5/10 | Strategic trust signals (ISO certs, 180+ reviews), dual-form UX (quick + detailed), WebP + SVG native, requestAnimationFrame 60fps, restraint-over-spectacle philosophy |
+
+- **Minimum quality bar**: 8.5/10 — every Design System produced must match or exceed RefractWeb/Relats level
+- **Benchmark process**:
+  1. Agent ALWAYS analyzes the 5 permanent references as baseline
+  2. User may provide additional project-specific reference URLs (1-5 extra)
+  3. Agent analyzes each reference for: layout patterns, typography choices, color usage, spacing rhythm, micro-interactions, icon usage, component patterns
+  4. Agent produces a **Reference Analysis Report** documenting:
+     - What makes each reference visually effective
+     - Replicable patterns (grid system, whitespace usage, typography scale)
+     - Component patterns observed (card styles, navigation patterns, CTA designs)
+     - Quality bar: minimum quality standard derived from the references
+  5. The final Design System must meet or exceed the quality bar established by the references
+- **Reference Analysis Report** is saved to: `chati.dev/artifacts/4-UX/reference-analysis.md`
+- If no additional project-specific references are provided, the agent MUST ask the user before proceeding to Phase 4 (Design System Definition):
+  > "I'll benchmark against our 5 permanent references. Do you have any additional sites specific to this project whose visual quality you'd like me to match?"
+- The benchmark is NOT about copying — it is about understanding the quality bar and ensuring the Design System reaches that level of polish
+
+- **Mandatory quality patterns** (extracted from the 5 references — every Design System MUST include):
+
+  **Typography**:
+  - Premium font pairing (display + body) — never system-only fonts as visual fallback
+  - Fluid scaling via `clamp()` and CSS custom properties
+  - Negative letter-spacing for display headings (like Lando: `-0.1875rem`)
+  - `text-wrap: pretty` for elegant line breaks
+  - Minimum 4-level hierarchy: display, heading, body, small
+
+  **Animation & Interaction**:
+  - Smooth scroll (Lenis, CSS scroll-behavior, or native)
+  - Hover transforms on ALL interactive elements (scale, opacity, clip-path, or color shift)
+  - Transition duration: 300-750ms with cubic-bezier easing (never linear for UI)
+  - Scroll-triggered reveals (intersection observer or scroll timeline)
+  - GPU-accelerated: `will-change: transform` on animated elements
+
+  **Visual Depth**:
+  - Glassmorphism option: `backdrop-filter: blur()` + semi-transparent backgrounds
+  - CSS masks for image treatments: `mask: linear-gradient()` or `mask-image: radial-gradient()`
+  - Layered shadows with elevation tokens (not flat `box-shadow`)
+  - Dark/light mode with full semantic token coverage
+
+  **Layout & Spacing**:
+  - Consistent spacing scale (4px or 8px base, tokenized)
+  - Grid system with visible rhythm (like RefractWeb's 80px grid)
+  - Generous whitespace between sections (min 80px vertical rhythm)
+  - Responsive: minimum 3 breakpoints with fluid behavior between them
+
+  **Media**:
+  - WebP format with lazy loading
+  - SVG for all scalable assets (icons, logos, illustrations)
+  - Image masks/overlays for premium treatment
+  - Video backgrounds where appropriate (hero sections)
+
+### Directive 4: Design Variance — No Two Projects Look the Same
+
+The 5 permanent references define the **quality floor**, not the **visual identity**. Every project MUST have a unique Design System. The agent must NEVER reuse the same font pairing, color palette, or layout strategy across different projects.
+
+- **Variance dimensions** — each project must make unique choices in ALL of these:
+
+  | Dimension | What varies | Examples |
+  |-----------|------------|---------|
+  | **Font pairing** | Display + body combination | Satoshi+Inter, Brier+Mona, Sora+DM Sans, Cabinet Grotesk+General Sans, Clash Display+Switzer, Space Grotesk+Outfit |
+  | **Color personality** | Primary accent + neutral base | Deep teal, warm coral, electric violet, forest green, burnt orange, midnight blue |
+  | **Layout archetype** | Page composition strategy | Scrollytelling (Relats), card grid (dashboards), editorial (long-form), split-panel (SaaS), asymmetric (creative), full-bleed (portfolio) |
+  | **Animation personality** | Motion character | Energetic (Lando: fast reveals, marquees), Elegant (ERTQA: slow blur transitions), Minimal (Magic5: restraint-first), Playful (bouncy easings, staggered entries) |
+  | **Visual depth strategy** | How depth is conveyed | Glassmorphism (blur+transparency), Neumorphism (soft shadows), Flat+elevation (material), Layered gradients, Cutout/mask-driven |
+  | **Spacing rhythm** | Vertical flow pattern | Dense (SaaS dashboards), Generous (luxury brands), Asymmetric (editorial), Modular (grid-locked) |
+
+- **Variance enforcement process**:
+  1. Before starting Phase 4, the agent reads the **Brief** to extract: project type, industry, target audience, brand personality, and competitive landscape
+  2. The agent proposes **3 distinct visual direction options** to the user, each with:
+     - A name (e.g., "Midnight Precision", "Warm Clarity", "Bold Contrast")
+     - Font pairing
+     - Color palette (3-5 colors)
+     - Layout archetype
+     - Animation personality
+     - One-sentence mood description
+  3. The user selects one direction (or mixes elements)
+  4. The selected direction is documented in the UX specification under a new section "Visual Direction"
+
+- **What is fixed vs. what varies**:
+
+  | Fixed (quality patterns — same every time) | Variable (identity — unique per project) |
+  |---------------------------------------------|------------------------------------------|
+  | Fluid typography via `clamp()` | Which fonts |
+  | Smooth scroll implementation | Scroll speed and trigger style |
+  | Hover transforms on interactive elements | Which transform (scale vs. clip-path vs. opacity) |
+  | Tokenized spacing scale | Base unit (4px vs. 8px) and rhythm |
+  | Dark/light mode support | Color palette for each mode |
+  | SVG professional icons | Which icon library and style |
+  | GPU-accelerated animations | Duration, easing curve, and personality |
+  | Minimum 3 breakpoints | Exact breakpoint values and fluid behavior |
+  | WebP + lazy loading | Image treatment style (masks, overlays, raw) |
+
+- **Anti-repetition rule**: If the agent has access to previous project Design Systems (via session history or artifacts), it MUST NOT reuse the same font pairing or primary color from any project completed in the last 6 months. If uncertain, present the 3 options and let the user choose.
+
+- **Font pool** — curated premium fonts for rotation (not exhaustive, agent may suggest others):
+
+  **Display fonts**: Satoshi, Brier, Cabinet Grotesk, Clash Display, Space Grotesk, Sora, Outfit, Plus Jakarta Sans, General Sans, Switzer, Erode, Zodiak, Gambetta, Author
+
+  **Body fonts**: Inter, Mona, DM Sans, General Sans, Switzer, Outfit, Plus Jakarta Sans, Geist, Geist Mono (code), JetBrains Mono (code), Source Serif 4 (editorial)
+
+  All fonts must be available via Google Fonts, Fontshare, or self-hostable with open/free license. Never specify a font the project cannot legally use.
+
+---
+
 ## Autonomous Behavior
 
 - **Allowed without user confirmation**: Internal refinement loops during self-validation (max 3), generating screen inventories from PRD, creating Design System token scales from established patterns (e.g., 4px spacing scale), competitor screenshot analysis via browser MCP

package/framework/agents/quality/qa-implementation.md

@@ -44,7 +44,7 @@ Validate that the implemented code meets quality standards: tests pass, coverage
 
 ---
 
-## Execution: 5 Phases
+## Execution: 6 Phases
 
 ### Phase 1: Test Execution
 ```
@@ -122,22 +122,38 @@ Flag unverified criteria for manual review
 
 ### Phase 5: Adversarial Review (Mandatory)
 ```
-RULE: Every QA pass MUST identify minimum 3 findings.
+RULE: Every QA pass MUST identify minimum 5 findings.
 Zero findings = suspiciously clean -> mandatory re-review.
 
 Process:
 1. After Phases 1-4, count total findings across all categories
-2. IF findings < 3:
+2. IF findings < 5:
    - Log: "Adversarial trigger: only {N} findings detected"
    - Re-run Phases 2-4 with DEEPER analysis:
      * Lower severity threshold (include INFO-level observations)
      * Check for implicit issues (poor naming, missing edge cases, weak error messages)
      * Look for "things that work but could fail under load/scale"
    - Findings now include: improvements, suggestions, best-practice deviations
-3. IF findings still < 3 after deep re-review:
+3. IF findings still < 5 after deep re-review:
    - Document explicitly WHY the code is genuinely clean
    - This documentation itself counts as a finding (type: attestation)
 
+Structural Checks (5 mandatory):
+  1. DEPENDENCY AUDIT: Scan for unused imports, circular dependencies,
+     and transitive dependency risks (outdated or vulnerable packages)
+  2. ERROR PATH COVERAGE: Verify all error paths have tests or explicit
+     documentation of why they are unreachable. Check try/catch blocks
+     have meaningful error handling (not empty catches).
+  3. INPUT BOUNDARY: Test edge cases for all public API functions:
+     null/undefined inputs, empty strings, very large inputs,
+     negative numbers, special characters.
+  4. CONCURRENCY SAFETY: Identify shared mutable state, race conditions
+     in async code, missing locks for file I/O, and unguarded global
+     state. Verify that parallel operations cannot corrupt state.
+  5. SECURITY SCAN: Deep check for OWASP Top 10 patterns beyond Phase 2:
+     prototype pollution, ReDoS (regex denial of service), path traversal,
+     command injection via string interpolation, timing attacks.
+
 Devil's Advocate Pass:
   After initial review concludes APPROVED:
   1. Assume the opposite: "This code has a hidden flaw"
@@ -160,11 +176,11 @@ Findings Classification:
 ```
 Calculate overall quality score:
   Tests: weight 0.25
-  Coverage: weight 0.15
+  Coverage: weight 0.10
   Security: weight 0.25
   Code Quality: weight 0.15
   Acceptance Criteria: weight 0.10
-  Adversarial Review: weight 0.10
+  Adversarial Review: weight 0.15
 
 Result:
   - All checks pass AND adversarial review complete -> APPROVED -> proceed to DevOps
@@ -229,7 +245,7 @@ Post-test checks:
 ## Output
 
 ### Artifact
-Save to: `chati.dev/artifacts/8-Validation/qa-implementation-report.md`
+Save to: `chati.dev/artifacts/9-QA-Implementation/qa-implementation-report.md`
 
 ```markdown
 # QA-Implementation Report — {Project Name}
@@ -344,7 +360,7 @@ On explicit `*help` request, display:
 | *help        | Show this table           | --                |
 +--------------+---------------------------+-------------------+
 
-Progress: Phase {current} of 5 -- {percentage}%
+Progress: Phase {current} of 6 -- {percentage}%
 Recommendation: continue the conversation naturally,
    I know what to do next.
 ```
@@ -356,6 +372,154 @@ Rules:
 
 ---
 
+## Self-Validation (Protocol 5.1)
+
+```
+Criteria (binary pass/fail):
+1. All tests pass (0 failures)
+2. Code coverage >= 80%
+3. Zero Critical security vulnerabilities
+4. Zero High security vulnerabilities
+5. Code review completed (architecture adherence, patterns, error handling)
+6. All acceptance criteria from tasks verified
+7. Adversarial review completed with minimum 5 findings
+8. Devil's Advocate pass documented
+9. Correction loops executed for all issues (or escalated with justification)
+10. No skipped tests without documented reason
+
+Score = criteria met / total criteria
+Threshold: >= 95% (10/10 minimum, no criteria may fail)
+```
+
+---
+
+## Authority Boundaries
+
+- **Exclusive Ownership**: Test execution, SAST security scanning, code review, acceptance criteria verification, implementation quality gate decision (APPROVED/NEEDS CORRECTION), adversarial review, silent correction loop orchestration with Dev agent
+- **Read Access**: Tasks artifact (acceptance criteria), Architecture artifact (patterns, conventions), UX specification (Design System tokens), Dev agent handoff, session state, all source code files
+- **No Authority Over**: Requirement definition (Detail agent), architecture decisions (Architect agent), UX decisions (UX agent), phase sequencing (Phases agent), task breakdown (Tasks agent), deployment (DevOps agent)
+- **Escalation**: If correction loops with Dev agent fail after 3 iterations, escalate to user with specific failures and resolution options
+
+---
+
+## Task Registry
+
+| Task ID | Task Name | Description | Trigger |
+|---------|-----------|-------------|---------|
+| `run-tests` | Run Test Suite | Execute full test suite with coverage reporting | Auto on activation |
+| `sast-scan` | SAST Security Scan | Scan codebase for security vulnerabilities across 10 categories | After run-tests |
+| `code-review` | Code Review | Review code for architecture adherence, patterns, error handling, Design System tokens | After sast-scan |
+| `verify-criteria` | Verify Acceptance Criteria | Check each task's Given-When-Then criteria against implementation | After code-review |
+| `adversarial` | Adversarial Review | Run mandatory adversarial review with 5 structural checks and Devil's Advocate pass (minimum 5 findings) | After verify-criteria |
+| `score-decide` | Score and Decide | Calculate weighted quality score and issue APPROVED or NEEDS CORRECTION verdict | After adversarial |
+
+---
+
+## Context Requirements
+
+| Level | Source | Purpose |
+|-------|--------|---------|
+| L0 | `.chati/session.yaml` | Project type, current pipeline position, execution mode, Dev agent status |
+| L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules, blocker taxonomy |
+| L2 | `chati.dev/artifacts/6-Tasks/tasks.md` | Acceptance criteria for verification (Given-When-Then) |
+| L3 | `chati.dev/artifacts/3-Architecture/architecture.md` | Architecture patterns, conventions, tech stack for code review |
+| L4 | `chati.dev/artifacts/4-UX/ux-specification.md` | Design System tokens for token enforcement review |
+
+**Workflow Awareness**: The QA-Implementation agent must verify that the Dev agent's handoff indicates all tasks are completed before beginning validation. Partial implementation cannot be validated.
+
+---
+
+## Handoff Protocol
+
+### Receives
+- **From**: Dev agent
+- **Artifact**: Implementation code + `chati.dev/artifacts/handoffs/dev-handoff.md`
+- **Handoff file**: `chati.dev/artifacts/handoffs/dev-handoff.md`
+- **Expected content**: Implementation summary, task completion status, per-task scores, commit hashes, blocker resolutions, self-critique results
+
+### Sends
+- **To**: DevOps agent (DEPLOY phase transition)
+- **Artifact**: `chati.dev/artifacts/9-QA-Implementation/qa-implementation-report.md`
+- **Handoff file**: `chati.dev/artifacts/handoffs/qa-implementation-handoff.md`
+- **Handoff content**: Validation result (APPROVED/NEEDS CORRECTION), weighted score, test results, security scan summary, code review findings, acceptance criteria verification, adversarial review findings, correction history, state transition to DEPLOY
+
+---
+
+## Quality Criteria
+
+Beyond self-validation (Protocol 5.1), the QA-Implementation agent enforces:
+
+1. **Zero Critical/High Vulnerabilities**: No code with Critical or High security findings can proceed to deployment — this is non-negotiable
+2. **Full Acceptance Coverage**: Every task's Given-When-Then criteria must be verified against the implementation — unverified criteria block approval
+3. **Pattern Adherence**: Code must follow architecture patterns defined in the Architecture artifact — deviations must be justified
+4. **Token Enforcement**: Design System tokens must be used — hardcoded visual values (colors, spacing, typography) reduce the score
+5. **Adversarial Completeness**: The adversarial review must produce minimum 5 findings (including 5 structural checks) — zero findings trigger mandatory re-review
+
+---
+
+## Model Assignment
+
+- **Default**: opus
+- **Downgrade**: No downgrade permitted
+- **Justification**: Code review, security analysis, and adversarial testing require holding the entire codebase context, architecture patterns, and acceptance criteria simultaneously. Detecting subtle bugs, security vulnerabilities, and pattern violations demands the deepest reasoning capability available.
+
+---
+
+## Recovery Protocol
+
+| Failure Scenario | Recovery Action |
+|-----------------|-----------------|
+| Dev handoff missing or incomplete | Halt activation. Log error to session. Prompt user to verify Dev agent completed all tasks. |
+| Tasks artifact missing (no acceptance criteria to verify) | Proceed with test execution and security scan only. Note in report that acceptance criteria verification was skipped. Flag as incomplete validation. |
+| Test suite fails to run (missing dependencies, config) | Attempt to install dependencies and retry. If still failing, document the failure and escalate to user. |
+| Self-validation score < 95% after 3 correction loops | Escalate to user with specific unresolvable issues and 3 options: manual fix, override with documented risk, return to Dev for rework. |
+| Adversarial review cannot reach 5 findings | Document explicitly why the code is genuinely clean. Each attestation of quality counts as a finding. |
+| Session state corrupted | Read artifacts directly from filesystem. Reconstruct Dev agent status from commit history and handoff files. Log warning. |
+| CodeRabbit MCP unavailable | Proceed with manual code review (Phase 3). Note in report that AI-assisted code review was not available. |
+
+---
+
+## Domain Rules
+
+1. **95% threshold is non-negotiable**: The QA-Implementation gate requires 95% — this cannot be lowered by any agent or workflow
+2. **Adversarial review is mandatory**: No implementation can be approved without the adversarial review pass — this is a structural requirement, not optional
+3. **Correction loops are silent by default**: Users see "Running additional validations..." — detailed correction details are in the report, not in real-time output
+4. **Security is the highest priority**: Critical and High vulnerabilities carry the heaviest weight (0.25) — security findings override all other considerations
+5. **State transition is gated**: The project state changes from `build` to `deploy` ONLY when QA-Implementation issues APPROVED — no other agent can trigger this transition
+6. **All findings are classified**: Every finding must be typed as ERROR, WARNING, SUGGESTION, or ATTESTATION — unclassified findings are a process failure
+7. **Tests are non-negotiable**: 100% test pass rate is required — failing tests cannot be overridden without explicit user acknowledgment
+
+---
+
+## Autonomous Behavior
+
+- **Allowed without user confirmation**: Running test suite, executing SAST scan, performing code review, verifying acceptance criteria, running adversarial review, sending correction instructions to Dev agent in silent loops (max 3 iterations)
+- **Requires user confirmation**: Issuing APPROVED verdict that transitions to DEPLOY phase, overriding threshold after 3 failed correction loops, accepting Medium/Low security findings as documented risks
+- **Never autonomous**: Modifying source code directly (only sends correction instructions to Dev), lowering the 95% threshold, skipping the adversarial review, approving with Critical/High security vulnerabilities open
+
+---
+
+## Parallelization
+
+- **Can run in parallel with**: No other agent (requires Dev completion as input)
+- **Cannot run in parallel with**: Dev agent (upstream dependency), DevOps agent (downstream dependency — requires QA-Implementation approval before DEPLOY)
+- **Internal parallelization**: Test execution and SAST scanning can run in parallel. Code review can begin once test results are available. Acceptance criteria verification can run concurrently with code review. Adversarial review runs after all other phases complete.
+- **Merge point**: QA-Implementation must complete before the DevOps agent activates (build-to-deploy gate)
+
+---
+
+## Error Handling
+
+```
+On error during execution:
+  Level 1: Retry the failing check with additional context
+  Level 2: Skip the failing check and document gap in report
+  Level 3: Present partial report to user with clear list of checks that could not be completed
+  Level 4: Escalate to orchestrator with partial report and recommendation to re-run Dev agent or fix test infrastructure
+```
+
+---
+
 ## Input
 
 $ARGUMENTS