tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/debug.md

@@ -1,5 +1,5 @@
 ---
-description: Debugging command. Activates DEBUG mode for systematic problem investigation. No fix is suggested until the root cause is confirmed.
+description: Debugging command. Activates DEBUG mode for systematic problem investigation using the 4-phase methodology (Collect → Hypothesize → Test → Fix). No fix is suggested until the root cause is confirmed and tested. No random changes. No guessing.
 ---
 
 # /debug — Root Cause Investigation
@@ -8,102 +8,98 @@ $ARGUMENTS
 
 ---
 
-This command switches the AI into **investigation mode**. No fixes are suggested until the root cause is identified and confirmed. No random changes. No guessing.
-
----
-
 ## The Investigation Contract
 
-> "A fix without a root cause is a patch on a symptom. It will fail again."
+"A fix without a root cause is a patch on a symptom. It will fail again."
 
 The `debugger` agent follows this sequence **without skipping steps**:
 
-1. Collect evidence
-2. Generate hypotheses
-3. Test hypotheses one at a time
-4. Identify root cause
-5. Apply targeted fix
-6. Verify the fix and prevent recurrence
+1. Collect all evidence first
+2. Generate ranked hypotheses 
+3. Test exactly one hypothesis at a time
+4. Confirm root cause with evidence
+5. Apply the minimum targeted fix
+6. Add a regression test to prevent recurrence
 
 ---
 
-## When to Use /debug vs Other Commands
+## When to Use /debug
 
-| Use `/debug` when... | Use something else when... |
-|---|---|
-| There's a specific error or unexpected behavior | Code needs to be written from scratch → `/generate` |
-| You have a stack trace or error message | Code quality needs improvement → `/refactor` |
-| Production is broken right now | You want to add tests → `/test` |
-| A bug reappears after being "fixed" | You want a full project health check → `/audit` |
+|Use `/debug` when...|Use something else when...|
+|:---|:---|
+|There's a specific error or unexpected behavior|Code needs to be written → `/generate`|
+|You have a stack trace or error message|Code quality needs improving → `/refactor`|
+|Production is broken right now|Missing test coverage → `/test`|
+|A bug reappears after being "fixed"|Full health check needed → `/audit`|
 
 ---
 
-## Step 1 — Evidence Collection
-
-**Collect these before forming any hypothesis:**
+## Step 1 — Evidence Collection (Collect All Before Hypothesizing)
 
 ```
-□ Exact error text — full stack trace, not a summary
+□ Exact error text — full stack trace, not a paraphrase
 □ Minimum reproduction steps — fewest actions that trigger the bug
 □ Last known-good state — commit hash, date, or config snapshot
-□ Recent changes — code, dependency updates, env vars, infra
-□ Environment — local / staging / production, OS, Node version, etc.
-□ Frequency — always / sometimes / only under load / only in prod
+□ Recent changes — code, deps, env vars, infra, config changes
+□ Environment — local/staging/prod, OS, Node version, browser, runtime
+□ Frequency — always / intermittent / only under load / production only
 ```
 
-> ⚠️ If the error is intermittent, collect timing data before hypothesizing.
+> ⚠️ If the error is intermittent: collect timing patterns before hypothesizing.
+
+### Priority Investigation Order (Most Likely Root Cause First)
+
+```
+1. Recent deployments     — 90% of outages are caused by recent changes
+2. Environment variables  — rotated/missing secrets are common silent failures
+3. Dependency updates     — a package update can break APIs without errors
+4. Infrastructure         — firewall, Security Groups, DB connection limits
+5. Application code       — last to check, easiest to blame prematurely
+```
 
 ---
 
-## Step 2 — Hypothesis Generation
+## Step 2 — Hypothesis Formation
 
