tribunal-kit 9.2.4 → 9.2.6

package/skills/huggingface-vision-trainer/SKILL.md

@@ -1,10 +1,43 @@
----
-name: huggingface-vision-trainer
-description: Trains and fine-tunes vision models for object detection (D-FINE, RT-DETR v2, DETR, YOLOS), image classification (timm models — MobileNetV3, MobileViT, ResNet, ViT/DINOv3 — plus any Transformers classifier), and SAM/SAM2 segmentation using Hugging Face Transformers on Hugging Face Jobs cloud GPUs. Covers COCO-format dataset preparation, Albumentations augmentation, mAP/mAR evaluation, accuracy metrics, SAM segmentation with bbox/point prompts, DiceCE loss, hardware selection, cost estimation, Trackio monitoring, and Hub persistence. Use when users mention training object detection, image classification, SAM, SAM2, segmentation, image matting, DETR, D-FINE, RT-DETR, ViT, timm, MobileNet, ResNet, bounding box models, or fine-tuning vision models on Hugging Face Jobs.
----
-
-# Vision Model Training on Hugging Face Jobs
-
+---
+name: huggingface-vision-trainer
+description: "Use when Trains and fine-tunes vision models for object detection (D-FINE, RT-DETR v2, DETR, YOLOS), image classification (timm models — MobileNetV3, MobileViT, ResNet, ViT/DINOv3 — plus any Transformers classifier), and SAM/SAM2 segmentation using Hugging Face Transformers on Hugging Face Jobs cloud GPUs. Covers COCO-format dataset preparation, Albumentations augmentation, mAP/mAR evaluation, accuracy metrics, SAM segmentation with bbox/point prompts, DiceCE loss, hardware selection, cost estimation, Trackio monitoring, and Hub persistence. Use when users mention training object detection, image classification, SAM, SAM2, segmentation, image matting, DETR, D-FINE, RT-DETR, ViT, timm, MobileNet, ResNet, bounding box models, or fine-tuning vision models on Hugging Face Jobs."
+version: 6.0.0
+last-updated: 2026-09-29
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Vision Model Training on Hugging Face Jobs
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `huggingface-vision-trainer` 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 Trains and fine-tunes vision models for object detection (D-FINE, RT-DETR v2, DETR, YOLOS), image classification (timm models — MobileNetV3, MobileViT, ResNet, ViT/DINOv3 — plus any Transformers classifier), and SAM/SAM2 segmentation using Hugging Face Transformers on Hugging Face Jobs cloud GPUs. Covers COCO-format dataset preparation, Albumentations augmentation, mAP/mAR evaluation, accuracy metrics, SAM segmentation with bbox/point prompts, DiceCE loss, hardware selection, cost estimation, Trackio monitoring, and Hub persistence. Use when users mention training object detection, image classification, SAM, SAM2, segmentation, image matting, DETR, D-FINE, RT-DETR, ViT, timm, MobileNet, ResNet, bounding box models, or fine-tuning vision models on Hugging Face Jobs.
+- **DO NOT activate when:** The task falls outside the `huggingface-vision-trainer` domain or is managed by a different dedicated specialist agent.
+
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
 Train object detection, image classification, and SAM/SAM2 segmentation models on managed cloud GPUs. No local GPU setup required—results are automatically saved to the Hugging Face Hub.
 
 ## When to Use This Skill
