tribunal-kit 9.2.3 → 9.2.5

package/.agent/agents/swarm-worker-contracts.md

@@ -1,170 +1,170 @@
-# 📋 Swarm Worker Contracts
-
-Defines the strict JSON schemas for all Swarm dispatch and result payloads.
-Every `WorkerRequest` and `WorkerResult` MUST conform to these schemas.
-Used by: `supervisor-agent`, `swarm_dispatcher.js`, `/swarm` workflow.
-
----
-
-## WorkerRequest Schema
-
-Emitted by the **Supervisor Agent** when dispatching a sub-task to a Worker.
-
-```typescript
-interface WorkerRequest {
-  // Unique identifier for correlating dispatches to results.
-  // Format: standard UUID v4 (randomly generated per invocation).
-  task_id: string;
-
-  // The category of work being requested.
-  type:
-    | 'research' // Understand or explain something
-    | 'generate_code' // Write new code
-    | 'review_code' // Audit existing code
-    | 'debug' // Find and fix a bug
-    | 'plan' // Produce a structured plan only (no code)
-    | 'design_schema' // Design a database or data schema
-    | 'write_docs' // Write documentation or comments
-    | 'security_audit' // OWASP security review
-    | 'optimize' // Refactor for performance
-    | 'test'; // Write or run tests
-
-  // The agent to route this WorkerRequest to.
-  // MUST match a filename in .agent/agents/ (without the .md extension).
-  agent: string;
-
-  // Single-sentence description of the task.
-  // MUST be specific and self-contained.
-  // ❌ "Handle the API"
-  // ✅ "Create a POST /users endpoint in Express that validates the request body"
-  goal: string;
-
-  // Minimal context the Worker requires to complete the goal.
-  // MUST NOT include: full file contents, entire conversation history, unrelated code.
-  // MUST include: relevant package versions, existing patterns, specific constraints.
-  context: string;
-
-  // Maximum number of retry attempts on failure, including the first attempt.
-  // Minimum: 1. Maximum: 3. Default: 3.
-  max_retries: number;
-}
-```
-
-### WorkerRequest Validation Rules
-
-| Field         | Rules                                                                            |
-| ------------- | -------------------------------------------------------------------------------- |
-| `task_id`     | Non-empty string. UUID v4 format preferred. Must be unique per swarm invocation. |
-| `type`        | Must be one of the 10 listed enum values exactly.                                |
-| `agent`       | Must match a file that exists at `.agent/agents/{agent}.md`.                     |
-| `goal`        | Non-empty. Single sentence. Max 200 characters.                                  |
-| `context`     | Non-empty. Max 800 characters. No full file dumps.                               |
-| `max_retries` | Integer 1–3 inclusive.                                                           |
-
----
-
-## WorkerResult Schema
-
-Emitted by the **Worker Agent** (or Supervisor on behalf of a failed Worker) after completing or failing a task.
-
-```typescript
-interface WorkerResult {
-  // Must match the task_id from the originating WorkerRequest.
-  task_id: string;
-
-  // The agent that processed this request.
-  agent: string;
-
-  // Outcome of the Worker's execution.
-  status:
-    | 'success' // Task completed. Output is valid.
-    | 'failure' // Task failed but retries remain.
-    | 'escalate'; // Task failed after max_retries. Requires human intervention.
-
-  // The agent's output if status is "success".
-  // Empty string if status is "failure" or "escalate".
-  output: string;
-
-  // Error message if status is "failure" or "escalate".
-  // MUST be specific — never just "Something went wrong."
-  // Empty string if status is "success".
-  error: string;
-
-  // Number of attempts made so far, including the current one.
-  // Starts at 1. Never exceeds max_retries from the WorkerRequest.
-  attempts: number;
-}
-```
-
-### WorkerResult Validation Rules
-
-| Field      | Rules                                                                       |
-| ---------- | --------------------------------------------------------------------------- |
-| `task_id`  | Must match a previously dispatched WorkerRequest task_id.                   |
-| `agent`    | Must match the agent from the originating WorkerRequest.                    |
-| `status`   | Must be exactly: `"success"`, `"failure"`, or `"escalate"`.                 |
-| `output`   | Required if status is `"success"`. Empty string otherwise.                  |
-| `error`    | Required if status is `"failure"` or `"escalate"`. Empty string if success. |
-| `attempts` | Integer ≥ 1. Must not exceed `max_retries` from the WorkerRequest.          |
-
----
-
-## Example: Successful Dispatch/Result Pair
-
-**WorkerRequest:**
-
-```json
-{
-  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-  "type": "generate_code",
-  "agent": "backend-specialist",
-  "goal": "Write an Express POST /users endpoint with zod body validation",
-  "context": "Express v4, zod v3.22. Body: { name: string, email: string }. Return 201 on success, 400 on validation failure.",
-  "max_retries": 3
-}
-```
-
-**WorkerResult:**
-
-```json
-{
-  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-  "agent": "backend-specialist",
-  "status": "success",
-  "output": "// ... generated code ...",
-  "error": "",
-  "attempts": 1
-}
-```
-
----
-
-## Example: Escalated Failure
-
-**WorkerResult:**
-
-```json
-{
-  "task_id": "b6a921c9-aa4e-4d1a-9862-d3f0b0e3f101",
-  "agent": "database-architect",
-  "status": "escalate",
-  "output": "",
-  "error": "Cannot infer schema without knowing whether PostgreSQL or MySQL is the target. Context is ambiguous.",
-  "attempts": 3
-}
-```
-
----
-
-## swarm_dispatcher.js Integration
-
-The `swarm_dispatcher.js` script validates **WorkerRequest** payloads before dispatch.
-
-**Usage:**
-
-```bash
-node .agent/scripts/swarm_dispatcher.js --mode swarm --file worker_request.json
-node .agent/scripts/swarm_dispatcher.js --mode swarm --payload '{"task_id":"...","type":"generate_code","agent":"backend-specialist","goal":"...","context":"...","max_retries":3}'
-```
-
-Exits `0` on valid payload. Exits `1` on any schema violation with a specific error message per field.
+# 📋 Swarm Worker Contracts
+
+Defines the strict JSON schemas for all Swarm dispatch and result payloads.
+Every `WorkerRequest` and `WorkerResult` MUST conform to these schemas.
+Used by: `supervisor-agent`, `swarm_dispatcher.js`, `/swarm` workflow.
+
+---
+
+## WorkerRequest Schema
+
+Emitted by the **Supervisor Agent** when dispatching a sub-task to a Worker.
+
+```typescript
+interface WorkerRequest {
+  // Unique identifier for correlating dispatches to results.
+  // Format: standard UUID v4 (randomly generated per invocation).
+  task_id: string;
+
+  // The category of work being requested.
+  type:
+    | 'research' // Understand or explain something
+    | 'generate_code' // Write new code
+    | 'review_code' // Audit existing code
+    | 'debug' // Find and fix a bug
+    | 'plan' // Produce a structured plan only (no code)
+    | 'design_schema' // Design a database or data schema
+    | 'write_docs' // Write documentation or comments
+    | 'security_audit' // OWASP security review
+    | 'optimize' // Refactor for performance
+    | 'test'; // Write or run tests
+
+  // The agent to route this WorkerRequest to.
+  // MUST match a filename in .agent/agents/ (without the .md extension).
+  agent: string;
+
+  // Single-sentence description of the task.
+  // MUST be specific and self-contained.
+  // ❌ "Handle the API"
+  // ✅ "Create a POST /users endpoint in Express that validates the request body"
+  goal: string;
+
+  // Minimal context the Worker requires to complete the goal.
+  // MUST NOT include: full file contents, entire conversation history, unrelated code.
+  // MUST include: relevant package versions, existing patterns, specific constraints.
+  context: string;
+
+  // Maximum number of retry attempts on failure, including the first attempt.
+  // Minimum: 1. Maximum: 3. Default: 3.
+  max_retries: number;
+}
+```
+
+### WorkerRequest Validation Rules
+
+| Field         | Rules                                                                            |
+| ------------- | -------------------------------------------------------------------------------- |
+| `task_id`     | Non-empty string. UUID v4 format preferred. Must be unique per swarm invocation. |
+| `type`        | Must be one of the 10 listed enum values exactly.                                |
+| `agent`       | Must match a file that exists at `.agent/agents/{agent}.md`.                     |
+| `goal`        | Non-empty. Single sentence. Max 200 characters.                                  |
+| `context`     | Non-empty. Max 800 characters. No full file dumps.                               |
+| `max_retries` | Integer 1–3 inclusive.                                                           |
+
+---
+
+## WorkerResult Schema
+
+Emitted by the **Worker Agent** (or Supervisor on behalf of a failed Worker) after completing or failing a task.
+
+```typescript
+interface WorkerResult {
+  // Must match the task_id from the originating WorkerRequest.
+  task_id: string;
+
+  // The agent that processed this request.
+  agent: string;
+
+  // Outcome of the Worker's execution.
+  status:
+    | 'success' // Task completed. Output is valid.
+    | 'failure' // Task failed but retries remain.
+    | 'escalate'; // Task failed after max_retries. Requires human intervention.
+
+  // The agent's output if status is "success".
+  // Empty string if status is "failure" or "escalate".
+  output: string;
+
+  // Error message if status is "failure" or "escalate".
+  // MUST be specific — never just "Something went wrong."
+  // Empty string if status is "success".
+  error: string;
+
+  // Number of attempts made so far, including the current one.
+  // Starts at 1. Never exceeds max_retries from the WorkerRequest.
+  attempts: number;
+}
+```
+
+### WorkerResult Validation Rules
+
+| Field      | Rules                                                                       |
+| ---------- | --------------------------------------------------------------------------- |
+| `task_id`  | Must match a previously dispatched WorkerRequest task_id.                   |
+| `agent`    | Must match the agent from the originating WorkerRequest.                    |
+| `status`   | Must be exactly: `"success"`, `"failure"`, or `"escalate"`.                 |
+| `output`   | Required if status is `"success"`. Empty string otherwise.                  |
+| `error`    | Required if status is `"failure"` or `"escalate"`. Empty string if success. |
+| `attempts` | Integer ≥ 1. Must not exceed `max_retries` from the WorkerRequest.          |
+
+---
+
+## Example: Successful Dispatch/Result Pair
+
+**WorkerRequest:**
+
+```json
+{
+  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "type": "generate_code",
+  "agent": "backend-specialist",
+  "goal": "Write an Express POST /users endpoint with zod body validation",
+  "context": "Express v4, zod v3.22. Body: { name: string, email: string }. Return 201 on success, 400 on validation failure.",
+  "max_retries": 3
+}
+```
+
+**WorkerResult:**
+
+```json
+{
+  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "agent": "backend-specialist",
+  "status": "success",
+  "output": "// ... generated code ...",
+  "error": "",
+  "attempts": 1
+}
+```
+
+---
+
+## Example: Escalated Failure
+
+**WorkerResult:**
+
+```json
+{
+  "task_id": "b6a921c9-aa4e-4d1a-9862-d3f0b0e3f101",
+  "agent": "database-architect",
+  "status": "escalate",
+  "output": "",
+  "error": "Cannot infer schema without knowing whether PostgreSQL or MySQL is the target. Context is ambiguous.",
+  "attempts": 3
+}
+```
+
+---
+
+## swarm_dispatcher.js Integration
+
+The `swarm_dispatcher.js` script validates **WorkerRequest** payloads before dispatch.
+
+**Usage:**
+
+```bash
+node .agent/scripts/swarm_dispatcher.js --mode swarm --file worker_request.json
+node .agent/scripts/swarm_dispatcher.js --mode swarm --payload '{"task_id":"...","type":"generate_code","agent":"backend-specialist","goal":"...","context":"...","max_retries":3}'
+```
+
+Exits `0` on valid payload. Exits `1` on any schema violation with a specific error message per field.

