tribunal-kit 2.4.6 → 3.0.0

package/.agent/workflows/test.md

@@ -1,166 +1,211 @@
----
-description: Test generation and test running command. Creates and executes tests for code.
----
-
-# /test — Test Quality Engine
-
-$ARGUMENTS
-
----
-
-This command either **generates tests that actually test things**, or **audits existing tests** to find ones that don't. A test that always passes isn't protecting anything.
-
----
-
-## When to Use /test vs Other Commands
-
-| Use `/test` when... | Use something else when... |
-|---|---|
-| No tests exist for working code | Code is broken → `/debug` first, then `/test` |
-| Tests exist but coverage is thin | Quality of test assertions → use `audit` mode |
-| You changed behavior and need regression tests | Full project test health → `/audit` |
-| You want edge case coverage only | Integration tests → specify in the test plan |
-
----
-
-## Modes
-
-```
-/test [file or function]     → Generate tests for the target
-/test audit                  → Check existing tests for quality issues
-/test coverage               → Identify code paths with no test coverage
-/test edge [function]        → Generate edge-case tests only (null, empty, boundary)
-/test run                    → Run the existing test suite and analyze failures
-```
-
----
-
-## Mode: Generate Tests
-
-### First — Read the Code
-
-Before writing a single test, map:
-
-- Every **execution path** (normal path, error path, edge cases)
-- All **direct external dependencies** (to identify what needs mocking)
-- **Expected inputs and outputs** — derived from the function signature and actual behavior, not assumed
-
-### Then — Write the Test Plan
-
-A plan must be written **before** test code:
-
-```
-Target: [function or module name]
-Framework: [Jest | Vitest | pytest | Go test]
-
-Path inventory:
-  › Normal path — valid input, expected output
-  › Null / undefined / None input
-  › Empty string / empty array / empty object
-  › Boundary values (0, -1, MAX_INT, max string length)
-  › Async rejection / network failure / timeout
-  › Invalid type input (string where number expected, etc.)
-  › Auth / permission fail path
-  › Concurrent access (if applicable)
-
-Dependencies to mock: [list — minimal, only direct external deps]
-```
-
-**Then tests are written and passed through `test-coverage-reviewer`.**
-
----
-
-## Test Structure Standard
-
-Every generated test file follows this format:
-
-```typescript
-describe('[Unit under test]', () => {
-
-  describe('[scenario group]', () => {
-    it('[specific behavior being tested]', () => {
-      // Arrange
-      const input = [setup value];
-
-      // Act
-      const result = functionUnderTest(input);
-
-      // Assert — specific value, not .toBeDefined()
-      expect(result).toBe([exact expected value]);
-    });
-  });
-
-  describe('edge cases', () => {
-    it('throws when input is null', () => {
-      expect(() => functionUnderTest(null)).toThrow('[exact error message]');
-    });
-
-    it('handles empty string without crashing', () => {
-      expect(functionUnderTest('')).toBe([expected fallback value]);
-    });
-  });
-
-});
-```
-
----
-
-## Mode: Audit Existing Tests
-
-The `test-coverage-reviewer` flags:
-
-| Problem | What It Looks Like | Why It's Bad |
-|---|---|---|
-| Tautology test | `expect(fn(x)).toBe(fn(x))` | Always passes regardless of fn's behavior |
-| No assertion | `it('works', () => { fn(); })` | Passes even if fn throws wrong output |
-| Missing edge cases | Suite has happy path only | Misses real-world failure modes |
-| Over-mocking | Every dep mocked, nothing real tested | Tests the mocking framework, not the code |
-| Vacuous truthy | `expect(result).toBeTruthy()` | Passes for `1`, `"a"`, `{}`, `[]` |
-
----
-
-## Mode: Run Tests
-
-```bash
-// turbo
-python .agent/scripts/test_runner.py . --coverage
-```
-
-After running, the `test-result-analyzer` identifies:
-- Root causes across multiple failing test files
-- Whether failures are from flaky setup or actual code breakage
-- Actionable fix recommendations
-
----
-
-## Hallucination Guard
-
-- Only **documented** Vitest/Jest/pytest methods are used — never `test.eventually()`, `expect.when()`, or inventions
-- Assertions test **specific values** — `toBe('exact')`, not `toBeDefined()` or `toBeTruthy()`
-- Mocks are **minimal** — only the direct external dependency, not the whole world
-- All conclusions about existing test quality are backed by **reading the actual test code**
-- `// VERIFY: check this matcher exists` on any assertion method not commonly used
-
----
-
-## Cross-Workflow Navigation
-
-| After /test shows... | Go to |
-|---|---|
-| Failures in existing tests after a change | `/debug` to find root cause |
-| Code has no tests and is untested in prod | `/review` first for quality check |
-| Tests pass but logic seems wrong | `/review [file]` for deeper audit |
-| Coverage gaps found in security-sensitive paths | `/audit` for full project security + test sweep |
-
----
-
-## Usage
-
-```
-/test src/services/auth.service.ts
-/test the validateEmail function
-/test audit — check whether my existing tests actually assert anything
-/test coverage — show branches with no test
-/test edge validateInput — generate null, empty, boundary tests only
-/test run — execute the suite and analyze failures
-```
+---
+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
+```

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

@@ -1,111 +1,113 @@
----
-description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Types. Use for API routes, server logic, and auth code.
----
-
-# /tribunal-backend — Server-Side Audit
-
-$ARGUMENTS
-
----
-
-Focused audit for backend and API code. Paste server-side code and these four reviewers analyze it simultaneously.
-
----
-
-## When to Use This vs Other Tribunals
-
-| Code type | Right tribunal |
-|---|---|
-| API routes, auth, middleware | `/tribunal-backend` ← you are here |
-| React components, hooks | `/tribunal-frontend` |
-| SQL queries, ORM, migrations | `/tribunal-database` |
-| Mobile-specific code | `/tribunal-mobile` |
-| Unknown domain or cross-domain | `/tribunal-full` |
-
----
-
-## Active Reviewers
-
-```
-logic-reviewer          → Invented stdlib methods, impossible conditional branches,
-                          calling .user on a req that wasn't authenticated
-security-auditor        → Auth bypass, SQL injection, secrets in code, rate limiting gaps,
-                          JWT algorithm enforcement, CORS misconfiguration
-dependency-reviewer     → Any import not found in your package.json
-type-safety-reviewer    → Implicit any, unguarded optional access, missing return types,
-                          unsafe casts
-```
-
----
-
-## What Gets Flagged — Real Examples
-
-| Reviewer | Example Finding |
-|---|---|
-| logic | `req.user.id` used after a guard that can pass with null user |
-| security | `jwt.verify(token, secret)` — no `algorithms` option → allows `alg:none` attack |
-| security | `app.use(cors())` with no origin restriction in production |
-| security | `rate-limiter` missing on auth endpoints |
-| dependency | `import { z } from 'zod'` but `zod` not in `package.json` |
-| type-safety | `async function handler(req, res)` — untyped `req` and `res` |
-| type-safety | `const user = await db.findUser(id)` — result typed as `any` |
-
----
-
-## Report Format
-
-```
-━━━ Backend Audit ━━━━━━━━━━━━━━━━━━━━━━━
-
-  logic-reviewer:        ✅ APPROVED
-  security-auditor:      ❌ REJECTED
-  dependency-reviewer:   ✅ APPROVED
-  type-safety-reviewer:  ⚠️  WARNING
-
-━━━ Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-security-auditor:
-  ❌ CRITICAL — Line 44
-     JWT algorithm not enforced: jwt.verify(token, secret)
-     Fix: jwt.verify(token, secret, { algorithms: ['HS256'] })
-
-  ❌ HIGH — Line 12
-     CORS open: app.use(cors()) — allows any origin
-     Fix: app.use(cors({ origin: process.env.ALLOWED_ORIGIN }))
-
-type-safety-reviewer:
-  ⚠️ MEDIUM — Line 10
-     Request body typed as any — use Zod schema parse at the API boundary
-     Fix: const body = schema.parse(req.body)
-
-━━━ Verdict: REJECTED — fix before merging ━━━━━━
-```
-
----
-
-## Hallucination Guard
-
-- Logic findings must cite the **exact line and condition** that creates the problem
-- Security findings must name the **attack class** (not just "this is unsafe")
-- No invented framework methods — only documented Express/Fastify/Hono/etc. APIs
-
----
-
-## Cross-Workflow Navigation
-
-| Finding type | Next step |
-|---|---|
-| Security CRITICAL | `/audit` to scan the whole project |
-| All approved | Human Gate to write to disk |
-| SQL queries also present | Add `/tribunal-database` for those specifically |
-
----
-
-## Usage
-
-```
-/tribunal-backend [paste API route code]
-/tribunal-backend [paste auth middleware]
-/tribunal-backend src/routes/user.ts
-/tribunal-backend the JWT verification middleware
-```
+---
+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
+```