maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-motion-design/roles/coordinator/commands/monitor.md

@@ -0,0 +1,216 @@
+# monitor_process Pipeline
+
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
+
+## Constants
+
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+- MAX_GC_ROUNDS: 2
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains [motion-researcher], [choreographer], [animator], [motion-tester] | handleCallback |
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCallback
+
+Worker completed. Process and advance.
+
+1. Parse message to identify role and task ID:
+
+| Message Pattern | Role |
+|----------------|------|
+| `[motion-researcher]` or `MRESEARCH-*` | motion-researcher |
+| `[choreographer]` or `CHOREO-*` | choreographer |
+| `[animator]` or `ANIM-*` | animator |
+| `[motion-tester]` or `MTEST-*` | motion-tester |
+
+2. Mark task completed: `update_task({ taskId: "<task-id>", status: "completed" })`
+3. Record completion in session state
+
+4. Check checkpoint for completed task:
+
+| Completed Task | Checkpoint | Action |
+|---------------|------------|--------|
+| MRESEARCH-001 | - | Notify user: research complete |
+| CHOREO-001 | - | Proceed to ANIM task(s) |
+| ANIM-* (single) | - | Proceed to MTEST-001 |
+| ANIM-* (page mode) | - | Check if all ANIM tasks complete, then unblock MTEST-001 |
+| MTEST-001 | PERF-001: Performance Gate | Check perf signal -> GC loop or complete |
+
+5. **Performance Gate handling** (MTEST task completed):
+   Read performance signal from message: `perf_passed`, `perf_warning`, or `fix_required`
+
+   | Signal | Condition | Action |
+   |--------|-----------|--------|
+   | `perf_passed` | FPS >= 60, no layout thrashing, reduced-motion present | Performance gate passed -> pipeline complete |
+   | `perf_warning` | Minor issues (will-change count high, near 60fps) | gc_rounds < max -> create ANIM-fix task |
+   | `fix_required` | FPS < 60 or layout thrashing detected | gc_rounds < max -> create ANIM-fix task (CRITICAL) |
+   | Any | gc_rounds >= max | Escalate to user |
+
+   **GC Fix Task Creation**:
+   ```
+   create_task({ subject: "ANIM-fix-<round>",
+     description: "PURPOSE: Address performance issues from motion-tester report | Success: All critical perf issues resolved
+   TASK:
+     - Parse performance report for specific issues (layout thrashing, unsafe properties, excessive will-change)
+     - Replace layout-triggering properties with compositor-only alternatives
+     - Optimize will-change usage
+     - Verify reduced-motion fallback completeness
+   CONTEXT:
+     - Session: <session-folder>
+     - Upstream artifacts: testing/reports/perf-report-<NNN>.md" })
+   update_task({ taskId: "ANIM-fix-<round>", owner: "animator" })
+   ```
+   Then create new MTEST task blocked by fix. Increment gc_state.round.
+
+   **GC Escalation Options** (when max rounds exceeded):
+   1. Accept current animations - skip performance review, continue
+   2. Try one more round
+   3. Terminate
+
+6. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.
+
+**Worker Progress** (from message bus):
+
+Before generating status output, read worker milestones:
+
+```javascript
+const progressMsgs = mcp__maestro__team_msg({
+  operation: "list", session_id: sessionId, type: "progress", last: 50
+})
+const blockerMsgs = mcp__maestro__team_msg({
+  operation: "list", session_id: sessionId, type: "blocker", last: 10
+})
+
+// Aggregate latest milestone per task
+const taskProgress = {}
+for (const msg of (progressMsgs.result?.messages || [])) {
+  const tid = msg.data?.task_id
+  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
+    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
+  }
+}
+```
+
+Include in status output:
+- Per-worker latest milestone (phase + progress_pct) next to task status
+- Active blockers section (if any blockerMsgs found)
+
+```
+Pipeline Status (<pipeline-mode>):
+  [DONE]  MRESEARCH-001 (motion-researcher)  -> research/*.json
+  [DONE]  CHOREO-001    (choreographer)       -> motion-tokens.json + sequences/
+  [RUN]   ANIM-001      (animator)            -> implementing animations...
+  [WAIT]  MTEST-001     (motion-tester)       -> blocked by ANIM-001
+
+GC Rounds: 0/2
+Performance Gate: pending
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
+```
+
+Output status -- do NOT advance pipeline.
+
+## handleResume
+
+1. Audit task list for inconsistencies:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed blockers but still "pending" -> include in spawn list
+2. -> handleSpawnNext
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, STOP.
+
+1. Collect: completedSubjects, inProgressSubjects, readySubjects (pending + all blockedBy completed)
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Check inner loop role with active worker -> skip (worker picks up)
+   b. update_task -> in_progress
+   c. team_msg log -> task_unblocked
+   d. Spawn team-worker:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker for <task-id>",
+  team_name: "motion-design",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: ~  or <project>/.claude/skills/team-motion-design/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: motion-design
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final send_message.
+
+Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+**Parallel spawn rules by mode**:
+
+| Mode | Scenario | Spawn Behavior |
+|------|----------|---------------|
+| tokens | Sequential | One task at a time |
+| component | Sequential | One task at a time, GC loop on MTEST |
+| page | After CHOREO-001 | Spawn ANIM-001..N in parallel (CP-3 Fan-out) |
+| page | After all ANIM complete | Spawn MTEST-001 |
+
+5. Add to active_workers, update session, output summary, STOP
+
+## handleComplete
+
+Pipeline done. Generate report and completion action.
+
+**Completion check by mode**:
+
+| Mode | Completion Condition |
+|------|---------------------|
+| tokens | All 4 tasks (+ fix tasks) completed |
+| component | All 4 tasks (+ fix tasks) completed |
+| page | All 4+N tasks (+ fix tasks) completed |
+
+1. If any tasks not completed -> handleSpawnNext
+2. If all completed -> transition to coordinator Phase 5
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 5 -> generate dynamic role spec
+4. Create new task, spawn worker
+5. Role count >= 5 -> merge or pause
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_workers with spawned successors
+3. No duplicate spawns

