tribunal-kit 9.2.4 → 9.2.6

package/{.pi → plugins/pi}/extensions/tribunal.ts

@@ -1,130 +1,130 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-export interface ExtensionAPI {
-  on(event: string, handler: (payload?: any) => Promise<any> | any): void;
-}
-
-const EXTREMELY_IMPORTANT_MARKER = '<EXTREMELY_IMPORTANT>';
-const BOOTSTRAP_MARKER = 'tribunal-kit:master-governance bootstrap for pi';
-
-const extensionDir = dirname(fileURLToPath(import.meta.url));
-const packageRoot = resolve(extensionDir, '../..');
-const skillsDir = resolve(packageRoot, '.agent', 'skills');
-const rulesPath = resolve(packageRoot, '.agent', 'rules', 'GEMINI.md');
-
-let cachedBootstrap: string | null | undefined;
-
-export default function tribunalPiExtension(pi: ExtensionAPI) {
-  let injectBootstrap = true;
-
-  pi.on('resources_discover', async () => ({
-    skillPaths: [skillsDir],
-  }));
-
-  pi.on('session_start', async () => {
-    injectBootstrap = true;
-  });
-
-  pi.on('session_compact', async () => {
-    injectBootstrap = true;
-  });
-
-  pi.on('agent_end', async () => {
-    injectBootstrap = false;
-  });
-
-  pi.on('context', async (event: any) => {
-    if (!injectBootstrap) return;
-    if (event?.messages?.some(messageContainsBootstrap)) return;
-
-    const bootstrap = getBootstrapContent();
-    if (!bootstrap) return;
-
-    const bootstrapMessage = {
-      role: 'user' as const,
-      content: [{ type: 'text' as const, text: bootstrap }],
-      timestamp: Date.now(),
-    };
-
-    const messages = event?.messages || [];
-    const insertAt = firstNonCompactionSummaryIndex(messages);
-
-    return {
-      messages: [...messages.slice(0, insertAt), bootstrapMessage, ...messages.slice(insertAt)],
-    };
-  });
-}
-
-function getBootstrapContent(): string | null {
-  if (cachedBootstrap !== undefined) return cachedBootstrap;
-
-  try {
-    let body = '';
-    if (existsSync(rulesPath)) {
-      const raw = readFileSync(rulesPath, 'utf8');
-      body = stripFrontmatter(raw);
-    } else {
-      body =
-        '# Tribunal Kit Master Governance Active\nEnforce strict TDD and 28-specialist reviewer waves.';
-    }
-
-    cachedBootstrap = `${EXTREMELY_IMPORTANT_MARKER}
-${BOOTSTRAP_MARKER}
-
-Tribunal Agent Kit Master Governance is active.
-
-The master rules and verification protocols are loaded for this Pi session. Follow them now.
-
-${body}
-
-${piToolMapping()}
-</EXTREMELY_IMPORTANT>`;
-    return cachedBootstrap;
-  } catch {
-    cachedBootstrap = null;
-    return null;
-  }
-}
-
-function stripFrontmatter(content: string): string {
-  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-  return (match ? match[1] : content).trim();
-}
-
-function piToolMapping(): string {
-  return `## Pi Tool Mapping for Tribunal Kit
-
-Pi has native skills support. When a Tribunal rule or skill applies, load the relevant \`SKILL.md\` with \`read\`, or let a user invoke \`/skill:name\` explicitly.
-
-Pi's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Use those for the corresponding actions: read a file, create or edit files, run shell commands, search file contents, find files by name, and list directories.
-
-Subagent-Driven Development (SDD):
-- To run SDD preparation: use \`bash\` to invoke \`tk sdd brief <plan-path> <task-number>\`.
-- To generate review diffs: use \`bash\` to invoke \`tk sdd diff <plan-path> <base-sha> <head-sha>\`.
-- When delegating to subagents via \`pi-subagents\` or similar tools, supply the generated \`task-<N>-brief.md\` out-of-band and enforce the Iron Law of TDD.`;
-}
-
-function messageContainsBootstrap(message: unknown): boolean {
-  const content = (message as { content?: unknown })?.content;
-  if (typeof content === 'string') return content.includes(BOOTSTRAP_MARKER);
-  if (!Array.isArray(content)) return false;
-  return content.some(part => {
-    return (
-      part &&
-      typeof part === 'object' &&
-      (part as { type?: unknown }).type === 'text' &&
-      typeof (part as { text?: unknown }).text === 'string' &&
-      (part as { text: string }).text.includes(BOOTSTRAP_MARKER)
-    );
-  });
-}
-
-function firstNonCompactionSummaryIndex(messages: unknown[]): number {
-  let index = 0;
-  while ((messages[index] as { role?: unknown } | undefined)?.role === 'compactionSummary') {
-    index += 1;
-  }
-  return index;
-}
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface ExtensionAPI {
+  on(event: string, handler: (payload?: any) => Promise<any> | any): void;
+}
+
+const EXTREMELY_IMPORTANT_MARKER = '<EXTREMELY_IMPORTANT>';
+const BOOTSTRAP_MARKER = 'tribunal-kit:master-governance bootstrap for pi';
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(extensionDir, '../..');
+const skillsDir = resolve(packageRoot, '.agent', 'skills');
+const rulesPath = resolve(packageRoot, '.agent', 'rules', 'GEMINI.md');
+
+let cachedBootstrap: string | null | undefined;
+
+export default function tribunalPiExtension(pi: ExtensionAPI) {
+  let injectBootstrap = true;
+
+  pi.on('resources_discover', async () => ({
+    skillPaths: [skillsDir],
+  }));
+
+  pi.on('session_start', async () => {
+    injectBootstrap = true;
+  });
+
+  pi.on('session_compact', async () => {
+    injectBootstrap = true;
+  });
+
+  pi.on('agent_end', async () => {
+    injectBootstrap = false;
+  });
+
+  pi.on('context', async (event: any) => {
+    if (!injectBootstrap) return;
+    if (event?.messages?.some(messageContainsBootstrap)) return;
+
+    const bootstrap = getBootstrapContent();
+    if (!bootstrap) return;
+
+    const bootstrapMessage = {
+      role: 'user' as const,
+      content: [{ type: 'text' as const, text: bootstrap }],
+      timestamp: Date.now(),
+    };
+
+    const messages = event?.messages || [];
+    const insertAt = firstNonCompactionSummaryIndex(messages);
+
+    return {
+      messages: [...messages.slice(0, insertAt), bootstrapMessage, ...messages.slice(insertAt)],
+    };
+  });
+}
+
+function getBootstrapContent(): string | null {
+  if (cachedBootstrap !== undefined) return cachedBootstrap;
+
+  try {
+    let body = '';
+    if (existsSync(rulesPath)) {
+      const raw = readFileSync(rulesPath, 'utf8');
+      body = stripFrontmatter(raw);
+    } else {
+      body =
+        '# Tribunal Kit Master Governance Active\nEnforce strict TDD and 28-specialist reviewer waves.';
+    }
+
+    cachedBootstrap = `${EXTREMELY_IMPORTANT_MARKER}
+${BOOTSTRAP_MARKER}
+
+Tribunal Agent Kit Master Governance is active.
+
+The master rules and verification protocols are loaded for this Pi session. Follow them now.
+
+${body}
+
+${piToolMapping()}
+</EXTREMELY_IMPORTANT>`;
+    return cachedBootstrap;
+  } catch {
+    cachedBootstrap = null;
+    return null;
+  }
+}
+
+function stripFrontmatter(content: string): string {
+  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  return (match ? match[1] : content).trim();
+}
+
+function piToolMapping(): string {
+  return `## Pi Tool Mapping for Tribunal Kit
+
+Pi has native skills support. When a Tribunal rule or skill applies, load the relevant \`SKILL.md\` with \`read\`, or let a user invoke \`/skill:name\` explicitly.
+
+Pi's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Use those for the corresponding actions: read a file, create or edit files, run shell commands, search file contents, find files by name, and list directories.
+
+Subagent-Driven Development (SDD):
+- To run SDD preparation: use \`bash\` to invoke \`tk sdd brief <plan-path> <task-number>\`.
+- To generate review diffs: use \`bash\` to invoke \`tk sdd diff <plan-path> <base-sha> <head-sha>\`.
+- When delegating to subagents via \`pi-subagents\` or similar tools, supply the generated \`task-<N>-brief.md\` out-of-band and enforce the Iron Law of TDD.`;
+}
+
+function messageContainsBootstrap(message: unknown): boolean {
+  const content = (message as { content?: unknown })?.content;
+  if (typeof content === 'string') return content.includes(BOOTSTRAP_MARKER);
+  if (!Array.isArray(content)) return false;
+  return content.some(part => {
+    return (
+      part &&
+      typeof part === 'object' &&
+      (part as { type?: unknown }).type === 'text' &&
+      typeof (part as { text?: unknown }).text === 'string' &&
+      (part as { text: string }).text.includes(BOOTSTRAP_MARKER)
+    );
+  });
+}
+
+function firstNonCompactionSummaryIndex(messages: unknown[]): number {
+  let index = 0;
+  while ((messages[index] as { role?: unknown } | undefined)?.role === 'compactionSummary') {
+    index += 1;
+  }
+  return index;
+}

