maestro-flow 0.5.31 → 0.5.33

package/.agy/skills/team-ux-improve/specs/team-config.json

@@ -0,0 +1,181 @@
+{
+  "version": "5.0.0",
+  "team_name": "ux-improve",
+  "team_display_name": "UX Improve",
+  "team_purpose": "Systematically discover and fix UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems",
+  "skill_name": "team-ux-improve",
+  "skill_path": "~  or <project>/.claude/skills/team-ux-improve/",
+  "worker_agent": "team-worker",
+  "pipeline_type": "Standard",
+  "completion_action": "interactive",
+  "has_inline_discuss": false,
+  "has_shared_explore": true,
+  "roles": [
+    {
+      "name": "coordinator",
+      "display_name": "Coordinator",
+      "type": "orchestrator",
+      "responsibility_type": "orchestration",
+      "role_spec": "roles/coordinator/role.md",
+      "task_prefix": null,
+      "inner_loop": false,
+      "allowed_tools": ["Agent", "AskUserQuestion", "Read", "Write", "Bash", "Glob", "Grep", "TaskList", "TaskGet", "TaskUpdate", "TaskCreate", "TeamCreate", "TeamDelete", "SendMessage", "mcp__maestro__team_msg"],
+      "description": "Orchestrates the UX improvement pipeline, spawns workers, monitors progress"
+    },
+    {
+      "name": "scanner",
+      "display_name": "UI Scanner",
+      "type": "worker",
+      "responsibility_type": "read_only_analysis",
+      "role_spec": "roles/scanner/role.md",
+      "task_prefix": "SCAN",
+      "inner_loop": false,
+      "allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__maestro__read_file", "mcp__maestro__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
+      "description": "Scans UI components to identify interaction issues (unresponsive buttons, missing feedback, state not refreshing)",
+      "frontmatter": {
+        "prefix": "SCAN",
+        "inner_loop": false,
+        "message_types": {
+          "success": "scan_complete",
+          "error": "error"
+        }
+      }
+    },
+    {
+      "name": "diagnoser",
+      "display_name": "State Diagnoser",
+      "type": "worker",
+      "responsibility_type": "orchestration",
+      "role_spec": "roles/diagnoser/role.md",
+      "task_prefix": "DIAG",
+      "inner_loop": false,
+      "allowed_tools": ["Read", "Grep", "Bash", "mcp__maestro__read_file", "mcp__maestro__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
+      "description": "Diagnoses root causes of UI issues: state management problems, event binding failures, async handling errors",
+      "frontmatter": {
+        "prefix": "DIAG",
+        "inner_loop": false,
+        "message_types": {
+          "success": "diag_complete",
+          "error": "error"
+        }
+      }
+    },
+    {
+      "name": "designer",
+      "display_name": "UX Designer",
+      "type": "worker",
+      "responsibility_type": "orchestration",
+      "role_spec": "roles/designer/role.md",
+      "task_prefix": "DESIGN",
+      "inner_loop": false,
+      "allowed_tools": ["Read", "Write", "Bash", "mcp__maestro__read_file", "mcp__maestro__write_file", "mcp__maestro__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
+      "description": "Designs feedback mechanisms (loading/error/success states) and state management patterns (React/Vue reactive updates)",
+      "frontmatter": {
+        "prefix": "DESIGN",
+        "inner_loop": false,
+        "message_types": {
+          "success": "design_complete",
+          "error": "error"
+        }
+      }
+    },
+    {
+      "name": "implementer",
+      "display_name": "Code Implementer",
+      "type": "worker",
+      "responsibility_type": "code_generation",
+      "role_spec": "roles/implementer/role.md",
+      "task_prefix": "IMPL",
+      "inner_loop": true,
+      "allowed_tools": ["Read", "Write", "Edit", "Bash", "mcp__maestro__read_file", "mcp__maestro__write_file", "mcp__maestro__edit_file", "mcp__maestro__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
+      "description": "Generates executable fix code with proper state management, event handling, and UI feedback bindings",
+      "frontmatter": {
+        "prefix": "IMPL",
+        "inner_loop": true,
+        "message_types": {
+          "success": "impl_complete",
+          "error": "error"
+        }
+      }
+    },
+    {
+      "name": "tester",
+      "display_name": "Test Engineer",
+      "type": "worker",
+      "responsibility_type": "validation",
+      "role_spec": "roles/tester/role.md",
+      "task_prefix": "TEST",
+      "inner_loop": false,
+      "allowed_tools": ["Read", "Write", "Bash", "mcp__maestro__read_file", "mcp__maestro__write_file", "mcp__maestro__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
+      "description": "Generates test cases to verify fixes (loading states, error handling, state updates)",
+      "frontmatter": {
+        "prefix": "TEST",
+        "inner_loop": false,
+        "message_types": {
+          "success": "test_complete",
+          "error": "error",
+          "fix": "fix_required"
+        }
+      }
+    }
+  ],
+  "utility_members": [
+    {
+      "name": "explorer",
+      "display_name": "Codebase Explorer",
+      "role_spec": "roles/explorer/role.md",
+      "callable_by": "coordinator",
+      "purpose": "Explore codebase for UI component patterns, state management conventions, and framework-specific patterns",
+      "allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__maestro__read_file", "mcp__maestro__team_msg"],
+      "frontmatter": {
+        "prefix": "EXPLORE",
+        "inner_loop": false,
+        "message_types": {
+          "success": "explore_complete",
+          "error": "error"
+        }
+      }
+    }
+  ],
+  "pipeline": {
+    "stages": [
+      {
+        "stage_id": 1,
+        "stage_name": "UI Scanning",
+        "roles": ["scanner"],
+        "dependencies": [],
+        "description": "Scan UI components for interaction issues"
+      },
+      {
+        "stage_id": 2,
+        "stage_name": "Root Cause Diagnosis",
+        "roles": ["diagnoser"],
+        "dependencies": ["scanner"],
+        "description": "Diagnose root causes of identified issues"
+      },
+      {
+        "stage_id": 3,
+        "stage_name": "Solution Design",
+        "roles": ["designer"],
+        "dependencies": ["diagnoser"],
+        "description": "Design feedback mechanisms and state management solutions"
+      },
+      {
+        "stage_id": 4,
+        "stage_name": "Code Implementation",
+        "roles": ["implementer"],
+        "dependencies": ["designer"],
+        "description": "Generate fix code with proper state handling"
+      },
+      {
+        "stage_id": 5,
+        "stage_name": "Test Validation",
+        "roles": ["tester"],
+        "dependencies": ["implementer"],
+        "description": "Generate and run tests to verify fixes"
+      }
+    ],
+    "diagram": "scanner (SCAN) → diagnoser (DIAG) → designer (DESIGN) → implementer (IMPL) → tester (TEST)",
+    "fast_advance_eligible": ["scanner→diagnoser", "diagnoser→designer", "designer→implementer"]
+  }
+}

package/.agy/skills/team-ux-improve/wisdom/anti-patterns/common-ux-pitfalls.md

@@ -0,0 +1,49 @@
+# Common UX Pitfalls
+
+## Interaction Issues
+- Buttons without loading states during async operations
+- Missing error handling with user feedback
+- State changes without visual updates
+- Double-click vulnerabilities (missing debounce)
+- No disabled state during processing
+- Silent failures without user notification
+- Generic error messages without actionable guidance
+- Missing confirmation for destructive actions
+- No empty state placeholder for data lists
+- Input without validation rules or inline feedback
+
+## State Management Issues
+- Stale data after mutations (direct array/object mutation)
+- Race conditions in async operations (no cancellation)
+- Missing rollback for failed optimistic updates
+- Stale closure capturing old state value
+- Missing loading/error/success state tracking
+
+## Visual Design Anti-Patterns (AI Slop)
+- AI Color Palette: cyan-on-dark, purple gradients (zero design intent)
+- Gradient text: background-clip: text as emphasis crutch
+- Glassmorphism everywhere: backdrop-filter as default aesthetic
+- All Buttons Primary: no visual hierarchy, every button filled
+- Pure Black/White: #000/#fff without tint (harsh, sterile)
+- Generic fonts: Inter, Roboto as defaults (forgettable)
+- Identical card grids: all items same visual weight
+- Nested cards: cards inside cards creating noise
+- Same spacing everywhere: no rhythm variation
+- Bounce/elastic easing: dated animation feel
+- Everything centered: including body text
+
+## Motion Issues
+- Layout animations (width/height/margin/padding triggers)
+- No reduced-motion query (@media prefers-reduced-motion)
+- CSS will-change set permanently (GPU waste)
+- ease/linear as default easing (unnatural)
+- Stagger exceeding 500ms total
+
+## Accessibility Issues
+- outline: none without :focus-visible replacement
+- Missing :focus-visible (using bare :focus)
+- Color-only state indication
+- Touch targets < 44px
+- No skip links
+- Placeholder used as label
+- Missing aria-describedby for error messages

package/.agy/skills/team-ux-improve/wisdom/patterns/state-management.md

@@ -0,0 +1,34 @@
+# State Management Patterns
+
+## Reactive Update Rules
+- NEVER mutate arrays/objects directly
+- React: use spread operator, filter/map for new references
+- Vue: use ref() for primitives, reactive() for objects, computed() for derived
+- Always trigger re-render through proper state API
+
+## Async State Pattern
+```
+const [data, setData] = useState(null);
+const [loading, setLoading] = useState(false);
+const [error, setError] = useState(null);
+
+// Always: loading -> success/error -> cleanup
+```
+
+## Race Condition Prevention
+- AbortController for fetch cancellation
+- Debounce for search/filter inputs (250-500ms)
+- Latest-wins pattern for concurrent requests
+- Disable trigger during processing
+
+## Optimistic Updates
+- Update UI immediately
+- Track pending state
+- Rollback on failure with error notification
+- Never lose user data silently
+
+## Form State
+- Controlled inputs (React) / v-model (Vue)
+- Validation on blur + on submit
+- Error clearing on re-input
+- Dirty tracking for unsaved changes warning

package/.agy/skills/team-ux-improve/wisdom/patterns/ui-feedback.md

@@ -0,0 +1,40 @@
+# UI Feedback Patterns
+
+## Loading States
+- Button: set disabled + aria-busy="true", show spinner, restore on complete
+- Page: skeleton screens (prefer over spinners for content areas)
+- Inline: progress indicator for multi-step operations
+- Duration: show loading after 200ms delay (avoid flash for fast operations)
+
+## Error States
+- Form: inline validation with aria-invalid + aria-describedby
+- API: toast/snackbar for non-blocking, inline for blocking errors
+- Error message: specific, actionable (not "Something went wrong")
+- Visual: red border on input, error icon, error text below
+
+## Success States
+- Form submit: success message + next action guidance
+- CRUD: optimistic update with subtle confirmation
+- Duration: success message visible 3-5 seconds
+
+## Empty States
+- Data list: illustration + message + primary action
+- Search: "No results" + suggestions
+- First use: onboarding guidance
+
+## Focus Feedback
+- :focus-visible only (not bare :focus)
+- Ring: 2px solid accent, offset 2px
+- Contrast: 3:1 against adjacent colors
+- Custom for dark backgrounds: lighter ring color
+
+## Hover Feedback
+- Wrap in @media(hover:hover) for touch safety
+- Subtle: background opacity change or slight color shift
+- Duration: 100-150ms transition
+- Cursor: pointer for clickable, not-allowed for disabled
+
+## Active Feedback
+- Scale: transform: scale(0.97) for physical feel
+- Or: darker background shade
+- Duration: instant (< 50ms feel)

package/.agy/skills/team-ux-improve/wisdom/principles/general-ux.md

@@ -0,0 +1,43 @@
+# General UX Principles
+
+## Feedback & Responsiveness
+- Every user action must have immediate visual feedback (< 100ms perceived)
+- Loading states for operations > 200ms: use skeleton/spinner, set aria-busy="true"
+- Success/error states clearly communicated with both visual and ARIA cues
+- Feedback duration: 100-150ms for hover/active/focus transitions
+- State change transitions: 200-300ms
+- Layout changes: 300-500ms
+
+## Interaction States (8 Required)
+Every interactive element must define all 8 states:
+1. Default — base appearance
+2. Hover — subtle bg/opacity change, wrap in @media(hover:hover)
+3. Focus — :focus-visible with 2px solid accent, offset 2px, 3:1 contrast ratio
+4. Active — scale(0.97) or darker background
+5. Disabled — opacity 0.5, cursor: not-allowed, aria-disabled="true"
+6. Loading — spinner/skeleton, disable interaction, aria-busy="true"
+7. Error — red border, error message below, aria-invalid="true"
+8. Success — green check, success message
+
+## State Management
+- UI state must reflect underlying data state immediately
+- Optimistic updates must have rollback mechanisms
+- State changes must be atomic and predictable
+- No direct array/object mutation (use spread/filter/map for reactive frameworks)
+- Race conditions: use request cancellation or debounce
+
+## Visual Design Quality
+- Color: OKLCH-based, tinted neutrals (never pure gray/black/white), 60-30-10 rule
+- Typography: distinctive fonts (not Inter/Roboto), modular scale, fluid clamp()
+- Spacing: 4pt base scale with varied rhythm (tight/comfortable/generous)
+- Motion: transform+opacity only, ease-out-quart easing, reduced-motion query required
+- Hierarchy: squint test, single primary CTA per viewport
+
+## Accessibility
+- All interactive elements keyboard accessible (tab + enter/space)
+- Color must NOT be the only indicator of state
+- Focus states must use :focus-visible (not bare :focus)
+- Focus ring: 3:1 contrast against adjacent colors
+- Touch targets: minimum 44x44px, 8px gap between adjacent
+- Visible labels on all form inputs (placeholder is not a label)
+- Skip links for keyboard navigation

package/.agy/skills/team-visual-a11y/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: team-visual-a11y
+description: Unified team skill for visual accessibility QA. OKLCH color contrast, typography readability, focus management, WCAG AA/AAA audit at rendered level. Uses team-worker agent architecture. Triggers on "team visual a11y", "accessibility audit", "visual a11y".
+agy-subagents:
+  - team-worker
+---
+
+## Sub-Agent Registration (Antigravity)
+
+Before any `invoke_subagent` call below, register each sub-agent type once per session by reading the system_prompt from `<agy-agents-dir>/<name>.md` and passing it to `define_subagent`. The `<agy-agents-dir>` is:
+- global install: `~/.gemini/antigravity-cli/agents/`
+- workspace install: `<project>/.agents/agents/`
+
+- `define_subagent(name="team-worker", description="<from agents/team-worker.md frontmatter>", system_prompt=<contents of agents/team-worker.md body>, enable_write_tools=true, enable_mcp_tools=true, enable_subagent_tools=false)`
+
+**ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
+
+---
+
+# Team Visual Accessibility
+
+Deep visual accessibility QA: OKLCH-based perceptual color contrast, typography readability at all viewports, focus-visible completeness, WCAG AA/AAA audit at rendered level. Built on **team-worker agent architecture** -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from `roles/<role>/role.md`.
+
+## Architecture
+
+```
+view_file(AbsolutePath="<agy-skills-dir>/team-visual-a11y/SKILL.md") + execute inline (args: "task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze -> dispatch -> spawn workers -> STOP
+                                    |
+                    +-------+-------+-------+
+                    v       v       v       |
+           [3 auditors spawn in PARALLEL]   |
+        color-auditor  typo-auditor  focus-auditor
+                    |       |       |
+                    +---+---+---+---+
+                        v
+               remediation-planner
+                        |
+                        v
+               fix-implementer (inner_loop)
+                        |
+                        v
+               [re-audit: color + focus in PARALLEL]
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | -- | -- |
+| color-auditor | [roles/color-auditor/role.md](roles/color-auditor/role.md) | COLOR-* | false |
+| typo-auditor | [roles/typo-auditor/role.md](roles/typo-auditor/role.md) | TYPO-* | false |
+| focus-auditor | [roles/focus-auditor/role.md](roles/focus-auditor/role.md) | FOCUS-* | false |
+| remediation-planner | [roles/remediation-planner/role.md](roles/remediation-planner/role.md) | REMED-* | false |
+| fix-implementer | [roles/fix-implementer/role.md](roles/fix-implementer/role.md) | FIX-* | true |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (ui)**: `maestro spec load --category ui` — load ui constraints as shared context
+3. **Wiki knowledge**: `maestro search "accessibility WCAG contrast" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `VA`
+- **Session path**: `.workflow/.team/VA-<slug>-<date>/`
+- **team_name**: `visual-a11y`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
+- **Max GC rounds**: 2
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+invoke_subagent([{ TypeName: "team-worker", Role: "<role>", Prompt: "<Prompt>", Workspace: "inherit" }])
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) -- Pipeline definitions and task registry
+- [specs/oklch-standards.md](specs/oklch-standards.md) -- OKLCH color accessibility rules
+- [specs/wcag-matrix.md](specs/wcag-matrix.md) -- WCAG 2.1 criteria matrix
+- [specs/typography-scale.md](specs/typography-scale.md) -- Typography accessibility rules
+- [specs/focus-patterns.md](specs/focus-patterns.md) -- Focus management patterns
+
+## Session Directory
+
+```
+.workflow/.team/VA-<slug>-<date>/
++-- .msg/
+|   +-- messages.jsonl         # Team message bus
+|   +-- meta.json              # Pipeline config + GC state
++-- audits/
+|   +-- color/                 # Color auditor output
+|   |   +-- color-audit-001.md
+|   +-- typography/            # Typography auditor output
+|   |   +-- typo-audit-001.md
+|   +-- focus/                 # Focus auditor output
+|       +-- focus-audit-001.md
++-- remediation/               # Remediation planner output
+|   +-- remediation-plan.md
++-- fixes/                     # Fix implementer output
+|   +-- fix-summary-001.md
++-- re-audit/                  # Re-audit output (GC loop)
+|   +-- color-audit-002.md
+|   +-- focus-audit-002.md
++-- evidence/                  # Screenshots, traces
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Session corruption | Attempt recovery, fallback to manual |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| GC loop stuck > 2 rounds | Escalate to user: accept / retry / terminate |
+| Chrome DevTools unavailable | Degrade to static analysis only |

package/.agy/skills/team-visual-a11y/roles/color-auditor/role.md

@@ -0,0 +1,177 @@
+---
+role: color-auditor
+prefix: COLOR
+inner_loop: false
+---
+
+# Color Accessibility Auditor
+
+OKLCH-based perceptual color contrast analysis. Extract all color values, calculate WCAG 2.1 and APCA contrast ratios, assess OKLCH lightness/chroma ranges, simulate color blindness conditions. Produce detailed color audit report with pass/fail per combination.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Target (URL or file paths) | From task description CONTEXT | Yes |
+| WCAG level (AA/AAA) | From task description CONTEXT | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+| Previous audit (re-audit) | <session>/audits/color/color-audit-*.md | Only for COLOR-002+ |
+
+1. Extract session path, target, and WCAG level from task description
+2. Determine audit type from subject: COLOR-001 -> initial audit, COLOR-002+ -> re-audit (verification)
+3. Identify target:
+   - URL -> use Chrome DevTools for rendered colors (navigate_page, evaluate_script)
+   - File paths -> read CSS/SCSS/Tailwind config files directly
+   - Full site -> enumerate stylesheets from HTML entry points
+4. For re-audit: read previous audit report and fix summary for comparison baseline
+
+## Phase 3: Color Audit Execution
+
+### Step 1: Color Extraction
+
+Extract all color values from target:
+
+**Static analysis** (always):
+- Glob for CSS/SCSS/Tailwind files -> extract color definitions
+- Parse CSS custom properties (--color-*), class colors, inline styles
+- Normalize all formats to OKLCH for perceptual comparison:
+  - `#hex` -> sRGB -> OKLCH
+  - `rgb()/rgba()` -> OKLCH
+  - `hsl()/hsla()` -> OKLCH
+  - `oklch()` -> direct
+- Record source location (file:line) for each color
+
+**Runtime analysis** (if Chrome DevTools available):
+- `mcp__chrome-devtools__navigate_page({ url: "<target-url>" })`
+- `mcp__chrome-devtools__evaluate_script({ expression: "..." })` with getComputedStyle to extract rendered colors from key elements (body, headings, links, buttons, inputs)
+- `mcp__chrome-devtools__take_screenshot({})` for visual evidence -> save to `<session>/evidence/`
+
+### Step 2: Contrast Ratio Calculation
+
+For each text/background color combination:
+
+**WCAG 2.1 Contrast Ratios**:
+- Calculate relative luminance: `L = 0.2126*R + 0.7152*G + 0.0722*B` (linearized sRGB)
+- Contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` where L1 > L2
+- Thresholds:
+
+| Text Type | AA | AAA |
+|-----------|-----|-----|
+| Normal text (< 18pt / < 14pt bold) | >= 4.5:1 | >= 7:1 |
+| Large text (>= 18pt / >= 14pt bold) | >= 3:1 | >= 4.5:1 |
+| Non-text (UI components, icons) | >= 3:1 | >= 3:1 |
+
+**APCA Contrast (Lc values)**:
+- Calculate APCA Lc using OKLCH lightness difference
+- Thresholds:
+
+| Use Case | Minimum Lc |
+|----------|-----------|
+| Body text (16px) | >= 60 |
+| Large text (24px+) | >= 45 |
+| Non-text elements | >= 30 |
+| Placeholder/disabled | >= 15 |
+
+### Step 3: OKLCH Lightness Analysis
+
+Verify OKLCH lightness ranges per specs/oklch-standards.md:
+
+| Element | Expected L Range | Flag If |
+|---------|-----------------|---------|
+| Dark text on light bg | L <= 40% | L > 40% (too light for text) |
+| Light background | L >= 90% | L < 90% (too dark for bg) |
+| Accent colors | L 50-65% | Outside range |
+| Disabled/muted text | L 55-70% | Outside range |
+
+Check chroma values:
+- Text colors: C near 0 (achromatic) unless intentional accent
+- Vibrant accents: C 0.2-0.25, max 1-2 per palette
+
+### Step 4: Color Blindness Simulation
+
+Assess color distinguishability under:
+- **Protanopia** (red-blind): Check red/green pairs still distinguishable
+- **Deuteranopia** (green-blind): Check green/red pairs
+- **Tritanopia** (blue-blind): Check blue/yellow pairs
+
+Flag combinations that rely solely on color difference without shape/text/pattern alternatives.
+
+### Step 5: Dark Mode Parity
+
+If dark mode exists (media query or data-attribute):
+- Verify all color combinations also pass in dark mode
+- Check that OKLCH lightness relationships invert properly
+- Flag combinations that pass in one mode but fail in the other
+
+### Dark Mode Audit (if dark mode exists)
+
+| Check | Requirement | Method |
+|-------|-------------|--------|
+| No pure black background | Base bg uses tinted dark (oklch L >= 0.10, chroma >= 0.005) | evaluate_script: getComputedStyle check |
+| Surface hierarchy | Higher elevation = lighter surface (at least 3 distinct levels) | Screenshot comparison |
+| Font weight reduction | Dark theme reduces weight by 1 step vs light (600→500, 500→400) | Compare computed font-weight |
+| Accent desaturation | Dark theme accents have lower OKLCH chroma than light (by 0.03-0.10) | Compare computed colors |
+| Dangerous combos | No gray text on colored backgrounds, no red-green only indicators | Visual + computed color analysis |
+| All contrast ratios met | WCAG AA requirements must pass in BOTH light and dark themes | Lighthouse audit both themes |
+
+## Phase 4: Report Generation & Output
+
+1. Write audit report to `<session>/audits/color/color-audit-{NNN}.md` (or `<session>/re-audit/color-audit-{NNN}.md` for re-audits):
+
+```markdown
+# Color Accessibility Audit - {NNN}
+[color-auditor]
+
+## Summary
+- **Total color combinations tested**: {count}
+- **Pass**: {pass_count} | **Fail**: {fail_count}
+- **WCAG Level**: {AA|AAA}
+- **Critical issues**: {count}
+- **High issues**: {count}
+
+## Color Palette (OKLCH)
+| Name | Value | L% | C | H | Source |
+|------|-------|----|---|---|--------|
+| ... | oklch(X% Y Z) | X | Y | Z | file:line |
+
+## Contrast Results
+| Foreground | Background | WCAG Ratio | Pass/Fail | APCA Lc | Pass/Fail | Type |
+|-----------|-----------|------------|-----------|---------|-----------|------|
+| ... | ... | X.X:1 | PASS/FAIL | XX | PASS/FAIL | normal/large |
+
+## OKLCH Lightness Issues
+| Element | Current L | Expected Range | Status |
+|---------|----------|---------------|--------|
+| ... | X% | Y-Z% | PASS/FAIL |
+
+## Color Blindness Assessment
+| Combination | Protanopia | Deuteranopia | Tritanopia | Alt indicator |
+|------------|-----------|-------------|-----------|--------------|
+| ... | safe/risk | safe/risk | safe/risk | yes/no |
+
+## Dark Mode Parity
+| Combination | Light Mode | Dark Mode | Status |
+|------------|-----------|----------|--------|
+| ... | PASS/FAIL | PASS/FAIL | PASS/FAIL |
+
+## Issues (by severity)
+### Critical
+- ...
+### High
+- ...
+### Medium
+- ...
+```
+
+2. For re-audit (COLOR-002+), add before/after comparison section:
+```markdown
+## Before/After Comparison
+| Combination | Before (ratio) | After (ratio) | Status |
+|------------|----------------|---------------|--------|
+| ... | X.X:1 FAIL | Y.Y:1 PASS | FIXED |
+```
+
+3. Update `<session>/.msg/meta.json` under `color-auditor` namespace:
+   - Read existing -> merge `{ "color-auditor": { audit_id, total_combinations, pass_count, fail_count, critical_count, high_count, timestamp } }` -> write back