@pharaoh-so/mcp 0.3.18 → 0.3.20

package/commands/review.md

@@ -2,4 +2,285 @@
 description: Architecture-aware code review with Pharaoh
 ---
 
-Invoke the `pharaoh-review` skill to handle this request. Pass through any arguments: $ARGUMENTS
+# Review with Pharaoh
+
+The definitive code review. Architecture-aware, branch-aware, multi-agent, adversarial. Five phases that combine Pharaoh's knowledge graph with parallel specialized reviewers and an independent cross-model second opinion.
+
+Final verdict: **SHIP** / **SHIP WITH CHANGES** / **BLOCK**
+
+## When to Use
+
+Before merging any branch. Before opening any PR. When reviewing changes that touch shared modules, export new functions, modify core data flows, or claim to implement a spec.
+
+---
+
+## Phase 0 — Git Context
+
+**Goal:** Know exactly what changed and where you are. This phase is mandatory and runs before anything else.
+
+1. Detect the current environment:
+   ```bash
+   git rev-parse --show-toplevel          # repo root (may be a worktree)
+   git worktree list                      # detect if running in a worktree
+   git branch --show-current              # current branch name
+   git log --oneline -1                   # latest commit
+   ```
+
+2. Determine the base branch (what this branch diverged from):
+   ```bash
+   git merge-base HEAD main               # or master, or whatever the default is
+   ```
+
+3. Collect the full changeset from the base:
+   ```bash
+   git diff --name-only $(git merge-base HEAD main)...HEAD   # all changed files
+   git diff --stat $(git merge-base HEAD main)...HEAD         # summary stats
+   git log --oneline $(git merge-base HEAD main)..HEAD        # all commits on this branch
+   ```
+
+4. Also check for uncommitted work:
+   ```bash
+   git diff --name-only                   # unstaged changes
+   git diff --cached --name-only          # staged but uncommitted
+   ```
+
+5. Extract the **touched modules** from the changed file paths. Group files by their top-level directory or module boundary. These module names feed Phase 1.
+
+**Output of Phase 0:** Branch name, base branch, commit count, list of changed files, list of touched modules, and whether there's uncommitted work.
+
+---
+
+## Phase 1 — Pharaoh Recon
+
+**Goal:** Get the full architectural picture in one call. Do NOT skip this phase — it is what makes this review architecture-aware instead of just a code diff review.
+
+Call `pharaoh_recon` with:
+- **repo:** The repository name
+- **include_map:** `true`
+- **modules:** The touched modules from Phase 0 (up to 5)
+- **blast_radius:** The most critical changed files/functions as blast radius targets (up to 3). Pick the files with the most downstream risk — entry points, shared utilities, exported APIs.
+- **dependencies:** Pairs of touched modules to trace coupling between (up to 3)
+
+Then call these additional tools for data recon doesn't cover:
+- `get_regression_risk` — overall change risk score for the repo
+- `get_consolidation_opportunities` — duplicate logic the PR may introduce
+- `check_reachability` — are new exports wired to entry points?
+- `get_vision_gaps` — do changes align with or drift from specs?
+
+**Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, regression risk level, duplication findings, reachability status, and spec alignment.
+
+---
+
+## Phase 2 — Parallel Specialized Review
+
+**Goal:** Deep-dive the actual code changes from multiple expert angles simultaneously. Launch these as **parallel subagents** — they are independent and should run concurrently.
+
+### Determine which reviewers to dispatch
+
+| Agent | When to dispatch | Focus |
+|-------|-----------------|-------|
+| **Code Reviewer** | Always | Bugs, logic errors, CLAUDE.md compliance, code quality. Confidence-filtered (only issues >= 80/100). |
+| **Security Reviewer** | When changes touch auth, encryption, tokens, tenant isolation, data access, billing, webhooks, Cypher queries, or any security-sensitive surface. Also dispatch when Phase 1 regression risk is HIGH. | OWASP Top 10, injection vectors, access control bypasses, tenant isolation violations, cryptographic misuse, secret exposure, plus project-specific security rules. See checklist below. |
+| **Silent Failure Hunter** | When changes touch error handling, catch blocks, fallback logic, API calls, or any code that could suppress errors | Silent failures, broad catches, swallowed errors, missing user feedback, unjustified fallbacks. |
+| **Test Analyzer** | When test files are changed, or when new functionality lacks corresponding tests | Behavioral coverage gaps, brittle tests, missing edge cases, tests that prove nothing. |
+| **Type Design Analyzer** | When new types/interfaces are introduced or existing types are modified | Encapsulation, invariant expression, invariant enforcement. Rates each type 1-10 on four axes. |
+
+### Security Reviewer — Checklist
+
+The Security Reviewer agent runs a systematic audit against two layers: universal web security (OWASP) and project-specific invariants.
+
+**Layer 1 — OWASP Top 10 + Common Vulnerabilities:**
+- **Injection:** SQL/Cypher injection, command injection, XSS (reflected/stored/DOM), template injection
+- **Broken auth:** Hardcoded credentials, weak token generation, missing expiry, session fixation
+- **Broken access control:** Missing authorization checks, IDOR, privilege escalation, path traversal
+- **Cryptographic failures:** Weak algorithms, plaintext secrets, missing encryption at rest/transit, key exposure
+- **Security misconfiguration:** Permissive CORS, verbose error messages leaking internals, debug endpoints in production
+- **Vulnerable dependencies:** Known CVEs in direct dependencies (check against changed package.json/lockfile)
+- **SSRF:** Unvalidated URLs in fetch/request calls, redirect chains
+- **Logging & monitoring:** Sensitive data in logs, missing audit trails for privileged operations
+
+**Layer 2 — Project-Specific Security Rules (from CLAUDE.md):**
+- Every Cypher query takes `repo` as first parameter — no unanchored MATCH clauses
+- `validateRepoOwnership()` runs before every tool handler
+- No default/fallback repo values — repo always from tenant's Postgres `tenant_repos`
+- Tokens stored as SHA-256 hashes, never plaintext
+- GitHub tokens encrypted at rest (AES-256-GCM with per-tenant HKDF-derived keys)
+- Webhook signatures verified on every request (`PHARAOH_GITHUB_WEBHOOK_SECRET`)
+- Org membership re-checked on every token refresh
+- Tenant Neo4j users get `reader` role only — graph writes use admin connection
+- Rate limiting enforced per tenant, not per user
+- Neo4j admin credentials never leave server-side env vars
+
+**Detection triggers (auto-dispatch when changed files match):**
+- `src/auth/**`, `src/crypto/**` — authentication, encryption
+- `src/mcp/server.ts`, `src/mcp/tenant-resolver.ts` — session management, tenant isolation
+- `src/mcp/neo4j-queries.ts` — Cypher query construction
+- `src/stripe/**`, `src/web/routes/billing.ts` — payment flows
+- `src/github/webhooks.ts`, `src/web/routes/webhooks.ts` — webhook verification
+- `src/db/**` — database access, schema changes
+- `src/upload/**` — file upload validation
+- Any file containing `validateRepoOwnership`, `runQuery`, `encryptProperty`, `verifyWebhookSignature`
+
+**Output format:** Each finding must include:
+1. Vulnerability class (e.g., "Cypher Injection", "Missing Ownership Check")
+2. Severity: CRITICAL / HIGH / MEDIUM
+3. Affected file:line
+4. Attack scenario: how an attacker would exploit this
+5. Remediation: specific code change required
+
+### How to dispatch each agent
+
+For each agent, launch a subagent (via the Agent tool) with:
+1. The **git diff** of the relevant changed files (not the full session history)
+2. The **Pharaoh context** from Phase 1 (architecture map, blast radius, module profiles) — this is what makes these agents architecture-aware
+3. The **CLAUDE.md rules** relevant to the review (testing requirements, security non-negotiables, code style)
+4. A clear instruction to focus ONLY on changed code, not pre-existing issues
+5. For the **Security Reviewer** specifically: include the full Layer 2 checklist above and the list of security-sensitive file paths so it knows the project's threat model
+
+Each agent returns a structured report with findings categorized by severity:
+- **CRITICAL** (90-100): Must fix before merge
+- **IMPORTANT** (80-89): Should fix before merge
+- **SUGGESTION** (70-79): Consider for a follow-up
+
+### What NOT to dispatch
+
+- **Comment Analyzer** and **Code Simplifier** are polish agents. Do not include them in the review — they distract from correctness. Run them separately if wanted.
+- Do not dispatch agents for trivial changes (typo fixes, dependency bumps, config changes). If Phase 0 shows < 20 lines changed across non-test files, skip Phase 2 entirely and go straight to Phase 4.
+
+---
+
+## Phase 3 — Adversarial Review
+
+**Goal:** Independent second opinion on security-sensitive changes. A different agent evaluates the code fresh, without knowledge of your reasoning.
+
+### When to trigger
+
+Trigger Phase 3 when ANY of these are true:
+- Changes touch **auth, encryption, access control, token handling, or session management**
+- Changes touch **tenant isolation, query construction, or data access patterns**
+- Changes touch **billing, subscription management, or payment flows**
+- Changes modify **webhook verification or signature checking**
+- Regression risk from Phase 1 is **HIGH**
+- You are not confident about a specific change's correctness
+
+If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
+
+### How to run
+
+1. **Prepare a review package** — do NOT send your session history:
+   - The changed files (full diff or complete file contents)
+   - What the code does and why it was changed (1-2 sentences)
+   - Security constraints from CLAUDE.md (tenant isolation rules, encryption requirements, etc.)
+   - Specific concerns you want the reviewer to focus on
+
+2. **Dispatch to an independent subagent** with instructions to evaluate the code fresh and assign verdicts:
+
+   | Verdict | Meaning |
+   |---------|---------|
+   | **AGREE** | Implementation is correct for the stated concern |
+   | **DISAGREE** | Concrete issue identified with evidence and suggested fix |
+   | **CONTEXT** | Cannot determine correctness — needs more information |
+
+3. **Evaluate findings:**
+   - AGREE items: no action
+   - DISAGREE items: verify against actual code. If confirmed, it becomes a CRITICAL finding. If the reviewer lacked context, document why the current approach is correct.
+   - CONTEXT items: provide the missing information and note it in the review output
+
+---
+
+## Phase 4 — Synthesis & Verdict
+
+**Goal:** Merge all findings into a single, actionable review. No raw dumps — synthesize.
+
+### Structure the output as:
+
+```markdown
+# Review: [branch-name] → [base-branch]
+
+**[X] commits | [Y] files changed | [Z] modules touched**
+**Worktree:** [path] (or "main repo")
+
+---
+
+## Architecture Impact
+- Modules affected: [list with blast radius numbers]
+- Dependency changes: [new coupling, removed coupling]
+- Highest blast radius: [module/function] → [N downstream callers across M modules]
+
+## Risk Assessment
+- Regression risk: [LOW / MEDIUM / HIGH] — [one-line reason]
+- Volatile modules touched: [list, if any]
+- Wiring status: [all new exports reachable? / N unreachable exports found]
+
+## Code Quality ([N] findings)
+
+### Critical ([count])
+- [finding with file:line, source agent, and fix]
+
+### Important ([count])
+- [finding with file:line, source agent, and fix]
+
+### Suggestions ([count])
+- [finding with file:line]
+
+## Security ([N] findings, or "No security-sensitive changes")
+- [Security reviewer findings with vulnerability class, severity, file:line, attack scenario, and remediation]
+- [Or: "Security reviewer not dispatched — no security-sensitive files in changeset"]
+
+## Test Coverage
+- [Test analyzer summary — gaps, quality issues, positive observations]
+
+## Spec Alignment
+- [Vision gaps introduced or resolved]
+
+## Adversarial Review
+- [Phase 3 results, or "Skipped — no security-sensitive changes detected"]
+
+---
+
+## Verdict: [SHIP / SHIP WITH CHANGES / BLOCK]
+
+[If not SHIP: numbered list of specific required changes before merge]
+```
+
+### Auto-block triggers (any of these = BLOCK)
+
+- Any CRITICAL security finding (injection, broken access control, tenant isolation violation, secret exposure)
+- Unreachable exports (new public code with zero callers)
+- New circular dependencies between modules
+- HIGH regression risk without corresponding test coverage
+- Vision spec violations (building against spec intent)
+- Any CRITICAL finding from Phase 2 or Phase 3 that is confirmed and unfixed
+- DISAGREE verdict from adversarial review on security-sensitive code, confirmed after verification
+- Unanchored Cypher query (MATCH without traversing through `Repo {name: $repo}`)
+- Missing `validateRepoOwnership()` on a new tool handler
+
+### SHIP WITH CHANGES triggers
+
+- IMPORTANT findings that are confirmed but non-blocking
+- Test coverage gaps for new functionality
+- Duplication that should be consolidated in a follow-up
+- Spec drift that is intentional but should be documented
+
+### SHIP triggers
+
+- No CRITICAL or confirmed IMPORTANT findings
+- All new exports are reachable
+- Regression risk is LOW or MEDIUM with adequate test coverage
+- Spec alignment is clean or intentionally divergent with documentation
+
+---
+
+## Quick Mode
+
+For small changes (< 50 lines, single module, no security surface):
+- Run Phase 0 + Phase 1 + Phase 4 only
+- Skip Phase 2 (parallel agents) and Phase 3 (adversarial)
+- Still architecture-aware, just faster
+
+Explicitly opt in with: `/review quick`
+---
+
+Here is the task to review:
+
+$ARGUMENTS