package/skills/12-principles-of-animation/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: 12-principles-of-animation
-description: "Use when Application of Disney's 12 Principles of Animation (Squash & Stretch, Anticipation, Staging, Follow Through, Slow In & Slow Out, Arc, Secondary Action, Timing, Exaggeration, Solid Drawing, Appeal) to modern web UI motion."
-version: 5.0.0
-last-updated: 2026-09-13
+description: "Use when implementing, optimizing, and timing 60fps/120fps 12 principles of animation animations, transitions, gesture physics, and reduced-motion fallbacks."
+version: 6.0.0
+last-updated: 2026-09-29
 skills:
   - motion-engineering
   - 60fps-animation
@@ -15,37 +15,107 @@ scripts-binding:
 
 # 12 Principles of Animation — Web UI Motion Theory
 
----
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `12-principles-of-animation` domain, inspect these 5 critical parameters:
+1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
+2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
+3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
+4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
+5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
 
-## 🛠️ Technical Architecture & Reference Recipes
 
----
+## Activation Boundaries
+- **Activate when:** Use when implementing, optimizing, and timing 60fps/120fps 12 principles of animation animations, transitions, gesture physics, and reduced-motion fallbacks.
+- **DO NOT activate when:** The task falls outside the `12-principles-of-animation` domain or is managed by a different dedicated specialist agent.
 
