@pharaoh-so/mcp 0.3.15 → 0.3.17

package/commands/plan.md

@@ -1,5 +1,142 @@
 ---
-description: Architecture-aware planning with Pharaoh reconnaissance
+description: Architecture-aware planning with Pharaoh reconnaissance (adapted from Garry Tan's planning framework)
 ---
 
-Invoke the `pharaoh-plan` skill to handle this request. Pass through any arguments: $ARGUMENTS
+# Plan Review
+
+Architecture-aware plan review before implementation. Adapted from [Garry Tan's planning framework](https://www.youtube.com/watch?v=bMknfKXIFA8) for AI-assisted development.
+
+**You are now in plan mode. Do NOT make any code changes. Think, evaluate, and present decisions.**
+
+## Document Review
+
+If the user provides a document, PRD, prompt, or artifact alongside this command, that IS the plan to review. Apply all review sections to that document. Do not treat it as background context — it is the subject of evaluation.
+
+Still run Step 1 (Reconnaissance) even when reviewing a document — always verify the plan against the actual codebase state.
+
+## Project Overrides
+
+If a `.claude/plan-review.md` file exists in this project, read it now and apply those rules on top of this baseline. Project rules take precedence where they conflict.
+
+## Engineering Preferences (guide all recommendations)
+
+- DRY: flag repetition aggressively
+- Well-tested: too many tests > too few; mutation score > line coverage
+- "Engineered enough" — not fragile/hacky, not over-abstracted
+- Handle more edge cases, not fewer; thoughtfulness > speed
+- Explicit > clever; simple > complex
+- Subtraction > addition; target zero or negative net LOC
+- Every export must have a caller; unwired code doesn't exist
+
+## Step 1: Pharaoh Reconnaissance (Required — do this BEFORE reviewing)
+
+Do NOT review from memory or assumptions. Query the actual codebase first.
+
+### If Pharaoh MCP tools are available:
+
+1. `get_codebase_map` — current modules, hot files, dependency graph
+2. `search_functions` for keywords related to the plan — find existing code to reuse/extend
+3. `get_module_context` on affected modules — entry points, patterns, conventions
+4. `query_dependencies` between affected modules — coupling, circular deps
+5. `get_blast_radius` on the primary target of the change — know what breaks
+6. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
+
+### Without Pharaoh (graceful fallback):
+
+1. Search the codebase for files and functions related to the plan (grep, glob)
+2. Read the entry points and module structure of affected areas
+3. Check existing tests for the modules the plan will touch
+4. Trace imports manually to estimate blast radius
+
+Ground every recommendation in what actually exists. If you propose adding something, confirm it doesn't already exist. If you propose changing something, know its blast radius.
+
+## Step 2: Mode Selection (MANDATORY — ask before proceeding)
+
+**STOP and ask the user which mode before starting the review.** This is a hard gate — do not infer, assume, or skip this question even if the user says "yes", "go ahead", or "yes to all". Present both options and wait for an explicit choice:
+
+> **BIG CHANGE or SMALL CHANGE?**
+>
+> - **BIG CHANGE**: Full interactive review, all relevant sections, up to 4 top issues per section
+> - **SMALL CHANGE**: One question per section, only sections 2-4
+
+If the user's response is ambiguous (e.g. "just do it", "yes to all"), ask again: "I need to know — BIG or SMALL change?" Do not proceed to Step 3 without an answer.
+
+## Step 3: Review Sections
+
+Adapt depth to change size. Skip sections that don't apply. **After each section, pause and ask for feedback before moving on.**
+
+### Section 1 — Architecture (skip for small/single-file changes)
+
+- Component boundaries and coupling concerns
+- Dependency graph: does this change shrink or expand surface area?
+- Data flow bottlenecks and single points of failure
+- Does this need new code at all, or can a human process / existing pattern solve it?
+
+### Section 2 — Code Quality (always)
+
+- Organization, module structure, DRY violations (be aggressive)
+- Error handling gaps and missing edge cases (call out explicitly)
+- Technical debt: shortcuts, hardcoded values, magic strings
+- Over-engineered or under-engineered relative to my preferences
+- Reuse: does code for this already exist somewhere?
+
+### Section 3 — Wiring & Integration (always)
+
+- Are all new exports called from a production entry point?
+- Run `get_blast_radius` on any new/changed functions — zero callers = not done
+- `check_reachability` on new exports — verify reachable from API handlers, crons, or event handlers
+- Does the plan declare WHERE new code gets called from? If not, flag it
+- Integration points: how does this connect to what already exists?
+
+### Section 4 — Tests (always)
+
+- Coverage gaps: unit, integration, e2e
+- Test quality: real assertions with hardcoded expected values, not `.toBeDefined()` or computed expectations
+- Missing edge cases and untested failure/error paths
+- One integration test proving wiring > ten isolated unit tests
+
+### Section 5 — Performance (only if relevant)
+
+- N+1 queries, unnecessary DB round-trips
+- Memory concerns, caching opportunities
+- Slow or high-complexity code paths
+
+### Section 6 — Security & Attack Surface (always for new endpoints/routes/APIs; skip for pure refactors)
+
+- **Authentication model** — what authenticates requests in this plan? Where is it validated? What happens on auth failure (redirect, 401, silent pass-through)? Use `search_functions` to find existing auth middleware and confirm reuse.
+- **Sensitive data in URLs** — does the design put tokens, session IDs, or tenant identifiers in URL paths or query params? These leak via Referer headers, browser history, logs, and link sharing.
+- **Authorization boundaries** — what prevents User A from accessing User B's data? Is there an ownership check, or just an "is logged in" check? Use `get_blast_radius` on existing ownership-check functions to see where they're already enforced.
+- **Input trust boundary** — does the plan accept user input that flows into shell commands, database queries, HTML rendering, or file paths? Each is an injection vector.
+- **Error and response surface** — will error responses or API payloads expose internals (stack traces, DB schemas, internal IDs) to unauthenticated callers?
+- **New attack surface** — does the plan introduce new public URLs, webhooks, API routes, or WebSocket endpoints? Each needs: rate limiting, authentication, and input validation. Use `get_module_context` on the receiving module to check what protections exist.
+
+## For Each Issue Found
+
+For every specific issue (bug, smell, design concern, risk, missing wiring):
+
+1. **Describe concretely** — file, line/function reference, what's wrong
+2. **Present 2-3 options** including "do nothing" where reasonable
+3. **For each option** — implementation effort, risk, blast radius, maintenance burden
+4. **Recommend one** mapped to my preferences above, and say why
+5. **Ask** whether I agree or want a different direction
+
+Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended option is always listed first. Use AskUserQuestion with clear labels like "Issue 1 Option A", "Issue 1 Option B".
+
+## Pharaoh Checkpoints (use throughout, not just at the end)
+
+- **Before reviewing**: recon (Step 1 above)
+- **During review**: `get_blast_radius` when evaluating impact of changes; `search_functions` before suggesting new code
+- **After decisions**: `check_reachability` on all new exports; `get_unused_code` to catch disconnections
+- **Final sweep**: `get_blast_radius` on ALL new exports — zero callers on non-entry-points = plan is incomplete
+
+## Workflow Rules
+
+- **After each section, pause and ask for feedback before moving on**
+- Do not assume priorities on timeline or scale
+- If you see a better approach to the entire plan, say so BEFORE section-by-section review
+- Challenge the approach if you see a better one — your job is to find problems I'll regret later
+---
+
+Here is the task to review:
+
+$ARGUMENTS

package/dist/install-skills.js

@@ -31,6 +31,15 @@ const BUNDLED_COMMANDS_DIR = join(PKG_ROOT, "commands");
  * get collision-safe distinctive names on this install path.
  */
 const SKILL_PREFIX = "pharaoh-";
+/**
+ * Filename of the install manifest written alongside the installed skills.
+ * Records which skills we installed in the previous run so the next run can
+ * diff against current source and remove skills that were cut or renamed
+ * between versions. See `cleanupRemovedSkills` for the diff logic.
+ */
+const MANIFEST_FILENAME = ".pharaoh-manifest.json";
+/** Current manifest format version. Bump on breaking shape changes. */
+const MANIFEST_VERSION = 1;
 // ── Detection ───────────────────────────────────────────────────────
 /**
  * Detect whether Claude Code is installed by checking for ~/.claude/.
@@ -83,12 +92,25 @@ function installClaudeCodePlugin(home = homedir()) {
     }
     // Install skills under the pharaoh- prefix for collision-safe names.
     const skillsDst = join(pluginDir, "skills");
+    // Read the previous install's manifest BEFORE copying fresh skills so
+    // the diff logic below sees the old state. Missing/corrupt manifest
+    // returns null → cleanupRemovedSkills becomes a no-op (first-run fallback).
+    const oldManifest = readPharaohManifest(skillsDst);
     const skillCount = installPrefixedSkills(BUNDLED_SKILLS_DIR, skillsDst, SKILL_PREFIX);
-    // Migrate: delete any bare-name skill dirs left from prior installs
-    // that used the dual bare+prefixed layout. Without this, users who
-    // upgrade keep both copies and Claude Code's prompt-name dedupe picks
-    // the wrong one.
+    // Legacy dual-layout cleanup: delete bare-name dirs matching CURRENT
+    // source skills. Still runs on every install because the manifest path
+    // doesn't know about bare-name stragglers for skills that are still in
+    // source — only about cuts.
     cleanupBareNameSkills(BUNDLED_SKILLS_DIR, skillsDst);
+    // Manifest-based cut cleanup: for any skill that was in the previous
+    // install's manifest but is no longer in current source, remove both
+    // its bare-name and pharaoh-prefixed variants. Heals the token-burn
+    // from cut/renamed skills between versions (see #788).
+    cleanupRemovedSkills(BUNDLED_SKILLS_DIR, skillsDst, oldManifest);
+    // Stamp a fresh manifest reflecting exactly what's in current source.
+    // Written AFTER install + cleanup so it always matches on-disk state,
+    // even if a corrupt old manifest caused the diff step to skip.
+    writePharaohManifest(skillsDst, getSourceSkillNames(BUNDLED_SKILLS_DIR));
     // Copy .mcp.json
     const mcpSrc = join(PKG_ROOT, ".mcp.json");
     if (existsSync(mcpSrc)) {
@@ -150,6 +172,10 @@ function installPrefixedSkills(srcDir, dstDir, prefix) {
  * skills from other sources that happen to share the `pharaoh/skills/`
  * install path).
  *
+ * This is the LEGACY cleanup — it only heals the bare+prefixed dual
+ * layout for skills that are STILL in source. Skills cut between
+ * versions are handled by `cleanupRemovedSkills` via the manifest.
+ *
  * @param srcDir - Bundled source skills directory.
  * @param dstDir - Installed skills directory.
  * @returns Number of stale directories removed.
@@ -171,6 +197,123 @@ function cleanupBareNameSkills(srcDir, dstDir) {
     }
     return removed;
 }
+/**
+ * Enumerate the bare source skill names by listing the source skills dir.
+ * Returns the names that `installPrefixedSkills` would copy (directory
+ * entries that contain a `SKILL.md`). Used by both the manifest writer
+ * and the cleanup diff logic so the two stay in lockstep.
+ *
+ * @param srcDir - Bundled source skills directory.
+ * @returns Sorted array of bare skill dir names.
+ */
+function getSourceSkillNames(srcDir) {
+    if (!existsSync(srcDir))
+        return [];
+    const names = [];
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (!existsSync(join(srcDir, entry.name, "SKILL.md")))
+            continue;
+        names.push(entry.name);
+    }
+    return names.sort();
+}
+/**
+ * Read `.pharaoh-manifest.json` from the installed skills directory.
+ *
+ * Returns `null` when:
+ * - The file does not exist (first run after this fix shipped)
+ * - The file is corrupted or not valid JSON (treated as missing, caller
+ *   will write a fresh one on the next install cycle)
+ *
+ * Corrupted-manifest handling is silent-but-logged: we don't want a bad
+ * manifest to crash the install, but we do want a warning on stderr so
+ * operators can spot persistent corruption.
+ *
+ * @param skillsDir - Installed skills directory.
+ * @returns The parsed manifest, or `null` if missing/invalid.
+ */
+function readPharaohManifest(skillsDir) {
+    const manifestPath = join(skillsDir, MANIFEST_FILENAME);
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const raw = readFileSync(manifestPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        // Defensive shape check — a valid-JSON manifest with the wrong
+        // shape is as useful as no manifest, so we reject it and let the
+        // caller write a fresh one.
+        if (typeof parsed.version !== "number" ||
+            typeof parsed.installedAt !== "string" ||
+            !Array.isArray(parsed.skills) ||
+            !parsed.skills.every((s) => typeof s === "string")) {
+            process.stderr.write(`Pharaoh: ${MANIFEST_FILENAME} has unexpected shape — treating as missing and writing a fresh one.\n`);
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        process.stderr.write(`Pharaoh: ${MANIFEST_FILENAME} is not valid JSON — treating as missing and writing a fresh one.\n`);
+        return null;
+    }
+}
+/**
+ * Write a fresh manifest file listing the current install's bare skill
+ * names. Overwrites any existing manifest. The caller is responsible for
+ * ensuring the parent directory exists — `installPrefixedSkills` already
+ * does that as part of its own run, so writing the manifest after the
+ * install copy completes is safe.
+ *
+ * @param skillsDir - Installed skills directory.
+ * @param skills    - Bare skill names present in the current source.
+ */
+function writePharaohManifest(skillsDir, skills) {
+    const manifest = {
+        version: MANIFEST_VERSION,
+        installedAt: new Date().toISOString(),
+        skills: [...skills],
+    };
+    writeFileSync(join(skillsDir, MANIFEST_FILENAME), JSON.stringify(manifest, null, "\t"));
+}
+/**
+ * Diff-based cleanup of skills removed between versions.
+ *
+ * Reads the old manifest's skill list and removes any entry that's no
+ * longer in the current source. For each removed name, we delete BOTH
+ * the bare-name and `pharaoh-` prefixed variants — the dual-layout from
+ * the pre-prefix era means both can exist on the same machine for the
+ * same skill, and leaving either behind burns context on every session.
+ *
+ * The flagship `pharaoh` skill is exempt from deletion even if a corrupt
+ * manifest lists it as removed. Losing the flagship would break every
+ * skill slash command, and the exempt-name guard is the only thing
+ * preventing an accidental self-destruct.
+ *
+ * @param srcDir      - Bundled source skills directory.
+ * @param dstDir      - Installed skills directory.
+ * @param oldManifest - Manifest from the previous install, or `null` for
+ *   first-run-after-fix (in which case this is a no-op).
+ * @returns Number of directories removed.
+ */
+function cleanupRemovedSkills(srcDir, dstDir, oldManifest) {
+    if (!oldManifest || !existsSync(dstDir))
+        return 0;
+    const exemptName = SKILL_PREFIX.replace(/-$/, "");
+    const currentSkills = new Set(getSourceSkillNames(srcDir));
+    const removed = oldManifest.skills.filter((name) => !currentSkills.has(name) && name !== exemptName);
+    let deleted = 0;
+    for (const name of removed) {
+        for (const variant of [name, `${SKILL_PREFIX}${name}`]) {
+            const dir = join(dstDir, variant);
+            if (existsSync(dir)) {
+                rmSync(dir, { recursive: true, force: true });
+                deleted++;
+            }
+        }
+    }
+    return deleted;
+}
 /**
  * Copy bundled slash command templates (`.md` files in the package's
  * `commands/` directory) to `~/.claude/commands/`, unconditionally
@@ -275,10 +418,18 @@ export function installSkills(home = homedir()) {
     if (!existsSync(targetDir)) {
         mkdirSync(targetDir, { recursive: true });
     }
+    // Read previous manifest before copying fresh skills (same rationale as
+    // the Claude Code path — diff the old state against current source so
+    // cut/renamed skills get cleaned up instead of lingering forever).
+    const oldManifest = readPharaohManifest(targetDir);
     // Prefix skills for collision safety (same rationale as Claude Code path).
     const count = installPrefixedSkills(BUNDLED_SKILLS_DIR, targetDir, SKILL_PREFIX);
-    // Also clean up any bare-name leftovers from prior installs.
+    // Legacy dual-layout cleanup for bare-name stragglers of current skills.
     cleanupBareNameSkills(BUNDLED_SKILLS_DIR, targetDir);
+    // Manifest-based cut cleanup for skills removed between versions.
+    cleanupRemovedSkills(BUNDLED_SKILLS_DIR, targetDir, oldManifest);
+    // Stamp a fresh manifest reflecting current source.
+    writePharaohManifest(targetDir, getSourceSkillNames(BUNDLED_SKILLS_DIR));
     return count;
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "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",