tribunal-kit 1.0.0 → 2.4.2

package/.agent/workflows/enhance.md

@@ -8,7 +8,18 @@ $ARGUMENTS
 
 ---
 
-This command adds to or improves existing code without breaking what already works. Enhancement is not greenfield — the existing system shapes what can be done and how.
+This command adds to or improves existing code **without breaking what already works**. Enhancement is not greenfield — the existing system shapes what can be done and how.
+
+---
+
+## When to Use /enhance vs Other Commands
+
+| Use `/enhance` when... | Use something else when... |
+|---|---|
+| Adding to working, existing code | Building from scratch → `/create` |
+| Extending a function or module | Restructuring without new behavior → `/refactor` |
+| Adding a new endpoint to an existing API | Fixing a broken behavior → `/debug` |
+| Upgrading a component's capabilities | Auditing for problems → `/review` |
 
 ---
 
@@ -17,7 +28,7 @@ This command adds to or improves existing code without breaking what already wor
 > Never modify code you haven't read.
 > Never modify a function without checking what calls it.
 
-The first step of every enhancement is a reading pass — not a writing pass.
+The first step of every enhancement is a **reading pass** — not a writing pass.
 
 ---
 
@@ -25,67 +36,73 @@ The first step of every enhancement is a reading pass — not a writing pass.
 
 ### Step 1 — Map the Impact Zone
 
+Before touching any file, produce this map:
+
 ```
-Files to change:      [list]
-Functions affected:   [list]
+Files to change:      [list — explicit, not "etc."]
+Functions affected:   [list — every function being modified]
 Callers of those:     [list — these must remain unbroken]
-Tests currently covering them: [list]
+Tests covering them:  [list — these must pass after the change]
+Exported symbols:     [list — any public API that must stay compatible]
 ```
 
-This map must exist before any file is opened for editing.
+> ⚠️ If the impact zone spans more than 10 files, pause and confirm scope with the user before proceeding.
 
 ### Step 2 — Define What Changes vs What Stays
 
 ```
 Adding:      [new capability being added]
-Modifying:   [existing behavior being changed]
-Preserving:  [things that must not change]
+Modifying:   [existing behavior being changed — explain why]
+Preserving:  [things that must not change — API contracts, test expectations, response formats]
 ```
 
-Any change to a public interface (function signature, API response shape, exported type) triggers an update of all callers.
+Any change to a **public interface** (function signature, API response shape, exported type) triggers an update of **all callers** — not just the changed file.
 
 ### Step 3 — Implement Through Tribunal Gate
 
-| Enhancement Type | Gate |
+| Enhancement Type | Tribunal Gate |
 |---|---|
-| Backend logic | `/tribunal-backend` |
-| Frontend/UI | `/tribunal-frontend` |
-| DB queries | `/tribunal-database` |
-| Cross-domain | `/tribunal-full` |
+| Backend logic / API change | `/tribunal-backend` |
+| Frontend / UI component | `/tribunal-frontend` |
+| DB queries or schema | `/tribunal-database` |
+| Cross-domain change | `/tribunal-full` |
+| Mobile UI component | `/tribunal-mobile` |
+| Performance-critical path | `/tribunal-performance` |
 
-The code goes through Tribunal before being shown.
+The code goes through Tribunal **before** being shown to the user.
 
 ### Step 4 — Regression Safety Check
 
 ```
-Existing tests: ✅ still pass (none were broken)
-New tests added: ✅ covering new behavior
-Callers updated: ✅ if any interface changed
+□ Existing tests: still pass (none were broken by the change)
+□ New tests added: covering the new behavior
+□ Callers updated: if any interface changed, all callers are updated together
+□ TypeScript / lint: check passes after the enhancement
 ```
 
-All three must be true before the enhancement is considered complete.
+All four must be true before the enhancement is considered complete.
 
 ---
 
 ## Response Template
 
 ```
-Enhancement: [What was added/changed]
+Enhancement: [What was added or changed, in one sentence]
 
 Impact Zone:
-  Changed: [files]
-  Callers updated: [files, or "none — interface preserved"]
+  Changed:         [files modified]
+  Callers updated: [files updated, or "none — interface preserved"]
 
 Tribunal result:
   [reviewer]: [APPROVED | REJECTED — reason]
 
 Regression risk:
-  🟢 Low — new path only, no existing path changed
-  🟡 Medium — shared code modified, callers reviewed
-  🔴 High — interface changed, all callers updated
+  🟢 Low    — new path only, no existing path changed
+  🟡 Medium — shared code modified, callers reviewed and updated
+  🔴 High   — interface changed, all callers updated and verified
 
 Changes:
-  [diff]
+  [diff or before/after]
 ```
 
 ---
