archgen-mcp 0.0.6 → 0.0.7

package/README.md

@@ -42,7 +42,7 @@ Requires **Node.js >= 20** (the official MCP SDK v2 floor).
 | `archgen_tasks` | next wave · set status · list · resume snapshot · **contract** (the assembled worker prompt) |
 | `archgen_docs` | navigate markdown artifacts: section index, one section, token map, reference integrity |
 | `archgen_registry` | refresh / read the AGENTS.md features registry |
-| `archgen_codegraph` | install + wire + index CodeGraph and its MCP |
+| `archgen_codegraph` | install CodeGraph if it is missing · wire its MCP · index the project |
 | `archgen_setup` | doctor · bootstrap servers · install/remove the MCP · list harnesses · **harness_info** (a platform's capabilities) |
 | `archgen_ui` | drive the VS Code extension in real time |
 | `archgen_skills` | match / install / load external capability skills |
@@ -90,7 +90,7 @@ The skill declares the server version it needs:
 ```yaml
 metadata:
   requires:
-    archgen_mcp: ">=0.0.6"
+    archgen_mcp: ">=x.y.z"
 ```
 
 `archgen_setup { action: 'doctor' }` reports a mismatch, `bootstrap` warns
@@ -112,14 +112,23 @@ implementation of any capability, only a second way to reach it.
 
 ## Safety
 
+- The server owns a **boundary**: the directory it was started in. A tool's
+  `projectRoot` argument selects a directory *inside* that boundary — it
+  cannot redefine it, so a model cannot move the edge by naming a different
+  root.
 - Every path argument is resolved against the project root and refused if it
-  escapes; symlinked targets are never written through.
+  escapes; symlinked targets are never written through, and a symlinked
+  *parent* is caught by comparing real paths.
+- The artifact space is anchored to the project: a `.archgen` directory
+  elsewhere on the machine is not this project's artifacts.
 - MCP-config writes are approval-gated (`approve: true` / `--yes`); without
   approval the tool reports its **plan** and writes nothing.
 - A config file that cannot be parsed is reported, never rewritten.
 - Writes are atomic (temp file + rename): readers see old-or-new, never a
-  partial file.
-- UI commands are allowlisted, workspace-scoped, expiring, and idempotent.
+  partial file. A read-modify-write — a status update, a config merge — runs
+  under an exclusive lock, so two workers cannot lose each other's change.
+- UI commands are allowlisted, workspace-scoped, expiring, and idempotent;
+  the command queue is pruned, so it cannot grow without bound.
 
 ## License
 

package/assets/harness-mcp.json

@@ -15,7 +15,7 @@
     "mcp (opencode), context_servers (zed). Codex CLI uses TOML ([mcp_servers.<id>]).",
     "",
     "COMMAND SHAPE: the server entries below are the ones the official installers",
-    "write — keep them byte-compatible, or the MCP server never connects.",
+    "write \u2014 keep them byte-compatible, or the MCP server never connects.",
     "The CodeGraph server also runs a FILE WATCHER, so the index stays live after",
     "the one-time init; nothing is re-indexed by hand.",
     "",
@@ -25,135 +25,365 @@
   ],
   "package": "@colbymchenry/codegraph",
   "entries": {
-    "stdio": { "type": "stdio", "command": "codegraph", "args": ["serve", "--mcp"] },
-    "stdioNoType": { "command": "codegraph", "args": ["serve", "--mcp"] },
-    "opencodeLocal": { "type": "local", "command": ["codegraph", "serve", "--mcp"], "enabled": true }
+    "stdio": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": [
+        "serve",
+        "--mcp"
+      ]
+    },
+    "stdioNoType": {
+      "command": "codegraph",
+      "args": [
+        "serve",
+        "--mcp"
+      ]
+    },
+    "opencodeLocal": {
+      "type": "local",
+      "command": [
+        "codegraph",
+        "serve",
+        "--mcp"
+      ],
+      "enabled": true
+    }
   },
   "npxEntries": {
-    "stdio": { "type": "stdio", "command": "npx", "args": ["-y", "@colbymchenry/codegraph", "serve", "--mcp"] },
-    "stdioNoType": { "command": "npx", "args": ["-y", "@colbymchenry/codegraph", "serve", "--mcp"] },
-    "opencodeLocal": { "type": "local", "command": ["npx", "-y", "@colbymchenry/codegraph", "serve", "--mcp"], "enabled": true }
+    "stdio": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp"
+      ]
+    },
+    "stdioNoType": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp"
+      ]
+    },
+    "opencodeLocal": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp"
+      ],
+      "enabled": true
+    }
   },
   "archgenPackage": "archgen-mcp",
   "archgenEntries": {
-    "stdio": { "type": "stdio", "command": "archgen-mcp", "args": [] },
-    "stdioNoType": { "command": "archgen-mcp", "args": [] },
-    "opencodeLocal": { "type": "local", "command": ["archgen-mcp"], "enabled": true }
+    "stdio": {
+      "type": "stdio",
+      "command": "archgen-mcp",
+      "args": []
+    },
+    "stdioNoType": {
+      "command": "archgen-mcp",
+      "args": []
+    },
+    "opencodeLocal": {
+      "type": "local",
+      "command": [
+        "archgen-mcp"
+      ],
+      "enabled": true
+    }
   },
   "archgenNpxEntries": {
-    "stdio": { "type": "stdio", "command": "npx", "args": ["-y", "archgen-mcp"] },
-    "stdioNoType": { "command": "npx", "args": ["-y", "archgen-mcp"] },
-    "opencodeLocal": { "type": "local", "command": ["npx", "-y", "archgen-mcp"], "enabled": true }
+    "stdio": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "archgen-mcp"
+      ]
+    },
+    "stdioNoType": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "archgen-mcp"
+      ]
+    },
+    "opencodeLocal": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "archgen-mcp"
+      ],
+      "enabled": true
+    }
   },
   "harnesses": {
     "claude": {
       "label": "Claude Code",
       "codegraphTarget": "claude",
-      "detectHome": [".claude", ".claude.json"],
-      "detectProject": [".claude", ".mcp.json"],
+      "detectHome": [
+        ".claude",
+        ".claude.json"
+      ],
+      "detectProject": [
+        ".claude",
+        ".mcp.json"
+      ],
       "configs": {
-        "global": { "path": "~/.claude.json", "key": "mcpServers", "entry": "stdio" },
-        "project": { "path": ".mcp.json", "key": "mcpServers", "entry": "stdio" }
+        "global": {
+          "path": "~/.claude.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        },
+        "project": {
+          "path": ".mcp.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        }
       }
     },
     "cursor": {
       "label": "Cursor",
       "codegraphTarget": "cursor",
-      "detectHome": [".cursor"],
-      "detectProject": [".cursor"],
+      "detectHome": [
+        ".cursor"
+      ],
+      "detectProject": [
+        ".cursor"
+      ],
       "configs": {
-        "global": { "path": "~/.cursor/mcp.json", "key": "mcpServers", "entry": "stdio" },
-        "project": { "path": ".cursor/mcp.json", "key": "mcpServers", "entry": "stdio" }
+        "global": {
+          "path": "~/.cursor/mcp.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        },
+        "project": {
+          "path": ".cursor/mcp.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        }
       }
     },
     "opencode": {
       "label": "OpenCode",
       "codegraphTarget": "opencode",
-      "detectHome": [".config/opencode"],
-      "detectProject": [".opencode", "opencode.json", "opencode.jsonc"],
-      "_note": "OpenCode's global config is JSONC (opencode.jsonc) — codegraph's own installer writes it correctly; our writer refuses non-JSON files on purpose, so this entry is a fallback only.",
+      "detectHome": [
+        ".config/opencode"
+      ],
+      "detectProject": [
+        ".opencode",
+        "opencode.json",
+        "opencode.jsonc"
+      ],
+      "_note": "OpenCode's global config is JSONC (opencode.jsonc) \u2014 codegraph's own installer writes it correctly; our writer refuses non-JSON files on purpose, so this entry is a fallback only.",
       "configs": {
-        "global": { "path": "~/.config/opencode/opencode.json", "key": "mcp", "entry": "opencodeLocal" },
-        "project": { "path": "opencode.json", "key": "mcp", "entry": "opencodeLocal" }
+        "global": {
+          "path": "~/.config/opencode/opencode.json",
+          "format": "json",
+          "key": "mcp",
+          "entry": "opencodeLocal"
+        },
+        "project": {
+          "path": "opencode.json",
+          "format": "json",
+          "key": "mcp",
+          "entry": "opencodeLocal"
+        }
       }
     },
     "codex": {
       "label": "Codex CLI",
       "codegraphTarget": "codex",
-      "detectHome": [".codex"],
-      "detectProject": [".codex"],
+      "detectHome": [
+        ".codex"
+      ],
+      "detectProject": [
+        ".codex"
+      ],
       "configs": {
-        "global": { "path": "~/.codex/config.toml", "format": "toml", "key": "mcp_servers.codegraph", "entry": "toml" },
-        "project": { "path": ".codex/config.toml", "format": "toml", "key": "mcp_servers.codegraph", "entry": "toml" }
+        "global": {
+          "path": "~/.codex/config.toml",
+          "format": "toml",
+          "entry": "stdioNoType"
+        },
+        "project": {
+          "path": ".codex/config.toml",
+          "format": "toml",
+          "entry": "stdioNoType"
+        }
       }
     },
     "gemini": {
       "label": "Gemini CLI",
       "codegraphTarget": "gemini",
-      "detectHome": [".gemini"],
-      "detectProject": [".gemini"],
+      "detectHome": [
+        ".gemini"
+      ],
+      "detectProject": [
+        ".gemini"
+      ],
       "configs": {
-        "global": { "path": "~/.gemini/settings.json", "key": "mcpServers", "entry": "stdio" },
-        "project": { "path": ".gemini/settings.json", "key": "mcpServers", "entry": "stdio" }
+        "global": {
+          "path": "~/.gemini/settings.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        },
+        "project": {
+          "path": ".gemini/settings.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        }
       }
     },
     "antigravity": {
       "label": "Antigravity",
       "codegraphTarget": "antigravity",
-      "detectHome": [".gemini/config"],
-      "detectProject": [".agents/mcp_config.json"],
+      "detectHome": [
+        ".gemini/config"
+      ],
+      "detectProject": [
+        ".agents/mcp_config.json"
+      ],
       "configs": {
-        "global": { "path": "~/.gemini/config/mcp_config.json", "key": "mcpServers", "entry": "stdio" },
-        "project": { "path": ".agents/mcp_config.json", "key": "mcpServers", "entry": "stdio" }
+        "global": {
+          "path": "~/.gemini/config/mcp_config.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        },
+        "project": {
+          "path": ".agents/mcp_config.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        }
       }
     },
     "kiro": {
       "label": "Kiro",
       "codegraphTarget": "kiro",
-      "detectHome": [".kiro"],
-      "detectProject": [".kiro"],
+      "detectHome": [
+        ".kiro"
+      ],
+      "detectProject": [
+        ".kiro"
+      ],
       "configs": {
-        "global": { "path": "~/.kiro/settings/mcp.json", "key": "mcpServers", "entry": "stdioNoType" },
-        "project": { "path": ".kiro/settings/mcp.json", "key": "mcpServers", "entry": "stdioNoType" }
+        "global": {
+          "path": "~/.kiro/settings/mcp.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdioNoType"
+        },
+        "project": {
+          "path": ".kiro/settings/mcp.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdioNoType"
+        }
       }
     },
     "windsurf": {
       "label": "Windsurf",
       "codegraphTarget": null,
-      "detectHome": [".codeium/windsurf"],
-      "detectProject": [".windsurf"],
+      "detectHome": [
+        ".codeium/windsurf"
+      ],
+      "detectProject": [
+        ".windsurf"
+      ],
       "configs": {
-        "global": { "path": "~/.codeium/windsurf/mcp_config.json", "key": "mcpServers", "entry": "stdioNoType" }
+        "global": {
+          "path": "~/.codeium/windsurf/mcp_config.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdioNoType"
+        }
       }
     },
     "vscode": {
       "label": "VS Code / Copilot",
       "codegraphTarget": null,
       "detectHome": [],
-      "detectProject": [".vscode", ".github/copilot-instructions.md"],
+      "detectProject": [
+        ".vscode",
+        ".github/copilot-instructions.md"
+      ],
       "configs": {
-        "project": { "path": ".vscode/mcp.json", "key": "servers", "entry": "stdio" }
+        "project": {
+          "path": ".vscode/mcp.json",
+          "format": "json",
+          "key": "servers",
+          "entry": "stdio"
+        }
       }
     },
     "zed": {
       "label": "Zed",
       "codegraphTarget": null,
-      "detectHome": [".config/zed"],
-      "detectProject": [".zed"],
+      "detectHome": [
+        ".config/zed"
+      ],
+      "detectProject": [
+        ".zed"
+      ],
       "configs": {
-        "global": { "path": "~/.config/zed/settings.json", "key": "context_servers", "entry": "stdioNoType" },
-        "project": { "path": ".zed/settings.json", "key": "context_servers", "entry": "stdioNoType" }
+        "global": {
+          "path": "~/.config/zed/settings.json",
+          "format": "json",
+          "key": "context_servers",
+          "entry": "stdioNoType"
+        },
+        "project": {
+          "path": ".zed/settings.json",
+          "format": "json",
+          "key": "context_servers",
+          "entry": "stdioNoType"
+        }
       }
     },
     "trae": {
       "label": "Trae",
       "codegraphTarget": null,
-      "detectHome": [".trae"],
-      "detectProject": [".trae"],
+      "detectHome": [
+        ".trae"
+      ],
+      "detectProject": [
+        ".trae"
+      ],
       "configs": {
-        "project": { "path": ".trae/mcp.json", "key": "mcpServers", "entry": "stdioNoType" }
+        "project": {
+          "path": ".trae/mcp.json",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdioNoType"
+        }
       }
     }
   },
-  "codegraphNativeTargets": ["claude", "cursor", "opencode", "codex", "gemini", "antigravity", "kiro"]
+  "codegraphNativeTargets": [
+    "claude",
+    "cursor",
+    "opencode",
+    "codex",
+    "gemini",
+    "antigravity",
+    "kiro"
+  ]
 }

package/assets/references/artifact-templates.md

@@ -6,9 +6,17 @@ Begin both files with three YAML comment lines. Comments are ignored by every
 consumer (the MCP server, the VS Code extension, any YAML toolchain), so this is
 purely additive metadata — it can never break a parser:
 
+**NEVER type the version yourself.** The `scaffold` action writes the generator
+line with the RUNNING server's version, and you paste its output verbatim. A
+version you write by hand is either stale or made up — and the provenance
+header exists precisely so it is never either.
+
+The shape of what `scaffold` returns (the version below is a sample of the
+running server's, not a value to copy):
+
 ```yaml
 # schema_version: 1
-# generator: archgen v0.0.4
+# generator: archgen v1.2.3
 # generated_at: 2026-08-26T09:00:00.000Z
 ```
 
@@ -16,11 +24,17 @@ The scaffold action returns these three lines ready to paste.
 
 Version token rules — code-defensive, NEVER guess:
 
-1. If a `.archgen-version` stamp sits next to `SKILL.md` (the installed skill
-   root) and reads as exact `MAJOR.MINOR.PATCH`, write `generator: archgen vX.Y.Z`.
-2. Else if an adjacent `archgen.config.json` carries a semver-shaped
-   `"version"` field, use that value the same way.
-3. Else omit the version token entirely: plain `# generator: archgen`.
+1. The `scaffold` action already resolved the version for you. Copy its
+   header as-is.
+2. If you must write the header yourself (backfilling an artifact the tool
+   did not create), resolve the version in this order and never invent one:
+   a. The `.archgen-version` stamp next to the installed `SKILL.md`, when it
+      reads as exact `MAJOR.MINOR.PATCH`.
+   b. Otherwise the `"version"` field of an adjacent `archgen.config.json`,
+      when it is semver-shaped.
+   c. Otherwise omit the version token entirely: plain `# generator: archgen`.
+3. `npx archgen-skill migrate --apply` applies rules 2(a)–(c) to existing
+   artifacts for you, and backs each file up before it touches it.
 
 `generated_at` is one ISO-8601 timestamp per generation run (all files written
 by the same run share it). Keep the header at the very top of the file; never

package/assets/references/platforms.md

@@ -111,12 +111,14 @@ release and refreshes it in place. The MCP server exposes its own tool set to
 the agent, so the skill does not restate the CLI's command surface — read it
 from the installed CLI (`codegraph help`) or the MCP tools themselves.
 
-> **Entry point — the `archgen_codegraph` tool.** It installs/upgrades the CLI,
-> wires every DETECTED harness with the correct per-platform shape, and builds
-> the project index — idempotently, with an approval gate before any config
-> write. It drives the official CLI; it never reimplements it.
+> **Entry point — the `archgen_codegraph` tool.** It installs the CLI **if it
+> is missing** (an installed CodeGraph is the user's to manage and is never
+> upgraded behind their back), wires every DETECTED harness with the correct
+> per-platform shape, and builds the project index — idempotently, with an
+> approval gate before any config write. It drives the official CLI; it never
+> reimplements it.
 > ```
-> archgen_codegraph { action: 'ensure' }   # install + wire + index
+> archgen_codegraph { action: 'ensure' }   # install if missing + wire + index
 > archgen_codegraph { action: 'status' }   # what is installed/wired/indexed
 > ```
 

package/bin/archgen-mcp.mjs

@@ -16,11 +16,13 @@ import { createServer } from '../src/server.mjs';
 import { runCli } from '../src/cli.mjs';
 
 const argv = process.argv.slice(2);
-const CLI_COMMANDS = new Set(['exec', 'bootstrap', 'doctor', 'uninstall-mcp', 'help']);
 const first = argv[0];
-// 'serve' is the default, but any explicit CLI command OR any flag means the
-// caller wants the command-line facade, not the JSON-RPC stream.
-const wantsCli = first === 'serve' ? false : CLI_COMMANDS.has(first) || (first !== undefined && first.startsWith('-'));
+// The stdio server is the DEFAULT, and only for no argument at all or the
+// explicit word 'serve'. Anything else is the command-line facade — a known
+// command, a flag, or an unknown word, which must say "unknown command"
+// rather than silently start a server and block on stdin (which is what it
+// used to do, making the mistake look like a hang).
+const wantsCli = !(first === undefined || first === 'serve');
 
 if (wantsCli) {
   const code = await runCli(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-mcp",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap, harness MCP wiring, and live UI control for coding agents.",
   "license": "MIT",
   "type": "module",

package/src/context.mjs

@@ -11,7 +11,7 @@ import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { invalidInput } from './core/errors.mjs';
-import { containPath } from './core/fs-safety.mjs';
+import { assertWithinRoot, containPath } from './core/fs-safety.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -148,19 +148,59 @@ export function loadAsset(name) {
 
 /**
  * The per-call context: project root + resolved skill + versions.
+ *
+ * THE ANCHOR. `anchorRoot` is the boundary the server works inside. It is
+ * set when the server starts — the directory the server was launched in, or
+ * the project the CLI named — and it does NOT change per call.
+ *
+ * `projectRoot` selects a directory INSIDE the anchor. It is a selector, not
+ * a boundary: naming a different root cannot move the edge of what the
+ * server may read or write. Before this, every containment check was
+ * relative to a root the MODEL chose, so the guard defended nothing — a
+ * model that named `/etc` simply moved the boundary to `/etc`.
  */
 export class Context {
   /**
-   * @param {{projectRoot?: string, home?: string, env?: Record<string, string|undefined>}} [opts]
+   * @param {{projectRoot?: string, anchorRoot?: string, home?: string, env?: Record<string, string|undefined>}} [opts]
    */
   constructor(opts = {}) {
     this.env = opts.env ?? process.env;
     this.home = opts.home ?? homedir();
-    this.projectRoot = resolve(opts.projectRoot ?? this.env.ARCHGEN_PROJECT_ROOT ?? process.cwd());
+    // The anchor is the server's DECLARED root: what the server was started
+    // with. The cwd is only the fallback for a server started without one.
+    this.anchorRoot = resolve(
+      opts.anchorRoot ?? opts.projectRoot ?? this.env.ARCHGEN_PROJECT_ROOT ?? process.cwd(),
+    );
+    this.projectRoot = resolve(opts.projectRoot ?? this.anchorRoot);
     this.skill = resolveSkill(this.projectRoot, this.home, this.env);
     this.serverVersion = serverVersion();
   }
 
+  /**
+   * A context for a directory inside the anchor.
+   *
+   * The candidate is resolved and proved to be inside the anchor; a path
+   * outside it is refused with PERMISSION_DENIED. The returned context
+   * keeps the SAME anchor, so containment checks made with it cannot be
+   * widened either.
+   *
+   * @param {string} candidate
+   * @returns {Context}
+   */
+  withProjectRoot(candidate) {
+    if (typeof candidate !== 'string' || candidate.trim() === '') {
+      throw invalidInput('projectRoot must be a non-empty string', { projectRoot: candidate });
+    }
+    const abs = resolve(this.anchorRoot, candidate);
+    assertWithinRoot(this.anchorRoot, abs);
+    return new Context({
+      projectRoot: abs,
+      anchorRoot: this.anchorRoot,
+      env: this.env,
+      home: this.home,
+    });
+  }
+
   /**
    * Resolve a caller-supplied path and prove it stays inside the project root.
    * Relative paths are resolved against the project root.

package/src/core/briefs.mjs

@@ -36,6 +36,19 @@ export function loadBrief(briefsDir, kind, vars = {}) {
   return { kind: key, brief: text };
 }
 
+/**
+ * The placeholder names a brief still contains.
+ *
+ * A dispatched brief must not carry a placeholder: a worker told to read
+ * `<slug dir>` looks for a directory with that literal name.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function remainingPlaceholders(text) {
+  return [...new Set([...String(text ?? '').matchAll(/<([a-z][a-z. ]*)>/g)].map((m) => m[1]))];
+}
+
 /**
  * Every brief, for a caller that wants them all.
  * @param {string} briefsDir