archgen-skill 0.0.6 → 0.0.7

package/lib/doctor.js

@@ -3,13 +3,13 @@
 // Verifies a project install: canonical store integrity, version stamp,
 // claude link resolution, managed blocks (exactly once each), and manifest
 // entry resolution. Safe issues are repaired in place unless --check is given
-// (report-only). Advisory FAIL rows (broken states only a human can fix) are
-// reported and counted in the summary but do NOT fail the run: the process
-// exits non-zero only when a repair operation itself throws.
+// (report-only). A FAIL row is a broken state a human must fix: it is
+// reported AND it fails the run (the process exits non-zero whenever any
+// FAIL row was produced).
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { globalTargets } from './install.js';
 import {
   END,
@@ -22,7 +22,7 @@ import {
   upsertManagedFile,
 } from './block.js';
 import { resolveSkillSource } from './init.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 { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, assertNotSymlink, assertWithinRoot, 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';
@@ -48,8 +48,7 @@ function relJoin(rel) {
  *   mutations; home overrides the homedir scanned for global installs (tests)
  * @returns {{root: string, checks: {status: 'OK'|'FIXED'|'WOULD-FIX'|'WARN'|'FAIL', msg: string}[],
  *            tally: Record<string, number>, failures: number}} `failures` counts
- *   repair operations that THEMSELVES threw — advisory FAIL rows are reported
- *   but never fail the run.
+ *   the FAIL rows — a broken state a human must fix always fails the run.
  */
 export function doctorProject(projectDir, packageRoot, opts = {}) {
   const root = resolve(projectDir);
@@ -57,16 +56,20 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   const homeDir = opts.home ?? homedir();
   const version = cliVersion(packageRoot);
   const checks = [];
-  const add = (status, msg) => checks.push({ status, msg });
-  let opFailures = 0;
+  let failures = 0;
+  // A FAIL row is a broken state a human must fix, so it MUST fail the run:
+  // the counter below is what the CLI turns into a non-zero exit code.
+  const add = (status, msg) => {
+    checks.push({ status, msg });
+    if (status === 'FAIL') failures++;
+  };
   // Run one repair step; a throw becomes a FAIL row instead of aborting the
-  // whole doctor pass (and is the only thing that flips the exit code).
+  // whole doctor pass.
   const attempt = (fn, okStatus, okMsg, failLabel) => {
     try {
       fn();
       add(okStatus, okMsg);
     } catch (e) {
-      opFailures++;
       add('FAIL', `${failLabel}: ${e.message} - fix manually`);
     }
   };
@@ -93,9 +96,27 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     })();
     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 obsolete = findObsolete(storeAbs, packaged);
+      if (obsolete.length > 0) {
+        if (checkOnly) {
+          for (const rel of obsolete) {
+            add('WOULD-FIX', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> would prune`);
+          }
+        } else {
+          // Pruning DELETES inside the store: refuse when the store (or one of
+          // its parents) is a symlink — the prune would otherwise reach
+          // outside the project through the link.
+          try {
+            assertNotSymlink(storeAbs);
+            assertWithinRoot(root, storeAbs);
+            pruneObsolete(storeAbs, packaged);
+            for (const rel of obsolete) {
+              add('FIXED', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> pruned`);
+            }
+          } catch (e) {
+            add('FAIL', `cannot prune the obsolete store tree: ${e.message} - fix manually`);
+          }
+        }
       }
     }
     const missingCore = ['references'].filter((d) => !existsSync(join(storeAbs, d)));
@@ -124,7 +145,12 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
       if (checkOnly) {
         add('WOULD-FIX', `store carries dev-only ${devOnlyPresent.join(', ')} -> pruned`);
       } else {
-        attempt(() => pruneDevOnly(storeAbs), 'FIXED',
+        // Same rule as the obsolete prune: never delete through a symlink.
+        attempt(() => {
+          assertNotSymlink(storeAbs);
+          assertWithinRoot(root, storeAbs);
+          pruneDevOnly(storeAbs);
+        }, 'FIXED',
           `dev-only ${devOnlyPresent.join(', ')} pruned from store`, 'cannot prune dev-only artifacts');
       }
     }