@@ -590,4 +623,49 @@ For comprehensive troubleshooting: see [references/reliability_principles.md](re
 - [SAM2 Model Documentation](https://huggingface.co/docs/transformers/model_doc/sam2)
 - [SAM Model Documentation](https://huggingface.co/docs/transformers/model_doc/sam)
 - [Object Detection Datasets](https://huggingface.co/datasets?task_categories=task_categories:object-detection)
-- [Image Classification Datasets](https://huggingface.co/datasets?task_categories=task_categories:image-classification)
+- [Image Classification Datasets](https://huggingface.co/datasets?task_categories=task_categories:image-classification)
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **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 |
+|:---|:---|:---|
+| **Platform-Dependent Shell Commands** | Hardcoding $(cat ~/.cache/huggingface/token) or piping to jq | Use platform-agnostic token checks via env var HF_TOKEN and native JSON parsing |
+| **VRAM OOM Crash** | Loading 70B model weights on a consumer 16GB GPU without quantization | Calculate parameter bounds (fp16 = VRAM/2, Q4 = VRAM*2) and load with bitsandbytes/GGUF |
+| **Blocking Batch Generation** | Generating large batches synchronously without streaming or yield | Use TextIteratorStreamer or asynchronous generate workers to prevent request timeouts |
+
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `ai-code-reviewer` · `python-pro` · `performance-optimizer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
+
+### ✅ Pre-Flight Self-Audit Checklist
+```
+✅ Are model architectures and weights verified to fit within target hardware VRAM budgets?
+✅ Are pipeline requests guarded with bounded timeouts and retry backoffs?
+✅ Are dataset loading scripts operating in streaming mode to prevent out-of-memory errors?
+✅ Are API tokens and cache paths handled portably without assuming UNIX shell environments?
+✅ Are tokenizers and generation parameters (max_new_tokens, temperature) strictly bounded?
+```
+
+### 🛑 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/skills/huggingface-zerogpu/SKILL.md

@@ -1,10 +1,43 @@
----
-name: huggingface-zerogpu
-description: AI demos and GPU compute with Gradio Spaces and Hugging Face Spaces ZeroGPU. Use when writing or reviewing code that uses `@spaces.GPU`, configuring `python_version` or `requirements.txt` for a ZeroGPU Space, or handling ZeroGPU-specific code constraints — pickle-based process isolation, `gr.State` semantics across the worker boundary, no `torch.compile` (use AoTI instead), CUDA wheel-only builds (no `nvcc` at build or runtime), large vs xlarge sizing, and dynamic duration callables. Make sure to use this skill whenever the user mentions ZeroGPU, `@spaces.GPU`, or the `spaces` Python package, or hits ZeroGPU-specific code errors like `PicklingError` across the worker boundary, `illegal duration`, or `flash-attn` wheel-build failures — even when the user does not explicitly ask for ZeroGPU coding guidance. Trigger on `import spaces` or `@spaces.GPU` in code.
----
-
-# Hugging Face ZeroGPU
-
+---
+name: huggingface-zerogpu
+description: "Use when AI demos and GPU compute with Gradio Spaces and Hugging Face Spaces ZeroGPU. Use when writing or reviewing code that uses `@spaces.GPU`, configuring `python_version` or `requirements.txt` for a ZeroGPU Space, or handling ZeroGPU-specific code constraints — pickle-based process isolation, `gr.State` semantics across the worker boundary, no `torch.compile` (use AoTI instead), CUDA wheel-only builds (no `nvcc` at build or runtime), large vs xlarge sizing, and dynamic duration callables. Make sure to use this skill whenever the user mentions ZeroGPU, `@spaces.GPU`, or the `spaces` Python package, or hits ZeroGPU-specific code errors like `PicklingError` across the worker boundary, `illegal duration`, or `flash-attn` wheel-build failures — even when the user does not explicitly ask for ZeroGPU coding guidance. Trigger on `import spaces` or `@spaces.GPU` in code."
+version: 6.0.0
+last-updated: 2026-09-29
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Hugging Face ZeroGPU
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `huggingface-zerogpu` 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 AI demos and GPU compute with Gradio Spaces and Hugging Face Spaces ZeroGPU. Use when writing or reviewing code that uses `@spaces.GPU`, configuring `python_version` or `requirements.txt` for a ZeroGPU Space, or handling ZeroGPU-specific code constraints — pickle-based process isolation, `gr.State` semantics across the worker boundary, no `torch.compile` (use AoTI instead), CUDA wheel-only builds (no `nvcc` at build or runtime), large vs xlarge sizing, and dynamic duration callables. Make sure to use this skill whenever the user mentions ZeroGPU, `@spaces.GPU`, or the `spaces` Python package, or hits ZeroGPU-specific code errors like `PicklingError` across the worker boundary, `illegal duration`, or `flash-attn` wheel-build failures — even when the user does not explicitly ask for ZeroGPU coding guidance. Trigger on `import spaces` or `@spaces.GPU` in code.
+- **DO NOT activate when:** The task falls outside the `huggingface-zerogpu` domain or is managed by a different dedicated specialist agent.
+
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
 Rules and patterns for ML demos on Hugging Face Spaces with **ZeroGPU** hardware. Covers `@spaces.GPU`, duration and quota tuning, process isolation, the CUDA availability model, concurrency safety, and CUDA build constraints.
 
 ## Scope
@@ -286,4 +319,49 @@ How to achieve this depends on your tooling:
 
 ### Pin `torch` to match wheel tags
 
-If you install a CUDA-dependent wheel via direct URL, the wheel filename encodes the `torch` major.minor it was built against (e.g. `cu12torch2.8`). Pin `torch==X.Y.Z` in `requirements.txt` to match — otherwise pip may resolve `torch` to a different version and the Space fails on first import. Details and the kernels-community alternative are in `references/cuda-and-deps.md`.
+If you install a CUDA-dependent wheel via direct URL, the wheel filename encodes the `torch` major.minor it was built against (e.g. `cu12torch2.8`). Pin `torch==X.Y.Z` in `requirements.txt` to match — otherwise pip may resolve `torch` to a different version and the Space fails on first import. Details and the kernels-community alternative are in `references/cuda-and-deps.md`.
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **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 |
+|:---|:---|:---|
+| **Platform-Dependent Shell Commands** | Hardcoding $(cat ~/.cache/huggingface/token) or piping to jq | Use platform-agnostic token checks via env var HF_TOKEN and native JSON parsing |
+| **VRAM OOM Crash** | Loading 70B model weights on a consumer 16GB GPU without quantization | Calculate parameter bounds (fp16 = VRAM/2, Q4 = VRAM*2) and load with bitsandbytes/GGUF |
+| **Blocking Batch Generation** | Generating large batches synchronously without streaming or yield | Use TextIteratorStreamer or asynchronous generate workers to prevent request timeouts |
+
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `ai-code-reviewer` · `python-pro` · `performance-optimizer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
+
+### ✅ Pre-Flight Self-Audit Checklist
+```
+✅ Are model architectures and weights verified to fit within target hardware VRAM budgets?
+✅ Are pipeline requests guarded with bounded timeouts and retry backoffs?
+✅ Are dataset loading scripts operating in streaming mode to prevent out-of-memory errors?
+✅ Are API tokens and cache paths handled portably without assuming UNIX shell environments?
+✅ Are tokenizers and generation parameters (max_new_tokens, temperature) strictly bounded?
+```
+
+### 🛑 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/skills/human-gate-negotiation/SKILL.md

@@ -1,30 +1,96 @@
 ---
 name: human-gate-negotiation
-description: "Use when preparing concise impact reports before approval requests for high-risk, non-idempotent actions."
-version: 1.0.0
-last-updated: 2026-09-25
+description: "Use when preparing structured impact reports and negotiating approval before executing high-risk, irreversible, or non-idempotent actions (production deploy, database migration, file deletion, permission grants)."
+version: 6.0.0
+last-updated: 2026-09-29
 skills:
   - fabel-protocol
+  - devops-engineer
 tools: Read, Grep, Glob, Bash, Edit, Write
 scripts-binding:
   - .agent/scripts/harness_manager.js
+  - .agent/scripts/verify_all.js
+  - .agent/scripts/lint_runner.js
 ---
 
-# Human Gate Negotiation
+# Human Gate Negotiation — High-Risk Action Safety Protocol
 
-## Context
-When an agent attempts a high-risk operation (deploying to production, running `rm -rf`, running a database migration), it MUST be paused, and explicit approval must be sought from the Human Gate. 
+## Activation Boundaries
+- **Activate when:** Use when preparing structured impact reports and negotiating approval before executing high-risk, irreversible, or non-idempotent actions (production deploy, database migration, file deletion, permission grants).
+- **DO NOT activate when:** The task falls outside the `human-gate-negotiation` domain or is managed by a different dedicated specialist agent.
 
-## The Impact Report Format
-Never just ask "Can I run this?". You must provide a structured report outlining the consequences of the action so the human can make an informed decision.
 
-**Mandatory Report Structure:**
-1. **Proposed Action**: The exact command or script to be executed.
-2. **Purpose**: Why this is necessary.
-3. **Files/Resources Affected**: Which systems will be mutated.
-4. **Expected Side Effects**: Downtime, data loss, irreversible state changes.
-5. **Verification Status**: Proof that tests passed before reaching this gate.
-6. **Rollback Instructions**: How to undo this action if it fails in production.
+## 🔁 Multi-Pass Execution Protocol
 
-## Agent Behavior
-Once the report is generated, the agent must enter a sleep/wait state and CANNOT proceed until the human explicitly provides an approval token.
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
+## Mandatory Pre-Flight Context Inspection
+1. **Action Risk Tier**: Determine Impact Tier (Tier 0: Fast-Pass, Tier 1: Express, Tier 2: Targeted, Tier 3: Full Gauntlet).
+2. **Idempotency Check**: Verify whether the action is reversible or non-idempotent (e.g. dropping a column vs adding an index).
+3. **Blast Radius Calculation**: Identify all systems, tables, users, or endpoints affected by this mutation.
+4. **Pre-Flight Verification Proof**: Confirm all tests and static analysis passed BEFORE requesting human approval.
+5. **Rollback Plan**: Formulate explicit, tested rollback commands to undo the action in case of failure.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Mandatory Human Gate Impact Report Schema
+```markdown
+━━━ 🛑 HUMAN GATE APPROVAL REQUEST ━━━━━━━━━━━━━━━━━
+Action:           [Exact command or code modification to be executed]
+Target Systems:   [Files, databases, infrastructure resources affected]
+Impact Tier:      [Tier 3 — High Blast Radius]
+
+Why It Is Needed: [1-2 sentences stating the concrete business/technical necessity]
+
+Blast Radius:
+  - Tables / Columns: [List affected tables/models]
+  - Downtime / Locks: [Estimated locking duration, zero-downtime guarantees]
+  - Reversibility:    [Fully Reversible / Irreversible without backup]
+
+Pre-Flight Proof:
+  - Tests:          ✅ 42/42 passing (test output verified)
+  - Static Lint:     ✅ 0 errors, 0 warnings
+  - Security Scan:   ✅ 0 critical/high findings
+
+Rollback Procedure:
+  - Command:        [Exact rollback command, e.g. alembic downgrade -1]
+  - Recovery Time:  [< 30 seconds]
+
+Decision: [Approve (Y) / Reject (N) / Revise (R)]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Vague or Casual Approval Prompts** | Asking "Can I run this?" leads to accidental destructive actions | Mandate the 6-point Human Gate Impact Report schema for all Tier 3 actions |
+| **Unstoppable Autonomous Run** | Agent continues executing commands while waiting for human response | Put agent into explicit wait/sleep state; block all further tool execution until approval token is received |
+
+## 🏛️ Tribunal Verification & Guardrails
+
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
+
+- **Active Reviewers:** `security-auditor`, `orchestrator`
+- **Evidence Standard:** Differentiate `[OBSERVED]` test proof from `[INFERRED]` operational risk.
+
+## 🤖 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 |

package/skills/i18n-localization/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: i18n-localization
-description: "Use when Internationalization (i18n) and localization mastery. Abstracting hardcoded strings, managing JSON/YAML translation dictionaries, bidirectional routing (RTL support for Arabic/Hebrew), Pluralization algorithms, date/currency formatting, and SSR locale detection in Next.js/React. Use when preparing an application for global multilingual scaling."
-version: 5.0.0
-last-updated: 2026-09-13
+description: "Use when executing, coordinating, planning, or reviewing i18n localization agent workflows, cognitive loops, and architecture standards."
+version: 6.0.0
+last-updated: 2026-09-29
 skills:
   - nextjs-react-expert
   - adapt
@@ -15,120 +15,178 @@ scripts-binding:
 
 # i18n & Localization — Global Scale Mastery
 
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## Hallucination Traps (Read First)
-
-- ❌ Concatenating translated strings (`'Hello ' + name`) -> ✅ Use interpolation: `t('greeting', { name })` to handle word order differences
-- ❌ Hardcoding date/number formats -> ✅ Use `Intl.DateTimeFormat` and `Intl.NumberFormat` with the user's locale
-- ❌ Assuming all languages read left-to-right -> ✅ Arabic, Hebrew, Farsi are RTL; use CSS `dir='auto'` and logical properties
-- ❌ Using string length for validation on translated text -> ✅ Translations can be 30-200% longer than English; design for expansion
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `i18n-localization` 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 executing, coordinating, planning, or reviewing i18n localization agent workflows, cognitive loops, and architecture standards.
+- **DO NOT activate when:** The task falls outside the `i18n-localization` domain or is managed by a different dedicated specialist agent.
 
-## 1. The i18n Architecture (Next.js / React)
 
-Do not hardcode strings inside UI components. Use a standardized library (e.g., `next-intl` or `react-i18next`).
+## 🔁 Multi-Pass Execution Protocol
 
-### Step 1: Dictionary Abstraction
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
 
-```json
-// messages/en.json
-{
-  "Dashboard": {
-    "welcomeMessage": "Welcome back, {name}!",
-    "unreadAlerts": "{count, plural, =0 {No unread alerts} one {You have 1 unread alert} other {You have # unread alerts}}"
-  }
-}
-```
 
-### Step 2: Component Implementation
-
-```tsx
-// ❌ BAD: Hardcoded English text and manual variable interpolation
-export function Header({ user, alertCount }) {
-  return (
-    <h1>
-      Welcome back, {user.name}! You have {alertCount} alerts.
-    </h1>
-  );
-}
-
-// ✅ GOOD: i18n Abstraction (using next-intl)
-import { useTranslations } from 'next-intl';
-
-export function Header({ user, alertCount }) {
-  const t = useTranslations('Dashboard');
-
-  return (
-    <header>
-      <h1>{t('welcomeMessage', { name: user.name })}</h1>
-      <p>{t('unreadAlerts', { count: alertCount })}</p>
-    </header>
-  );
-}
-```
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
 
+## Hallucination Traps (Read First)
+
+- ❌ Concatenating translated strings (`'Hello ' + name`) -> ✅ Use interpolation: `t('greeting', { name })` to handle word order differences
+- ❌ Hardcoding date/number formats -> ✅ Use `Intl.DateTimeFormat` and `Intl.NumberFormat` with the user's locale
+- ❌ Assuming all languages read left-to-right -> ✅ Arabic, Hebrew, Farsi are RTL; use CSS `dir='auto'` and logical properties
+- ❌ Using string length for validation on translated text -> ✅ Translations can be 30-200% longer than English; design for expansion
+
 ---
+## 1. The i18n Architecture (Next.js / React)
+
+Do not hardcode strings inside UI components. Use a standardized library (e.g., `next-intl` or `react-i18next`).
+
+### Step 1: Dictionary Abstraction
+
+```json
+// messages/en.json
+{
+  "Dashboard": {
+    "welcomeMessage": "Welcome back, {name}!",
+    "unreadAlerts": "{count, plural, =0 {No unread alerts} one {You have 1 unread alert} other {You have # unread alerts}}"
+  }
+}
+```
+
+### Step 2: Component Implementation
+
+```tsx
+// ❌ BAD: Hardcoded English text and manual variable interpolation
+export function Header({ user, alertCount }) {
+  return (
+    <h1>
+      Welcome back, {user.name}! You have {alertCount} alerts.
+    </h1>
+  );
+}
+
+// ✅ GOOD: i18n Abstraction (using next-intl)
+import { useTranslations } from 'next-intl';
+
+export function Header({ user, alertCount }) {
+  const t = useTranslations('Dashboard');
+
+  return (
+    <header>
+      <h1>{t('welcomeMessage', { name: user.name })}</h1>
+      <p>{t('unreadAlerts', { count: alertCount })}</p>
+    </header>
+  );
+}
+```
+
+---
+
+## 2. Advanced Native Formatting (`Intl`)
+
+Do not install `moment.js` or write massive regex string parsers to format currencies in Euros vs Dollars. The browser handles this natively with the `Intl` API.
+
+```typescript
+// Data/Currency Formatting correctly tied to the active locale
+const locale = 'de-DE';
+
+// ✅ Currency
+const price = new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(1200.5);
+// Output in Germany: "1.200,50 €"
+
+// ✅ Dates
+const date = new Intl.DateTimeFormat(locale, { dateStyle: 'full' }).format(new Date());
+// Output in Germany: "Freitag, 2. April 2026"
+
+// ✅ Relative Time
+const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+rtf.format(-2, 'day'); // Output: "vorgestern" (the day before yesterday)
+```
+
+---
+
+## 3. Bidirectional Architecture (RTL)
+
+For languages like Arabic and Hebrew, the UI must fundamentally flip horizontally. Right-To-Left (RTL) breaks standard CSS `marginLeft` and `marginRight`.
+
+**The Solution:** Logical CSS Properties.
+Tailwind v4 (and modern CSS) natively supports logical direction.
+
+```css
+/* ❌ BAD: Hardcoded physical space */
+.btn {
+  margin-left: 10px;
+} /* Will break layout in Hebrew */
+
+/* ✅ GOOD: Logical spacing (Tailwind: ms-4, me-4) */
+.btn {
+  margin-inline-start: 10px;
+} /* Automatically flips in RTL mode */
+```
+
+_In React HTML tag:_ `<html lang="ar" dir="rtl">`
+
+---
+
+## 4. Routing and SSR Detection
+
+Users should not face English UI natively in Japan. Detect their browser headers at the edge routing layer.
+
+In Next.js Middleware:
+
+1. Parse the incoming `Accept-Language` header.
+2. Intercept requests to `/dashboard`.
+3. Rewrite URL to the detected locale (e.g., `/ja/dashboard`).
 
-## 2. Advanced Native Formatting (`Intl`)
-
-Do not install `moment.js` or write massive regex string parsers to format currencies in Euros vs Dollars. The browser handles this natively with the `Intl` API.
-
-```typescript
-// Data/Currency Formatting correctly tied to the active locale
-const locale = 'de-DE';
-
-// ✅ Currency
-const price = new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(1200.5);
-// Output in Germany: "1.200,50 €"
+## 🚨 Edge-Case & Failure Mode Matrix
 
-// ✅ Dates
-const date = new Intl.DateTimeFormat(locale, { dateStyle: 'full' }).format(new Date());
-// Output in Germany: "Freitag, 2. April 2026"
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **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 |
 
-// ✅ Relative Time
-const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
-rtf.format(-2, 'day'); // Output: "vorgestern" (the day before yesterday)
-```
 
----
+## 🏛️ Tribunal Verification & Guardrails
 
-## 3. Bidirectional Architecture (RTL)
+**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
 
-For languages like Arabic and Hebrew, the UI must fundamentally flip horizontally. Right-To-Left (RTL) breaks standard CSS `marginLeft` and `marginRight`.
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
 
-**The Solution:** Logical CSS Properties.
-Tailwind v4 (and modern CSS) natively supports logical direction.
-
-```css
-/* ❌ BAD: Hardcoded physical space */
-.btn {
-  margin-left: 10px;
-} /* Will break layout in Hebrew */
-
-/* ✅ GOOD: Logical spacing (Tailwind: ms-4, me-4) */
-.btn {
-  margin-inline-start: 10px;
-} /* Automatically flips in RTL mode */
+### ✅ 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?
 ```
 
-_In React HTML tag:_ `<html lang="ar" dir="rtl">`
-
----
-
-## 4. Routing and SSR Detection
-
-Users should not face English UI natively in Japan. Detect their browser headers at the edge routing layer.
-
-In Next.js Middleware:
-
-1. Parse the incoming `Accept-Language` header.
-2. Intercept requests to `/dashboard`.
-3. Rewrite URL to the detected locale (e.g., `/ja/dashboard`).
+### 🛑 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.