tribunal-kit 2.4.6 → 3.0.0

package/.agent/workflows/deploy.md

@@ -1,153 +1,189 @@
----
-description: Deployment command for production releases. Pre-flight checks and deployment execution.
----
-
-# /deploy — Production Release
-
-$ARGUMENTS
-
----
-
-This command runs a structured, gate-enforced deployment sequence. **Nothing reaches production without passing all three gates.**
-
----
-
-## The Non-Negotiable Rule
-
-> **The Human Gate is never skipped.**
-> Even if every automated gate passes, a human sees the deployment summary and explicitly approves before anything executes.
-
----
-
-## Before Running /deploy
-
-Confirm the following checklist manually:
-
-```
-□ /audit passed with no CRITICAL or HIGH issues
-□ All tests pass on the current commit
-□ CHANGELOG.md is updated
-□ Environment variables are confirmed in the target environment
-□ Database migrations (if any) have a rollback plan
-□ Rollback target (tag or SHA) is documented
-```
-
----
-
-## Three-Gate Sequence
-
-### Gate 1 — Security Sweep
-
-`security-auditor` scans all files in the deployment diff:
-
-```
-Expected clean state:
-  ✅ No secrets or credentials in any changed file
-  ✅ No unparameterized query introduced
-  ✅ No new CVE-affected dependency
-  ✅ No debug endpoints left active
-  ✅ No `console.log` with sensitive data
-```
-
-```bash
-// turbo
-python .agent/scripts/security_scan.py .
-```
-
-**If any CRITICAL or HIGH issue → deployment is blocked.** Fix and re-scan before proceeding.
-
-### Gate 2 — Tribunal Verification
-
-Run `/tribunal-full` on all changed code:
-
-```bash
-# Run full check suite
-// turbo
-python .agent/scripts/verify_all.py
-```
-
-```
-✅ logic-reviewer: APPROVED
-✅ security-auditor: APPROVED
-✅ dependency-reviewer: APPROVED
-✅ type-safety-reviewer: APPROVED
-```
-
-**Any REJECTED verdict → deployment blocked.** Fix and re-review.
-
-### Gate 3 — Human Approval
-
-A deployment summary is shown before execution:
-
-```
-━━━ Release Summary ━━━━━━━━━━━━━━━━━━━━━━━━
-Target:        [staging | production]
-Commit:        [SHA — first 8 chars]
-Files changed: [N] — view diff?
-Security gate: ✅ Passed (no CRITICAL/HIGH issues)
-Tribunal gate: ✅ All reviewers APPROVED
-Tests:         ✅ [N] passed, [0] failed
-
-Rollback to:   [previous tag or commit SHA]
-Rollback time: [estimate in minutes]
-DB migration:  [None | ⚠️ IRREVERSIBLE | ✅ Reversible]
-DB backup:     [Confirmed | Not confirmed — deployment blocked]
-
-Proceed with deployment? Y = execute | N = cancel
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## Rollback is a Prerequisite
-
-Before any deployment executes, a rollback plan must exist:
-
-```
-What does this roll back to?     → [tag or SHA]
-How long will rollback take?     → [estimate]
-Is the DB migration reversible?  → Yes | No — if No, is backup confirmed?
-Who gets notified on rollback?   → [name or Slack channel]
-```
-
-**No rollback plan = no deployment.** This is not optional.
-
----
-
-## Environment-Specific Rules
-
-| Target | Extra Requirements |
-|---|---|
-| Staging | Rollback optional, tests required, git tag optional |
-| Production | All requirements above + git tag required |
-| Hotfix | Security gate required, Human Gate required |
-
----
-
-## Hallucination Guard
-
-- **No invented CLI flags** — `# VERIFY: check docs for this flag` on any uncertain command
-- **All secrets via environment variables** — never hardcoded in deploy configs or scripts
-- **All images tagged with a specific version** — `latest` is forbidden in production configs
-- **Never generate deployment steps without reading the existing deploy scripts** — read before writing
-
----
-
-## Cross-Workflow Navigation
-
-| Before /deploy... | Go to |
-|---|---|
-| Security audit not run yet | `/audit` first |
-| Tests broken | `/debug` to fix, then `/test` to verify |
-| Changelog outdated | `/changelog` to update first |
-| DB migration needed | `/migrate` with rollback plan documented |
-
----
-
-## Usage
-
-```
-/deploy to staging
-/deploy to production after staging validation
-/deploy hotfix for the auth regression
-```
+---
+description: Production deployment command. Runs pre-flight safety checks (tests, type-check, lint, security, build), creates a rollback baseline, confirms Human Gate, then executes deployment. Requires explicit human approval before going live.
+---
+
+# /deploy — Production Deployment
+
+$ARGUMENTS
+
+---
+
+## The Deployment Contract
+
+> "Production is the only environment that matters. Every deployment is a risk event."
+> Every step is logged. Every step has a rollback path. No surprises.
+
+---
+
+## When to Use /deploy
+
+| Use `/deploy` when... | Do NOT deploy when... |
+|:---|:---|
+| All pre-flight checks pass | Any pre-flight check fails |
+| Changes are reviewed and approved | In the middle of a debug session |
+| You have a rollback plan | No tests run since last change |
+| Non-peak traffic hours (if possible) | Security audit shows critical issues |
+
+---
+
+## Phase 1 — Pre-Flight Checks (ALL Must Pass)
+
+**If ANY check in Phase 1 fails → deployment is BLOCKED.**
+
+```bash
+# T-minus safety sequence (in exact order)
+
+# 1. Security: halt on critical
+python .agent/scripts/security_scan.py . --level=critical
+
+# 2. Dependencies: no exploitable CVEs
+npm audit --audit-level=high
+
+# 3. Type safety: zero errors allowed
+npx tsc --noEmit
+
+# 4. Tests: all must pass
+npm test
+
+# 5. Build: production build must succeed
+npm run build
+
+# 6. Lint: blocking errors halt deployment
+npm run lint --max-warnings=0
+```
+
+**Pre-Flight Report:**
+
+```
+━━━ Pre-Flight Status ━━━━━━━━━━━━━━━━━━━━━
+
+Security:    ✅ CLEAR | ❌ BLOCKED ([finding])
+npm audit:   ✅ CLEAR | ❌ BLOCKED ([CVE])
+TypeScript:  ✅ ZERO ERRORS | ❌ BLOCKED (N errors)
+Tests:       ✅ ALL PASS | ❌ BLOCKED (N failing)
+Build:       ✅ SUCCESS | ❌ BLOCKED (build error)
+Linting:     ✅ CLEAN | ⚠️ WARNINGS (N) | ❌ BLOCKING ERRORS (N)
+```
+
+---
+
+## Phase 2 — Rollback Baseline
+
+Before deployment, capture the rollback state:
+
+```bash
+# Option A: Git baseline
+git rev-parse HEAD  # Record current commit hash
+# Rollback: git revert HEAD or git reset --hard [hash]
+
+# Option B: Tag the current release
+git tag release-$(date +%Y%m%d-%H%M%S)
+git push origin --tags
+
+# Option C: Database snapshot (if schema changed)
+pg_dump $DATABASE_URL > backup-$(date +%Y%m%d-%H%M%S).sql
+```
+
+**Rollback baseline must be confirmed before deployment begins.**
+
+---
+
+## Phase 3 — Human Gate (Non-Negotiable)
+
+After pre-flight passes, present to the deployer:
+
+```
+━━━ Deployment Approval Required ━━━━━━━━━━━━━━
+
+Target environment:  [production | staging]
+Changes in this deploy:
+  [commit summary: feat/fix/chore + description]
+  [number of files changed]
+
+Database changes:    [Yes: describe migration | None]
+Breaking changes:    [Yes: describe | None]
+
+Pre-flight:          ✅ ALL CHECKS PASSED
+
+Rollback baseline:   Commit [hash] tagged as [release-name]
+Rollback command:    git reset --hard [hash]
+
+Deploy?  Y = proceed | N = abort | W = wait (deploy later)
+```
+
+**Nothing is deployed without explicit "Y" from the human.**
+
+---
+
+## Phase 4 — Deployment Execution
+
+```bash
+# Deploy (platform-specific — auto-detected from project config)
+
+# → Render + GitHub Actions:
+git push origin main  # CI/CD deploys automatically
+
+# → Manual Fly.io:
+flyctl deploy --strategy rolling
+
+# → Manual Kubernetes:
+kubectl set image deployment/api api=[registry]/app:[commit-sha]
+kubectl rollout status deployment/api
+```
+
+---
+
+## Phase 5 — Post-Deploy Verification
+
+Within 5 minutes of deployment completing:
+
+```bash
+# Health check
+curl -f https://api.yoursite.com/health        # Must return 200
+curl -f https://yoursite.com                   # Must load
+curl -f https://yoursite.com/api/auth/session  # Auth must work
+
+# Monitor error rate (5 minutes)
+# If error rate > 1% above baseline → initiate rollback immediately
+```
+
+---
+
+## Rollback Decision Tree
+
+```
+After deploy, within 5 minutes:
+├── Error rate normal + health checks pass → ✅ Deployment successful
+├── Error rate elevated but < 1% above baseline → ⚠️ Monitor for 10 more minutes
+├── Error rate > 1% above baseline → ❌ ROLLBACK IMMEDIATELY
+└── Health check fails → ❌ ROLLBACK IMMEDIATELY
+
+Rollback command:
+  git reset --hard [baseline-commit]
+  git push origin main --force-with-lease
+```
+
+---
+
+## Schema Change Deployment Pattern
+
+If this deploy includes database migrations:
+
+```
+1. Deploy migration in isolation (no application code change)
+2. Verify migration succeeded and DB is healthy
+3. THEN deploy application code that uses new schema
+```
+
+**Never deploy application code and schema changes in the same deployment.**
+
+---
+
+## Cross-Workflow Navigation
+
+| Pre-flight finds... | Go to |
+|:---|:---|
+| Security vulnerability | Fix with `/tribunal-backend` first |
+| TypeScript errors | Fix with `/fix` or `/generate` first |
+| Tests failing | Fix with `/debug` and `/test` first |
+| Build failure | Fix with `/debug` first |

