tribunal-kit 9.2.1 → 9.2.4

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

@@ -1,6 +1,6 @@
 ---
 name: test-result-analyzer
-description: Use when Ingests test logs and identifies root causes across multiple failing test files. Provides actionable fix recommendations.
+description: "Use when Ingests test logs and identifies root causes across multiple failing test files. Provides actionable fix recommendations."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -16,35 +16,6 @@ scripts-binding:
 
 # Test Result Analyzer Skill
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `test-result-analyzer` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when Ingests test logs and identifies root causes across multiple failing test files. Provides actionable fix recommendations.
-- **DO NOT activate when:** The task falls outside the `test-result-analyzer` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass       | Phase            | Core Action                                                                                  |
-| :--------- | :--------------- | :------------------------------------------------------------------------------------------- |
-| **Pass 1** | **Understand**   | Deconstruct the user's explicit objective, implicit requirements, and platform constraints.  |
-| **Pass 2** | **Plan**         | Decompose the task into smallest logical steps; map dependencies and required tool calls.    |
-| **Pass 3** | **Execute**      | Implement the solution with production-grade craft, zero placeholders, and strict typing.    |
-| **Pass 4** | **Verify**       | Run linters, unit tests, or compiler checks to validate structural correctness.              |
-| **Pass 5** | **Attack**       | Perform an adversarial review searching for edge-case failures, race conditions, and traps.  |
-| **Pass 6** | **Improve**      | Eliminate discovered friction, optimize performance, and harden error boundaries.            |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
@@ -297,49 +268,3 @@ If only snapshot tests fail → likely intentional UI change:
 - **Mark uncertainty**: `// UNCERTAIN: log format not fully recognized, manual review recommended`.
 - **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.
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario                               | Risk                                                 | Mitigation Strategy                                                             |
-| :------------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------ |
-| **Empty or Null Inputs**               | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers   |
-| **Network Timeout / Latency**          | Hanging operations or duplicate side-effects         | Implement bounded abort controllers, exponential backoff, and idempotency keys  |
-| **Concurrency / Race Conditions**      | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls          |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection      | Validate boundary payloads with Zod/Pydantic schemas prior to execution         |
-| **Resource / Memory Saturation**       | OOM errors, frame drops, or memory leaks             | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern                       | What AI Commonly Does Wrong                                              | What Is Actually Correct                                                 |
-| :--------------------------------- | :----------------------------------------------------------------------- | :----------------------------------------------------------------------- |
-| **Testing Implementation Details** | Asserting on private component state or internal helper functions        | Assert on observable user behaviors, DOM roles, and network outcomes     |
-| **Flaky Async Assertion**          | Using arbitrary setTimeout delays before asserting on asynchronous state | Use waitFor or findBy queries that poll with timeout bounds              |
-| **Shared Mutable State**           | Reusing database records across concurrent test runners                  | Isolate test databases per worker or execute in rolled-back transactions |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `test-engineer` · `qa-automation-engineer` · `logic-reviewer`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Do tests follow behavioral GIVEN/WHEN/THEN specifications?
-✅ Are happy path, failure paths, and boundary conditions (0, null, max) covered?
-✅ Are test mocks isolated and reset between successive suites?
-✅ Do E2E locators rely on stable ARIA attributes instead of brittle CSS selectors?
-✅ Did I verify test suite passes without flaky race conditions?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agent/skills/testing-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing-patterns
-description: Use when Testing mastery across stacks. Unit testing with Jest/Vitest/pytest, integration testing, E2E with Playwright, mocking strategies, test architecture (AAA, Given-When-Then), code coverage, snapshot testing, API testing, component testing with Testing Library, and TDD workflow. Use when writing tests, designing test architecture, or improving test coverage.
+description: "Use when Testing mastery across stacks. Unit testing with Jest/Vitest/pytest, integration testing, E2E with Playwright, mocking strategies, test architecture (AAA, Given-When-Then), code coverage, snapshot testing, API testing, component testing with Testing Library, and TDD workflow. Use when writing tests, designing test architecture, or improving test coverage."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -16,35 +16,6 @@ scripts-binding:
 
 # Testing Patterns — Cross-Stack Testing Mastery
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `testing-patterns` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when Testing mastery across stacks. Unit testing with Jest/Vitest/pytest, integration testing, E2E with Playwright, mocking strategies, test architecture (AAA, Given-When-Then), code coverage, snapshot testing, API testing, component testing with Testing Library, and TDD workflow. Use when writing tests, designing test architecture, or improving test coverage.
-- **DO NOT activate when:** The task falls outside the `testing-patterns` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass       | Phase            | Core Action                                                                                  |
-| :--------- | :--------------- | :------------------------------------------------------------------------------------------- |
-| **Pass 1** | **Understand**   | Deconstruct the user's explicit objective, implicit requirements, and platform constraints.  |
-| **Pass 2** | **Plan**         | Decompose the task into smallest logical steps; map dependencies and required tool calls.    |
-| **Pass 3** | **Execute**      | Implement the solution with production-grade craft, zero placeholders, and strict typing.    |
-| **Pass 4** | **Verify**       | Run linters, unit tests, or compiler checks to validate structural correctness.              |
-| **Pass 5** | **Attack**       | Perform an adversarial review searching for edge-case failures, race conditions, and traps.  |
-| **Pass 6** | **Improve**      | Eliminate discovered friction, optimize performance, and harden error boundaries.            |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
@@ -561,49 +532,3 @@ Coverage rules:
 - Focus coverage on: business logic, data transformations, auth/security
 - Skip coverage on: config files, types-only files, generated code
 ```
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario                               | Risk                                                 | Mitigation Strategy                                                             |
-| :------------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------ |
-| **Empty or Null Inputs**               | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers   |
-| **Network Timeout / Latency**          | Hanging operations or duplicate side-effects         | Implement bounded abort controllers, exponential backoff, and idempotency keys  |
-| **Concurrency / Race Conditions**      | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls          |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection      | Validate boundary payloads with Zod/Pydantic schemas prior to execution         |
-| **Resource / Memory Saturation**       | OOM errors, frame drops, or memory leaks             | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern                       | What AI Commonly Does Wrong                                              | What Is Actually Correct                                                 |
-| :--------------------------------- | :----------------------------------------------------------------------- | :----------------------------------------------------------------------- |
-| **Testing Implementation Details** | Asserting on private component state or internal helper functions        | Assert on observable user behaviors, DOM roles, and network outcomes     |
-| **Flaky Async Assertion**          | Using arbitrary setTimeout delays before asserting on asynchronous state | Use waitFor or findBy queries that poll with timeout bounds              |
-| **Shared Mutable State**           | Reusing database records across concurrent test runners                  | Isolate test databases per worker or execute in rolled-back transactions |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `test-engineer` · `qa-automation-engineer` · `logic-reviewer`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Do tests follow behavioral GIVEN/WHEN/THEN specifications?
-✅ Are happy path, failure paths, and boundary conditions (0, null, max) covered?
-✅ Are test mocks isolated and reset between successive suites?
-✅ Do E2E locators rely on stable ARIA attributes instead of brittle CSS selectors?
-✅ Did I verify test suite passes without flaky race conditions?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agent/skills/thermo-nuclear-code-quality-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: thermo-nuclear-code-quality-review
-description: Use when Run an extremely strict maintainability review for abstraction quality, giant files, spaghetti-condition growth, and architectural debt.
+description: "Use when Run an extremely strict maintainability review for abstraction quality, giant files, spaghetti-condition growth, and architectural debt."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -15,35 +15,6 @@ scripts-binding:
 
 # Thermo-Nuclear Code Quality Review — Zero-Tolerance Maintainability Audit
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `thermo-nuclear-code-quality-review` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when Run an extremely strict maintainability review for abstraction quality, giant files, spaghetti-condition growth, and architectural debt.
-- **DO NOT activate when:** The task falls outside the `thermo-nuclear-code-quality-review` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass       | Phase            | Core Action                                                                                  |
-| :--------- | :--------------- | :------------------------------------------------------------------------------------------- |
-| **Pass 1** | **Understand**   | Deconstruct the user's explicit objective, implicit requirements, and platform constraints.  |
-| **Pass 2** | **Plan**         | Decompose the task into smallest logical steps; map dependencies and required tool calls.    |
-| **Pass 3** | **Execute**      | Implement the solution with production-grade craft, zero placeholders, and strict typing.    |
-| **Pass 4** | **Verify**       | Run linters, unit tests, or compiler checks to validate structural correctness.              |
-| **Pass 5** | **Attack**       | Perform an adversarial review searching for edge-case failures, race conditions, and traps.  |
-| **Pass 6** | **Improve**      | Eliminate discovered friction, optimize performance, and harden error boundaries.            |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
@@ -89,49 +60,3 @@ function processOrder(order: Order) {
 ### 4. Direct Dependency Coupling
 
 - Modules importing concrete database models or vendor SDKs directly inside domain business logic instead of interface adapters are rejected.
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario                               | Risk                                                 | Mitigation Strategy                                                             |
-| :------------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------ |
-| **Empty or Null Inputs**               | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers   |
-| **Network Timeout / Latency**          | Hanging operations or duplicate side-effects         | Implement bounded abort controllers, exponential backoff, and idempotency keys  |
-| **Concurrency / Race Conditions**      | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls          |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection      | Validate boundary payloads with Zod/Pydantic schemas prior to execution         |
-| **Resource / Memory Saturation**       | OOM errors, frame drops, or memory leaks             | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern                    | What AI Commonly Does Wrong                                                       | What Is Actually Correct                                                       |
-| :------------------------------ | :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
-| **Hardcoded Secret Pattern**    | Committing API keys, tokens, or private salts into source code                    | Load credentials strictly via runtime environment variables and secret stores  |
-| **Prompt Injection Surface**    | Directly concatenating untrusted user input into LLM system prompts               | Wrap user content in isolated delimiters and strip injection control sequences |
-| **Missing Authorization Check** | Relying only on authentication token presence without checking tenant/object RBAC | Verify user permissions against the specific target record ID before mutation  |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `security-auditor` · `penetration-tester` · `backend-security-expert`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Are user inputs sanitized and treated as untrusted at system boundaries?
-✅ Are secrets loaded strictly via environment variables with zero hardcoding?
-✅ Is least-privilege enforcement active on APIs, tokens, and storage buckets?
-✅ Are prompt-injection delimiters and sanitizers wrapped around LLM inputs?
-✅ Did I verify encryption in transit and at rest for sensitive customer data?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agent/skills/thinking-protocol/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: thinking-protocol
-description: Use when Tribunal Agent Kit thinking and cognitive reasoning rules. Helps agents structure their thoughts and follow protocols.
+description: "Use when Tribunal Agent Kit thinking and cognitive reasoning rules. Helps agents structure their thoughts and follow protocols."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -16,83 +16,6 @@ scripts-binding:
 
 # Thinking Protocol — Cognitive Reasoning Rules
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `thinking-protocol` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when Tribunal Agent Kit thinking and cognitive reasoning rules. Helps agents structure their thoughts and follow protocols.
-- **DO NOT activate when:** The task falls outside the `thinking-protocol` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass       | Phase            | Core Action                                                                                  |
-| :--------- | :--------------- | :------------------------------------------------------------------------------------------- |
-| **Pass 1** | **Understand**   | Deconstruct the user's explicit objective, implicit requirements, and platform constraints.  |
-| **Pass 2** | **Plan**         | Decompose the task into smallest logical steps; map dependencies and required tool calls.    |
-| **Pass 3** | **Execute**      | Implement the solution with production-grade craft, zero placeholders, and strict typing.    |
-| **Pass 4** | **Verify**       | Run linters, unit tests, or compiler checks to validate structural correctness.              |
-| **Pass 5** | **Attack**       | Perform an adversarial review searching for edge-case failures, race conditions, and traps.  |
-| **Pass 6** | **Improve**      | Eliminate discovered friction, optimize performance, and harden error boundaries.            |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
-
----
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario                               | Risk                                                 | Mitigation Strategy                                                             |
-| :------------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------ |
-| **Empty or Null Inputs**               | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers   |
-| **Network Timeout / Latency**          | Hanging operations or duplicate side-effects         | Implement bounded abort controllers, exponential backoff, and idempotency keys  |
-| **Concurrency / Race Conditions**      | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls          |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection      | Validate boundary payloads with Zod/Pydantic schemas prior to execution         |
-| **Resource / Memory Saturation**       | OOM errors, frame drops, or memory leaks             | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern                       | What AI Commonly Does Wrong                                               | What Is Actually Correct                                                 |
-| :--------------------------------- | :------------------------------------------------------------------------ | :----------------------------------------------------------------------- |
-| **Hallucinated Tool Capabilities** | Assuming an external library or CLI command exists without verification   | Run a verification check or verify package.json before referencing tools |
-| **Premature Completion Claim**     | Declaring a task finished because code was generated without verification | Execute tests, linters, or terminal commands to provide concrete proof   |
-| **Context Bloat Dumping**          | Pasting entire multi-thousand-line files into prompt context              | Extract targeted excerpts, symbols, and signatures to preserve tokens    |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-reviewer`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Did I deconstruct the root objective before proposing architecture?
-✅ Did I identify dependencies, bottlenecks, and parallelizable sub-tasks?
-✅ Did I avoid over-engineering and select the simplest effective pattern?
-✅ Did I verify assumptions with concrete file reads instead of speculation?
-✅ Did I establish measurable verification criteria before completion?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agent/skills/to-spring-or-not-to-spring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: to-spring-or-not-to-spring
-description: Use when Audit and decide when to use physics-based spring animations (stiffness, damping, mass) vs duration-based cubic-bezier easing curves.
+description: "Use when Audit and decide when to use physics-based spring animations (stiffness, damping, mass) vs duration-based cubic-bezier easing curves."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -15,35 +15,6 @@ scripts-binding:
 
 # To Spring or Not to Spring — Motion Physics Decision Matrix
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `to-spring-or-not-to-spring` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when Audit and decide when to use physics-based spring animations (stiffness, damping, mass) vs duration-based cubic-bezier easing curves.
-- **DO NOT activate when:** The task falls outside the `to-spring-or-not-to-spring` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass       | Phase            | Core Action                                                                                  |
-| :--------- | :--------------- | :------------------------------------------------------------------------------------------- |
-| **Pass 1** | **Understand**   | Deconstruct the user's explicit objective, implicit requirements, and platform constraints.  |
-| **Pass 2** | **Plan**         | Decompose the task into smallest logical steps; map dependencies and required tool calls.    |
-| **Pass 3** | **Execute**      | Implement the solution with production-grade craft, zero placeholders, and strict typing.    |
-| **Pass 4** | **Verify**       | Run linters, unit tests, or compiler checks to validate structural correctness.              |
-| **Pass 5** | **Attack**       | Perform an adversarial review searching for edge-case failures, race conditions, and traps.  |
-| **Pass 6** | **Improve**      | Eliminate discovered friction, optimize performance, and harden error boundaries.            |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
@@ -70,49 +41,3 @@ Execute all non-trivial tasks through this 7-pass cognitive loop:
 1. **Stiffness** (Rigidity): High stiffness ($400+$) = snappy and tight; Low stiffness ($100$) = slow and lazy.
 2. **Damping** (Friction): High damping ($30+$) = zero overshoot bounce; Low damping ($10$) = heavy oscillating bounce.
 3. **Mass** (Weight): Higher mass ($2.0$) = feels heavy with momentum inertia.
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario                               | Risk                                                 | Mitigation Strategy                                                             |
-| :------------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------ |
-| **Empty or Null Inputs**               | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers   |
-| **Network Timeout / Latency**          | Hanging operations or duplicate side-effects         | Implement bounded abort controllers, exponential backoff, and idempotency keys  |
-| **Concurrency / Race Conditions**      | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls          |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection      | Validate boundary payloads with Zod/Pydantic schemas prior to execution         |
-| **Resource / Memory Saturation**       | OOM errors, frame drops, or memory leaks             | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern             | What AI Commonly Does Wrong                                           | What Is Actually Correct                                            |
-| :----------------------- | :-------------------------------------------------------------------- | :------------------------------------------------------------------ |
-| **The Instant Pop Trap** | Conditionally unmounting elements without animated interpolation      | Use AnimatePresence or coordinate morphs with continuous geometry   |
-| **Layout Thrashing**     | Animating width, height, top, or left inside animation loops          | Animate composite-only transform (translate3d, scale) and opacity   |
-| **Sluggish Duration**    | Setting micro-interaction transitions to 600ms+ causing interface lag | Cap interactive feedback at 160ms–240ms with snappy ease-out curves |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `frontend-reviewer` · `motion-reviewer` · `ui-ux-auditor`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Does animation maintain 60fps/120fps using transform and opacity?
-✅ Is optical mass conserved across state interpolations without volume collapse?
-✅ Is duration capped within micro-interaction budgets (160ms–280ms)?
-✅ Is prefers-reduced-motion respected with graceful instant fallbacks?
-✅ Did I prevent layout thrashing and continuous geometry mutations?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agent/skills/train-sentence-transformers/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: train-sentence-transformers
+description: Train or fine-tune sentence-transformers models across `SentenceTransformer` (bi-encoder, dense or static embedding model for retrieval, similarity, clustering, classification, paraphrase mining, dedup, multimodal), `CrossEncoder` (reranker, pair scoring for two-stage retrieval / pair classification), `SparseEncoder` (SPLADE, sparse embedding model for learned-sparse retrieval), and `MultiVectorEncoder` (ColBERT / late-interaction, per-token embeddings scored with MaxSim). Covers loss selection, hard-negative mining, evaluators, distillation, LoRA, Matryoshka, and Hugging Face Hub publishing. Use for any sentence-transformers training task.
+---
+
+# Train a sentence-transformers Model
+
+**This SKILL.md is a router, not a manual.** It tells you which references and example scripts to load for your task. The actual content (recommended losses, evaluators, training-script structure, model selection, training-arg knobs, troubleshooting) lives in `references/` and `scripts/`.
+
+**Do not synthesize a training script from this file alone.** Open the per-type production template (`scripts/train_<type>_example.py`) and copy it as your starting point. The templates contain load-bearing scaffolding (autocast helper, model-card class, logger silencing list, `force=True`, `seed`, TF32, version-compatible imports, named-evaluator metric handling) that prior agent runs have repeatedly missed when rolling their own from a synthesized snippet.
+
+## 1. Identify the model type
+
+| Tag | Class | What it does | When to pick |
+|---|---|---|---|
+| **[SentenceTransformer]** | `SentenceTransformer` (bi-encoder) | Maps each input to a fixed-dim dense vector | Retrieval, similarity, clustering, classification, paraphrase mining, dedup |
+| **[CrossEncoder]** | `CrossEncoder` (reranker) | Scores `(query, passage)` pairs jointly | Two-stage retrieval (rerank top-100 from bi-encoder), pair classification |
+| **[SparseEncoder]** | `SparseEncoder` (SPLADE) | Sparse vectors over the vocabulary | Learned-sparse retrieval, inverted-index backends (Elasticsearch / OpenSearch / Lucene) |
+| **[MultiVectorEncoder]** | `MultiVectorEncoder` (ColBERT) | One embedding per token, scored with MaxSim | Late-interaction retrieval, recall gains over bi-encoders at higher storage cost, multimodal (ColPali / ColQwen2) |
+
+Tiebreakers when the request is ambiguous: "embedding model" / "vector search" / "similarity" → **[SentenceTransformer]**. "rerank" / "ranker" / "two-stage" → **[CrossEncoder]**. "SPLADE" / "sparse" / "inverted index" → **[SparseEncoder]**. "ColBERT" / "late interaction" / "multi-vector" / "MaxSim" / "ColPali" / "ColQwen" → **[MultiVectorEncoder]**. If still unclear, ask.
+
+## 2. Required reading
+
+**Read these in full before writing any code. Do not triage by perceived relevance.**
+
+### Per-type: always required
+
+**[SentenceTransformer]**
+- `references/losses_sentence_transformer.md`: loss-to-data-shape mapping, `BatchSamplers.NO_DUPLICATES` requirement for MNRL-family, `Cached*` ↔ `gradient_checkpointing` incompatibility.
+- `references/evaluators_sentence_transformer.md`: evaluator-to-task mapping, `metric_for_best_model` key construction (named vs unnamed), per-evaluator `primary_metric` values.
+- `references/model_architectures.md`: encoder vs decoder vs static vs Router pipelines, pooling rules (mean / cls / lasttoken), auto-mean-pooling behavior for fresh-start MLM bases.
+- `scripts/train_sentence_transformer_example.py`: production template. Copy this as your starting point.
+
+**[CrossEncoder]**
+- `references/losses_cross_encoder.md`: pointwise / pairwise / listwise / distillation, `pos_weight` derivation, `activation_fn=Identity()` mandatory for non-BCE losses (silent eval-rank collapse otherwise).
+- `references/evaluators_cross_encoder.md`: `CrossEncoderRerankingEvaluator` recipe, named-evaluator key format `eval_{name}_{primary_metric}`.
+- `scripts/train_cross_encoder_example.py`: production template. Copy this as your starting point.
+
+**[SparseEncoder]**
+- `references/losses_sparse_encoder.md`: `SpladeLoss` wrapper requirement, FLOPS regularizer weights, smoke-test active-dim ramp behavior.
+- `references/evaluators_sparse_encoder.md`: `SparseNanoBEIREvaluator` (English-only) and the in-domain alternative, `eval_{name}_{primary_metric}` key format.
+- `scripts/train_sparse_encoder_example.py`: production template. Copy this as your starting point.
+
+**[MultiVectorEncoder]**
+- `references/losses_multi_vector_encoder.md`: MaxSim scoring, scale choice per scoring mode (`scale=1.0` for MaxSim, roughly the average query length for MeanMaxSim), MNRL / CachedMNRL / MarginMSE / DistillKLDiv, XTR-vs-ColBERT scoring, CachedMNRL ↔ `gradient_checkpointing` incompatibility.
+- `references/evaluators_multi_vector_encoder.md`: `MultiVectorNanoBEIREvaluator` (English-only) and the in-domain alternative, `eval_NanoBEIR_mean_maxsim_ndcg@10` key format, distillation-eval spearman variant.
+- `scripts/train_multi_vector_encoder_example.py`: production template. Copy this as your starting point.
+
+### Cross-cutting: always required (regardless of task)
+
+- `references/training_args.md`: `TrainingArguments` knobs, precision rules (load fp32 + autocast bf16/fp16, never `torch_dtype=bfloat16`), `warmup_steps` (float) vs deprecated `warmup_ratio`, `save_steps` must be a multiple of `eval_steps` for `load_best_model_at_end`, schedulers, HPO, tracker, resume, hub-push variants.
+- `references/dataset_formats.md`: column-matching rules (label name auto-detection, column-order-not-name), reshaping recipes, hard-negative mining options.
+- `references/base_model_selection.md`: discovery commands, per-type model namespaces, ModernBERT-family `max_seq_length=8192` trap, `datasets >= 4` script-loader rejection, non-English starting-point shortcuts.
+- `references/troubleshooting.md`: symptom-indexed failure recipes. Skim the section headings on every run, even a healthy one. The "Metrics don't improve" and "Hub push fails" entries cover bugs that bite frequently and are cheaper to recognize before they fire than to debug after.
+
+### Cross-cutting: load when applicable
+
+- `references/hardware_guide.md`: VRAM sizing, multi-GPU, FSDP / DeepSpeed, HF Jobs flavors. Required for >24GB models, multi-GPU, or HF Jobs runs.
+- `references/hf_jobs_execution.md`: required when running on HF Jobs.
+- `references/prompts_and_instructions.md`: required when using prompt-tuned bases (E5, BGE, GTE, Qwen3-Embedding, Instructor, Nomic, etc.) or adding `query: ` / `passage: ` style prefixes.
+
+### Variant scripts (open when the task matches)
+- **[SentenceTransformer]** `scripts/train_sentence_transformer_<matryoshka|multi_dataset|with_lora|distillation|make_multilingual|static_embedding>_example.py`.
+- **[CrossEncoder]** `scripts/train_cross_encoder_<distillation|listwise>_example.py`.
+- **[SparseEncoder]** `scripts/train_sparse_encoder_distillation_example.py`.
+- Hard-negative mining CLI: `scripts/mine_hard_negatives.py`.
+
+## 3. Defaults
+
+Override only if the user specifies otherwise:
+- **Local execution.** Pitch HF Jobs only if local hardware can't fit the job.
+- **Single run.** After it completes, propose experimentation if the user would benefit (weak/marginal verdict, "see how high you can push it" framing, etc.). Iteration rules in `references/training_args.md` (Experimentation section).
+- **Public Hub push at end-of-run, wrapped in try-except.** On HF Jobs (ephemeral env) ALSO enable in-trainer push (`push_to_hub=True` + `hub_strategy="every_save"`). Details in `references/hf_jobs_execution.md`.
+
+## 4. Constraints the produced script must satisfy
+
+These are non-negotiable contracts. Implementation lives in the production templates and references. Do not reinvent.
+
+- Capture the pre-training evaluator score as `baseline_eval` **before** `trainer.train()`.
+- Emit a single end-of-run line: `VERDICT: WIN|MARGINAL|REGRESSION | score=... | baseline=... | delta=...`. A monitor scrapes for this.
+- Silence `httpx`, `httpcore`, `huggingface_hub`, `urllib3`, `filelock`, `fsspec` to WARNING (otherwise HF download URLs flood the agent's context).
+- Tee logs to `logs/{RUN_NAME}.log`.
+- End with `model.push_to_hub(...)` wrapped in `try/except`.
+- Smoke-test before any long run (`max_steps=1` + tiny dataset slice). The production templates show one common pattern (`SMOKE_TEST` env var).
+- **[CrossEncoder]** Include `EarlyStoppingCallback(patience>=3)`. CE rerankers often peak mid-training and regress.
+- **[SparseEncoder]** Log `query_active_dims` / `corpus_active_dims` on the verdict line. High nDCG with collapsed sparsity is not a win. The keys come back name-prefixed (e.g. `..._query_active_dims`). Use suffix matching to pluck them. See the SPARSE production template for the exact pattern.
+- **[MultiVectorEncoder]** Match `scale` to the scoring mode on any MNRL-family loss: near `1.0` for unnormalized MaxSim (do not copy `scale=20.0` from bi-encoder MNRL), roughly the average query length with length-normalized MeanMaxSim, since each score is divided by its query's token count. `XTRScores` is a train-only `similarity_fct`: the evaluators reject it, so evaluation always scores with MaxSim, including for XTR-trained models.
+
+## 5. Workflow
+
+1. Identify the model type (§1). Ask if ambiguous.
+2. Load the §2 required-reading files for that type.
+3. Open `scripts/train_<type>_example.py` and copy it as your starting point.
+4. Replace `MODEL_NAME`, `DATASET_NAME`, `RUN_NAME`, the loss, and the evaluator with the user's task. Cross-check loss/data-shape match against `references/losses_<type>.md`. Cross-check the `metric_for_best_model` key against `references/evaluators_<type>.md` (named evaluators format the key as `eval_{name}_{primary_metric}`).
+5. Smoke-test (`max_steps=1`).
+6. Run.
+7. After the run, append to `logs/experiments.md` and propose iteration if the verdict is weak/marginal.
+
+## Prerequisites
+
+```bash
+pip install "sentence-transformers[train]>=5.0"        # add [train,image] / [audio] / [video] for [SentenceTransformer] multimodal
+                                                       # [MultiVectorEncoder] requires >=6.0
+pip install trackio                                    # optional tracker (or wandb / tensorboard / mlflow)
+hf auth login                                          # or set HF_TOKEN with write scope (for Hub push)
+```
+
+GPU strongly recommended. CPU works only for demos and `[SentenceTransformer]` `StaticEmbedding`.