tribunal-kit 2.4.6 → 3.0.0

package/.agent/workflows/fix.md

@@ -1,143 +1,135 @@
----
-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
-```
+---
+description: Auto-fix known issues with lint, formatting, imports, and TypeScript errors. Runs lint_runner.py and auto-fixers. Human approval required before applying any changes. Shows a diff of what will change before writing to disk.
+---
+
+# /fix — Automated Error Resolution
+
+$ARGUMENTS
+
+---
+
+## When to Use /fix
+
+| Use `/fix` when... | Use something else when... |
+|:---|:---|
+| Lint errors blocking CI | Logic bugs → `/debug` |
+| TypeScript type errors | Feature changes needed → `/enhance` |
+| Formatting inconsistencies | Security vulnerabilities → `/tribunal-backend` |
+| Missing imports auto-detectable | Structural changes → `/refactor` |
+| After a dependency version upgrade breaks types | |
+
+---
+
+## What /fix Handles (Auto-Fixable)
+
+```
+✅ AUTO-FIXABLE:
+│ ESLint  → eslint --fix (formatting, unused imports, style)
+│ Prettier → prettier --write (spacing, quotes, semicolons)
+│ TypeScript → add missing required imports visible from types
+│ Tailwind → class ordering (prettier-plugin-tailwindcss)
+│ npm audit → npm audit fix (non-breaking dependency patches)
+
+⚠️ REQUIRES HUMAN DECISION:
+│ TypeScript strict mode errors (may require type narrowing by developer)
+│ Breaking API changes after major version bump
+│ Logic errors flagged by ESLint (not just style)
+│ Security vulnerabilities (audit fix --force changes major versions)
+```
+
+---
+
+## Execution Sequence
+
+```bash
+# 1. Run lint with auto-fix
+python .agent/scripts/lint_runner.py . --fix
+
+# 2. Fix remaining TypeScript errors (auto-detectable only)
+npx tsc --noEmit 2>&1 | grep "error TS"
+
+# 3. Format all files
+npx prettier --write "src/**/*.{ts,tsx,js,json,css}"
+
+# 4. Check npm audit (report, don't auto-fix without approval)
+npm audit --audit-level=high
+```
+
+---
+
+## Human Gate — Review Diff Before Applying
+
+After running fixers:
+
+```
+━━━ Fix Preview ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Files that will change:
+  src/components/Button.tsx        (lint: 3 unused imports removed)
+  src/lib/auth.ts                  (lint: missing semicolons, trailing whitespace)
+  src/app/api/users/route.ts       (prettier: formatting)
+
+Diff preview:
+  --- src/components/Button.tsx
+  +++ src/components/Button.tsx
+  - import { useState, useEffect, useCallback } from 'react'; // useEffect unused
+  + import { useState, useCallback } from 'react';
+
+━━━ Remaining Errors (Need Human Review) ━━━
+
+  src/lib/payment.ts:34 — TS2345: Argument of type 'string | null' not assignable to 'string'
+  → This requires deliberate type narrowing — cannot auto-fix safely
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Apply auto-fixes?  Y = write to disk | N = discard | S = select specific files
+```
+
+**No files are written without explicit "Y" approval.**
+
+---
+
+## Fix Guard
+
+```
+❌ Never run --force on npm audit fix without human approval (can break major APIs)
+❌ Never auto-fix TypeScript errors that require business logic decisions
+❌ Never apply lint fixes to generated test files without human review
+❌ Never "fix" ESLint disable comments — they may be intentional suppressions
+❌ Never mix fix + refactoring in the same run
+```
+
+---
+
+## After /fix — Verify
+
+```bash
+# Verify fixes didn't introduce new errors
+npx tsc --noEmit    # Must be clean
+npm test            # Must still all pass
+npm run lint        # Must be zero errors
+```
+
+If any verification step fails after fixes → report and revert auto-fixes for that file.
+
+---
+
+## Cross-Workflow Navigation
+
+| After /fix shows... | Go to |
+|:---|:---|
+| Logic errors remaining after lint | `/debug` |
+| Security issues in audit output | `/tribunal-backend` |
+| Complex type errors needing refactoring | `/refactor` |
+| After all errors fixed | `/deploy` (if pre-deploy fix) or `/generate` (if pre-generation) |
+
+---
+
+## Usage Examples
+
+```
+/fix all lint errors in src/components/
+/fix TypeScript errors after upgrading to Next.js 15
+/fix unused import warnings blocking CI
+/fix after running npm audit --audit-level=high
+/fix formatting inconsistencies across the entire src/ directory
+```

package/.agent/workflows/generate.md

@@ -1,164 +1,157 @@
----
-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)
+```
+
+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` | `dependency-reviewer` + `type-safety-reviewer` |
+| `sql`, `query`, `database`, `prisma`, `drizzle` | `sql-reviewer` |
+| `component`, `hook`, `react`, `vue`, `jsx` | `frontend-reviewer` + `type-safety-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-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` |
+| 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
+```