tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/architecture/SKILL.md

@@ -1,200 +1,161 @@
----
-name: architecture
-description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Architecture Decision Framework
-
-> An architecture decision is only good until the constraints change.
-> Document the decision AND the reasoning — future teams need both.
-
----
-
-## When to Use This Skill
-
-- A new system, service, or major feature is being designed
-- An existing architecture is being evaluated for scaling, cost, or maintainability problems
-- A team disagrees on technical direction and needs a structured decision process
-- A decision needs to be documented so future engineers understand the "why"
-
----
-
-## The Decision Process
-
-Good architecture decisions follow a sequence. Skipping steps creates decisions that look good in a diagram and fail in production.
-
-### Phase 1 — Understand the Forces
-
-Before proposing anything, map what actually constrains the design:
-
-```
-Requirements:     What must this system do?
-Quality attributes: Speed, reliability, security, cost, maintainability — rank them
-Constraints:      Team size, existing tech, regulatory, budget
-Team context:     What does the team already know? What can they operate?
-```
-
-**The trap:** Jumping to technology before understanding quality attributes.
-If the top priority is "cheap to run" — that's a different answer than "sub-100ms response time."
-
-### Phase 2 — Generate Options
-
-Produce at least 2 real alternates. "We could do X, or we could not" is not a comparison.
-
-For each option document:
-- How it satisfies the top quality attributes
-- Where it falls short
-- Long-term operational cost (not just build cost)
-- Risk to the team given their current knowledge
-
-### Phase 3 — Evaluate Trade-offs
-
-Use a table:
-
-| Quality Attribute | Option A | Option B | Option C |
-|---|---|---|---|
-| Time to first delivery | ★★★ | ★★ | ★★★★ |
-| Operational complexity | Low | High | Medium |
-| Cost at 10x scale | $ | $$$ | $$ |
-
-The option with the most stars doesn't always win. **The one that best fits the top-priority attributes wins.**
-
-### Phase 4 — Document the Decision (ADR)
-
-Every significant architecture decision gets an ADR (Architecture Decision Record).
-
-```markdown
-# ADR-NNN: [Short title]
-
-## Status
-Accepted / Proposed / Deprecated / Superseded by ADR-NNN
-
-## Context
-[What situation or problem prompted this decision?]
-
-## Options Considered
-[Brief description of each option]
-
-## Decision
-[What was chosen and why]
-
-## Trade-offs Accepted
-[What downsides are being consciously accepted?]
-
-## Consequences
-[What becomes easier? What becomes harder?]
-```
-
----
-
-## File Index
-
-| File | Covers | When to Load |
-|---|---|---|
-| `context-discovery.md` | Questions to map requirements and constraints | Early in design |
-| `pattern-selection.md` | Monolith vs microservices, event-driven, CQRS, etc. | Choosing structural patterns |
-| `patterns-reference.md` | Reference descriptions of common patterns | Evaluating patterns |
-| `trade-off-analysis.md` | Scoring and comparison frameworks | Decision phase |
-| `examples.md` | Worked architecture examples | Concrete reference |
-
----
-
-## Anti-Patterns in Architecture Work
-
-| Pattern | Problem |
-|---|---|
-| Resume-driven architecture | Choosing tech because it's interesting, not because it fits |
-| Premature microservices | Splitting a monolith before the domain boundaries are known |
-| Ignoring operational cost | Systems that are brilliant to build and terrible to run |
-| No ADR | Decision rationale lost — future engineers repeat the same debates |
-| One option considered | Not an evaluation, just a justification |
-
----
-
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
-
-```
-━━━ Architecture Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
-```
-
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/brainstorm` or `/plan`**
-**Active reviewers: `project-planner` · `logic-reviewer`**
-
-### ❌ Forbidden AI Tropes in Architecture
-
-1. **Defaulting to Microservices** — never recommend Microservices for a new or small project without explicit scale requirements. Monolith first.
-2. **Over-engineering with CQRS/Event Sourcing** — do not suggest complex distributed patterns unless the domain demands it.
-3. **Assuming AWS/Cloud Provider** — ask where the user deploys, do not hallucinate AWS services as the default solution.
-4. **Ignoring Operational Cost** — do not recommend architectures that require dedicated DevOps teams if the user is a solo developer.
-5. **Failing to Document Trade-offs** — every architecture decision has a downside. Never present a "perfect" solution.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before proposing an architecture:
-```
-✅ Did I start with the simplest architecture that satisfies the constraints?
-✅ Did I explicitly document the downsides (cost, complexity, maintainability) of my proposal?
-✅ Is my proposal grounded in the user's actual constraints (team size, budget, timeline)?
-✅ Did I ask about the read/write ratio and data shape before choosing a database?
-✅ Is my solution resilient to partial failures?
-```
-
-
----
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+---
+name: architecture
+description: Software architecture mastery. System design patterns, clean architecture, hexagonal/ports-and-adapters, event-driven architecture, microservices vs monolith decision framework, CQRS, domain-driven design, Architecture Decision Records (ADRs), and scalability patterns. Use when making architecture decisions, designing systems, or documenting technical decisions.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 3.1.0
+last-updated: 2026-04-07
+applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
+---
+
+# Architecture — System Design Mastery
+
+## Architecture Selection
+
+```
+Team size?           Scale?                  Cadence?
+1–5   → Monolith     <10K RPM  → Monolith     Weekly → Monolith
+5–20  → Mod. Mono    <100K RPM → Mono+CDN     Daily  → Modular Mono
+20+   → Microsvcs    >100K RPM → Microsvcs    Per-svc → Microsvcs
+
+❌ Microservices are NOT inherently better.
+   A well-structured monolith beats a poorly designed microservice system.
+   Start monolith. Extract services only when proven necessary.
+```
+
+**3 Questions Before Any Pattern:**
+1. What SPECIFIC problem does this pattern solve?
+2. Is there a simpler solution?
+3. Can we add this LATER when proven needed?
+
+---
+
+## Clean Architecture (Dependency Rule)
+
+```
+Presentation → Application → Domain ← Infrastructure
+              (Controllers)  (Use Cases)  (Entities)  (DB, APIs)
+
+Dependency Rule: arrows point INWARD. Domain knows NOTHING about infra.
+Application defines interfaces (ports). Infrastructure implements them (adapters).
+```
+
+```typescript
+// Domain — pure business logic, zero external dependencies
+interface UserRepository { findById(id: string): Promise<User | null>; }
+class User {
+  promote(): void {
+    if (this._role === UserRole.ADMIN) throw new DomainError("Already admin");
+    this._role = UserRole.ADMIN;
+  }
+}
+
+// Application — orchestrates use cases
+class PromoteUserUseCase {
+  async execute(userId: string): Promise<void> {
+    const user = await this.userRepo.findById(userId);
+    if (!user) throw new NotFoundError("User", userId);
+    user.promote();
+    await this.userRepo.save(user);
+    await this.eventBus.publish(new UserPromotedEvent(userId));
+  }
+}
+
+// Infrastructure — concrete implementations of ports
+class PostgresUserRepository implements UserRepository {
+  async findById(id: string) { /* db.query(...) */ }
+}
+```
+
+---
+
+## CQRS
+
+```
+Commands (Write) → Normalized Write DB
+Queries  (Read)  → Denormalized/Cached Read Model
+
+When to use:  ✅ Read/write patterns diverge  ✅ 10:1+ read:write ratio  ✅ Event sourcing
+When NOT to:  ❌ Simple CRUD  ❌ Team < 3 devs  ❌ Read/write models are identical
+```
+
+---
+
+## Event-Driven Architecture
+
+```
+Event Types:
+  Domain Events      → "OrderPlaced" within a bounded context
+  Integration Events → Cross-service via message queue
+  Notification Events → Fire-and-forget (logging, analytics)
+
+Broker Selection:
+  BullMQ / Redis Streams → Simple, single-service queues
+  RabbitMQ               → Complex routing, dead-letter queues
+  Apache Kafka           → High throughput, replay, event log
+  AWS SQS/SNS            → Managed, serverless-friendly
+
+Outbox Pattern (reliable publishing):
+  1. Save entity + event in ONE DB transaction
+  2. Background worker polls outbox → publishes to broker
+  3. Mark as published → guarantees at-least-once delivery
+```
+
+---
+
+## Anti-Patterns Reference
+
+| Pattern | When it's an Anti-Pattern | Simpler Alternative |
+|---------|--------------------------|---------------------|
+| Microservices | Before team or scale justifies it | Modular monolith |
+| Clean/Hexagonal | Over-abstraction for simple CRUD | Concrete first, interfaces later |
+| Event Sourcing | No business requirement for audit/replay | Append-only audit log |
+| CQRS | Simple data model, no read/write divergence | Single model |
+| Repository | Simple CRUD, single database | ORM direct access |
+
+---
+
+## Architecture Decision Records (ADRs)
+
+```markdown
+## ADR-001: [Decision Title]
+**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+
+**Context:** [Problem + constraints: team, scale, timeline]
+
+**Decision:** [What was chosen — be specific]
+
+**Rationale:** [Why — tied to requirements]
+
+**Trade-offs:** [What we consciously give up]
+
+**Consequences:**
+- Positive: [Benefits]
+- Negative: [Costs/Risks]
+- Mitigation: [How to address negatives]
+
+**Revisit when:** [Trigger conditions]
+```
+
+ADR storage: `docs/architecture/adr-001-title.md`
+
+---
+
+## Scalability Patterns
+
+```
+Read scaling:   Redis cache → Read replicas → CDN for static assets
+Write scaling:  Queue writes → Partition data → Event sourcing
+Stateless:      Sessions in Redis → JWT → No server affinity
+DB scaling:     Connection pooling → Read replicas → Partitioning → Sharding (last resort)
+Cache layers:   L1: In-memory (process) L2: Redis (shared) L3: CDN (edge)
+```
+
+## Scale-to-Architecture Matrix
+
+```
+                MVP           SaaS          Enterprise
+Scale:          <1K           1K–100K       100K+
+Team:           Solo          2–10          10+
+Architecture:   Simple Mono   Modular Mono  Distributed
+Framework:      Next.js API   NestJS        Microservices
+```

package/.agent/skills/authentication-best-practices/SKILL.md

@@ -1,72 +1,139 @@
----
-name: authentication-best-practices
-description: Authentication and Identity Management expert. Specializes in JWTs, OIDC, HTTP-Only Cookies, and secure password hashing.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-30
-applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
----
-
-# Authentication & Session Best Practices
-
-You are an Identity and Access Management (IAM) Specialist. You are strictly forbidden from writing custom cryptography or insecure authentication flows.
-
-## Core Directives
-
-1. **Token Storage & JWTs:**
-   - Never store JWTs or session tokens in `localStorage` or `sessionStorage` where they are vulnerable to XSS.
-   - Always issue access tokens as `Secure, HttpOnly, SameSite=Strict/Lax` browser cookies.
-   - When verifying JWTs, always explicitly define the `algorithms` array (e.g., `['HS256']`) to prevent algorithm confusion attacks where the attacker sets `alg: none`.
-
-2. **Password Hashing:**
-   - Never write a custom hashing algorithm.
-   - If managing raw passwords, use `Argon2id` or `Bcrypt` with a sufficient work factor (e.g., 10-12 rounds salt). 
-   - Never log passwords, tokens, or PII to the standard `stdout` or custom loggers.
-
-3. **Session Revocation:**
-   - JWTs scale well but cannot be instantly revoked without a denylist. If instant revocation or device management is required, default to opaque, stateful session tokens backed by Redis or an equivalent fast KV store.
-
-## Execution
-Review identity handling mechanisms forcefully. If you catch an agent or a user attempting to place a secret in client-side code, throw a high-level alert and immediately rewrite the architecture to utilize backend-for-frontend (BFF) proxying or HttpOnly cookes.
+---
+name: authentication-best-practices
+description: Authentication and Authorization mastery. Best practices for OAuth2, OpenID Connect, JWT (JSON Web Tokens), session management, password hashing, MFA (Multi-Factor Authentication), RBAC/ABAC, SSO, and secure credential storage. Use when auditing or implementing login flows, identity systems, or access control.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
 
+# Authentication & Authorization — Identity Mastery
 
 ---
 
-## 🤖 LLM-Specific Traps
+## Passwords & Hashing
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+```typescript
+// ❌ BAD: md5, sha1, sha256 (too fast, vulnerable to brute force/rainbow tables)
+const hash = crypto.createHash('sha256').update(password).digest('hex');
 
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+// ✅ GOOD: Argon2 (memory-hard, ASIC resistant) or bcrypt
+import * as argon2 from "argon2";
+
+async function hashPassword(password: string): Promise<string> {
+  // Argon2 hashes include the salt inherently in the resulting string
+  return await argon2.hash(password, {
+    type: argon2.argon2id, // recommended variant
+    memoryCost: 2 ** 16,   // 64 MB
+    timeCost: 3,           // iterations
+    parallelism: 1,        // threads
+  });
+}
+
+async function verifyPassword(hash: string, password: string): Promise<boolean> {
+  return await argon2.verify(hash, password);
+}
+```
+
+### Password Policies
+- **Length over complexity**: Require minimum 12 characters. Stop requiring arbitrary symbols (e.g., `!@#`).
+- **Check against breaches**: Use HaveIBeenPwned API or similar to reject compromised passwords during signup.
+- **Never expire passwords arbitrarily**: Only force resets if there is evidence of a breach.
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+## Session Management vs. JWT
 
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
+### 1. Stateful Sessions (Cookies)
+**Best for**: Monolithic web apps, SSR apps (Next.js, Remix).
+- Server stores session ID mapped to user data in Redis/DB.
+- Client stores session ID in an `HttpOnly`, `Secure`, `SameSite=Lax/Strict` cookie.
+- **Pros**: Immediate revocation, server-side truth, invisible to XSS.
+- **Cons**: Requires DB lookup per request.
 