----
 
-## The 6 Essential Web Principles
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
 
-### 1. Squash & Stretch (Scale Elasticity)
 
-- Compress elements slightly on impact (e.g. button press down `scale(0.97)`), then stretch slightly on release (`scale(1.02)` -> `scale(1)`).
-- **Rule**: Preserve overall volume. If height decreases by 5%, width must expand by 5%.
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
 
-### 2. Anticipation (Pre-Motion Cue)
+---
+
+## The 6 Essential Web Principles
+
+### 1. Squash & Stretch (Scale Elasticity)
+
+- Compress elements slightly on impact (e.g. button press down `scale(0.97)`), then stretch slightly on release (`scale(1.02)` -> `scale(1)`).
+- **Rule**: Preserve overall volume. If height decreases by 5%, width must expand by 5%.
+
+### 2. Anticipation (Pre-Motion Cue)
+
+- Before a major movement (e.g. modal sliding up), perform a micro-backwards movement (e.g. shift down `2px` for `40ms`) to prepare the user's eye.
+
+### 3. Staging (Focus & Spatial Hierarchy)
+
+- Direct user attention to one primary animation at a time. Never animate competing layout elements across different regions simultaneously.
+
+### 4. Slow In & Slow Out (Easing Curves)
+
+- Objects in nature start slow, accelerate, and decelerate gradually. Use strong ease-out curves (`cubic-bezier(0.16, 1, 0.3, 1)`) for UI entrances.
+
+### 5. Arcs (Natural Curvilinear Trajectories)
+
+- Human arms and physical objects move in curved arcs rather than mechanical straight lines. When moving elements across 2D space, use parabolic bezier curves or `offset-path`.
+
+### 6. Follow Through & Overlapping Action
+
+- Secondary elements (e.g. badge text inside a sliding card) lag slightly behind the main container (stagger delay 30ms - 50ms), creating organic physical realism.
 
-- Before a major movement (e.g. modal sliding up), perform a micro-backwards movement (e.g. shift down `2px` for `40ms`) to prepare the user's eye.
+## 🚨 Edge-Case & Failure Mode Matrix
 
-### 3. Staging (Focus & Spatial Hierarchy)
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
 
-- Direct user attention to one primary animation at a time. Never animate competing layout elements across different regions simultaneously.
 
-### 4. Slow In & Slow Out (Easing Curves)
+## 🤖 LLM-Specific Traps Table
 
-- Objects in nature start slow, accelerate, and decelerate gradually. Use strong ease-out curves (`cubic-bezier(0.16, 1, 0.3, 1)`) for UI entrances.
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **The Instant Pop Trap** | Conditionally unmounting elements without animated interpolation | Use AnimatePresence or coordinate morphs with continuous geometry |
+| **Layout Thrashing** | Animating width, height, top, or left inside animation loops | Animate composite-only transform (translate3d, scale) and opacity |
+| **Sluggish Duration** | Setting micro-interaction transitions to 600ms+ causing interface lag | Cap interactive feedback at 160ms–240ms with snappy ease-out curves |
 
