tribunal-kit 3.1.0 → 4.0.1

package/.agent/skills/plan-writing/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Writing plans without verification criteria -> ✅ Every plan needs a 'How to verify this worked' section
+- ❌ Planning at the wrong granularity (too high or too low) -> ✅ Plans should be at the component/feature level, not line-by-line or system-wide
+- ❌ Skipping the 'What could go wrong' section -> ✅ Identifying failure modes before implementation prevents costly rework
+
+---
+
+
 # Plan Writing — Execution Blueprints Mastery
 
 ---

package/.agent/skills/platform-engineer/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Building internal platforms without talking to developers -> ✅ Platform engineering exists to reduce developer cognitive load; ask them what hurts
+- ❌ Creating golden paths that are mandatory -> ✅ Golden paths should be the easiest option, not the only option
+- ❌ Over-automating before the process is understood -> ✅ Manual first, then script, then platform; premature automation bakes in bad processes
+
+---
+
+
 # Platform Engineering — Developer Experience Mastery
 
 ---

package/.agent/skills/playwright-best-practices/SKILL.md

@@ -7,6 +7,15 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Using `page.waitForTimeout(3000)` for synchronization -> ✅ Use `page.waitForSelector()`, `expect(locator).toBeVisible()`, or auto-waiting locators
+- ❌ Using CSS selectors or XPath for test locators -> ✅ Use `getByRole()`, `getByLabel()`, `getByTestId()` for resilient selectors
+- ❌ Running tests without `--workers=1` in CI debug mode -> ✅ Parallel tests with shared state cause flaky failures; isolate tests properly
+- ❌ Not using `test.describe.configure({ mode: 'serial' })` when tests have ordering dependencies -> ✅ Explicitly mark serial when needed
+
+---
+
+
 # Playwright E2E — Bulletproof Testing Mastery
 
 ---

package/.agent/skills/project-idioms/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: project-idioms
+description: >
+  Auto-evolved skill containing project-specific architectural idioms extracted
+  from the developer's own code decisions. Generated by skill_evolution.py.
+  Commit this file to share your Engineering Culture across the team.
+  Every agent MUST respect these idioms above generic defaults.
+version: auto
+last-updated: 2026-04-09
+digest-cycles: 0
+pattern: generator
+---
+
+## Hallucination Traps (Read First)
+- ❌ Overriding project idioms without explicit justification -> ✅ Idioms represent team decisions; flag deviations with reasoning
+- ❌ Applying idioms from one project to a different project -> ✅ Idioms are project-specific; verify they apply to the current codebase
+
+---
+
+
+# Project Idioms — Auto-Evolved Skill
+
+> **Authority Level: ABSOLUTE**
+> These idioms were extracted from this project's actual code decisions.
+> They override all generic agent defaults and best practices.
+> Every agent reads this file on activation and adapts its proposals accordingly.
+
+---
+
+## How Idioms Are Born
+
+1. Developer commits code that **differs** from what the AI proposed.
+2. `skill_evolution.py digest` extracts the architectural delta (semantic filter).
+3. A minimal LLM prompt (< 500 tokens) identifies the **WHY** behind the change.
+4. The idiom is recorded here with a stable pattern + reason pair.
+5. All future code generations must align with these idioms.
+
+---
+
+## Recorded Idioms
+
+| ID | Pattern | Why This Project Uses It | Domain | Since |
+|:---|:--------|:-------------------------|:-------|:------|
+| — | — | _No idioms recorded yet. Run your first digest cycle._ | — | — |
+
+---
+
+## How to Add New Idioms
+
+Run after committing or staging a meaningful architectural change:
+
+```bash
+# Analyze staged changes (default)
+python .agent/scripts/skill_evolution.py digest
+
+# Preview without writing
+python .agent/scripts/skill_evolution.py digest --dry-run
+
+# Analyze last commit instead of staged
+python .agent/scripts/skill_evolution.py digest --head
+
+# Check current idiom count and token savings
+python .agent/scripts/skill_evolution.py status
+```
+
+---
+
+## Enforcement Rules for All Agents
+
+```
+□ Before proposing any code: scan the idiom table above
+□ If your proposal contradicts an idiom → flag it explicitly with:
+     "⚠️ Note: My proposal differs from Project Idiom #N. Reason: [explain]"
+□ Never override an idiom silently
+□ When citing an idiom in a review:
+     "Per Project Idiom #N: [pattern] — [reason]"
+□ If no idioms yet → proceed with domain-standard approaches
+```
+
+---
+
+## Digest History
+
+Last digest: `never`
+Total cycles: `0`
+
+Run `python .agent/scripts/skill_evolution.py status` to see full statistics.

