tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/test.md

@@ -1,166 +1,189 @@
 ---
-description: Test generation and test running command. Creates and executes tests for code.
+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 Quality Engine
+# /test — Test Generation & Execution
 
 $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
 
----
-
-## 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 |
+|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||
 
 ---
 
-## Modes
+## Testing Trophy Strategy (2026 Standard)
 
 ```
-/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
+             /\
+            /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).
+
 ---
 
-## Mode: Generate Tests
+## Phase 1 — Coverage Gap Analysis
 
-### First — Read the Code
+Before writing new tests, understand existing coverage:
 
-Before writing a single test, map:
+```bash
+npm run test:coverage  # Generate coverage report
+```
 
-- 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
+Cover these areas in priority order:
 
-### Then — Write the Test Plan
+```
+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)
+```
 
-A plan must be written **before** test code:
+---
 
-```
-Target: [function or module name]
-Framework: [Jest | Vitest | pytest | Go test]
+## Phase 2 — Test Design (Behavioral, Not Structural)
 
-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)
+Tests describe **behavior**, not implementation:
 
-Dependencies to mock: [list — minimal, only direct external deps]
 ```
+✅ Behavioral: "returns 401 when no auth token is provided"
+❌ Structural: "calls validateToken() once"
 
-**Then tests are written and passed through `test-coverage-reviewer`.**
+Format every test as:
+GIVEN  [initial state/context]
+WHEN   [action taken]
+THEN   [observable behavior verified]
+```
 
 ---
 
-## Test Structure Standard
-
-Every generated test file follows this format:
+## Phase 3 — Minimum Required Test Coverage
 
-```typescript
-describe('[Unit under test]', () => {
+The Tribunal rejects any test submission that does not cover ALL of:
 
-  describe('[scenario group]', () => {
-    it('[specific behavior being tested]', () => {
-      // Arrange
-      const input = [setup value];
+```
+□ 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?
+```
 
-      // Act
-      const result = functionUnderTest(input);
+---
 
-      // Assert — specific value, not .toBeDefined()
-      expect(result).toBe([exact expected value]);
-    });
-  });
+## Test Templates by Layer
 
-  describe('edge cases', () => {
-    it('throws when input is null', () => {
-      expect(() => functionUnderTest(null)).toThrow('[exact error message]');
-    });
+### Unit Test (Vitest)
 
-    it('handles empty string without crashing', () => {
-      expect(functionUnderTest('')).toBe([expected fallback value]);
-    });
+```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)
 
-## Mode: Audit Existing Tests
+```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);
+});
+```
 
-The `test-coverage-reviewer` flags:
+### E2E Test (Playwright)
 
-| 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"`, `{}`, `[]` |
+```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();
+});
+```
 
 ---
 
-## Mode: Run Tests
+## Phase 4 — Test Execution
 
 ```bash
-// turbo
-python .agent/scripts/test_runner.py . --coverage
+# 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%)
 ```
 
-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
+Failed tests halt the workflow. Fix the code or fix the test (not both — understand which first).
 
 ---
 
-## Hallucination Guard
+## Human Gate — Before Writing Test Files
 
-- 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
+After the test-coverage-reviewer approves:
 
----
+```
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━
 
-## Cross-Workflow Navigation
+Generated tests cover:
+  ✅ Happy path
+  ✅ Error path
+  ✅ Boundary cases
+  ✅ Auth boundary
 
-| 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 |
+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.
 
 ---
 
-## Usage
+## Test Review Verdicts
+
+The `test-coverage-reviewer` is automatically activated and checks:
 
 ```
-/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
+□ 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,111 +1,93 @@
 ---
-description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Types. Use for API routes, server logic, and auth code.
+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 — Server-Side Audit
+# /tribunal-backend — Backend Code Audit
 
 $ARGUMENTS
 
 ---
 
-Focused audit for backend and API code. Paste server-side code and these four reviewers analyze it simultaneously.
+## 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||
 
-## 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` |
+## 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
 
 ---
 
-## Active Reviewers
+## Verdict System
 
 ```
-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
+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
 ```
 
 ---
 
-## 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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## Backend-Specific Hallucination Traps (Common LLM Mistakes)
 