package/.agent/agents/swarm-worker-registry.md

@@ -1,99 +1,99 @@
-# 🗂️ Swarm Worker Registry
-
-Maps task types and domain keywords to the correct specialist Worker agents.
-Used by `supervisor-agent` to select the correct `agent` field in every `WorkerRequest`.
-All agents listed here MUST exist as `.md` files in `.agent/agents/`.
-
----
-
-## Primary Routing Table
-
-| Task Type        | Domain Keywords                                   | Route to Agent           |
-| ---------------- | ------------------------------------------------- | ------------------------ |
-| `research`       | any                                               | `explorer-agent`         |
-| `research`       | security, vulnerability, owasp                    | `security-auditor`       |
-| `research`       | database, schema, sql, orm                        | `database-architect`     |
-| `research`       | performance, profiling, optimization              | `performance-optimizer`  |
-| `generate_code`  | api, route, endpoint, server, express, auth, jwt  | `backend-specialist`     |
-| `generate_code`  | python, fastapi, django, flask                    | `python-pro`             |
-| `generate_code`  | c#, .net, blazor, aspnet                          | `csharp-developer`       |
-| `generate_code`  | component, hook, react, next, ui, css             | `frontend-specialist`    |
-| `generate_code`  | mobile, react native, flutter, ios, android       | `mobile-developer`       |
-| `generate_code`  | docker, ci, cd, deploy, github actions, cloud     | `devops-engineer`        |
-| `generate_code`  | sql, query, migration, prisma, drizzle            | `sql-pro`                |
-| `generate_code`  | vue, nuxt                                         | `vue-expert`             |
-| `review_code`    | api, backend, auth                                | `backend-specialist`     |
-| `review_code`    | react, component, hook                            | `frontend-specialist`    |
-| `review_code`    | sql, query                                        | `sql-pro`                |
-| `review_code`    | security (any domain)                             | `security-auditor`       |
-| `debug`          | any                                               | `debugger`               |
-| `plan`           | any                                               | `project-planner`        |
-| `design_schema`  | any                                               | `database-architect`     |
-| `write_docs`     | any                                               | `documentation-writer`   |
-| `security_audit` | any                                               | `security-auditor`       |
-| `optimize`       | any                                               | `performance-optimizer`  |
-| `test`           | any                                               | `test-engineer`          |
-| `visual_audit`   | ui, component, visual, screenshot, layout, render | `ui-visual-auditor`      |
-| `generate_code`  | aws, terraform, ecs, fargate, lambda, iac, vpc    | `cloud-engineer`         |
-| `plan`           | system design, scale, capacity, architecture      | `system-architect`       |
-| `test`           | e2e, playwright, automation, cypress              | `qa-automation-engineer` |
-
----
-
-## Tiebreaker Rules
-
-When multiple domain keywords match, apply the following priority order:
-
-1. **Most specific agent wins.** `sql-pro` beats `database-architect` for SQL query generation. `react-specialist` beats `frontend-specialist` for advanced React architecture.
-2. **Security always runs in parallel.** Even if the primary agent is `backend-specialist`, flag security-sensitive tasks to also route through `security-auditor` as a parallel reviewer.
-3. **When in doubt, use `explorer-agent` first.** If the codebase is unknown, map it before generating.
-
----
-
-## Agent Capability Summary
-
-Quick reference for Supervisor triage. Full instructions are in each agent's `.md` file.
-
-| Agent File                  | Best For                                         | Do NOT Use For          |
-| --------------------------- | ------------------------------------------------ | ----------------------- |
-| `backend-specialist.md`     | REST APIs, auth flows, server logic              | React components        |
-| `python-pro.md`             | FastAPI, Django, data scripts                    | Node/TypeScript code    |
-| `csharp-developer`          | .NET 8+, C#, Blazor, AOT                         | Python or Node backends |
-| `frontend-specialist.md`    | Web UI, CSS, components                          | Server code             |
-| `react-specialist.md`       | Advanced React patterns, Next.js architecture    | Vue or mobile           |
-| `vue-expert.md`             | Vue 3, Nuxt 3, Pinia                             | React or Angular        |
-| `mobile-developer.md`       | React Native, Flutter                            | Web browser UI          |
-| `database-architect.md`     | Schema design, ORM selection, migrations         | Raw SQL query tuning    |
-| `sql-pro.md`                | Complex queries, CTEs, window functions, indexes | Schema design           |
-| `devops-engineer.md`        | CI/CD, Docker, Kubernetes, cloud infra           | Application code        |
-| `security-auditor.md`       | OWASP review, pen test findings, auth hardening  | Feature development     |
-| `performance-optimizer.md`  | Profiling, bottleneck resolution, caching        | New feature design      |
-| `debugger.md`               | Root cause analysis, systematic issue isolation  | Code generation         |
-| `project-planner.md`        | Planning, task breakdown, estimates              | Implementation          |
-| `documentation-writer.md`   | READMEs, API docs, inline comments               | Code or schemas         |
-| `test-engineer.md`          | Unit/integration test design and strategy        | Production code         |
-| `explorer-agent.md`         | Mapping unknown codebases before acting          | Building new features   |
-| `cloud-engineer.md`         | AWS, Terraform, Docker, ECS, GitHub Actions CI   | Application code        |
-| `system-architect.md`       | System design, capacity planning, scalability    | Implementation details  |
-| `qa-automation-engineer.md` | E2E testing, Playwright, test automation         | Unit test design        |
-
----
-
-## Hard Constraints
-
-```
-❌ Never route to an agent not listed in this registry
-❌ Never route "generate_code" to "project-planner" or "documentation-writer"
-❌ Never route "plan" to any code-generating agent
-❌ Never route multi-domain tasks to a single agent — split into multiple WorkerRequests
-```
-
----
-
-## Adding New Workers
-
-When a new specialist agent is added to `.agent/agents/`, update this registry:
-
-1. Add a row to the **Primary Routing Table** for each `type` and keyword combination it handles
-2. Add a row to the **Agent Capability Summary** with "Best For" and "Do NOT Use For" guidance
-3. Run `node .agent/scripts/verify_all.js` to verify consistency
+# 🗂️ Swarm Worker Registry
+
+Maps task types and domain keywords to the correct specialist Worker agents.
+Used by `supervisor-agent` to select the correct `agent` field in every `WorkerRequest`.
+All agents listed here MUST exist as `.md` files in `.agent/agents/`.
+
+---
+
+## Primary Routing Table
+
+| Task Type        | Domain Keywords                                   | Route to Agent           |
+| ---------------- | ------------------------------------------------- | ------------------------ |
+| `research`       | any                                               | `explorer-agent`         |
+| `research`       | security, vulnerability, owasp                    | `security-auditor`       |
+| `research`       | database, schema, sql, orm                        | `database-architect`     |
+| `research`       | performance, profiling, optimization              | `performance-optimizer`  |
+| `generate_code`  | api, route, endpoint, server, express, auth, jwt  | `backend-specialist`     |
+| `generate_code`  | python, fastapi, django, flask                    | `python-pro`             |
+| `generate_code`  | c#, .net, blazor, aspnet                          | `csharp-developer`       |
+| `generate_code`  | component, hook, react, next, ui, css             | `frontend-specialist`    |
+| `generate_code`  | mobile, react native, flutter, ios, android       | `mobile-developer`       |
+| `generate_code`  | docker, ci, cd, deploy, github actions, cloud     | `devops-engineer`        |
+| `generate_code`  | sql, query, migration, prisma, drizzle            | `sql-pro`                |
+| `generate_code`  | vue, nuxt                                         | `vue-expert`             |
+| `review_code`    | api, backend, auth                                | `backend-specialist`     |
+| `review_code`    | react, component, hook                            | `frontend-specialist`    |
+| `review_code`    | sql, query                                        | `sql-pro`                |
+| `review_code`    | security (any domain)                             | `security-auditor`       |
+| `debug`          | any                                               | `debugger`               |
+| `plan`           | any                                               | `project-planner`        |
+| `design_schema`  | any                                               | `database-architect`     |
+| `write_docs`     | any                                               | `documentation-writer`   |
+| `security_audit` | any                                               | `security-auditor`       |
+| `optimize`       | any                                               | `performance-optimizer`  |
+| `test`           | any                                               | `test-engineer`          |
+| `visual_audit`   | ui, component, visual, screenshot, layout, render | `ui-visual-auditor`      |
+| `generate_code`  | aws, terraform, ecs, fargate, lambda, iac, vpc    | `cloud-engineer`         |
+| `plan`           | system design, scale, capacity, architecture      | `system-architect`       |
+| `test`           | e2e, playwright, automation, cypress              | `qa-automation-engineer` |
+
+---
+
+## Tiebreaker Rules
+
+When multiple domain keywords match, apply the following priority order:
+
+1. **Most specific agent wins.** `sql-pro` beats `database-architect` for SQL query generation. `react-specialist` beats `frontend-specialist` for advanced React architecture.
+2. **Security always runs in parallel.** Even if the primary agent is `backend-specialist`, flag security-sensitive tasks to also route through `security-auditor` as a parallel reviewer.
+3. **When in doubt, use `explorer-agent` first.** If the codebase is unknown, map it before generating.
+
+---
+
+## Agent Capability Summary
+
+Quick reference for Supervisor triage. Full instructions are in each agent's `.md` file.
+
+| Agent File                  | Best For                                         | Do NOT Use For          |
+| --------------------------- | ------------------------------------------------ | ----------------------- |
+| `backend-specialist.md`     | REST APIs, auth flows, server logic              | React components        |
+| `python-pro.md`             | FastAPI, Django, data scripts                    | Node/TypeScript code    |
+| `csharp-developer`          | .NET 8+, C#, Blazor, AOT                         | Python or Node backends |
+| `frontend-specialist.md`    | Web UI, CSS, components                          | Server code             |
+| `react-specialist.md`       | Advanced React patterns, Next.js architecture    | Vue or mobile           |
+| `vue-expert.md`             | Vue 3, Nuxt 3, Pinia                             | React or Angular        |
+| `mobile-developer.md`       | React Native, Flutter                            | Web browser UI          |
+| `database-architect.md`     | Schema design, ORM selection, migrations         | Raw SQL query tuning    |
+| `sql-pro.md`                | Complex queries, CTEs, window functions, indexes | Schema design           |
+| `devops-engineer.md`        | CI/CD, Docker, Kubernetes, cloud infra           | Application code        |
+| `security-auditor.md`       | OWASP review, pen test findings, auth hardening  | Feature development     |
+| `performance-optimizer.md`  | Profiling, bottleneck resolution, caching        | New feature design      |
+| `debugger.md`               | Root cause analysis, systematic issue isolation  | Code generation         |
+| `project-planner.md`        | Planning, task breakdown, estimates              | Implementation          |
+| `documentation-writer.md`   | READMEs, API docs, inline comments               | Code or schemas         |
+| `test-engineer.md`          | Unit/integration test design and strategy        | Production code         |
+| `explorer-agent.md`         | Mapping unknown codebases before acting          | Building new features   |
+| `cloud-engineer.md`         | AWS, Terraform, Docker, ECS, GitHub Actions CI   | Application code        |
+| `system-architect.md`       | System design, capacity planning, scalability    | Implementation details  |
+| `qa-automation-engineer.md` | E2E testing, Playwright, test automation         | Unit test design        |
+
+---
+
+## Hard Constraints
+
+```
+❌ Never route to an agent not listed in this registry
+❌ Never route "generate_code" to "project-planner" or "documentation-writer"
+❌ Never route "plan" to any code-generating agent
+❌ Never route multi-domain tasks to a single agent — split into multiple WorkerRequests
+```
+
+---
+
+## Adding New Workers
+
+When a new specialist agent is added to `.agent/agents/`, update this registry:
+
+1. Add a row to the **Primary Routing Table** for each `type` and keyword combination it handles
+2. Add a row to the **Agent Capability Summary** with "Best For" and "Do NOT Use For" guidance
+3. Run `node .agent/scripts/verify_all.js` to verify consistency