@@ -152,6 +178,10 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
       return;
     }
     try {
+      // Escape check FIRST, exactly as init does: a symlinked .claude/
+      // .claude/skills parent must not redirect the recreated link outside
+      // the project root.
+      assertWithinRoot(root, dirname(claudeAbs));
       try { unlinkSync(claudeAbs); } catch { /* absent */ }
       mkdirSync(dirname(claudeAbs), { recursive: true });
       symlinkSync('../../.agents/skills/archgen', claudeAbs);
@@ -184,60 +214,66 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
         'AGENTS.md created with managed block', 'cannot create AGENTS.md managed block');
     }
   } else {
-    let raw = readFileSync(agentsAbs, 'utf8');
-    const starts = countOccurrences(raw, START);
-    const ends = countOccurrences(raw, END);
-    if (starts === 0 && ends === 0) {
-      if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
-      else {
-        attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
-          'AGENTS.md managed block added', 'cannot add AGENTS.md managed block');
-      }
-    } else if (starts > 1 || ends > 1) {
-      add('FAIL', `AGENTS.md has ${starts} start / ${ends} end markers - fix manually`);
-    } else if (starts === 0 || ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
-      // Orphan/inverted markers: repairing through upsertBlock would throw, so
-      // classify as FAIL instead of attempting the write.
-      add('FAIL', 'AGENTS.md has broken archgen markers - fix manually');
-    } else {
-      // Block-format currency: an unversioned or older-stamped managed block is
-      // upgraded in place through the normal upsert path (everything outside the
-      // markers survives byte-for-byte by design). Newer stamps are left alone.
-      const det = detectBlockVersion(raw);
-      const parsed = det.version ? parseSemver(det.version) : null;
-      const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
-      if (stale) {
-        const from = det.version ? 'v' + det.version : 'unversioned';
-        if (checkOnly) {
-          add('WOULD-FIX', `WOULD-UPGRADE: AGENTS.md block ${from} -> v${version}`);
-        } else {
-          let upgraded = false;
-          attempt(() => { upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')); upgraded = true; },
-            'FIXED', `UPGRADED: AGENTS.md block ${from} -> v${version}`, 'cannot upgrade AGENTS.md block');
-          if (upgraded) raw = readFileSync(agentsAbs, 'utf8');
-        }
-      }
-      const fsCount = countOccurrences(raw, FEATURES_START);
-      const feCount = countOccurrences(raw, FEATURES_END);
-      const fsIdx = raw.indexOf(FEATURES_START);
-      const feIdx = raw.indexOf(FEATURES_END);
-      if (fsCount === 1 && feCount === 1 && fsIdx < feIdx) {
-        add('OK', 'AGENTS.md block + features registry present');
-      } else if (fsCount === 1 && feCount === 1) {
-        // Counts are right but ORDER is inverted (end before start): any
-        // registry write would throw (upsertFeaturesRegistry requires
-        // end > start), so flag the state instead of blessing it as OK.
-        if (checkOnly) add('WOULD-FIX', 'AGENTS.md archgen:features markers are reversed -> swap them');
-        else add('FAIL', 'AGENTS.md archgen:features markers are reversed - fix manually');
-      } else if (fsCount === 0 && feCount === 0) {
-        if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing features registry -> inserted');
+    // An unreadable managed file is a FAIL row, not a reason to abort the
+    // whole doctor pass.
+    try {
+      let raw = readFileSync(agentsAbs, 'utf8');
+      const starts = countOccurrences(raw, START);
+      const ends = countOccurrences(raw, END);
+      if (starts === 0 && ends === 0) {
+        if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
         else {
-          attempt(() => upsertFeaturesRegistry(agentsAbs, []), 'FIXED',
-            'AGENTS.md features registry inserted', 'cannot insert AGENTS.md features registry');
+          attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
+            'AGENTS.md managed block added', 'cannot add AGENTS.md managed block');
         }
+      } else if (starts > 1 || ends > 1) {
+        add('FAIL', `AGENTS.md has ${starts} start / ${ends} end markers - fix manually`);
+      } else if (starts === 0 || ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
+        // Orphan/inverted markers: repairing through upsertBlock would throw, so
+        // classify as FAIL instead of attempting the write.
+        add('FAIL', 'AGENTS.md has broken archgen markers - fix manually');
       } else {
-        add('FAIL', 'AGENTS.md has broken archgen:features markers - fix manually');
+        // Block-format currency: an unversioned or older-stamped managed block is
+        // upgraded in place through the normal upsert path (everything outside the
+        // markers survives byte-for-byte by design). Newer stamps are left alone.
+        const det = detectBlockVersion(raw);
+        const parsed = det.version ? parseSemver(det.version) : null;
+        const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
+        if (stale) {
+          const from = det.version ? 'v' + det.version : 'unversioned';
+          if (checkOnly) {
+            add('WOULD-FIX', `WOULD-UPGRADE: AGENTS.md block ${from} -> v${version}`);
+          } else {
+            let upgraded = false;
+            attempt(() => { upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')); upgraded = true; },
+              'FIXED', `UPGRADED: AGENTS.md block ${from} -> v${version}`, 'cannot upgrade AGENTS.md block');
+            if (upgraded) raw = readFileSync(agentsAbs, 'utf8');
+          }
+        }
+        const fsCount = countOccurrences(raw, FEATURES_START);
+        const feCount = countOccurrences(raw, FEATURES_END);
+        const fsIdx = raw.indexOf(FEATURES_START);
+        const feIdx = raw.indexOf(FEATURES_END);
+        if (fsCount === 1 && feCount === 1 && fsIdx < feIdx) {
+          add('OK', 'AGENTS.md block + features registry present');
+        } else if (fsCount === 1 && feCount === 1) {
+          // Counts are right but ORDER is inverted (end before start): any
+          // registry write would throw (upsertFeaturesRegistry requires
+          // end > start), so flag the state instead of blessing it as OK.
+          if (checkOnly) add('WOULD-FIX', 'AGENTS.md archgen:features markers are reversed -> swap them');
+          else add('FAIL', 'AGENTS.md archgen:features markers are reversed - fix manually');
+        } else if (fsCount === 0 && feCount === 0) {
+          if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing features registry -> inserted');
+          else {
+            attempt(() => upsertFeaturesRegistry(agentsAbs, []), 'FIXED',
+              'AGENTS.md features registry inserted', 'cannot insert AGENTS.md features registry');
+          }
+        } else {
+          add('FAIL', 'AGENTS.md has broken archgen:features markers - fix manually');
+        }
       }
+    } catch (e) {
+      add('FAIL', 'cannot read AGENTS.md: ' + e.message + ' - fix manually');
     }
   }
 
@@ -249,18 +285,44 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
         'CLAUDE.md created with @AGENTS.md bridge', 'cannot create CLAUDE.md bridge');
     }
   } else {
-    const raw = readFileSync(claudeMdAbs, 'utf8');
-    const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
-    const imports = body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
-    const starts = countOccurrences(raw, START);
-    const ends = countOccurrences(raw, END);
-    if (imports && starts <= 1 && ends <= 1) add('OK', 'CLAUDE.md bridges to AGENTS.md');
-    else if (starts > 1 || ends > 1) add('FAIL', 'CLAUDE.md has multiple archgen blocks - fix manually');
-    else if (starts !== ends) add('FAIL', 'CLAUDE.md has broken archgen markers - fix manually');
-    else if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing @AGENTS.md bridge -> written');
-    else {
-      attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
-        'CLAUDE.md @AGENTS.md bridge written', 'cannot write CLAUDE.md bridge');
+    // An unreadable managed file is a FAIL row, not a reason to abort the
+    // whole doctor pass.
+    let raw = null;
+    try {
+      raw = readFileSync(claudeMdAbs, 'utf8');
+    } catch (e) {
+      add('FAIL', 'cannot read CLAUDE.md: ' + e.message + ' - fix manually');
+    }
+    if (raw !== null) {
+      const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+      const imports = body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
+      const starts = countOccurrences(raw, START);
+      const ends = countOccurrences(raw, END);
+      if (starts > 1 || ends > 1) add('FAIL', 'CLAUDE.md has multiple archgen blocks - fix manually');
+      else if (starts !== ends) add('FAIL', 'CLAUDE.md has broken archgen markers - fix manually');
+      else if (starts === 1) {
+        // The managed block is ours: keep its provenance stamp current, the
+        // same way the AGENTS.md block is kept current.
+        const det = detectBlockVersion(raw);
+        const parsed = det.version ? parseSemver(det.version) : null;
+        const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
+        if (stale) {
+          const from = det.version ? 'v' + det.version : 'unversioned';
+          if (checkOnly) {
+            add('WOULD-FIX', `WOULD-UPGRADE: CLAUDE.md block ${from} -> v${version}`);
+          } else {
+            attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+              `UPGRADED: CLAUDE.md block ${from} -> v${version}`, 'cannot upgrade CLAUDE.md block');
+          }
+        } else {
+          add('OK', 'CLAUDE.md bridges to AGENTS.md');
+        }
+      } else if (imports) add('OK', 'CLAUDE.md bridges to AGENTS.md');
+      else if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing @AGENTS.md bridge -> written');
+      else {
+        attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+          'CLAUDE.md @AGENTS.md bridge written', 'cannot write CLAUDE.md bridge');
+      }
     }
   }
 
