tribunal-kit 2.4.6 → 3.1.0

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

@@ -1,209 +1,103 @@
 ---
 name: tdd-workflow
-description: Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.
+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: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Test-Driven Development
-
-> TDD is not about testing. It is about design.
-> Writing the test first forces you to design the interface before you know how it will be implemented.
+# Test-Driven Development (TDD) — Defect-Free Execution Mastery
 
 ---
 
-## The RED-GREEN-REFACTOR Cycle
-
-Every change in TDD follows three phases:
+## 1. The Red-Green-Refactor Cycle
 
-```
-RED    → Write a test that fails (for code that doesn't exist yet)
-GREEN  → Write the minimum code to make the test pass
-REFACTOR → Clean up the code without changing its behavior
-```
-
-The constraint is important: in GREEN phase, write only enough code to pass the test. No more.
-
----
+TDD is a strict, irrevocable discipline. Do not write the implementation first.
 
-## RED Phase — Write a Failing Test
+### 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.
 
-Write a test that:
-1. Describes one specific piece of behavior
-2. Uses the API you wish existed (design the interface first)
-3. Fails for the right reason (not a syntax error — a logical failure)
+```typescript
+// 1. The failing test
+import { calculateDiscount } from './pricing';
 
-```ts
-// RED: This test fails because `validatePassword` doesn't exist yet
-it('should reject passwords shorter than 8 characters', () => {
-  const result = validatePassword('short');
-  expect(result.valid).toBe(false);
-  expect(result.error).toBe('Password must be at least 8 characters');
+test('Should apply 10% discount for orders over $100', () => {
+    expect(calculateDiscount(150)).toBe(135);
 });
+// ❌ FAILS: calculateDiscount is not defined
 ```
 
-**The test failing for the right reason is the signal.** If it fails because of a missing import, that's not the RED phase — that's setup.
+### Step 2: GREEN (Make it pass exactly)
+Write the absolute minimum, dumbest code required to make the test pass. Do not over-engineer.
 
----
-
-## GREEN Phase — Minimum Code to Pass
-
-Write only what is needed for the test to pass. Resist the urge to also handle the "other cases" — those will get their own tests.
-
-```ts
-// GREEN: Minimum implementation to pass the one test
-function validatePassword(password: string): { valid: boolean; error?: string } {
-  if (password.length < 8) {
-    return { valid: false, error: 'Password must be at least 8 characters' };
-  }
-  return { valid: true };
+```typescript
+// 2. The minimum implementation
+export function calculateDiscount(subtotal: number): number {
+    if (subtotal >= 100) return subtotal * 0.90;
+    return subtotal;
 }
+// ✅ PASSES.
 ```
 
-The code may be ugly. That is fine. GREEN is about passing the test, not about clean code.
-
----
-
-## REFACTOR Phase — Clean Without Breaking
+### Step 3: REFACTOR
+Now wrap the implementation in clean architectural principles. The tests guarantee you haven't broken the behavior while you optimize.
 
-Now that the test is green, improve the code:
-- Extract duplication
-- Clarify naming
-- Simplify logic
+```typescript
+// 3. The Refactor
+const DISCOUNT_THRESHOLD = 100;
+const DISCOUNT_RATE = 0.90;
 
-The constraint: all tests must stay green during and after refactor.
-
-```ts
-// REFACTOR: Same behavior, cleaner structure
-const MIN_PASSWORD_LENGTH = 8;
-
-function validatePassword(password: string): ValidationResult {
-  if (password.length < MIN_PASSWORD_LENGTH) {
-    return failure(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`);
-  }
-  return success();
+export function calculateDiscount(subtotal: number): number {
+    return subtotal >= DISCOUNT_THRESHOLD ? subtotal * DISCOUNT_RATE : subtotal;
 }
+// ✅ STILL PASSES. Safe to commit.
 ```
 
 ---
 
-## Triangulation
+## 2. Test Doubles (Mocks, Stubs, Spies)
 
-When a single test could be satisfied by a hardcoded value, write a second test to force a real implementation.
+Knowing *how* to mock separates amateurs from professionals. Over-mocking destroys architectural integrity.
 
-```ts
-// Test 1: Could be satisfied by always returning 2
-it('should add two numbers', () => {
-  expect(add(1, 1)).toBe(2);
-});
+|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')`|
 
-// Test 2: Forces a real implementation
-it('should add two different numbers', () => {
-  expect(add(3, 4)).toBe(7);
-});
-```
-
-**Rule:** If your implementation could be a constant or a special case, triangulate.
+### 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.
 
 ---
 
-## When TDD Pays Off
-
-TDD's ROI is highest for:
-- Business logic (calculation, validation, state machines)
-- Utility functions used in many places
-- Error handling paths that are hard to trigger manually
-- Refactoring existing code you want to verify still works
+## 3. Anti-Pattern: Testing Implementation Details
 
-TDD's ROI is lower for:
-- UI components (Storybook + visual review is often more efficient)
-- Database migrations (integration test after, not TDD)
-- Exploratory/prototype code that will be thrown away
-
----
-
-## Common TDD Mistakes
-
-| Mistake | Effect |
-|---|---|
-| Writing tests after implementation | Tests confirm the implementation, not the behavior |
-| Testing too much in one cycle | Large RED-GREEN steps hide design problems |
-| Skipping REFACTOR | Code quality degrades with each cycle |
-| Not reaching RED | Writing tests that pass immediately means the implementation already existed |
-| Mocking everything | Tests become coupled to implementation, not behavior |
-
----
+Tests should verify the *behavior* output, not the underlying code structure.
 
-## 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Ending the GREEN or REFACTOR phases based on assumption that the code is correct.
-- ✅ **Required:** You are explicitly forbidden from completing a test cycle or ending your task without providing **concrete terminal evidence** that the test suite actually ran and returned a strictly passing (GREEN) result.
-
----
-
-## Output Format
+```typescript
+class Account {
+    private balance = 0;
+    deposit(amount: number) { this.balance += amount; }
+    getBalance() { return this.balance; }
+}
 
-When this skill produces or reviews code, structure your output as follows:
+// ❌ 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
+});
 ```
-━━━ Tdd Workflow Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       Tdd Workflow
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
-```
-
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
-
-
----
-
-## 🤖 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.

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.