tribunal-kit 3.0.0 → 3.1.0

package/.agent/workflows/test.md

@@ -1,211 +1,189 @@
----
-description: Test generation and test running command. Creates and executes tests for code using the Testing Trophy strategy (unit → integration → E2E). Tests are behavioral (GIVEN/WHEN/THEN), not structural. Tests cannot be approved without covering happy path, error path, and boundary cases.
----
-
-# /test — Test Generation & Execution
-
-$ARGUMENTS
-
----
-
-## When to Use /test
-
-| Use `/test` when... | Use something else when... |
-|:---|:---|
-| New code was just generated and needs tests | Tests are failing → `/debug` |
-| After `/debug` to prevent regression | Need a full coverage audit → `/audit` |
-| Test coverage is below threshold | E2E for the whole app → `/performance-benchmarker` |
-| A bug was fixed and needs a regression test | |
-
----
-
-## Testing Trophy Strategy (2026 Standard)
-
-```
-             /\
-            /E2E\          ← Small (Playwright): happy paths, auth, critical checkout
-           /──────\
-          /Integr.\        ← Medium (RTL + MSW): component + network behavior  
-         /──────────\
-        /    Unit    \     ← Foundation (Vitest): pure logic + transformations
-       /──────────────\
-      /   Static Types  \  ← Free: TypeScript + ESLint
-     /────────────────────\
-```
-
-When asked to write tests without specifying a level, default to **integration tests** (highest ROI per test).
-
----
-
-## Phase 1 — Coverage Gap Analysis
-
-Before writing new tests, understand existing coverage:
-
-```bash
-npm run test:coverage  # Generate coverage report
-```
-
-Cover these areas in priority order:
-
-```
-1. Authentication flows (login, logout, session expiry)
-2. Data mutation paths (create, update, delete)
-3. Validation rejection (invalid input → correct error)
-4. Error handling (API failure → correct fallback)
-5. Authorization (wrong role → 403, unauthenticated → 401)
-6. Boundary values (0, null, empty, max)
-```
-
----
-
-## Phase 2 — Test Design (Behavioral, Not Structural)
-
-Tests describe **behavior**, not implementation:
-
-```
-✅ Behavioral: "returns 401 when no auth token is provided"
-❌ Structural: "calls validateToken() once"
-
-Format every test as:
-GIVEN  [initial state/context]
-WHEN   [action taken]
-THEN   [observable behavior verified]
-```
-
----
-
-## Phase 3 — Minimum Required Test Coverage
-
-The Tribunal rejects any test submission that does not cover ALL of:
-
-```
-□ Happy path — does it work correctly with valid input?
-□ Error path — does it fail correctly with invalid/missing input?
-□ Boundary cases — what happens at 0, null, empty, max, limits?
-□ Auth boundary — what happens without auth? With wrong role?
-```
-
----
-
-## Test Templates by Layer
-
-### Unit Test (Vitest)
-
-```typescript
-describe('[functionName]()', () => {
-  it('[happy path description]', () => {
-    expect(fn(validInput)).toBe(expectedResult);
-  });
-  
-  it('returns [expected] when input is [edge case]', () => {
-    expect(fn(boundaryInput)).toBe(expectedBoundaryResult);
-  });
-  
-  it('throws [ErrorType] when [invalid condition]', () => {
-    expect(() => fn(invalidInput)).toThrow(ExpectedError);
-  });
-});
-```
-
-### Integration Test (RTL + MSW)
-
-```typescript
-test('[user observable behavior]', async () => {
-  // GIVEN: server mock defined in handlers.ts
-  // WHEN: user action
-  render(<Component />);
-  await userEvent.click(screen.getByRole('button', { name: /submit/i }));
-  // THEN: observable outcome
-  await screen.findByText(/success/i);
-});
-```
-
-### E2E Test (Playwright)
-
-```typescript
-test('[critical user path]', async ({ page }) => {
-  // GIVEN: pre-authenticated (stored session — not login from UI every test)
-  // WHEN: navigate and act
-  await page.goto('/checkout');
-  // THEN: verify final state
-  await expect(page.getByText('Order confirmed')).toBeVisible();
-});
-```
-
----
-
-## Phase 4 — Test Execution
-
-```bash
-# Run tests
-npm test                    # Unit + integration
-npm run test:e2e           # Playwright E2E (CI environment)
-npm run test:coverage      # With coverage report
-
-# target coverage threshold (default 80%)
-```
-
-Failed tests halt the workflow. Fix the code or fix the test (not both — understand which first).
-
----
-
-## Human Gate — Before Writing Test Files
-
-After the test-coverage-reviewer approves:
-
-```
-━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Generated tests cover:
-  ✅ Happy path
-  ✅ Error path
-  ✅ Boundary cases
-  ✅ Auth boundary
-
-Files to write:
-  [list of .test.ts files]
-
-Write to disk?  Y = write | N = discard | R = revise coverage
-```
-
-No test files are written without explicit approval.
-
----
-
-## Test Review Verdicts
-
-The `test-coverage-reviewer` is automatically activated and checks:
-
-```
-□ Happy path covered for new function/component
-□ Error/rejection paths covered
-□ Boundary values tested
-□ No brittle CSS selectors — only getByRole/getByLabelText
-□ No implementation details tested (private state, internal calls)
-□ Async assertions use await findBy* (not getBy*)
-□ Mock only at architectural boundaries (MSW for network — not hooks/methods)
-```
-
----
-
-## Cross-Workflow Navigation
-
-| After /test shows... | Go to |
-|:---|:---|
-| Tests failing — suspected logic bug | `/debug` |
-| Tests failing — suspected security issue | `/tribunal-backend` |
-| Coverage still below threshold | `/audit` for full coverage report |
-| E2E tests failing | Check `/audit` script output |
-
----
-
-## Usage Examples
-
-```
-/test the calculateDiscount function in src/lib/pricing.ts
-/test the POST /api/auth/login route including rate limit behavior
-/test the UserProfile component including loading and error states
-/test the checkout flow E2E with Playwright
-/test add regression test for bug: login fails with uppercase email
-/test the database transaction in createOrder for rollback behavior
-```
+---
+description: Test generation and test running command. Creates and executes tests for code using the Testing Trophy strategy (unit → integration → E2E). Tests are behavioral (GIVEN/WHEN/THEN), not structural. Tests cannot be approved without covering happy path, error path, and boundary cases.
+---
+
+# /test — Test Generation & Execution
+
+$ARGUMENTS
+
+---
+
+## When to Use /test
+
+|Use `/test` when...|Use something else when...|
+|:---|:---|
+|New code was just generated and needs tests|Tests are failing → `/debug`|
+|After `/debug` to prevent regression|Need a full coverage audit → `/audit`|
+|Test coverage is below threshold|E2E for the whole app → `/performance-benchmarker`|
+|A bug was fixed and needs a regression test||
+
+---
+
+## Testing Trophy Strategy (2026 Standard)
+
+```
+             /\
+            /E2E\          ← Small (Playwright): happy paths, auth, critical checkout
+           /──────\
+          /Integr.\        ← Medium (RTL + MSW): component + network behavior  
+         /──────────\
+        /    Unit    \     ← Foundation (Vitest): pure logic + transformations
+       /──────────────\
+      /   Static Types  \  ← Free: TypeScript + ESLint
+     /────────────────────\
+```
+
+When asked to write tests without specifying a level, default to **integration tests** (highest ROI per test).
+
+---
+
+## Phase 1 — Coverage Gap Analysis
+
+Before writing new tests, understand existing coverage:
+
+```bash
+npm run test:coverage  # Generate coverage report
+```
+
+Cover these areas in priority order:
+
+```
+1. Authentication flows (login, logout, session expiry)
+2. Data mutation paths (create, update, delete)
+3. Validation rejection (invalid input → correct error)
+4. Error handling (API failure → correct fallback)
+5. Authorization (wrong role → 403, unauthenticated → 401)
+6. Boundary values (0, null, empty, max)
+```
+
+---
+
+## Phase 2 — Test Design (Behavioral, Not Structural)
+
+Tests describe **behavior**, not implementation:
+
+```
+✅ Behavioral: "returns 401 when no auth token is provided"
+❌ Structural: "calls validateToken() once"
+
+Format every test as:
+GIVEN  [initial state/context]
+WHEN   [action taken]
+THEN   [observable behavior verified]
+```
+
+---
+
+## Phase 3 — Minimum Required Test Coverage
+
+The Tribunal rejects any test submission that does not cover ALL of:
+
+```
+□ Happy path — does it work correctly with valid input?
+□ Error path — does it fail correctly with invalid/missing input?
+□ Boundary cases — what happens at 0, null, empty, max, limits?
+□ Auth boundary — what happens without auth? With wrong role?
+```
+
+---
+
+## Test Templates by Layer
+
+### Unit Test (Vitest)
+
+```typescript
+describe('[functionName]()', () => {
+  it('[happy path description]', () => {
+    expect(fn(validInput)).toBe(expectedResult);
+  });
+  
+  it('returns [expected] when input is [edge case]', () => {
+    expect(fn(boundaryInput)).toBe(expectedBoundaryResult);
+  });
+  
+  it('throws [ErrorType] when [invalid condition]', () => {
+    expect(() => fn(invalidInput)).toThrow(ExpectedError);
+  });
+});
+```
+
+### Integration Test (RTL + MSW)
+
+```typescript
+test('[user observable behavior]', async () => {
+  // GIVEN: server mock defined in handlers.ts
+  // WHEN: user action
+  render(<Component />);
+  await userEvent.click(screen.getByRole('button', { name: /submit/i }));
+  // THEN: observable outcome
+  await screen.findByText(/success/i);
+});
+```
+
+### E2E Test (Playwright)
+
+```typescript
+test('[critical user path]', async ({ page }) => {
+  // GIVEN: pre-authenticated (stored session — not login from UI every test)
+  // WHEN: navigate and act
+  await page.goto('/checkout');
+  // THEN: verify final state
+  await expect(page.getByText('Order confirmed')).toBeVisible();
+});
+```
+
+---
+
+## Phase 4 — Test Execution
+
+```bash
+# Run tests
+npm test                    # Unit + integration
+npm run test:e2e           # Playwright E2E (CI environment)
+npm run test:coverage      # With coverage report
+
+# target coverage threshold (default 80%)
+```
+
+Failed tests halt the workflow. Fix the code or fix the test (not both — understand which first).
+
+---
+
+## Human Gate — Before Writing Test Files
+
+After the test-coverage-reviewer approves:
+
+```
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Generated tests cover:
+  ✅ Happy path
+  ✅ Error path
+  ✅ Boundary cases
+  ✅ Auth boundary
+
+Files to write:
+  [list of .test.ts files]
+
+Write to disk?  Y = write | N = discard | R = revise coverage
+```
+
+No test files are written without explicit approval.
+
+---
+
+## Test Review Verdicts
+
+The `test-coverage-reviewer` is automatically activated and checks:
+
+```
+□ Happy path covered for new function/component
+□ Error/rejection paths covered
+□ Boundary values tested
+□ No brittle CSS selectors — only getByRole/getByLabelText
+□ No implementation details tested (private state, internal calls)
+□ Async assertions use await findBy* (not getBy*)
+□ Mock only at architectural boundaries (MSW for network — not hooks/methods)
+```
+
+---