-Map possible causes — label each honestly:
+Map all possible causes with explicit likelihood labels:
 
 ```
-Cause A: [what it is] — Likelihood: High / Medium / Low — Evidence: [what points to it]
-Cause B: [what it is] — Likelihood: High / Medium / Low — Evidence: [what points to it]
-Cause C: [what it is] — Likelihood: High / Medium / Low — Evidence: [what points to it]
+ROOT CAUSE CANDIDATES
+━━━━━━━━━━━━━━━━━━━━━
+H1 [High]   — [cause] — Evidence: [what points to this]
+H2 [Medium] — [cause] — Evidence: [what is consistent with this]
+H3 [Low]    — [cause] — Evidence: [theoretically possible]
 ```
 
-Every entry is labeled as a **hypothesis**, never as a confirmed fact.
-
-**Hypothesis ranking rules:**
-- High likelihood: directly supported by evidence or error message
-- Medium likelihood: consistent with the error but no direct evidence
-- Low likelihood: possible but requires unusual conditions
+**Never state a hypothesis as confirmed fact until Step 3 proves it.**
 
 ---
 
 ## Step 3 — Single-Hypothesis Testing
 
-Test causes **one at a time**. Never test two simultaneously — it makes the result ambiguous.
+Test **one at a time**. Never test two simultaneously — results become ambiguous.
 
 ```
-H1 tested: [what was examined + how]
-Result:     ✅ Confirmed root cause | ❌ Ruled out — [reason]
+H1 tested: [how it was investigated]
+Result:    ✅ Confirmed | ❌ Ruled out — [specific evidence against]
 
-H2 tested: [what was examined + how]
-Result:     ✅ Confirmed root cause | ❌ Ruled out — [reason]
+H2 tested: [how it was investigated]
+Result:    ✅ Confirmed | ❌ Ruled out — [reason]
 ```
 
-Stop when the first hypothesis is confirmed. Do not continue testing eliminated causes.
+Stop when the first hypothesis is confirmed. Do not continue investigating eliminated causes.
 
 ---
 
 ## Step 4 — Root Cause Statement
 
-The root cause is the **single thing** that, if changed, prevents the entire failure chain.
-
-Format:
+The root cause is one sentence: **WHY this happened**, not WHAT happened.
 
 ```
-Root Cause: [One sentence — WHY this happened, not WHAT happened]
-
-Example:
-✅ "JWT verification was skipped when the Authorization header used 'bearer' (lowercase), 
-    because the header check was case-sensitive."
+✅ "JWT verification was skipped when Authorization header used lowercase 'bearer'
+    because the header check was case-sensitive"
 
-❌ "The login returned 401." (This is the symptom, not the cause)
+❌ "The API returned 401" — This is the symptom, not the root cause
 ```
 
 ---
@@ -111,86 +107,59 @@ Example:
 ## Step 5 — Fix + Regression Prevention
 
 ```
-Targeted fix:    One change — the minimum required to resolve the root cause
-Regression test: A specific test added to catch this exact failure if it ever returns
-Similar patterns: Any other locations in the codebase where this pattern exists
+Targeted fix:    The minimum change that eliminates the root cause
+Regression test: A specific test that will catch this exact failure if it returns
+Similar patterns: Other locations in the codebase to audit for the same issue
+Debug cleanup:   All console.log/temporary changes removed from proposed fix
 ```
 
