archgen-skill 0.0.5 → 0.0.6

package/README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/akashmaurya99/archgen/actions/workflows/ci.yml/badge.svg)](https://github.com/akashmaurya99/archgen/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/akashmaurya99/archgen/blob/main/LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
 Describe what you want to build. archgen interviews you (or surveys your existing
 codebase), produces an architecture contract plus a dependency-ordered task graph,
@@ -49,8 +49,13 @@ npx archgen-skill install          # symlinks; --copy for real copies
 ```
 
 Prefer shell? Clone the repo and run `./install.sh` (same behavior, plus
-`--init`, `--project`, `--uninstall`). Requires Node.js ≥ 18. The skill itself
-has zero npm dependencies.
+`--init`, `--project`, `--uninstall`). Requires Node.js ≥ 20 — the official MCP
+SDK v2 floor.
+
+**What `init` actually does:** installs the skill (guidance only — no code),
+wires the `archgen-mcp` MCP server into every detected harness, and ensures
+CodeGraph (its CLI, its MCP entry, and the project index). The CLI itself is
+zero-dependency; the MCP server it installs depends on the official MCP SDK.
 
 ## Quick start
 
@@ -125,11 +130,12 @@ are supported for all of them.
 
 ## VS Code extension (optional)
 
-A read-only visual layer that renders `.archgen/` as a live task DAG, your
+A visual layer that renders `.archgen/` as a live task DAG, your
 code-dependency graph, and rendered docs — with a ▶ button that hands any task to
 your agent. Install it from the VS Code Marketplace or from a `.vsix` on
 [GitHub Releases](https://github.com/akashmaurya99/archgen/releases). It never
-edits anything: uninstalling it loses nothing.
+edits your plan, your tasks, or your code — only its own runtime state under
+`.archgen/.runtime/`, so uninstalling it loses nothing.
 
 ## Documentation
 
@@ -145,7 +151,7 @@ See [CONTRIBUTING.md](https://github.com/akashmaurya99/archgen/blob/main/CONTRIB
 Skill suite and CLI tests run with zero dependencies:
 
 ```sh
-node --test skill/scripts/test/*.test.mjs   # skill suite
+node --test packages/mcp/test/**/*.test.mjs   # MCP server suite
 cd packages/cli && npm test                 # CLI suite
 ```
 

package/bin/archgen.mjs

@@ -22,6 +22,7 @@ import { uninstallProject } from '../lib/uninstall-project.js';
 import { restoreMain } from '../lib/restore.js';
 import { migrateMain } from '../lib/migrate.js';
 import { compareSemver, fetchLatestVersion } from '../lib/version.js';
+import { npmInvocation, whichOnPath } from '../lib/spawn-npm.js';
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 
@@ -46,6 +47,8 @@ Usage:
                                 and generate AGENTS.md / CLAUDE.md pointer blocks.
     [--force]                     proceed automatically; divergent copies are
                                   backed up to .archgen/.backup/ (never destroyed)
+    [--no-codegraph]              skip the CodeGraph bootstrap
+    [--no-mcp]                   skip wiring the archgen MCP server
   npx archgen-skill doctor [dir]      Health-check a project install: store integrity,
                                 version stamp, claude link, managed blocks,
                                 manifest. Repairs safe issues in place.
@@ -53,6 +56,8 @@ Usage:
   npx archgen-skill install           Install into global harness skill dirs
     [--copy]                      real copies instead of symlinks
     [--uninstall]                 remove manifest-recorded entries
+    [--no-codegraph]              skip the CodeGraph bootstrap
+    [--no-mcp]                   skip wiring the archgen MCP server
   npx archgen-skill uninstall         Remove globally-installed copies (manifest-based)
     --project [dir]               remove archgen from a project: claude link,
                                   managed blocks, canonical store (kept when
@@ -92,7 +97,9 @@ try {
   switch (cmd) {
     case 'init': {
       flag('--force');
-      const r = initProject(positionalDir(), PACKAGE_ROOT);
+      const noCodegraph = flag('--no-codegraph');
+      const noMcp = flag('--no-mcp');
+      const r = initProject(positionalDir(), PACKAGE_ROOT, { codegraph: !noCodegraph, mcp: !noMcp });
       console.log('archgen: project ready (single-store layout)');
       console.log('  + store ' + r.storePath);
       if (r.claudeLink === 'created') console.log('  + link  .claude/skills/archgen -> ../../.agents/skills/archgen');
@@ -120,8 +127,10 @@ try {
     }
     case 'install': {
       const copy = flag('--copy');
+      const noCodegraph = flag('--no-codegraph');
+      const noMcp = flag('--no-mcp');
       if (flag('--uninstall')) { uninstall(); break; }
-      const r = installGlobal({ copy });
+      const r = installGlobal({ copy, codegraph: !noCodegraph, mcp: !noMcp });
       console.log('archgen: global harness install (mode: ' + (copy ? 'copy' : 'symlink') + ')');
       for (const [status, mode, path] of r.rows) console.log(`  ${status.padEnd(7)} ${mode.padEnd(5)} ${path}`);
       console.log('\nPer-project setup (recommended): npx archgen-skill init');
@@ -137,6 +146,7 @@ try {
         if (r.storeRemoved) console.log('  - .agents/skills/archgen (unmodified store)');
         if (r.storeKept) console.log('  = .agents/skills/archgen KEPT (customized)');
         if (r.manifestRemoved) console.log('  - .archgen/.install-manifest.json');
+        for (const m of r.mcpRemoved ?? []) console.log(`  - ${m} (archgen MCP entry)`);
         for (const w of r.warnings) console.log('  note: ' + w);
         console.log('  .archgen feature folders and backups are preserved.');
       } else {
@@ -177,17 +187,24 @@ try {
         runInitAndDoctor(dir);
         break;
       }
+      if (!/^\d+\.\d+\.\d+[-+]?[0-9A-Za-z.-]*$/.test(latest)) {
+        // Registry returned something that is not a semver tag — never
+        // interpolate it into a command line.
+        console.error('  ! registry returned a non-semver version string; refusing: ' + JSON.stringify(latest));
+        process.exitCode = 1;
+        break;
+      }
       console.log('  ↑ newer version available: ' + latest);
       console.log('  upgrading global install: npm install -g archgen-skill@' + latest);
-      const up = spawnSync('npm', ['install', '-g', 'archgen-skill@' + latest], { stdio: 'inherit' });
+      const inv = npmInvocation(['install', '-g', 'archgen-skill@' + latest]);
+      const up = spawnSync(inv.command, inv.args, { stdio: 'inherit', shell: inv.shell });
       if (up.status !== 0) {
         console.error('  ! global upgrade failed — run it manually, then re-run: archgen-skill update');
         process.exitCode = 1;
         break;
       }
       // The running process is the OLD code; re-exec the freshly installed binary.
-      const bin = spawnSync('command', ['-v', 'archgen-skill'], { encoding: 'utf8', shell: true });
-      const freshBin = (bin.stdout || '').trim();
+      const freshBin = whichOnPath('archgen-skill');
       if (!freshBin) {
         console.log('\nUpgraded to v' + latest + '. Now finish per project with:\n  npx archgen-skill@latest init');
         break;

package/lib/block.js

@@ -98,7 +98,7 @@ export function renderBlock(skillRelPath = '.agents/skills/archgen', eol = '\n')
     '',
     'Rules of the road:',
     '- Generated artifacts live ONLY under `.archgen/<slug>/`',
-    '- Never hand-edit task statuses - use `scripts/set-status.mjs` (comment-safe)',
+    '- Never hand-edit task statuses - call the `archgen_tasks` MCP tool (comment-safe)',
     '- Two gates before any execution: verifier approval, then human approval',
     '',
     '## Features registry',

package/lib/bootstrap.js

@@ -0,0 +1,103 @@
+// bootstrap.js — the install-time server bootstrap for `archgen init` /
+// `archgen install`.
+//
+// The CLI used to shell out to the skill's scripts/codegraph.mjs. That script
+// no longer exists: ALL deterministic capability now lives in the archgen MCP
+// server, so the CLI drives THAT instead. One implementation, three ways in
+// (agent -> MCP stdio, CLI -> `archgen-mcp bootstrap`, extension -> exec).
+//
+// The bootstrap does two things in one pass:
+//   1. wires the archgen MCP entry into every detected harness
+//   2. ensures CodeGraph: its CLI, its MCP entry, and the project index
+//
+// NEVER FATAL: no npm, no network, a read-only config, or a missing MCP
+// server must still leave a working skill install. Failures are REPORTED,
+// never thrown.
+import { bootstrapMcp, resolveMcpBinary } from './mcp-server.js';
+
+/**
+ * @param {{
+ *   projectDir: string,
+ *   location?: 'project'|'global'|'both',
+ *   log?: (line: string) => void,
+ *   env?: Record<string, string|undefined>,
+ *   noCodegraph?: boolean,
+ *   noMcp?: boolean,
+ * }} opts
+ * @returns {{ok: boolean, skipped?: string, detail?: string, report?: any}}
+ */
+export function bootstrapServers(opts) {
+  const {
+    projectDir,
+    location = 'both',
+    log = () => {},
+    env = process.env,
+    noCodegraph = false,
+    noMcp = false,
+  } = opts;
+
+  // ARCHGEN_CODEGRAPH=0 skips the bootstrap (no spawn, no network, no writes)
+  // — without it the test suite would wire the developer's real MCP configs.
+  if (env.ARCHGEN_CODEGRAPH === '0' || env.ARCHGEN_CODEGRAPH === 'off') {
+    return { ok: true, skipped: 'ARCHGEN_CODEGRAPH=0 (bootstrap disabled)' };
+  }
+  if (noMcp && noCodegraph) {
+    return { ok: true, skipped: '--no-mcp and --no-codegraph passed' };
+  }
+
+  const resolved = resolveMcpBinary({ projectRoot: projectDir, env });
+  log(`  + mcp server: ${resolved.bin ?? 'npx -y archgen-mcp'} (${resolved.source})`);
+
+  if (noMcp) {
+    log('  ! archgen MCP wiring skipped (--no-mcp)');
+  }
+  if (noCodegraph) {
+    log('  ! CodeGraph bootstrap skipped (--no-codegraph)');
+  }
+
+  const r = bootstrapMcp({
+    projectDir,
+    location,
+    approved: true,
+    env,
+  });
+
+  if (!r.report) {
+    return {
+      ok: true, // never fatal — the skill install itself succeeded
+      detail: `server bootstrap incomplete: ${r.detail ?? 'unknown error'}`,
+    };
+  }
+
+  const report = r.report;
+  const mcp = report.mcp ?? {};
+  const codegraph = report.codegraph ?? {};
+
+  for (const w of mcp.wired ?? []) {
+    log(`  + harness: ${w.harness} → ${w.path} [${w.key}] ${w.status}${w.detail ? ' — ' + w.detail : ''}`);
+  }
+  if (codegraph.cli) {
+    log(
+      `  + codegraph ${codegraph.cli.version ?? 'unknown'}${codegraph.cli.action !== 'none' ? ' (' + codegraph.cli.action + ')' : ''}${codegraph.cli.latest ? ' · latest available ' + codegraph.cli.latest : ''}`,
+    );
+  }
+  if (codegraph.telemetry) {
+    log(`  + telemetry: ${codegraph.telemetry.state ?? 'unknown'}${codegraph.telemetry.action !== 'none' ? ' → ' + codegraph.telemetry.action : ''}`);
+  }
+  for (const w of codegraph.wiring?.native ?? []) {
+    log(`  + harness: ${w.targets} (${w.location}) → ${w.status}${w.detail ? ' — ' + w.detail : ''}`);
+  }
+  if (codegraph.index) {
+    log(`  + index: ${codegraph.index.action ?? 'none'}${codegraph.index.files != null ? ' (' + codegraph.index.files + ' files)' : ''}`);
+  }
+  log('  + realtime: the MCP server watches files — the index stays live, no re-indexing needed');
+
+  if (r.ok === false || codegraph.ok === false) {
+    return {
+      ok: false,
+      report,
+      detail: 'one or more server bootstrap steps failed',
+    };
+  }
+  return { ok: true, report };
+}

package/lib/doctor.js

@@ -22,9 +22,10 @@ import {
   upsertManagedFile,
 } from './block.js';
 import { resolveSkillSource } from './init.js';
-import { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, hashDir, loadManifest, pruneDevOnly, saveManifest } from './store.js';
+import { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, findObsolete, hashDir, loadManifest, pruneDevOnly, pruneObsolete, saveManifest } from './store.js';
 import { compareSemver, parseSemver } from './version.js';
 import { readStamp, writeStamp } from './version-stamp.js';
+import { mcpDoctor } from './mcp-server.js';
 
 function lstatSafe(p) {
   try { return lstatSync(p); } catch { return null; }
@@ -83,7 +84,21 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!existsSync(join(storeAbs, 'SKILL.md'))) {
     add('FAIL', 'store .agents/skills/archgen missing or incomplete - run `archgen init`');
   } else {
-    const missingCore = ['scripts', 'references'].filter((d) => !existsSync(join(storeAbs, d)));
+    // MIGRATION: the skill no longer ships code. An install carried over from
+    // the pre-MCP layout still has a scripts/ tree — dead weight that would
+    // otherwise read as "diverges from packaged skill (customized?)".
+    // Pruned BEFORE the divergence check so an upgrade is not misreported.
+    const packaged = (() => {
+      try { return resolveSkillSource(packageRoot); } catch { return null; }
+    })();
+    if (packaged) {
+      // --check reports WITHOUT mutating; repair mode prunes.
+      const obsolete = checkOnly ? findObsolete(storeAbs, packaged) : pruneObsolete(storeAbs, packaged);
+      for (const rel of obsolete) {
+        add(checkOnly ? 'WOULD-FIX' : 'FIXED', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> ${checkOnly ? 'would prune' : 'pruned'}`);
+      }
+    }
+    const missingCore = ['references'].filter((d) => !existsSync(join(storeAbs, d)));
     if (missingCore.length > 0) {
       // Deferred so the managed-block FAIL rows below stay FIRST: existing
       // consumers read checks.find(FAIL) expecting the marker verdict.
@@ -296,6 +311,34 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     add(v ? 'OK' : 'WARN', `skill ${p}: ${slot}`);
   }
 
