tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/generate.md

@@ -1,164 +1,165 @@
----
-description: Generate code using the full Tribunal Anti-Hallucination pipeline. Maker generates at low temperature → selected reviewers audit in parallel → Human Gate for final approval.
----
-
-# /generate — Hallucination-Free Code Generation
-
-$ARGUMENTS
-
----
-
-This command runs code generation through the full Tribunal pipeline. Code reaches you only after being reviewed by the appropriate specialist reviewers. **Nothing is written to disk without your explicit approval.**
-
----
-
-## When to Use /generate vs Other Commands
-
-| Use `/generate` when... | Use something else when... |
-|---|---|
-| You need new code written | Existing code needs to change → `/enhance` |
-| A single focused piece of code is needed | Multi-domain build → `/swarm` or `/create` |
-| You want a safety-audited code snippet | You need a full project structure → `/create` |
-| You need a quick but safe implementation | You want to understand options first → `/plan` |
-
----
-
-## Pipeline Flow
-
-```
-Your request
-    │
-    ▼
-Context scan — existing files, schema, package.json read first
-    │
-    ▼
-Maker generates at temperature 0.1
-(grounded in real context — never inventing)
-    │
-    ▼
-Auto-selected reviewers run in parallel
-    │
-    ▼
-Human Gate — you see all verdicts and the diff
-Only then: write to disk (Y) or discard (N) or revise (R)
-```
-
----
-
-## Who Reviews It
-
-**Default (always active):**
-
-```
-logic-reviewer     → Hallucinated methods, impossible logic, undefined refs
-security-auditor   → OWASP vulnerabilities, SQL injection, hardcoded secrets
-```
-
-**Auto-activated by keywords in your request:**
-
-| Keyword in request | Additional Reviewers Activated |
-|---|---|
-| `api`, `route`, `endpoint` | `dependency-reviewer` + `type-safety-reviewer` |
-| `sql`, `query`, `database`, `orm` | `sql-reviewer` |
-| `component`, `hook`, `react`, `vue` | `frontend-reviewer` + `type-safety-reviewer` |
-| `test`, `spec`, `coverage`, `jest`, `vitest` | `test-coverage-reviewer` |
-| `slow`, `memory`, `optimize`, `cache` | `performance-reviewer` |
-| `mobile`, `react native`, `flutter` | `mobile-reviewer` |
-| `llm`, `openai`, `anthropic`, `gemini`, `ai`, `embedding` | `ai-code-reviewer` |
-| `a11y`, `wcag`, `aria`, `accessibility` | `accessibility-reviewer` |
-| `import`, `require`, `package` | `dependency-reviewer` |
-
-> If unsure which reviewers to activate, use `/tribunal-full` for maximum coverage.
-
----
-
-## What the Maker Is Not Allowed to Do
-
-```
-❌ Import a package not verified in the project's package.json
-❌ Call a method it hasn't seen in official documentation
-❌ Use `any` in TypeScript without a comment explaining why
-❌ Generate an entire application in one shot
-❌ Guess at a database column or table name
-❌ Fabricate API response shapes — read existing types first
-❌ Assume environment variables exist — reference .env.example or documented config
-```
-
-When unsure about any call: the Maker writes `// VERIFY: [reason]` instead of hallucinating.
-
----
-
-## Reviewer Verdict Meanings
-
-| Verdict | Meaning | What Happens |
-|---|---|---|
-| `✅ APPROVED` | No issues found | Code proceeds to Human Gate |
-| `⚠️ WARNING` | Non-blocking issue | Human Gate shown with warning highlighted |
-| `❌ REJECTED` | Blocking issue found | Code is revised, not shown to human |
-
-**Retry limit:** Maker is revised up to **3 times** per rejection. After 3 failed attempts, the session halts and reports to the user with the full failure history.
-
----
-
-## Output Format
-
-```
-━━━ Tribunal: [Domain] ━━━━━━━━━━━━━━━━━━
-
-Active reviewers: logic · security · [others]
-
-[Generated code with // VERIFY: tags where applicable]
-
-━━━ Verdicts ━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-logic-reviewer:           ✅ APPROVED
-security-auditor:         ✅ APPROVED
-dependency-reviewer:      ⚠️ WARNING — lodash not in package.json
-
-━━━ Warnings ━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-dependency-reviewer:
-  ⚠️ Medium — Line 3
-     lodash is imported but not listed in package.json
-     Fix: Run `npm install lodash` or use a built-in alternative
-
-━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━
-
-Write to disk?  Y = approve | N = discard | R = revise with feedback
-```
-
----
-
-## Hallucination Guard (Expanded)
-
-- **Context-first**: Maker reads `package.json`, `tsconfig.json`, and any referenced files before writing a single line
-- **No phantom imports**: Every import is verified against the project's dependencies
-- **No invented methods**: Only methods documented in the official library docs are used
-- **`// VERIFY:` on all uncertainty**: Any call that cannot be verified from existing code or official docs gets a `// VERIFY:` comment
-- **No complete app generation**: Large features are broken into reviewable modules, not dumped as a monolith
-- **Secrets stay in env**: No hardcoded credentials, keys, or tokens — ever
-
----
-
-## Cross-Workflow Navigation
-
-| If the result of /generate shows... | Go to |
-|---|---|
-| Multiple files need changing | `/enhance` for impact-zone analysis |
-| Security-critical code was touched | `/tribunal-full` for maximum coverage |
-| New DB queries are generated | `/tribunal-database` |
-| New API routes are generated | `/tribunal-backend` |
-| Tests need to be written next | `/test` |
-
----
-
-## Usage
-
-```
-/generate a JWT middleware for Express with algorithm enforcement
-/generate a Prisma query for users with their posts included
-/generate a debounced search hook in React
-/generate a parameterized SQL query for fetching paginated orders
-/generate a rate-limited fetch wrapper using p-limit
-/generate a zod schema for email + password login input
-```
+---
+description: Generate code using the full Tribunal Anti-Hallucination pipeline. Maker generates grounded in real project context at low temperature → domain-selected reviewers audit in parallel → Human Gate for final approval. Nothing is written to disk without explicit approval.
+---
+
+# /generate — Hallucination-Free Code Generation
+
+$ARGUMENTS
+
+---
+
+## When to Use /generate
+
+| Use `/generate` when... | Use something else when... |
+|:---|:---|
+| New code needs to be written from scratch | Existing code needs modification → `/enhance` |
+| A single focused piece of code is needed | Multi-domain build → `/create` or `/swarm` |
+| A safe, reviewed snippet is required | You want to understand options first → `/plan` |
+| You need a quick but Tribunal-reviewed piece | Full project structure needed → `/create` |
+
+---
+
+## Pipeline Flow
+
+```
+Your request
+    │
+    ▼
+Context scan (MANDATORY before first line of code)
+├── Read package.json → verify all imports exist
+├── Read tsconfig.json → understand strictness, paths aliases
+├── Read referenced files → understand actual data shapes
+└── Read .env.example → know available environment variables
+    │
+    ▼
+Maker generates at temperature 0.1
+├── Only methods verified in official docs
+├── Only packages in package.json
+├── // VERIFY: [reason] on any uncertain call
+└── No full application generation — modules only
+    │
+    ▼
+Reviewers run in parallel (auto-selected by keyword)
+    │
+    ▼
+Human Gate — verdicts shown + unified diff
+Y = write to disk | N = discard | R = revise with feedback
+```
+
+---
+
+## What the Maker Is Not Allowed to Do
+
+```
+❌ Import a package not in package.json
+❌ Call a method not verified in official documentation
+❌ Use TypeScript 'any' without an explanation comment
+❌ Generate an entire application in one shot
+❌ Guess at database column or table names (read schema first)
+❌ Fabricate API response shapes (read existing types first)
+❌ Assume environment variables exist (read .env.example first)
+❌ Use Next.js 14 patterns in a Next.js 15 project (check version!)
+❌ Use React 18 hooks in a React 19 project (useFormState → useActionState)
+❌ Use framer-motion v6 API in a v12 project (exitBeforeEnter → mode="wait")
+❌ Use raw useEffect for GSAP — always useGSAP from @gsap/react
+❌ Hallucinate LLM model names — verify against provider's current model list
+```
+
+When unsure: write `// VERIFY: [specific reason]` instead of hallucinating.
+
+---
+
+## Reviewer Auto-Selection
+
+**Always active:**
+```
+logic-reviewer     → Hallucinated methods, undefined refs, impossible logic
+security-auditor   → OWASP vulnerabilities, hardcoded secrets, injection
+```
+
+**Auto-activated by keywords:**
+
+| Keyword in request | Additional Reviewers |
+|:---|:---|
+| `api`, `route`, `endpoint`, `handler`, `server action` | `dependency-reviewer` + `type-safety-reviewer` |
+| `sql`, `query`, `database`, `prisma`, `drizzle`, `orm` | `sql-reviewer` |
+| `component`, `hook`, `react`, `vue`, `jsx`, `tsx` | `frontend-reviewer` + `type-safety-reviewer` |
+| `animation`, `gsap`, `framer`, `motion`, `scroll` | `frontend-reviewer` + `performance-reviewer` |
+| `test`, `spec`, `vitest`, `jest`, `playwright` | `test-coverage-reviewer` |
+| `slow`, `optimize`, `cache`, `performance`, `bundle` | `performance-reviewer` |
+| `mobile`, `react native`, `expo` | `mobile-reviewer` |
+| `llm`, `openai`, `anthropic`, `gemini`, `embedding`, `ai` | `ai-code-reviewer` |
+| `aria`, `wcag`, `a11y`, `accessibility` | `accessibility-reviewer` |
+| `import`, `package`, `npm`, `require` | `dependency-reviewer` |
+
+> For maximum safety on critical code: use `/tribunal-full` for all 11 reviewers simultaneously.
+
+---
+
+## Reviewer Verdicts
+
+| Verdict | Meaning | What Happens |
+|:---|:---|:---|
+| `✅ APPROVED` | No issues found | Proceeds to Human Gate |
+| `⚠️ WARNING` | Non-blocking issue | Human Gate shown with warning highlighted |
+| `❌ REJECTED` | Blocking issue | Maker revises before Human Gate |
+
+**Retry limit:** Maker is revised up to 3 times per REJECTED verdict. After 3 failures, the session halts and reports to the user with full failure history. No silent failures.
+
+---
+
+## Output Format
+
+```
+━━━ Tribunal: [Domain] ━━━━━━━━━━━━━━━━━━━━━━
+
+Active reviewers: logic · security · [others]
+
+[Generated code with // VERIFY: tags where uncertain]
+
+━━━ Verdicts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+logic-reviewer:      ✅ APPROVED
+security-auditor:    ✅ APPROVED  
+dependency-reviewer: ⚠️ WARNING — lodash not in package.json
+
+━━━ Warnings ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+dependency-reviewer:
+  ⚠️ Medium — Line 3: 'lodash' imported but not in package.json
+  Fix: npm install lodash  OR  use built-in Array methods
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Write to disk?  Y = approve | N = discard | R = revise with feedback
+```
+
+---
+
+## Cross-Workflow Navigation
+
+| After /generate shows... | Go to |
+|:---|:---|
+| Multiple files need changing | `/enhance` for impact-zone analysis |
+| Security-critical code was generated | `/tribunal-full` for maximum coverage |
+| DB queries were generated | `/tribunal-database` |
+| New API routes were generated | `/tribunal-backend` |
+| Animation/motion code generated | `/tribunal-frontend` |
+| Tests need to be written next | `/test` |
+| Something was rejected 3 times | Escalate to human with failure report |
+
+---
+
+## Usage Examples
+
+```
+/generate a JWT middleware for Express with HS256 algorithm enforcement
+/generate a Prisma query for users with their published posts in last 30 days
+/generate a debounced search hook in React 19 using useDeferredValue
+/generate a parameterized SQL query for paginated order history
+/generate a Zod schema for email + password + role login input
+/generate a Server Action for creating a product with image upload
+/generate a rate-limited fetch wrapper using @upstash/ratelimit
+/generate a Framer Motion page transition with shared element (layoutId)
+/generate a GSAP ScrollTrigger timeline with useGSAP React hook
+/generate an OpenAI structured output call with Zod schema validation
+```

