tribunal-kit 2.4.6 → 3.0.0

package/.agent/workflows/migrate.md

@@ -1,163 +1,160 @@
----
-description: Migration workflow for framework upgrades, dependency bumps, and database migrations.
----
-
-# /migrate — Version & Schema Migration
-
-$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 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` |
-
----
-
-## 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 |
-
----
-
-## What Happens
-
-### Stage 1 — Inventory Breaking Changes
-
-Before touching any code:
-
-```
-□ 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:
-
-```
-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)
-```
-
-Each step is a **checkpoint**. If a step fails, stop and resolve before continuing.
-
-### Stage 3 — Execute Incrementally
-
-```
-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
-```
-
-**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
-
-```
-□ All tests pass
-□ Build completes without errors
-□ No remaining deprecation warnings
-□ Version updated in package.json
-□ Rollback path documented
-□ Staging environment tested (if applicable)
-```
-
----
-
-## Database Migration Specific
-
-When running database migrations:
-
-```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?
-```
-
-**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.
-```
-
----
-
-## Hallucination 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 |
-
----
-
-## Usage
-
-```
-/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
-```
+---
+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 — Safe Migration Execution
+
+$ARGUMENTS
+
+---
+
+## When to Use /migrate
+
+| 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 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
+```
+
+---
+
+## Phase 1 — Impact Analysis
+
+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
+```
+
+---
+
+## Phase 2 — Breaking Change Inventory
+
+```
+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
+```
+
+---
+
+## Phase 3 — Database Migrate (Expand-and-Contract Pattern)
+
+**NEVER do destructive schema changes in a single step on live data.**
+
+```
+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
+```
+
+---
+
+## Phase 4 — Migration Execution Order
+
+```
+□ 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
+```
+
+---
+
+## Phase 5 — Rollback Plan
+
+Before migrating production, document the rollback:
+
+```
+Rollback for code migration:
+  git revert [migration-commit]
+  git push origin main --force-with-lease
+
+Rollback for DB migration:
+  Maintain down.sql for every migration
+  Test rollback script on staging before production migration
+```
+
+---
+
+## Migration Guard
+
+```
+❌ 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 Examples
+
+```
+/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
+```

package/.agent/workflows/orchestrate.md