package/.agent/skills/python-patterns/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-03-12
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Using `dict` for structured data when a dataclass/Pydantic model exists -> ✅ Dicts have no type safety; use typed models
+- ❌ Catching bare `except:` or `except Exception:` -> ✅ Catch specific exceptions; bare except swallows KeyboardInterrupt and SystemExit
+- ❌ Using `os.path` for path operations -> ✅ Use `pathlib.Path` for modern, readable path manipulation
+
+---
+
+
 # Python Development Principles
 
 ---

package/.agent/skills/readme-builder/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-03-19
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Starting a README with the project name as the only heading -> ✅ Lead with what the project DOES, not just what it IS
+- ❌ Skipping installation and quick-start sections -> ✅ Users need to run the project in under 60 seconds or they leave
+- ❌ Using screenshots without alt text -> ✅ All images need descriptive alt text for accessibility and broken image fallback
+
+---
+
+
 # README Builder Skill
 
 ---

package/.agent/skills/red-team-tactics/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-03-12
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Testing only happy-path authentication -> ✅ Red teaming must test token reuse, expired tokens, forged tokens, and privilege escalation
+- ❌ Reporting vulnerabilities without proof-of-concept -> ✅ Every finding needs a reproducible PoC and severity rating (CVSS)
+- ❌ Stopping after finding the first vulnerability -> ✅ Real attackers chain multiple low-severity issues; test for escalation paths
+
+---
+
+
 # Red Team & Penetration Testing Principles
 
 A red team engagement is a controlled attack.

package/.agent/skills/seo-fundamentals/SKILL.md

@@ -7,6 +7,15 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Using `<div>` for everything instead of semantic HTML -> ✅ Use `<main>`, `<article>`, `<nav>`, `<section>` for crawler comprehension
+- ❌ Multiple `<h1>` tags on a single page -> ✅ One `<h1>` per page; use `<h2>`-`<h6>` for hierarchy
+- ❌ Generating meta descriptions with AI boilerplate -> ✅ Each page needs a unique, specific meta description under 160 characters
+- ❌ Using client-side rendering for content pages -> ✅ SSR/SSG for pages that need to be indexed; CSR is invisible to crawlers without JS rendering
+
+---
+
+
 # SEO Fundamentals — Visibility & Discoverability Mastery
 
 ---

package/.agent/skills/server-management/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Running services as root -> ✅ Create a dedicated service user with minimal permissions; never run as root
+- ❌ Using password-based SSH -> ✅ Disable password auth; use SSH key pairs only with `PermitRootLogin no`
+- ❌ Editing nginx config without testing -> ✅ Always run `nginx -t` before `systemctl reload nginx`; syntax errors take down all sites
+
+---
+
+
 # Server Management — Production Linux Mastery
 
 ---

package/.agent/skills/shadcn-ui-expert/SKILL.md

@@ -7,6 +7,15 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ `import { Button } from 'shadcn-ui'` -> ✅ shadcn/ui is NOT a package; components are copied into YOUR project. Import from `@/components/ui/button`
+- ❌ Using shadcn/ui without initializing it -> ✅ Run `npx shadcn@latest init` first; it generates tailwind config and utils
+- ❌ Assuming all shadcn components are installed -> ✅ Each component must be added separately: `npx shadcn@latest add button`
+- ❌ Overriding Radix primitive props without understanding accessibility -> ✅ Radix handles focus, keyboard, and ARIA; don't break it
+
+---
+
+
 # shadcn/ui Expert — Component Architecture Mastery
 
 ---

