tribunal-kit 3.0.0 → 3.1.0

package/.agent/workflows/deploy.md

@@ -1,189 +1,180 @@
----
-description: Production deployment command. Runs pre-flight safety checks (tests, type-check, lint, security, build), creates a rollback baseline, confirms Human Gate, then executes deployment. Requires explicit human approval before going live.
----
-
-# /deploy — Production Deployment
-
-$ARGUMENTS
-
----
-
-## The Deployment Contract
-
-> "Production is the only environment that matters. Every deployment is a risk event."
-> Every step is logged. Every step has a rollback path. No surprises.
-
----
-
-## When to Use /deploy
-
-| Use `/deploy` when... | Do NOT deploy when... |
-|:---|:---|
-| All pre-flight checks pass | Any pre-flight check fails |
-| Changes are reviewed and approved | In the middle of a debug session |
-| You have a rollback plan | No tests run since last change |
-| Non-peak traffic hours (if possible) | Security audit shows critical issues |
-
----
-
-## Phase 1 — Pre-Flight Checks (ALL Must Pass)
-
-**If ANY check in Phase 1 fails → deployment is BLOCKED.**
-
-```bash
-# T-minus safety sequence (in exact order)
-
-# 1. Security: halt on critical
-python .agent/scripts/security_scan.py . --level=critical
-
-# 2. Dependencies: no exploitable CVEs
-npm audit --audit-level=high
-
-# 3. Type safety: zero errors allowed
-npx tsc --noEmit
-
-# 4. Tests: all must pass
-npm test
-
-# 5. Build: production build must succeed
-npm run build
-
-# 6. Lint: blocking errors halt deployment
-npm run lint --max-warnings=0
-```
-
-**Pre-Flight Report:**
-
-```
-━━━ Pre-Flight Status ━━━━━━━━━━━━━━━━━━━━━
-
-Security:    ✅ CLEAR | ❌ BLOCKED ([finding])
-npm audit:   ✅ CLEAR | ❌ BLOCKED ([CVE])
-TypeScript:  ✅ ZERO ERRORS | ❌ BLOCKED (N errors)
-Tests:       ✅ ALL PASS | ❌ BLOCKED (N failing)
-Build:       ✅ SUCCESS | ❌ BLOCKED (build error)
-Linting:     ✅ CLEAN | ⚠️ WARNINGS (N) | ❌ BLOCKING ERRORS (N)
-```
-
----
-
-## Phase 2 — Rollback Baseline
-
-Before deployment, capture the rollback state:
-
-```bash
-# Option A: Git baseline
-git rev-parse HEAD  # Record current commit hash
-# Rollback: git revert HEAD or git reset --hard [hash]
-
-# Option B: Tag the current release
-git tag release-$(date +%Y%m%d-%H%M%S)
-git push origin --tags
-
-# Option C: Database snapshot (if schema changed)
-pg_dump $DATABASE_URL > backup-$(date +%Y%m%d-%H%M%S).sql
-```
-
-**Rollback baseline must be confirmed before deployment begins.**
-
----
-
-## Phase 3 — Human Gate (Non-Negotiable)
-
-After pre-flight passes, present to the deployer:
-
-```
-━━━ Deployment Approval Required ━━━━━━━━━━━━━━
-
-Target environment:  [production | staging]
-Changes in this deploy:
-  [commit summary: feat/fix/chore + description]
-  [number of files changed]
-
-Database changes:    [Yes: describe migration | None]
-Breaking changes:    [Yes: describe | None]
-
-Pre-flight:          ✅ ALL CHECKS PASSED
-
-Rollback baseline:   Commit [hash] tagged as [release-name]
-Rollback command:    git reset --hard [hash]
-
-Deploy?  Y = proceed | N = abort | W = wait (deploy later)
-```
-
-**Nothing is deployed without explicit "Y" from the human.**
-
----
-
-## Phase 4 — Deployment Execution
-
-```bash
-# Deploy (platform-specific — auto-detected from project config)
-
-# → Render + GitHub Actions:
-git push origin main  # CI/CD deploys automatically
-
-# → Manual Fly.io:
-flyctl deploy --strategy rolling
-
-# → Manual Kubernetes:
-kubectl set image deployment/api api=[registry]/app:[commit-sha]
-kubectl rollout status deployment/api
-```
-
----
-
-## Phase 5 — Post-Deploy Verification
-
-Within 5 minutes of deployment completing:
-
-```bash
-# Health check
-curl -f https://api.yoursite.com/health        # Must return 200
-curl -f https://yoursite.com                   # Must load
-curl -f https://yoursite.com/api/auth/session  # Auth must work
-
-# Monitor error rate (5 minutes)
-# If error rate > 1% above baseline → initiate rollback immediately
-```
-
----
-
-## Rollback Decision Tree
-
-```
-After deploy, within 5 minutes:
-├── Error rate normal + health checks pass → ✅ Deployment successful
-├── Error rate elevated but < 1% above baseline → ⚠️ Monitor for 10 more minutes
-├── Error rate > 1% above baseline → ❌ ROLLBACK IMMEDIATELY
-└── Health check fails → ❌ ROLLBACK IMMEDIATELY
-
-Rollback command:
-  git reset --hard [baseline-commit]
-  git push origin main --force-with-lease
-```
-
----
-
-## Schema Change Deployment Pattern
-
-If this deploy includes database migrations:
-
-```
-1. Deploy migration in isolation (no application code change)
-2. Verify migration succeeded and DB is healthy
-3. THEN deploy application code that uses new schema
-```
-
-**Never deploy application code and schema changes in the same deployment.**
-
----
-
-## Cross-Workflow Navigation
-
-| Pre-flight finds... | Go to |
-|:---|:---|
-| Security vulnerability | Fix with `/tribunal-backend` first |
-| TypeScript errors | Fix with `/fix` or `/generate` first |
-| Tests failing | Fix with `/debug` and `/test` first |
-| Build failure | Fix with `/debug` first |
+---
+description: Production deployment command. Runs pre-flight safety checks (tests, type-check, lint, security, build), creates a rollback baseline, confirms Human Gate, then executes deployment. Requires explicit human approval before going live.
+---
+
+# /deploy — Production Deployment
+
+$ARGUMENTS
+
+---
+
+## The Deployment Contract
+
+"Production is the only environment that matters. Every deployment is a risk event."
+Every step is logged. Every step has a rollback path. No surprises.
+
+---
+
+## When to Use /deploy
+
+|Use `/deploy` when...|Do NOT deploy when...|
+|:---|:---|
+|All pre-flight checks pass|Any pre-flight check fails|
+|Changes are reviewed and approved|In the middle of a debug session|
+|You have a rollback plan|No tests run since last change|
+|Non-peak traffic hours (if possible)|Security audit shows critical issues|
+
+---
+
+## Phase 1 — Pre-Flight Checks (ALL Must Pass)
+
+**If ANY check in Phase 1 fails → deployment is BLOCKED.**
+
+```bash
+# T-minus safety sequence (in exact order)
+
+# 1. Security: halt on critical
+python .agent/scripts/security_scan.py . --level=critical
+
+# 2. Dependencies: no exploitable CVEs
+npm audit --audit-level=high
+
+# 3. Type safety: zero errors allowed
+npx tsc --noEmit
+
+# 4. Tests: all must pass
+npm test
+
+# 5. Build: production build must succeed
+npm run build
+
+# 6. Lint: blocking errors halt deployment
+npm run lint --max-warnings=0
+```
+
+**Pre-Flight Report:**
+
+```
+━━━ Pre-Flight Status ━━━━━━━━━━━━━━━━━━━━━
+
+Security:    ✅ CLEAR | ❌ BLOCKED ([finding])
+npm audit:   ✅ CLEAR | ❌ BLOCKED ([CVE])
+TypeScript:  ✅ ZERO ERRORS | ❌ BLOCKED (N errors)
+Tests:       ✅ ALL PASS | ❌ BLOCKED (N failing)
+Build:       ✅ SUCCESS | ❌ BLOCKED (build error)
+Linting:     ✅ CLEAN | ⚠️ WARNINGS (N) | ❌ BLOCKING ERRORS (N)
+```
+
+---
+
+## Phase 2 — Rollback Baseline
+
+Before deployment, capture the rollback state:
+
+```bash
+# Option A: Git baseline
+git rev-parse HEAD  # Record current commit hash
+# Rollback: git revert HEAD or git reset --hard [hash]
+
+# Option B: Tag the current release
+git tag release-$(date +%Y%m%d-%H%M%S)
+git push origin --tags
+
+# Option C: Database snapshot (if schema changed)
+pg_dump $DATABASE_URL > backup-$(date +%Y%m%d-%H%M%S).sql
+```
+
+**Rollback baseline must be confirmed before deployment begins.**
+
+---
+
+## Phase 3 — Human Gate (Non-Negotiable)
+
+After pre-flight passes, present to the deployer:
+
+```
+━━━ Deployment Approval Required ━━━━━━━━━━━━━━
+
+Target environment:  [production | staging]
+Changes in this deploy:
+  [commit summary: feat/fix/chore + description]
+  [number of files changed]
+
+Database changes:    [Yes: describe migration | None]
+Breaking changes:    [Yes: describe | None]
+
+Pre-flight:          ✅ ALL CHECKS PASSED
+
+Rollback baseline:   Commit [hash] tagged as [release-name]
+Rollback command:    git reset --hard [hash]
+
+Deploy?  Y = proceed | N = abort | W = wait (deploy later)
+```
+
+**Nothing is deployed without explicit "Y" from the human.**
+
+---
+
+## Phase 4 — Deployment Execution
+
+```bash
+# Deploy (platform-specific — auto-detected from project config)
+
+# → Render + GitHub Actions:
+git push origin main  # CI/CD deploys automatically
+
+# → Manual Fly.io:
+flyctl deploy --strategy rolling
+
+# → Manual Kubernetes:
+kubectl set image deployment/api api=[registry]/app:[commit-sha]
+kubectl rollout status deployment/api
+```
+
+---
+
+## Phase 5 — Post-Deploy Verification
+
+Within 5 minutes of deployment completing:
+
+```bash
+# Health check
+curl -f https://api.yoursite.com/health        # Must return 200
+curl -f https://yoursite.com                   # Must load
+curl -f https://yoursite.com/api/auth/session  # Auth must work
+
+# Monitor error rate (5 minutes)
+# If error rate > 1% above baseline → initiate rollback immediately
+```
+
+---
+
+## Rollback Decision Tree
+
+```
+After deploy, within 5 minutes:
+├── Error rate normal + health checks pass → ✅ Deployment successful
+├── Error rate elevated but < 1% above baseline → ⚠️ Monitor for 10 more minutes
+├── Error rate > 1% above baseline → ❌ ROLLBACK IMMEDIATELY
+└── Health check fails → ❌ ROLLBACK IMMEDIATELY
+
+Rollback command:
+  git reset --hard [baseline-commit]
+  git push origin main --force-with-lease
+```
+
+---
+
+## Schema Change Deployment Pattern
+
+If this deploy includes database migrations:
+
+```
+1. Deploy migration in isolation (no application code change)
+2. Verify migration succeeded and DB is healthy
+3. THEN deploy application code that uses new schema
+```
+
+**Never deploy application code and schema changes in the same deployment.**
+
+---

package/.agent/workflows/enhance.md

@@ -1,151 +1,128 @@
----
-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
-```
-
----
-
-## Cross-Workflow Navigation
-
-| After /enhance shows... | Go to |
-|:---|:---|
-| A breaking change in auth or security code | `/tribunal-backend` |
-| DB schema changes required | `/tribunal-database` |
-| Component redesign needed | `/tribunal-frontend` |
-| New tests required | `/test` |
-| Performance impact suspected | `/tribunal-performance` |
-
----
-
-## Usage Examples
-
-```
-/enhance add pagination to the /api/users endpoint
-/enhance add server-side error boundary to the dashboard page
-/enhance update the User model to add a phoneNumber field
-/enhance replace useState with useOptimistic for the like button
-/enhance add rate limiting to the POST /auth/login endpoint
-/enhance add dark mode support to the design system
-```
+---
+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
+```
+
+---