tribunal-kit 9.2.4 → 9.2.6

package/.agent/workflows/migrate.md

@@ -1,198 +1,198 @@
----
-description: Migration workflow for framework upgrades, dependency bumps, and database migrations. Impact analysis first, expand-and-contract for DB, dependency compatibility matrix before upgrading, rollback tested before deploy.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-07-30
-required-skills:
-  - plan-writing
-  - architecture
-  - database-design
-scripts-binding:
-  - .agent/scripts/dependency_analyzer.js
-  - .agent/scripts/schema_validator.js
-  - .agent/scripts/verify_all.js
----
-
-# /migrate — Safe Migration Execution
-
-$ARGUMENTS
-
----
-
-## Mandatory Pre-Flight Context Inspection
-
-Before running framework upgrades, major dependency bumps, or database migrations, you MUST inspect:
-
-1. Dependency Compatibility Matrix (`dependency_analyzer.js`) → Verify target version peer dependencies and breaking changes
-2. Database Expand-and-Contract Plan (`schema_validator.js`) → Ensure database column changes add new fields before dropping old ones
-3. Rollback Protocol Verification → Test local rollback procedure (e.g. SQLite backup or DB transaction revert) before applying migration
-
-4. Required Skills → Before executing, load and follow procedural rules from:
-   - `plan-writing` (.agent/skills/plan-writing/SKILL.md): Implementation plan structure, phases, and approval gates
-   - `architecture` (.agent/skills/architecture/SKILL.md): System architecture, module boundaries, and dependency management
-   - `database-design` (.agent/skills/database-design/SKILL.md): Schema normalization, indexing, migration strategy
-
----
-
-## When to Use /migrate
-
-| Use `/migrate` when...                      | Use something else when...                  |
-| :------------------------------------------ | :------------------------------------------ |
-| Upgrading Next.js major version             | Adding a feature → `/enhance`               |
-| Upgrading React version                     | Schema change in existing rows → `/migrate` |
-| Database schema structural change           | Simple column add → `/enhance`              |
-| Changing auth libraries (next-auth v4 → v5) | Dependency patches → `/fix`                 |
-| Removing deprecated APIs at scale           |                                             |
-
----
-
-## Migration Types
-
-```
-Type A: Framework upgrade (Next.js 14 → 15, React 18 → 19)
-  → Audit breaking changes, update callsites, run Tribunal
-
-Type B: Dependency major version (Prisma 5 → 6, next-auth 4 → 5)
-  → Check changelog for removed APIs, update all callsites
-
-Type C: Database schema migration (expand-and-contract)
-  → Always in 3 phases, never destructive in one step
-
-Type D: Auth system migration
-  → Dual-write old + new, staged rollout, never big bang
-```
-
----
-
-## Phase 1 — Impact Analysis
-
-Before any migration:
-
-```bash
-# What uses the old API?
-grep -r "getServerSideProps\|getStaticProps" src/ --include="*.ts"  # Next.js pages/ to app/
-grep -r "getServerSession\|NextAuth" src/ --include="*.ts"          # next-auth v4 to v5
-grep -r "from 'next-auth'" src/ --include="*.ts"                    # Count callsites
-grep -r "prisma\.user\.findOne" src/ --include="*.ts"               # Removed Prisma APIs
-
-# How many files will change?
-# Low risk: < 5 files
-# Medium risk: 5-20 files → plan each file explicitly
-# High risk: > 20 files → automate with codemods, not manual
-```
-
----
-
-## Phase 2 — Breaking Change Inventory
-
-```
-Framework Migration Breaking Changes (Next.js 14 → 15 example):
-□ params and searchParams are now Promises — must await
-□ cookies(), headers(), draftMode() are async — must await
-□ fetch() caching defaults changed (now no-store by default)
-□ Turbopack becomes default dev server (may affect custom configs)
-
-Auth Library Breaking Changes (next-auth v4 → v5):
-□ import { getServerSession } from 'next-auth' → import { auth } from './auth'
-□ Configuration file: pages/api/auth/[...nextauth].ts → auth.ts
-□ SessionProvider import path changed
-□ Callbacks API may have changed
-```
-
----
-
-## Phase 3 — Database Migrate (Expand-and-Contract Pattern)
-
-**NEVER do destructive schema changes in a single step on live data.**
-
-```
-Step 1: EXPAND (add, never remove)
-  - Add new column (nullable)
-  - Add new table
-  - Add new foreign key
-
-Step 2: DUAL-WRITE (write to both old and new)
-  - Application writes to BOTH old_column and new_column
-  - Deploy this code before backfilling
-
-Step 3: BACKFILL (populate new structure)
-  - Fill new_column from old_column in background batches
-  - Verify: SELECT COUNT(*) WHERE new_column IS NULL should = 0
-
-Step 4: READ MIGRATION (switch reads to new)
-  - Application reads from new_column only
-  - Application still writes to both
-
-Step 5: CONTRACT (remove old)
-  - Remove writes to old_column
-  - After 1 deployment cycle → drop old_column
-```
-
----
-
-## Phase 4 — Migration Execution Order
-
-```
-□ Create git branch: git checkout -b migrate/[description]
-□ Run tests BEFORE migration: npm test (establish baseline)
-□ Apply changes in topological order (foundation files first)
-□ Run: npx tsc --noEmit (no type errors introduced)
-□ Run: npm test (all tests still pass)
-□ Run Tribunal on changed files: /tribunal-full
-□ PR review with explicit diff
-□ Deploy to staging before production
-□ Run tests in staging
-□ Human Gate: approve production deployment
-```
-
----
-
-## Phase 5 — Rollback Plan
-
-Before migrating production, document the rollback:
-
-```
-Rollback for code migration:
-  git revert [migration-commit]
-  git push origin main --force-with-lease
-
-Rollback for DB migration:
-  Maintain down.sql for every migration
-  Test rollback script on staging before production migration
-```
-
----
-
-## Migration Guard
-
-```
-❌ Never rename a DB column in a single migration (breaks live app)
-❌ Never DROP a column in the same migration that adds the replacement
-❌ Never migrate production database and application code simultaneously
-❌ Never run a migration without first testing on a restored production backup
-❌ Never skip the backward-compatibility window (keep old code during transition)
-```
-
----
-
-## Usage Examples
-
-```
-/migrate upgrade Next.js 14 to Next.js 15 App Router
-/migrate upgrade from next-auth v4 to v5 auth.js
-/migrate add a phoneNumber field to the users table
-/migrate remove the deprecated legacy_api_key column from users
-/migrate upgrade Prisma 5 to Prisma 6 and update all breaking API calls
-```
-
----
-
-## After /migrate — Next Steps
-
-| Outcome                    | Next Command                                |
-| :------------------------- | :------------------------------------------ |
-| Migration succeeds locally | → `/test` to verify all behaviors intact    |
-| Tests pass after migration | → `/tribunal-full` for safety audit         |
-| Audit passes               | → `/deploy` with explicit rollback baseline |
-
----
+---
+description: Migration workflow for framework upgrades, dependency bumps, and database migrations. Impact analysis first, expand-and-contract for DB, dependency compatibility matrix before upgrading, rollback tested before deploy.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 3.0.0
+last-updated: 2026-07-30
+required-skills:
+  - plan-writing
+  - architecture
+  - database-design
+scripts-binding:
+  - .agent/scripts/dependency_analyzer.js
+  - .agent/scripts/schema_validator.js
+  - .agent/scripts/verify_all.js
+---
+
+# /migrate — Safe Migration Execution
+
+$ARGUMENTS
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Before running framework upgrades, major dependency bumps, or database migrations, you MUST inspect:
+
+1. Dependency Compatibility Matrix (`dependency_analyzer.js`) → Verify target version peer dependencies and breaking changes
+2. Database Expand-and-Contract Plan (`schema_validator.js`) → Ensure database column changes add new fields before dropping old ones
+3. Rollback Protocol Verification → Test local rollback procedure (e.g. SQLite backup or DB transaction revert) before applying migration
+
+4. Required Skills → Before executing, load and follow procedural rules from:
+   - `plan-writing` (.agent/skills/plan-writing/SKILL.md): Implementation plan structure, phases, and approval gates
+   - `architecture` (.agent/skills/architecture/SKILL.md): System architecture, module boundaries, and dependency management
+   - `database-design` (.agent/skills/database-design/SKILL.md): Schema normalization, indexing, migration strategy
+
+---
+
+## When to Use /migrate
+
+| Use `/migrate` when...                      | Use something else when...                  |
+| :------------------------------------------ | :------------------------------------------ |
+| Upgrading Next.js major version             | Adding a feature → `/enhance`               |
+| Upgrading React version                     | Schema change in existing rows → `/migrate` |
+| Database schema structural change           | Simple column add → `/enhance`              |
+| Changing auth libraries (next-auth v4 → v5) | Dependency patches → `/fix`                 |
+| Removing deprecated APIs at scale           |                                             |
+
+---
+
+## Migration Types
+
+```
+Type A: Framework upgrade (Next.js 14 → 15, React 18 → 19)
+  → Audit breaking changes, update callsites, run Tribunal
+
+Type B: Dependency major version (Prisma 5 → 6, next-auth 4 → 5)
+  → Check changelog for removed APIs, update all callsites
+
+Type C: Database schema migration (expand-and-contract)
+  → Always in 3 phases, never destructive in one step
+
+Type D: Auth system migration
+  → Dual-write old + new, staged rollout, never big bang
+```
+
+---
+
+## Phase 1 — Impact Analysis
+
+Before any migration:
+
+```bash
+# What uses the old API?
+grep -r "getServerSideProps\|getStaticProps" src/ --include="*.ts"  # Next.js pages/ to app/
+grep -r "getServerSession\|NextAuth" src/ --include="*.ts"          # next-auth v4 to v5
+grep -r "from 'next-auth'" src/ --include="*.ts"                    # Count callsites
+grep -r "prisma\.user\.findOne" src/ --include="*.ts"               # Removed Prisma APIs
+
+# How many files will change?
+# Low risk: < 5 files
+# Medium risk: 5-20 files → plan each file explicitly
+# High risk: > 20 files → automate with codemods, not manual
+```
+
+---
+
+## Phase 2 — Breaking Change Inventory
+
+```
+Framework Migration Breaking Changes (Next.js 14 → 15 example):
+□ params and searchParams are now Promises — must await
+□ cookies(), headers(), draftMode() are async — must await
+□ fetch() caching defaults changed (now no-store by default)
+□ Turbopack becomes default dev server (may affect custom configs)
+
+Auth Library Breaking Changes (next-auth v4 → v5):
+□ import { getServerSession } from 'next-auth' → import { auth } from './auth'
+□ Configuration file: pages/api/auth/[...nextauth].ts → auth.ts
+□ SessionProvider import path changed
+□ Callbacks API may have changed
+```
+
+---
+
+## Phase 3 — Database Migrate (Expand-and-Contract Pattern)
+
+**NEVER do destructive schema changes in a single step on live data.**
+
+```
+Step 1: EXPAND (add, never remove)
+  - Add new column (nullable)
+  - Add new table
+  - Add new foreign key
+
+Step 2: DUAL-WRITE (write to both old and new)
+  - Application writes to BOTH old_column and new_column
+  - Deploy this code before backfilling
+
+Step 3: BACKFILL (populate new structure)
+  - Fill new_column from old_column in background batches
+  - Verify: SELECT COUNT(*) WHERE new_column IS NULL should = 0
+
+Step 4: READ MIGRATION (switch reads to new)
+  - Application reads from new_column only
+  - Application still writes to both
+
+Step 5: CONTRACT (remove old)
+  - Remove writes to old_column
+  - After 1 deployment cycle → drop old_column
+```
+
+---
+
+## Phase 4 — Migration Execution Order
+
+```
+□ Create git branch: git checkout -b migrate/[description]
+□ Run tests BEFORE migration: npm test (establish baseline)
+□ Apply changes in topological order (foundation files first)
+□ Run: npx tsc --noEmit (no type errors introduced)
+□ Run: npm test (all tests still pass)
+□ Run Tribunal on changed files: /tribunal-full
+□ PR review with explicit diff
+□ Deploy to staging before production
+□ Run tests in staging
+□ Human Gate: approve production deployment
+```
+
+---
+
+## Phase 5 — Rollback Plan
+
+Before migrating production, document the rollback:
+
+```
+Rollback for code migration:
+  git revert [migration-commit]
+  git push origin main --force-with-lease
+
+Rollback for DB migration:
+  Maintain down.sql for every migration
+  Test rollback script on staging before production migration
+```
+
+---
+
+## Migration Guard
+
+```
+❌ Never rename a DB column in a single migration (breaks live app)
+❌ Never DROP a column in the same migration that adds the replacement
+❌ Never migrate production database and application code simultaneously
+❌ Never run a migration without first testing on a restored production backup
+❌ Never skip the backward-compatibility window (keep old code during transition)
+```
+
+---
+
+## Usage Examples
+
+```
+/migrate upgrade Next.js 14 to Next.js 15 App Router
+/migrate upgrade from next-auth v4 to v5 auth.js
+/migrate add a phoneNumber field to the users table
+/migrate remove the deprecated legacy_api_key column from users
+/migrate upgrade Prisma 5 to Prisma 6 and update all breaking API calls
+```
+
+---
+
+## After /migrate — Next Steps
+
+| Outcome                    | Next Command                                |
+| :------------------------- | :------------------------------------------ |
+| Migration succeeds locally | → `/test` to verify all behaviors intact    |
+| Tests pass after migration | → `/tribunal-full` for safety audit         |
+| Audit passes               | → `/deploy` with explicit rollback baseline |
+
+---

