tribunal-kit 9.2.4 → 9.2.6

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

@@ -1,189 +1,189 @@
----
-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.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-07-30
-required-skills:
-  - testing-patterns
-  - api-patterns
-  - backend-security-expert
-scripts-binding:
-  - .agent/scripts/test_runner.js
-  - .agent/scripts/security_scan.js
----
-
-# /api-tester — Automated API Testing
-
-$ARGUMENTS
-
----
-
-## Mandatory Pre-Flight Context Inspection
-
-Before running automated API endpoint tests or auth-aware request sequences, you MUST inspect:
-
-1. Target Route Definition & Data Schemas → Inspect route parameters, body validation schemas (Zod/Pydantic), and auth middleware
-2. Test Server URL & Credentials (`.env.test`) → Verify base URL and test token environment variables
-3. Multi-Stage Request Sequence → Enforce sequential execution: Auth Login → Token Capture → CRUD Operations → Error Edge Case Verification
-
-4. Required Skills → Before executing, load and follow procedural rules from:
-   - `testing-patterns` (.agent/skills/testing-patterns/SKILL.md): Testing Trophy strategy (unit → integration → E2E)
-   - `api-patterns` (.agent/skills/api-patterns/SKILL.md): REST/GraphQL API design, versioning, and error contracts
-   - `backend-security-expert` (.agent/skills/backend-security-expert/SKILL.md): Server-side security, auth, JWT, ORM injection, RBAC
-
----
-
-## 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                    |
-
----
+---
+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.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 3.0.0
+last-updated: 2026-07-30
+required-skills:
+  - testing-patterns
+  - api-patterns
+  - backend-security-expert
+scripts-binding:
+  - .agent/scripts/test_runner.js
+  - .agent/scripts/security_scan.js
+---
+
+# /api-tester — Automated API Testing
+
+$ARGUMENTS
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Before running automated API endpoint tests or auth-aware request sequences, you MUST inspect:
+
+1. Target Route Definition & Data Schemas → Inspect route parameters, body validation schemas (Zod/Pydantic), and auth middleware
+2. Test Server URL & Credentials (`.env.test`) → Verify base URL and test token environment variables
+3. Multi-Stage Request Sequence → Enforce sequential execution: Auth Login → Token Capture → CRUD Operations → Error Edge Case Verification
+
+4. Required Skills → Before executing, load and follow procedural rules from:
+   - `testing-patterns` (.agent/skills/testing-patterns/SKILL.md): Testing Trophy strategy (unit → integration → E2E)
+   - `api-patterns` (.agent/skills/api-patterns/SKILL.md): REST/GraphQL API design, versioning, and error contracts
+   - `backend-security-expert` (.agent/skills/backend-security-expert/SKILL.md): Server-side security, auth, JWT, ORM injection, RBAC
+
+---
+
+## 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/arch.md