-> ⚠️ All debug logging added during investigation must be removed before the fix is presented.
-
 ---
 
 ## Debug Report Format
 
 ```
-━━━ Debug Report ━━━━━━━━━━━━━━━━━━━━━━━
+━━━ Debug Report ━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Symptom:      [what the user sees]
-Error:        [exact message or trace]
+Symptom:      [what the user observes]
+Error:        [exact message / stack trace]
 Reproduced:   Yes | No | Sometimes — [conditions]
-Environment:  [runtime, version, OS]
-Last working: [commit / date / known-good state]
-
-━━━ Evidence Collected ━━━━━━━━━━━━━━━━
+Environment:  [Node v22, Next.js 15, PostgreSQL 16]
+Last working: [commit hash / date]
 
+━━━ Evidence ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 - [specific observation 1]
 - [specific observation 2]
 
-━━━ Hypotheses ━━━━━━━━━━━━━━━━━━━━━━━
-
-H1 [High]   — [cause and why it's likely]
-H2 [Medium] — [cause and why it's possible]
-H3 [Low]    — [cause and why it's a stretch]
+━━━ Hypotheses ━━━━━━━━━━━━━━━━━━━━━━━━━━
+H1 [High]   — [cause and reasoning]
+H2 [Medium] — [cause and reasoning]
 
-━━━ Investigation ━━━━━━━━━━━━━━━━━━━
+━━━ Investigation ━━━━━━━━━━━━━━━━━━━━━━━
+H1: [what was tested] → ✅ Confirmed root cause
+H2: [what was tested] → ❌ Ruled out — [reason]
 
-H1: checked [what was examined] → ✅ Confirmed root cause
-H2: ruled out — [evidence against it]
+━━━ Root Cause ━━━━━━━━━━━━━━━━━━━━━━━━━
+[Single sentence WHY — not WHAT]
 
-━━━ Root Cause ━━━━━━━━━━━━━━━━━━━━━
+━━━ Fix ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Before: [original code]
+After:  [corrected code]
 
-[Single sentence — WHY this happened]
-
-━━━ Fix ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Before:  [original code]
-After:   [corrected code]
-
-Regression test: [what test prevents this from recurring]
-Similar patterns: [any other locations to check in the codebase]
+Regression test: [test preventing recurrence]
+Similar patterns: [other locations to check]
 ```
 
 ---
 
 ## Hallucination Guard
 
-- Every hypothesis is **explicitly labeled as a hypothesis** — never as confirmed fact until evidence backs it
-- Proposed fixes only use **real, documented APIs** — `// VERIFY: check method exists` on any uncertain call
-- **One change per fix** — multi-file rewrites presented as "a debug session" are a red flag
-- Debug logging added during investigation must be **removed** before the fix is presented
-- **Never assume the error message is accurate** — verify it matches actual behavior
-
----
-
-## Cross-Workflow Navigation
-
-| After /debug reveals... | Go to |
-|---|---|
-| Root cause confirmed, fix ready | `/generate` to write the fix safely through Tribunal |
-| Multiple files need changing | `/enhance` for impact-zone analysis + callers update |
-| Missing test allowed the bug in | `/test` to add regression coverage |
-| Performance was the root cause | `/tribunal-performance` for full optimization review |
-| Security vulnerability found | `/audit` to check if it exists elsewhere |
-
----
-
-## Usage
-
 ```
-/debug TypeError: Cannot read properties of undefined reading 'id'
-/debug API returns 500 only in production
-/debug useEffect runs on every render instead of once
-/debug login works locally but fails in CI
-/debug memory usage grows unbounded over 24h in the worker process
-/debug race condition in the payment confirmation handler
+❌ Never propose a fix before root cause is confirmed with evidence
+❌ Never test two hypotheses simultaneously
+❌ Never propose a "rewrite" as a debug session
+❌ Never leave console.log in the proposed fix
+❌ Never assume the error message accurately describes the actual cause
+❌ Never use real API methods without verifying they exist in this version
 ```
+
+---

package/.agent/workflows/deploy.md

@@ -1,153 +1,180 @@
 ---
-description: Deployment command for production releases. Pre-flight checks and deployment execution.
+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 Release
+# /deploy — Production Deployment
 
 $ARGUMENTS
 
 ---
 
-This command runs a structured, gate-enforced deployment sequence. **Nothing reaches production without passing all three gates.**
+## 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.
 
 ---
 
-## The Non-Negotiable Rule
+## When to Use /deploy
 
-> **The Human Gate is never skipped.**
-> Even if every automated gate passes, a human sees the deployment summary and explicitly approves before anything executes.
+|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|
 
 ---
 
-## Before Running /deploy
+## Phase 1 — Pre-Flight Checks (ALL Must Pass)
 