-security-auditor:
-  ❌ CRITICAL — Line 44
-     JWT algorithm not enforced: jwt.verify(token, secret)
-     Fix: jwt.verify(token, secret, { algorithms: ['HS256'] })
+```typescript
+// ❌ express.Router() methods that don't exist
+router.middleware(() => {});          // not a method — use app.use()
+router.beforeAll(() => {});           // not a method — use router.use()
 
-  ❌ HIGH — Line 12
-     CORS open: app.use(cors()) — allows any origin
-     Fix: app.use(cors({ origin: process.env.ALLOWED_ORIGIN }))
+// ❌ Hono methods that don't exist
+app.middleware('/path', handler);      // not valid — use app.use('/path', handler)
 
-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)
+// ❌ next-auth v4 patterns in v5 projects
+import { getServerSession } from 'next-auth'; // v4 — use auth() from './auth' in v5
 
-━━━ Verdict: REJECTED — fix before merging ━━━━━━
+// ❌ 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
 ```
 
 ---
 
-## 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
+## Usage Examples
 
 ```
-/tribunal-backend [paste API route code]
-/tribunal-backend [paste auth middleware]
-/tribunal-backend src/routes/user.ts
-/tribunal-backend the JWT verification middleware
+/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
 ```

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

@@ -1,132 +1,94 @@
 ---
-description: Database-specific Tribunal. Runs Logic + Security + SQL reviewers. Use for queries, migrations, and ORM code.
+description: Database-specific Tribunal. Runs Logic + Security + SQL reviewers. Use for Prisma queries, raw SQL, schema migrations, ORM operations, and database transaction code.
 ---
 
-# /tribunal-database — Data Layer Audit
+# /tribunal-database — Database Code Audit
 
 $ARGUMENTS
 
 ---
 
-Focused audit for SQL queries, ORM code, schema changes, and migrations. **Provide your schema alongside the code** for the most accurate analysis.
+## When to Use /tribunal-database
 
----
-
-## When to Use This vs Other Tribunals
-
-| Code type | Right tribunal |
-|---|---|
-| SQL queries, ORM, migrations | `/tribunal-database` ← you are here |
-| API routes, auth, middleware | `/tribunal-backend` |
-| React components, hooks | `/tribunal-frontend` |
-| Unknown domain or cross-domain | `/tribunal-full` |
-
----
-
-## Active Reviewers
-
-```
-logic-reviewer      → ORM methods that don't exist, impossible WHERE conditions,
-                      chained queries on results that could be null
-security-auditor    → SQL injection surfaces, sensitive data exposed without masking,
-                      missing authorization checks before DB access
-sql-reviewer        → String interpolation in queries, N+1 patterns,
-                      references to tables/columns not in the schema,
-                      unbounded SELECT *, missing WHERE clauses on DELETE/UPDATE
-```
+|Use `/tribunal-database` when...|Use something else when...|
+|:---|:---|
+|Prisma queries and schema|Frontend queries → `/tribunal-frontend`|
+|Raw SQL with pg/mysql2/better-sqlite3|API routes calling DB → `/tribunal-backend`|
+|Database migrations|Full audit → `/tribunal-full`|
+|ORM schema changes||
+|Transaction boundaries||
 
 ---
 
-## Important: Provide Your Schema
+## 3 Active Reviewers (All Run Simultaneously)
 
-The `sql-reviewer` can only validate column/table names if it has the schema:
+### logic-reviewer
+- Prisma methods that don't exist (`findOne` was removed — use `findUnique`)
+- Transaction that should be `$transaction` but isn't
+- Pagination query missing total count (returns wrong metadata)
+- `.findMany()` with no `take` limit (unbounded query)
 
-```
-/tribunal-database
+### security-auditor
+- SQL injection via `$queryRaw` with template literals and user input
+- Row-level security bypass (no WHERE clause on user-scoped query)
+- Mass assignment via `prisma.user.update({ data: req.body })` (unrestricted)
+- Prisma `$executeRaw` with string interpolation
 
-Schema:
-  CREATE TABLE users (id UUID, email TEXT, created_at TIMESTAMPTZ);
-  CREATE TABLE posts (id UUID, user_id UUID REFERENCES users(id), title TEXT);
-
-Code to audit:
-  [paste query or ORM code here]
-```
-
-**Without the schema**, the reviewer flags all table/column references as `[VERIFY — schema not provided]`.
+### sql-reviewer
+- N+1 pattern (loop with prisma query inside)
+- Foreign key columns without `@@index`
+- No index on ORDER BY column for large tables
+- Unscoped UPDATE/DELETE without WHERE clause
+- Missing rollback in raw SQL catch block
+- Expand vs contract migration not followed
 
 ---
 