+  // 8. MCP server wiring — the archgen MCP server is what actually gives the
+  //    agent its tools. A skill with no MCP entry is a skill the agent cannot
+  //    use, so this is a first-class check, not a footnote.
+  //
+  // READ-ONLY and NEVER FATAL: doctor must work on a machine with no npm, no
+  // network, and no MCP server installed. The MCP server is asked for its own
+  // report; if it cannot run, that is a WARN with the remediation command.
+  const mcp = mcpDoctor({ projectRoot: root, env: { ...process.env, HOME: homeDir } });
+  if (!mcp.report) {
+    add('WARN', `archgen MCP server not reachable${mcp.detail ? ` — ${mcp.detail}` : ''} — install with: npx archgen-mcp bootstrap --project . --yes`);
+  } else {
+    const rep = mcp.report;
+    add(
+      rep.skill ? 'OK' : 'WARN',
+      rep.skill
+        ? `archgen MCP server v${rep.server} ready (skill ${rep.skill.version ?? 'unknown'})`
+        : 'archgen MCP server ready, but no skill was found',
+    );
+    const wired = (rep.mcpTargets ?? []).filter((t) => t.exists).length;
+    if (wired === 0) {
+      add('WARN', 'archgen MCP is not wired into any harness config — run: npx archgen-mcp bootstrap --project . --yes');
+    } else {
+      add('OK', `archgen MCP wiring present in ${wired} harness config(s)`);
+    }
+    if (rep.codegraph) add('OK', `codegraph ${rep.codegraph.version}`);
+    else add('WARN', 'codegraph not installed — run: npx archgen-mcp bootstrap --project . --yes');
+  }
+
   const tally = { OK: 0, FIXED: 0, 'WOULD-FIX': 0, WARN: 0, FAIL: 0 };
   for (const c of checks) tally[c.status]++;
   return { root, checks, tally, failures: opFailures };

