tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/enhance.md

@@ -1,139 +1,128 @@
 ---
-description: Add or update features in existing application. Used for iterative development.
+description: Add or update features in existing applications. Performs impact analysis before any code change — identifies all dependents, detects breaking changes, generates Tribunal-reviewed modifications. No change is written to disk without Human Gate approval.
 ---
 
-# /enhance — Extend What Exists
+# /enhance — Feature Addition & Modification
 
 $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.
+## When to Use /enhance
 
----
-
-## 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` |
+|Use `/enhance` when...|Use something else when...|
+|:---|:---|
+|Adding a feature to an existing codebase|Starting from scratch → `/create`|
+|Changing existing behavior|Fixing a bug → `/debug`|
+|Iterating on a recently created feature|Full architecture review → `/plan`|
+|Extending an existing API or component|Performance problems → `/tribunal-performance`|
 
 ---
 
-## First Rule: Read, Then Write
+## Phase 1 — Impact Analysis (MANDATORY Before Any Change)
 
-> Never modify code you haven't read.
-> Never modify a function without checking what calls it.
+Before writing any code, map what will be affected:
 
-The first step of every enhancement is a **reading pass** — not a writing pass.
+```bash
+# What does the target file import?
+head -30 [target-file]  # Read all imports at the top
 
----
+# Who imports the target file? (callers)
+grep -r "from '.*target-module'" src/ --include="*.ts" --include="*.tsx"
 
-## Enhancement Sequence
+# Who references the specific function/type being changed?
+grep -r "targetFunction\|TargetType" src/ --include="*.ts" --include="*.tsx"
+```
 
-### Step 1 — Map the Impact Zone
+**Risk Classification:**
 
-Before touching any file, produce this map:
+|File import count|Risk Level|Required Action|
+|:---|:---|:---|
+|0–2 importers|Low|Normal Tribunal review|
+|3–5 importers|Medium|List all affected files in plan|
+|6+ importers|High|Full dependency map + staged rollout|
 
-```
-Files to change:      [list — explicit, not "etc."]
-Functions affected:   [list — every function being modified]
-Callers of those:     [list — these must remain unbroken]
-Tests covering them:  [list — these must pass after the change]
-Exported symbols:     [list — any public API that must stay compatible]
-```
-
-> ⚠️ 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
+## Phase 2 — Breaking Change Detection
 
 ```
-Adding:      [new capability being added]
-Modifying:   [existing behavior being changed — explain why]
-Preserving:  [things that must not change — API contracts, test expectations, response formats]
+Changes that BREAK existing callers:
+□ Removing or renaming exported function/type/component
+□ Adding required (non-optional) parameter to existing function
+□ Changing a parameter type to incompatible type
+□ Changing return type to incompatible type
+□ Database schema changes (remove column, rename column, change type)
+□ API contract changes (removing fields from response)
+
+Changes that DON'T break callers:
+□ Adding optional parameter with default value
+□ Adding new exported function (existing callers unaffected)
+□ Adding nullable column to DB schema
+□ Widening return type (e.g., T → T | null)
+□ Internal implementation changes with same interface
 ```
 
-Any change to a **public interface** (function signature, API response shape, exported type) triggers an update of **all callers** — not just the changed file.
+If any breaking changes are detected → document them in the plan before proceeding.
 
-### Step 3 — Implement Through Tribunal Gate
+---
 
-| Enhancement Type | Tribunal Gate |
-|---|---|
-| 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` |
+## Phase 3 — Enhancement Plan
 
-The code goes through Tribunal **before** being shown to the user.
+```markdown
+## Enhancement: [Feature Name]
 
-### Step 4 — Regression Safety Check
+Scope: [what is changing]
+Impact zone: [N files affected]
+Breaking changes: [Yes: list | None detected]
 
-```
-□ 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
+Changes:
+1. [file-a.ts] — [what changes and why]
+2. [file-b.ts] — [downstream update required because...]
+3. [file-c.test.ts] — [test updates required]
 ```
 
-All four must be true before the enhancement is considered complete.
+**Human Gate:** Plan presented before any editing begins.
 
 ---
 