-## What Gets Flagged — Real Examples
-
-| Reviewer | Example Finding | Severity |
-|---|---|---|
-| logic | `prisma.user.findFirstOrCreate()` — not a real Prisma method | ❌ HIGH |
-| security | `` db.query(`SELECT * WHERE id = ${req.params.id}`) `` — injection | ❌ CRITICAL |
-| security | `SELECT password FROM users` returned to API without masking | ❌ HIGH |
-| sql | `SELECT * FROM payments` when `payments` not in schema | ❌ HIGH |
-| sql | `SELECT` query inside a `for` loop — N+1 pattern | ❌ HIGH |
-| sql | `DELETE FROM sessions` with no `WHERE` clause | ❌ CRITICAL |
-| sql | `SELECT * FROM users` with no pagination — unbounded result | ⚠️ MEDIUM |
-| security | No `LIMIT` on a user-controlled query parameter | ⚠️ MEDIUM |
-
----
-
-## Report Format
+## Verdict System
 
 ```
-━━━ Database Audit ━━━━━━━━━━━━━━━━━━━━━━
-
-  logic-reviewer:    ✅ APPROVED
-  security-auditor:  ❌ REJECTED
-  sql-reviewer:      ❌ REJECTED
-
-━━━ Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-security-auditor:
-  ❌ CRITICAL — Line 6
-     SQL injection: string interpolation in query
-     Code: db.query(`SELECT * WHERE id = ${req.params.id}`)
-     Fix:  db.query('SELECT * WHERE id = $1', [req.params.id])
-
-sql-reviewer:
-  ❌ HIGH — Line 19
-     N+1 detected: SELECT inside for-loop (10 users = 10 queries)
-     Fix:  Batch with WHERE id = ANY($1::uuid[]) or use a JOIN
-
-  ⚠️ MEDIUM — Line 32
-     Unbounded result: SELECT * FROM audit_logs — no LIMIT
-     Fix:  Add LIMIT + OFFSET or use cursor-based pagination
-
-━━━ Verdict: REJECTED — fix CRITICAL and HIGH before merging ━━━
+If ANY reviewer → ❌ REJECTED: fix before Human Gate
+If any reviewer → ⚠️ WARNING:  proceed with flagged items
+If all reviewers → ✅ APPROVED: Human Gate
 ```
 
 ---
 
-## Hallucination Guard
-
-- `sql-reviewer` only references tables and columns **from the provided schema** — no invented schema
-- ORM method names are verified against **the installed ORM version's documented API**
-- Parameterized query fixes show the **exact parameterized form** for the target database driver
-- N+1 fixes must show the **actual batched query**, not just say "use a JOIN"
-
 ---
 
-## Cross-Workflow Navigation
-
-| Finding type | Next step |
-|---|---|
-| SQL injection CRITICAL | Rotate credentials, then fix with `/generate` using parameterization |
-| N+1 pattern in ORM | `/enhance` the repository method with proper eager loading |
-| Schema references invalid columns | Fix schema first with `/migrate` |
-| All approved | Human Gate to write to disk |
+## Database-Specific Hallucination Traps (Common LLM Mistakes)
+
+```typescript
+// ❌ Prisma: findOne was REMOVED — doesn't exist in any version
+const user = await prisma.user.findOne({ where: { id } });
+// ✅ Correct
+const user = await prisma.user.findUnique({ where: { id } });
+
+// ❌ Prisma: upsertMany doesn't exist
+await prisma.product.upsertMany({ data: products });         // Doesn't exist
+// ✅ Use createMany or transaction with multiple upserts
+await prisma.$transaction(products.map(p => prisma.product.upsert({ ... })));
+
+// ❌ Migration fails silently: adding NOT NULL column to populated table
+ALTER TABLE users ADD COLUMN phone VARCHAR(20) NOT NULL; // Error on existing rows
+// ✅ Always add nullable first, backfill, then add constraint
+
+// ❌ Missing rollback in raw SQL
+try {
+  await db.query('BEGIN');
+  await db.query('UPDATE ...');
+} catch (e) {
+  // Missing: await db.query('ROLLBACK');
+}
+```
 
 ---
 
-## Usage
+## Usage Examples
 
 ```
-/tribunal-database [paste query with schema]
-/tribunal-database src/repositories/userRepo.ts
-/tribunal-database [paste Prisma query]
-/tribunal-database the payment queries in services/billing.ts
+/tribunal-database the createOrder function with Stripe idempotency
+/tribunal-database the user registration with email uniqueness check
+/tribunal-database the migration file adding phoneNumber to users
+/tribunal-database the paginated product query with category filter
 ```