prism-pr 1.0.0-alpha.65 → 1.0.0-alpha.67

package/README.md

@@ -1,120 +1,339 @@
-# PRISM-PR
-
-Intelligent Pull Request review orchestrator for Bitbucket. AI-powered code review with pattern-based pre-checks using ast-grep structural matching.
-
-## Install
-
-```bash
-npm i -g prism-pr
-```
-
-## Setup
-
-```bash
-# Login with your Bitbucket app password
-prism login
-```
-
-Your Bitbucket app password needs these permissions:
-- Repositories: **Read** + **Write**
-- Pull requests: **Read**
-
-## Guard — Instant PR Pattern Check
-
-Guard checks your PR against learned patterns from past reviews. Zero LLM calls, under 2 seconds.
-
-### Check a PR (CLI)
-
-```bash
-# Basic check
-prism guard check -w <workspace> -r <repo> -p <pr-id> --verbose
-
-# Filter by severity
-prism guard check -w <workspace> -r <repo> -p <pr-id> --min-severity high --verbose
-
-# JSON output (for CI/CD)
-prism guard check -w <workspace> -r <repo> -p <pr-id> --json
-
-# Use remote rules (shared team patterns)
-prism guard check -w <workspace> -r <repo> -p <pr-id> --remote --verbose
-```
-
-### Interactive TUI
-
-```bash
-prism guard
-```
-
-Launches the full interactive experience: select workspace, repo, PR, and browse results with keyboard navigation.
-
-### Exit codes
-
-- `0` — No matches found (all clear)
-- `1` — Matches found
-
-Use in CI: `prism guard check -w acme -r app -p $PR_ID --min-severity high || exit 1`
-
-## Rules — Generate and Share Patterns
-
-Rules are generated from your review history and shared via a remote repository.
-
-### Generate patterns
-
-```bash
-# Generate .prism-patterns.json from past reviews
-prism rules sync -w <workspace> -r <repo> --verbose
-
-# Skip AI rule generation (faster, keyword-only)
-prism rules sync -w <workspace> -r <repo> --skip-rules
-```
-
-### Share with your team
-
-```bash
-# Push patterns to remote rules repo
-prism rules push -w <workspace> -r <repo>
-```
-
-Your team then uses `--remote` flag on guard check to fetch shared rules automatically.
-
-### View stats
-
-```bash
-prism rules stats -w <workspace> -r <repo>
-```
-
-## AI Review — Full PR Analysis
-
-```bash
-# Launch interactive TUI for full AI review
-prism
-
-# Or start directly
-prism review start -w <workspace> -r <repo> -p <pr-id>
-```
-
-The AI review uses specialized agents (TypeScript, PHP, CSS, Security, Architecture, Performance, etc.) to analyze your PR and generate findings with inline suggestions.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `prism` | Launch interactive TUI |
-| `prism login` | Authenticate with Bitbucket |
-| `prism logout` | Remove stored credentials |
-| `prism guard` | Guard TUI (pattern check) |
-| `prism guard check` | Guard CLI (non-interactive) |
-| `prism rules sync` | Generate patterns from review history |
-| `prism rules push` | Push patterns to remote repo |
-| `prism rules stats` | Show pattern statistics |
-| `prism review start` | Start AI review for a PR |
-
-## Requirements
-
-- Node.js 20+
-- Bitbucket Cloud account with app password
-- Claude Code CLI (for AI review and rule generation)
-
-## License
-
-Private
+# PRISM-PR
+
+> **Alpha** — this package is in active development (`1.0.0-alpha`). APIs and commands may change between releases.
+
+Intelligent Pull Request review orchestrator for Bitbucket. AI-powered code review plus pattern-based pre-checks using ast-grep structural matching, a shared team rules repository, and a self-evolving rule system that learns from your feedback.
+
+## Install
+
+```bash
+npm i -g prism-pr
+```
+
+## Requirements
+
+- Node.js **>= 22.5.0** (SQLite is loaded via the native `node:sqlite` module)
+- Bitbucket Cloud account with an Atlassian API token
+- AI provider (one of):
+  - `ANTHROPIC_API_KEY` environment variable (preferred), or
+  - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+
+## Setup
+
+```bash
+prism login
+```
+
+Your Bitbucket app password / API token needs these permissions:
+
+- Repositories: **Read** + **Write**
+- Pull requests: **Read** + **Write**
+
+## Discoverability — always available
+
+Every command documents itself via `--help`. If something in this README is stale, trust `--help`:
+
+```bash
+prism --help                      # full command tree
+prism rules --help                # subcommands under `rules`
+prism guard --help                # subcommands under `guard`
+prism rules bootstrap --help      # flags + examples for a specific command
+prism guard check --help
+prism review start --help
+```
+
+---
+
+## Quick start — zero config
+
+PRISM auto-detects your stack and bootstraps rules on the first run. No setup needed.
+
+```bash
+cd your-bitbucket-repo
+prism guard check
+```
+
+That's it. On first run, PRISM will:
+
+1. Detect workspace/repo from your git remote
+2. Fetch `package.json` via Bitbucket API to detect your stack (TypeScript, Angular, React, NestJS, AG Grid, …)
+3. Generate a manifest with the matching rulesets
+4. Push everything to the shared rules repository
+5. Resolve patterns and check your PR
+
+### Manual bootstrap (optional)
+
+If you prefer explicit control:
+
+```bash
+# Detect stack and push manifest + rulesets to the shared rules repo
+prism rules bootstrap
+
+# Preview without pushing
+prism rules bootstrap --dry-run
+
+# JSON output (CI-friendly)
+prism rules bootstrap --dry-run --json
+
+# Explicit workspace/repo/branch
+prism rules bootstrap --workspace acme --repo my-repo --branch develop
+```
+
+### Check a PR
+
+```bash
+# Interactive PR picker (auto-detects workspace/repo from git origin)
+prism guard check
+
+# Pick a PR by ID
+prism guard check --pr 42
+
+# Full output with code snippets and suggestions
+prism guard check --pr 42 --verbose
+
+# Filter by severity
+prism guard check --pr 42 --min-severity high --verbose
+
+# JSON output for CI
+prism guard check --pr 42 --json
+```
+
+**`--verbose` gates the snippet and suggestion.** Without it, matches show severity badge + title + file:line only. With `--verbose`, you get diff context with a pointer on the exact line, plus the fix suggestion.
+
+---
+
+## Living Rules — self-evolving rule system
+
+PRISM's rules aren't static. They learn, adapt, and grow with your codebase.
+
+### Auto-Refresh
+
+Manifests detect when your stack changes. If you add a new framework (e.g. NestJS) to your project, the next guard check automatically updates the manifest with the new rulesets. Default staleness threshold: 7 days.
+
+### Versioned Catalog
+
+Rulesets are published as immutable versioned artifacts:
+
+```
+catalog/
+  shared/security/1.0.0.json    # immutable, infinite cache
+  shared/general/1.0.0.json
+  angular/v17/1.0.0.json
+  ...
+catalog/index.json               # lists all rulesets + latest versions
+```
+
+Manifests can pin versions: `"shared/security@1.2.0"`. Unversioned includes resolve to latest. A 3-level fallback chain ensures resilience: versioned remote → unversioned remote → static builtin catalog.
+
+### Feedback Loop & Auto-Tune
+
+Mark findings as false positives. After enough feedback, PRISM auto-excludes noisy patterns.
+
+```bash
+# CLI: mark specific pattern IDs as false positive
+prism guard check --pr 42 --mark-fp "security--xss--innerHTML-usage,general--debug--console-log"
+
+# CLI: auto-exclude patterns with 3+ false positives
+prism guard check --pr 42 --auto-tune
+```
+
+In the TUI, press `[f]` on any finding to mark it as a false positive. Press `[t]` in the results screen to apply auto-tune.
+
+### AI Rule Suggestion
+
+PRISM can analyze findings from any review and generate new ast-grep rules automatically. Rule suggestions are a **post-review** action — you see the findings first, then decide which patterns should become permanent rules.
+
+```bash
+# CLI: generate rules from guard findings
+prism guard check --pr 42 --suggest-rules
+
+# CLI: generate rules from AI review findings
+prism review start --workspace acme --repo app --pr 42 --suggest-rules
+```
+
+PRISM uses the same AI provider configured for reviews (auto-detects from `ANTHROPIC_API_KEY` or falls back to Claude Code CLI).
+
+In the TUI, press `[g]` on any results screen (guard results or AI review findings) to generate rule suggestions on demand. Review, accept/reject, and apply to the manifest.
+
+---
+
+## Interactive TUI
+
+```bash
+prism           # main TUI (review + navigation)
+prism guard     # guard-focused TUI
+```
+
+Launches a full Ink-based terminal UI with keyboard navigation.
+
+### Guardian Angel section
+
+- **Guard Check** — select workspace → repo → PR → run check
+- **Guard Check (auto-detect)** — detects workspace/repo from git origin, skips manual selection
+- **Rules Bootstrap** — detect stack and push manifest (dry-run toggle, branch override)
+
+### Guard options (toggleable in guard-home)
+
+| Key | Option | Description |
+|-----|--------|-------------|
+| `v` | Verbose | Show context lines and suggestions |
+| `s` | Severity | Cycle minimum severity filter |
+| `a` | AST | Toggle ast-grep matching on/off |
+
+### Guard results actions
+
+| Key | Action | Description |
+|-----|--------|-------------|
+| `↑↓` | Navigate | Browse findings |
+| `Enter` | Detail | View finding detail with context |
+| `f` | False positive | Mark finding as FP (in detail view) |
+| `j` | Export JSON | Export results to `prism-guard-results.json` |
+| `t` | Auto-tune | Batch-exclude patterns with enough FP feedback |
+| `g` | AI suggestions | Generate and review AI-suggested rules (on demand) |
+| `Esc` | Back | Return to previous screen |
+
+### AI Review findings actions
+
+| Key | Action | Description |
+|-----|--------|-------------|
+| `↑↓` | Navigate | Browse findings |
+| `Enter` | Detail | View finding detail |
+| `g` | AI suggestions | Generate rules from review findings (on demand) |
+| `p` | Publish | Publish findings to Bitbucket PR |
+| `Esc` | Back | Return to previous screen |
+
+---
+
+## AI Review — full PR analysis (LLM-powered)
+
+```bash
+prism review start --workspace acme --repo app --pr 42
+
+# Verbose logging
+prism review start --workspace acme --repo app --pr 42 --verbose
+
+# Pick a provider explicitly
+prism review start --workspace acme --repo app --pr 42 --provider anthropic
+prism review start --workspace acme --repo app --pr 42 --provider claude-code
+
+# Generate rule suggestions from findings
+prism review start --workspace acme --repo app --pr 42 --suggest-rules
+```
+
+> **Note:** `review start` requires `--workspace` and `--repo` explicitly (no auto-detect from git origin). `guard check` auto-detects both.
+
+The AI review runs specialized agents (TypeScript, PHP, CSS, Security, Architecture, Performance, …) and produces findings with inline suggestions. Findings are stored in a local SQLite database for review memory and pattern generation.
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `prism` | Launch main interactive TUI |
+| `prism login` | Authenticate with Bitbucket |
+| `prism logout` | Remove stored credentials |
+| `prism guard` | Guard Check TUI |
+| `prism guard check` | Non-interactive pattern check (manifest v3) |
+| `prism rules bootstrap` | Detect stack, generate manifest, push to rules repo |
+| `prism rules sync` | ~~Legacy v2.~~ Generate `.prism-patterns.json` from local review history (deprecated) |
+| `prism rules push` | ~~Legacy v2.~~ Push a local `.prism-patterns.json` to the rules repo (deprecated) |
+| `prism rules stats` | Show aggregated finding patterns from local review history |
+| `prism review start` | Run an AI code review on a PR |
+
+### guard check flags
+
+| Flag | Description |
+|------|-------------|
+| `--workspace, -w` | Bitbucket workspace (auto-detected from git origin) |
+| `--repo, -r` | Repository slug (auto-detected from git origin) |
+| `--pr, -p` | Pull request ID (interactive picker if omitted) |
+| `--verbose` | Show diff context and suggestions |
+| `--min-severity` | Filter: `critical`, `high`, `medium`, `low`, `info` |
+| `--json` | Structured JSON output (CI-friendly) |
+| `--skip-ast` | Skip ast-grep, keyword-only matching |
+| `--auto-tune` | Auto-exclude patterns with repeated false positives |
+| `--suggest-rules` | Generate AI rules from recurring findings |
+| `--mark-fp` | Mark pattern IDs as false positive (comma-separated) |
+| `--patterns` | Path to local patterns file (bypasses manifest) |
+| `--remote` | **Deprecated.** Use v2 remote fetch path |
+
+### Exit codes (guard check)
+
+- `0` — no matches found
+- `1` — matches found (or error)
+
+Useful in CI:
+
+```bash
+prism guard check --pr "$PR_ID" --min-severity high --json > findings.json
+```
+
+---
+
+## Concepts
+
+### Manifest v3
+
+A `ProjectManifest` lives at `projects/<workspace>/<repo>.json` in the shared rules repo. It references rulesets by id instead of inlining patterns:
+
+```json
+{
+  "version": 3,
+  "generatedAt": "2026-04-13T21:00:00.000Z",
+  "stack": {
+    "languages": ["typescript"],
+    "frameworks": [{ "name": "angular", "version": "17.3.0" }],
+    "detectedAt": "2026-04-13T21:00:00.000Z"
+  },
+  "includes": ["angular/base", "angular/v17", "shared/typescript", "shared/security@1.0.0"],
+  "excludes": ["general--debug--console-log"],
+  "patterns": []
+}
+```
+
+- `includes` — ruleset IDs to pull in (supports `@version` pinning)
+- `excludes` — pattern IDs to skip (auto-tune populates this)
+- `patterns` — project-specific custom patterns (AI suggestions land here)
+
+### Rulesets
+
+Built-in rulesets today (9 rulesets, 30+ ast-grep patterns):
+
+- `shared/general`, `shared/security`, `shared/typescript`
+- `angular/base`, `angular/v17`
+- `react/base`
+- `nestjs/base`
+- `ag-grid/base`, `ag-grid/v32`
+
+### Remote catalog structure
+
+All teams share a single Bitbucket rules repository that hosts manifests and versioned rulesets. The default shared repo is `walzate1/prism-rules`:
+
+```
+{rules-repo} (Bitbucket)
+├── projects/{workspace}/{repo}.json    # per-project manifest
+├── rulesets/{id}.json                  # unversioned rulesets (backward compat)
+└── catalog/
+    ├── index.json                      # catalog index (all rulesets + versions)
+    └── {id}/{version}.json             # immutable versioned rulesets
+```
+
+### Severity levels
+
+`critical` · `high` · `medium` · `low` · `info`
+
+### Pattern resolution flow
+
+1. `--patterns <file>` explicitly set → use local file (bypasses manifest)
+2. Fetch manifest from `projects/<ws>/<repo>.json`
+3. If no manifest → **auto-bootstrap** (detect stack → generate → push → continue)
+4. If manifest is stale (>7 days) → **auto-refresh** (re-detect stack → smart merge → push)
+5. Resolve includes via 3-level fallback (versioned → unversioned → static builtin)
+6. Apply excludes → merge custom patterns → run guard
+
+---
+
+## License
+
+UNLICENSED — All rights reserved.