package/.agent/skills/skill-creator/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-03-30
 applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Creating skills without frontmatter (name, description, version) -> ✅ Every SKILL.md MUST start with YAML frontmatter
+- ❌ Making skills too broad (covering multiple unrelated domains) -> ✅ One skill = one domain; split if content exceeds 10KB
+- ❌ Creating skills that duplicate existing skills -> ✅ Always check the skills directory before creating a new skill
+
+---
+
+
 # Skill Creator
 
 You are a Meta-Agent tasked with defining the capabilities of future AI agents by creating rigorous `SKILL.md` files.

package/.agent/skills/supabase-postgres-best-practices/SKILL.md

@@ -7,6 +7,15 @@ last-updated: 2026-03-30
 applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Using Supabase without enabling Row Level Security (RLS) -> ✅ ALL tables MUST have RLS enabled; without it, data is publicly accessible
+- ❌ `supabase.from('users').select('*')` in client-side code without RLS -> ✅ This exposes ALL rows to ALL users; add RLS policies first
+- ❌ Storing API keys in client-side JavaScript -> ✅ The `anon` key is public by design; protect data with RLS, not key secrecy
+- ❌ Using Supabase Edge Functions for compute-heavy tasks -> ✅ Edge Functions have 150ms CPU time limit; use server functions for heavy work
+
+---
+
+
 # Supabase & Postgres Best Practices
 
 You are a Supabase Data Architect. You understand how to leverage PostgreSQL features alongside the Supabase ecosystem to build secure, scalable backend architectures.

package/.agent/skills/swiftui-expert/SKILL.md

@@ -7,6 +7,15 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Using `@State` for shared data between views -> ✅ `@State` is local to a view; use `@Binding`, `@Environment`, or `@Observable` for sharing
+- ❌ Putting heavy computation in the `body` property -> ✅ `body` is called on EVERY re-render; move computation to `.task {}` or `onChange`
+- ❌ `List { ForEach(items) { ... } }` without `id:` parameter -> ✅ Always provide `id:` for `Identifiable` conformance or use `\.self`
+- ❌ Using `NavigationView` -> ✅ Deprecated in iOS 16+; use `NavigationStack` or `NavigationSplitView`
+
+---
+
+
 # SwiftUI Expert — Native Apple Platforms Mastery
 
 ---

package/.agent/skills/systematic-debugging/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Changing multiple things at once to fix a bug -> ✅ Change ONE variable at a time; multiple changes make it impossible to identify the fix
+- ❌ Assuming the bug is where the error message points -> ✅ The error location is often downstream; trace UP the call stack to find root cause
+- ❌ Not reproducing the bug before attempting a fix -> ✅ If you cannot reproduce it reliably, you cannot verify your fix works
+
+---
+
+
 # Systematic Debugging — Root Cause Mastery
 
 ---

package/.agent/skills/tdd-workflow/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Writing tests that test implementation details instead of behavior -> ✅ Test WHAT it does (inputs/outputs), not HOW (internal methods)
+- ❌ Skipping the Red phase (writing a failing test first) -> ✅ If the test passes before you write the code, it tests nothing
+- ❌ Refactoring during the Red or Green phase -> ✅ Red: write failing test. Green: make it pass minimally. THEN refactor. Never mix phases
+
+---
+
+
 # Test-Driven Development (TDD) — Defect-Free Execution Mastery
 
 ---

package/.agent/skills/ui-ux-pro-max/SKILL.md

@@ -6,6 +6,14 @@ last-updated: 2026-03-12
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Using purple/violet as primary color -> ✅ #1 AI design cliche; choose signal orange, deep red, teal, or warm neutrals
+- ❌ Default hero layout (left text, right image) without justification -> ✅ Break the template; asymmetry, full-bleed, or typographic approaches
+- ❌ Mesh gradient backgrounds as 'premium' -> ✅ Use grain, solid contrast, or depth instead; mesh gradients are the new stock photo
+
+---
+
+
 # UI/UX Pro Max: Peak Performance Frontend Aesthetics
 
 This skill guides the creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

