tribunal-kit 2.4.6 → 3.0.0

package/.agent/workflows/review.md

@@ -1,155 +1,116 @@
----
-description: Audit existing code for hallucinations. Runs Logic + Security reviewers on any code without generating anything new.
----
-
-# /review — Code Audit (No Generation)
-
-$ARGUMENTS
-
----
-
-This command audits code you already have. **Nothing is generated.** The reviewers read, analyze, and report — that's it.
-
-Paste code directly after the command, or point to a file.
-
----
-
-## When to Use /review vs Other Commands
-
-| Use `/review` when... | Use something else when... |
-|---|---|
-| You want to audit code you already wrote | You want to generate new code → `/generate` |
-| You received AI-generated code from another tool | Code needs full pre-merge audit → `/tribunal-full` |
-| You suspect a security issue in one file | Full project security sweep → `/audit` |
-| You want a quick sanity check on a PR | Pre-merge review → `/tribunal-full` |
-
----
-
-## How to Use It
-
-**Via paste:**
-
-```
-/review
-
-[paste code here]
-```
-
-**Via file reference:**
-
-```
-/review src/services/auth.service.ts
-/review src/routes/user.ts for injection risks
-```
-
-**With a specific concern:**
-
-```
-/review src/db/queries.ts focus: SQL injection only
-/review the auth middleware focus: auth bypass and secrets
-```
-
----
-
-## What Always Runs
-
-```
-logic-reviewer      → Methods that don't exist, conditions that can't be true,
-                      undefined variables used before assignment,
-                      unreachable code, inverted boolean logic
-
-security-auditor    → SQL injection, hardcoded credentials, auth bypass,
-                      unvalidated input, exposed stack traces,
-                      insecure defaults, OWASP Top 10
-```
-
-## What Also Runs (Based on Code Type)
-
-| Code Contains | Additional Reviewer Activated |
-|---|---|
-| `SELECT`, `INSERT`, `UPDATE`, ORM queries | `sql-reviewer` |
-| React hooks, Vue components, JSX | `frontend-reviewer` |
-| TypeScript generics, `any`, type assertions | `type-safety-reviewer` |
-| `import`, `require`, third-party packages | `dependency-reviewer` |
-| `openai`, `anthropic`, `gemini`, LLM SDK calls | `ai-code-reviewer` |
-| Performance-critical loops or async paths | `performance-reviewer` |
-
----
-
-## Severity Levels
-
-| Symbol | Level | Meaning |
-|---|---|---|
-| `❌ CRITICAL` | Must Fix | Security vulnerability or data loss risk |
-| `❌ HIGH` | Must Fix | Logic error or likely production bug |
-| `⚠️ MEDIUM` | Should Fix | Non-critical but risky pattern |
-| `💬 LOW` | Advisory | Code smell or style concern |
-
----
-
-## Audit Report Format
-
-```
-━━━ Audit: [filename or snippet title] ━━━━━━━━━
-
-Active reviewers: logic · security · [others]
-
-logic-reviewer:       ✅ No hallucinated APIs or impossible logic found
-security-auditor:     ❌ REJECTED
-
-Findings:
-  ❌ CRITICAL — Line 8
-     Type: SQL injection
-     Code: `db.query(\`SELECT * WHERE id = ${id}\`)`
-     Fix:  db.query('SELECT * WHERE id = $1', [id])
-
-  ⚠️ MEDIUM — Line 22
-     Type: Unguarded optional access
-     Code: `user.profile.name`
-     Fix:  `user?.profile?.name ?? 'Unknown'`
-
-  💬 LOW — Line 34
-     Type: Magic number
-     Code: `setTimeout(fn, 3000)`
-     Fix:  Extract to named constant: `const RETRY_DELAY_MS = 3000`
-
-━━━ Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-1 CRITICAL issue blocking integration.
-1 MEDIUM issue — review before shipping.
-1 LOW advisory — consider addressing.
-
-Verdict: REJECTED — fix CRITICAL issues before merging.
-```
-
----
-
-## Hallucination Guard
-
-- Reviewers **read the actual code** — they don't assume what it does from function names
-- Every finding includes the **exact line and exact code** — no vague claims
-- Proposed fixes are **real, documented API calls** — not invented alternatives
-- Severity ratings are **evidence-based** — "CRITICAL" is never used for style concerns
-
----
-
-## Cross-Workflow Navigation
-
-| If review reveals... | Go to |
-|---|---|
-| CRITICAL security issues | `/audit` to check if the pattern exists elsewhere |
-| Code needs to be rewritten | `/generate` to regenerate with Tribunal protection |
-| More reviewers needed | `/tribunal-full` for all 11 reviewers |
-| Pattern found across many files | `/refactor` to fix the root abstraction |
-
----
-
-## Usage
-
-```
-/review the auth middleware
-/review this SQL query [paste]
-/review src/routes/user.ts for injection risks
-/review my React component for hooks violations
-/review src/services/payment.ts focus: error handling and data exposure
-```
+---
+description: Audit existing code for hallucinations. Runs Logic + Security reviewers on any code without generating anything new. The pure review mode — read, analyze, and report only.
+---
+
+# /review — Hallucination Audit (Read-Only)
+
+$ARGUMENTS
+
+---
+
+## When to Use /review
+
+| Use `/review` when... | Use something else when... |
+|:---|:---|
+| Auditing code you didn't write | AI-specific code review → `/review-ai` |
+| Checking existing code for hallucinations | Need Tribunal with generation → `/generate` |
+| Pre-merge code review | Full pre-deploy audit → `/audit` |
+| Validating AI-generated output | Security only → `/tribunal-backend` |
+| Reviewing code from a junior developer | |
+
+---
+
+## The Review Contract
+
+```
+/review is READ ONLY.
+No files are modified.
+No code is generated.
+Only findings and recommendations are produced.
+```
+
+---
+
+## Active Reviewers
+
+Logic + Security run on ALL code by default.
+
+**Additional reviewers auto-activated by content:**
+
+| Code Contains | Additional Reviewers |
+|:---|:---|
+| SQL, Prisma, database operations | `sql-reviewer` |
+| React, hooks, components | `frontend-reviewer` |
+| TypeScript types, generics | `type-safety-reviewer` |
+| npm imports, package.json | `dependency-reviewer` |
+| Tests, specs, describe/it blocks | `test-coverage-reviewer` |
+| LLM API calls (OpenAI, Anthropic) | `ai-code-reviewer` |
+| ARIA, disability, a11y | `accessibility-reviewer` |
+
+---
+
+## Review Output Format
+
+```
+━━━ Code Review — [filename or description] ━━━━━
+
+Logic Review:   ✅ APPROVED | ⚠️ [N] warnings | ❌ [N] critical
+Security:       ✅ APPROVED | ⚠️ [N] warnings | ❌ [N] critical
+
+━━━ Findings (sorted by severity) ━━━━━━━━━━━━━━
+
+[CRITICAL] [File:Line] [description] → [specific fix]
+[HIGH]     [File:Line] [description] → [specific fix]
+[MEDIUM]   [File:Line] [description] → [note]
+
+━━━ Verdict: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ APPROVED — code is production-ready
+⚠️ WARNINGS — [N] items to address before release
+❌ CRITICAL — [N] blockers must be resolved
+```
+
+---
+
+## What Each Reviewer Looks For
+
+### logic-reviewer
+- Methods called on wrong object types
+- Impossible states that will throw at runtime
+- Functions called before they're defined
+- Missing null checks on potentially-undefined values
+
+### security-auditor
+- SQL injection (string interpolation in queries)
+- XSS (user content in innerHTML or dangerouslySetInnerHTML)
+- JWT issues (no algorithm enforcement, weak secrets)
+- Auth order (business logic before auth check)
+- Hardcoded secrets
+
+---
+
+## Hallucination-Specific Checks
+
+The review specifically catches:
+
+```
+□ Methods imported from packages that don't export them
+□ React hooks that don't exist (fabricated hook names)
+□ Prisma methods removed in current version (findOne, upsertMany)
+□ Next.js 15 dynamic APIs used without await (cookies, headers, params)
+□ React 19 deprecated API usage (useFormState instead of useActionState)
+□ Parameters passed to LLM APIs that don't exist (max_length, format, memory)
+□ Model names that don't exist (gpt-5, claude-4, gemini-ultra)
+```
+
+---
+
+## Usage Examples
+
+```
+/review src/lib/auth.ts
+/review the entire src/app/api/checkout/ directory
+/review the PaymentForm component
+/review this code: [paste code inline]
+/review src/lib/ai-chat.ts for AI API hallucinations
+/review the last generated code before we write it to disk
+```

package/.agent/workflows/session.md

@@ -1,154 +1,94 @@
----
-description: Interactive session state tracking for multi-conversation context continuity.
----
-
-# /session — Interactive Session State Tracker
-
-Use this workflow to maintain context and track overarching goals across multiple single-chat sessions. It acts as a logbook that survives conversation resets.
-
----
-
-## When to Use This
-
-- Starting a long multi-session task (spanning multiple conversations)
-- Resuming work after a break — load the last checkpoint instantly
-- Tracking parallel workstreams (tag different sessions)
-- Exporting a summary of work for documentation or handoff
-
----
-
-## Commands
-
-```bash
-# ── Core commands ──────────────────────────────────────────────────
-
-# Save a checkpoint of the current session
-// turbo
-python .agent/scripts/session_manager.py save "working on auth middleware"
-
-# Load the current active session (note + tags)
-// turbo
-python .agent/scripts/session_manager.py load
-
-# Compact status overview: active session + last 3 checkpoints
-// turbo
-python .agent/scripts/session_manager.py status
-
-# View the last 10 session checkpoints
-// turbo
-python .agent/scripts/session_manager.py show
-
-# ── Tagging and filtering ─────────────────────────────────────────
-
-# Add a label/tag to the current session
-python .agent/scripts/session_manager.py tag <label>
-python .agent/scripts/session_manager.py tag v2-feature
-
-# ── History and export ────────────────────────────────────────────
-
-# Paginated list of ALL sessions (most recent first)
-python .agent/scripts/session_manager.py list
-python .agent/scripts/session_manager.py list --all   # show entire history
-
-# Export all sessions to session_export.md (or stdout)
-python .agent/scripts/session_manager.py export
-python .agent/scripts/session_manager.py export --stdout
-
-# Clear the session data entirely to start fresh
-python .agent/scripts/session_manager.py clear
-```
-
----
-
-## Command Reference
-
-| Command | Description |
-|---|---|
-| `save <note>` | Save a new session checkpoint with a note |
-| `load` | Display the current active session |
-| `status` | Compact 3-session status summary + active session |
-| `show` | Show the last 10 sessions |
-| `tag <label>` | Add a tag to the current session (e.g., `v2-feature`, `auth-sprint`) |
-| `list [--all]` | Paginated full session history |
-| `export [--stdout]` | Export all history to `session_export.md` |
-| `clear` | Delete the session state file entirely |
-
----
-
-## How It Works
-
-Session state is stored in `.agent_session.json` in the project root.
-
-**Start of a new conversation:** run `status` immediately to re-establish situational awareness:
-
-```
-python .agent/scripts/session_manager.py status
-```
-
-**When reaching a natural waypoint** (completed a task, switching context): run `save` with a descriptive note so the next session starts with full context.
-
-**Tags** group related sessions for filtering and export. Use them for features, sprints, or bugfix tracks.
-
----
-
-## Workflow Patterns
-
-**Starting a session:**
-```
-User:  /session save "Finished implementing JWT strategy. Next: user endpoints."
-Agent: ✅ Session saved: Finished implementing JWT strategy...
-       Session: #5, tagged: auth-sprint
-```
-
-**Resuming after a break:**
-```
-User:  /session status
-Agent: ━━━ Session Status ━━━━━━━━━━━━━━━━━━━━━━━━
-         Total sessions: 5
-         Active:         #5 — Finished implementing JWT strategy...
-
-         Last 3 sessions:
-           #5  2026-03-03T23:15  [auth-sprint]  Finished JWT strategy...
-           #4  2026-03-03T21:00  [auth-sprint]  Completed DB schema for auth...
-           #3  2026-03-03T18:30  [auth-sprint]  Set up project structure...
-```
-
-**Exporting for handoff or documentation:**
-```
-User:  /session export
-Agent: ✅ Exported 5 sessions to session_export.md
-```
-
----
-
-## Best Practices
-
-| Practice | Why |
-|---|---|
-| Save at every natural stopping point | Next session starts with accurate context |
-| Use descriptive notes with "Next:" | Gives future sessions a clear direction |
-| Tag sessions by feature or sprint | Makes export and filtering useful |
-| Run `status` at every session start | Reestablishes context without reading the full history |
-
----
-
-## Cross-Workflow Navigation
-
-| Use /session when... | Then go to... |
-|---|---|
-| Starting a multi-session task | `/plan` to write the formal plan for the work |
-| Resuming work on a feature | Load session, then continue with relevant workflow |
-| Work is complete, documenting it | `/changelog` to record what was built |
-
----
-
-## Usage
-
-```
-/session save "Finished JWT middleware. Next: protect API routes."
-/session status
-/session tag auth-sprint
-/session list
-/session export
-/session load
-```
+---
+description: Interactive session state tracking for multi-conversation context continuity. Saves and restores agent context across separate sessions so work can be resumed without losing progress.
+---
+
+# /session — Session State Management
+
+$ARGUMENTS
+
+---
+
+## Commands
+
+```
+/session save      → Save current session state to disk
+/session restore   → Restore most recent session
+/session status    → Show current session summary
+/session new       → Create a new session (archive current)
+/session list      → List all saved sessions
+```
+
+---
+
+## Execution
+
+```bash
+python .agent/scripts/session_manager.py save
+python .agent/scripts/session_manager.py restore
+python .agent/scripts/session_manager.py status
+python .agent/scripts/session_manager.py new
+python .agent/scripts/session_manager.py list
+```
+
+---
+
+## What Gets Saved
+
+```
+Session state includes:
+□ Current task.md content
+□ Summary of what was completed this session
+□ Open questions / blocked items
+□ Files modified in this session (from git status)
+□ Next planned actions
+```
+
+---
+
+## Session File Format
+
+```markdown
+# Session: [timestamp]
+
+## Completed This Session
+- [task item 1 — completed]
+- [task item 2 — completed]
+
+## In Progress
+- [task item 3 — started but not finished]
+
+## Blocked
+- [item] — blocked by [reason]
+
+## Files Modified
+- src/lib/auth.ts
+- src/app/api/users/route.ts
+
+## Next Session: Start With
+1. [first thing to do in the next session]
+2. [second thing]
+
+## Open Questions
+- [question 1]
+```
+
+---
+
+## When to Use /session
+
+```
+End of work session:   /session save → so next session can restore context
+Next work session:     /session restore → avoid re-explaining context
+Complex multi-day task: /session save between each work block
+Context handoff:       /session save → share session file with collaborator
+```
+
+---
+
+## Usage Examples
+
+```
+/session save   (at end of coding session)
+/session restore (at start of next coding session)
+/session status (check what was accomplished)
+```