package/bin/run.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
-
-// Suppress node:sqlite ExperimentalWarning
-const _origEmit = process.emit.bind(process);
-process.emit = function (event, ...args) {
-  if (event === 'warning' && args[0]?.name === 'ExperimentalWarning') return false;
-  return _origEmit(event, ...args);
-};
-
-import { execute } from '@oclif/core';
-
-// If no command specified, default to interactive TUI
-if (process.argv.length === 2) {
-  process.argv.push('interactive');
-}
-
-await execute({ dir: import.meta.url });
+
+// Suppress node:sqlite ExperimentalWarning
+const _origEmit = process.emit.bind(process);
+process.emit = function (event, ...args) {
+  if (event === 'warning' && args[0]?.name === 'ExperimentalWarning') return false;
+  return _origEmit(event, ...args);
+};
+
+import { execute } from '@oclif/core';
+
+// If no command specified, default to interactive TUI
+if (process.argv.length === 2) {
+  process.argv.push('interactive');
+}
+
+await execute({ dir: import.meta.url });

package/dist/ai/adapters/model-provider-llm-adapter.d.ts

@@ -0,0 +1,21 @@
+import type { ModelProvider } from '../../types/provider.js';
+import type { LLMProvider } from '../../rules-engine/pattern-generator.js';
+/**
+ * Adapter that bridges ModelProvider (tool_use, returns AnalyzeResult) →
+ * LLMProvider (string-in / string-out) required by PatternGenerator.
+ *
+ * Strategy:
+ * 1. Defines a tool schema where `findings[0]` is the model's complete text output.
+ * 2. Calls ModelProvider.analyze() with this schema.
+ * 3. Extracts findings[0] as a string (or JSON-serializes if the model returns an object).
+ * 4. Returns empty string when findings is empty — callers handle empty gracefully.
+ */
+export declare class ModelProviderLLMAdapter implements LLMProvider {
+    private readonly provider;
+    constructor(provider: ModelProvider);
+    analyze(systemPrompt: string, userContent: string, options?: {
+        toolName?: string;
+        maxTokens?: number;
+    }): Promise<string>;
+}
+//# sourceMappingURL=model-provider-llm-adapter.d.ts.map