package/.agent/workflows/migrate.md

@@ -1,163 +1,160 @@
 ---
-description: Migration workflow for framework upgrades, dependency bumps, and database migrations.
+description: Migration workflow for framework upgrades, dependency bumps, and database migrations. Impact analysis first, expand-and-contract for DB, dependency compatibility matrix before upgrading, rollback tested before deploy.
 ---
 
-# /migrate — Version & Schema Migration
+# /migrate — Safe Migration Execution
 
 $ARGUMENTS
 
 ---
 
-This command structures any migration operation — upgrading framework versions, bumping major dependencies, or running database migrations — to minimize breakage and ensure a clear rollback path.
+## When to Use /migrate
 
----
-
-## When to Use /migrate vs Other Commands
-
-| Use `/migrate` when... | Use something else when... |
-|---|---|
-| Upgrading a framework (Next.js 14 → 15) | Minor patch bumps → update `package.json` directly |
-| Bumping dependencies with breaking changes | Bug from a recent upgrade → `/debug` |
-| Creating or running database migrations | Adding a feature to existing schema → `/enhance` |
-| Switching tools entirely (Jest → Vitest) | Code restructuring only → `/refactor` |
+|Use `/migrate` when...|Use something else when...|
+|:---|:---|
+|Upgrading Next.js major version|Adding a feature → `/enhance`|
+|Upgrading React version|Schema change in existing rows → `/migrate`|
+|Database schema structural change|Simple column add → `/enhance`|
+|Changing auth libraries (next-auth v4 → v5)|Dependency patches → `/fix`|
+|Removing deprecated APIs at scale||
 
 ---
 
 ## Migration Types
 