package/.agent/workflows/minimal.md

@@ -1,101 +1,101 @@
----
-description: Analyze requested implementation for minimal viable change. Enforces the 7-level Decision Order (NO_CHANGE to CREATE), Change Budget estimation, Minimality Score (0-100), Complexity Flags detection, and repository search.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 6.0.0
-last-updated: 2026-07-30
-required-skills:
-  - clean-code
-  - codebase-design
-scripts-binding:
-  - .agent/scripts/minimal_change_engine.js
-  - .agent/scripts/case_law_manager.js
----
-
-# /minimal — Minimal Change Governance Workflow
-
-$ARGUMENTS
-
----
-
-## Mandatory Pre-Flight Context Inspection
-
-Before proposing any code change, you MUST evaluate the **10 Core Governance Questions**:
-
-1. Does anything need to change? (`NO_CHANGE`)
-2. Does the repository already solve this? (`REUSE`)
-3. Does an existing function, component, utility, service, or abstraction solve it? (`REUSE`)
-4. Does the language standard library solve it? (`REUSE`)
-5. Does the framework or platform solve it? (`REUSE`)
-6. Does an existing dependency solve it? (`REUSE`)
-7. Is configuration enough? (`CONFIGURE`)
-8. Is deletion or simplification better than addition? (`DELETE`)
-9. Is the proposed abstraction necessary for the current requirement? (`MODIFY`/`EXTEND`)
-10. What is the smallest implementation that satisfies the request? (`MODIFY`/`EXTEND` vs `CREATE`)
-
-11. 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
-
----
-
-## Sub-Commands
-
-| Command             | Description                                                                           |
-| :------------------ | :------------------------------------------------------------------------------------ |
-| `/minimal`          | Analyze requested implementation and determine smallest viable change footprint       |
-| `/minimal-review`   | Review proposed change diff for unnecessary complexity and file proliferation         |
-| `/change-budget`    | Display estimated Change Budget (files added/modified, lines, deps, abstractions)     |
-| `/complexity-audit` | Audit proposal for 14 standardized complexity flags and overengineering patterns      |
-| `/reuse-check`      | Search repository for existing functions, symbols, and utilities before creating code |
-
----
-
-## Decision Order Hierarchy
-
-Evaluate solutions strictly in this order:
-
-```
-NO_CHANGE ➔ REUSE ➔ CONFIGURE ➔ DELETE ➔ MODIFY ➔ EXTEND ➔ CREATE
-```
-
----
-
-## Output Schema
-
-```
-━━━ Minimal Change Governance Audit ━━━━━━━━━━━━━━━━━━━━━━
-
-Minimality Score:          88/100 (PASSED)
-Decision Classification:   MODIFY
-Strictness Mode:           balanced
-
-━━━ Change Budget ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-files_added:               0
-files_modified:            2
-dependencies_added:        0
-new_abstractions:          0
-estimated_lines_added:     14
-estimated_lines_removed:    4
-
-━━━ Complexity Flags ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ None detected
-
-━━━ Reuse Opportunities ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-- Extend src/utils/http.ts for retry policy rather than creating a new service file
-
-━━━ Recommendation ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Proceed with MODIFY strategy on src/utils/http.ts
-```
-
----
-
-## Usage Examples
-
-```
-/minimal add request retry handling to API calls
-/minimal-review src/services/retryQueue.ts
-/change-budget
-/complexity-audit
-/reuse-check fetchRetry
-```
+---
+description: Analyze requested implementation for minimal viable change. Enforces the 7-level Decision Order (NO_CHANGE to CREATE), Change Budget estimation, Minimality Score (0-100), Complexity Flags detection, and repository search.
+tools: Read, Grep, Glob, Bash, Edit, Write
+version: 6.0.0
+last-updated: 2026-07-30
+required-skills:
+  - clean-code
+  - codebase-design
+scripts-binding:
+  - .agent/scripts/minimal_change_engine.js
+  - .agent/scripts/case_law_manager.js
+---
+
+# /minimal — Minimal Change Governance Workflow
+
+$ARGUMENTS
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Before proposing any code change, you MUST evaluate the **10 Core Governance Questions**:
+
+1. Does anything need to change? (`NO_CHANGE`)
+2. Does the repository already solve this? (`REUSE`)
+3. Does an existing function, component, utility, service, or abstraction solve it? (`REUSE`)
+4. Does the language standard library solve it? (`REUSE`)
+5. Does the framework or platform solve it? (`REUSE`)
+6. Does an existing dependency solve it? (`REUSE`)
+7. Is configuration enough? (`CONFIGURE`)
+8. Is deletion or simplification better than addition? (`DELETE`)
+9. Is the proposed abstraction necessary for the current requirement? (`MODIFY`/`EXTEND`)
+10. What is the smallest implementation that satisfies the request? (`MODIFY`/`EXTEND` vs `CREATE`)
+
+11. 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
+
+---
+
+## Sub-Commands
+
+| Command             | Description                                                                           |
+| :------------------ | :------------------------------------------------------------------------------------ |
+| `/minimal`          | Analyze requested implementation and determine smallest viable change footprint       |
+| `/minimal-review`   | Review proposed change diff for unnecessary complexity and file proliferation         |
+| `/change-budget`    | Display estimated Change Budget (files added/modified, lines, deps, abstractions)     |
+| `/complexity-audit` | Audit proposal for 14 standardized complexity flags and overengineering patterns      |
+| `/reuse-check`      | Search repository for existing functions, symbols, and utilities before creating code |
+
+---
+
+## Decision Order Hierarchy
+
+Evaluate solutions strictly in this order:
+
+```
+NO_CHANGE ➔ REUSE ➔ CONFIGURE ➔ DELETE ➔ MODIFY ➔ EXTEND ➔ CREATE
+```
+
+---
+
+## Output Schema
+
+```
+━━━ Minimal Change Governance Audit ━━━━━━━━━━━━━━━━━━━━━━
+
+Minimality Score:          88/100 (PASSED)
+Decision Classification:   MODIFY
+Strictness Mode:           balanced
+
+━━━ Change Budget ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+files_added:               0
+files_modified:            2
+dependencies_added:        0
+new_abstractions:          0
+estimated_lines_added:     14
+estimated_lines_removed:    4
+
+━━━ Complexity Flags ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ None detected
+
+━━━ Reuse Opportunities ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+- Extend src/utils/http.ts for retry policy rather than creating a new service file
+
+━━━ Recommendation ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Proceed with MODIFY strategy on src/utils/http.ts
+```
+
+---
+
+## Usage Examples
+
+```
+/minimal add request retry handling to API calls
+/minimal-review src/services/retryQueue.ts
+/change-budget
+/complexity-audit
+/reuse-check fetchRetry
+```