package/dist/ai/adapters/model-provider-llm-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-provider-llm-adapter.d.ts","sourceRoot":"","sources":["../../../src/ai/adapters/model-provider-llm-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAwB3E;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,YAAW,WAAW;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,aAAa;IAE9C,OAAO,CACX,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAClD,OAAO,CAAC,MAAM,CAAC;CAwBnB"}

package/dist/ai/adapters/model-provider-llm-adapter.js

@@ -0,0 +1,58 @@
+/**
+ * Tool schema designed to work with AnthropicProvider's extraction logic.
+ *
+ * AnthropicProvider always extracts `toolUseBlock.input.findings` from the tool call response.
+ * So the schema MUST use `findings` as the key — the model places its response in `findings[0]`.
+ *
+ * With this schema the model is instructed to return an array with exactly one element:
+ * the complete JSON response. AnthropicProvider's existing extraction code
+ * (`input.findings ?? []`) captures it, and we return `findings[0]`.
+ */
+const TEXT_CAPTURE_TOOL_SCHEMA = {
+    type: 'object',
+    properties: {
+        findings: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Array with exactly one element: the complete JSON response. No markdown fences.',
+        },
+    },
+    required: ['findings'],
+};
+/**
+ * Adapter that bridges ModelProvider (tool_use, returns AnalyzeResult) →
+ * LLMProvider (string-in / string-out) required by PatternGenerator.
+ *
+ * Strategy:
+ * 1. Defines a tool schema where `findings[0]` is the model's complete text output.
+ * 2. Calls ModelProvider.analyze() with this schema.
+ * 3. Extracts findings[0] as a string (or JSON-serializes if the model returns an object).
+ * 4. Returns empty string when findings is empty — callers handle empty gracefully.
+ */
+export class ModelProviderLLMAdapter {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async analyze(systemPrompt, userContent, options) {
+        const toolName = options?.toolName ?? 'generate_ast_grep_rule';
+        const maxTokens = options?.maxTokens ?? 1024;
+        const result = await this.provider.analyze({
+            systemPrompt,
+            userContent,
+            toolName,
+            toolSchema: TEXT_CAPTURE_TOOL_SCHEMA,
+            maxTokens,
+        });
+        if (result.findings.length === 0) {
+            return '';
+        }
+        const first = result.findings[0];
+        if (typeof first === 'string') {
+            return first;
+        }
+        // Object findings — JSON-serialize for parseGeneratedRule to handle
+        return JSON.stringify(first);
+    }
+}
+//# sourceMappingURL=model-provider-llm-adapter.js.map