@@ -0,0 +1,80 @@
+---
+description: Tribunal Architecture Intelligence — Autonomous architecture extraction, zero-trust verification, blast radius simulation, semantic diffing, and health auditing.
+---
+
+# /arch — Tribunal Architecture Intelligence
+
+Execute deterministic architecture intelligence, verification, and blast radius simulation.
+
+## Overview
+Unlike superficial diagramming tools that only generate static pictures, `/arch` treats architecture as an **executable, verifiable Evidence Graph**.
+
+```
+SOURCE CODE
+    ↓ (AST & pattern extraction)
+FACT MODEL (.agent/history/architecture-model.json)
+    ↓ (Zero-trust provenance verification)
+CONFIDENCE & CONTRADICTION GATES (L1-L5)
+    ↓ (Downstream dependency closure)
+BLAST RADIUS & RISK SIMULATION
+    ↓ (Projections: Topology, Security, Failure, Impact)
+INTERACTIVE STANDALONE EXPLORER & AUDIT REPORT
+```
+
+---
+
+## Subcommands
+
+### 1. Extract Architectural Fact Model
+```bash
+tk arch map
+# or: node .agent/scripts/architecture_extractor.js
+```
+Scans repository AST, route definitions, database models, queues, events, and auth middleware. Emits the canonical `.agent/history/architecture-model.json`.
+
+### 2. Zero-Trust Verification
+```bash
+tk arch verify [--strict]
+# or: node .agent/scripts/architecture_verifier.js
+```
+Verifies that all entity code locations, lines, symbols, and hashes match ground truth. Surfaces any architectural contradictions or drifted/stale evidence.
+
+### 3. Change Blast Radius & Impact Simulation
+```bash
+tk arch impact <component-id-or-file>
+# or: node .agent/scripts/blast_radius_engine.js <query>
+```
+Simulates the impact of changing a component: direct callers, transitive dependents across concentric depth rings, impacted API routes, affected test suites, and risk tier (LOW/MEDIUM/HIGH/CRITICAL).
+
+### 4. Semantic Architecture Diff (PR Gate)
+```bash
+tk arch diff <base-model.json> <head-model.json>
+# or: node .agent/scripts/architecture_diff.js <base> <head>
+```
+Calculates true architectural shifts:
+- Trust boundaries crossed (e.g. public route directly accessing isolated database)
+- Resilience regressions (e.g. timeouts removed from external API calls)
+- Blast radius expansions (components whose downstream impact grew >25%)
+- New external SaaS/cloud dependencies introduced
+
+### 5. Architectural Health Audit
+```bash
+tk arch audit
+# or: node .agent/scripts/architecture_health.js
+```
+Audits structural risks:
+- Circular dependencies (exact cycle chains)
+- Single Points of Failure (SPOFs / High Fan-In bottlenecks)
+- Excessive Coupling (God Modules / High Fan-Out)
+- Test coverage gaps on critical components
+
+### 6. Multi-Projection Interactive Explorer
+```bash
+tk arch project [--open]
+# or: node .agent/scripts/architecture_visualizer.js
+```
+Generates a zero-dependency, standalone HTML explorer at `.agent/history/architecture-intelligence.html` with 4 interactive projections:
+1. **Topology**: Services, routes, datastores, queues
+2. **Security**: Trust zones & authentication gates
+3. **Failure Modes**: Timeouts, retries, fallbacks
+4. **Blast Radius Simulator**: Click any node to visualize live concentric blast rings

package/.agent/workflows/assimilate.md

@@ -1,21 +1,24 @@
----
-name: assimilate
-description: "Trigger the learning pipeline to extract, validate, and store Tribunal Instincts."
-version: 1.0.0
----
-
-# ASSIMILATE (LEARNING PIPELINE)
-
-## Invocation
-`/assimilate` or `/learn`
-
-## Behavior
-Instead of learning in real-time and bloating the execution path, learning is an offline batch job.
-
-1. **Extraction**: Invokes the `memory_archivist.js` which reads the most recent session logs.
-2. **Analysis**: Searches for repeated errors, test failures, and ultimate successful fixes.
-3. **Validation**: Converts successful fixes into candidate "Tribunal Instincts".
-4. **Storage**: Saves the verified evidence-backed instinct into `instincts.json` where `context_broker.js` can retrieve it for future related tasks.
-
-## Limits
-Do not trigger this workflow automatically after every prompt. Use it specifically after a long debugging session or a complex architectural setup to persist the hard-earned lessons.
+---
+name: assimilate
+description: 'Trigger the learning pipeline to extract, validate, and store Tribunal Instincts.'
+version: 1.0.0
+---
+
+# ASSIMILATE (LEARNING PIPELINE)
+
+## Invocation
+
+`/assimilate` or `/learn`
+
+## Behavior
+
+Instead of learning in real-time and bloating the execution path, learning is an offline batch job.
+
+1. **Extraction**: Invokes the `memory_archivist.js` which reads the most recent session logs.
+2. **Analysis**: Searches for repeated errors, test failures, and ultimate successful fixes.
+3. **Validation**: Converts successful fixes into candidate "Tribunal Instincts".
+4. **Storage**: Saves the verified evidence-backed instinct into `instincts.json` where `context_broker.js` can retrieve it for future related tasks.
+
+## Limits
+
+Do not trigger this workflow automatically after every prompt. Use it specifically after a long debugging session or a complex architectural setup to persist the hard-earned lessons.