package/lib/init.js

@@ -17,12 +17,13 @@
 //   to a symlink; a customized one is left untouched with a warning;
 // - installs are atomic: built in a temp sibling dir, then renamed.
 
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { importsAgents, renderBlock, START, END, upsertManagedFile } from './block.js';
 import { CLAUDE_LINK_REL, STORE_REL, VERSION_FILE, appendEntry, assertNotSymlink, assertWithinRoot, cliVersion, hashDir, moveToBackup, pruneDevOnly } from './store.js';
 import { writeStamp } from './version-stamp.js';
+import { bootstrapServers } from './bootstrap.js';
 
 const CONTEXT_FILES = ['AGENTS.md', 'CLAUDE.md'];
 
@@ -99,8 +100,11 @@ function installClaudeAdapter(root, source, warnings) {
  * claude adapter, and write context pointers.
  * @param {string} projectDir target repo root
  * @param {string} packageRoot dir containing this CLI package
- * @param {{force?: boolean}} opts --force proceeds automatically; divergent
- *   copies are always auto-backed-up (never refused, never destroyed)
+ * @param {{force?: boolean, codegraph?: boolean, mcp?: boolean, log?: (s: string) => void, env?: NodeJS.ProcessEnv}} opts
+ *   --force proceeds automatically; divergent copies are always auto-backed-up
+ *   (never refused, never destroyed). opts.codegraph === false opts OUT of the
+ *   automatic CodeGraph bootstrap (install + MCP wiring + index build);
+ *   opts.mcp === false opts OUT of the archgen MCP wiring.
  * @returns {{storePath: string, claudeLink: 'created'|'existing'|'migrated'|'skipped'|'kept-divergent',
  *            backups: string[], contextFiles: string[], createdContextFiles: string[], warnings: string[]}}
  */
@@ -110,6 +114,9 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   // both plain and --force runs take the same safe path.
   const force = opts.force === true;
   void force;
+  const codegraphAllowed = opts.codegraph !== false;
+  const mcpAllowed = opts.mcp !== false;
+  const log = opts.log ?? console.log;
 
   const root = resolve(projectDir);
   const source = resolveSkillSource(packageRoot);
@@ -165,5 +172,27 @@ export function initProject(projectDir, packageRoot, opts = {}) {
     appendEntry(root, 'block', name);
   }
 
+  // 4. Server bootstrap — wire the archgen MCP server into every detected
+  //    harness AND ensure CodeGraph (its CLI, its MCP entry, the project
+  //    index). Non-fatal by design: an offline machine still gets the skill
+  //    installed.
+  if (codegraphAllowed || mcpAllowed) {
+    const r = bootstrapServers({
+      projectDir: root,
+      location: 'both',
+      log,
+      env: opts.env,
+      noCodegraph: !codegraphAllowed,
+      noMcp: !mcpAllowed,
+    });
+    if (!r.ok) {
+      warnings.push(`server bootstrap incomplete${r.detail ? ': ' + r.detail : ''} — install later with: npx archgen-mcp bootstrap --project . --yes`);
+    } else if (r.skipped) {
+      warnings.push(`server bootstrap skipped (${r.skipped})`);
+    }
+  } else {
+    warnings.push('server bootstrap skipped (--no-codegraph --no-mcp)');
+  }
+
   return { storePath: storeAbs, claudeLink, backups, contextFiles, createdContextFiles, warnings };
 }