-### 5. Arcs (Natural Curvilinear Trajectories)
 
-- Human arms and physical objects move in curved arcs rather than mechanical straight lines. When moving elements across 2D space, use parabolic bezier curves or `offset-path`.
+## 🏛️ Tribunal Verification & Guardrails
 
-### 6. Follow Through & Overlapping Action
+**Active Reviewers:** `frontend-reviewer` · `motion-reviewer` · `ui-ux-auditor`
+**Slash Command:** `/review` or `/tribunal-full`
 
-- Secondary elements (e.g. badge text inside a sliding card) lag slightly behind the main container (stagger delay 30ms - 50ms), creating organic physical realism.
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
+
+### ✅ Pre-Flight Self-Audit Checklist
+```
+✅ Does animation maintain 60fps/120fps using transform (translate3d, scale) and opacity?
+✅ Is optical mass conserved across state interpolations without volume collapse?
+✅ Is duration capped within micro-interaction budgets (150ms–280ms)?
+✅ Is prefers-reduced-motion respected with graceful instant fallbacks?
+✅ Did I prevent layout thrashing and continuous geometry mutations?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/skills/60fps-animation/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: 60fps-animation
-description: "Use when Web animation performance guidance for avoiding layout thrashing, achieving 60/120fps motion, and using GPU compositor-friendly properties (transform, opacity)."
-version: 5.0.0
-last-updated: 2026-09-13
+description: "Use when implementing, optimizing, and timing 60fps/120fps 60fps animation animations, transitions, gesture physics, and reduced-motion fallbacks."
+version: 6.0.0
+last-updated: 2026-09-29
 skills:
   - motion-engineering
   - accessible-animation
@@ -15,77 +15,134 @@ scripts-binding:
 
 # 60fps Animation — GPU Compositor & High-Performance Motion
 
----
-
-## 🛠️ Technical Architecture & Reference Recipes
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `60fps-animation` domain, inspect these 5 critical parameters:
+1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
+2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
+3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
+4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
+5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
 
----
 
-## 🛠️ Technical Architecture & Reference Recipes
-
----
+## Activation Boundaries
+- **Activate when:** Use when implementing, optimizing, and timing 60fps/120fps 60fps animation animations, transitions, gesture physics, and reduced-motion fallbacks.
+- **DO NOT activate when:** The task falls outside the `60fps-animation` domain or is managed by a different dedicated specialist agent.
 
-## 2026 Motion Performance & GPU Invariants
-
-1. **CSS `@starting-style` Native Transitions**:
-   ```css
-   /* Native entry animation without JS transition wrappers */
-   dialog[open] {
-     opacity: 1;
-     transform: scale(1);
-     transition:
-       opacity 200ms ease,
-       transform 200ms ease;
-     @starting-style {
-       opacity: 0;
-       transform: scale(0.95);
-     }
-   }
-   ```
-2. **Native Scroll-Driven Animations**: Use CSS `animation-timeline: view()` or `scroll()` to run scroll animations directly on the compositor thread without firing JavaScript scroll event handlers.
-3. **No Layout Thrashing in JS**: Never interleave DOM reads (`element.getBoundingClientRect()`, `offsetHeight`) with DOM writes (`style.transform`). Batch reads first, then writes in `requestAnimationFrame()`.
-
-## Hallucination Traps (Read First)
-
-- ❌ Animating `top`, `left`, `width`, `height` → ✅ Animate `transform: translate3d(...)` and `scale(...)`
-- ❌ Using JavaScript scroll listeners for parallax/fade → ✅ Use native CSS `animation-timeline`
-- ❌ Setting `will-change: transform` globally on every element → ✅ Blows GPU VRAM; apply only during active interaction
-- ❌ Animating box-shadow directly → ✅ Animate `opacity` on a pseudo-element (`::after`) with pre-rendered shadow
 
----
+## 🔁 Multi-Pass Execution Protocol
 
-## 4 Performance Rules
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
 
-### 1. Compositor-Only Animation Pipeline
 
-Only animate properties handled strictly by the GPU compositor layer:
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
 
-- ✅ **Compositor Properties** (Zero Layout / Zero Paint): `transform` (`translate3d`, `scale`, `rotate`) and `opacity`.
-- ❌ **Forbidden Animating Properties** (Triggers Full Layout Re-calculation): `width`, `height`, `margin`, `padding`, `top`, `left`, `border-width`.
+## 2026 Motion Performance & GPU Invariants
+
+1. **CSS `@starting-style` Native Transitions**:
+   ```css
+   /* Native entry animation without JS transition wrappers */
+   dialog[open] {
+     opacity: 1;
+     transform: scale(1);
+     transition:
+       opacity 200ms ease,
+       transform 200ms ease;
+     @starting-style {
+       opacity: 0;
+       transform: scale(0.95);
+     }
+   }
+   ```
+2. **Native Scroll-Driven Animations**: Use CSS `animation-timeline: view()` or `scroll()` to run scroll animations directly on the compositor thread without firing JavaScript scroll event handlers.
+3. **No Layout Thrashing in JS**: Never interleave DOM reads (`element.getBoundingClientRect()`, `offsetHeight`) with DOM writes (`style.transform`). Batch reads first, then writes in `requestAnimationFrame()`.
+
+## Hallucination Traps (Read First)
+
+- ❌ Animating `top`, `left`, `width`, `height` → ✅ Animate `transform: translate3d(...)` and `scale(...)`
+- ❌ Using JavaScript scroll listeners for parallax/fade → ✅ Use native CSS `animation-timeline`
+- ❌ Setting `will-change: transform` globally on every element → ✅ Blows GPU VRAM; apply only during active interaction
+- ❌ Animating box-shadow directly → ✅ Animate `opacity` on a pseudo-element (`::after`) with pre-rendered shadow
+
+---
+
+## 4 Performance Rules
+
+### 1. Compositor-Only Animation Pipeline
+
+Only animate properties handled strictly by the GPU compositor layer:
+
+- ✅ **Compositor Properties** (Zero Layout / Zero Paint): `transform` (`translate3d`, `scale`, `rotate`) and `opacity`.
+- ❌ **Forbidden Animating Properties** (Triggers Full Layout Re-calculation): `width`, `height`, `margin`, `padding`, `top`, `left`, `border-width`.
+
+### 2. Replacing Width/Height Transitions with Scale Math
+
+Instead of animating `width: 100px` to `200px`:
+
+```css
+/* BAD: Triggers Layout recalculation on every frame */
+.box-bad {
+  transition: width 300ms ease;
+}
+
+/* GOOD: GPU Compositor Hardware Accelerated */
+.box-good {
+  transform: scaleX(2);
+  transform-origin: left center;
+  transition: transform 300ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+### 3. `will-change` Management
+
+- Apply `will-change: transform, opacity` ONLY right before or during active animation.
+- Remove `will-change` when animation completes to free up GPU VRAM memory!
+
+### 4. Layout Thrashing Prevention in JS
+
+- Never interleave DOM reads (`element.offsetHeight`) with DOM writes (`element.style.height = ...`) inside requestAnimationFrame or scroll handlers. Batch all reads first, then perform all writes.
 
-### 2. Replacing Width/Height Transitions with Scale Math
+## 🚨 Edge-Case & Failure Mode Matrix
 
-Instead of animating `width: 100px` to `200px`:
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
 
-```css
-/* BAD: Triggers Layout recalculation on every frame */
-.box-bad {
-  transition: width 300ms ease;
-}
 
-/* GOOD: GPU Compositor Hardware Accelerated */
-.box-good {
-  transform: scaleX(2);
-  transform-origin: left center;
-  transition: transform 300ms cubic-bezier(0.16, 1, 0.3, 1);
-}
-```
+## 🏛️ Tribunal Verification & Guardrails
 
-### 3. `will-change` Management
+**Active Reviewers:** `frontend-reviewer` · `motion-reviewer` · `ui-ux-auditor`
+**Slash Command:** `/review` or `/tribunal-full`
 
-- Apply `will-change: transform, opacity` ONLY right before or during active animation.
-- Remove `will-change` when animation completes to free up GPU VRAM memory!
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
 
-### 4. Layout Thrashing Prevention in JS
+### ✅ Pre-Flight Self-Audit Checklist
+```
+✅ Does animation maintain 60fps/120fps using transform (translate3d, scale) and opacity?
+✅ Is optical mass conserved across state interpolations without volume collapse?
+✅ Is duration capped within micro-interaction budgets (150ms–280ms)?
+✅ Is prefers-reduced-motion respected with graceful instant fallbacks?
+✅ Did I prevent layout thrashing and continuous geometry mutations?
+```
 
-- Never interleave DOM reads (`element.offsetHeight`) with DOM writes (`element.style.height = ...`) inside requestAnimationFrame or scroll handlers. Batch all reads first, then perform all writes.
+### 🛑 Verification-Before-Completion (VBC) Protocol
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.