prism-pr 1.0.0-alpha.47

package/README.md

@@ -0,0 +1,964 @@
+# PRISM-CLI
+
+Intelligent Pull Request review orchestrator for Bitbucket. Automates code reviews using AI multi-agent architecture with a TUI-first interactive experience.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Authentication Setup](#authentication-setup)
+- [Usage](#usage)
+- [Architecture Overview](#architecture-overview)
+- [Data Flow](#data-flow)
+- [AI Agent System](#ai-agent-system)
+- [Configuration](#configuration)
+- [Project Structure](#project-structure)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start
+
+```bash
+# 1. Clone and install
+git clone <repo-url>
+cd prism-cli
+pnpm install
+
+# 2. Build
+pnpm build
+
+# 3. Run
+pnpm start        # or: node bin/run.js
+```
+
+On first launch, PRISM opens an interactive TUI that guides you through login, workspace selection, and PR review.
+
+---
+
+## Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | >= 20.0.0 | Required for ESM + crypto APIs |
+| pnpm | Latest | Package manager |
+| Bitbucket API Token | - | See [Authentication Setup](#authentication-setup) |
+| AI Provider | - | Claude Code CLI (default) or Anthropic API key |
+
+### AI Provider Options
+
+| Provider | Setup | Cost |
+|----------|-------|------|
+| **Claude Code** (default) | No extra config needed — uses your local Claude Code CLI | Included in Claude Code subscription |
+| **Anthropic API** | Set `ANTHROPIC_API_KEY` env var or in `config.json` | Pay-per-token |
+
+---
+
+## Installation
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build (TypeScript → dist/ + migrations + oclif manifest)
+pnpm build
+
+# Verify
+pnpm test          # Run all 1210 tests
+```
+
+### Build Pipeline
+
+```
+pnpm build
+  └── tsc -b                          # TypeScript compilation
+  └── postbuild:
+      ├── copyfiles migrations → dist/  # SQLite migration files
+      ├── copyfiles prompts → dist/     # Agent prompt templates
+      └── oclif manifest                # Command discovery manifest
+```
+
+---
+
+## Authentication Setup
+
+PRISM uses Bitbucket API tokens for authentication.
+
+### Step 1: Create an API Token
+
+1. Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Create an **"API token with scopes"** (NOT a simple API token)
+3. Create an App with these scopes:
+
+| Scope | Access | Purpose |
+|-------|--------|---------|
+| `read:user:bitbucket` | Read | Validate credentials (`GET /2.0/user`) |
+| `read:workspace:bitbucket` | Read | Access workspace info |
+| `read:repository:bitbucket` | Read | List repos, fetch file content (stack detection) |
+| `read:pullrequest:bitbucket` | Read | Fetch PR metadata, diffs, and comments |
+| `write:pullrequest:bitbucket` | Write | Publish inline review comments |
+
+### Step 2: Login via PRISM
+
+On first launch, the TUI shows a login screen:
+
+```
+  Username:  your-email@example.com
+  API Token: ****************************
+```
+
+- **Username**: Your Bitbucket email (the one you log in with)
+- **API Token**: The token created in Step 1
+
+Credentials are encrypted (AES-256-GCM) and stored locally. Never transmitted anywhere except Bitbucket API.
+
+### Credential Storage
+
+| Platform | Location |
+|----------|----------|
+| Windows | `%APPDATA%\prism-cli\credentials.json` |
+| macOS | `~/.config/prism-cli/credentials.json` |
+| Linux | `~/.config/prism-cli/credentials.json` |
+
+---
+
+## Usage
+
+### Interactive Mode (Default)
+
+```bash
+prism               # Launch TUI
+```
+
+The TUI guides you through:
+
+```
+Login  -->  Workspace  -->  Repository  -->  PR  -->  Agents  -->  Review  -->  Publish
+```
+
+### Command Mode
+
+```bash
+prism login                            # Authenticate
+prism logout                           # Clear credentials
+prism review start --pr <id>           # Start review for a specific PR
+```
+
+---
+
+## Architecture Overview
+
+PRISM is organized in 5 horizontal layers. Each layer only depends on the layers below it.
+
+### Layer Diagram
+
+```
+ ===================================================================
+  TERMINAL EXPERIENCE                          src/tui/, src/commands/
+ -------------------------------------------------------------------
+  TUI Screens (Ink/React)   Screen Router      TUI State (useReducer)
+  14 interactive screens     navigation map     auth, selection, review
+ ===================================================================
+                               |
+                               v
+ ===================================================================
+  APPLICATION CORE                                        src/core/
+ -------------------------------------------------------------------
+  Workflow Engine          Session Manager       Comment Publisher
+  16-step orchestration    SQLite CRUD           BB inline comments
+  coordinates all layers   review sessions       rate-limit handling
+ ===================================================================
+                               |
+                               v
+ ===================================================================
+  AI ORCHESTRATION                                  src/ai/
+ -------------------------------------------------------------------
+  Review Orchestrator ──> Rule-Based Strategy ──> Context Analyzer
+  sequential dispatch     agent plan builder      file + stack analysis
+                               |
+              Agent Registry (7 agents, sequential execution)
+     ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┐
+     │  TS  │ SEC  │ CSS  │  C#  │ ARCH │ TEST │ PERF │
+     └──────┴──────┴──────┴──────┴──────┴──────┴──────┘
+  Deduplicator             Consolidation         Skill Registry
+  vs existing comments     merge multi-agent     per-agent instructions
+ ===================================================================
+                               |
+                               v
+ ===================================================================
+  INTEGRATION                          src/bitbucket/, src/stack-detector/
+ -------------------------------------------------------------------
+  Bitbucket Client         Stack Detector        Engram Client
+  REST API (auth, PRs,     8 manifest parsers    cross-session memory
+  diffs, comments)         + AI fallback         prior reviews + context
+ ===================================================================
+                               |
+                               v
+ ===================================================================
+  PERSISTENCE                          src/persistence/, src/config/
+ -------------------------------------------------------------------
+  SQLite + Drizzle ORM     Credential Manager    Config Manager
+  sessions, findings,      AES-256-GCM           provider resolution
+  profiles, workspaces     encrypted storage     global + per-repo
+ ===================================================================
+```
+
+### Component Summary
+
+| Layer | Key Components | Technology |
+|-------|---------------|------------|
+| **Terminal** | 14 TUI screens, screen router, state management | Ink v5, React 18, oclif v4 |
+| **Core** | 16-step workflow engine, session tracking, comment publishing | Custom orchestration |
+| **AI** | 7 specialized agents, strategy-based selection, dedup pipeline | Anthropic SDK, Zod |
+| **Integration** | Bitbucket REST client, manifest-based stack detection, memory | fetch, Engram HTTP |
+| **Persistence** | SQLite (WAL), encrypted credentials, JSON config | better-sqlite3, Drizzle |
+
+---
+
+## Data Flow
+
+### Complete Workflow: Input to Output
+
+```
+                        ┌─────────────┐
+                        │   USER      │
+                        │   launches  │
+                        │   prism     │
+                        └──────┬──────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │   AUTHENTICATION    │
+                    │                      │
+                    │  credentials.json    │
+                    │  ──decrypt──►        │
+                    │  GET /2.0/user       │
+                    │  ──validate──►       │
+                    └──────────┬──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │   SELECTION         │
+                    │                      │
+                    │  Workspace (SQLite)  │
+                    │       ▼              │
+                    │  Repos (BB API)      │
+                    │       ▼              │
+                    │  Open PRs (BB API)   │
+                    │       ▼              │
+                    │  Agents (checkbox)   │
+                    └──────────┬──────────┘
+                               │
+          ┌────────────────────▼────────────────────┐
+          │          WORKFLOW ENGINE (16 steps)       │
+          │                                           │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 1: Fetch PR metadata            │ │
+          │  │   GET /pullrequests/{id}             │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 2: Fetch existing BB comments   │ │
+          │  │   GET /pullrequests/{id}/comments    │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 2b: Comment integrity check     │ │
+          │  │   Compare DB findings vs live BB     │ │
+          │  │   comments → detect deleted ones     │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 4: Fetch raw unified diff       │ │
+          │  │   GET /pullrequests/{id}/diff        │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 5: Load prior review memory     │ │
+          │  │   Engram: search prior findings      │ │
+          │  │   Engram: get project context        │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 4b: Load conventions            │ │
+          │  │   From prism.yaml or inline config   │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 4c: Detect tech stack           │ │
+          │  │                                       │ │
+          │  │  ┌──────────────────────────┐        │ │
+          │  │  │ 1. Check SQLite cache     │        │ │
+          │  │  └─────────┬────────────────┘        │ │
+          │  │            ▼                          │ │
+          │  │  ┌──────────────────────────┐        │ │
+          │  │  │ 2. Fetch manifests from   │        │ │
+          │  │  │    BB source API          │        │ │
+          │  │  │    (package.json, go.mod, │        │ │
+          │  │  │     Cargo.toml, etc.)     │        │ │
+          │  │  └─────────┬────────────────┘        │ │
+          │  │            ▼                          │ │
+          │  │  ┌──────────────────────────┐        │ │
+          │  │  │ 3. Parse → StackProfile   │        │ │
+          │  │  │    {framework, runtime,   │        │ │
+          │  │  │     language, libraries}  │        │ │
+          │  │  └─────────┬────────────────┘        │ │
+          │  │            ▼                          │ │
+          │  │  ┌──────────────────────────┐        │ │
+          │  │  │ 4. AI fallback (haiku)    │        │ │
+          │  │  │    if manifests missing   │        │ │
+          │  │  └─────────┬────────────────┘        │ │
+          │  │            ▼                          │ │
+          │  │  ┌──────────────────────────┐        │ │
+          │  │  │ 5. Merge + cache in       │        │ │
+          │  │  │    SQLite                 │        │ │
+          │  │  └──────────────────────────┘        │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 6: Parse diff → DiffFile[]      │ │
+          │  │   Filter excluded patterns           │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 6b: Cost estimation             │ │
+          │  │   chars × agents × provider rate     │ │
+          │  │   Warn if >5000 lines or >$5         │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          │  ┌─────────────────────────────────────┐ │
+          │  │ Step 7: Create DB session            │ │
+          │  │   SessionManager → SQLite            │ │
+          │  └──────────────┬──────────────────────┘ │
+          │                 ▼                         │
+          └─────────────────┬───────────────────────┘
+                            │
+       ┌────────────────────▼────────────────────┐
+       │       AI ORCHESTRATION (Step 9)          │
+       │                                           │
+       │  ┌─────────────────────────────────────┐ │
+       │  │ Agent Selection (RuleBasedStrategy)  │ │
+       │  │                                       │ │
+       │  │  Priority chain:                      │ │
+       │  │  1. config.agents (explicit override) │ │
+       │  │  2. context ∪ stack (merged)          │ │
+       │  │  3. context-only (fallback)           │ │
+       │  │                                       │ │
+       │  │  Context: file extensions in diff     │ │
+       │  │  Stack:   framework/library rules     │ │
+       │  └──────────────┬──────────────────────┘ │
+       │                 ▼                         │
+       │  ┌─────────────────────────────────────┐ │
+       │  │ Sequential Agent Execution           │ │
+       │  │                                       │ │
+       │  │  For each selected agent:             │ │
+       │  │  ┌───────────────────────────────┐   │ │
+       │  │  │ 1. Filter files by fileFilter  │   │ │
+       │  │  │ 2. Load skills for agent       │   │ │
+       │  │  │ 3. Build system prompt:        │   │ │
+       │  │  │    base + context + conventions│   │ │
+       │  │  │    + skills + stack profile    │   │ │
+       │  │  │    + framework rules (auto +   │   │ │
+       │  │  │      repo reviewRules)         │   │ │
+       │  │  │ 4. Format diff as user content │   │ │
+       │  │  │    with [L{line}] annotations  │   │ │
+       │  │  │ 5. Call AI provider            │   │ │
+       │  │  │    (tool_use: report_findings) │   │ │
+       │  │  │ 6. Validate findings via Zod   │   │ │
+       │  │  │ 7. Check line numbers vs diff  │   │ │
+       │  │  └───────────────────────────────┘   │ │
+       │  └──────────────┬──────────────────────┘ │
+       │                 ▼                         │
+       │  ┌─────────────────────────────────────┐ │
+       │  │ Post-Processing                      │ │
+       │  │                                       │ │
+       │  │  1. Consolidate (same loc+category    │ │
+       │  │     → keep highest severity)          │ │
+       │  │  2. Deduplicate vs existing BB        │ │
+       │  │     comments + prior Engram findings  │ │
+       │  │  3. Sort: severity → file → line      │ │
+       │  └──────────────┬──────────────────────┘ │
+       │                 │                         │
+       │  Output: ReviewFinding[]                  │
+       │  + agentResults[] + totalUsage            │
+       └─────────────────┬───────────────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    HUMAN REVIEW (TUI)       │
+          │                              │
+          │  Findings grouped by file    │
+          │  Severity badges:            │
+          │   [CRITICAL] [HIGH] [MED]   │
+          │                              │
+          │  Navigate: arrows + Enter    │
+          │  Publish:  'p' key           │
+          └──────────────┬──────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    PUBLISH FLOW             │
+          │                              │
+          │  Confirm: y/n               │
+          │       ▼                      │
+          │  For each finding:           │
+          │   1. Format as markdown      │
+          │   2. POST /comments          │
+          │      {inline: {path, line}}  │
+          │   3. 500ms rate limit delay  │
+          │   4. Store BB comment ID     │
+          │       ▼                      │
+          │  Save to Engram memory       │
+          │  Update SQLite session       │
+          └──────────────┬──────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    OUTPUT                    │
+          │                              │
+          │  Published:  X comments      │
+          │  Skipped:    Y               │
+          │  Failed:     Z               │
+          │  Cost:       $0.XX           │
+          │  Session:    #abc123         │
+          │                              │
+          │  → Inline comments now       │
+          │    visible on Bitbucket PR   │
+          └─────────────────────────────┘
+```
+
+### Agent Selection Detail
+
+```
+                  ┌─────────────┐     ┌──────────────────┐
+                  │  Diff Files  │     │  Stack Profile    │
+                  │  (.ts, .css, │     │  {framework:      │
+                  │   .yaml ...) │     │   "angular",      │
+                  └──────┬──────┘     │   keyLibraries:   │
+                         │             │   ["rxjs"]}       │
+                         ▼             └────────┬─────────┘
+              ┌──────────────────┐              │
+              │ analyzeContext() │              │
+              │ File extensions  │              ▼
+              │ → DetectedContext│    ┌──────────────────────┐
+              └────────┬────────┘    │ getStackAwareAgents() │
+                       │              │ Framework rules:      │
+                       │              │  angular → ts + arch  │
+                       │              │  react   → ts         │
+                       │              │  dotnet  → cs + sec   │
+                       │              │ Library rules:        │
+                       │              │  rxjs    → perf       │
+                       │              │  prisma  → sec + perf │
+                       ▼              └────────┬─────────────┘
+              ┌──────────────────┐             │
+              │getRecommendedA-  │             │
+              │gents() by ext:   │             │
+              │  .ts → ts-rev    │             │
+              │  .css → css-rev  │             │
+              │  .cs → cs-rev    │             │
+              │  always: sec-rev │             │
+              └────────┬────────┘             │
+                       │                       │
+                       └───────┬───────────────┘
+                               ▼
+                    ┌─────────────────────┐
+                    │  resolveAgentIds()   │
+                    │                      │
+                    │  Priority:           │
+                    │  1. config.agents    │
+                    │     (absolute)       │
+                    │  2. context ∪ stack  │
+                    │     (merged Set)     │
+                    │  3. context-only     │
+                    │     (no stack)       │
+                    └──────────┬──────────┘
+                               │
+                               ▼
+                    ┌─────────────────────┐
+                    │  Selected Agents     │
+                    │  [ts, sec, arch,     │
+                    │   perf]              │
+                    └─────────────────────┘
+```
+
+### Screen Navigation Map
+
+```
+┌──────────┐   no creds   ┌──────────┐
+│ Welcome  │─────────────►│  Login   │
+│ Screen   │              │  Screen  │
+└────┬─────┘              └────┬─────┘
+     │ valid                   │ saved
+     ▼                         ▼
+┌──────────────────────────────────────┐
+│            Home Screen                │
+│  [Start Review]  [Past Sessions]     │
+└────┬────────────────────┬────────────┘
+     │                    │
+     ▼                    ▼
+┌──────────┐       ┌─────────────┐
+│Workspace │       │  Session    │
+│ Select   │       │  List       │
+└────┬─────┘       └─────────────┘
+     │
+     ▼
+┌──────────┐
+│  Repo    │  Search + project groups
+│  Select  │
+└────┬─────┘
+     │
+     ▼
+┌──────────┐
+│  PR List │  Search by id/title/author
+└────┬─────┘
+     │
+     ▼
+┌──────────┐
+│  Agent   │  Checkboxes, Space to toggle
+│  Select  │
+└────┬─────┘
+     │ Enter
+     ▼
+┌──────────┐  integrity  ┌─────────────┐
+│ Review   │────────────►│  Integrity  │
+│ Running  │◄────────────│  Report     │
+└────┬─────┘  key press  └─────────────┘
+     │ findings ready
+     ▼
+┌──────────┐
+│ Findings │  Navigate, view detail
+│  List    │
+└────┬─────┘
+     │ 'p' key
+     ▼
+┌──────────┐
+│ Publish  │  y = publish, n = draft
+│ Confirm  │
+└────┬─────┘
+     │ 'y'
+     ▼
+┌──────────┐
+│Publishing│  Progress bar per comment
+│  Screen  │
+└────┬─────┘
+     │ complete + key press
+     ▼
+┌──────────┐
+│  Report  │  Stats + cost → Home
+└──────────┘
+```
+
+---
+
+## AI Agent System
+
+### Registered Agents
+
+| Agent | ID | Handles | Trigger |
+|-------|----|---------|---------|
+| TypeScript | `ts-reviewer` | `.ts .tsx .js .jsx` | TS/JS files in diff |
+| Security | `security-reviewer` | All files | Always runs |
+| CSS | `css-reviewer` | `.css .scss .sass .less` | Style files in diff |
+| C# | `csharp-reviewer` | `.cs` | C# files in diff or .NET stack |
+| Architecture | `architecture-reviewer` | All files | 5+ files or 2+ languages |
+| Testing | `testing-reviewer` | `*.test.* *.spec.*` | Test files in diff |
+| Performance | `performance-reviewer` | All files | 300+ lines or 8+ files |
+
+### Stack-Aware Selection Rules
+
+When a `StackProfile` is detected from the project's manifest files:
+
+| Framework / Library | Extra Agents Added |
+|--------------------|--------------------|
+| Angular | ts-reviewer + architecture-reviewer |
+| React / Next.js / Vue | ts-reviewer |
+| .NET / ASP.NET | csharp-reviewer + security-reviewer |
+| NestJS | ts-reviewer + security-reviewer + architecture-reviewer |
+| Express / Fastify | security-reviewer |
+| Django / Flask / FastAPI | security-reviewer |
+| rxjs / ngrx | performance-reviewer |
+| ORMs (Prisma, Drizzle, TypeORM, EF) | security-reviewer + performance-reviewer |
+
+### Finding Schema
+
+Each agent produces findings with this structure:
+
+```typescript
+{
+  filePath: string          // File in the diff
+  lineNumber: number        // Must be an actual addition line
+  severity: 'critical' | 'high' | 'medium' | 'low' | 'info'
+  category: 'bug' | 'security' | 'performance' | 'style' | 'maintainability'
+           | 'accessibility' | 'testing' | 'architecture' | 'documentation' | 'other'
+  title: string             // Short description (max 100 chars)
+  problem: string           // What's wrong
+  rationale: string         // Why it matters
+  suggestion: string        // How to fix it
+  agentId: string           // Which agent produced this
+}
+```
+
+### Framework Context Auto-Injection
+
+When a `StackProfile` is detected, PRISM automatically injects a framework context block into each relevant agent's prompt. The `FRAMEWORK_AGENT_MAP` controls which agents receive context for each framework:
+
+| Framework | Agents that receive context |
+|-----------|----------------------------|
+| Angular | ts-reviewer, architecture-reviewer, html-reviewer |
+| React / Next.js | ts-reviewer |
+| Vue / Nuxt | ts-reviewer, html-reviewer |
+| NestJS | ts-reviewer, architecture-reviewer, security-reviewer |
+| Laravel | security-reviewer |
+| .NET / .NET Framework | csharp-reviewer, security-reviewer |
+
+The injected block looks like:
+
+```
+## Framework-Specific Review Rules
+Framework: Angular
+Version: ^17.3.0
+Key libraries: RxJS, NgRx
+```
+
+Custom `reviewRules` defined in `.prism.yml` are merged after the auto-detected framework context. They are agent-scoped: each entry targets one agent by ID and appends free-form instructions to that agent's prompt.
+
+**Source files:**
+- `src/ai/agents/framework-rules/normalize.ts` — framework name normalization + version extraction
+- `src/ai/agents/framework-rules/routing-map.ts` — `FRAMEWORK_AGENT_MAP`
+- `src/ai/agents/framework-rules/index.ts` — `resolveFrameworkRules()` merges auto context + repo rules
+
+### Post-Processing Pipeline
+
+```
+Raw Findings (all agents)
+    │
+    ▼
+Consolidation: same file+line+category → keep highest severity
+    │
+    ▼
+Deduplication: remove findings matching existing BB comments or prior Engram reviews
+    │
+    ▼
+Sort: severity (critical→info) → filePath (A→Z) → lineNumber (asc)
+    │
+    ▼
+Final ReviewFinding[] → presented to user
+```
+
+---
+
+## Configuration
+
+### Global Config (`config.json`)
+
+Auto-created in platform config directory.
+
+```json
+{
+  "defaultModel": "claude-opus-4-5",
+  "maxDiffLines": 5000,
+  "engramUrl": "http://localhost:7437",
+  "provider": "claude-code"
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `defaultModel` | `claude-opus-4-5` | AI model for all agents |
+| `maxDiffLines` | `5000` | Lines before cost warning |
+| `engramUrl` | `http://localhost:7437` | Engram memory server |
+| `provider` | auto-detect | `anthropic` or `claude-code` |
+| `anthropicApiKey` | - | Inline API key (alternative to env var) |
+
+### Per-Repo Config (`prism.yaml`)
+
+Place in the repository's working directory to customize reviews for that repo.
+
+```yaml
+# Override which agents run (bypasses auto-detection)
+agents:
+  - ts-reviewer
+  - security-reviewer
+
+# Model override for this repo
+model: claude-sonnet-4-5-20250514
+
+# Coding conventions injected into agent prompts
+conventions:
+  - "Use functional components with hooks, no class components"
+  - "All API calls must go through the service layer"
+
+# Or load from a file
+conventionsFile: .github/conventions.md
+
+# Files to skip during review
+excludePatterns:
+  - "**/*.generated.ts"
+  - "dist/**"
+  - "*.lock"
+
+# Custom skills (inject domain-specific instructions per agent)
+skills:
+  - id: react-patterns
+    name: React Patterns
+    instructions: "Enforce custom hooks for shared state logic"
+    agentIds:
+      - ts-reviewer
+      - architecture-reviewer
+
+# Per-agent custom review rules (injected after framework context)
+reviewRules:
+  - agent: ts-reviewer
+    rules: |
+      Prefer inject() over constructor injection.
+      Flag *ngIf usage in files under src/features/.
+  - agent: security-reviewer
+    rules: |
+      Treat any hardcoded URL containing internal hostnames as HIGH severity.
+
+# Max diff lines for this repo
+maxDiffLines: 8000
+```
+
+### Engram (Optional Memory Service)
+
+Engram provides cross-session memory. When running:
+
+- Prior review findings are loaded before agents run (avoids duplicate comments)
+- Project context (patterns, conventions learned) is available to agents
+- Review results are saved for future sessions
+
+Start Engram separately:
+```bash
+# Engram runs as a local HTTP service
+engram serve --port 7437
+```
+
+If Engram is unavailable, PRISM works normally without memory features.
+
+---
+
+## Project Structure
+
+```
+prism-cli/
+├── bin/
+│   └── run.js                    # CLI entry point
+├── src/
+│   ├── commands/                  # oclif commands
+│   │   ├── interactive.ts         #   Default: launches TUI
+│   │   ├── login.ts               #   prism login
+│   │   ├── logout.ts              #   prism logout
+│   │   └── review/
+│   │       └── start.ts           #   prism review start --pr <id>
+│   ├── tui/                       # Ink/React TUI
+│   │   ├── app.tsx                #   Root component + state
+│   │   ├── screen-router.tsx      #   Screen navigation (14 screens)
+│   │   ├── screens/               #   Individual screen components
+│   │   ├── components/            #   Reusable UI (ScrollList, SearchableList)
+│   │   └── hooks/                 #   Custom hooks (useAuth, useBitbucket)
+│   ├── ai/
+│   │   ├── agents/                # AI review agents
+│   │   │   ├── registry.ts        #   Agent registration
+│   │   │   ├── ts-reviewer.ts     #   TypeScript agent
+│   │   │   ├── security-reviewer.ts
+│   │   │   ├── css-reviewer.ts
+│   │   │   ├── csharp-reviewer.ts
+│   │   │   ├── architecture-reviewer.ts
+│   │   │   ├── testing-reviewer.ts
+│   │   │   ├── performance-reviewer.ts
+│   │   │   ├── prompts/           #   Agent system prompt templates
+│   │   │   └── shared/            #   Finding schema + prompt builder
+│   │   ├── orchestrator/          # Agent coordination
+│   │   │   ├── orchestrator.ts    #   Main orchestrator
+│   │   │   ├── context-analyzer.ts #  File analysis + stack-aware selection
+│   │   │   ├── rule-based-strategy.ts # Agent plan builder
+│   │   │   ├── strategy.ts        #   Strategy interface
+│   │   │   ├── deduplicator.ts    #   Finding dedup vs existing comments
+│   │   │   └── consolidation.ts   #   Multi-agent finding merge
+│   │   ├── providers/             # AI provider abstraction
+│   │   │   ├── anthropic.ts       #   Direct Anthropic SDK
+│   │   │   └── claude-code.ts     #   Claude Code CLI bridge
+│   │   └── skills/                # Skill registry
+│   ├── bitbucket/                 # Bitbucket REST API client
+│   │   ├── client.ts             #   All API methods
+│   │   └── errors.ts             #   BB-specific error types
+│   ├── config/                    # Configuration
+│   │   ├── config-manager.ts     #   Global config + provider resolution
+│   │   └── credentials.ts        #   Encrypted credential storage
+│   ├── core/                      # Application core
+│   │   ├── workflow-engine.ts    #   16-step review workflow
+│   │   ├── comment-publisher.ts  #   BB comment posting + rate limits
+│   │   └── diff-parser.ts        #   Unified diff → DiffFile[]
+│   ├── memory/                    # Engram integration
+│   │   └── engram-client.ts      #   HTTP client for Engram sidecar
+│   ├── persistence/               # SQLite + Drizzle ORM
+│   │   ├── database.ts           #   DB init + auto-migration
+│   │   ├── schema.ts             #   Drizzle schema (sessions, findings, profiles)
+│   │   ├── session-manager.ts    #   Session CRUD
+│   │   ├── profile-repository.ts #   Stack profile cache
+│   │   ├── workspace-repository.ts # Known workspaces
+│   │   └── migrations/           #   SQL migration files
+│   ├── stack-detector/            # Tech stack detection
+│   │   ├── stack-detector.ts     #   Manifest-based detection
+│   │   ├── parsers.ts            #   8 manifest parsers
+│   │   ├── ai-stack-fallback.ts  #   AI fallback (haiku)
+│   │   ├── merge-profiles.ts     #   Deterministic + AI merge
+│   │   ├── formatter.ts          #   Profile → text for prompts
+│   │   └── types.ts              #   StackProfile interface
+│   ├── types/                     # Shared TypeScript types
+│   └── utils/                     # Utilities (logger, paths)
+├── test/
+│   └── unit/                      # 1210 tests across 104 files
+├── .sdd/
+│   └── STATE.md                   # SDD development state tracker
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+└── .eslintrc.cjs
+```
+
+---
+
+## Development
+
+### Commands
+
+```bash
+pnpm build              # Compile TypeScript + copy assets + oclif manifest
+pnpm start              # Build + run
+pnpm dev                # Watch mode (tsc -b --watch)
+pnpm test               # Run all tests (vitest run)
+pnpm test:watch         # Watch mode tests
+pnpm test:coverage      # Tests with coverage report
+pnpm lint               # ESLint check
+pnpm lint:fix           # ESLint auto-fix
+pnpm format             # Prettier format
+pnpm format:check       # Prettier check
+pnpm release            # Bump version + CHANGELOG + commit + tag
+pnpm release:graduate   # Graduate from prerelease to stable
+```
+
+### Tech Stack
+
+| Technology | Purpose |
+|-----------|---------|
+| TypeScript 5.7 | Language (strict mode, ESM) |
+| oclif v4 | CLI framework + command routing |
+| Ink v5 + React 18 | Terminal UI (TUI) |
+| Anthropic SDK | Claude API integration |
+| better-sqlite3 | Local database (WAL mode) |
+| Drizzle ORM | SQL schema + migrations |
+| Vitest 3.0 | Testing framework |
+| msw 2.7 | API mocking in tests |
+| ink-testing-library | TUI component testing |
+| Zod | Runtime schema validation |
+| ESLint + Prettier | Code quality |
+
+### TypeScript Conventions
+
+- **Strict mode**: `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `noImplicitAny`
+- **ESM**: All imports use `.js` extensions (`import { foo } from './bar.js'`)
+- **Optional properties**: Omit via spread, never pass `undefined` directly
+- **Conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
+- **Agent findings**: Output in Spanish (language instruction in all prompts)
+
+### Running Tests
+
+```bash
+# All tests
+pnpm test
+
+# Specific file
+npx vitest run test/unit/context-analyzer.test.ts
+
+# Pattern match
+npx vitest run --reporter=verbose -t "stack"
+
+# Watch single file
+npx vitest test/unit/context-analyzer.test.ts
+```
+
+---
+
+## Versioning
+
+This project uses [Semantic Versioning](https://semver.org/) with automated releases via [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version). Versions are derived from [Conventional Commits](https://www.conventionalcommits.org/).
+
+### Commit types and version impact
+
+| Commit prefix | Example | In prerelease | In stable |
+|---------------|---------|---------------|-----------|
+| `fix:` | `fix: handle 409 on approve` | `alpha.42` → `alpha.43` | `1.0.0` → `1.0.1` |
+| `feat:` | `feat: add python-reviewer` | `alpha.42` → `alpha.43` | `1.0.0` → `1.1.0` |
+| `feat!:` / `BREAKING CHANGE` | `feat!: redesign agent API` | `alpha.42` → `2.0.0-alpha.0` | `1.0.0` → `2.0.0` |
+| `docs:`, `chore:`, `test:`, `ci:` | `docs: update STATE.md` | No bump | No bump |
+
+### Release lifecycle
+
+```
+alpha (current)  →  beta  →  stable  →  ongoing
+1.0.0-alpha.X       1.0.0-beta.X   1.0.0      1.1.0, 1.0.1, ...
+```
+
+- **Alpha** (`1.0.0-alpha.X`) — Core features working, known gaps and rough edges. Each `feat:` or `fix:` increments the alpha number.
+- **Beta** (`1.0.0-beta.X`) — All v1 features implemented, focus on polish and stability.
+- **Stable** (`1.0.0`) — Production-ready. `feat:` bumps minor, `fix:` bumps patch.
+
+### Release commands
+
+```bash
+# Regular alpha release (after committing changes)
+pnpm release
+# 1.0.0-alpha.42 → 1.0.0-alpha.43
+
+# Promote to beta
+npx commit-and-tag-version --prerelease beta
+# 1.0.0-alpha.X → 1.0.0-beta.1
+
+# Graduate to stable
+pnpm release:graduate
+# 1.0.0-beta.X → 1.0.0
+```
+
+After graduating to stable, `pnpm release:graduate` continues to work for regular semver releases (`1.0.0` → `1.1.0` on feat, `1.0.1` on fix).
+
+### CHANGELOG
+
+Only user-facing changes appear in `CHANGELOG.md`: Features (`feat:`), Bug Fixes (`fix:`), and Performance (`perf:`). Internal commits (`docs:`, `chore:`, `test:`, `refactor:`) are hidden from the CHANGELOG but tracked in git history.
+
+### Configuration
+
+Versioning behavior is defined in `.versionrc`. Tags use the `v` prefix (e.g., `v1.0.0-alpha.42`).
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `EEXIT` error on login | oclif `this.exit(0)` caught as error | Fixed in codebase — use `return` instead |
+| Arrow keys don't work | Ink raw mode ref-count dropped to 0 | `RawModeGuard` component fixes this |
+| `410 Gone` on workspace list | Bitbucket removed cross-workspace API | Uses local SQLite registry now |
+| Findings show "clean PR" when API errors | All agents failed silently | Check API key balance / connectivity |
+| Diff parser fails on Windows | CRLF normalization issue | Fixed: `\r\n?` regex handles double-CRLF |
+| DB migrations not found | Running with `tsc` directly (no `dist/`) | `resolveMigrationsFolder()` falls back to `src/` |
+
+### Logs
+
+PRISM logs to stdout via the TUI. For debugging, check:
+- SQLite database: `<config-dir>/prism.db` (use any SQLite browser)
+- Session data: `review_sessions` + `review_findings` tables
+- Stack cache: `project_profiles` table
+
+### Resetting State
+
+```bash
+# Clear credentials (forces re-login)
+rm "<config-dir>/credentials.json"
+
+# Clear all data (sessions, profiles, workspaces)
+rm "<config-dir>/prism.db"
+
+# Clear global config
+rm "<config-dir>/config.json"
+```