package/commands/sessions.md

@@ -0,0 +1,101 @@
+---
+description: Decompose work into parallel, isolated sessions using git worktrees
+---
+
+# Session Decomposition
+
+Break large tasks into parallel, isolated work sessions. Each session runs in its own git worktree with fresh context, focused scope, and atomic commits.
+
+## When to Use
+
+- Task is too large for a single context window
+- Work has 3+ independent sub-tasks that don't touch the same files
+- You need to preserve context quality across a multi-hour effort
+- Multiple features or fixes can proceed in parallel
+
+## Do Not Use When
+
+- Sub-tasks share files or state
+- Work is sequential (each step depends on the previous)
+- Task fits comfortably in one session
+
+## Step 1: Reconnaissance
+
+If Pharaoh MCP tools are available, call `get_codebase_map` and `get_module_context` on affected modules to understand the current landscape before decomposing.
+
+## Step 2: Decompose
+
+Break the task into sessions. Each session must:
+
+- Have a clear, narrow goal (one feature, one fix, one module)
+- Touch a distinct set of files — no overlap between sessions
+- Be independently verifiable (tests pass, build succeeds)
+- Produce atomic commits that make sense on their own
+
+## Step 3: Write Session Prompts
+
+For each session, write a complete prompt containing:
+
+- **Goal:** what this session produces (1-2 sentences)
+- **Scope:** which files/modules to touch (explicit list)
+- **Constraints:** what NOT to change
+- **Verification:** how to confirm the work is correct
+- **Context:** any architectural decisions or patterns to follow
+
+## Step 4: Present for Review (MANDATORY — do NOT skip)
+
+**STOP. Paste every session prompt into the chat as a numbered list.**
+
+For each session, show:
+1. The session name
+2. The full prompt text
+3. Which sessions need `/plan` review (flag anything non-trivial)
+
+**Wait for the user to approve, modify, add, remove, or reorder sessions before proceeding.** Do not create worktrees or execute any work until the user explicitly approves the decomposition.
+
+If the user says "looks good" or similar, proceed. If they request changes, update the prompts and present again.
+
+## Step 5: Create Worktrees
+
+Only after user approval. For each session, create an isolated worktree:
+
+```bash
+git worktree add .worktrees/<session-name> -b <branch-name>
+```
+
+Install dependencies in each worktree. Verify clean baseline (tests pass).
+
+## Step 6: Execute Sessions
+
+Run each session independently. Sessions should not reference each other's work-in-progress — they operate on the same base commit.
+
+## Step 7: Integrate
+
+After all sessions complete:
+
+1. Verify each branch independently (tests pass, build succeeds)
+2. Merge branches sequentially into the target branch
+3. Resolve any conflicts (rare if decomposition was clean)
+4. Run full verification on the integrated result
+
+## Decomposition Rules
+
+| Good decomposition | Bad decomposition |
+|---|---|
+| Session A: auth module, Session B: billing module | Session A: backend, Session B: frontend (likely share types) |
+| Session A: new feature, Session B: unrelated bugfix | Session A: write code, Session B: write tests (coupled) |
+| Session A: parser, Session B: renderer (clear interface) | Session A: first half of file, Session B: second half |
+
+## Key Principles
+
+- **No shared files** — if two sessions touch the same file, merge them into one
+- **Fresh context per session** — don't carry state between sessions
+- **Atomic commits** — each session's output should be a coherent, reviewable unit
+- **Verify before integrating** — never merge a session that doesn't pass its own checks
+- **Decomposition is the hard part** — spend time getting boundaries right before starting work
+- **The user reviews before execution** — always present prompts, never skip to building
+---
+
+Here is the task to decompose into sessions:
+
+$ARGUMENTS