package/.agents/skills/team-motion-design/roles/coordinator/role.md

@@ -0,0 +1,167 @@
+# Coordinator Role
+
+Motion Design Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages animation task chains with GC loops for performance validation.
+
+## Identity
+- **Name**: coordinator | **Tag**: [coordinator]
+- **Responsibility**: Analyze task -> Create team -> Dispatch tasks -> monitor_process progress -> Report results
+
+## Boundaries
+
+### MUST
+- All output (send_message, team_msg, logs) must carry `[coordinator]` identifier
+- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
+- Dispatch tasks with proper dependency chains and blockedBy
+- monitor_process worker progress via message bus and route messages
+- Handle Generator-Critic loops with max 2 iterations
+- Maintain session state persistence
+
+### MUST NOT
+- Implement domain logic (researching, choreographing, animating, testing) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip sync points when configured
+- Force-advance pipeline past failed performance test
+- Modify source code or animation artifacts directly -- delegate to workers
+- Omit `[coordinator]` identifier in any output
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (analyze, dispatch, monitor):
+
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains [motion-researcher], [choreographer], [animator], [motion-tester] | -> handleCallback (monitor.md) |
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists in .workflow/.team/MD-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/adapt/complete: load `@commands/monitor.md`, execute matched handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/MD-*/.msg/meta.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (audit list_tasks, reset in_progress->pending, rebuild team, kick first ready task)
+4. Multiple -> ask_user for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse task description from arguments
+2. Detect motion scope:
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| Token, easing, duration system, motion tokens | tokens |
+| Animate specific component(s), single element | component |
+| Full page scroll choreography, page transitions | page |
+| Unclear | ask user |
+
+3. Ask for missing parameters if scope unclear:
+   ```
+   ask_user({
+     questions: [
+       { question: "Motion design scope?", header: "Scope", options: [
+         { label: "Animation token system", description: "Easing functions, duration scale, stagger formulas" },
+         { label: "Component animation", description: "Animate specific component(s) with transitions" },
+         { label: "Page scroll choreography", description: "Full page scroll-triggered reveals and transitions" }
+       ]},
+       { question: "Target framework?", header: "Framework", options: [
+         { label: "CSS-only" }, { label: "React" },
+         { label: "Vue" }, { label: "Vanilla JS" }, { label: "Other" }
+       ]}
+     ]
+   })
+   ```
+4. Delegate to `@commands/analyze.md` -> output scope context
+5. Record: pipeline_mode, framework, complexity
+
+## Phase 2: Create Team + Initialize Session
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `shell({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-motion-design`
+2. Generate session ID: `MD-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
+   ```
+   .workflow/.team/MD-<slug>-<date>/research/perf-traces/
+   .workflow/.team/MD-<slug>-<date>/choreography/sequences/
+   .workflow/.team/MD-<slug>-<date>/animations/keyframes/
+   .workflow/.team/MD-<slug>-<date>/animations/orchestrators/
+   .workflow/.team/MD-<slug>-<date>/testing/traces/
+   .workflow/.team/MD-<slug>-<date>/testing/reports/
+   .workflow/.team/MD-<slug>-<date>/wisdom/
+   .workflow/.team/MD-<slug>-<date>/.msg/
+   ```
+4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
+5. create_team(team_name="motion-design")
+6. Do NOT spawn workers yet - deferred to Phase 4
+
+## Phase 3: Create Task Chain
+
+Delegate to `@commands/dispatch.md`. Task chains by mode:
+
+| Mode | Task Chain |
+|------|------------|
+| tokens | MRESEARCH-001 -> CHOREO-001 -> ANIM-001 -> MTEST-001 |
+| component | MRESEARCH-001 -> CHOREO-001 -> ANIM-001 -> MTEST-001 (GC loop) |
+| page | MRESEARCH-001 -> CHOREO-001 -> [ANIM-001..N parallel] -> MTEST-001 |
+
+## Phase 4: Spawn-and-Stop
+
+Delegate to `@commands/monitor.md#handleSpawnNext`:
+1. Find ready tasks (pending + blockedBy resolved)
+2. Spawn team-worker agents (see SKILL.md Spawn Template)
+3. Output status summary
+4. STOP
+
+## Phase 5: Report + Completion Action
+
+1. Read session state -> collect all results
+2. List deliverables:
+
+| Deliverable | Path |
+|-------------|------|
+| Animation Inventory | <session>/research/animation-inventory.json |
+| Performance Baseline | <session>/research/performance-baseline.json |
+| Easing Catalog | <session>/research/easing-catalog.json |
+| Motion Tokens | <session>/choreography/motion-tokens.json |
+| Choreography Sequences | <session>/choreography/sequences/*.md |
+| CSS Keyframes | <session>/animations/keyframes/*.css |
+| JS Orchestrators | <session>/animations/orchestrators/*.js |
+| Performance Reports | <session>/testing/reports/perf-report-*.md |
+
+3. Calculate: completed_tasks, gc_rounds, perf_score, final_fps
+4. Output pipeline summary with [coordinator] prefix
+5. Execute completion action:
+   ```
+   ask_user({
+     questions: [{ question: "Pipeline complete. What next?", header: "Completion", options: [
+       { label: "Archive & Clean", description: "Archive session and clean up team resources" },
+       { label: "Keep Active", description: "Keep session for follow-up work" },
+       { label: "Export Results", description: "Export deliverables to specified location" }
+     ]}]
+   })
+   ```
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Reset task to pending, respawn worker |
+| Dependency cycle | Detect, report to user, halt |
+| Invalid scope | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |
+| GC loop stuck > 2 rounds | Escalate to user: accept / try one more / terminate |

package/.agents/skills/team-motion-design/roles/motion-researcher/role.md

@@ -0,0 +1,117 @@
+---
+role: motion-researcher
+prefix: MRESEARCH
+inner_loop: false
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Motion & Animation Researcher
+
+Audit existing animations in the codebase, measure paint/composite costs via Chrome DevTools performance traces, and catalog easing patterns. Produce foundation data for downstream choreographer, animator, and motion-tester roles.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Detect project type and tech stack from package.json or equivalent:
+
+| Package | Detected Stack |
+|---------|---------------|
+| next | nextjs |
+| react | react |
+| vue | vue |
+| svelte | svelte |
+| gsap | gsap |
+| framer-motion | framer-motion |
+| @react-spring/web | react-spring |
+| (default) | css-vanilla |
+
+3. Use CLI tools (e.g., `maestro delegate "..." --to gemini --mode analysis`) or direct tools (Glob, Grep) to scan for existing animations, transitions, keyframes
+4. Read framework context from session config
+
+## Phase 3: Research Execution
+
+Execute 3 analysis streams:
+
+**Stream 1 -- Animation Inventory**:
+- Search for CSS @keyframes declarations (pattern: `@keyframes`)
+- Search for CSS transition properties (pattern: `transition:`, `transition-property:`)
+- Search for JS animation APIs (requestAnimationFrame, Web Animations API, GSAP, Framer Motion)
+- Search for IntersectionObserver usage (scroll-triggered animations)
+- Catalog each animation: name, properties animated, duration, easing, trigger mechanism
+- Flag unsafe properties (width, height, top, left, margin, padding, color, background-color)
+- Output: `<session>/research/animation-inventory.json`
+  ```json
+  {
+    "css_keyframes": [{ "name": "", "file": "", "properties": [], "safe": true }],
+    "css_transitions": [{ "file": "", "line": 0, "properties": [], "duration": "", "easing": "" }],
+    "js_animations": [{ "file": "", "type": "rAF|WAAPI|gsap|framer", "properties": [] }],
+    "scroll_triggers": [{ "file": "", "type": "IntersectionObserver|scroll-event", "threshold": 0 }],
+    "unsafe_animations": [{ "file": "", "line": 0, "property": "", "suggestion": "" }],
+    "summary": { "total": 0, "safe_count": 0, "unsafe_count": 0 }
+  }
+  ```
+
+**Stream 2 -- Performance Baseline**:
+- If Chrome DevTools MCP available:
+  - Start performance trace: `mcp__chrome-devtools__performance_start_trace()`
+  - Trigger page load or scroll interaction
+  - Stop trace: `mcp__chrome-devtools__performance_stop_trace()`
+  - Analyze: `mcp__chrome-devtools__performance_analyze_insight()`
+  - Extract: FPS data, paint/composite times, layout thrashing events, layer count
+- If Chrome DevTools unavailable:
+  - Static analysis: count layout-triggering properties, estimate performance from code patterns
+  - Mark `_source: "static-analysis"`
+- Output: `<session>/research/performance-baseline.json`
+  ```json
+  {
+    "_source": "chrome-devtools|static-analysis",
+    "fps": { "average": 0, "minimum": 0, "drops": [] },
+    "paint_time_ms": 0,
+    "composite_time_ms": 0,
+    "layout_thrashing": [],
+    "layer_count": 0,
+    "will_change_count": 0
+  }
+  ```
+
+**Stream 3 -- Easing Catalog**:
+- Search for cubic-bezier declarations in CSS
+- Search for named easing functions (ease, ease-in, ease-out, ease-in-out, linear)
+- Search for JS easing implementations (spring physics, custom curves)
+- Catalog each: name/value, usage count, context (hover, scroll, entry)
+- Recommend additions based on gaps (missing ease-spring, missing stagger patterns)
+- Reference specs/motion-tokens.md for recommended token schema
+- Output: `<session>/research/easing-catalog.json`
+  ```json
+  {
+    "existing": [{ "value": "", "usage_count": 0, "contexts": [] }],
+    "recommended_additions": [{ "name": "", "value": "", "reason": "" }],
+    "duration_patterns": [{ "value": "", "usage_count": 0, "contexts": [] }],
+    "stagger_patterns": [{ "found": false, "details": "" }]
+  }
+  ```
+
+Compile research summary metrics: animation_count, safe_percentage, fps_baseline, easing_count, has_reduced_motion.
+
+## Phase 4: Validation & Output
+
+1. Verify all 3 output files exist and contain valid JSON with required fields:
+
+| File | Required Fields |
+|------|----------------|
+| animation-inventory.json | css_keyframes array, summary |
+| performance-baseline.json | _source |
+| easing-catalog.json | existing array |
+
+2. If any file missing or invalid, re-run corresponding stream
+
+3. Update `<session>/wisdom/.msg/meta.json` under `motion-researcher` namespace:
+   - Read existing -> merge `{ "motion-researcher": { detected_stack, animation_count, safe_percentage, fps_baseline, easing_count, has_reduced_motion } }` -> write back

package/.agents/skills/team-motion-design/roles/motion-tester/role.md

@@ -0,0 +1,177 @@
+---
+role: motion-tester
+prefix: MTEST
+inner_loop: false
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Motion Performance Tester
+
+Test animation performance via Chrome DevTools performance traces and static code analysis. Verify compositor-only animations, measure FPS, detect layout thrashing, and validate prefers-reduced-motion accessibility compliance. Act as Critic in the animator<->motion-tester Generator-Critic loop.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Animation files | <session>/animations/keyframes/*.css | Yes |
+| JS orchestrators | <session>/animations/orchestrators/*.js | Yes |
+| Motion tokens | <session>/choreography/motion-tokens.json | Yes |
+| Choreography sequences | <session>/choreography/sequences/*.md | Yes (component/page) |
+| GPU constraints | specs/gpu-constraints.md | Yes |
+| Reduced motion spec | specs/reduced-motion.md | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. Read all animation CSS files from animations/keyframes/
+3. Read all JS orchestrator files from animations/orchestrators/
+4. Read motion tokens for reference values
+5. Read choreography sequences for expected behavior
+6. Read GPU constraints and reduced motion specs for validation rules
+
+## Phase 3: Test Execution
+
+### Test 1: Compositor-Only Verification
+
+Scan all CSS @keyframes and transition properties for unsafe values:
+
+**SAFE** (compositor thread, no repaint):
+- `transform` (translate, scale, rotate, skew)
+- `opacity`
+- `filter` (blur, brightness, contrast)
+- `backdrop-filter`
+
+**UNSAFE** (trigger layout/paint):
+- `width`, `height`, `top`, `left`, `right`, `bottom`
+- `margin`, `padding`, `border`
+- `font-size`, `color`, `background-color`
+- `box-shadow` (partial -- expensive paint)
+
+For each animation file:
+1. Parse @keyframes blocks, extract animated properties
+2. Parse transition declarations, extract properties
+3. Flag any UNSAFE property with file:line reference
+4. Score: `safe_percentage = safe_count / total_count * 100`
+
+### Test 2: Frame Rate Analysis
+
+**If Chrome DevTools MCP available**:
+1. `mcp__chrome-devtools__performance_start_trace()` -- start recording
+2. `mcp__chrome-devtools__evaluate_script({ expression: "/* trigger animations */" })` -- trigger
+3. `mcp__chrome-devtools__performance_stop_trace()` -- stop recording
+4. `mcp__chrome-devtools__performance_analyze_insight()` -- analyze
+5. Extract: average FPS, minimum FPS, frame drops, long frames (>16.67ms)
+6. Target: average >= 60fps, minimum >= 45fps, no consecutive drops
+
+**If Chrome DevTools unavailable** (static analysis fallback):
+1. Count total animated properties per frame (concurrent animations)
+2. Estimate frame budget: < 5ms style+layout, < 5ms paint+composite
+3. Flag: >10 concurrent animations, nested animations, forced synchronous layouts
+4. Mark `_source: "static-analysis"` and note limitations
+
+### Test 3: Layout Thrashing Detection
+
+Scan JS orchestrators for read-write-read patterns:
+
+**Thrashing patterns** (DOM read -> write -> read in same frame):
+- `offsetHeight` / `offsetWidth` read followed by style write followed by read
+- `getBoundingClientRect()` interleaved with style mutations
+- `getComputedStyle()` followed by DOM writes
+
+For each JS file:
+1. Parse for DOM read APIs: `offsetHeight`, `offsetWidth`, `clientHeight`, `getBoundingClientRect`, `getComputedStyle`, `scrollTop`, `scrollHeight`
+2. Check if style writes (`.style.*`, `.classList.*`, `.setAttribute`) occur between reads
+3. Flag thrashing sequences with file:line references
+
+### Test 4: will-change Audit
+
+1. Count elements with `will-change` in CSS
+2. Flag if count > 4 (memory cost)
+3. Check for `will-change: auto` on collections (anti-pattern)
+4. Verify will-change is removed after animation completes (in JS orchestrators)
+5. Check for missing will-change on heavily animated elements
+
+### Test 5: Reduced Motion Compliance
+
+1. Verify `@media (prefers-reduced-motion: reduce)` block exists
+2. Check all animation-duration and transition-duration are overridden
+3. Verify scroll-behavior set to auto
+4. Check JS for `matchMedia('(prefers-reduced-motion: reduce)')` detection
+5. Verify parallax effects disabled in reduced motion
+6. Verify no auto-playing or infinite loop animations in reduced motion
+
+### Perceived Performance Checks
+| Check | Pass Criteria |
+|-------|---------------|
+| Preemptive animation start | Hover/click animations start on pointerdown, not click |
+| No height/width animation | Grid-template-rows trick used instead of height transitions |
+| Ease-in for progress | Progress indicators use ease-in (compresses perceived wait) |
+| Ease-out for entrances | Content entrances use ease-out (natural settle) |
+
+**Scoring**:
+
+| Check | Weight | Criteria |
+|-------|--------|----------|
+| Compositor-only | 30% | 100% safe = 10, each unsafe -2 |
+| Frame rate | 25% | >= 60fps = 10, 50-59 = 7, 40-49 = 4, < 40 = 1 |
+| Layout thrashing | 20% | 0 instances = 10, each instance -3 |
+| will-change budget | 10% | <= 4 = 10, 5-6 = 7, 7+ = 3 |
+| Reduced motion | 15% | All 5 checks pass = 10, each miss -2 |
+
+**Overall score**: `round(compositor*0.30 + fps*0.25 + thrashing*0.20 + willchange*0.10 + reducedmotion*0.15)`
+
+**Signal determination**:
+
+| Condition | Signal |
+|-----------|--------|
+| Score >= 8 AND no layout thrashing AND FPS >= 60 | `perf_passed` (GATE PASSED) |
+| Score >= 6 AND no critical issues | `perf_warning` (REVISION SUGGESTED) |
+| Score < 6 OR layout thrashing OR FPS < 60 | `fix_required` (CRITICAL FIX NEEDED) |
+
+## Phase 4: Report & Output
+
+1. Write performance report to `<session>/testing/reports/perf-report-{NNN}.md`:
+   ```markdown
+   # Performance Report {NNN}
+
+   ## Summary
+   - Overall Score: X/10
+   - Signal: perf_passed|perf_warning|fix_required
+   - Source: chrome-devtools|static-analysis
+
+   ## Compositor-Only Verification
+   - Safe: X/Y properties (Z%)
+   - Unsafe properties found:
+     - [file:line] property: suggestion
+
+   ## Frame Rate
+   - Average FPS: X
+   - Minimum FPS: X
+   - Frame drops: X
+   - Long frames (>16.67ms): X
+
+   ## Layout Thrashing
+   - Instances found: X
+   - Details:
+     - [file:line] pattern: description
+
+   ## will-change Audit
+   - Elements with will-change: X
+   - Budget status: OK|OVER
+   - Issues:
+     - [file:line] issue: description
+
+   ## Reduced Motion Compliance
+   - @media query present: yes|no
+   - Duration override: yes|no
+   - JS detection: yes|no
+   - Parallax disabled: yes|no|N/A
+   - No infinite loops: yes|no
+
+   ## Recommendations
+   1. [Priority] Description
+   ```
+
+2. Update `<session>/wisdom/.msg/meta.json` under `motion-tester` namespace:
+   - Read existing -> merge `{ "motion-tester": { report_id, score, signal, fps_average, safe_percentage, thrashing_count, will_change_count, reduced_motion_complete } }` -> write back