package/.agent/skills/web-accessibility-auditor/SKILL.md

@@ -7,6 +7,15 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Adding `role='button'` to a `<div>` instead of using `<button>` -> ✅ Native HTML elements have built-in keyboard and screen reader support
+- ❌ Using `aria-label` on elements that already have visible text -> ✅ Redundant ARIA overrides visible text for screen readers; use only when needed
+- ❌ Color as the only indicator of state -> ✅ Always pair color with icon, text, or pattern for colorblind users (1 in 12 males)
+- ❌ Assuming accessibility is a checklist to run at the end -> ✅ Build accessible from the start; retrofitting is 10x more expensive
+
+---
+
+
 # Web Accessibility (a11y) — Inclusive UI Mastery
 
 ---

package/.agent/skills/web-design-guidelines/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-03-12
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Designing mobile-last (desktop first, then shrinking) -> ✅ Design mobile-first, then enhance for larger screens
+- ❌ Using more than 2-3 font families -> ✅ Stick to 1-2 font families maximum; more creates visual noise
+- ❌ Ignoring touch target sizes on mobile -> ✅ Minimum 44x44px touch targets (Apple HIG) / 48x48dp (Material Design)
+
+---
+
+
 # Next-Gen Web Interface Review Guidelines (Pro-Max Level)
 
 ---

package/.agent/skills/webapp-testing/SKILL.md

@@ -7,6 +7,14 @@ last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
+## Hallucination Traps (Read First)
+- ❌ Mocking everything in integration tests -> ✅ Integration tests verify real interactions; mock only external services (APIs, DBs)
+- ❌ Testing Library: using `getByTestId` as the primary selector -> ✅ Prefer `getByRole`, `getByLabelText`, `getByText` for user-centric testing
+- ❌ Writing E2E tests that depend on seed data -> ✅ Each test should create its own data in setup and clean up in teardown
+
+---
+
+
 # Webapp Testing — Full Stack Pipeline Mastery
 
 ---

package/.agent/workflows/generate.md

@@ -73,6 +73,7 @@ When unsure: write `// VERIFY: [specific reason]` instead of hallucinating.
 
 **Always active:**
 ```
+precedence-reviewer→ Enforces repository Case Law and past rejections (Runs First)
 logic-reviewer     → Hallucinated methods, undefined refs, impossible logic
 security-auditor   → OWASP vulnerabilities, hardcoded secrets, injection
 ```

package/.agent/workflows/tribunal-backend.md

@@ -22,7 +22,8 @@ $ARGUMENTS
 
 ## 4 Active Reviewers (All Run Simultaneously)
 
-### logic-reviewer
+### precedence-reviewer    → Checks local repo Case Law for past rejections
+logic-reviewer
 - Hallucinated Express/Hono/Fastify methods
 - Missing awaits on async operations
 - Unreachable code after return statements

package/.agent/workflows/tribunal-database.md

@@ -22,7 +22,8 @@ $ARGUMENTS
 
 ## 3 Active Reviewers (All Run Simultaneously)
 
-### logic-reviewer
+### precedence-reviewer    → Checks local repo Case Law for past rejections
+logic-reviewer
 - Prisma methods that don't exist (`findOne` was removed — use `findUnique`)
 - Transaction that should be `$transaction` but isn't
 - Pagination query missing total count (returns wrong metadata)

package/.agent/workflows/tribunal-frontend.md

@@ -22,7 +22,8 @@ $ARGUMENTS
 
 ## 4 Active Reviewers (All Run Simultaneously)
 
-### logic-reviewer
+### precedence-reviewer    → Checks local repo Case Law for past rejections
+logic-reviewer
 - Hallucinated React 19 hooks (non-existent hook names)
 - useFormState called instead of useActionState (React 19 rename)
 - useEffect missing dependencies (stale closure)

