tribunal-kit 3.0.0 → 4.0.0

package/.agent/skills/tdd-workflow/SKILL.md

@@ -1,137 +1,111 @@
----
-name: tdd-workflow
-description: Test-Driven Development (TDD) mastery. Red-Green-Refactor cycles, behavior-driven design (BDD), strict mutation coverage, test doubles (mocks/stubs/spies), and avoiding test-induced design damage. Use when building complex algorithms, deep business logic, or strictly regulated systems.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 2.0.0
-last-updated: 2026-04-02
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Test-Driven Development (TDD) — Defect-Free Execution Mastery
-
-> You do not write tests to verify your code. You write tests to design your code.
-> Unverified code is a liability. TDD is the professional hygiene of software engineering.
-
----
-
-## 1. The Red-Green-Refactor Cycle
-
-TDD is a strict, irrevocable discipline. Do not write the implementation first.
-
-### Step 1: RED (Write the failing test)
-Write the test as if the API already exists exactly how you *wish* it were designed.
-Run the test. It MUST fail (because the function doesn't exist, or returns the wrong value). If it passes, the test is useless.
-
-```typescript
-// 1. The failing test
-import { calculateDiscount } from './pricing';
-
-test('Should apply 10% discount for orders over $100', () => {
-    expect(calculateDiscount(150)).toBe(135);
-});
-// ❌ FAILS: calculateDiscount is not defined
-```
-
-### Step 2: GREEN (Make it pass exactly)
-Write the absolute minimum, dumbest code required to make the test pass. Do not over-engineer.
-
-```typescript
-// 2. The minimum implementation
-export function calculateDiscount(subtotal: number): number {
-    if (subtotal >= 100) return subtotal * 0.90;
-    return subtotal;
-}
-// ✅ PASSES.
-```
-
-### Step 3: REFACTOR
-Now wrap the implementation in clean architectural principles. The tests guarantee you haven't broken the behavior while you optimize.
-
-```typescript
-// 3. The Refactor
-const DISCOUNT_THRESHOLD = 100;
-const DISCOUNT_RATE = 0.90;
-
-export function calculateDiscount(subtotal: number): number {
-    return subtotal >= DISCOUNT_THRESHOLD ? subtotal * DISCOUNT_RATE : subtotal;
-}
-// ✅ STILL PASSES. Safe to commit.
-```
-
----
-
-## 2. Test Doubles (Mocks, Stubs, Spies)
-
-Knowing *how* to mock separates amateurs from professionals. Over-mocking destroys architectural integrity.
-
-| Type | When to use | Example |
-|:---|:---|:---|
-| **Dummy** | Filler objects passed but never used | `processOrder(new UserDummy(), payload)` |
-| **Stub** | Hardcodes a specific response | `db.getUser.mockResolvedValue({ id: 1 })` |
-| **Spy** | Records how many times a function was called | `expect(emailService.send).toHaveBeenCalledTimes(1)` |
-| **Mock** | A spy with predefined expectations of exact payloads | `expect(logger.info).toHaveBeenCalledWith('Authorized')` |
-
-### The Mocking Rule
-**Only mock at the architectural boundaries (Database, Network, External FileSystem).**
-NEVER mock internal business logic or child pure-functions. If function A calls function B, test A by allowing it to genuinely call B.
-
----
-
-## 3. Anti-Pattern: Testing Implementation Details
-
-Tests should verify the *behavior* output, not the underlying code structure.
-
-```typescript
-class Account {
-    private balance = 0;
-    deposit(amount: number) { this.balance += amount; }
-    getBalance() { return this.balance; }
-}
-
-// ❌ BAD: Testing internal state (Fragile)
-test('Deposit updates the internal balance variable', () => {
-    const acc = new Account();
-    acc.deposit(50);
-    expect(acc['balance']).toBe(50); // Intrusive test breaks if variable is renamed
-});
-
-// ✅ GOOD: Testing external behavior contract
-test('Deposit makes the funds available via getBalance', () => {
-    const acc = new Account();
-    acc.deposit(50);
-    expect(acc.getBalance()).toBe(50); // Tests the public API only
-});
-```
-
----
-
-## 🤖 LLM-Specific Traps (TDD)
-
-1. **Executing Green-First:** Writing the implementation *before* the test. This completely bypasses the design guidance inherent to TDD.
-2. **Test-Induced Design Damage:** Making private methods public just so they can be individually unit tested. Test the private methods exclusively through the public interface.
-3. **Mocks as Reality:** AI deeply mocking internal functions (`vi.mock('./utils')`) to the point where the test simply verifies the mock configuration, providing zero real-world confidence.
-4. **Fragile "Any" Mocks:** AI writing `expect(mock).toHaveBeenCalledWith(expect.anything())`, neutralizing the actual verification value of the spy.
-5. **No Edge Cases:** Generating tests exclusively for the "Happy Path" (valid inputs). TDD requires boundary testing (nulls, negatives, MAX_INT, empty arrays).
-6. **Massive Arrange Blocks:** Constructing 100-line object setups before the action occurs. Strongly indicates the code under test requires too many dependencies.
-7. **Random Execution Dependency:** Writing tests relying on `Math.random()`, `new Date()`, or real database connections. Tests must be deterministic. Inject interfaces for time and randomizers.
-8. **Catch-All Error Checks:** AI writes `expect(fn).toThrowError()`. Assert against specific error messages so regressions in the exact failure reason are detected.
-9. **Test Name Obscurity:** `test('Works properly', () => ...)`. The test name should read as explicit documentation of system constraints (`test('Throws InsufficientFundsError when withdrawal exceeds balance')`).
-10. **Refactor Skip:** Completing the "Green" phase and stopping. The Refactor phase is where the technical debt is permanently cleared.
-
----
-
-## 🏛️ Tribunal Integration
-
-### ✅ Pre-Flight Self-Audit
-```
-✅ Did I write the failing test requirements BEFORE creating the implementation?
-✅ Are internal private methods accessed solely via verifying the public API layer?
-✅ Were mocks restricted entirely to architectural boundaries (Network/DB/Disk)?
-✅ Are date/time instances mocked via FakeTimers to ensure strict determinism?
-✅ Do assertions verify precise error messages instead of generic catch-all throws?
-✅ Are test case titles descriptive enough to serve as living documentation?
-✅ Have all negative edge cases (boundaries, empty states) been accounted for?
-✅ Upon achieving 'Green', was a deliberate refactor pass initiated for clean code?
-✅ Has `expect.anything()` been avoided to enforce rigid verification of call payloads?
-✅ Does the payload setup rely on minimal dummy data instead of colossal stubs?
-```
+---
+name: tdd-workflow
+description: Test-Driven Development (TDD) mastery. Red-Green-Refactor cycles, behavior-driven design (BDD), strict mutation coverage, test doubles (mocks/stubs/spies), and avoiding test-induced design damage. Use when building complex algorithms, deep business logic, or strictly regulated systems.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+## Hallucination Traps (Read First)
+- ❌ Writing tests that test implementation details instead of behavior -> ✅ Test WHAT it does (inputs/outputs), not HOW (internal methods)
+- ❌ Skipping the Red phase (writing a failing test first) -> ✅ If the test passes before you write the code, it tests nothing
+- ❌ Refactoring during the Red or Green phase -> ✅ Red: write failing test. Green: make it pass minimally. THEN refactor. Never mix phases
+
+---
+
+
+# Test-Driven Development (TDD) — Defect-Free Execution Mastery
+
+---
+
+## 1. The Red-Green-Refactor Cycle
+
+TDD is a strict, irrevocable discipline. Do not write the implementation first.
+
+### Step 1: RED (Write the failing test)
+Write the test as if the API already exists exactly how you *wish* it were designed.
+Run the test. It MUST fail (because the function doesn't exist, or returns the wrong value). If it passes, the test is useless.
+
+```typescript
+// 1. The failing test
+import { calculateDiscount } from './pricing';
+
+test('Should apply 10% discount for orders over $100', () => {
+    expect(calculateDiscount(150)).toBe(135);
+});
+// ❌ FAILS: calculateDiscount is not defined
+```
+
+### Step 2: GREEN (Make it pass exactly)
+Write the absolute minimum, dumbest code required to make the test pass. Do not over-engineer.
+
+```typescript
+// 2. The minimum implementation
+export function calculateDiscount(subtotal: number): number {
+    if (subtotal >= 100) return subtotal * 0.90;
+    return subtotal;
+}
+// ✅ PASSES.
+```
+
+### Step 3: REFACTOR
+Now wrap the implementation in clean architectural principles. The tests guarantee you haven't broken the behavior while you optimize.
+
+```typescript
+// 3. The Refactor
+const DISCOUNT_THRESHOLD = 100;
+const DISCOUNT_RATE = 0.90;
+
+export function calculateDiscount(subtotal: number): number {
+    return subtotal >= DISCOUNT_THRESHOLD ? subtotal * DISCOUNT_RATE : subtotal;
+}
+// ✅ STILL PASSES. Safe to commit.
+```
+
+---
+
+## 2. Test Doubles (Mocks, Stubs, Spies)
+
+Knowing *how* to mock separates amateurs from professionals. Over-mocking destroys architectural integrity.
+
+|Type|When to use|Example|
+|:---|:---|:---|
+|**Dummy**|Filler objects passed but never used|`processOrder(new UserDummy(), payload)`|
+|**Stub**|Hardcodes a specific response|`db.getUser.mockResolvedValue({ id: 1 })`|
+|**Spy**|Records how many times a function was called|`expect(emailService.send).toHaveBeenCalledTimes(1)`|
+|**Mock**|A spy with predefined expectations of exact payloads|`expect(logger.info).toHaveBeenCalledWith('Authorized')`|
+
+### The Mocking Rule
+**Only mock at the architectural boundaries (Database, Network, External FileSystem).**
+NEVER mock internal business logic or child pure-functions. If function A calls function B, test A by allowing it to genuinely call B.
+
+---
+
+## 3. Anti-Pattern: Testing Implementation Details
+
+Tests should verify the *behavior* output, not the underlying code structure.
+
+```typescript
+class Account {
+    private balance = 0;
+    deposit(amount: number) { this.balance += amount; }
+    getBalance() { return this.balance; }
+}
+
+// ❌ BAD: Testing internal state (Fragile)
+test('Deposit updates the internal balance variable', () => {
+    const acc = new Account();
+    acc.deposit(50);
+    expect(acc['balance']).toBe(50); // Intrusive test breaks if variable is renamed
+});
+
+// ✅ GOOD: Testing external behavior contract
+test('Deposit makes the funds available via getBalance', () => {
+    const acc = new Account();
+    acc.deposit(50);
+    expect(acc.getBalance()).toBe(50); // Tests the public API only
+});
+```
+
+---

package/.agent/skills/test-result-analyzer/SKILL.md

@@ -52,16 +52,16 @@ Report — structured output with confidence levels
 
 Auto-detect the test framework from output patterns:
 
-| Framework | Detection Pattern | Failure Marker |
+|Framework|Detection Pattern|Failure Marker|
 |---|---|---|
-| Jest | `PASS`/`FAIL` with file paths, `●` for test names | `FAIL src/...` |
-| Vitest | `✓`/`×` markers, `FAIL` blocks | `❯ FAIL` or `× test name` |
-| pytest | `PASSED`/`FAILED` with `::` separator | `FAILED tests/...::test_name` |
-| Go test | `ok`/`FAIL` with package paths | `--- FAIL: TestName` |
-| Mocha | `passing`/`failing` counts, indented suites | `N failing` section |
-| JUnit (XML) | `<testsuite>` XML structure | `<failure>` elements |
-| RSpec | `.F` markers, `Failures:` section | `Failure/Error:` |
-| Cargo test | `test result: FAILED` | `---- test_name stdout ----` |
+|Jest|`PASS`/`FAIL` with file paths, `●` for test names|`FAIL src/...`|
+|Vitest|`✓`/`×` markers, `FAIL` blocks|`❯ FAIL` or `× test name`|
+|pytest|`PASSED`/`FAILED` with `::` separator|`FAILED tests/...::test_name`|
+|Go test|`ok`/`FAIL` with package paths|`--- FAIL: TestName`|
+|Mocha|`passing`/`failing` counts, indented suites|`N failing` section|
+|JUnit (XML)|`<testsuite>` XML structure|`<failure>` elements|
+|RSpec|`.F` markers, `Failures:` section|`Failure/Error:`|
+|Cargo test|`test result: FAILED`|`---- test_name stdout ----`|
 
 ## Step 2: Failure Extraction
 
@@ -86,15 +86,15 @@ Group failures into clusters based on shared characteristics:
 
 ### Cluster Types
 
-| Cluster Type | How to Detect | Typical Root Cause |
+|Cluster Type|How to Detect|Typical Root Cause|
 |---|---|---|
-| **Shared Module** | Multiple tests import from the same file that changed | Missing export, type change, API change |
-| **Same Error Type** | All failures throw `TypeError` or `ConnectionError` | Broken dependency, env issue |
-| **Shared Fixture** | Tests using same `beforeEach`/setup fail together | Fixture setup failure cascading |
-| **Import Chain** | Failures follow the import graph | Dependency that fails to resolve |
-| **Environment** | All tests fail with connection/config errors | Missing env var, DB not running |
-| **Timing** | Tests pass individually, fail together | Race condition, shared state |
-| **Snapshot** | Multiple `toMatchSnapshot` failures | Intentional UI change (update snapshots) |
+|**Shared Module**|Multiple tests import from the same file that changed|Missing export, type change, API change|
+|**Same Error Type**|All failures throw `TypeError` or `ConnectionError`|Broken dependency, env issue|
+|**Shared Fixture**|Tests using same `beforeEach`/setup fail together|Fixture setup failure cascading|
+|**Import Chain**|Failures follow the import graph|Dependency that fails to resolve|
+|**Environment**|All tests fail with connection/config errors|Missing env var, DB not running|
+|**Timing**|Tests pass individually, fail together|Race condition, shared state|
+|**Snapshot**|Multiple `toMatchSnapshot` failures|Intentional UI change (update snapshots)|
 
 ### Cascade Detection Algorithm
 
@@ -125,25 +125,25 @@ Example:
 
 **FPF Confidence Levels:**
 
-| Confidence | Criteria |
+|Confidence|Criteria|
 |---|---|
-| **HIGH** | Same source file in >50% of failure stack traces |
-| **MEDIUM** | Same error type across multiple test files |
-| **LOW** | Failures appear independent, multiple root causes likely |
+|**HIGH**|Same source file in >50% of failure stack traces|
+|**MEDIUM**|Same error type across multiple test files|
+|**LOW**|Failures appear independent, multiple root causes likely|
 
 ## Step 5: Fix Recommendations
 
 For each cluster, provide actionable fixes:
 
-| Fix Type | Example | How to Verify |
+|Fix Type|Example|How to Verify|
 |---|---|---|
-| **Missing Export** | `export { fn }` added to module | Re-run failing tests |
-| **Type Mismatch** | Function signature changed, callers need update | Check callers with `grep_search` |
-| **Stale Mock** | Mock doesn't match new interface | Compare mock to actual implementation |
-| **Env Variable** | `.env.test` missing `DATABASE_URL` | Check `.env.example` vs `.env.test` |
-| **Snapshot Update** | Intentional UI change | Run with `--updateSnapshot` flag |
-| **Race Condition** | Tests share global state | Add isolation or `beforeEach` reset |
-| **Dependency Update** | Package API changed after upgrade | Check changelog of updated package |
+|**Missing Export**|`export { fn }` added to module|Re-run failing tests|
+|**Type Mismatch**|Function signature changed, callers need update|Check callers with `grep_search`|
+|**Stale Mock**|Mock doesn't match new interface|Compare mock to actual implementation|
+|**Env Variable**|`.env.test` missing `DATABASE_URL`|Check `.env.example` vs `.env.test`|
+|**Snapshot Update**|Intentional UI change|Run with `--updateSnapshot` flag|
+|**Race Condition**|Tests share global state|Add isolation or `beforeEach` reset|
+|**Dependency Update**|Package API changed after upgrade|Check changelog of updated package|
 
 ### Fix Priority Formula
 ```
@@ -241,11 +241,11 @@ If only snapshot tests fail → likely intentional UI change:
 
 ## Cross-Skill Integration
 
-| Paired Skill | Integration Point |
+|Paired Skill|Integration Point|
 |---|---|
-| `systematic-debugging` | Escalate when FPF is unclear → 4-phase debug methodology |
-| `testing-patterns` | Reference when recommending test structure improvements |
-| `workflow-optimizer` | Flag inefficient test-debug-retest loops |
+|`systematic-debugging`|Escalate when FPF is unclear → 4-phase debug methodology|
+|`testing-patterns`|Reference when recommending test structure improvements|
+|`workflow-optimizer`|Flag inefficient test-debug-retest loops|
 
 ## Anti-Hallucination Guard
 
@@ -256,44 +256,4 @@ If only snapshot tests fail → likely intentional UI change:
 - **Never guess at assertion values** — quote exactly what "Expected" and "Received" say in the output.
 - **Don't assume test runner** — auto-detect from output format, don't assume Jest.
 
-
----
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
 ---
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.