@pharaoh-so/mcp 0.3.42 → 0.3.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/commands/review.md +49 -40
  2. package/inspect-tools.json +2 -2
  3. package/package.json +1 -1
  4. package/skills/review/SKILL.md +51 -42
package/commands/review.md CHANGED
@@ -4,7 +4,7 @@ description: Architecture-aware code review with Pharaoh
4
4
 
5
5
  # Review with Pharaoh
6
6
 
7
- 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.
7
+ The definitive code review, for any codebase. Architecture-aware, branch-aware, multi-agent, adversarial. Five phases that combine Pharaoh's knowledge graph with parallel specialized reviewers and an independent second opinion. Every phase works without Pharaoh too; Pharaoh makes the architecture picture exact and cheap where it maps the repo.
8
8
 
9
9
  Final verdict: **SHIP** / **SHIP WITH CHANGES** / **BLOCK**
10
10
 
@@ -26,16 +26,17 @@ Before merging any branch. Before opening any PR. When reviewing changes that to
26
26
  git log --oneline -1 # latest commit
27
27
  ```
28
28
 
29
- 2. Determine the base branch (what this branch diverged from):
29
+ 2. Determine the base (where this branch diverged from the branch it merges into):
30
30
  ```bash
31
- git merge-base HEAD main # or master, or whatever the default is
31
+ DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD) # the default branch, e.g. origin/main
32
+ BASE=$(git merge-base HEAD "$DEFAULT") # use the PR's target branch if it isn't the default
32
33
  ```
33
34
 
34
35
  3. Collect the full changeset from the base:
35
36
  ```bash