package/.agent/workflows/tribunal-full.md

@@ -24,6 +24,7 @@ $ARGUMENTS
 
 ```
 Tier 1: Always active (universal concerns)
+├── precedence-reviewer    → Checks local repo Case Law for past rejections
 ├── logic-reviewer         → Hallucinated methods, impossible logic, undefined refs
 └── security-auditor       → OWASP 2025, injection, JWT, SSRF, IDOR
 

package/.agent/workflows/tribunal-mobile.md

@@ -22,7 +22,8 @@ $ARGUMENTS
 
 ## 3 Active Reviewers (All Run Simultaneously)
 
-### logic-reviewer
+### precedence-reviewer    → Checks local repo Case Law for past rejections
+logic-reviewer
 - `runOnJS` called inside `onUpdate` instead of `onEnd` (runs every frame)
 - Missing `'worklet'` directive on functions called inside Reanimated
 - FlatList inside ScrollView (disables virtualization)

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

@@ -22,7 +22,8 @@ $ARGUMENTS
 
 ## 2 Active Reviewers (Both Run Simultaneously)
 
-### logic-reviewer
+### precedence-reviewer    → Checks local repo Case Law for past rejections
+logic-reviewer
 - Expensive computation in render function (runs every render)
 - Missing memoization where React.memo/useMemo would help
 - Infinite re-render loop (effect updates a value that triggers the effect)

package/README.md

@@ -7,7 +7,7 @@
 
   [![NPM](https://img.shields.io/npm/v/tribunal-kit?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/tribunal-kit)
   [![License](https://img.shields.io/badge/License-MIT-8b5cf6?style=for-the-badge)](LICENSE)
-  [![Version](https://img.shields.io/badge/Version-3.0.0-black?style=for-the-badge)](CHANGELOG.md)
+  [![Version](https://img.shields.io/badge/Version-4.0.0_Supreme_Court-black?style=for-the-badge)](CHANGELOG.md)
 </div>
 
 
@@ -59,6 +59,22 @@ No manual tagging required. The system self-organizes.
 
 <br>
 
+## ▓▒░ THE SUPREME COURT (v4.0)
+
+*(New in v4)* The Tribunal Kit now features persistent memory so the AI **never makes the same mistake twice** and automatically learns your team's coding style.
+
+**1. The Case Law Engine (Never repeat mistakes)**
+If an agent makes a mistake, you can record it as a legal precedent. Before writing any future code, the `precedence-reviewer` checks this database locally to forcefully block the AI from repeating that mistake.
+- `npx tribunal-kit case add` *(Record an AI hallucination)*
+- `npx tribunal-kit case search "query"` *(Search your precedents)*
+
+**2. Skill Evolution Forge (Auto-learns your style)**
+You no longer need to write manual rules. The system reads your Git commits, strips out the noise to save tokens, and automatically extracts your project's unique architectural patterns to teach the AI.
+- `npx tribunal-kit learn` *(Run a learning digest on staged files)*
+- `npx tribunal-kit hook` *(Automate learning every time you `git push`)*
+
+<br>
+
 ## ▓▒░ CAPABILITY MATRIX
 
 | System Asset | Count | Operational Scope |
@@ -117,6 +133,19 @@ Unleash parallel reviewers on existing code.
 
 </details>
 
+<details>
+<summary><b>⚖️ SUPREME COURT / MEMORY</b></summary>
+<br>
+
+| Command | Action |
+| :--- | :--- |
+| <code>npx tribunal-kit case add</code> | Record an AI hallucination to ban it forever. |
+| <code>npx tribunal-kit case search</code> | Search your local database of banned code. |
+| <code>npx tribunal-kit learn</code> | Auto-extract project idioms from your git diffs. |
+| <code>npx tribunal-kit hook</code> | Install a git hook to auto-learn the moment you push. |
+
+</details>
+
 <details>
 <summary><b>🔧 TROUBLESHOOTING & OPS</b></summary>
 <br>