@@ -94,7 +111,20 @@ Changes:
 
 - **Read existing code before describing it** — never assume what a function does from its name
 - **Preserved interfaces must stay identical** — adding a required parameter breaks every caller silently
-- **Unknown patterns get `// VERIFY`** — never guess at a codebase convention
+- **Unknown patterns get `// VERIFY`** — never guess at a codebase convention or framework behavior
+- **Never delete or rename an export** without verifying all import sites are updated
+- **`// VERIFY: check method exists`** on any method call not seen in existing code or official docs
+
+---
+
+## Cross-Workflow Navigation
+
+| If during /enhance you encounter... | Go to |
+|---|---|
+| Unexpected behavior in existing code | `/debug` to root-cause before changing anything |
+| Code quality so poor it needs restructuring | `/refactor` first, then come back to `/enhance` |
+| Security vulnerability in the code you're reading | `/audit` to determine blast radius |
+| Tests don't exist for the area being changed | `/test` first to establish a baseline |
 
 ---
 
@@ -104,4 +134,6 @@ Changes:
 /enhance add pagination to the users list API endpoint
 /enhance add rate limiting to all authentication routes
 /enhance upgrade the search component to support filters
+/enhance add retry logic to the payment service's HTTP client
+/enhance extend the user model to support multiple email addresses
 ```

package/.agent/workflows/fix.md

@@ -0,0 +1,143 @@
+---
+description: Auto-fix known issues with lint, formatting, imports, and TypeScript errors. Human approval required before applying.
+---
+
+# /fix — Automated Issue Resolution
+
+$ARGUMENTS
+
+---
+
+This command runs auto-fixable checks and applies corrections. **Every fix requires human approval** — nothing is written to disk without explicit confirmation.
+
+---
+
+## When to Use /fix vs Other Commands
+
+| Use `/fix` when... | Use something else when... |
+|---|---|
+| Lint reports many auto-fixable issues | Logic bugs → `/debug` |
+| Formatting is inconsistent after a merge | Security vulnerabilities → `/audit` |
+| Dependency upgrade changed import paths | TypeScript type errors → `/generate` or manual fix |
+| Quick cleanup before a PR | Full project health check → `/audit` |
+
+---
+
+## What Happens
+
+### Stage 1 — Dry Run (Always First)
+
+Before fixing anything, show what would change:
+
+```bash
+# Lint auto-fix dry run (show issues without applying)
+// turbo
+python .agent/scripts/lint_runner.py . --fix
+
+# Prettier check (show files that would be reformatted)
+// turbo
+npx prettier --check .
+
+# TypeScript errors (does not auto-fix — reports only)
+// turbo
+npx tsc --noEmit
+```
+
+Present the dry run results to the user before touching anything:
+
+```
+📋 Auto-fixable issues found:
+  - ESLint: 12 fixable issues across 5 files
+  - Prettier: 8 files would be reformatted
+  - TypeScript: 3 unused imports (auto-fixable)
+  - TypeScript: 2 type errors (require manual fix — see below)
+
+⚠️ Manual fixes required (not auto-fixable):
+  - src/auth/jwt.ts line 34: Type 'string | undefined' is not assignable to 'string'
+  - src/db/queries.ts line 12: Property 'userId' does not exist
+
+⏸️ Proceed with auto-fix? [Y = apply | N = cancel]
+```
+
+> ⏸️ **Human Gate** — never apply fixes without explicit user approval.
+
+---
+
+### Stage 2 — Apply Fixes (After Approval)
+
+Run fixers in this order (order matters — ESLint first prevents Prettier from undoing logic changes):
+
+```bash
+# Step 1: ESLint logic fixes
+npx eslint . --fix
+
+# Step 2: Prettier formatting
+npx prettier --write .
+
+# Step 3: Import sorting (if configured)
+npx organize-imports-cli tsconfig.json
+```
+
+---
+
+### Stage 3 — Verify After Fix
+
+```bash
+# Full lint must be clean after auto-fix
+// turbo
+python .agent/scripts/lint_runner.py .
+
+# Tests must still pass (fixes should not change behavior)
+// turbo
+python .agent/scripts/test_runner.py .
+
+# Show git diff of all applied changes
+git diff --stat
+```
+
+If tests fail after auto-fix → **revert immediately** and report which fix caused the failure.
+
+---
+
+## What This Does NOT Fix
+
+| Issue type | Handled by |
+|---|---|
+| TypeScript type errors requiring logic changes | Manual fix or `/generate` |
+| Logic bugs | `/debug` |
+| Security vulnerabilities | `/audit` then `/generate` |
+| Test failures | `/debug` then `/test` |
+| Architecture issues | `/refactor` |
+
+These are reported but left for human resolution. Auto-fix never attempts these.
+
+---
+
+## Safety Rules
+
+1. **Never auto-fix without showing the diff first**
+2. **Never fix and commit in one step** — user reviews the diff before any commit
+3. **If a fix changes behavior** (not just formatting): flag it as `⚠️ This fix may change runtime behavior — review manually`
+4. **Revert on test failure** — if tests fail after fixing, undo the fix and report which change caused it
+5. **Never modify files in `node_modules` or generated output directories**
+
+---
+
+## Cross-Workflow Navigation
+
+| After /fix... | Go to |
+|---|---|
+| Lint is clean, ready for review | `/review [file]` for logic audit |
+| TypeScript errors remain after lint fix | Address manually or use `/generate` for targeted rewrite |
+| Pre-deploy cleanup complete | `/audit` for full project health check |
+
+---
+
+## Usage
+
+```
+/fix lint errors in this project
+/fix formatting across all files
+/fix unused imports and variables
+/fix all ESLint and Prettier issues before the PR
+```

package/.agent/workflows/generate.md

@@ -8,7 +8,18 @@ $ARGUMENTS
 
 ---
 
-This command runs code generation through the full Tribunal pipeline. Code reaches you only after being reviewed. Nothing is written to disk without your explicit approval.
+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` |
 
 ---
 