package/.agent/workflows/tribunal-backend.md

@@ -1,113 +1,93 @@
----
-description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Type Safety reviewers. Use for API routes, server logic, auth code, middleware, Server Actions, and any server-side business logic.
----
-
-# /tribunal-backend — Backend Code Audit
-
-$ARGUMENTS
-
----
-
-## When to Use /tribunal-backend
-
-| Use `/tribunal-backend` when... | Use something else when... |
-|:---|:---|
-| Reviewing API routes or middleware | Frontend components → `/tribunal-frontend` |
-| Auth, JWT, session code | Database queries only → `/tribunal-database` |
-| Server Actions | Mobile code → `/tribunal-mobile` |
-| Input validation and Zod schemas | Maximum coverage → `/tribunal-full` |
-| Third-party API integrations | |
-
----
-
-## 4 Active Reviewers (All Run Simultaneously)
-
-### logic-reviewer
-- Hallucinated Express/Hono/Fastify methods
-- Missing awaits on async operations
-- Unreachable code after return statements
-- Race conditions in sequential state mutations
-
-### security-auditor
-- SQL injection via string interpolation
-- JWT verify missing `{ algorithms: ['HS256'] }` option
-- Auth check after business logic (wrong order)
-- IDOR — resource ownership not verified against session
-- SSRF — user-controlled URLs passed to fetch()
-- Hardcoded secrets / missing env var existence checks
-- CORS wildcard (`*`) in production
-
-### dependency-reviewer
-- Packages not in package.json
-- npm package names matching typosquatting patterns
-- Major version incompatibilities
-- Known CVEs in used packages
-
-### type-safety-reviewer
-- `any` types in request handlers
-- Missing Zod validation before DB access
-- Unsafe type assertions (`as User` without runtime check)
-- Return type mismatches
-
----
-
-## Verdict System
-
-```
-If ANY reviewer → ❌ REJECTED: code must be fixed before Human Gate
-If any reviewer → ⚠️ WARNING:  proceed with flagged items noted
-If all reviewers → ✅ APPROVED: present to Human Gate
-```
-
----
-
-## Output Format
-
-```
-━━━ Tribunal Backend ━━━━━━━━━━━━━━━━━━━━━
-
-logic-reviewer:      ✅ APPROVED
-security-auditor:    ❌ REJECTED
-dependency-reviewer: ✅ APPROVED
-type-safety-reviewer: ⚠️ WARNING
-
-━━━ VERDICT: ❌ REJECTED ━━━━━━━━━━━━━━━━━
-
-Blockers:
-- security-auditor: [CRITICAL] SQL string interpolation on line 23: query = `SELECT * WHERE email = '${email}'`
-  Fix: Use parameterized query: prisma.user.findUnique({ where: { email } })
-
-Warnings:
-- type-safety-reviewer: [MEDIUM] 'req.body' cast as 'any' on line 47 — use Zod parse instead
-```
-
----
-
-## Backend-Specific Hallucination Traps (Common LLM Mistakes)
-
-```typescript
-// ❌ express.Router() methods that don't exist
-router.middleware(() => {});          // not a method — use app.use()
-router.beforeAll(() => {});           // not a method — use router.use()
-
-// ❌ Hono methods that don't exist
-app.middleware('/path', handler);      // not valid — use app.use('/path', handler)
-
-// ❌ next-auth v4 patterns in v5 projects
-import { getServerSession } from 'next-auth'; // v4 — use auth() from './auth' in v5
-
-// ❌ jwt.verify async form (it's synchronous)
-const payload = await jwt.verify(token, secret); // jwt.verify is NOT async
-const payload = jwt.verify(token, secret);        // Correct
-```
-
----
-
-## Usage Examples
-
-```
-/tribunal-backend the POST /api/auth/login route with JWT issuance
-/tribunal-backend the createOrder Server Action with Stripe integration
-/tribunal-backend the auth middleware that verifies session on protected routes
-/tribunal-backend the webhook handler for Stripe payment events
-```
+---
+description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Type Safety reviewers. Use for API routes, server logic, auth code, middleware, Server Actions, and any server-side business logic.
+---
+
+# /tribunal-backend — Backend Code Audit
+
+$ARGUMENTS
+
+---
+
+## When to Use /tribunal-backend
+
+|Use `/tribunal-backend` when...|Use something else when...|
+|:---|:---|
+|Reviewing API routes or middleware|Frontend components → `/tribunal-frontend`|
+|Auth, JWT, session code|Database queries only → `/tribunal-database`|
+|Server Actions|Mobile code → `/tribunal-mobile`|
+|Input validation and Zod schemas|Maximum coverage → `/tribunal-full`|
+|Third-party API integrations||
+
+---
+
+## 4 Active Reviewers (All Run Simultaneously)
+
+### logic-reviewer
+- Hallucinated Express/Hono/Fastify methods
+- Missing awaits on async operations
+- Unreachable code after return statements
+- Race conditions in sequential state mutations
+
+### security-auditor
+- SQL injection via string interpolation
+- JWT verify missing `{ algorithms: ['HS256'] }` option
+- Auth check after business logic (wrong order)
+- IDOR — resource ownership not verified against session
+- SSRF — user-controlled URLs passed to fetch()
+- Hardcoded secrets / missing env var existence checks
+- CORS wildcard (`*`) in production
+
+### dependency-reviewer
+- Packages not in package.json
+- npm package names matching typosquatting patterns
+- Major version incompatibilities
+- Known CVEs in used packages
+
+### type-safety-reviewer
+- `any` types in request handlers
+- Missing Zod validation before DB access
+- Unsafe type assertions (`as User` without runtime check)
+- Return type mismatches
+
+---
+
+## Verdict System
+
+```
+If ANY reviewer → ❌ REJECTED: code must be fixed before Human Gate
+If any reviewer → ⚠️ WARNING:  proceed with flagged items noted
+If all reviewers → ✅ APPROVED: present to Human Gate
+```
+
+---
+
+---
+
+## Backend-Specific Hallucination Traps (Common LLM Mistakes)
+
+```typescript
+// ❌ express.Router() methods that don't exist
+router.middleware(() => {});          // not a method — use app.use()
+router.beforeAll(() => {});           // not a method — use router.use()
+
+// ❌ Hono methods that don't exist
+app.middleware('/path', handler);      // not valid — use app.use('/path', handler)
+
+// ❌ next-auth v4 patterns in v5 projects
+import { getServerSession } from 'next-auth'; // v4 — use auth() from './auth' in v5
+
+// ❌ jwt.verify async form (it's synchronous)
+const payload = await jwt.verify(token, secret); // jwt.verify is NOT async
+const payload = jwt.verify(token, secret);        // Correct
+```
+
+---
+
+## Usage Examples
+
+```
+/tribunal-backend the POST /api/auth/login route with JWT issuance
+/tribunal-backend the createOrder Server Action with Stripe integration
+/tribunal-backend the auth middleware that verifies session on protected routes
+/tribunal-backend the webhook handler for Stripe payment events
+```