package/dist/ai/adapters/model-provider-llm-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-provider-llm-adapter.js","sourceRoot":"","sources":["../../../src/ai/adapters/model-provider-llm-adapter.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,wBAAwB,GAAG;IAC/B,IAAI,EAAE,QAAiB;IACvB,UAAU,EAAE;QACV,QAAQ,EAAE;YACR,IAAI,EAAE,OAAgB;YACtB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE;YAClC,WAAW,EAAE,iFAAiF;SAC/F;KACF;IACD,QAAQ,EAAE,CAAC,UAAU,CAAU;CAChC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,OAAO,uBAAuB;IACL;IAA7B,YAA6B,QAAuB;QAAvB,aAAQ,GAAR,QAAQ,CAAe;IAAG,CAAC;IAExD,KAAK,CAAC,OAAO,CACX,YAAoB,EACpB,WAAmB,EACnB,OAAmD;QAEnD,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,wBAAwB,CAAC;QAC/D,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC;QAE7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YACzC,YAAY;YACZ,WAAW;YACX,QAAQ;YACR,UAAU,EAAE,wBAAwB;YACpC,SAAS;SACV,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,oEAAoE;QACpE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/ai/agents/prompts/architecture-reviewer.txt

@@ -1,39 +1,39 @@
-You are a senior software architect reviewing a pull request for structural and design issues. Your goal is to identify high-signal architectural problems — NOT file-level code style issues or implementation details.
-
-## Focus Areas
-
-Review the entire diff holistically and report findings for:
-
-1. **Circular dependencies** — modules or packages that import each other directly or transitively, creating tight coupling that prevents independent testing or deployment
-2. **Single Responsibility Principle violations** — classes, modules, or functions that are clearly doing multiple unrelated things (e.g., a data model that also handles HTTP calls; a service that mixes business logic with persistence)
-3. **Layer boundary crossings** — higher-level layers being imported by lower-level layers (e.g., UI components importing directly from database models; infrastructure code importing domain entities incorrectly)
-4. **Inappropriate coupling** — components that know too much about each other's internals; tight coupling that makes changes in one place require changes in many others
-5. **Leaked abstractions** — implementation details of one layer leaking into another (e.g., SQL-specific types in business logic; HTTP status codes in domain services)
-
-## Critical Output Constraint
-
-Produce between 0 and 3 findings MAXIMUM. This is a hard limit.
-
-Focus only on `critical` or `high` severity architectural issues. Do NOT report:
-- `medium`, `low`, or `info` severity findings
-- File-level implementation details
-- Naming conventions or code style
-- Issues that affect a single file without cross-component impact
-- Theoretical violations without clear evidence in the diff
-
-If no high-signal architectural issues exist, return an empty findings array. Do NOT manufacture findings to appear thorough.
-
-## Output Instructions
-
-You MUST call the `report_findings` tool to submit your findings. Do not write findings as plain text — the tool call is required.
-
-For each finding, reference the exact line number using the `[L{num}]` annotations provided in the diff. The `lineNumber` field in each finding MUST correspond to an annotated line from the diff.
-
-If there are no findings, call `report_findings` with an empty array: `{ "findings": [] }`.
-
-## Severity Criteria
-
-| Severity | When to use |
-|----------|-------------|
-| `critical` | Circular dependency or layer violation that will break builds or prevent testability |
-| `high` | SRP violation or coupling issue that will cause cascading changes and increase defect rate |
+You are a senior software architect reviewing a pull request for structural and design issues. Your goal is to identify high-signal architectural problems — NOT file-level code style issues or implementation details.
+
+## Focus Areas
+
+Review the entire diff holistically and report findings for:
+
+1. **Circular dependencies** — modules or packages that import each other directly or transitively, creating tight coupling that prevents independent testing or deployment
+2. **Single Responsibility Principle violations** — classes, modules, or functions that are clearly doing multiple unrelated things (e.g., a data model that also handles HTTP calls; a service that mixes business logic with persistence)
+3. **Layer boundary crossings** — higher-level layers being imported by lower-level layers (e.g., UI components importing directly from database models; infrastructure code importing domain entities incorrectly)
+4. **Inappropriate coupling** — components that know too much about each other's internals; tight coupling that makes changes in one place require changes in many others
+5. **Leaked abstractions** — implementation details of one layer leaking into another (e.g., SQL-specific types in business logic; HTTP status codes in domain services)
+
+## Critical Output Constraint
+
+Produce between 0 and 3 findings MAXIMUM. This is a hard limit.
+
+Focus only on `critical` or `high` severity architectural issues. Do NOT report:
+- `medium`, `low`, or `info` severity findings
+- File-level implementation details
+- Naming conventions or code style
+- Issues that affect a single file without cross-component impact
+- Theoretical violations without clear evidence in the diff
+
+If no high-signal architectural issues exist, return an empty findings array. Do NOT manufacture findings to appear thorough.
+
+## Output Instructions
+
+You MUST call the `report_findings` tool to submit your findings. Do not write findings as plain text — the tool call is required.
+
+For each finding, reference the exact line number using the `[L{num}]` annotations provided in the diff. The `lineNumber` field in each finding MUST correspond to an annotated line from the diff.
+
+If there are no findings, call `report_findings` with an empty array: `{ "findings": [] }`.
+
+## Severity Criteria
+
+| Severity | When to use |
+|----------|-------------|
+| `critical` | Circular dependency or layer violation that will break builds or prevent testability |
+| `high` | SRP violation or coupling issue that will cause cascading changes and increase defect rate |