-| Type | Examples | Key Risk |
-|---|---|---|
-| Framework major version | Next.js 14→15, React 18→19 | Removed APIs, new routing conventions |
-| Dependency breaking change | Lodash 4→5, Axios 1→2 | Changed method signatures |
-| Tool migration | Jest → Vitest, CRA → Vite | Config format, different globals |
-| Database migration | Prisma schema change, SQL column add | Data loss, downtime |
-| Language version | Python 3.10 → 3.12, Node 18 → 22 | Behavior changes, removed builtins |
+```
+Type A: Framework upgrade (Next.js 14 → 15, React 18 → 19)
+  → Audit breaking changes, update callsites, run Tribunal
+  
+Type B: Dependency major version (Prisma 5 → 6, next-auth 4 → 5)
+  → Check changelog for removed APIs, update all callsites
+  
+Type C: Database schema migration (expand-and-contract)
+  → Always in 3 phases, never destructive in one step
+
+Type D: Auth system migration
+  → Dual-write old + new, staged rollout, never big bang
+```
 
 ---
 
-## What Happens
-
-### Stage 1 — Inventory Breaking Changes
+## Phase 1 — Impact Analysis
 
-Before touching any code:
+Before any migration:
 
+```bash
+# What uses the old API?
+grep -r "getServerSideProps\|getStaticProps" src/ --include="*.ts"  # Next.js pages/ to app/
+grep -r "getServerSession\|NextAuth" src/ --include="*.ts"          # next-auth v4 to v5
+grep -r "from 'next-auth'" src/ --include="*.ts"                    # Count callsites
+grep -r "prisma\.user\.findOne" src/ --include="*.ts"               # Removed Prisma APIs
+
+# How many files will change?
+# Low risk: < 5 files
+# Medium risk: 5-20 files → plan each file explicitly
+# High risk: > 20 files → automate with codemods, not manual
 ```