@@ -18,14 +29,14 @@ This command runs code generation through the full Tribunal pipeline. Code reach
 Your request
     │
     ▼
-Context read — existing files, schema, package.json scanned
+Context scan — existing files, schema, package.json read first
     │
     ▼
 Maker generates at temperature 0.1
-(grounded in context, never inventing)
+(grounded in real context — never inventing)
     │
     ▼
-Selected reviewers run in parallel
+Auto-selected reviewers run in parallel
     │
     ▼
 Human Gate — you see all verdicts and the diff
@@ -36,36 +47,56 @@ Only then: write to disk (Y) or discard (N) or revise (R)
 
 ## Who Reviews It
 
-Default (always active):
+**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:
+**Auto-activated by keywords in your request:**
 
-| Keyword | Additional Reviewer |
+| Keyword in request | Additional Reviewers Activated |
 |---|---|
-| api, route, endpoint | `dependency-reviewer` + `type-safety-reviewer` |
-| sql, query, database | `sql-reviewer` |
-| component, hook, react | `frontend-reviewer` + `type-safety-reviewer` |
-| test, spec, coverage | `test-coverage-reviewer` |
-| slow, memory, optimize | `performance-reviewer` |
+| `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 in the project's package.json
-❌ Call a method it hasn't seen documented
+❌ 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 name
+❌ 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: it writes `// VERIFY: [reason]` instead of hallucinating.
+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.
 
 ---
 
@@ -76,12 +107,20 @@ When unsure about any call: it writes `// VERIFY: [reason]` instead of hallucina
 
 Active reviewers: logic · security · [others]
 
-[Generated code]
+[Generated code with // VERIFY: tags where applicable]
 
 ━━━ Verdicts ━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-logic-reviewer:       ✅ APPROVED
-security-auditor:     ✅ APPROVED
+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 ━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -90,11 +129,36 @@ 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 function to validate and normalize email addresses
+/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
 ```

package/.agent/workflows/migrate.md

@@ -0,0 +1,163 @@
+---
+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
+```