package/.agent/workflows/enhance.md

@@ -1,139 +1,151 @@
----
-description: Add or update features in existing application. Used for iterative development.
----
-
-# /enhance — Extend What Exists
-
-$ARGUMENTS
-
----
-
-This command adds to or improves existing code **without breaking what already works**. Enhancement is not greenfield — the existing system shapes what can be done and how.
-
----
-
-## When to Use /enhance vs Other Commands
-
-| Use `/enhance` when... | Use something else when... |
-|---|---|
-| Adding to working, existing code | Building from scratch → `/create` |
-| Extending a function or module | Restructuring without new behavior → `/refactor` |
-| Adding a new endpoint to an existing API | Fixing a broken behavior → `/debug` |
-| Upgrading a component's capabilities | Auditing for problems → `/review` |
-
----
-
-## First Rule: Read, Then Write
-
-> Never modify code you haven't read.
-> Never modify a function without checking what calls it.
-
-The first step of every enhancement is a **reading pass** — not a writing pass.
-
----
-
-## Enhancement Sequence
-
-### Step 1 — Map the Impact Zone
-
-Before touching any file, produce this map:
-
-```
-Files to change:      [list — explicit, not "etc."]
-Functions affected:   [list — every function being modified]
-Callers of those:     [list — these must remain unbroken]
-Tests covering them:  [list — these must pass after the change]
-Exported symbols:     [list — any public API that must stay compatible]
-```
-
-> ⚠️ If the impact zone spans more than 10 files, pause and confirm scope with the user before proceeding.
-
-### Step 2 — Define What Changes vs What Stays
-
-```
-Adding:      [new capability being added]
-Modifying:   [existing behavior being changed — explain why]
-Preserving:  [things that must not change — API contracts, test expectations, response formats]
-```
-
-Any change to a **public interface** (function signature, API response shape, exported type) triggers an update of **all callers** — not just the changed file.
-
-### Step 3 — Implement Through Tribunal Gate
-
-| Enhancement Type | Tribunal Gate |
-|---|---|
-| Backend logic / API change | `/tribunal-backend` |
-| Frontend / UI component | `/tribunal-frontend` |
-| DB queries or schema | `/tribunal-database` |
-| Cross-domain change | `/tribunal-full` |
-| Mobile UI component | `/tribunal-mobile` |
-| Performance-critical path | `/tribunal-performance` |
-
-The code goes through Tribunal **before** being shown to the user.
-
-### Step 4 — Regression Safety Check
-
-```
-□ Existing tests: still pass (none were broken by the change)
-□ New tests added: covering the new behavior
-□ Callers updated: if any interface changed, all callers are updated together
-□ TypeScript / lint: check passes after the enhancement
-```
-
-All four must be true before the enhancement is considered complete.
-
----
-
-## Response Template
-
-```
-Enhancement: [What was added or changed, in one sentence]
-
-Impact Zone:
-  Changed:         [files modified]
-  Callers updated: [files updated, or "none — interface preserved"]
-
-Tribunal result:
-  [reviewer]: [APPROVED | REJECTED — reason]
-
-Regression risk:
-  🟢 Low    — new path only, no existing path changed
-  🟡 Medium — shared code modified, callers reviewed and updated
-  🔴 High   — interface changed, all callers updated and verified
-
-Changes:
-  [diff or before/after]
-```
-
----
-
-## Hallucination Guard
-
-- **Read existing code before describing it** — never assume what a function does from its name
-- **Preserved interfaces must stay identical** — adding a required parameter breaks every caller silently
-- **Unknown patterns get `// VERIFY`** — never guess at a codebase convention or framework behavior
-- **Never delete or rename an export** without verifying all import sites are updated
-- **`// VERIFY: check method exists`** on any method call not seen in existing code or official docs
-
----
-
-## Cross-Workflow Navigation
-
-| If during /enhance you encounter... | Go to |
-|---|---|
-| Unexpected behavior in existing code | `/debug` to root-cause before changing anything |
-| Code quality so poor it needs restructuring | `/refactor` first, then come back to `/enhance` |
-| Security vulnerability in the code you're reading | `/audit` to determine blast radius |
-| Tests don't exist for the area being changed | `/test` first to establish a baseline |
-
----
-
-## Usage
-
-```
-/enhance add pagination to the users list API endpoint
-/enhance add rate limiting to all authentication routes
-/enhance upgrade the search component to support filters
-/enhance add retry logic to the payment service's HTTP client
-/enhance extend the user model to support multiple email addresses
-```
+---
+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.
+---
+
+# /enhance — Feature Addition & Modification
+
+$ARGUMENTS
+
+---
+
+## 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
+```
+
+---
+
+## Cross-Workflow Navigation
+
+| After /enhance shows... | Go to |
+|:---|:---|
+| A breaking change in auth or security code | `/tribunal-backend` |
+| DB schema changes required | `/tribunal-database` |
+| Component redesign needed | `/tribunal-frontend` |
+| New tests required | `/test` |
+| Performance impact suspected | `/tribunal-performance` |
+
+---
+
+## Usage Examples
+
+```
+/enhance add pagination to the /api/users endpoint
+/enhance add server-side error boundary to the dashboard page
+/enhance update the User model to add a phoneNumber field
+/enhance replace useState with useOptimistic for the like button
+/enhance add rate limiting to the POST /auth/login endpoint
+/enhance add dark mode support to the design system
+```