-□ What is the migration? (from X to Y)
-□ Is there an official migration guide? (read it before proceeding)
-□ What are the documented breaking changes? (read the changelog)
-□ Which files in the codebase are affected? (grep for imports, config references)
-□ Is there a rollback path? (git branch, database backup, rollback command)
-□ Is the migration reversible? (some DB migrations are one-way)
-```
-
-> ⚠️ **Never start a migration without reading the official migration guide first.** If none exists, read the changelog and all GitHub "breaking change" issues.
 
 ---
 
-### Stage 2 — Plan the Migration Path
-
-Create a sequential checklist ordered by dependency:
+## Phase 2 — Breaking Change Inventory
 
 ```
-1. Update configuration files        (package.json, tsconfig, build config)
-2. Update runtime code               (imports, renamed APIs, new patterns)
-3. Handle deprecated features        (replace deprecated APIs with new equivalents)
-4. Update tests for new behavior     (new patterns, changed mocks)
-5. Run full test suite               (must pass before declaring done)
-6. Update documentation              (README, CHANGELOG)
+Framework Migration Breaking Changes (Next.js 14 → 15 example):
+□ params and searchParams are now Promises — must await
+□ cookies(), headers(), draftMode() are async — must await
+□ fetch() caching defaults changed (now no-store by default)
+□ Turbopack becomes default dev server (may affect custom configs)
+
+Auth Library Breaking Changes (next-auth v4 → v5):
+□ import { getServerSession } from 'next-auth' → import { auth } from './auth'
+□ Configuration file: pages/api/auth/[...nextauth].ts → auth.ts
+□ SessionProvider import path changed
+□ Callbacks API may have changed
 ```
 
-Each step is a **checkpoint**. If a step fails, stop and resolve before continuing.
+---
+
+## Phase 3 — Database Migrate (Expand-and-Contract Pattern)
 
-### Stage 3 — Execute Incrementally
+**NEVER do destructive schema changes in a single step on live data.**
 
 ```