-## Response Template
-
-```
-Enhancement: [What was added or changed, in one sentence]
-
-Impact Zone:
-  Changed:         [files modified]
-  Callers updated: [files updated, or "none — interface preserved"]
+## Phase 4 — Tribunal-Reviewed Implementation
 
-Tribunal result:
-  [reviewer]: [APPROVED | REJECTED — reason]
+Each file change goes through the Tribunal pipeline:
 
-Regression risk:
-  🟢 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 or before/after]
+```
+logic-reviewer:      runs on every change
+security-auditor:    runs on every change
+[domain-specific]:   activated based on change type
 ```
 
----
-
-## Hallucination Guard
-
-- **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 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
+**NEVER modify files outside the defined impact zone without approval.**
 
 ---
 
-## Cross-Workflow Navigation
+## Phase 5 — Consistency Verification
+
+After all changes:
 
-| 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 |
+```
+□ npx tsc --noEmit — zero new TypeScript errors
+□ npm test — all existing tests still pass
+□ New tests written for the new behavior
+□ API response contracts verified not to have changed unexpectedly
+□ Database migration (if schema changed) runs cleanly
+```
 
 ---
 
-## Usage
+## Enhancement Guard
 
 ```
-/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
+❌ Never modify files outside the documented impact zone without re-running Impact Analysis
+❌ Never add a required parameter without updating all callers
+❌ Never rename an exported symbol without grepping all callers first
+❌ Never change a DB column without an expand-and-contract migration plan
+❌ Never update package versions silently — show in plan
+❌ Never "fix other things while we're here" — scope creep
 ```
+
+---

package/.agent/workflows/fix.md

@@ -1,143 +1,114 @@
 ---
-description: Auto-fix known issues with lint, formatting, imports, and TypeScript errors. Human approval required before applying.
+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 Issue Resolution
+# /fix — Automated Error 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
+
+|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||
 
 ---
 
-## When to Use /fix vs Other Commands
+## What /fix Handles (Auto-Fixable)
 
-| 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` |
+```
+✅ 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)
+```
 
 ---
 
-## What Happens
-
-### Stage 1 — Dry Run (Always First)
-
-Before fixing anything, show what would change:
+## Execution Sequence
 
 ```bash
-# Lint auto-fix dry run (show issues without applying)
-// turbo
+# 1. Run lint with auto-fix
 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)
+# 2. Fix remaining TypeScript errors (auto-detectable only)
+npx tsc --noEmit 2>&1 | grep "error TS"
 
-⚠️ 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
+# 3. Format all files
+npx prettier --write "src/**/*.{ts,tsx,js,json,css}"
 
-⏸️ Proceed with auto-fix? [Y = apply | N = cancel]
+# 4. Check npm audit (report, don't auto-fix without approval)
+npm audit --audit-level=high
 ```
 
-> ⏸️ **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
+## Human Gate — Review Diff Before Applying
 
-# Step 2: Prettier formatting
-npx prettier --write .
+After running fixers:
 
-# Step 3: Import sorting (if configured)
-npx organize-imports-cli tsconfig.json
 ```
+━━━ 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)
 
-### Stage 3 — Verify After Fix
+Diff preview:
+  --- src/components/Button.tsx
+  +++ src/components/Button.tsx
+  - import { useState, useEffect, useCallback } from 'react'; // useEffect unused
+  + import { useState, useCallback } from 'react';
 
-```bash
-# Full lint must be clean after auto-fix
-// turbo
-python .agent/scripts/lint_runner.py .
+━━━ Remaining Errors (Need Human Review) ━━━
 
-# Tests must still pass (fixes should not change behavior)
-// turbo
-python .agent/scripts/test_runner.py .
+  src/lib/payment.ts:34 — TS2345: Argument of type 'string | null' not assignable to 'string'
+  → This requires deliberate type narrowing — cannot auto-fix safely
 
-# Show git diff of all applied changes
-git diff --stat
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Apply auto-fixes?  Y = write to disk | N = discard | S = select specific files
 ```
 
-If tests fail after auto-fix → **revert immediately** and report which fix caused the failure.
+**No files are written without explicit "Y" approval.**
 
 ---
 
-## What This Does NOT Fix
+## Fix Guard
 
-| 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.
+```
+❌ 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
+```
 
 ---
 
-## 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**
-
----
+## After /fix — Verify
 
-## Cross-Workflow Navigation
+```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
+```
 
-| 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 |
+If any verification step fails after fixes → report and revert auto-fixes for that file.
 
 ---
-
-## 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
-```