package/.agent/workflows/audit-live.md

@@ -1,53 +1,53 @@
----
-description: Live website audit using native browser automation. Audits accessibility (WCAG 2.2), console errors, network failures, Core Web Vitals, and security headers. Passes findings through Tribunal's Maker-Reviewer pipeline before proposing fixes.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 1.0.0
-last-updated: 2026-09-13
-required-skills:
-  - browser-audit
-  - web-quality-audit
-  - audit-and-fix
-scripts-binding:
-  - .agent/scripts/browser_audit.js
-  - .agent/scripts/checklist.js
----
-
-# /audit-live — Live Website Health & Accessibility Audit
-
-$ARGUMENTS
-
----
-
-## 1. Objective
-
-Audits a running local server (`http://localhost:3000`) or live staging URL using Tribunal Kit's native browser automation engine.
-
-## 2. Execution Pipeline
-
-```
-1. Ingest URL from arguments
-      │
-2. Execute Browser Audit
-   node .agent/scripts/browser_audit.js <url> --json
-      │
-3. Multi-Reviewer Fan-Out Analysis:
-   - web-quality-audit: Evaluates WCAG 2.2 AA contrast & labels
-   - frontend-specialist: Analyzes heading hierarchy & layout shifts
-   - security-auditor: Checks CSP and security headers
-      │
-4. Synthesize Prioritized Action Plan:
-   - P0: Fatal console errors & unhandled promise rejections
-   - P1: Form labels, missing alt text, keyboard focus
-   - P2: Security headers & performance optimizations
-      │
-5. Human Gate Approval:
-   Present proposed code fixes to human before editing files.
-```
-
-## 3. Human Gate Verification
-
-No code is modified on disk without explicit approval. Findings are presented as:
-
-- Issue Description & Location
-- Proposed Fix (Code diff)
-- Re-test command to verify resolution.
+---
+description: Live website audit using native browser automation. Audits accessibility (WCAG 2.2), console errors, network failures, Core Web Vitals, and security headers. Passes findings through Tribunal's Maker-Reviewer pipeline before proposing fixes.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 1.0.0
+last-updated: 2026-09-13
+required-skills:
+  - browser-audit
+  - web-quality-audit
+  - audit-and-fix
+scripts-binding:
+  - .agent/scripts/browser_audit.js
+  - .agent/scripts/checklist.js
+---
+
+# /audit-live — Live Website Health & Accessibility Audit
+
+$ARGUMENTS
+
+---
+
+## 1. Objective
+
+Audits a running local server (`http://localhost:3000`) or live staging URL using Tribunal Kit's native browser automation engine.
+
+## 2. Execution Pipeline
+
+```
+1. Ingest URL from arguments
+      │
+2. Execute Browser Audit
+   node .agent/scripts/browser_audit.js <url> --json
+      │
+3. Multi-Reviewer Fan-Out Analysis:
+   - web-quality-audit: Evaluates WCAG 2.2 AA contrast & labels
+   - frontend-specialist: Analyzes heading hierarchy & layout shifts
+   - security-auditor: Checks CSP and security headers
+      │
+4. Synthesize Prioritized Action Plan:
+   - P0: Fatal console errors & unhandled promise rejections
+   - P1: Form labels, missing alt text, keyboard focus
+   - P2: Security headers & performance optimizations
+      │
+5. Human Gate Approval:
+   Present proposed code fixes to human before editing files.
+```
+
+## 3. Human Gate Verification
+
+No code is modified on disk without explicit approval. Findings are presented as:
+
+- Issue Description & Location
+- Proposed Fix (Code diff)
+- Re-test command to verify resolution.