@@ -1,151 +1,168 @@
----
-description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews, or tasks requiring different domain expertise.
----
-
-# /orchestrate — Multi-Agent Coordination
-
-$ARGUMENTS
-
----
-
-This command coordinates multiple specialists to solve a problem that requires more than one domain. **One agent is not orchestration.**
-
----
-
-## When to Use /orchestrate vs Other Commands
-
-| Use `/orchestrate` when... | Use something else when... |
-|---|---|
-| Task requires 3+ domain specialists | Single domain → use the right `/tribunal-*` |
-| Sequential work with review gates between waves | Parallel, independent tasks → `/swarm` |
-| Existing codebase with complex dependencies | Greenfield project → `/create` |
-| Human gates required between every wave | Maximum parallel output → `/swarm` |
-
----
-
-## The Minimum Rule
-
-> **Fewer than 3 agents = not orchestration.**
->
-> Before marking any orchestration session as complete, count the agents invoked. If the count is less than 3, activate more. A single agent delegated to is just a delegation.
-
----
-
-## Agent Selection by Task Type
-
-| Task | Required Specialists |
-|---|---|
-| Full-stack feature | `frontend-specialist` + `backend-specialist` + `test-engineer` |
-| API build | `backend-specialist` + `security-auditor` + `test-engineer` |
-| Database-heavy work | `database-architect` + `backend-specialist` + `security-auditor` |
-| Complete product | `project-planner` + `frontend-specialist` + `backend-specialist` + `devops-engineer` |
-| Security investigation | `security-auditor` + `penetration-tester` + `devops-engineer` |
-| Complex bug | `debugger` + `explorer-agent` + `test-engineer` |
-| New codebase or unknown repo | `explorer-agent` + relevant specialists |
-
----
-
-## Two-Phase Protocol (Strict)
-
-### Phase A — Planning Only
-
-Only two agents are allowed during planning:
-
-```
-project-planner   → writes docs/PLAN-{slug}.md
-explorer-agent    → (if working in existing code) maps the codebase structure
-```
-
-No other agent runs. No code is produced.
-
-After planning, the plan is shown to the user:
-
-```
-✅ Plan ready: docs/PLAN-{slug}.md
-
-Approve to start implementation? (Y / N)
-```
-
-**Phase B does NOT start without a Y.**
-
-### Phase B — Implementation (Manager & Micro-Workers)
-
-After approval, the Orchestrator acts as Manager and dispatches Micro-Workers using **isolated JSON payloads**.
-
-```
-Wave 1:  database-architect + security-auditor (JSON dispatch #1)
-         ↓
-[Wait for completion & Tribunal review]
-         ↓
-Wave 2:  backend-specialist + frontend-specialist (JSON dispatch #2)
-         ↓
-[Wait for completion & Tribunal review]
-         ↓
-Wave 3:  test-engineer (JSON dispatch #3)
-         ↓
-[Wait for completion & Human Gate]
-```
-
-Workers execute in parallel **within** their wave, but waves execute **sequentially**. Each wave waits for the previous wave's Tribunal gate before proceeding.
-
----
-
-## Hierarchical Context Pruning
-
-When dispatching workers, the Orchestrator MUST use the `dispatch_micro_workers` JSON format.
-
-**Context discipline is strictly enforced:**
-
-```
-❌ Never pass full chat histories to workers
-❌ Never attach every file — attach only files the worker will actually read
-✅ The context_summary injected by the Orchestrator is the ONLY shared context
-✅ Files attached are strictly limited to what's needed for that specific task
-```
-
-**Per-worker context limit:** Excerpt only the relevant function or schema section — never the entire file.
-
----
-
-## Retry Protocol
-
-```
-Attempt 1  → Worker runs with original parameters
-Attempt 2  → Worker runs with stricter constraints + failure feedback
-Attempt 3  → Worker runs with max constraints + full context dump
-Attempt 4  → HALT. Report to human with full failure history.
-```
-
-Hard limit: **3 retries per worker**. After 3 failures, escalate — do not silently proceed.
-
----
-
-## Hallucination Guard
-
-- Every agent's output goes through Tribunal before it reaches the user
-- The Human Gate fires before any file is written — user sees the diff and approves
-- Per-agent scope is enforced — `frontend-specialist` **never** writes DB migrations
-- Retry limit: 3 Maker revisions per agent; after 3 failures → stop and report
-- `context_summary` is the only mechanism for sharing context across agents — no full dumps
-
----
-
-## Cross-Workflow Navigation
-
-| When /orchestrate reveals... | Go to |
-|---|---|
-| Worker keeps failing after 3 retries | `/debug` the isolated worker task |
-| Plan needed before orchestrating | `/plan` first, then run `/orchestrate` against it |
-| Fully parallel independent sub-tasks | `/swarm` is more efficient |
-| Single domain needs specialist audit | Use the domain-specific `/tribunal-*` |
-
----
-
-## Usage
-
-```
-/orchestrate build a complete auth system with JWT and refresh tokens
-/orchestrate review the entire API layer for security issues
-/orchestrate build a multi-tenant SaaS onboarding flow
-/orchestrate analyze this repo and implement all security findings
-```
+---
+description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews requiring different domain expertise, or tasks where a single agent would miss domain-specific failures. Fan-Out dispatch → parallel execution → Fan-In synthesis → Human Gate.
+---
+
+# /orchestrate — Multi-Agent Coordination
+
+$ARGUMENTS
+
+---
+
+## When to Use /orchestrate
+
+| Use `/orchestrate` when... | Use something else when... |
+|:---|:---|
+| Task spans 2+ technical domains | Single domain → use specialist directly |
+| Multi-perspective review is needed | Simple code generation → `/generate` |
+| Fan-out parallelism would save time | Debugging → `/debug` (sequential by nature) |
+| One agent would miss domain failures | Planning only → `/plan` |
+
+---
+
+## Phase 1 — Scope Classification
+
+Before dispatching workers:
+
+```
+1. Is this actually multi-domain? (2+ distinct technical areas)
+   → YES → proceed to Phase 2
+   → NO  → route to the single correct specialist agent
+
+2. Can tasks be parallelized (no dependencies between them)?
+   → YES → Fan-Out dispatch (all workers simultaneous)
+   → NO  → Sequential wave dispatch
+   
+3. Context budget check:
+   □ How many files does each worker need?
+   □ Total context across all workers manageable?
+   □ Can I pass context_summary instead of full file dumps?
+```
+
+---
+
+## Phase 2 — Worker Decomposition
+
+Break the goal into atomic, non-overlapping worker tasks:
+
+```
+Goal: Review the full checkout feature before launch
+
+Decomposed Workers:
+├── Worker A [backend-specialist]: Review API routes for auth and validation
+├── Worker B [database-architect]: Review DB queries for N+1 and transactions
+├── Worker C [frontend-specialist]: Review UI components for RSC compliance
+└── Worker D [security-auditor]: Review the full checkout flow for OWASP issues
+```
+
+**Worker files cannot overlap.** If two workers both need to modify the same file → one worker owns it.
+
+---
+
+## Fan-Out Pattern (Parallel Dispatch)
+
+When tasks are independent, dispatch all simultaneously:
+
+```
+━━━ Wave 1: Fan-Out ━━━━━━━━━━━━━━━━━━━━━━━
+Worker A (backend)    → RUNNING  (reading: src/app/api/checkout/)
+Worker B (database)   → RUNNING  (reading: prisma/schema.prisma, checkout queries)
+Worker C (frontend)   → RUNNING  (reading: src/app/checkout/page.tsx)
+Worker D (security)   → RUNNING  (reading: all of the above)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Wait for ALL workers (allSettled — single worker failure doesn't cancel siblings)
+
+━━━ Wave 1: Results ━━━━━━━━━━━━━━━━━━━━━━━
+Worker A: ✅ COMPLETE
+Worker B: ✅ COMPLETE
+Worker C: ⚠️ BLOCKED (missing: what state management pattern to assume)
+Worker D: ✅ COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Supervisor provides missing info to Worker C → redispatch
+```
+
+---
+
+## BLOCKED Worker Protocol
+
+When a worker cannot proceed:
+
+```
+Status: BLOCKED
+Reason: Missing context — the auth middleware file is not in provided scope
+Unblocked by: Read src/middleware.ts first and pass auth pattern to worker
+
+Supervisor action:
+1. Provide the missing context if available
+2. Escalate to human if decision is needed
+3. Never guess — BLOCKED beats hallucinating
+```
+
+---
+
+## Sequential Wave Execution
+
+When tasks depend on each other:
+
+```
+Wave 1 → Foundation (must complete first)
+Wave 2 → Depends on Wave 1 output (receives context_summary, not full output)
+Wave 3 → Synthesis (combines all wave outputs)
+```
+
+**Context discipline between waves:** Summarize Wave N output in 3-5 bullets before passing to Wave N+1.
+
+---
+
+## Fan-In — Synthesis
+
+After all workers complete:
+
+```
+1. Merge findings by severity
+2. Identify conflicts (Worker A says X, Worker B says Y)
+3. Resolve conflicts with evidence (which worker has specific file evidence?)
+4. Produce unified output sorted by priority
+```
+
+---
+
+## Human Gate
+
+```
+━━━ Orchestration Complete ━━━━━━━━━━━━━━━━━
+
+Workers: 4 dispatched / 4 complete / 0 blocked
+
+━━━ Synthesized Findings ━━━━━━━━━━━━━━━━━━
+[Critical issues first, then high, then medium]
+
+━━━ Required Changes ━━━━━━━━━━━━━━━━━━━━━
+Files to modify: [list]
+Files to create: [list]
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Approve?  Y = proceed | N = discard | R = revise
+```
+
+---
+
+## Error Recovery
+
+```
+Worker failure (after 3 retries):
+  Report: agent=[name], task=[what], attempts=3, last_error=[error], suggestion=[what to check]
+  Action: continue remaining workers, include failure in final synthesis
+```
+
+---
+
+## Usage Examples
+
+```
+/orchestrate review the entire authentication system for security and correctness
+/orchestrate analyze the payment feature: backend logic + DB queries + frontend UX
+/orchestrate comprehensive code review before launch: security + tests + performance
+/orchestrate compare three different caching strategies and recommend the best fit
+```