tribunal-kit 4.5.1 → 4.6.1

package/.agent/workflows/enhance.md

@@ -1,128 +1,154 @@
----
-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 — Feature Addition & Modification
-
-$ARGUMENTS
-
----
-
-## When to Use /enhance
-
-|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`|
-
----
-
-## Phase 1 — Impact Analysis (MANDATORY Before Any Change)
-
-Before writing any code, map what will be affected:
-
-```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"
-
-# Who references the specific function/type being changed?
-grep -r "targetFunction\|TargetType" src/ --include="*.ts" --include="*.tsx"
-```
-
-**Risk Classification:**
-
-|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|
-
----
-
-## Phase 2 — Breaking Change Detection
-
-```
-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
-```
-
-If any breaking changes are detected → document them in the plan before proceeding.
-
----
-
-## Phase 3 — Enhancement Plan
-
-```markdown
-## Enhancement: [Feature Name]
-
-Scope: [what is changing]
-Impact zone: [N files affected]
-Breaking changes: [Yes: list | None detected]
-
-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]
-```
-
-**Human Gate:** Plan presented before any editing begins.
-
----
-
-## Phase 4 — Tribunal-Reviewed Implementation
-
-Each file change goes through the Tribunal pipeline:
-
-```
-logic-reviewer:      runs on every change
-security-auditor:    runs on every change
-[domain-specific]:   activated based on change type
-```
-
-**NEVER modify files outside the defined impact zone without approval.**
-
----
-
-## Phase 5 — Consistency Verification
-
-After all changes:
-
-```
-□ 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
-```
-
----
-
-## Enhancement Guard
-
-```
-❌ 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
-```
-
----
+---
+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.
+required-skills: clean-code
+---
+
+# /enhance — Feature Addition & Modification
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE any modification:
+□ Target file              → Understand current implementation
+□ Target file's importers  → Map the impact zone (grep callers)
+□ package.json             → Verify dependencies exist
+□ tsconfig.json            → Understand path aliases and strictness
+□ Related test files        → Know what tests exist for this module
+```
+
+---
+
+## When to Use /enhance
+
+| 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` |
+
+---
+
+## Phase 1 — Impact Analysis (MANDATORY Before Any Change)
+
+Before writing any code, map what will be affected:
+
+```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"
+
+# Who references the specific function/type being changed?
+grep -r "targetFunction\|TargetType" src/ --include="*.ts" --include="*.tsx"
+```
+
+**Risk Classification:**
+
+| 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 |
+
+---
+
+## Phase 2 — Breaking Change Detection
+
+```
+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
+```
+
+If any breaking changes are detected → document them in the plan before proceeding.
+
+---
+
+## Phase 3 — Enhancement Plan
+
+```markdown
+## Enhancement: [Feature Name]
+
+Scope: [what is changing]
+Impact zone: [N files affected]
+Breaking changes: [Yes: list | None detected]
+
+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]
+```
+
+**Human Gate:** Plan presented before any editing begins.
+
+---
+
+## Phase 4 — Tribunal-Reviewed Implementation
+
+Each file change goes through the Tribunal pipeline:
+
+```
+logic-reviewer:      runs on every change
+security-auditor:    runs on every change
+[domain-specific]:   activated based on change type
+```
+
+**NEVER modify files outside the defined impact zone without approval.**
+
+---
+
+## Phase 5 — Consistency Verification
+
+After all changes:
+
+```
+□ 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
+```
+
+---
+
+## Enhancement Guard
+
+```
+❌ 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
+```
+
+---
+
+## After /enhance — Next Steps
+
+| Outcome                            | Next Command                                |
+| :--------------------------------- | :------------------------------------------ |
+| Enhancement applied, needs tests   | → `/test` for new behavior coverage         |
+| Enhancement applied, needs review  | → `/review` or `/tribunal-*` for validation |
+| Enhancement revealed deeper issues | → `/refactor` for structural improvement    |
+| Ready for deployment               | → `/deploy` with pre-flight checks          |
+
+---

package/.agent/workflows/fix.md

@@ -1,114 +1,136 @@
----
-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.
-
----
+---
+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.
+required-skills: lint-and-validate, clean-code
+---
+
+# /fix — Automated Error Resolution
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE fixing:
+□ package.json                → Identify lint/format tools and scripts
+□ tsconfig.json               → Understand strictness levels
+□ .eslintrc / prettierrc      → Understand code style rules
+```
+
+---
+
+## 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.
+
+---
+
+## After /fix — Next Steps
+
+| Outcome                     | Next Command                            |
+| :-------------------------- | :-------------------------------------- |
+| All fixed and clean         | → `/deploy` or commit code              |
+| Manual fixes needed         | → Edit files manually or use `/enhance` |
+| Fixes revealed logic errors | → `/debug` to investigate               |
+
+---