-### ❌ Forbidden AI Tropes
+### 2. Stateless JWT (JSON Web Tokens)
+**Best for**: Distributed APIs, Microservices, Native mobile apps.
+- Server signs a token containing user claims.
+- Client passes it in `Authorization: Bearer <token>` header.
+- **Pros**: No DB lookup needed, easy cross-origin sharing.
+- **Cons**: Cannot be easily revoked before expiration.
 
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+### The JWT "Refresh Token" Pattern
+```typescript
+// Scenario: API authentication
+// 1. Access Token (Short-lived: 15 mins)
+const accessToken = jwt.sign({ userId: user.id }, JWT_SECRET, {
+  expiresIn: "15m",
+  algorithm: "HS256" // ALWAYS explicitly specify
+});
+// 2. Refresh Token (Long-lived: 7 days, opaque string in DB)
+const refreshToken = crypto.randomBytes(40).toString('hex');
+await db.refreshTokens.create({ token: refreshToken, userId: user.id, expires: addDays(7) });
 
-### ✅ Pre-Flight Self-Audit
+// Client flow:
+// - Access token kept in memory (JS variable) to prevent XSS theft.
+// - Refresh token kept in HttpOnly cookie.
+// - When Access Token expires, endpoint reads cookie, validates DB, issues new Access Token.
+```
+
+---
+
+## OAuth2 & OIDC (OpenID Connect)
 
