tribunal-kit 9.2.3 → 9.2.5

package/.agent/workflows/performance-benchmarker.md

@@ -1,148 +1,148 @@
----
-description: Run standardized performance benchmarks including Lighthouse CI, bundle analysis, and API latency checks. Records before/after metrics. No optimization claims without measured evidence.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-07-30
-required-skills:
-  - performance-profiling
-  - web-quality-audit
-  - 60fps-animation
-scripts-binding:
-  - .agent/scripts/bundle_analyzer.js
-  - .agent/scripts/verify_all.js
----
-
-# /performance-benchmarker — Evidence-Based Performance Measurement
-
-$ARGUMENTS
-
----
-
-## Mandatory Pre-Flight Context Inspection
-
-Before running performance benchmarks or capturing latency metrics, you MUST inspect:
-
-1. Target App Environment & Build Command (`package.json`) → Confirm production build output and dev/preview server URL
-2. Benchmark Scripts Availability (`.agent/scripts/bundle_analyzer.js`) → Verify automated bundle and latency measurement tooling
-3. Before/After Metric Recording Constraint → Require side-by-side metric tables (LCP, CLS, INP, TTFB, Bundle Size) for every benchmark pass
-
-4. Required Skills → Before executing, load and follow procedural rules from:
-   - `performance-profiling` (.agent/skills/performance-profiling/SKILL.md): Performance measurement methodology and profiling tools
-   - `web-quality-audit` (.agent/skills/web-quality-audit/SKILL.md): Lighthouse-style analysis across Performance, Accessibility, SEO
-   - `60fps-animation` (.agent/skills/60fps-animation/SKILL.md): GPU compositor-friendly properties and layout thrash avoidance
-
----
-
-## When to Use /performance-benchmarker
-
-| Use `/performance-benchmarker` when...  | Use something else when...                            |
-| :-------------------------------------- | :---------------------------------------------------- |
-| Establishing performance baseline       | Code optimization decisions → `/tribunal-performance` |
-| After optimization — verify improvement | Memory leaks investigation → `/debug`                 |
-| Pre-release performance gate            | Bundle analysis only → run ANALYZE=true npm run build |
-| Regular weekly benchmark                | API review only → `/tribunal-backend`                 |
-
----
-
-## Benchmark Suite (Run in Order)
-
-```bash
-# 1. Lighthouse CI — Core Web Vitals
-npx lighthouse http://localhost:3000 \
-  --output=json \
-  --output-path=./reports/lighthouse-$(date +%Y%m%d).json \
-  --only-categories=performance,accessibility,best-practices,seo
-
-# 2. Bundle Analysis
-ANALYZE=true npm run build
-
-# 3. API latency (using autocannon for load test)
-npx autocannon -c 10 -d 20 http://localhost:3000/api/products
-# -c: 10 concurrent connections
-# -d: 20 second duration
-
-# 4. Database query analysis
-# (Prisma): Add to your test route temporarily
-const plan = await prisma.$queryRaw`EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = ${userId}`;
-console.log(plan);
-```
-
----
-
-## Benchmark Report Format
-
-```
-━━━ Performance Benchmark — [date] ━━━━━━━━━
-
-━━━ Core Web Vitals (Lighthouse) ━━━━━━━━━━
-LCP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
-INP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
-CLS:  [score]  [✅ Good | ⚠️ Needs Work | ❌ Poor]
-FCP:  [time]
-TTFB: [time]
-
-Performance Score: [N]/100
-
-━━━ Bundle Sizes ━━━━━━━━━━━━━━━━━━━━━━━━━
-First Load JS (shared): [size]
-Largest page:           [size] ([route])
-Largest 3 bundles:
-  [bundle]: [size]
-  [bundle]: [size]
-  [bundle]: [size]
-
-━━━ API Latency (10 concurrent, 20s) ━━━━━━
-GET /api/products: avg [ms] | p99 [ms] | [req/s] req/s
-POST /api/orders:  avg [ms] | p99 [ms]
-
-━━━ Comparison (vs last run) ━━━━━━━━━━━━━━
-LCP:    4.2s → 1.9s  ▼ IMPROVED ✅
-INP:    480ms → 140ms ▼ IMPROVED ✅
-Bundle: 890kb → 310kb ▼ IMPROVED ✅
-p99 latency: 230ms → 89ms ▼ IMPROVED ✅
-```
-
----
-
-## Performance Gates (Fail Criteria)
-
-```
-Failing these means optimization is blocking — not optional:
-
-LCP   > 4.0s     → ❌ Must fix — users see blank page
-INP   > 500ms    → ❌ Must fix — UI feels unresponsive
-CLS   > 0.25     → ❌ Must fix — layout jumps are jarring
-Bundle > 1mb     → ❌ Must fix — 3G users abandon
-p99 API > 2000ms → ❌ Must fix — timeout risk on slow connections
-
-Warning range (fix before major release):
-LCP   2.5–4.0s  → ⚠️
-INP   200–500ms → ⚠️
-Bundle 500kb–1mb → ⚠️
-```
-
----
-
-## Historical Tracking
-
-Save every benchmark run:
-
-```bash
-# Benchmarks should be saved with date stamps
-./reports/lighthouse-2026-04-02.json
-./reports/bundle-2026-04-02.txt
-./reports/latency-2026-04-02.txt
-```
-
-This enables trend analysis: is performance improving or degrading over time?
-
----
-
-## After /performance-benchmarker — Next Steps
-
-| Outcome                          | Next Command                                            |
-| :------------------------------- | :------------------------------------------------------ |
-| Performance passes all gates     | → `/deploy` or return to development                    |
-| Performance degrades/fails gates | → `/tribunal-speed` to optimize the specific bottleneck |
-
----
+---
+description: Run standardized performance benchmarks including Lighthouse CI, bundle analysis, and API latency checks. Records before/after metrics. No optimization claims without measured evidence.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 3.0.0
+last-updated: 2026-07-30
+required-skills:
+  - performance-profiling
+  - web-quality-audit
+  - 60fps-animation
+scripts-binding:
+  - .agent/scripts/bundle_analyzer.js
+  - .agent/scripts/verify_all.js
+---
+
+# /performance-benchmarker — Evidence-Based Performance Measurement
+
+$ARGUMENTS
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Before running performance benchmarks or capturing latency metrics, you MUST inspect:
+
+1. Target App Environment & Build Command (`package.json`) → Confirm production build output and dev/preview server URL
+2. Benchmark Scripts Availability (`.agent/scripts/bundle_analyzer.js`) → Verify automated bundle and latency measurement tooling
+3. Before/After Metric Recording Constraint → Require side-by-side metric tables (LCP, CLS, INP, TTFB, Bundle Size) for every benchmark pass
+
+4. Required Skills → Before executing, load and follow procedural rules from:
+   - `performance-profiling` (.agent/skills/performance-profiling/SKILL.md): Performance measurement methodology and profiling tools
+   - `web-quality-audit` (.agent/skills/web-quality-audit/SKILL.md): Lighthouse-style analysis across Performance, Accessibility, SEO
+   - `60fps-animation` (.agent/skills/60fps-animation/SKILL.md): GPU compositor-friendly properties and layout thrash avoidance
+
+---
+
+## When to Use /performance-benchmarker
+
+| Use `/performance-benchmarker` when...  | Use something else when...                            |
+| :-------------------------------------- | :---------------------------------------------------- |
+| Establishing performance baseline       | Code optimization decisions → `/tribunal-performance` |
+| After optimization — verify improvement | Memory leaks investigation → `/debug`                 |
+| Pre-release performance gate            | Bundle analysis only → run ANALYZE=true npm run build |
+| Regular weekly benchmark                | API review only → `/tribunal-backend`                 |
+
+---
+
+## Benchmark Suite (Run in Order)
+
+```bash
+# 1. Lighthouse CI — Core Web Vitals
+npx lighthouse http://localhost:3000 \
+  --output=json \
+  --output-path=./reports/lighthouse-$(date +%Y%m%d).json \
+  --only-categories=performance,accessibility,best-practices,seo
+
+# 2. Bundle Analysis
+ANALYZE=true npm run build
+
+# 3. API latency (using autocannon for load test)
+npx autocannon -c 10 -d 20 http://localhost:3000/api/products
+# -c: 10 concurrent connections
+# -d: 20 second duration
+
+# 4. Database query analysis
+# (Prisma): Add to your test route temporarily
+const plan = await prisma.$queryRaw`EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = ${userId}`;
+console.log(plan);
+```
+
+---
+
+## Benchmark Report Format
+
+```
+━━━ Performance Benchmark — [date] ━━━━━━━━━
+
+━━━ Core Web Vitals (Lighthouse) ━━━━━━━━━━
+LCP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
+INP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
+CLS:  [score]  [✅ Good | ⚠️ Needs Work | ❌ Poor]
+FCP:  [time]
+TTFB: [time]
+
+Performance Score: [N]/100
+
+━━━ Bundle Sizes ━━━━━━━━━━━━━━━━━━━━━━━━━
+First Load JS (shared): [size]
+Largest page:           [size] ([route])
+Largest 3 bundles:
+  [bundle]: [size]
+  [bundle]: [size]
+  [bundle]: [size]
+
+━━━ API Latency (10 concurrent, 20s) ━━━━━━
+GET /api/products: avg [ms] | p99 [ms] | [req/s] req/s
+POST /api/orders:  avg [ms] | p99 [ms]
+
+━━━ Comparison (vs last run) ━━━━━━━━━━━━━━
+LCP:    4.2s → 1.9s  ▼ IMPROVED ✅
+INP:    480ms → 140ms ▼ IMPROVED ✅
+Bundle: 890kb → 310kb ▼ IMPROVED ✅
+p99 latency: 230ms → 89ms ▼ IMPROVED ✅
+```
+
+---
+
+## Performance Gates (Fail Criteria)
+
+```
+Failing these means optimization is blocking — not optional:
+
+LCP   > 4.0s     → ❌ Must fix — users see blank page
+INP   > 500ms    → ❌ Must fix — UI feels unresponsive
+CLS   > 0.25     → ❌ Must fix — layout jumps are jarring
+Bundle > 1mb     → ❌ Must fix — 3G users abandon
+p99 API > 2000ms → ❌ Must fix — timeout risk on slow connections
+
+Warning range (fix before major release):
+LCP   2.5–4.0s  → ⚠️
+INP   200–500ms → ⚠️
+Bundle 500kb–1mb → ⚠️
+```
+
+---
+
+## Historical Tracking
+
+Save every benchmark run:
+
+```bash
+# Benchmarks should be saved with date stamps
+./reports/lighthouse-2026-04-02.json
+./reports/bundle-2026-04-02.txt
+./reports/latency-2026-04-02.txt
+```
+
+This enables trend analysis: is performance improving or degrading over time?
+
+---
+
+## After /performance-benchmarker — Next Steps
+
+| Outcome                          | Next Command                                            |
+| :------------------------------- | :------------------------------------------------------ |
+| Performance passes all gates     | → `/deploy` or return to development                    |
+| Performance degrades/fails gates | → `/tribunal-speed` to optimize the specific bottleneck |
+
+---

