tribunal-kit 9.2.4 → 9.2.6

package/.agent/workflows/enhance.md

@@ -1,165 +1,165 @@
----
-description: Add or update features in existing applications. Performs impact analysis before any code change — identifies all dependents, detects breaking changes, generates Tribunal-reviewed modifications. No change is written to disk without Human Gate approval.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-07-30
-required-skills:
-  - clean-code
-  - codebase-design
-  - testing-patterns
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/test_runner.js
----
-
-# /enhance — Feature Addition & Modification
-
-$ARGUMENTS
-
----
-
-## Mandatory Pre-Flight Context Inspection
-
-Before modifying existing features or appending functionality, you MUST inspect:
-
-1. Impact Zone Identification → Grep for all callers and importers of the target file to map blast radius
-2. Existing Contract & Unit Tests → Inspect existing tests and type signatures for the target module to prevent regression
-3. Breaking Change Detection → Ensure signature changes update all dependent call sites simultaneously before writing to disk
-
-4. Required Skills → Before executing, load and follow procedural rules from:
-   - `clean-code` (.agent/skills/clean-code/SKILL.md): Self-documenting naming, no over-engineering, error handling patterns
-   - `codebase-design` (.agent/skills/codebase-design/SKILL.md): Deep module design with small interfaces and clean seams
-   - `testing-patterns` (.agent/skills/testing-patterns/SKILL.md): Testing Trophy strategy (unit → integration → E2E)
-
----
-
-## When to Use /enhance
-
-| Use `/enhance` when...                   | Use something else when...                     |
-| :--------------------------------------- | :--------------------------------------------- |
-| Adding a feature to an existing codebase | Starting from scratch → `/create`              |
-| Changing existing behavior               | Fixing a bug → `/debug`                        |
-| Iterating on a recently created feature  | Full architecture review → `/plan`             |
-| Extending an existing API or component   | Performance problems → `/tribunal-performance` |
-
----
-
-## Phase 1 — Impact Analysis (MANDATORY Before Any Change)
-
-Before writing any code, map what will be affected:
-
-```bash
-# What does the target file import?
-head -30 [target-file]  # Read all imports at the top
-
-# Who imports the target file? (callers)
-grep -r "from '.*target-module'" src/ --include="*.ts" --include="*.tsx"
-
-# Who references the specific function/type being changed?
-grep -r "targetFunction\|TargetType" src/ --include="*.ts" --include="*.tsx"
-```
-
-**Risk Classification:**
-
-| File import count | Risk Level | Required Action                      |
-| :---------------- | :--------- | :----------------------------------- |
-| 0–2 importers     | Low        | Normal Tribunal review               |
-| 3–5 importers     | Medium     | List all affected files in plan      |
-| 6+ importers      | High       | Full dependency map + staged rollout |
-
----
-
-## Phase 2 — Breaking Change Detection
-
-```
-Changes that BREAK existing callers:
-□ Removing or renaming exported function/type/component
-□ Adding required (non-optional) parameter to existing function
-□ Changing a parameter type to incompatible type
-□ Changing return type to incompatible type
-□ Database schema changes (remove column, rename column, change type)
-□ API contract changes (removing fields from response)
-
-Changes that DON'T break callers:
-□ Adding optional parameter with default value
-□ Adding new exported function (existing callers unaffected)
-□ Adding nullable column to DB schema
-□ Widening return type (e.g., T → T | null)
-□ Internal implementation changes with same interface
-```
-
-If any breaking changes are detected → document them in the plan before proceeding.
-
----
-
-## Phase 3 — Enhancement Plan
-
-```markdown
-## Enhancement: [Feature Name]
-
-Scope: [what is changing]
-Impact zone: [N files affected]
-Breaking changes: [Yes: list | None detected]
-
-Changes:
-
-1. [file-a.ts] — [what changes and why]
-2. [file-b.ts] — [downstream update required because...]
-3. [file-c.test.ts] — [test updates required]
-```
-
-**Human Gate:** Plan presented before any editing begins.
-
----
-
-## Phase 4 — Tribunal-Reviewed Implementation
-
-Each file change goes through the Tribunal pipeline:
-
-```
-logic-reviewer:      runs on every change
-security-auditor:    runs on every change
-[domain-specific]:   activated based on change type
-```
-
-**NEVER modify files outside the defined impact zone without approval.**
-
----
-
-## Phase 5 — Consistency Verification
-
-After all changes:
-
-```
-□ npx tsc --noEmit — zero new TypeScript errors
-□ npm test — all existing tests still pass
-□ New tests written for the new behavior
-□ API response contracts verified not to have changed unexpectedly
-□ Database migration (if schema changed) runs cleanly
-```
-
----
-
-## Enhancement Guard
-
-```
-❌ Never modify files outside the documented impact zone without re-running Impact Analysis
-❌ Never add a required parameter without updating all callers
-❌ Never rename an exported symbol without grepping all callers first
-❌ Never change a DB column without an expand-and-contract migration plan
-❌ Never update package versions silently — show in plan
-❌ Never "fix other things while we're here" — scope creep
-```
-
----
-
-## After /enhance — Next Steps
-
-| Outcome                            | Next Command                                |
-| :--------------------------------- | :------------------------------------------ |
-| Enhancement applied, needs tests   | → `/test` for new behavior coverage         |
-| Enhancement applied, needs review  | → `/review` or `/tribunal-*` for validation |
-| Enhancement revealed deeper issues | → `/refactor` for structural improvement    |
-| Ready for deployment               | → `/deploy` with pre-flight checks          |
-
----
+---
+description: Add or update features in existing applications. Performs impact analysis before any code change — identifies all dependents, detects breaking changes, generates Tribunal-reviewed modifications. No change is written to disk without Human Gate approval.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 3.0.0
+last-updated: 2026-07-30
+required-skills:
+  - clean-code
+  - codebase-design
+  - testing-patterns
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/test_runner.js
+---
+
+# /enhance — Feature Addition & Modification
+
+$ARGUMENTS
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Before modifying existing features or appending functionality, you MUST inspect:
+
+1. Impact Zone Identification → Grep for all callers and importers of the target file to map blast radius
+2. Existing Contract & Unit Tests → Inspect existing tests and type signatures for the target module to prevent regression
+3. Breaking Change Detection → Ensure signature changes update all dependent call sites simultaneously before writing to disk
+
+4. Required Skills → Before executing, load and follow procedural rules from:
+   - `clean-code` (.agent/skills/clean-code/SKILL.md): Self-documenting naming, no over-engineering, error handling patterns
+   - `codebase-design` (.agent/skills/codebase-design/SKILL.md): Deep module design with small interfaces and clean seams
+   - `testing-patterns` (.agent/skills/testing-patterns/SKILL.md): Testing Trophy strategy (unit → integration → E2E)
+
+---
+
+## When to Use /enhance
+
+| Use `/enhance` when...                   | Use something else when...                     |
+| :--------------------------------------- | :--------------------------------------------- |
+| Adding a feature to an existing codebase | Starting from scratch → `/create`              |
+| Changing existing behavior               | Fixing a bug → `/debug`                        |
+| Iterating on a recently created feature  | Full architecture review → `/plan`             |
+| Extending an existing API or component   | Performance problems → `/tribunal-performance` |
+
+---
+
+## Phase 1 — Impact Analysis (MANDATORY Before Any Change)
+
+Before writing any code, map what will be affected:
+
+```bash
+# What does the target file import?
+head -30 [target-file]  # Read all imports at the top
+
+# Who imports the target file? (callers)
+grep -r "from '.*target-module'" src/ --include="*.ts" --include="*.tsx"
+
+# Who references the specific function/type being changed?
+grep -r "targetFunction\|TargetType" src/ --include="*.ts" --include="*.tsx"
+```
+
+**Risk Classification:**
+
+| File import count | Risk Level | Required Action                      |
+| :---------------- | :--------- | :----------------------------------- |
+| 0–2 importers     | Low        | Normal Tribunal review               |
+| 3–5 importers     | Medium     | List all affected files in plan      |
+| 6+ importers      | High       | Full dependency map + staged rollout |
+
+---
+
+## Phase 2 — Breaking Change Detection
+
+```
+Changes that BREAK existing callers:
+□ Removing or renaming exported function/type/component
+□ Adding required (non-optional) parameter to existing function
+□ Changing a parameter type to incompatible type
+□ Changing return type to incompatible type
+□ Database schema changes (remove column, rename column, change type)
+□ API contract changes (removing fields from response)
+
+Changes that DON'T break callers:
+□ Adding optional parameter with default value
+□ Adding new exported function (existing callers unaffected)
+□ Adding nullable column to DB schema
+□ Widening return type (e.g., T → T | null)
+□ Internal implementation changes with same interface
+```
+
+If any breaking changes are detected → document them in the plan before proceeding.
+
+---
+
+## Phase 3 — Enhancement Plan
+
+```markdown
+## Enhancement: [Feature Name]
+
+Scope: [what is changing]
+Impact zone: [N files affected]
+Breaking changes: [Yes: list | None detected]
+
+Changes:
+
+1. [file-a.ts] — [what changes and why]
+2. [file-b.ts] — [downstream update required because...]
+3. [file-c.test.ts] — [test updates required]
+```
+
+**Human Gate:** Plan presented before any editing begins.
+
+---
+
+## Phase 4 — Tribunal-Reviewed Implementation
+
+Each file change goes through the Tribunal pipeline:
+
+```
+logic-reviewer:      runs on every change
+security-auditor:    runs on every change
+[domain-specific]:   activated based on change type
+```
+
+**NEVER modify files outside the defined impact zone without approval.**
+
+---
+
+## Phase 5 — Consistency Verification
+
+After all changes:
+
+```
+□ npx tsc --noEmit — zero new TypeScript errors
+□ npm test — all existing tests still pass
+□ New tests written for the new behavior
+□ API response contracts verified not to have changed unexpectedly
+□ Database migration (if schema changed) runs cleanly
+```
+
+---
+
+## Enhancement Guard
+
+```
+❌ Never modify files outside the documented impact zone without re-running Impact Analysis
+❌ Never add a required parameter without updating all callers
+❌ Never rename an exported symbol without grepping all callers first
+❌ Never change a DB column without an expand-and-contract migration plan
+❌ Never update package versions silently — show in plan
+❌ Never "fix other things while we're here" — scope creep
+```
+
+---
+
+## After /enhance — Next Steps
+
+| Outcome                            | Next Command                                |
+| :--------------------------------- | :------------------------------------------ |
+| Enhancement applied, needs tests   | → `/test` for new behavior coverage         |
+| Enhancement applied, needs review  | → `/review` or `/tribunal-*` for validation |
+| Enhancement revealed deeper issues | → `/refactor` for structural improvement    |
+| Ready for deployment               | → `/deploy` with pre-flight checks          |
+
+---

