tribunal-kit 4.5.1 → 4.6.1

package/.agent/workflows/api-tester.md

@@ -1,151 +1,176 @@
----
-description: Automated multi-stage API endpoint testing. Generates and runs auth-aware request sequences (login → use token → test CRUD → verify errors). Reports response codes, schema mismatches, and unexpected data.
----
-
-# /api-tester — Automated API Testing
-
-$ARGUMENTS
-
----
-
-## When to Use /api-tester
-
-|Use `/api-tester` when...|Use something else when...|
-|:---|:---|
-|Testing REST API endpoints manually|Unit tests needed → `/test`|
-|Verifying auth token flows end-to-end|Full security audit → `/audit`|
-|After generating new endpoints|Load testing → `/performance-benchmarker`|
-|Checking response schemas||
-
----
-
-## Phase 1 — Endpoint Discovery
-
-```bash
-# Find all defined routes
-grep -r "app.get\|app.post\|app.put\|app.delete\|app.patch" src/ --include="*.ts"
-grep -r "router.get\|router.post\|router.put" src/ --include="*.ts"
-
-# Next.js Route Handlers
-find src/app/api -name "route.ts" | sort
-```
-
----
-
-## Phase 2 — Auth Flow (Token Acquisition)
-
-Before testing protected endpoints, acquire auth token:
-
-```bash
-# Acquire JWT
-curl -X POST http://localhost:3000/api/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"test@example.com","password":"testpassword"}' \
-  -s | jq '.token'
-
-# Assign to variable
-TOKEN=$(curl -X POST http://localhost:3000/api/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"test@example.com","password":"testpassword"}' \
-  -s | jq -r '.token')
-```
-
----
-
-## Phase 3 — CRUD Sequence Testing
-
-Test endpoints in the correct order (create before read, read before delete):
-
-```bash
-# 1. CREATE (POST)
-CREATE_RESPONSE=$(curl -X POST http://localhost:3000/api/users \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"Test User","email":"new@test.com"}')
-CREATED_ID=$(echo $CREATE_RESPONSE | jq -r '.id')
-echo "Created: $CREATED_ID"
-
-# 2. READ (GET)
-curl -X GET "http://localhost:3000/api/users/$CREATED_ID" \
-  -H "Authorization: Bearer $TOKEN" \
-  | jq .
-
-# 3. UPDATE (PATCH)
-curl -X PATCH "http://localhost:3000/api/users/$CREATED_ID" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"Updated Name"}'
-
-# 4. DELETE
-curl -X DELETE "http://localhost:3000/api/users/$CREATED_ID" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
----
-
-## Phase 4 — Error Case Testing
-
-Test that errors are handled correctly:
-
-```bash
-# 4xx errors (client errors — must NOT return 200!)
-echo "--- Unauthenticated request (expect 401) ---"
-curl -X GET http://localhost:3000/api/users -s -o /dev/null -w "%{http_code}\n"
-
-echo "--- Invalid ID (expect 404 or 400) ---"
-curl -X GET "http://localhost:3000/api/users/not-a-real-id" \
-  -H "Authorization: Bearer $TOKEN" \
-  -s -o /dev/null -w "%{http_code}\n"
-
-echo "--- Invalid body (expect 400) ---"
-curl -X POST http://localhost:3000/api/users \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"invalid":"field"}' \
-  -s -o /dev/null -w "%{http_code}\n"
-
-echo "--- Rate limiting (expect 429 after N requests) ---"
-for i in {1..15}; do
-  STATUS=$(curl -X POST http://localhost:3000/api/auth/login \
-    -H "Content-Type: application/json" \
-    -d '{"email":"x","password":"wrong"}' \
-    -s -o /dev/null -w "%{http_code}")
-  echo "Attempt $i: $STATUS"
-done
-```
-
----
-
-## Phase 5 — Test Report
-
-```
-━━━ API Test Report ━━━━━━━━━━━━━━━━━━━━━━
-
-Auth Flow:   ✅ Login → token acquired
-POST /users: ✅ 201 Created — id returned
-GET /users:  ✅ 200 — data matches expected schema
-PATCH /users: ✅ 200 — update reflected
-DELETE /users: ✅ 204 No Content
-
-Error Cases:
-  Unauthenticated: ✅ 401 (expected)
-  Invalid ID:      ✅ 404 (expected)
-  Invalid body:    ✅ 400 (expected) — Zod error returned
-  Rate limiting:   ✅ 429 on attempt 11 (expected)
-
-━━━ Issues Found ━━━━━━━━━━━━━━━━━━━━━━━━
-
-  ❌ GET /api/users returns 200 with no auth (should be 401)
-  ⚠️ PATCH /api/users doesn't validate Content-Type (accepts any body)
-```
-
----
-
-## Usage Examples
-
-```
-/api-tester POST /api/auth/login then test /api/users CRUD
-/api-tester test the /api/checkout flow with Stripe test card
-/api-tester verify all auth routes return 401 for unauthenticated requests
-/api-tester test rate limiting on /api/auth/login
-```
+---
+description: Automated multi-stage API endpoint testing. Generates and runs auth-aware request sequences (login → use token → test CRUD → verify errors). Reports response codes, schema mismatches, and unexpected data.
+required-skills: testing-patterns, api-patterns
+---
+
+# /api-tester — Automated API Testing
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE testing:
+□ Target endpoint files       → Understand the expected parameters and auth needs
+□ package.json                → Check testing frameworks available
+□ .env.example / .env.test     → Check for test database or mock API URLs
+```
+
+---
+
+## When to Use /api-tester
+
+| Use `/api-tester` when...             | Use something else when...                |
+| :------------------------------------ | :---------------------------------------- |
+| Testing REST API endpoints manually   | Unit tests needed → `/test`               |
+| Verifying auth token flows end-to-end | Full security audit → `/audit`            |
+| After generating new endpoints        | Load testing → `/performance-benchmarker` |
+| Checking response schemas             |                                           |
+
+---
+
+## Phase 1 — Endpoint Discovery
+
+```bash
+# Find all defined routes
+grep -r "app.get\|app.post\|app.put\|app.delete\|app.patch" src/ --include="*.ts"
+grep -r "router.get\|router.post\|router.put" src/ --include="*.ts"
+
+# Next.js Route Handlers
+find src/app/api -name "route.ts" | sort
+```
+
+---
+
+## Phase 2 — Auth Flow (Token Acquisition)
+
+Before testing protected endpoints, acquire auth token:
+
+```bash
+# Acquire JWT
+curl -X POST http://localhost:3000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"testpassword"}' \
+  -s | jq '.token'
+
+# Assign to variable
+TOKEN=$(curl -X POST http://localhost:3000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"testpassword"}' \
+  -s | jq -r '.token')
+```
+
+---
+
+## Phase 3 — CRUD Sequence Testing
+
+Test endpoints in the correct order (create before read, read before delete):
+
+```bash
+# 1. CREATE (POST)
+CREATE_RESPONSE=$(curl -X POST http://localhost:3000/api/users \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Test User","email":"new@test.com"}')
+CREATED_ID=$(echo $CREATE_RESPONSE | jq -r '.id')
+echo "Created: $CREATED_ID"
+
+# 2. READ (GET)
+curl -X GET "http://localhost:3000/api/users/$CREATED_ID" \
+  -H "Authorization: Bearer $TOKEN" \
+  | jq .
+
+# 3. UPDATE (PATCH)
+curl -X PATCH "http://localhost:3000/api/users/$CREATED_ID" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Updated Name"}'
+
+# 4. DELETE
+curl -X DELETE "http://localhost:3000/api/users/$CREATED_ID" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Phase 4 — Error Case Testing
+
+Test that errors are handled correctly:
+
+```bash
+# 4xx errors (client errors — must NOT return 200!)
+echo "--- Unauthenticated request (expect 401) ---"
+curl -X GET http://localhost:3000/api/users -s -o /dev/null -w "%{http_code}\n"
+
+echo "--- Invalid ID (expect 404 or 400) ---"
+curl -X GET "http://localhost:3000/api/users/not-a-real-id" \
+  -H "Authorization: Bearer $TOKEN" \
+  -s -o /dev/null -w "%{http_code}\n"
+
+echo "--- Invalid body (expect 400) ---"
+curl -X POST http://localhost:3000/api/users \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"invalid":"field"}' \
+  -s -o /dev/null -w "%{http_code}\n"
+
+echo "--- Rate limiting (expect 429 after N requests) ---"
+for i in {1..15}; do
+  STATUS=$(curl -X POST http://localhost:3000/api/auth/login \
+    -H "Content-Type: application/json" \
+    -d '{"email":"x","password":"wrong"}' \
+    -s -o /dev/null -w "%{http_code}")
+  echo "Attempt $i: $STATUS"
+done
+```
+
+---
+
+## Phase 5 — Test Report
+
+```
+━━━ API Test Report ━━━━━━━━━━━━━━━━━━━━━━
+
+Auth Flow:   ✅ Login → token acquired
+POST /users: ✅ 201 Created — id returned
+GET /users:  ✅ 200 — data matches expected schema
+PATCH /users: ✅ 200 — update reflected
+DELETE /users: ✅ 204 No Content
+
+Error Cases:
+  Unauthenticated: ✅ 401 (expected)
+  Invalid ID:      ✅ 404 (expected)
+  Invalid body:    ✅ 400 (expected) — Zod error returned
+  Rate limiting:   ✅ 429 on attempt 11 (expected)
+
+━━━ Issues Found ━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ❌ GET /api/users returns 200 with no auth (should be 401)
+  ⚠️ PATCH /api/users doesn't validate Content-Type (accepts any body)
+```
+
+---
+
+## Usage Examples
+
+```
+/api-tester POST /api/auth/login then test /api/users CRUD
+/api-tester test the /api/checkout flow with Stripe test card
+/api-tester verify all auth routes return 401 for unauthenticated requests
+/api-tester test rate limiting on /api/auth/login
+```
+
+---
+
+## After /api-tester — Next Steps
+
+| Outcome                     | Next Command                                        |
+| :-------------------------- | :-------------------------------------------------- |
+| Tests fail due to code bugs | → `/debug` to isolate the fix                       |
+| Tests pass, coverage needed | → `/test` to convert to automated Jest/Vitest suite |
+| API is slow                 | → `/tribunal-speed` to profile latency              |
+| Ready to ship               | → `/deploy` with full pre-flight                    |
+
+---

package/.agent/workflows/audit.md

@@ -1,127 +1,150 @@
----
-description: Full project audit combining security scan, lint, schema validation, test coverage, dependency analysis, and bundle analysis. Runs all scripts in priority order. Human review required before applying any fixes.
----
-
-# /audit — Complete Project Health Assessment
-
-$ARGUMENTS
-
----
-
-## When to Use /audit
-
-|Use `/audit` when...|Use something else when...|
-|:---|:---|
-|Before a major release or launch|Single file review → `/review`|
-|After a security incident|Just lint errors → `/fix`|
-|Onboarding to a new codebase|Performance only → `/performance-benchmarker`|
-|Weekly/monthly health check|Testing only → `/test`|
-|Before major dependency updates||
-
----
-
-## Execution Order (Fixed — Do Not Reorder)
-
-Security failures early in the pipeline halt subsequent steps. Lint/test failures continue with flags.
-
-```
-Priority 1 — Security (HALT if critical finding)
-  node .agent/scripts/security_scan.js .
-
-Priority 2 — Dependencies (HALT if exploitable CVE found)
-  node .agent/scripts/dependency_analyzer.js . --audit
-
-Priority 3 — Type Checking (CONTINUE but flag)
-  npx tsc --noEmit
-
-Priority 4 — Lint (CONTINUE but flag as deployment blocker)
-  node .agent/scripts/lint_runner.js .
-
-Priority 5 — Schema Validation (CONTINUE but flag)
-  node .agent/scripts/schema_validator.js .
-
-Priority 6 — Tests (CONTINUE but mark incomplete)
-  node .agent/scripts/test_runner.js . --coverage
-
-Priority 7 — Bundle Analysis (INFORM only)
-  node .agent/scripts/bundle_analyzer.js . --build
-```
-
-### Cascade Failure Rules
-
-|Check|Failure Behavior|
-|:---|:---|
-|Security scan (critical)|**HALT** — all subsequent steps cancelled|
-|Dependency audit (exploitable CVE)|**HALT** — fix before proceeding|
-|Lint + type errors|**CONTINUE** — flag as deployment blocker|
-|Tests failing|**CONTINUE** — mark task as incomplete|
-|Bundle analysis (large)|**INFORM** — no blocking|
-
----
-
-## Script Retry Protocol
-
-```
-Script exits 0:     Success — continue pipeline
-Script exits 1:     Failure — report and decide: retry or skip?
-Script not found:   Skip with warning — do not block pipeline
-Script times out:   Kill after 5 min — report timeout — continue
-Script crashes:     Catch exception — report stack trace — continue
-```
-
-**Hard limit: 3 retries per script.** After 3 failures, report to human and continue with remaining scripts.
-
----
-
-## Audit Report Format
-
-```
-━━━ Audit Report: [Project Name] ━━━━━━━━━━━━━━━━━━━━
-
-Score: [N/7 checks passed]
-
-1. Security Scan:         ✅ PASSED | ❌ FAILED (CRITICAL — HALTED) | ⚠️ WARNINGS
-2. Dependency Audit:      ✅ PASSED | ❌ FAILED (CVE-XXXX-XXXX found) | ⚠️ WARNINGS
-3. TypeScript:            ✅ PASSED | ❌ FAILED (N errors)
-4. Lint:                  ✅ PASSED | ❌ FAILED (N errors, M warnings)
-5. Schema Validation:     ✅ PASSED | ❌ FAILED | N/A
-6. Test Coverage:         ✅ PASSED | ❌ FAILED (N% — below 80% threshold)
-7. Bundle Size:           ✅ GOOD (310kb) | ⚠️ LARGE (>500kb) | ❌ CRITICAL (>1mb)
-
-━━━ Critical Issues (Fix Before Deploy) ━━━━━━━━━━━━━
-- [CRITICAL] SQL injection in src/routes/users.ts:47
-- [HIGH] JWT secret from hardcoded fallback in src/lib/auth.ts:12
-
-━━━ Important Issues (Fix Before Release) ━━━━━━━━━━
-- [MEDIUM] 4 TypeScript 'any' types in src/components/
-- [MEDIUM] Test coverage: 58% (target: 80%)
-
-━━━ Recommendations ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-- Update lodash 4.17.20 → 4.17.21 (Prototype pollution CVE)
-- Add @types/node to devDependencies (missing)
-- Bundle size: chart library causes +240kb — use dynamic import
-
-━━━ Suggested Next Steps ━━━━━━━━━━━━━━━━━━━━━━━━━━
-Critical items → /tribunal-backend to fix injection and JWT issues
-Test gaps → /test to add coverage for checkout and auth flows
-Bundle → /enhance to add dynamic import for chart component
-```
-
----
-
-## Human Review Gate
-
-After the audit report is produced:
-
-```
-Human Gate required before any fixes are applied.
-
-Approve a fix plan?
-Y = proceed with automated fixes where safe
-N = report only, no changes
-S = select specific items to fix
-```
-
-No files are modified without explicit approval.
-
----
+---
+description: Full project audit combining security scan, lint, schema validation, test coverage, dependency analysis, and bundle analysis. Runs all scripts in priority order. Human review required before applying any fixes.
+required-skills: vulnerability-scanner, clean-code
+---
+
+# /audit — Complete Project Health Assessment
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE auditing:
+□ package.json                → Identify all configured scripts and dependencies
+□ Config files                 → tsconfig.json, eslint.config.js, jest.config.js
+□ .agent/scripts/              → Check which audit scripts exist and are executable
+```
+
+---
+
+## When to Use /audit
+
+| Use `/audit` when...             | Use something else when...                    |
+| :------------------------------- | :-------------------------------------------- |
+| Before a major release or launch | Single file review → `/review`                |
+| After a security incident        | Just lint errors → `/fix`                     |
+| Onboarding to a new codebase     | Performance only → `/performance-benchmarker` |
+| Weekly/monthly health check      | Testing only → `/test`                        |
+| Before major dependency updates  |                                               |
+
+---
+
+## Execution Order (Fixed — Do Not Reorder)
+
+Security failures early in the pipeline halt subsequent steps. Lint/test failures continue with flags.
+
+```
+Priority 1 — Security (HALT if critical finding)
+  node .agent/scripts/security_scan.js .
+
+Priority 2 — Dependencies (HALT if exploitable CVE found)
+  node .agent/scripts/dependency_analyzer.js . --audit
+
+Priority 3 — Type Checking (CONTINUE but flag)
+  npx tsc --noEmit
+
+Priority 4 — Lint (CONTINUE but flag as deployment blocker)
+  node .agent/scripts/lint_runner.js .
+
+Priority 5 — Schema Validation (CONTINUE but flag)
+  node .agent/scripts/schema_validator.js .
+
+Priority 6 — Tests (CONTINUE but mark incomplete)
+  node .agent/scripts/test_runner.js . --coverage
+
+Priority 7 — Bundle Analysis (INFORM only)
+  node .agent/scripts/bundle_analyzer.js . --build
+```
+
+### Cascade Failure Rules
+
+| Check                              | Failure Behavior                          |
+| :--------------------------------- | :---------------------------------------- |
+| Security scan (critical)           | **HALT** — all subsequent steps cancelled |
+| Dependency audit (exploitable CVE) | **HALT** — fix before proceeding          |
+| Lint + type errors                 | **CONTINUE** — flag as deployment blocker |
+| Tests failing                      | **CONTINUE** — mark task as incomplete    |
+| Bundle analysis (large)            | **INFORM** — no blocking                  |
+
+---
+
+## Script Retry Protocol
+
+```
+Script exits 0:     Success — continue pipeline
+Script exits 1:     Failure — report and decide: retry or skip?
+Script not found:   Skip with warning — do not block pipeline
+Script times out:   Kill after 5 min — report timeout — continue
+Script crashes:     Catch exception — report stack trace — continue
+```
+
+**Hard limit: 3 retries per script.** After 3 failures, report to human and continue with remaining scripts.
+
+---
+
+## Audit Report Format
+
+```
+━━━ Audit Report: [Project Name] ━━━━━━━━━━━━━━━━━━━━
+
+Score: [N/7 checks passed]
+
+1. Security Scan:         ✅ PASSED | ❌ FAILED (CRITICAL — HALTED) | ⚠️ WARNINGS
+2. Dependency Audit:      ✅ PASSED | ❌ FAILED (CVE-XXXX-XXXX found) | ⚠️ WARNINGS
+3. TypeScript:            ✅ PASSED | ❌ FAILED (N errors)
+4. Lint:                  ✅ PASSED | ❌ FAILED (N errors, M warnings)
+5. Schema Validation:     ✅ PASSED | ❌ FAILED | N/A
+6. Test Coverage:         ✅ PASSED | ❌ FAILED (N% — below 80% threshold)
+7. Bundle Size:           ✅ GOOD (310kb) | ⚠️ LARGE (>500kb) | ❌ CRITICAL (>1mb)
+
+━━━ Critical Issues (Fix Before Deploy) ━━━━━━━━━━━━━
+- [CRITICAL] SQL injection in src/routes/users.ts:47
+- [HIGH] JWT secret from hardcoded fallback in src/lib/auth.ts:12
+
+━━━ Important Issues (Fix Before Release) ━━━━━━━━━━
+- [MEDIUM] 4 TypeScript 'any' types in src/components/
+- [MEDIUM] Test coverage: 58% (target: 80%)
+
+━━━ Recommendations ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+- Update lodash 4.17.20 → 4.17.21 (Prototype pollution CVE)
+- Add @types/node to devDependencies (missing)
+- Bundle size: chart library causes +240kb — use dynamic import
+
+━━━ Suggested Next Steps ━━━━━━━━━━━━━━━━━━━━━━━━━━
+Critical items → /tribunal-backend to fix injection and JWT issues
+Test gaps → /test to add coverage for checkout and auth flows
+Bundle → /enhance to add dynamic import for chart component
+```
+
+---
+
+## Human Review Gate
+
+After the audit report is produced:
+
+```
+Human Gate required before any fixes are applied.
+
+Approve a fix plan?
+Y = proceed with automated fixes where safe
+N = report only, no changes
+S = select specific items to fix
+```
+
+No files are modified without explicit approval.
+
+---
+
+## After /audit — Next Steps
+
+| Outcome                      | Next Command                                    |
+| :--------------------------- | :---------------------------------------------- |
+| Security/Dependency failures | → `/tribunal-backend` to implement secure fixes |
+| Lint/Type errors             | → `/fix` for automated cleanup                  |
+| Test coverage missing        | → `/test` to generate missing tests             |
+| Audit clean                  | → `/deploy` if preparing for release            |
+
+---