-Review these questions before confirming output:
 ```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
+Roles:
+1. Resource Owner (User)
+2. Client (Your App)
+3. Authorization Server (Google/GitHub/Auth0)
+4. Resource Server (API)
+
+Flow (Authorization Code + PKCE):
+1. User clicks "Login with Google".
+2. App generates `code_verifier` and `code_challenge`.
+3. App redirects user to Google with `code_challenge`.
+4. User logs in, Google redirects back to App with an authorization `code`.
+5. App sends `code` + `code_verifier` to Google backend.
+6. Google returns `id_token` (OIDC identity) and `access_token` (OAuth permissions).
+
+// ❌ HALLUCINATION TRAP: Implicit Flow is deprecated.
+// Never use Implicit Flow (response_type=token) where the token is returned in the URL hash.
+// Always use Authorization Code Flow with PKCE, even for Single Page Apps (SPAs).
 ```
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
+---
 
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+## Multi-Factor Authentication (MFA)
+
+- **SMS**: Deprecated by NIST due to SIM swapping vulnerabilities. (Better than nothing, but avoid as primary MFA).
+- **TOTP (Authenticator Apps)**: Standard implementations use HMAC-SHA1. Keep the secret key heavily encrypted at rest.
+- **WebAuthn / Passkeys**: The modern gold standard. Replaces passwords entirely using hardware enclaves (FaceID, TouchID, YubiKey).
+
+---
+
+## Authorization Models
+
+### RBAC (Role-Based Access Control)
+- Users have Roles (`admin`, `editor`, `viewer`).
+- Roles have Permissions (`create:post`, `delete:user`).
+
+```typescript
+// ✅ Check permissions, not roles directly (more flexible)
+if (!user.permissions.includes("delete:user")) {
+  throw new ForbiddenError();
+}
+```
+
+### ABAC (Attribute-Based Access Control)
+- Access based on context (e.g., "User can edit Document if Document.department == User.department").
+
+```typescript
+// Example Policy
+function canEditPost(user: User, post: Post): boolean {
+  if (user.role === "admin") return true;
+  if (post.authorId === user.id) return true;
+  if (post.status === "draft" && user.department === "content") return true;
+  return false;
+}
+```
+
+---