36
- git diff --name-only $(git merge-base HEAD main)...HEAD # all changed files
37
- git diff --stat $(git merge-base HEAD main)...HEAD # summary stats
38
- git log --oneline $(git merge-base HEAD main)..HEAD # all commits on this branch
37
+ git diff --name-only "$BASE"...HEAD # all changed files
38
+ git diff --stat "$BASE"...HEAD # summary stats
39
+ git log --oneline "$BASE"..HEAD # all commits on this branch
39
40
  ```
40
41
 
41
42
  4. Also check for uncommitted work:
@@ -52,18 +53,34 @@ Before merging any branch. Before opening any PR. When reviewing changes that to
52
53
 
53
54
  ## Phase 1 — Pharaoh Recon
54
55
 
55
- **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.
56
+ **Goal:** Get the full architectural picture, and the project's own rules, before reading the diff in depth. Do NOT skip this phase: it is what makes this review architecture-aware instead of just a code diff review.
57
+
58
+ ### With Pharaoh
56
59
 
57
60
  Call `pharaoh_recon` with:
58
- - **repo:** The repository name
61
+ - **repo:** The repository name (if the name is wrong, Pharaoh replies with the repos it maps)
59
62
  - **include_map:** `true`
60
63
  - **modules:** The touched modules from Phase 0 (up to 5)
61
64
  - **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.
62
65
  - **dependencies:** Pairs of touched modules to trace coupling between (up to 3)
63
66
 
67
+ Pharaoh's graph maps the default branch, so it shows what the change lands on: callers, blast radius, module boundaries, endpoints. Code that is new on this branch isn't in it yet; read the diff for that.
68
+
69
+ ### Without Pharaoh (graceful fallback)
70
+
71
+ If Pharaoh isn't connected, or doesn't map this repo, build the same picture by hand:
72
+ 1. Read the top-level layout and the manifest files (package.json, pyproject.toml, go.mod, Cargo.toml) to find the module boundaries
73
+ 2. For each changed exported function or file, search for its callers to estimate the blast radius
74
+ 3. Read the entry points the change can reach: routes, CLI commands, jobs, event handlers
75
+ 4. Say in the review that the architecture context came from search, not the graph
76
+
77
+ ### The project's own rules
78
+
79
+ Read the rules the project states for itself: `CLAUDE.md` or `AGENTS.md` (including nested ones in touched directories), `CONTRIBUTING.md` and `SECURITY.md`, whichever exist. Note every rule stated as non-negotiable: testing requirements, security invariants, code style. They are what Phase 2's reviewers check the change against.
80
+
64
81
  Then read `docs/VISION.md` if the repo has one — the repo's architectural contract. For every touched module, find its relevant assertions. Any change touching code governed by a MUST-bullet must be checked against that assertion — if the change would violate the MUST, the verdict tips toward BLOCK unless VISION.md is updated in the same PR with user approval.
65
82
 
66
- **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, and spec alignment.
83
+ **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, the project's rules, and spec alignment.
67
84
 
68
85
  ---
69
86
 
@@ -75,8 +92,8 @@ Then read `docs/VISION.md` if the repo has one — the repo's architectural cont
75
92
 
76
93
  | Agent | When to dispatch | Focus |
77
94
  |-------|-----------------|-------|
78
- | **Code Reviewer** | Always | Bugs, logic errors, CLAUDE.md compliance, code quality. Confidence-filtered (only issues >= 80/100). |
79
- | **Security Reviewer** | When changes touch auth, encryption, tokens, tenant isolation, data access, billing, webhooks, Cypher queries, or any security-sensitive surface. Also dispatch when the Phase 1 blast radius marks the change as HIGH risk. | OWASP Top 10, injection vectors, access control bypasses, tenant isolation violations, cryptographic misuse, secret exposure, plus project-specific security rules. See checklist below. |
95
+ | **Code Reviewer** | Always | Bugs, logic errors, compliance with the project's rules, code quality. Confidence-filtered (only issues >= 80/100). |
96
+ | **Security Reviewer** | When changes touch any security-sensitive surface (see the detection triggers below). Also dispatch when the Phase 1 blast radius marks the change as HIGH risk. | OWASP Top 10, injection vectors, access control bypasses, tenant isolation in multi-tenant systems, cryptographic misuse, secret exposure, plus the project's own security rules. See checklist below. |
80
97
  | **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. |
81
98
  | **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. |
82
99
  | **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. |
@@ -86,7 +103,7 @@ Then read `docs/VISION.md` if the repo has one — the repo's architectural cont
86
103
  The Security Reviewer agent runs a systematic audit against two layers: universal web security (OWASP) and project-specific invariants.
87
104
 
88
105
  **Layer 1 — OWASP Top 10 + Common Vulnerabilities:**
89
- - **Injection:** SQL/Cypher injection, command injection, XSS (reflected/stored/DOM), template injection
106
+ - **Injection:** SQL, NoSQL and graph query injection, command injection, XSS (reflected/stored/DOM), template injection
90
107
  - **Broken auth:** Hardcoded credentials, weak token generation, missing expiry, session fixation
91
108
  - **Broken access control:** Missing authorization checks, IDOR, privilege escalation, path traversal
92
109
  - **Cryptographic failures:** Weak algorithms, plaintext secrets, missing encryption at rest/transit, key exposure
@@ -95,29 +112,22 @@ The Security Reviewer agent runs a systematic audit against two layers: universa
95
112
  - **SSRF:** Unvalidated URLs in fetch/request calls, redirect chains
96
113
  - **Logging & monitoring:** Sensitive data in logs, missing audit trails for privileged operations
97
114
 
98
- **Layer 2 — Project-Specific Security Rules (from CLAUDE.md):**
99
- - Every Cypher query takes `repo` as first parameter — no unanchored MATCH clauses
100
- - `validateRepoOwnership()` runs before every tool handler
101
- - No default/fallback repo values — repo always from tenant's Postgres `tenant_repos`
102
- - Tokens stored as SHA-256 hashes, never plaintext
103
- - GitHub tokens encrypted at rest (AES-256-GCM with per-tenant HKDF-derived keys)
104
- - Webhook signatures verified on every request (`PHARAOH_GITHUB_WEBHOOK_SECRET`)
105
- - Org membership re-checked on every token refresh
106
- - Tenant Neo4j users get `reader` role only — graph writes use admin connection
107
- - Rate limiting enforced per tenant, not per user
108
- - Neo4j admin credentials never leave server-side env vars
109
-
110
- **Detection triggers (auto-dispatch when changed files match):**
111
- - `src/auth/**`, `src/crypto/**` — authentication, encryption
112
- - `src/mcp/server.ts`, `src/mcp/tenant-resolver.ts` — session management, tenant isolation
113
- - `src/mcp/neo4j-queries.ts` — Cypher query construction
114
- - `src/stripe/**`, `src/web/routes/billing.ts` — payment flows
115
- - `src/github/webhooks.ts`, `src/web/routes/webhooks.ts` — webhook verification
116
- - `src/db/**` — database access, schema changes
117
- - Any file containing `validateRepoOwnership`, `runQuery`, `encryptProperty`, `verifyWebhookSignature`
115
+ **Layer 2 — The project's own security rules:**
116
+ Take them from the rules collected in Phase 1 (`CLAUDE.md`, `AGENTS.md`, `SECURITY.md`, `docs/VISION.md`) and check each one against the diff by name. Rules like "every query is scoped to the caller's tenant", "tokens are stored hashed" and "webhooks verify their signature" are what this layer exists for. If the project states none, work out its threat model from the code: who the users and tenants are, where secrets live, which inputs are untrusted.
117
+
118
+ **Detection triggers (dispatch when the change touches any of these):**
119
+ - Authentication, sessions, tokens, permissions, and the middleware that guards routes
120
+ - Cryptography, secrets, key handling, and environment variables that hold credentials
121
+ - Query construction and data access (SQL, raw ORM queries, NoSQL, graph queries), schema migrations
122
+ - Payments, billing, subscriptions
123
+ - Webhooks, signature verification, third-party callbacks
124
+ - File paths, uploads, shell commands or URLs built from user input
125
+ - Anything the project's rules call security-sensitive
126
+
127
+ With Pharaoh, find these structurally: `get_module_context` on a touched module lists its endpoints, database tables and environment variables, and `get_blast_radius` shows the endpoints, jobs and database operations a changed function reaches. A change that reaches an endpoint, a table or a secret is security-sensitive. Without Pharaoh, match on file paths and names (auth, session, token, crypto, middleware, webhook, billing, payment, migration).
118
128
 
119
129
  **Output format:** Each finding must include:
120
- 1. Vulnerability class (e.g., "Cypher Injection", "Missing Ownership Check")
130
+ 1. Vulnerability class (e.g., "SQL Injection", "Missing Authorization Check")
121
131
  2. Severity: CRITICAL / HIGH / MEDIUM
122
132
  3. Affected file:line
123
133
  4. Attack scenario: how an attacker would exploit this
@@ -127,10 +137,10 @@ The Security Reviewer agent runs a systematic audit against two layers: universa
127
137
 
128
138
  For each agent, launch a subagent (via the Agent tool) with:
129
139
  1. The **git diff** of the relevant changed files (not the full session history)
130
- 2. The **Pharaoh context** from Phase 1 (architecture map, blast radius, module profiles) — this is what makes these agents architecture-aware
131
- 3. The **CLAUDE.md rules** relevant to the review (testing requirements, security non-negotiables, code style)
140
+ 2. The **architecture context** from Phase 1 (architecture map, blast radius, module profiles, from Pharaoh or the fallback) — this is what makes these agents architecture-aware
141
+ 3. The **project's rules** from Phase 1 that bear on the review (testing requirements, security rules, code style)
132
142
  4. A clear instruction to focus ONLY on changed code, not pre-existing issues
133
- 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
143
+ 5. For the **Security Reviewer** specifically: the project's security rules (Layer 2) and the security-sensitive files you found, so it knows the project's threat model
134
144
 
135
145
  Each agent returns a structured report with findings categorized by severity:
136
146
  - **CRITICAL** (90-100): Must fix before merge
@@ -152,7 +162,7 @@ Each agent returns a structured report with findings categorized by severity:
152
162
 
153
163
  Trigger Phase 3 when ANY of these are true:
154
164
  - Changes touch **auth, encryption, access control, token handling, or session management**
155
- - Changes touch **tenant isolation, query construction, or data access patterns**
165
+ - Changes touch **multi-tenant isolation, query construction, or data access patterns**
156
166
  - Changes touch **billing, subscription management, or payment flows**
157
167
  - Changes modify **webhook verification or signature checking**
158
168
  - The Phase 1 blast radius marks the change as **HIGH** risk
@@ -165,7 +175,7 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
165
175
  1. **Prepare a review package** — do NOT send your session history:
166
176
  - The changed files (full diff or complete file contents)
167
177
  - What the code does and why it was changed (1-2 sentences)
168
- - Security constraints from CLAUDE.md (tenant isolation rules, encryption requirements, etc.)
178
+ - The project's security rules from Phase 1 (tenant isolation, encryption requirements, etc.)
169
179
  - Specific concerns you want the reviewer to focus on
170
180
 
171
181
  2. **Dispatch to an independent subagent** with instructions to evaluate the code fresh and assign verdicts:
@@ -248,8 +258,7 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
248
258
  - Vision spec drift: new complex function has no matching assertion AND the domain it lives in has existing assertions (implies invariants are expected here)
249
259
  - Any CRITICAL finding from Phase 2 or Phase 3 that is confirmed and unfixed
250
260
  - DISAGREE verdict from adversarial review on security-sensitive code, confirmed after verification
251
- - Unanchored Cypher query (MATCH without traversing through `Repo {name: $repo}`)
252
- - Missing `validateRepoOwnership()` on a new tool handler
261
+ - A violation of a security rule the project states as non-negotiable (Phase 1), such as a query that skips the project's tenant scoping or a handler that skips its authorization check
253
262
 
254
263
  ### SHIP WITH CHANGES triggers
255
264
 
package/inspect-tools.json CHANGED
@@ -299,7 +299,7 @@
299
299
  },
300
300
  {
301
301
  "name": "pharaoh_account",
302
- "description": "Your Pharaoh plan, live repo and refreshes.\n\nPick one action and provide its fields; invalid combinations are rejected.\n\n• status: each workspace's plan and live repo, the upgrade link, the setup page\n• set_free_repo { repo }: change a free workspace's live repo\n• refresh_repo { repo, full? }: re-map one live repo now\n\nCALL THIS WHEN:\n• You want to know what plan you're on or which repo is live\n• A repo doesn't answer because it isn't live, or you want to switch which one is\n• You want to upgrade so every repo is live, or manage billing\n• You want a repo's graph refreshed before its next push\n\nFlag reference:\n full = force a full remap, bypassing the incremental diff.",
302
+ "description": "Your Pharaoh plan, live repo and refreshes.\n\nPick one action and provide its fields; invalid combinations are rejected.\n\n• status: each workspace's plan and live repo, the upgrade link, the setup page\n• set_free_repo { repo }: change a free workspace's live repo\n• refresh_repo { repo, full? }: re-map one live repo now\n\nCALL THIS WHEN:\n• You want to know what plan you're on or which repo is live\n• A repo doesn't answer because it isn't live, or you want to switch which one is\n• You want to upgrade so every repo is live, or manage billing\n• You want a repo's graph refreshed before its next push\n\nFlag reference:\n full = force a full rebuild, skipping the delta refresh.",
303
303
  "inputSchema": {
304
304
  "$schema": "http://json-schema.org/draft-07/schema#",
305
305
  "type": "object",
@@ -318,7 +318,7 @@
318
318
  "type": "string"
319
319
  },
320
320
  "full": {
321
- "description": "Used by: refresh_repo. Force a full remap, bypassing the incremental diff.",
321
+ "description": "Used by: refresh_repo. Force a full rebuild, skipping the delta refresh.",
322
322
  "type": "boolean"
323
323
  }
324
324
  },
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@pharaoh-so/mcp",
3
3
  "mcpName": "so.pharaoh/pharaoh",
4
- "version": "0.3.42",
4
+ "version": "0.3.44",
5
5
  "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.",
6
6
  "type": "module",
7
7
  "main": "dist/index.js",
package/skills/review/SKILL.md CHANGED
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: review
3
3
  prompt-name: review-with-pharaoh
4
- description: "The definitive code review. Five-phase workflow: git context detection (worktree, branch, base, changed files), Pharaoh recon (architecture map, module context, blast radius in one call), parallel specialized agent dispatch (code quality, error handling, test coverage, type design), cross-model adversarial review for security-sensitive changes, and a final synthesized verdict of SHIP / SHIP WITH CHANGES / BLOCK. Always architecture-aware, always branch-aware."
5
- version: 0.3.0
4
+ description: "The definitive code review, for any codebase. Five-phase workflow: git context detection (worktree, branch, base, changed files), Pharaoh recon (architecture map, module context, blast radius in one call, with a fallback when the repo isn't mapped), parallel specialized agent dispatch (code quality, security against the project's own rules, error handling, test coverage, type design), adversarial review for security-sensitive changes, and a final synthesized verdict of SHIP / SHIP WITH CHANGES / BLOCK. Architecture-aware wherever Pharaoh maps the repo, always branch-aware."
5
+ version: 0.4.0
6
6
  homepage: https://pharaoh.so
7
7
  user-invocable: true
8
8
  metadata: {"emoji": "☥", "tags": ["code-review", "pull-request", "architecture", "pharaoh", "multi-agent", "adversarial-review", "regression-risk", "spec-alignment"]}
@@ -10,7 +10,7 @@ metadata: {"emoji": "☥", "tags": ["code-review", "pull-request", "architecture
10
10
 
11
11
  # Review with Pharaoh
12
12
 
13
- 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.
13
+ The definitive code review, for any codebase. Architecture-aware, branch-aware, multi-agent, adversarial. Five phases that combine Pharaoh's knowledge graph with parallel specialized reviewers and an independent second opinion. Every phase works without Pharaoh too; Pharaoh makes the architecture picture exact and cheap where it maps the repo.
14
14
 
15
15
  Final verdict: **SHIP** / **SHIP WITH CHANGES** / **BLOCK**
16
16
 
@@ -32,16 +32,17 @@ Before merging any branch. Before opening any PR. When reviewing changes that to
32
32
  git log --oneline -1 # latest commit
33
33
  ```
34
34
 
35
- 2. Determine the base branch (what this branch diverged from):
35
+ 2. Determine the base (where this branch diverged from the branch it merges into):
36
36
  ```bash
37
- git merge-base HEAD main # or master, or whatever the default is
37
+ DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD) # the default branch, e.g. origin/main
38
+ BASE=$(git merge-base HEAD "$DEFAULT") # use the PR's target branch if it isn't the default
38
39
  ```
39
40
 
40
41
  3. Collect the full changeset from the base:
41
42
  ```bash
42
- git diff --name-only $(git merge-base HEAD main)...HEAD # all changed files
43
- git diff --stat $(git merge-base HEAD main)...HEAD # summary stats
44
- git log --oneline $(git merge-base HEAD main)..HEAD # all commits on this branch
43
+ git diff --name-only "$BASE"...HEAD # all changed files
44
+ git diff --stat "$BASE"...HEAD # summary stats
45
+ git log --oneline "$BASE"..HEAD # all commits on this branch
45
46
  ```
46
47
 
47
48
  4. Also check for uncommitted work:
@@ -58,18 +59,34 @@ Before merging any branch. Before opening any PR. When reviewing changes that to
58
59
 
59
60
  ## Phase 1 — Pharaoh Recon
60
61
 
61
- **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.
62
+ **Goal:** Get the full architectural picture, and the project's own rules, before reading the diff in depth. Do NOT skip this phase: it is what makes this review architecture-aware instead of just a code diff review.
63
+
64
+ ### With Pharaoh
62
65
 
63
66
  Call `pharaoh_recon` with:
64
- - **repo:** The repository name
67
+ - **repo:** The repository name (if the name is wrong, Pharaoh replies with the repos it maps)
65
68
  - **include_map:** `true`
66
69
  - **modules:** The touched modules from Phase 0 (up to 5)
67
70
  - **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.
68
71
  - **dependencies:** Pairs of touched modules to trace coupling between (up to 3)
69
72
 
73
+ Pharaoh's graph maps the default branch, so it shows what the change lands on: callers, blast radius, module boundaries, endpoints. Code that is new on this branch isn't in it yet; read the diff for that.
74
+
75
+ ### Without Pharaoh (graceful fallback)
76
+
77
+ If Pharaoh isn't connected, or doesn't map this repo, build the same picture by hand:
78
+ 1. Read the top-level layout and the manifest files (package.json, pyproject.toml, go.mod, Cargo.toml) to find the module boundaries
79
+ 2. For each changed exported function or file, search for its callers to estimate the blast radius
80
+ 3. Read the entry points the change can reach: routes, CLI commands, jobs, event handlers
81
+ 4. Say in the review that the architecture context came from search, not the graph
82
+
83
+ ### The project's own rules
84
+
85
+ Read the rules the project states for itself: `CLAUDE.md` or `AGENTS.md` (including nested ones in touched directories), `CONTRIBUTING.md` and `SECURITY.md`, whichever exist. Note every rule stated as non-negotiable: testing requirements, security invariants, code style. They are what Phase 2's reviewers check the change against.
86
+
70
87
  Then read `docs/VISION.md` if the repo has one — the repo's architectural contract. For every touched module, find its relevant assertions. Any change touching code governed by a MUST-bullet must be checked against that assertion — if the change would violate the MUST, the verdict tips toward BLOCK unless VISION.md is updated in the same PR with user approval.
71
88
 
72
- **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, and spec alignment.
89
+ **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, the project's rules, and spec alignment.
73
90
 
74
91
  ---
75
92
 
@@ -81,8 +98,8 @@ Then read `docs/VISION.md` if the repo has one — the repo's architectural cont
81
98
 
82
99
  | Agent | When to dispatch | Focus |
83
100
  |-------|-----------------|-------|
84
- | **Code Reviewer** | Always | Bugs, logic errors, CLAUDE.md compliance, code quality. Confidence-filtered (only issues >= 80/100). |
85
- | **Security Reviewer** | When changes touch auth, encryption, tokens, tenant isolation, data access, billing, webhooks, Cypher queries, or any security-sensitive surface. Also dispatch when the Phase 1 blast radius marks the change as HIGH risk. | OWASP Top 10, injection vectors, access control bypasses, tenant isolation violations, cryptographic misuse, secret exposure, plus project-specific security rules. See checklist below. |
101
+ | **Code Reviewer** | Always | Bugs, logic errors, compliance with the project's rules, code quality. Confidence-filtered (only issues >= 80/100). |
102
+ | **Security Reviewer** | When changes touch any security-sensitive surface (see the detection triggers below). Also dispatch when the Phase 1 blast radius marks the change as HIGH risk. | OWASP Top 10, injection vectors, access control bypasses, tenant isolation in multi-tenant systems, cryptographic misuse, secret exposure, plus the project's own security rules. See checklist below. |
86
103
  | **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. |
87
104
  | **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. |
88
105
  | **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. |
@@ -92,7 +109,7 @@ Then read `docs/VISION.md` if the repo has one — the repo's architectural cont
92
109
  The Security Reviewer agent runs a systematic audit against two layers: universal web security (OWASP) and project-specific invariants.
93
110
 
94
111
  **Layer 1 — OWASP Top 10 + Common Vulnerabilities:**
95
- - **Injection:** SQL/Cypher injection, command injection, XSS (reflected/stored/DOM), template injection
112
+ - **Injection:** SQL, NoSQL and graph query injection, command injection, XSS (reflected/stored/DOM), template injection
96
113
  - **Broken auth:** Hardcoded credentials, weak token generation, missing expiry, session fixation
97
114
  - **Broken access control:** Missing authorization checks, IDOR, privilege escalation, path traversal
98
115
  - **Cryptographic failures:** Weak algorithms, plaintext secrets, missing encryption at rest/transit, key exposure
@@ -101,29 +118,22 @@ The Security Reviewer agent runs a systematic audit against two layers: universa
101
118
  - **SSRF:** Unvalidated URLs in fetch/request calls, redirect chains
102
119
  - **Logging & monitoring:** Sensitive data in logs, missing audit trails for privileged operations
103
120
 
104
- **Layer 2 — Project-Specific Security Rules (from CLAUDE.md):**
105
- - Every Cypher query takes `repo` as first parameter — no unanchored MATCH clauses
106
- - `validateRepoOwnership()` runs before every tool handler
107
- - No default/fallback repo values — repo always from tenant's Postgres `tenant_repos`
108
- - Tokens stored as SHA-256 hashes, never plaintext
109
- - GitHub tokens encrypted at rest (AES-256-GCM with per-tenant HKDF-derived keys)
110
- - Webhook signatures verified on every request (`PHARAOH_GITHUB_WEBHOOK_SECRET`)
111
- - Org membership re-checked on every token refresh
112
- - Tenant Neo4j users get `reader` role only — graph writes use admin connection
113
- - Rate limiting enforced per tenant, not per user
114
- - Neo4j admin credentials never leave server-side env vars
115
-
116
- **Detection triggers (auto-dispatch when changed files match):**
117
- - `src/auth/**`, `src/crypto/**` — authentication, encryption
118
- - `src/mcp/server.ts`, `src/mcp/tenant-resolver.ts` — session management, tenant isolation
119
- - `src/mcp/neo4j-queries.ts` — Cypher query construction
120
- - `src/stripe/**`, `src/web/routes/billing.ts` — payment flows
121
- - `src/github/webhooks.ts`, `src/web/routes/webhooks.ts` — webhook verification
122
- - `src/db/**` — database access, schema changes
123
- - Any file containing `validateRepoOwnership`, `runQuery`, `encryptProperty`, `verifyWebhookSignature`
121
+ **Layer 2 — The project's own security rules:**
122
+ Take them from the rules collected in Phase 1 (`CLAUDE.md`, `AGENTS.md`, `SECURITY.md`, `docs/VISION.md`) and check each one against the diff by name. Rules like "every query is scoped to the caller's tenant", "tokens are stored hashed" and "webhooks verify their signature" are what this layer exists for. If the project states none, work out its threat model from the code: who the users and tenants are, where secrets live, which inputs are untrusted.
123
+
124
+ **Detection triggers (dispatch when the change touches any of these):**
125
+ - Authentication, sessions, tokens, permissions, and the middleware that guards routes
126
+ - Cryptography, secrets, key handling, and environment variables that hold credentials
127
+ - Query construction and data access (SQL, raw ORM queries, NoSQL, graph queries), schema migrations
128
+ - Payments, billing, subscriptions
129
+ - Webhooks, signature verification, third-party callbacks
130
+ - File paths, uploads, shell commands or URLs built from user input
131
+ - Anything the project's rules call security-sensitive
132
+
133
+ With Pharaoh, find these structurally: `get_module_context` on a touched module lists its endpoints, database tables and environment variables, and `get_blast_radius` shows the endpoints, jobs and database operations a changed function reaches. A change that reaches an endpoint, a table or a secret is security-sensitive. Without Pharaoh, match on file paths and names (auth, session, token, crypto, middleware, webhook, billing, payment, migration).
124
134
 
125
135
  **Output format:** Each finding must include:
126
- 1. Vulnerability class (e.g., "Cypher Injection", "Missing Ownership Check")
136
+ 1. Vulnerability class (e.g., "SQL Injection", "Missing Authorization Check")
127
137
  2. Severity: CRITICAL / HIGH / MEDIUM
128
138
  3. Affected file:line
129
139
  4. Attack scenario: how an attacker would exploit this
@@ -133,10 +143,10 @@ The Security Reviewer agent runs a systematic audit against two layers: universa
133
143
 
134
144
  For each agent, launch a subagent (via the Agent tool) with:
135
145
  1. The **git diff** of the relevant changed files (not the full session history)
136
- 2. The **Pharaoh context** from Phase 1 (architecture map, blast radius, module profiles) — this is what makes these agents architecture-aware
137
- 3. The **CLAUDE.md rules** relevant to the review (testing requirements, security non-negotiables, code style)
146
+ 2. The **architecture context** from Phase 1 (architecture map, blast radius, module profiles, from Pharaoh or the fallback) — this is what makes these agents architecture-aware
147
+ 3. The **project's rules** from Phase 1 that bear on the review (testing requirements, security rules, code style)
138
148
  4. A clear instruction to focus ONLY on changed code, not pre-existing issues
139
- 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
149
+ 5. For the **Security Reviewer** specifically: the project's security rules (Layer 2) and the security-sensitive files you found, so it knows the project's threat model
140
150
 
141
151
  Each agent returns a structured report with findings categorized by severity:
142
152
  - **CRITICAL** (90-100): Must fix before merge
@@ -158,7 +168,7 @@ Each agent returns a structured report with findings categorized by severity:
158
168
 
159
169
  Trigger Phase 3 when ANY of these are true:
160
170
  - Changes touch **auth, encryption, access control, token handling, or session management**
161
- - Changes touch **tenant isolation, query construction, or data access patterns**
171
+ - Changes touch **multi-tenant isolation, query construction, or data access patterns**
162
172
  - Changes touch **billing, subscription management, or payment flows**
163
173
  - Changes modify **webhook verification or signature checking**
164
174
  - The Phase 1 blast radius marks the change as **HIGH** risk
@@ -171,7 +181,7 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
171
181
  1. **Prepare a review package** — do NOT send your session history:
172
182
  - The changed files (full diff or complete file contents)
173
183
  - What the code does and why it was changed (1-2 sentences)
174
- - Security constraints from CLAUDE.md (tenant isolation rules, encryption requirements, etc.)
184
+ - The project's security rules from Phase 1 (tenant isolation, encryption requirements, etc.)
175
185
  - Specific concerns you want the reviewer to focus on
176
186
 
177
187
  2. **Dispatch to an independent subagent** with instructions to evaluate the code fresh and assign verdicts:
@@ -254,8 +264,7 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
254
264
  - Vision spec drift: new complex function has no matching assertion AND the domain it lives in has existing assertions (implies invariants are expected here)
255
265
  - Any CRITICAL finding from Phase 2 or Phase 3 that is confirmed and unfixed
256
266
  - DISAGREE verdict from adversarial review on security-sensitive code, confirmed after verification
257
- - Unanchored Cypher query (MATCH without traversing through `Repo {name: $repo}`)
258
- - Missing `validateRepoOwnership()` on a new tool handler
267
+ - A violation of a security rule the project states as non-negotiable (Phase 1), such as a query that skips the project's tenant scoping or a handler that skips its authorization check
259
268
 
260
269
  ### SHIP WITH CHANGES triggers
261
270