-Confirm the following checklist manually:
+**If ANY check in Phase 1 fails → deployment is BLOCKED.**
 
-```
-□ /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
-```
+```bash
+# T-minus safety sequence (in exact order)
 
----
+# 1. Security: halt on critical
+python .agent/scripts/security_scan.py . --level=critical
 
-## Three-Gate Sequence
+# 2. Dependencies: no exploitable CVEs
+npm audit --audit-level=high
 
-### Gate 1 — Security Sweep
+# 3. Type safety: zero errors allowed
+npx tsc --noEmit
 
-`security-auditor` scans all files in the deployment diff:
+# 4. Tests: all must pass
+npm test
 
-```
-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
+# 5. Build: production build must succeed
+npm run build
+
+# 6. Lint: blocking errors halt deployment
+npm run lint --max-warnings=0
 ```
 
-```bash
-// turbo
-python .agent/scripts/security_scan.py .
+**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)
 ```
 
-**If any CRITICAL or HIGH issue → deployment is blocked.** Fix and re-scan before proceeding.
+---
 
-### Gate 2 — Tribunal Verification
+## Phase 2 — Rollback Baseline
 
-Run `/tribunal-full` on all changed code:
+Before deployment, capture the rollback state:
 
 ```bash
-# Run full check suite
-// turbo
-python .agent/scripts/verify_all.py
-```
+# Option A: Git baseline
+git rev-parse HEAD  # Record current commit hash
+# Rollback: git revert HEAD or git reset --hard [hash]
 
-```
-✅ logic-reviewer: APPROVED
-✅ security-auditor: APPROVED
-✅ dependency-reviewer: APPROVED
-✅ type-safety-reviewer: APPROVED
+# 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
 ```
 
-**Any REJECTED verdict → deployment blocked.** Fix and re-review.
+**Rollback baseline must be confirmed before deployment begins.**
 
-### Gate 3 — Human Approval
+---
 
-A deployment summary is shown before execution:
+## Phase 3 — Human Gate (Non-Negotiable)
+
+After pre-flight passes, present to the deployer:
 
 ```
-━━━ 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
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+━━━ Deployment Approval Required ━━━━━━━━━━━━━━
 
----
+Target environment:  [production | staging]
+Changes in this deploy:
+  [commit summary: feat/fix/chore + description]
+  [number of files changed]
 
-## Rollback is a Prerequisite
+Database changes:    [Yes: describe migration | None]
+Breaking changes:    [Yes: describe | None]
 
-Before any deployment executes, a rollback plan must exist:
+Pre-flight:          ✅ ALL CHECKS PASSED
 
-```
-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]
+Rollback baseline:   Commit [hash] tagged as [release-name]
+Rollback command:    git reset --hard [hash]
+
+Deploy?  Y = proceed | N = abort | W = wait (deploy later)
 ```
 
-**No rollback plan = no deployment.** This is not optional.
+**Nothing is deployed without explicit "Y" from the human.**
 
 ---
 
-## Environment-Specific Rules
+## Phase 4 — Deployment Execution
+
+```bash
+# Deploy (platform-specific — auto-detected from project config)
+
+# → Render + GitHub Actions:
+git push origin main  # CI/CD deploys automatically
 
-| 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 |
+# → Manual Fly.io:
+flyctl deploy --strategy rolling
+
+# → Manual Kubernetes:
+kubectl set image deployment/api api=[registry]/app:[commit-sha]
+kubectl rollout status deployment/api
+```
 
 ---
 
-## Hallucination Guard
+## Phase 5 — Post-Deploy Verification
 
-- **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
+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
+```
 
 ---
 
-## Cross-Workflow Navigation
+## Rollback Decision Tree
 
-| 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 |
+```
+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
+```
 
 ---
 
-## Usage
+## Schema Change Deployment Pattern
+
+If this deploy includes database migrations:
 
 ```
-/deploy to staging
-/deploy to production after staging validation
-/deploy hotfix for the auth regression
+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.**
+
+---