@@ -271,8 +333,23 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!manifest) {
     if (existsSync(storeAbs)) add('WARN', `no install manifest at ${MANIFEST_REL} (re-run init to regenerate)`);
     else add('OK', 'no manifest (nothing installed)');
+  } else if (!Array.isArray(manifest.entries)) {
+    // A manifest without an entries array is malformed: report it instead of
+    // crashing the whole doctor pass on it.
+    add('FAIL', `manifest ${MANIFEST_REL} has no entries array - fix manually`);
   } else {
-    const resolves = (e) => e && typeof e.path === 'string' && existsSync(join(root, ...e.path.split('/')));
+    // An entry only "resolves" when its path stays inside the project root:
+    // a manifest path like `../../etc/passwd` must never count as resolved.
+    const entryAbs = (rel) => {
+      if (typeof rel !== 'string' || rel === '') return null;
+      const abs = resolve(root, ...rel.split('/'));
+      if (abs !== root && !abs.startsWith(root + sep)) return null;
+      return abs;
+    };
+    const resolves = (e) => {
+      const abs = entryAbs(e && e.path);
+      return abs !== null && existsSync(abs);
+    };
     const stale = manifest.entries.filter((e) => !resolves(e));
     if (stale.length === 0) {
       add('OK', `manifest: all ${manifest.entries.length} entr${manifest.entries.length === 1 ? 'y' : 'ies'} resolve`);
@@ -341,5 +418,5 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
 
   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 };
+  return { root, checks, tally, failures };
 }

