tribunal-kit 1.0.0 → 2.4.0

package/.agent/workflows/changelog.md

@@ -0,0 +1,144 @@
+---
+description: Auto-generate changelogs from git history. Categorizes changes by type and follows Keep a Changelog format.
+---
+
+# /changelog — Generate Change History
+
+$ARGUMENTS
+
+---
+
+This command generates a structured changelog from git history. It reads real commits and categorizes them — it never invents changes that don't exist.
+
+---
+
+## When to Use This
+
+- Before a release to document what changed
+- When preparing release notes for stakeholders
+- To create or update `CHANGELOG.md`
+- To summarize work completed in a sprint or between two tags
+
+---
+
+## What Happens
+
+### Stage 1 — Determine Range
+
+Default range: commits since the last tag. Override with:
+
+```bash
+# Default: since last tag
+// turbo
+git log $(git describe --tags --abbrev=0)..HEAD --oneline --format="%h %ad %s" --date=short
+
+# Last N commits
+git log -n 20 --oneline --format="%h %ad %s" --date=short
+
+# Between specific tags
+git log v1.0.0..v2.0.0 --oneline --format="%h %ad %s" --date=short
+
+# Since a date
+git log --since="2025-01-01" --oneline --format="%h %ad %s" --date=short
+```
+
+If no tags exist: default to last 20 commits and flag no tags found.
+
+### Stage 2 — Collect and Categorize
+
+Read the git log and categorize each commit by prefix:
+
+| Commit Prefix | Category | Icon |
+|---|---|---|
+| `feat:`, `feature:`, `add:` | Features | ✨ |
+| `fix:`, `bugfix:`, `hotfix:` | Fixes | 🐛 |
+| `refactor:`, `cleanup:` | Refactors | ♻️ |
+| `docs:`, `doc:` | Documentation | 📝 |
+| `test:`, `tests:` | Tests | ✅ |
+| `chore:`, `build:`, `ci:` | Maintenance | 🔧 |
+| `perf:`, `performance:` | Performance | ⚡ |
+| `security:`, `sec:` | Security | 🔒 |
+| `BREAKING:`, `breaking:`, `!` after scope | Breaking Changes | 💥 |
+| (no recognized prefix) | Other | 📦 |
+
+### Stage 3 — Generate Output
+
+Output follows [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+# Changelog
+
+## [Unreleased] — YYYY-MM-DD
+
+### 💥 Breaking Changes
+- `abc1234` — Description of breaking change
+
+### ✨ Features
+- `def5678` — Description of new feature
+
+### 🐛 Fixes
+- `ghi9012` — Description of bug fix
+
+### ⚡ Performance
+- `jkl3456` — Description of performance improvement
+
+### 🔒 Security
+- `mno7890` — Description of security fix
+
+### ♻️ Refactors
+- `pqr1234` — Description of refactor
+
+### 📝 Documentation
+- `stu5678` — Description of docs change
+
+### 🔧 Maintenance
+- `vwx9012` — Description of chore/dependency bump
+```
+
+### Stage 4 — Review and Save
+
+Present the generated summary before writing:
+
+```
+📋 Generated changelog from [range]:
+  💥 1 breaking change
+  ✨ 3 features
+  🐛 5 fixes
+  📦 2 uncategorized commits
+
+Save to CHANGELOG.md? [Y = append | N = cancel | S = stdout only]
+```
+
+> ⏸️ **Human Gate** — CHANGELOG.md is not written without confirmation.
+
+---
+
+## Hallucination Guard
+
+- **Only include commits that actually exist** in git history — read from `git log`, never invent
+- **Never summarize or paraphrase** ambiguous commit messages — include verbatim if unclear
+- **Always show the commit hash** for traceability beside each entry
+- **Never infer intent** from a commit message — report what was written, not what it "probably meant"
+- Breaking changes need to be explicitly labeled in the commit — never infer breakage from code
+
+---
+
+## Cross-Workflow Navigation
+
+| After /changelog reveals... | Go to |
+|---|---|
+| Many uncategorized commits | Enforce commit conventions in the team |
+| Breaking changes need documentation | Update API docs or migration guides |
+| Ready for release | `/deploy` to complete the release pipeline |
+
+---
+
+## Usage
+
+```
+/changelog since the last release
+/changelog for the last 50 commits
+/changelog between v1.0 and v2.0
+/changelog generate and save to CHANGELOG.md
+/changelog sprint summary since 2025-03-01
+```

package/.agent/workflows/create.md

@@ -8,7 +8,18 @@ $ARGUMENTS
 
 ---
 
-This command starts a structured creation process. Code only appears after requirements are clear and a plan is approved.
+This command starts a structured creation process. **Code only appears after requirements are clear and a plan is approved.** Building before understanding is the number one source of wasted work.
+
+---
+
+## When to Use /create vs Other Commands
+
+| Use `/create` when... | Use something else when... |
+|---|---|
+| Starting something from scratch | Extending existing code → `/enhance` |
+| Building a complete feature (frontend + backend + DB) | Single function needed → `/generate` |
+| You need a plan before code | Plan only, no code → `/plan` |
+| Multi-domain coordination required | Single domain → `/generate` with right tribunal |
 
 ---
 
@@ -25,7 +36,18 @@ Before any planning begins, these four things must be established:
 4. What's the observable done state?   (how do we know it's finished?)
 ```
 
-If anything is unclear → ask. Do not skip to Stage 2 on assumptions.
+**If anything is unclear → ask. Do not skip to Stage 2 on assumptions.**
+
+Minimum Socratic gate questions by project type:
+
+| Project type | Questions to ask before planning |
+|---|---|
+| API / backend | Auth strategy? Database? Error format? Rate limiting? |
+| Frontend / UI | Framework? Design system? State management? SSR? |
+| Full-stack | All of the above + deployment target |
+| CLI tool | Target OS? Binary or script? Package manager integration? |
+
+---
 
 ### Stage 2 — Plan
 
@@ -36,36 +58,52 @@ Location: docs/PLAN-{task-slug}.md
 
 Must contain:
   - Goal (one sentence)
-  - OOS list (what we won't build)
-  - Task table with: task / agent / dependency / done-condition
+  - Out-of-scope list (what we won't build in this version)
+  - Open questions with [VERIFY] tags
+  - Task table: task / agent / dependency / done-condition
   - Tribunal gate per task
+  - Time estimates: optimistic / realistic / pessimistic + confidence level
 ```
 
 **The plan is shown to the user before any code is written.**
 
 > ⏸️ "Here's the plan: `docs/PLAN-{slug}.md` — proceed?"
-> Do not advance until explicitly confirmed.
+> Do not advance until explicitly confirmed with **Y**.
+
+---
 
 ### Stage 3 — Build (Parallel agents, after approval)
 
-| Layer | Agent | Review Gate |
+| Layer | Primary Agent | Review Gate |
 |---|---|---|
-| Data schema | `database-architect` | `/tribunal-database` |
-| API & server | `backend-specialist` | `/tribunal-backend` |
+| Data schema / migrations | `database-architect` | `/tribunal-database` |
+| API & server logic | `backend-specialist` | `/tribunal-backend` |
 | UI & components | `frontend-specialist` | `/tribunal-frontend` |
-| Test coverage | `test-engineer` | `logic + test-coverage` |
+| Test coverage | `test-engineer` | `logic + test-coverage-reviewer` |
+| DevOps / deploy config | `devops-engineer` | `/tribunal-backend` |
 
 Each agent's code goes through Tribunal before being shown to the user.
 
+**Wave execution (if multiple layers):**
+
+```
+Wave 1: database-architect → reviewed → Human Gate
+Wave 2: backend-specialist (uses Wave 1 schema) → reviewed → Human Gate
+Wave 3: frontend-specialist + test-engineer (parallel) → reviewed → Human Gate
+```
+
+---
+
 ### Stage 4 — Verify
 
 ```
-Did the code satisfy every done-condition from Stage 1?   Y / N
-Did all Tribunal reviewers return APPROVED?               Y / N
-Are untested paths labeled // TODO with an explanation?  Y / N
+□ Did the code satisfy every done-condition from Stage 1?
+□ Did all Tribunal reviewers return APPROVED?
+□ Are untested paths labeled // TODO with an explanation?
+□ Does the plan file match what was actually built?
 ```
 
-All three must be Y before the task is declared done.
+All four must be checked before the task is declared done.
 
 ---
 
@@ -73,7 +111,20 @@ All three must be Y before the task is declared done.
 
 - Every import must exist in the project's `package.json` or carry `// VERIFY: add to deps`
 - No invented framework methods — `// VERIFY: check docs for this method` on any uncertain call
-- No agent touches code outside its domain
+- No agent touches code outside its domain (frontend agent never writes DB migrations)
+- No full-application generation in one shot — build in layers with Human Gates between waves
+
+---
+
+## Cross-Workflow Navigation
+
+| If during /create you need to... | Go to |
+|---|---|
+| Understand the existing codebase first | Use `explorer-agent` before Stage 2 |
+| Only write the plan (not build it) | `/plan` |
+| Add to an already built feature | `/enhance` |
+| Debug something during Stage 3 | `/debug` |
+| Run a full safety check before shipping | `/audit` |
 
 ---
 
@@ -83,4 +134,6 @@ All three must be Y before the task is declared done.
 /create a REST API with JWT auth
 /create a React dashboard with real-time chart updates
 /create a complete user onboarding flow (frontend + backend + DB)
+/create a CLI tool that validates JSON schemas against a spec
+/create a scheduled background job for sending email digests
 ```

package/.agent/workflows/debug.md

@@ -1,5 +1,5 @@
 ---
-description: Debugging command. Activates DEBUG mode for systematic problem investigation.
+description: Debugging command. Activates DEBUG mode for systematic problem investigation. No fix is suggested until the root cause is confirmed.
 ---
 
 # /debug — Root Cause Investigation
@@ -8,7 +8,7 @@ $ARGUMENTS
 
 ---
 
-This command switches the AI into **investigation mode**. No fixes are suggested until the root cause is identified. No random changes. No guessing.
+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.
 
 ---
 
@@ -16,49 +16,126 @@ This command switches the AI into **investigation mode**. No fixes are suggested
 
 > "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:
+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
+
+---
+
+## When to Use /debug vs Other Commands
+
+| 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` |
+
+---
+
+## Step 1 — Evidence Collection
+
+**Collect these before forming any hypothesis:**
+
+```
+□ Exact error text — full stack trace, not a summary
+□ 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
+```
+
+> ⚠️ If the error is intermittent, collect timing data before hypothesizing.
+
+---
+
+## Step 2 — Hypothesis Generation
+
+Map possible causes — label each honestly:
+
+```
+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]
+```
+
+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
 
 ---
 
-## Investigation Sequence
+## Step 3 — Single-Hypothesis Testing
 
-**Collect evidence first:**
-- Exact error text (full stack trace, not a summary)
-- Minimum reproduction steps
-- Last known-good state (commit, date, config)
-- Recent changes (code, dependency updates, env vars, infrastructure)
+Test causes **one at a time**. Never test two simultaneously — it makes the result ambiguous.
 
-**Map possible causes — label them honestly:**
+```
+H1 tested: [what was examined + how]
+Result:     ✅ Confirmed root cause | ❌ Ruled out — [reason]
 
+H2 tested: [what was examined + how]
+Result:     ✅ Confirmed root cause | ❌ Ruled out — [reason]
 ```
-Cause A: [what it is] — Likelihood: High / Medium / Low
-Cause B: [what it is] — Likelihood: High / Medium / Low
-Cause C: [what it is] — Likelihood: High / Medium / Low
+
+Stop when the first hypothesis is confirmed. Do not continue testing eliminated causes.
+
+---
+
+## Step 4 — Root Cause Statement
+
+The root cause is the **single thing** that, if changed, prevents the entire failure chain.
+
+Format:
+
 ```
+Root Cause: [One sentence — WHY this happened, not WHAT happened]
 
-Every entry labeled as a **hypothesis**, not a diagnosis.
+Example:
+✅ "JWT verification was skipped when the Authorization header used 'bearer' (lowercase), 
+    because the header check was case-sensitive."
 
-**Test causes one at a time:**
-Check one. Mark resolved or eliminated. Move to next. Never test two simultaneously.
+❌ "The login returned 401." (This is the symptom, not the cause)
+```
 
-**Find the root cause:**
-The thing that, if changed, prevents the entire failure chain. Fixing a symptom doesn't count.
+---
 
-**Apply a targeted fix + prevent recurrence:**
-One change. Then verify. Then add a regression test.
+## 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
+```
+
+> ⚠️ All debug logging added during investigation must be removed before the fix is presented.
 
 ---
 
-## Report Format
+## Debug Report Format
 
 ```
 ━━━ Debug Report ━━━━━━━━━━━━━━━━━━━━━━━
 
 Symptom:      [what the user sees]
 Error:        [exact message or trace]
-Reproduced:   [Yes | No | Sometimes]
+Reproduced:   Yes | No | Sometimes — [conditions]
+Environment:  [runtime, version, OS]
 Last working: [commit / date / known-good state]
 
+━━━ Evidence Collected ━━━━━━━━━━━━━━━━
+
+- [specific observation 1]
+- [specific observation 2]
+
 ━━━ Hypotheses ━━━━━━━━━━━━━━━━━━━━━━━
 
 H1 [High]   — [cause and why it's likely]
@@ -72,33 +149,48 @@ H2: ruled out — [evidence against it]
 
 ━━━ Root Cause ━━━━━━━━━━━━━━━━━━━━━
 
-[Single sentence explaining WHY this happened]
+[Single sentence — WHY this happened]
 
 ━━━ Fix ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Before:  [original code]
 After:   [corrected code]
 
-Regression test: [what test was added to prevent this]
-Similar patterns: [anywhere else in the codebase this might exist]
+Regression test: [what test prevents this from recurring]
+Similar patterns: [any other locations to check in the codebase]
 ```
 
 ---
 
 ## Hallucination Guard
 
-- Every hypothesis is explicitly labeled as a hypothesis — never as confirmed fact
-- Proposed fixes only use real, documented APIs — `// VERIFY: check method exists` on uncertainty
-- 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
+- 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
+/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
 ```

package/.agent/workflows/deploy.md

@@ -8,7 +8,7 @@ $ARGUMENTS
 
 ---
 
-This command runs a structured, gate-enforced deployment sequence. Nothing reaches production without passing all three gates.
+This command runs a structured, gate-enforced deployment sequence. **Nothing reaches production without passing all three gates.**
 
 ---
 
@@ -19,6 +19,21 @@ This command runs a structured, gate-enforced deployment sequence. Nothing reach
 
 ---
 
+## 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
@@ -28,23 +43,34 @@ This command runs a structured, gate-enforced deployment sequence. Nothing reach
 ```
 Expected clean state:
   ✅ No secrets or credentials in any changed file
-  ✅ No unparameterized query added
-  ✅ No new CVE-affected dependency introduced
+  ✅ 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 is found → deployment is blocked.**
-The issue must be fixed and re-scanned before proceeding.
+**If any CRITICAL or HIGH issue → deployment is blocked.** Fix and re-scan before proceeding.
 
 ### Gate 2 — Tribunal Verification
 
-`/tribunal-full` runs on all changed code:
+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
+✅ logic-reviewer: APPROVED
+✅ security-auditor: APPROVED
+✅ dependency-reviewer: APPROVED
+✅ type-safety-reviewer: APPROVED
 ```
 
 **Any REJECTED verdict → deployment blocked.** Fix and re-review.
@@ -54,43 +80,67 @@ The issue must be fixed and re-scanned before proceeding.
 A deployment summary is shown before execution:
 
 ```
-━━━ Release Summary ━━━━━━━━━
+━━━ Release Summary ━━━━━━━━━━━━━━━━━━━━━━━━
 Target:        [staging | production]
-Files changed: [N]
-Security gate: ✅ Passed
-Tribunal gate: ✅ All APPROVED
-Tests:         ✅ N passed
-
-Rollback to:   [previous tag / commit SHA]
-Rollback time: [estimate]
-DB-safe:       [Yes | No — explain]
-
-Proceed with deployment? (Y to execute | N to cancel)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+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, the rollback plan must be established:
+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
-Who gets notified on rollback?        → [name or channel]
+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.
+**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
-- All images tagged with a specific version — `latest` is forbidden in production configs
+- **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 |
 
 ---
 
@@ -99,4 +149,5 @@ No rollback plan = no deployment.
 ```
 /deploy to staging
 /deploy to production after staging validation
+/deploy hotfix for the auth regression
 ```