package/lib/install.js

@@ -10,6 +10,7 @@ import { resolveSkillSource } from './init.js';
 import { assertNotSymlink, assertWithinRoot, cliVersion, hashDir, moveToBackupInto, pruneDevOnly, refuseSymlinkMessage } from './store.js';
 import { writeStamp } from './version-stamp.js';
 import { loadConfig } from './config.js';
+import { bootstrapServers } from './bootstrap.js';
 
 // Module-anchored default: works from the npm package (cli/lib -> cli/vendor)
 // AND from a monorepo checkout (packages/cli/lib -> ../../skill) without depending on cwd.
@@ -58,7 +59,7 @@ function nextBackupTs(tdir) {
 }
 
 /**
- * @param {{copy?: boolean, home?: string, packageRoot?: string}} opts
+ * @param {{copy?: boolean, home?: string, packageRoot?: string, codegraph?: boolean, mcp?: boolean, log?: (s: string) => void, env?: NodeJS.ProcessEnv}} opts
  * @returns {{rows: Array<[string, string, string]>, failures: number, manifest: string,
  *            backups: string[]}} rows are [STATUS, MODE, PATH]; `backups` lists
  *            absolute vault locations written by this run.
@@ -165,6 +166,24 @@ export function installGlobal(opts = {}) {
       rows.push(['FAILED', '-', dest + ' (' + e.message + ')']);
     }
   }
+  // Server bootstrap — GLOBAL wiring only (project-local configs belong to
+  // `init`). Wires the archgen MCP server and CodeGraph into every DETECTED
+  // global harness. Non-fatal: an offline machine still gets the skill
+  // installed.
+  if (opts.codegraph !== false || opts.mcp !== false) {
+    const r = bootstrapServers({
+      projectDir: process.cwd(),
+      location: 'global',
+      log: opts.log ?? console.log,
+      env: opts.env,
+      noCodegraph: opts.codegraph === false,
+      noMcp: opts.mcp === false,
+    });
+    if (!r.ok) {
+      rows.push(['WARN', '-', 'server bootstrap incomplete — run: npx archgen-mcp bootstrap --location global --yes']);
+    }
+  }
+
   return { rows, failures, manifest, backups };
 }
 

package/lib/mcp-server.js

@@ -0,0 +1,159 @@
+// mcp-server.js — locate and drive the `archgen-mcp` server from the CLI.
+//
+// WHY THE CLI DELEGATES: archgen's deterministic capability now lives in ONE
+// place — the MCP server. The CLI used to shell out to the skill's
+// scripts/codegraph.mjs; it now shells out to `archgen-mcp bootstrap`, which
+// runs the same code the agent's tools run. There is no second implementation
+// of harness wiring, CodeGraph bootstrap, or doctor logic.
+//
+// NEVER FATAL: no npm, no network, a read-only config, or a missing MCP
+// server must still leave a working skill install. Failures are REPORTED,
+// never thrown — the same posture bootstrapCodegraph has always had.
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const MCP_PACKAGE = 'archgen-mcp';
+
+/**
+ * Locate the archgen-mcp binary.
+ *
+ * Resolution order (first hit wins):
+ *   1. $ARCHGEN_MCP_BIN            — explicit override
+ *   2. <project>/node_modules/.bin/archgen-mcp
+ *   3. `archgen-mcp` on PATH       — a global npm install
+ *   4. `npx -y archgen-mcp`        — network fallback (npx caches it)
+ *
+ * @param {{projectRoot?: string, home?: string, env?: Record<string, string|undefined>}} opts
+ * @returns {{bin: string|null, source: 'override'|'local'|'path'|'npx', command: string, args: string[]}}
+ */
+export function resolveMcpBinary(opts = {}) {
+  const { projectRoot = process.cwd(), home = homedir(), env = process.env } = opts;
+
+  const override = env.ARCHGEN_MCP_BIN;
+  if (override && existsSync(override)) {
+    return { bin: override, source: 'override', command: override, args: [] };
+  }
+
+  const local = join(
+    resolve(projectRoot),
+    'node_modules',
+    '.bin',
+    process.platform === 'win32' ? 'archgen-mcp.cmd' : 'archgen-mcp',
+  );
+  if (existsSync(local)) return { bin: local, source: 'local', command: local, args: [] };
+
+  const onPath = whichOnPath('archgen-mcp', env);
+  if (onPath) return { bin: onPath, source: 'path', command: onPath, args: [] };
+
+  return { bin: null, source: 'npx', command: 'npx', args: ['-y', MCP_PACKAGE] };
+}
+
+/**
+ * Locate an executable on PATH (cross-platform, no shell).
+ * @param {string} bin
+ * @param {Record<string, string|undefined>} env
+ * @returns {string|null}
+ */
+export function whichOnPath(bin, env = process.env) {
+  const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';') : [''];
+  const dirs = (env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
+  for (const d of dirs) {
+    for (const ext of exts) {
+      const p = join(d, bin + ext);
+      try {
+        if (existsSync(p) && !p.endsWith('/')) return p;
+      } catch {
+        /* not here */
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Run one `archgen-mcp` subcommand and return its JSON output.
+ *
+ * @param {string[]} args the subcommand + flags
+ * @param {{projectRoot?: string, timeout?: number, env?: Record<string, string|undefined>}} opts
+ * @returns {{ok: boolean, code: number|null, data: any, stdout: string, stderr: string, detail?: string}}
+ */
+export function runMcp(args, opts = {}) {
+  const { projectRoot = process.cwd(), timeout = 600000, env = process.env } = opts;
+  const resolved = resolveMcpBinary({ projectRoot, env });
+
+  let r;
+  try {
+    r = spawnSync(resolved.command, [...resolved.args, ...args], {
+      encoding: 'utf8',
+      timeout,
+      env,
+      cwd: projectRoot,
+      shell: false,
+      // On Windows the npx shim is a .cmd file, which needs a shell.
+      ...(process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved.command) ? { shell: true } : {}),
+    });
+  } catch (e) {
+    return { ok: false, code: null, data: null, stdout: '', stderr: '', detail: String(e?.message ?? e) };
+  }
+  if (r.error) {
+    return { ok: false, code: null, data: null, stdout: '', stderr: '', detail: String(r.error.message ?? r.error) };
+  }
+  const stdout = r.stdout ?? '';
+  let data = null;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    /* not JSON — the caller renders the raw output */
+  }
+  return {
+    ok: r.status === 0,
+    code: r.status ?? null,
+    data,
+    stdout,
+    stderr: r.stderr ?? '',
+  };
+}
+
+/**
+ * Wire the archgen MCP server into the detected harnesses and ensure CodeGraph.
+ *
+ * @param {{projectRoot: string, location?: 'project'|'global'|'both', approved?: boolean, env?: Record<string, string|undefined>}} opts
+ * @returns {{ok: boolean, skipped?: string, detail?: string, report?: any}}
+ */
+export function bootstrapMcp(opts) {
+  const { projectRoot, location = 'both', approved = true, env = process.env } = opts;
+  const args = ['bootstrap', '--project', projectRoot, '--location', location, '--json'];
+  if (approved) args.push('--yes');
+
+  const r = runMcp(args, { projectRoot, env });
+  if (r.detail) {
+    return { ok: false, detail: `cannot run ${MCP_PACKAGE}: ${r.detail}` };
+  }
+  if (r.data === null) {
+    const firstLine = (r.stderr || r.stdout || '').trim().split('\n')[0];
+    return { ok: false, detail: firstLine || `${MCP_PACKAGE} bootstrap produced no output` };
+  }
+  return { ok: r.ok, report: r.data, detail: r.ok ? undefined : r.stderr.trim().split('\n')[0] };
+}
+
+/**
+ * Health-check the archgen MCP install.
+ * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
+ */
+export function mcpDoctor(opts) {
+  const { projectRoot, env = process.env } = opts;
+  const r = runMcp(['doctor', '--project', projectRoot, '--json'], { projectRoot, env, timeout: 60000 });
+  return { ok: r.ok, report: r.data, detail: r.detail ?? (r.data ? undefined : r.stderr.trim().split('\n')[0]) };
+}
+
+/**
+ * Remove the archgen MCP entries.
+ * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
+ */
+export function uninstallMcp(opts) {
+  const { projectRoot, env = process.env } = opts;
+  const r = runMcp(['uninstall-mcp', '--project', projectRoot, '--yes', '--json'], { projectRoot, env, timeout: 60000 });
+  return { ok: r.ok, report: r.data, detail: r.detail };
+}

package/lib/migrations/001-stamp-provenance.mjs

@@ -4,9 +4,9 @@
 //
 // What it writes: three YAML COMMENT lines at the very top of tasks.yaml and
 // architecture.yaml. Comments are inert to every consumer by contract — the
-// skill's zero-dep parser records them positionally (set-status.mjs preserves
-// them verbatim), verify-plan.mjs never sees them as data, and the VS Code
-// extension port behaves identically. Additive-only: no existing key is
+// MCP core's parser records them positionally (`archgen_tasks{set_status}`
+// preserves them verbatim), the verifier never sees them as data, and the VS
+// Code extension port behaves identically. Additive-only: no existing key is
 // touched, nothing becomes required.
 //
 //   # schema_version: 1

package/lib/spawn-npm.js

@@ -0,0 +1,54 @@
+// spawn-npm.js — run npm on every platform without a shell.
+// An unshelled spawnSync("npm", …) fails with EINVAL on Windows since the
+// CVE-2024-27980 hardening, so npm's JS entry point is invoked with the
+// current node binary instead.
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** npm-cli.js path: `npm_execpath` first, then node-relative layouts. */
+export function npmCliPath() {
+  const fromEnv = process.env.npm_execpath;
+  if (typeof fromEnv === 'string' && fromEnv.endsWith('.js') && existsSync(fromEnv)) {
+    return fromEnv;
+  }
+  const dir = dirname(process.execPath);
+  const candidates =
+    process.platform === 'win32'
+      ? [join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js')] // Windows: node.exe sits beside node_modules/
+      : [join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')]; // POSIX: bin/../lib/...
+  for (const c of candidates) if (existsSync(c)) return c;
+  // Homebrew cellar layout: /opt/homebrew/{bin,lib}/...
+  if (process.platform !== 'win32') {
+    const brew = join(dir, '..', '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (existsSync(brew)) return brew;
+  }
+  return null;
+}
+
+/**
+ * Spawn npm with { command, args, shell }. Args MUST be registry-verified
+ * constants (the shell fallback on Windows interpolates them).
+ */
+export function npmInvocation(npmArgs) {
+  const cli = npmCliPath();
+  if (cli) return { command: process.execPath, args: [cli, ...npmArgs], shell: false };
+  const isWin = process.platform === 'win32';
+  return { command: isWin ? 'npm.cmd' : 'npm', args: npmArgs, shell: isWin };
+}
+
+/** Cross-platform `which` (PATHEXT on Windows). */
+export function whichOnPath(bin) {
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+  const dirs = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
+  for (const d of dirs) {
+    for (const ext of exts) {
+      const p = join(d, bin + ext);
+      try {
+        if (existsSync(p)) return p;
+      } catch { /* next */ }
+    }
+  }
+  return null;
+}