package/lib/init.js

@@ -20,7 +20,7 @@
 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 { importsAgents, hasManagedBlock, 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';
@@ -57,6 +57,12 @@ function relJoin(rel) {
 function installClaudeAdapter(root, source, warnings) {
   const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
   const storeAbs = join(root, relJoin(STORE_REL));
+
+  // Escape check FIRST — before anything is removed or created: a symlinked
+  // .claude/.claude/skills parent must not redirect the adapter (nor the
+  // removal of a legacy copy) outside the project root.
+  assertWithinRoot(root, dirname(claudeAbs));
+
   const st = lstatSafe(claudeAbs);
   let migrating = false;
 
@@ -81,9 +87,6 @@ function installClaudeAdapter(root, source, warnings) {
     return 'kept-divergent';
   }
 
-  // Escape check: a symlinked .claude/.claude/skills parent must not redirect
-  // the adapter creation outside the project root.
-  assertWithinRoot(root, claudeAbs);
   try {
     mkdirSync(dirname(claudeAbs), { recursive: true });
     symlinkSync('../../.agents/skills/archgen', claudeAbs);
@@ -134,21 +137,44 @@ export function initProject(projectDir, packageRoot, opts = {}) {
 
   // 1. Canonical store — fingerprint before mutating (ownership check).
   const prev = lstatSafe(storeAbs);
-  if (prev) {
-    const identical = prev.isDirectory() && !prev.isSymbolicLink()
-      && hashDir(storeAbs, { ignore: [VERSION_FILE] }) === hashDir(source);
-    if (!identical) backups.push(moveToBackup(root, STORE_REL));
-  }
+  const identical = !!(prev && prev.isDirectory() && !prev.isSymbolicLink()
+    && hashDir(storeAbs, { ignore: [VERSION_FILE] }) === hashDir(source));
 
-  // Atomic install: build in a temp sibling dir, then rename into place.
+  // Atomic install: build in a temp sibling dir, then swap it into place.
+  // The current store is renamed aside (identical) or moved into the backup
+  // vault (divergent) so the swap can be undone: a failed swap puts the old
+  // store back, and a failed copy never leaves an orphan temp directory.
   const skillsParent = dirname(storeAbs);
   mkdirSync(skillsParent, { recursive: true });
   const tmp = join(skillsParent, '.archgen-tmp-' + randomBytes(6).toString('hex'));
-  cpSync(source, tmp, { recursive: true });
-  pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
-  writeStamp(tmp, version);
-  rmSync(storeAbs, { recursive: true, force: true });
-  renameSync(tmp, storeAbs);
+  const aside = join(skillsParent, '.archgen-old-' + randomBytes(6).toString('hex'));
+  let asideUsed = false;
+  try {
+    cpSync(source, tmp, { recursive: true });
+    pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
+    writeStamp(tmp, version);
+    if (lstatSafe(storeAbs)) {
+      if (identical) {
+        renameSync(storeAbs, aside);
+        asideUsed = true;
+      } else {
+        backups.push(moveToBackup(root, STORE_REL));
+      }
+    }
+    renameSync(tmp, storeAbs);
+  } catch (e) {
+    if (asideUsed) {
+      // Put the previous store back: a failed swap must never leave the
+      // project without a store.
+      try {
+        renameSync(aside, storeAbs);
+        asideUsed = false;
+      } catch { /* keep it aside rather than deleting the user's data */ }
+    }
+    rmSync(tmp, { recursive: true, force: true });
+    throw e;
+  }
+  if (asideUsed) rmSync(aside, { recursive: true, force: true });
   appendEntry(root, 'dir', STORE_REL);
 
   // 2. Claude adapter — relative symlink, never a second copy.
@@ -159,7 +185,10 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   const createdContextFiles = [];
   for (const name of CONTEXT_FILES) {
     const abs = join(root, name);
-    if (name === 'CLAUDE.md' && importsAgents(abs)) {
+    // A hand-written `@AGENTS.md` import is the user's — leave it alone. A
+    // managed block is ours: refresh it so its provenance stamp tracks the
+    // running CLI instead of freezing at the first-ever install.
+    if (name === 'CLAUDE.md' && !hasManagedBlock(abs) && importsAgents(abs)) {
       warnings.push('CLAUDE.md already imports @AGENTS.md - skipped (already-imports)');
       continue;
     }

package/lib/install.js

@@ -180,7 +180,7 @@ export function installGlobal(opts = {}) {
       noMcp: opts.mcp === false,
     });
     if (!r.ok) {
-      rows.push(['WARN', '-', 'server bootstrap incomplete — run: npx archgen-mcp bootstrap --location global --yes']);
+      rows.push(['WARN', '-', 'server bootstrap incomplete' + (r.detail ? ` (${r.detail})` : '') + ' — run: npx archgen-mcp bootstrap --location global --yes']);
     }
   }
 
@@ -196,17 +196,70 @@ function stampNote(rows, dest, write) {
   }
 }
 
-export function uninstallGlobal(home = homedir()) {
+/**
+ * The exact destinations a global install may create.
+ *
+ * A manifest entry is acted on ONLY when it names one of them. A plain
+ * suffix test (`endsWith('skills/archgen')`) would let any path with that
+ * ending be removed — including paths outside the known harness dirs.
+ */
+function allowedGlobalDestinations(home) {
+  const set = new Set(globalTargets(home).map((d) => resolve(join(d, 'archgen'))));
+  set.add(resolve(join(process.cwd(), '.github', 'skills', 'archgen')));
+  return set;
+}
+
+/**
+ * Move an edited copy-mode install into the global backup vault before it is
+ * removed: the uninstall must never be the last place those edits exist.
+ * An install that still matches the packaged skill needs no backup.
+ */
+function backupEditedCopy(dest, packageRoot, backups) {
+  let identical = false;
+  try {
+    identical = hashDir(dest) === hashDir(resolveSkillSource(packageRoot));
+  } catch {
+    identical = false; // unverifiable -> preserve it
+  }
+  if (identical) return;
+  const tdir = dirname(dest);
+  const loc = moveToBackupInto(tdir, 'archgen', GLOBAL_BACKUP_REL, nextBackupTs(tdir));
+  backups.push(join(tdir, ...loc.split('/')));
+}
+
+/**
+ * Remove the globally-installed copies recorded in the manifest.
+ *
+ * Only entries that name a known harness destination are removed. An entry
+ * that cannot be verified is SKIPPED and KEPT in the manifest — the manifest
+ * is only removed when nothing was left behind.
+ *
+ * @param {string} home home directory holding the manifest
+ * @param {{packageRoot?: string}} opts
+ */
+export function uninstallGlobal(home = homedir(), opts = {}) {
   const manifest = join(home, MANIFEST_NAME);
   if (!existsSync(manifest)) return { removed: 0, failed: 0, noop: true };
+  const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+  const allowed = allowedGlobalDestinations(home);
   let removed = 0, failed = 0;
+  const kept = [];
+  const backups = [];
   for (const line of readFileSync(manifest, 'utf8').split('\n')) {
     if (!line.trim()) continue;
     const [kind, p] = line.split('\t');
-    if (!p || !p.endsWith(join('skills', 'archgen'))) { failed++; continue; } // safety guard
-    try { rmSync(p, { force: true, recursive: true }); removed++; }
-    catch { failed++; }
+    if (!p || !allowed.has(resolve(p))) { failed++; kept.push(line); continue; } // safety guard
+    try {
+      if (kind === 'copy') backupEditedCopy(p, packageRoot, backups);
+      rmSync(p, { force: true, recursive: true }); removed++;
+    } catch { failed++; kept.push(line); }
+  }
+  if (kept.length === 0) {
+    try { rmSync(manifest, { force: true }); } catch { failed++; }
+  } else {
+    // The skipped entries stay recorded: the manifest is the only thing that
+    // knows they were never removed.
+    try { writeFileSync(manifest, kept.join('\n') + '\n'); } catch { failed++; }
   }
-  rmSync(manifest, { force: true });
-  return { removed, failed, noop: false };
+  return { removed, failed, noop: false, backups };
 }

package/lib/mcp-server.js

@@ -9,10 +9,10 @@
 // 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 { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 
 export const MCP_PACKAGE = 'archgen-mcp';
 
@@ -72,6 +72,89 @@ export function whichOnPath(bin, env = process.env) {
   return null;
 }
 
+/**
+ * Quote one argument for cmd.exe.
+ *
+ * cmd.exe parses `&`, `|`, `<`, `>`, `^` and whitespace as syntax even in an
+ * unquoted argument — an unquoted project path is split on spaces and its
+ * `&`/`|` are executed. Double quotes neutralize all of them. `%` is the one
+ * character cmd expands even inside quotes, so an argument carrying one is
+ * refused rather than silently rewritten.
+ *
+ * @param {string} arg
+ * @returns {string} the quoted argument
+ */
+export function quoteWindowsArg(arg) {
+  const s = String(arg);
+  if (s === '') return '""';
+  if (/["%]/.test(s)) {
+    throw new Error(`refusing to pass an unsafe character through the Windows shell: ${JSON.stringify(s)}`);
+  }
+  return '"' + s + '"';
+}
+
+/**
+ * Find the JS entry point a Windows npm shim launches.
+ *
+ * npm writes `<name>.cmd` beside the package it points at, and the package's
+ * package.json names the real script. Resolving it lets the script run with
+ * the current node binary — no shell, no quoting, nothing to inject.
+ *
+ * @param {string} cmdPath path of the .cmd/.bat shim
+ * @returns {string|null} absolute path of the JS entry point
+ */
+function resolveShimEntry(cmdPath) {
+  const name = basename(cmdPath).replace(/\.(cmd|bat)$/i, '');
+  const dir = dirname(cmdPath);
+  const candidates = [
+    join(dir, 'node_modules', MCP_PACKAGE), // global npm prefix
+    join(dir, '..', MCP_PACKAGE), // node_modules/.bin -> node_modules/<pkg>
+    join(dir, '..', 'node_modules', MCP_PACKAGE), // prefix/lib layout
+  ];
+  for (const pkgDir of candidates) {
+    let pkg;
+    try {
+      pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+    } catch {
+      continue; // not this layout
+    }
+    const bin = pkg && pkg.bin;
+    const rel = typeof bin === 'string' ? bin : bin && typeof bin === 'object' ? bin[name] : null;
+    if (!rel) continue;
+    const js = resolve(pkgDir, rel);
+    if (existsSync(js)) return js;
+  }
+  return null;
+}
+
+/**
+ * Build the spawn invocation for the MCP server.
+ *
+ * On Windows an npm-installed binary is a `.cmd` shim that only cmd.exe can
+ * run — and cmd.exe parses unquoted arguments as shell syntax. The shim's JS
+ * entry point is preferred (run with the current node binary, no shell at
+ * all); when it cannot be resolved, every argument is quoted for cmd.exe.
+ *
+ * @param {string} command executable to run
+ * @param {string[]} args arguments
+ * @param {string} [platform] process.platform (injectable for tests)
+ * @param {Record<string, string|undefined>} [env] environment used for lookups
+ * @returns {{command: string, args: string[], shell: boolean}}
+ */
+export function mcpInvocation(command, args, platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return { command, args, shell: false };
+  let cmd = command;
+  if (!/\.(cmd|bat)$/i.test(cmd) && !/[\\/]/.test(cmd)) {
+    // A bare name (e.g. 'npx') resolves to a .cmd shim on Windows.
+    const shim = whichOnPath(cmd + '.cmd', env);
+    if (shim) cmd = shim;
+  }
+  if (!/\.(cmd|bat)$/i.test(cmd)) return { command, args, shell: false };
+  const js = resolveShimEntry(cmd);
+  if (js) return { command: process.execPath, args: [js, ...args], shell: false };
+  return { command: quoteWindowsArg(cmd), args: args.map(quoteWindowsArg), shell: true };
+}
+
 /**
  * Run one `archgen-mcp` subcommand and return its JSON output.
  *
@@ -82,17 +165,16 @@ export function whichOnPath(bin, env = process.env) {
 export function runMcp(args, opts = {}) {
   const { projectRoot = process.cwd(), timeout = 600000, env = process.env } = opts;
   const resolved = resolveMcpBinary({ projectRoot, env });
+  const inv = mcpInvocation(resolved.command, [...resolved.args, ...args], process.platform, env);
 
   let r;
   try {
-    r = spawnSync(resolved.command, [...resolved.args, ...args], {
+    r = spawnSync(inv.command, inv.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 } : {}),
+      shell: inv.shell,
     });
   } catch (e) {
     return { ok: false, code: null, data: null, stdout: '', stderr: '', detail: String(e?.message ?? e) };