tribunal-kit 4.5.1 → 4.6.1

package/.agent/workflows/test.md

@@ -1,189 +1,211 @@
----
-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)
-```
-
----
+---
+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.
+required-skills: testing-patterns, tdd-workflow
+---
+
+# /test — Test Generation & Execution
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE testing:
+□ Target files                → Code to be tested
+□ Existing tests              → Understand testing patterns already used
+□ package.json                → Check test frameworks (Jest, Vitest, etc.)
+```
+
+---
+
+## 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)
+```
+
+---
+
+## After /test — Next Steps
+
+| Outcome                     | Next Command                                         |
+| :-------------------------- | :--------------------------------------------------- |
+| Tests pass cleanly          | → `/deploy` or return to `/enhance` for next feature |
+| Tests fail with bugs        | → `/debug` to trace logic errors                     |
+| Need to improve performance | → `/performance-benchmarker`                         |
+
+---

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

@@ -1,105 +1,136 @@
----
-description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Type Safety + Resilience + Schema 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||
-
----
-
-## 6 Active Reviewers (All Run Simultaneously)
-
-### precedence-reviewer    → Checks local repo Case Law for past rejections
-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
-
-### schema-reviewer
-- Missing input validation on req.body/req.query
-- Validation applied client-side only
-- Loosely defined Zod/Pydantic schemas
-
-### resilience-reviewer
-- Swallowed errors (empty catch blocks)
-- Missing timeouts on network fetches
-- Unhandled Promise rejections
-- Missing retries for temporal network failures
-
----
-
-## 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
-```
+---
+description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Type Safety + Resilience + Schema reviewers. Use for API routes, server logic, auth code, middleware, Server Actions, and any server-side business logic.
+required-skills: backend-security-expert, nodejs-best-practices, api-patterns
+---
+
+# /tribunal-backend — Backend Code Audit
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE backend review:
+□ Target backend files         → The code being audited
+□ package.json                 → Verify dependency versions (express, next, etc.)
+□ prisma/schema.prisma         → If ORM is used
+□ .env.example                 → Expected environment variables
+```
+
+---
+
+## 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       |                                              |
+
+---
+
+## 6 Active Reviewers (All Run Simultaneously)
+
+### precedence-reviewer → Checks local repo Case Law for past rejections
+
+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
+
+### schema-reviewer
+
+- Missing input validation on req.body/req.query
+- Validation applied client-side only
+- Loosely defined Zod/Pydantic schemas
+
+### resilience-reviewer
+
+- Swallowed errors (empty catch blocks)
+- Missing timeouts on network fetches
+- Unhandled Promise rejections
+- Missing retries for temporal network failures
+
+---
+
+## 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
+```
+
+---
+
+## After /tribunal-backend — Next Steps
+
+| Outcome                      | Next Command                                      |
+| :--------------------------- | :------------------------------------------------ |
+| All checks pass              | → `/deploy` or merge code                         |
+| Reviewers reject with fixes  | → Apply fixes, then run `/tribunal-backend` again |
+| Performance concerns raised  | → `/tribunal-performance` for deep profiling      |
+| Need test coverage for logic | → `/test` to generate backend tests               |
+
+---