package/.agent/workflows/fix-ci.md

@@ -1,94 +1,94 @@
----
-description: Automated CI/CD Failure Diagnosis & Repair. Parses raw GitHub Actions/GitLab CI runner logs, identifies the root cause (lockfile drift, missing environment variables, matrix incompatibilities, test timeouts, or syntax errors), and produces validated fixes.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-08-14
-required-skills:
-  - cicd-pro
-  - diagnosing-bugs
-  - devops-engineer
-scripts-binding:
-  - .agent/scripts/cicd_validator.js
-  - .agent/scripts/test_runner.js
-  - .agent/scripts/lint_runner.js
----
-
-# /fix-ci — Automated Pipeline Failure Resolution
-
-$ARGUMENTS
-
----
-
-## Mandatory Pre-Flight Context Inspection
-
-Before attempting to fix CI pipeline failures:
-
-1. Parse Failing Runner Log → Identify exact step, exit code, and stack trace or runner error message
-2. Inspect Workflow YAML & Project Configs → Compare runner environment (Node/Python/OS version) with local workspace
-3. Human Gate Before Disk Write → Present root cause explanation and proposed diff for approval
-
-4. Required Skills → Before executing, load and follow procedural rules from:
-   - `cicd-pro` (.agent/skills/cicd-pro/SKILL.md): CI/CD workflow syntax, matrix builds, and deployment strategies
-   - `diagnosing-bugs` (.agent/skills/diagnosing-bugs/SKILL.md): Bug diagnosis patterns and root cause investigation
-   - `devops-engineer` (.agent/skills/devops-engineer/SKILL.md): CI/CD pipeline management and infrastructure automation
-
----
-
-## 4-Step CI Diagnosis & Repair Loop
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. LOG INGESTION                                            │
-│    User pastes failed CI log or step output                 │
-│    Extract: Step Name, Error Code, Root Stack Trace        │
-│                                                             │
-│ 2. CLASSIFICATION                                           │
-│    □ Lockfile / Dependency Drift (npm ci vs package.json)   │
-│    □ Environment / Missing Secret / Missing Env Var        │
-│    □ Version / Runner Matrix Incompatibility               │
-│    □ Test / Lint / Typecheck Failure in CI Context         │
-│    □ Service Container (DB/Redis) Connection Timeout       │
-│                                                             │
-│ 3. REPRODUCTION & ROOT CAUSE ISOLATION                      │
-│    Simulate failing step locally using test/lint runners   │
-│                                                             │
-│ 4. REMEDIATION & VALIDATION                                 │
-│    Apply fix to code or workflow YAML                       │
-│    Run .agent/scripts/cicd_validator.js                     │
-│    Submit through /tribunal-cicd Human Gate                │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Common CI Failure Root Causes & Fix Recipes
-
-### 1. `npm ci` ERESOLVE / Lockfile Drift
-
-- **Symptom:** `npm error code EUSAGE / ERESOLVE` or `npm ci can only install when package.json and package-lock.json are in sync`.
-- **Fix:** Run `npm install` locally to update lockfile and commit the synced `package-lock.json`.
-
-### 2. Missing Environment Variables / Secrets
-
-- **Symptom:** `process.env.DATABASE_URL is undefined` during build or test steps in CI.
-- **Fix:** Add dummy or mock environment variables to the workflow step `env:` block (e.g. `DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/test"`).
-
-### 3. Missing Service Container Healthchecks
-
-- **Symptom:** Test step cannot connect to Postgres/Redis service in GitHub Actions runner.
-- **Fix:** Add `options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5` to the service container definition.
-
-### 4. Runner OS / Architecture Differences
-
-- **Symptom:** Native binary module (e.g. `sharp`, `bcrypt`, `@swc/core`) fails to load on `ubuntu-latest`.
-- **Fix:** Ensure correct optional dependencies or add OS matrix build steps.
-
----
-
-## Usage Examples
-
-```
-/fix-ci [paste failed GitHub Actions log]
-/fix-ci the test job failed on ubuntu-latest Node 22 with exit code 1
-/fix-ci error: package-lock.json out of sync during npm ci
-```
+---
+description: Automated CI/CD Failure Diagnosis & Repair. Parses raw GitHub Actions/GitLab CI runner logs, identifies the root cause (lockfile drift, missing environment variables, matrix incompatibilities, test timeouts, or syntax errors), and produces validated fixes.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 3.0.0
+last-updated: 2026-08-14
+required-skills:
+  - cicd-pro
+  - diagnosing-bugs
+  - devops-engineer
+scripts-binding:
+  - .agent/scripts/cicd_validator.js
+  - .agent/scripts/test_runner.js
+  - .agent/scripts/lint_runner.js
+---
+
+# /fix-ci — Automated Pipeline Failure Resolution
+
+$ARGUMENTS
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Before attempting to fix CI pipeline failures:
+
+1. Parse Failing Runner Log → Identify exact step, exit code, and stack trace or runner error message
+2. Inspect Workflow YAML & Project Configs → Compare runner environment (Node/Python/OS version) with local workspace
+3. Human Gate Before Disk Write → Present root cause explanation and proposed diff for approval
+
+4. Required Skills → Before executing, load and follow procedural rules from:
+   - `cicd-pro` (.agent/skills/cicd-pro/SKILL.md): CI/CD workflow syntax, matrix builds, and deployment strategies
+   - `diagnosing-bugs` (.agent/skills/diagnosing-bugs/SKILL.md): Bug diagnosis patterns and root cause investigation
+   - `devops-engineer` (.agent/skills/devops-engineer/SKILL.md): CI/CD pipeline management and infrastructure automation
+
+---
+
+## 4-Step CI Diagnosis & Repair Loop
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. LOG INGESTION                                            │
+│    User pastes failed CI log or step output                 │
+│    Extract: Step Name, Error Code, Root Stack Trace        │
+│                                                             │
+│ 2. CLASSIFICATION                                           │
+│    □ Lockfile / Dependency Drift (npm ci vs package.json)   │
+│    □ Environment / Missing Secret / Missing Env Var        │
+│    □ Version / Runner Matrix Incompatibility               │
+│    □ Test / Lint / Typecheck Failure in CI Context         │
+│    □ Service Container (DB/Redis) Connection Timeout       │
+│                                                             │
+│ 3. REPRODUCTION & ROOT CAUSE ISOLATION                      │
+│    Simulate failing step locally using test/lint runners   │
+│                                                             │
+│ 4. REMEDIATION & VALIDATION                                 │
+│    Apply fix to code or workflow YAML                       │
+│    Run .agent/scripts/cicd_validator.js                     │
+│    Submit through /tribunal-cicd Human Gate                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Common CI Failure Root Causes & Fix Recipes
+
+### 1. `npm ci` ERESOLVE / Lockfile Drift
+
+- **Symptom:** `npm error code EUSAGE / ERESOLVE` or `npm ci can only install when package.json and package-lock.json are in sync`.
+- **Fix:** Run `npm install` locally to update lockfile and commit the synced `package-lock.json`.
+
+### 2. Missing Environment Variables / Secrets
+
+- **Symptom:** `process.env.DATABASE_URL is undefined` during build or test steps in CI.
+- **Fix:** Add dummy or mock environment variables to the workflow step `env:` block (e.g. `DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/test"`).
+
+### 3. Missing Service Container Healthchecks
+
+- **Symptom:** Test step cannot connect to Postgres/Redis service in GitHub Actions runner.
+- **Fix:** Add `options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5` to the service container definition.
+
+### 4. Runner OS / Architecture Differences
+
+- **Symptom:** Native binary module (e.g. `sharp`, `bcrypt`, `@swc/core`) fails to load on `ubuntu-latest`.
+- **Fix:** Ensure correct optional dependencies or add OS matrix build steps.
+
+---
+
+## Usage Examples
+
+```
+/fix-ci [paste failed GitHub Actions log]
+/fix-ci the test job failed on ubuntu-latest Node 22 with exit code 1
+/fix-ci error: package-lock.json out of sync during npm ci
+```