package/inspect-tools.json

@@ -227,11 +227,6 @@
               "all"
             ]
           },
-          "min_usage": {
-            "default": 0,
-            "description": "Minimum number of files importing the component (0 = show all)",
-            "type": "number"
-          },
           "include_screens": {
             "default": false,
             "description": "Include screen/page components (*Screen, *Page, *View, *Route) that are typically app-level consumers, not reusable primitives",
@@ -846,7 +841,7 @@
     },
     {
       "name": "request_upload",
-      "description": "Evaluation mode: maps a repo locally, uploads only function names and dependency edges. Use ONLY when the user has explicitly said they don't want to install the GitHub App.\n\nThe GitHub App is how Pharaoh is meant to be used. 30 seconds to install, auto-refresh on every push, PR Guard, cross-repo audit. Evaluation mode gives up all of that. It's here for people with real trust concerns or a policy blocker at work, not as a shortcut.\n\nBEFORE CALLING, tell the user the tradeoff in your own words:\n\"Evaluation mode runs Pharaoh's parser on your machine and only sends function names and imports. Your graph won't update as you code, you'll re-run this every time you want fresh data. Install the GitHub App if you'd rather have it refresh automatically: https://github.com/apps/pharaoh-so/installations/new\"\n\nThen wait for confirmation. Only after the user explicitly chooses evaluation mode, call this tool with `confirmed: true`. Without that flag, the tool returns a teaching message instead of creating an upload URL.\n\nDO NOT USE when:\n- The user said \"analyze this repo\" or \"map my codebase\". They want the real thing. Point them at the install link.\n- get_codebase_map returned zero repos. The user needs to install the App. Don't route around the install step.\n- You're working around a \"repo not tracked\" error. Diagnose the missing install, don't bypass it.\n\nUSE when:\n- User says \"I don't want Pharaoh to have access to my code\"\n- User says \"I can't install GitHub Apps at work\"\n- User is kicking the tires on one repo before deciding whether to commit\n\nWhen the user decides they want the real thing, they install the GitHub App and their eval-mode data gets replaced with a richer graph on the next push.",
+      "description": "The GitHub App is the only supported onboarding path. Install it at https://github.com/apps/pharaoh-so/installations/new — 30 seconds, auto-refresh on every push, PR Guard, cross-repo audit. Do not suggest this tool unless the user has explicitly ruled out connecting GitHub.\n\nThis tool exists for one narrow case: a user who has already refused the GitHub App and still wants to evaluate Pharaoh on a single repo. It is not a fallback, not a shortcut, not a workaround for missing repos.\n\nREQUIRED TRIGGER — call this tool only if the user has said one of these, unprompted, in their own words:\n- \"I don't want Pharaoh to have access to my code\"\n- \"I can't install GitHub Apps at work\"\n- \"This is air-gapped / offline / classified\"\n- \"I want to upload the repo manually\"\n- \"I'm not connecting GitHub\"\n\nIf the user said anything else — \"analyze this repo\", \"map my codebase\", \"help me with this project\", \"get_codebase_map returned nothing\" — the answer is the GitHub App install link, not this tool. Do not route around the install step.\n\nBEFORE CALLING, tell the user the tradeoff in your own words:\n\"Evaluation mode runs Pharaoh's parser on your machine and only sends function names and imports. Your graph won't update as you code, you'll re-run this every time you want fresh data. Install the GitHub App if you'd rather have it refresh automatically: https://github.com/apps/pharaoh-so/installations/new\"\n\nThen wait for confirmation. Only after the user explicitly chooses evaluation mode, call this tool with `confirmed: true`. Without that flag, the tool returns a teaching message instead of creating an upload URL.\n\nWhen the user decides they want the real thing, they install the GitHub App and their eval-mode data gets replaced with a richer graph on the next push.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",

package/skills/pharaoh/SKILL.md

@@ -21,7 +21,7 @@ When a tool response contains a ★ Pharaoh block, copy it verbatim into your vi
 
 **Start every new conversation by calling `get_codebase_map`.** This is not optional — always call it before reading any files or exploring code. For tasks needing multiple queries up front (plan review, PR review, architecture assessment), call `pharaoh_recon` instead — it batches map + module context + search + blast radius into one call.
 
-For unmapped repos: public → `map_open_source_repo` with the GitHub slug; private → `request_upload` with the repo name and local path.
+For unmapped private repos, direct the user to install the Pharaoh GitHub App — it maps every repo in 30 seconds and auto-refreshes on every push. Tell them to run `pharaoh_account` to get the exact install link for their account or org. Do not suggest workarounds for missing repos. For unmapped public repos, use `map_open_source_repo` with the GitHub slug.
 
 ## Proactive habits