-For each step in the migration plan:
-  1. Make the change
-  2. Run affected tests immediately
-  3. Verify no regressions
-  4. Commit the step (isolated commit)
-  5. Move to next step
+Step 1: EXPAND (add, never remove)
+  - Add new column (nullable)
+  - Add new table
+  - Add new foreign key
+
+Step 2: DUAL-WRITE (write to both old and new)
+  - Application writes to BOTH old_column and new_column
+  - Deploy this code before backfilling
+
+Step 3: BACKFILL (populate new structure)
+  - Fill new_column from old_column in background batches
+  - Verify: SELECT COUNT(*) WHERE new_column IS NULL should = 0
+
+Step 4: READ MIGRATION (switch reads to new)
+  - Application reads from new_column only
+  - Application still writes to both
+
+Step 5: CONTRACT (remove old)
+  - Remove writes to old_column
+  - After 1 deployment cycle → drop old_column
 ```
 
-**Rules:**
-- **One breaking change at a time** — never batch multiple incompatible changes
-- If a step requires more than **5 file changes**, break it into sub-steps
-- Tests run **after every step**, not just at the end
-- If a step breaks more than 5 tests, stop and reassess scope
+---
 
-### Stage 4 — Verify Complete Migration
+## Phase 4 — Migration Execution Order
 
 ```
-□ All tests pass
-□ Build completes without errors
-□ No remaining deprecation warnings
-□ Version updated in package.json
-□ Rollback path documented
-□ Staging environment tested (if applicable)
+□ Create git branch: git checkout -b migrate/[description]
+□ Run tests BEFORE migration: npm test (establish baseline)
+□ Apply changes in topological order (foundation files first)
+□ Run: npx tsc --noEmit (no type errors introduced)
+□ Run: npm test (all tests still pass)
+□ Run Tribunal on changed files: /tribunal-full
+□ PR review with explicit diff
+□ Deploy to staging before production
+□ Run tests in staging
+□ Human Gate: approve production deployment
 ```
 
 ---
 
-## Database Migration Specific
+## Phase 5 — Rollback Plan
 
-When running database migrations:
+Before migrating production, document the rollback:
 
-```bash
-# 1. Backup the database FIRST (even in dev)
-pg_dump mydb > backup_before_migration.sql
-
-# 2. Run Prisma schema validation
-// turbo
-python .agent/scripts/schema_validator.py .
-
-# 3. Test migration on shadow/test database first
-npx prisma migrate dev --name [migration-name]
-
-# 4. Verify data integrity after migration
-# Run custom verification queries or check row counts
-
-# 5. Document rollback SQL
-# What command reverses this migration?
 ```
+Rollback for code migration:
+  git revert [migration-commit]
+  git push origin main --force-with-lease
 
-**One-way migrations:** If a migration drops data or columns, it may be irreversible. Document this explicitly:
-
-```
-⚠️ IRREVERSIBLE: This migration drops column `users.legacy_auth_token`.
-   Rollback: Requires restoring from backup — not possible via migrate down.
+Rollback for DB migration:
+  Maintain down.sql for every migration
+  Test rollback script on staging before production migration
 ```
 
 ---
 
-## Hallucination Guard
+## Migration Guard
 
-- **Never invent migration steps** — only use documented migration guides and official changelogs
-- **Never assume backward compatibility** — verify each changed API against official docs
-- Flag undocumented behavior changes: `// VERIFY: migration guide does not mention this change`
-- **Do not remove deprecated code** until the replacement is verified working
-- **No version guessing** — specify exact versions, not ranges, unless the migration guide specifies
-
----
-
-## Cross-Workflow Navigation
-
-| After /migrate results show... | Go to |
-|---|---|
-| Tests broke after migration | `/debug` to find root cause |
-| Security issues in a new version's patterns | `/audit` for security-focused review |
-| New version uses different patterns everywhere | `/refactor` to bring code in line |
-| All tests pass, ready for deploy | `/deploy` following pre-flight checklist |
+```
+❌ Never rename a DB column in a single migration (breaks live app)
+❌ Never DROP a column in the same migration that adds the replacement
+❌ Never migrate production database and application code simultaneously
+❌ Never run a migration without first testing on a restored production backup
+❌ Never skip the backward-compatibility window (keep old code during transition)
+```
 
 ---
 
-## Usage
+## Usage Examples
 
 ```
-/migrate Next.js 14 to 15
-/migrate from Jest to Vitest
-/migrate add a new database column with Prisma
-/migrate upgrade React Router from v5 to v6
-/migrate Python 3.10 to 3.12
-/migrate from REST to tRPC
+/migrate upgrade Next.js 14 to Next.js 15 App Router
+/migrate upgrade from next-auth v4 to v5 auth.js
+/migrate add a phoneNumber field to the users table
+/migrate remove the deprecated legacy_api_key column from users
+/migrate upgrade Prisma 5 to Prisma 6 and update all breaking API calls
 ```