package/.agent/workflows/pipeline.md

@@ -1,165 +1,165 @@
----
-description: Hybrid 3-Pass Code Generation pipeline. Pass 1 (Planner) → Pass 2 (Builder) → Pass 3 (Zero-LLM Deterministic Validator). Maximizes code generation quality while keeping prompt context hyper-efficient.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-07-30
-required-skills:
-  - clean-code
-  - codebase-design
-  - lint-and-validate
-scripts-binding:
-  - .agent/scripts/pipeline_engine.js
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/security_scan.js
----
-
-# /pipeline — Hybrid 3-Pass Code Generation
-
-$ARGUMENTS
-
----
-
-## Mandatory Pre-Flight Context Inspection
-
-Before running 3-pass pipeline generation, you MUST inspect:
-
-1. Pipeline Engine Script (`.agent/scripts/pipeline_engine.js`) → Verify availability and options (`--task`, `--file`, `--phase`)
-2. Context Token Allocation -> Keep Pass 2 builder prompt under 2,500 tokens (loading max 3 essential skill key-rules)
-3. Zero-LLM Pass 3 Validator → Run deterministic security, lint, and type checks on generated code prior to Human Gate submission
-
-4. Required Skills → Before executing, load and follow procedural rules from:
-   - `clean-code` (.agent/skills/clean-code/SKILL.md): Self-documenting naming, no over-engineering, error handling patterns
-   - `codebase-design` (.agent/skills/codebase-design/SKILL.md): Deep module design with small interfaces and clean seams
-   - `lint-and-validate` (.agent/skills/lint-and-validate/SKILL.md): ESLint, Prettier, and code quality enforcement rules
-
-## When to Use /pipeline
-
-| Use `/pipeline` when...                          | Use something else when...              |
-| :----------------------------------------------- | :-------------------------------------- |
-| Code generation quality is the top priority      | Quick single-line fix → direct edit     |
-| Context window saturation is causing weak output | Need full tribunal review → `/generate` |
-| Building UI components, APIs, or complex logic   | Exploring options → `/brainstorm`       |
-| You want maximum LLM attention on code synthesis | Planning architecture → `/plan`         |
-
----
-
-## Architecture
-
-```
-User Task → Pass 1 (Planner) → Pass 2 (Builder) → Pass 3 (Validator) → Human Gate
-              ~1,500 tokens     ~2,500 tokens       0 tokens (deterministic)
-```
-
-**vs. monolithic /generate: ~12,000–18,000 tokens in a single pass**
-
----
-
-## Phase 1 — Plan (Automatic)
-
-The pipeline engine classifies the task, detects the stack, and selects 2-3 essential skills.
-
-```bash
-node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --phase plan --output json
-```
-
-Output: Structured spec JSON with task_type, stack, essential_skills, and constraints.
-
-**Human Gate**: Review the spec before proceeding to generation.
-
----
-
-## Phase 2 — Build (Focused Generation)
-
-Assembles a minimal prompt containing ONLY:
-
-- The spec from Phase 1
-- 2-3 essential skill key-rules (condensed)
-- Target file content (if modifying existing code)
-
-```bash
-node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --phase build --output prompt
-```
-
-**What is NOT in the prompt (saving ~10,000 tokens):**
-
-- ❌ Full GEMINI.md master rules
-- ❌ Agent persona definitions
-- ❌ Tribunal gate rules
-- ❌ Error recovery protocol
-- ❌ Fabel Protocol cognitive loops
-- ❌ Unrelated domain skills
-
-The LLM receives a clean, focused prompt and can dedicate 75%+ of its attention to generating high-quality code.
-
----
-
-## Phase 3 — Validate (Zero-LLM Deterministic)
-
-After code is generated, run deterministic validation:
-
-```bash
-node .agent/scripts/pipeline_engine.js --phase validate --code ./output.tsx
-```
-
-Checks:
-
-- ✅ OWASP security patterns (eval, innerHTML, hardcoded secrets, SQL injection)
-- ✅ TypeScript `any` usage
-- ✅ Empty catch blocks
-- ✅ Console.log pollution
-- ✅ Error handling gaps
-
-If validation fails → structured feedback is generated for automated retry (max 3 attempts).
-
----
-
-## Full Pipeline (All Phases)
-
-```bash
-node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --output report
-```
-
-Or in dry-run mode:
-
-```bash
-node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --dry-run
-```
-
----
-
-## Pipeline Guard
-
-```
-❌ Never load GEMINI.md into Pass 2 — the planner already distilled what's needed
-❌ Never skip Pass 3 validation — it's zero-cost (no LLM calls)
-❌ Never select more than 3 skills for a single generation pass
-❌ Never inject agent persona definitions into the builder prompt
-❌ Never bypass the Human Gate — even in pipeline mode
-```
-
----
-
-## Comparison: /generate vs /pipeline
-
-| Dimension                    | `/generate` (current) | `/pipeline` (new)      |
-| :--------------------------- | :-------------------- | :--------------------- |
-| System prompt tokens         | ~12,000–18,000        | ~2,500 (Pass 2)        |
-| % context for actual task    | ~11%                  | ~75%                   |
-| Governance overhead          | ~89%                  | ~25%                   |
-| Post-gen validation          | LLM-based (expensive) | Deterministic (free)   |
-| Skills loaded per generation | 6–10                  | 2–3                    |
-| Self-healing retry           | Full re-generation    | Targeted feedback loop |
-| Backward compatibility       | N/A                   | 100% (additive)        |
-
----
-
-## After /pipeline — Next Steps
-
-| Outcome                      | Next Command                       |
-| :--------------------------- | :--------------------------------- |
-| Code generated, needs review | → `/review` for human audit        |
-| Code has issues after retry  | → `/generate` with full tribunal   |
-| Code passed, ready to test   | → `/test` for test generation      |
-| Code passed, ready to deploy | → `/deploy` with pre-flight checks |
-
----
+---
+description: Hybrid 3-Pass Code Generation pipeline. Pass 1 (Planner) → Pass 2 (Builder) → Pass 3 (Zero-LLM Deterministic Validator). Maximizes code generation quality while keeping prompt context hyper-efficient.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 3.0.0
+last-updated: 2026-07-30
+required-skills:
+  - clean-code
+  - codebase-design
+  - lint-and-validate
+scripts-binding:
+  - .agent/scripts/pipeline_engine.js
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/security_scan.js
+---
+
+# /pipeline — Hybrid 3-Pass Code Generation
+
+$ARGUMENTS
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Before running 3-pass pipeline generation, you MUST inspect:
+
+1. Pipeline Engine Script (`.agent/scripts/pipeline_engine.js`) → Verify availability and options (`--task`, `--file`, `--phase`)
+2. Context Token Allocation -> Keep Pass 2 builder prompt under 2,500 tokens (loading max 3 essential skill key-rules)
+3. Zero-LLM Pass 3 Validator → Run deterministic security, lint, and type checks on generated code prior to Human Gate submission
+
+4. Required Skills → Before executing, load and follow procedural rules from:
+   - `clean-code` (.agent/skills/clean-code/SKILL.md): Self-documenting naming, no over-engineering, error handling patterns
+   - `codebase-design` (.agent/skills/codebase-design/SKILL.md): Deep module design with small interfaces and clean seams
+   - `lint-and-validate` (.agent/skills/lint-and-validate/SKILL.md): ESLint, Prettier, and code quality enforcement rules
+
+## When to Use /pipeline
+
+| Use `/pipeline` when...                          | Use something else when...              |
+| :----------------------------------------------- | :-------------------------------------- |
+| Code generation quality is the top priority      | Quick single-line fix → direct edit     |
+| Context window saturation is causing weak output | Need full tribunal review → `/generate` |
+| Building UI components, APIs, or complex logic   | Exploring options → `/brainstorm`       |
+| You want maximum LLM attention on code synthesis | Planning architecture → `/plan`         |
+
+---
+
+## Architecture
+
+```
+User Task → Pass 1 (Planner) → Pass 2 (Builder) → Pass 3 (Validator) → Human Gate
+              ~1,500 tokens     ~2,500 tokens       0 tokens (deterministic)
+```
+
+**vs. monolithic /generate: ~12,000–18,000 tokens in a single pass**
+
+---
+
+## Phase 1 — Plan (Automatic)
+
+The pipeline engine classifies the task, detects the stack, and selects 2-3 essential skills.
+
+```bash
+node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --phase plan --output json
+```
+
+Output: Structured spec JSON with task_type, stack, essential_skills, and constraints.
+
+**Human Gate**: Review the spec before proceeding to generation.
+
+---
+
+## Phase 2 — Build (Focused Generation)
+
+Assembles a minimal prompt containing ONLY:
+
+- The spec from Phase 1
+- 2-3 essential skill key-rules (condensed)
+- Target file content (if modifying existing code)
+
+```bash
+node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --phase build --output prompt
+```
+
+**What is NOT in the prompt (saving ~10,000 tokens):**
+
+- ❌ Full GEMINI.md master rules
+- ❌ Agent persona definitions
+- ❌ Tribunal gate rules
+- ❌ Error recovery protocol
+- ❌ Fabel Protocol cognitive loops
+- ❌ Unrelated domain skills
+
+The LLM receives a clean, focused prompt and can dedicate 75%+ of its attention to generating high-quality code.
+
+---
+
+## Phase 3 — Validate (Zero-LLM Deterministic)
+
+After code is generated, run deterministic validation:
+
+```bash
+node .agent/scripts/pipeline_engine.js --phase validate --code ./output.tsx
+```
+
+Checks:
+
+- ✅ OWASP security patterns (eval, innerHTML, hardcoded secrets, SQL injection)
+- ✅ TypeScript `any` usage
+- ✅ Empty catch blocks
+- ✅ Console.log pollution
+- ✅ Error handling gaps
+
+If validation fails → structured feedback is generated for automated retry (max 3 attempts).
+
+---
+
+## Full Pipeline (All Phases)
+
+```bash
+node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --output report
+```
+
+Or in dry-run mode:
+
+```bash
+node .agent/scripts/pipeline_engine.js --task "$TASK" --file "$FILE" --dry-run
+```
+
+---
+
+## Pipeline Guard
+
+```
+❌ Never load GEMINI.md into Pass 2 — the planner already distilled what's needed
+❌ Never skip Pass 3 validation — it's zero-cost (no LLM calls)
+❌ Never select more than 3 skills for a single generation pass
+❌ Never inject agent persona definitions into the builder prompt
+❌ Never bypass the Human Gate — even in pipeline mode
+```
+
+---
+
+## Comparison: /generate vs /pipeline
+
+| Dimension                    | `/generate` (current) | `/pipeline` (new)      |
+| :--------------------------- | :-------------------- | :--------------------- |
+| System prompt tokens         | ~12,000–18,000        | ~2,500 (Pass 2)        |
+| % context for actual task    | ~11%                  | ~75%                   |
+| Governance overhead          | ~89%                  | ~25%                   |
+| Post-gen validation          | LLM-based (expensive) | Deterministic (free)   |
+| Skills loaded per generation | 6–10                  | 2–3                    |
+| Self-healing retry           | Full re-generation    | Targeted feedback loop |
+| Backward compatibility       | N/A                   | 100% (additive)        |
+
+---
+
+## After /pipeline — Next Steps
+
+| Outcome                      | Next Command                       |
+| :--------------------------- | :--------------------------------- |
+| Code generated, needs review | → `/review` for human audit        |
+| Code has issues after retry  | → `/generate` with full tribunal   |
+| Code passed, ready to test   | → `/test` for test generation      |
+| Code passed, ready to deploy | → `/deploy` with pre-flight checks |
+
+---