archgen-skill 0.0.4 → 0.0.6

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, cliVersion, hashDir, moveToBackup } from './store.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'];
 
@@ -80,6 +81,9 @@ 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);
@@ -96,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[]}}
  */
@@ -107,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);
@@ -116,6 +126,12 @@ export function initProject(projectDir, packageRoot, opts = {}) {
 
   const storeAbs = join(root, relJoin(STORE_REL));
 
+  // Supply-chain guards BEFORE any mutation: a symlinked store (a malicious
+  // clone can ship .agents/skills/archgen as a link to an unrelated dir) is
+  // refused, and the resolved real path must stay inside the project root.
+  assertNotSymlink(storeAbs);
+  assertWithinRoot(root, storeAbs);
+
   // 1. Canonical store — fingerprint before mutating (ownership check).
   const prev = lstatSafe(storeAbs);
   if (prev) {
@@ -129,6 +145,7 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   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);
@@ -155,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

@@ -7,9 +7,10 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveSkillSource } from './init.js';
-import { cliVersion, hashDir, moveToBackupInto } from './store.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.
@@ -36,6 +37,7 @@ export function globalTargets(home = homedir()) {
 }
 
 function record(manifest, kind, path) {
+  assertNotSymlink(manifest);
   const line = `${kind}\t${path}`;
   let dup = false;
   if (existsSync(manifest)) {
@@ -57,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.
@@ -73,17 +75,31 @@ export function installGlobal(opts = {}) {
   const backups = [];
   let failures = 0;
 
-  const targets = [...globalTargets(home), join(process.cwd(), '.github', 'skills')];
-  for (const tdir of targets) {
+  const targets = [
+    ...globalTargets(home).map((d) => [d, home]),
+    [join(process.cwd(), '.github', 'skills'), process.cwd()],
+  ];
+  for (const [tdir, base] of targets) {
     const dest = join(tdir, 'archgen');
     if (!existsSync(tdir)) { rows.push(['SKIP', '-', tdir + ' (does not exist)']); continue; }
     try {
+      // Realpath-escape guard: a symlinked harness dir (e.g. ~/.claude -> /etc)
+      // must not redirect the install outside the base it belongs to.
+      assertWithinRoot(base, tdir);
       mkdirSync(tdir, { recursive: true }); // no-op when present
       if (opts.copy) {
         // Safety invariant: fingerprint dest BEFORE mutating; identical
         // (stamp-ignoring) skips like link mode, divergent moves into the
         // vault first — nothing is rmSync'd without a prior backup of it.
         const prev = lstatSafe(dest);
+        if (prev && prev.isSymbolicLink()) {
+          // A symlink at dest is only ours when it points at this source (a
+          // previous link-mode install). Any other link is foreign: replacing
+          // it would let a planted symlink steer the copy, so refuse.
+          let linkTarget = null;
+          try { linkTarget = resolve(dirname(dest), readlinkSync(dest)); } catch { /* unreadable */ }
+          if (linkTarget !== source) throw new Error(refuseSymlinkMessage(dest));
+        }
         let identical = false;
         if (prev && prev.isDirectory() && !prev.isSymbolicLink()) {
           try { identical = hashDir(dest) === hashDir(source); } catch { identical = false; }
@@ -100,7 +116,9 @@ export function installGlobal(opts = {}) {
             rows.push(['BACKED-UP', '-', abs]);
           }
           rmSync(dest, { force: true, recursive: true }); // no-op after a move; guards exotic-FS fallbacks
+          assertNotSymlink(dest); // TOCTOU re-check: nothing may have re-linked dest between backup and copy
           cpSync(source, dest, { recursive: true });
+          pruneDevOnly(dest); // dev-only artifacts (scripts/test) never reach global --copy trees
           stampNote(rows, dest, () => writeStamp(dest, version));
           record(manifest, 'copy', dest);
           rows.push(['OK', 'copy', dest]);
@@ -148,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;
+}

package/lib/store.js

@@ -11,7 +11,11 @@
 // - hashDir() fingerprints a tree (stable-order walk of relpaths + contents,
 //   sha256) so mutations only ever happen after verifying ownership/divergence;
 // - GUARDED_RELPATHS (.claude, .agents, .claude/skills, .agents/skills) are
-//   never deleted: parent pruning stops before touching those levels.
+//   never deleted: parent pruning stops before touching those levels;
+// - assertNotSymlink()/assertWithinRoot() lstat BEFORE every write: a
+//   symlinked target (supply-chain attack: a malicious clone shipping
+//   .agents/skills/archgen or AGENTS.md as a link to an unrelated directory)
+//   is refused instead of written through.
 
 import { createHash } from 'node:crypto';
 import {
@@ -22,11 +26,12 @@ import {
   readFileSync,
   readdirSync,
   readlinkSync,
+  realpathSync,
   renameSync,
   rmSync,
   writeFileSync,
 } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { loadConfig } from './config.js';
 
 export const STORE_REL = '.agents/skills/archgen';
@@ -41,6 +46,120 @@ export const VERSION_FILE = CONFIG_FILES.stamp;
 
 const GUARDED_RELPATHS = new Set(['.claude', '.agents', '.claude/skills', '.agents/skills']);
 
+/**
+ * Dev-only skill subtrees that must NEVER be distributed to end users. The
+ * repo's own node:test suite (scripts/test) is repo-only CI tooling: nothing
+ * imports it at runtime and it references repo-only fixtures
+ * (fixtures/yaml-corpus), so it cannot run in an installed project — shipping
+ * it into installed stores or the npm payload is dead weight. It is excluded
+ * consistently from the vendor mirror, every installed-store copy, and BOTH
+ * sides of hashDir comparisons (so its presence/absence never reads as drift).
+ * scripts/lib is deliberately NOT here — it is a runtime dependency of the
+ * skill scripts (imported by next-tasks/plan-graph/set-status/doc-index/etc).
+ */
+export const DEV_ONLY_RELPATHS = ['scripts/test'];
+
+/**
+ * Subtrees that the CURRENT packaged skill no longer ships.
+ *
+ * The skill used to ship a `scripts/` tree (11 scripts + a lib/ folder). It
+ * does any more — every capability moved into the archgen MCP server. An
+ * existing install still carries that tree, and it is dead weight: nothing
+ * reads it, and it makes the store hash as DIVERGED from the packaged skill.
+ *
+ * Pruning it is a MIGRATION, not a repair: the tree is ours (it shipped in a
+ * previous version), so removing it is safe. It is never removed from a store
+ * whose packaged skill still ships the same path — the check is always
+ * "packaged skill has no such directory".
+ */
+export const OBSOLETE_RELPATHS = ['scripts'];
+
+/**
+ * The subtrees the packaged skill no longer ships that are still present in
+ * an installed tree (report-only — nothing is touched).
+ *
+ * @param {string} absRoot the installed skill tree
+ * @param {string} packagedRoot the packaged (vendor) skill tree
+ * @returns {string[]} the relpaths that are obsolete
+ */
+export function findObsolete(absRoot, packagedRoot) {
+  const found = [];
+  for (const rel of OBSOLETE_RELPATHS) {
+    if (existsSync(join(packagedRoot, ...rel.split('/')))) continue; // still shipped — not obsolete
+    if (!existsSync(join(absRoot, ...rel.split('/')))) continue;
+    found.push(rel);
+  }
+  return found;
+}
+
+/**
+ * Remove the subtrees the packaged skill no longer ships.
+ *
+ * @param {string} absRoot the installed skill tree
+ * @param {string} packagedRoot the packaged (vendor) skill tree
+ * @returns {string[]} the relpaths actually removed
+ */
+export function pruneObsolete(absRoot, packagedRoot) {
+  const removed = [];
+  for (const rel of findObsolete(absRoot, packagedRoot)) {
+    rmSync(join(absRoot, ...rel.split('/')), { recursive: true, force: true });
+    removed.push(rel);
+  }
+  return removed;
+}
+
+/** True when relpath `r` is (or lives inside) a dev-only excluded subtree. */
+function isDevOnlyRelPath(r) {
+  for (const prefix of DEV_ONLY_RELPATHS) {
+    if (r === prefix || r.startsWith(prefix + '/')) return true;
+  }
+  return false;
+}
+
+/** Canonical refusal message for every symlink-write guard (CLI + install.sh). */
+export function refuseSymlinkMessage(absPath) {
+  return 'Refusing to write through symlink at ' + absPath + ' — use --copy or remove symlink';
+}
+
+/**
+ * Supply-chain guard: lstat (never stat — the LINK itself, not its target) a
+ * path before writing it. Absent paths pass (safe to create); a symlink at
+ * the target throws so no write can ever be redirected through the link.
+ */
+export function assertNotSymlink(absPath) {
+  let st = null;
+  try { st = lstatSync(absPath); } catch { return; }
+  if (st.isSymbolicLink()) throw new Error(refuseSymlinkMessage(absPath));
+}
+
+/**
+ * Realpath-escape guard: resolve `absPath` (climbing to the nearest existing
+ * ancestor when it does not exist yet, so a symlinked PARENT dir is caught
+ * before anything is created beneath it) and refuse when the real location
+ * lands outside `rootAbs`. Catches `.agents -> /elsewhere` style redirects
+ * that a final-component lstat cannot see.
+ */
+export function assertWithinRoot(rootAbs, absPath) {
+  let rootReal;
+  try { rootReal = realpathSync(rootAbs); } catch { return; }
+  let probe = absPath;
+  for (;;) {
+    let exists = true;
+    try { lstatSync(probe); } catch { exists = false; }
+    if (exists) {
+      let real;
+      try { real = realpathSync(probe); } catch { return; } // broken chain: nothing writable through it
+      if (real !== rootReal && !real.startsWith(rootReal + sep)) {
+        throw new Error(refuseSymlinkMessage(absPath));
+      }
+      return;
+    }
+    const parent = dirname(probe);
+    if (parent === probe) return;
+    probe = parent;
+  }
+}
+
 /** Version string of this CLI package (used for the in-store stamp). */
 export function cliVersion(packageRoot) {
   return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
@@ -56,26 +175,65 @@ function byName(a, b) {
  * The version stamp is ALWAYS ignored on both sides of a comparison: it is
  * CLI metadata written at destination time (global symlink installs stamp the
  * shared real copy), never skill content, so it must not read as divergence.
+ * DEV_ONLY_RELPATHS (scripts/test) are ALSO always ignored on both sides: they
+ * are pruned from every distributed copy, so a source tree that still carries
+ * them (the dev-checkout skill/ fallback) must hash equal to an installed store
+ * that does not — while a real edit anywhere else must still read as divergence.
  * @param {string} dir absolute directory to hash
  * @param {{ignore?: string[]}} opts EXTRA relpaths to skip
  */
 export function hashDir(dir, opts = {}) {
   const ignore = new Set([VERSION_FILE, ...(opts.ignore ?? [])]);
   const hash = createHash('sha256');
-  (function walk(abs, rel) {
+  // A directory contributes its marker ONLY when its subtree contributes
+  // something. Without this, a directory holding nothing but excluded
+  // dev-only content hashed a 'd <rel>' marker on one side and nothing on the
+  // other — the two trees then read as divergent even though they are
+  // identical once the exclusions are applied.
+  //
+  // File contents are hashed as BYTES, never as strings: a lossy string
+  // round-trip would change the digest for any non-UTF-8 file.
+  const walk = (abs, rel) => {
     const entries = readdirSync(abs, { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+    const chunks = [];
     for (const ent of entries) {
       const r = rel ? rel + '/' + ent.name : ent.name;
-      if (ignore.has(r)) continue;
+      if (ignore.has(r) || isDevOnlyRelPath(r)) continue;
       const p = join(abs, ent.name);
-      if (ent.isSymbolicLink()) hash.update('l ' + r + ' -> ' + readlinkSync(p) + '\n');
-      else if (ent.isDirectory()) { hash.update('d ' + r + '\n'); walk(p, r); }
-      else { hash.update('f ' + r + '\0'); hash.update(readFileSync(p)); hash.update('\n'); }
+      if (ent.isSymbolicLink()) {
+        chunks.push(Buffer.from('l ' + r + ' -> ' + readlinkSync(p) + '\n'));
+      } else if (ent.isDirectory()) {
+        const sub = walk(p, r);
+        if (sub.length > 0) {
+          chunks.push(Buffer.from('d ' + r + '\n'));
+          chunks.push(...sub);
+        }
+      } else {
+        chunks.push(Buffer.from('f ' + r + '\0'));
+        chunks.push(readFileSync(p));
+        chunks.push(Buffer.from('\n'));
+      }
     }
-  })(dir, '');
+    return chunks;
+  };
+  for (const chunk of walk(dir, '')) hash.update(chunk);
   return hash.digest('hex');
 }
 
+/**
+ * Remove every dev-only subtree (DEV_ONLY_RELPATHS) from an absolute skill-tree
+ * root; idempotent no-op when a subtree is absent. Called after EVERY copy of
+ * the skill into a distributed location (installed store, global --copy tree,
+ * vendor mirror) so dev-only artifacts never reach end users regardless of which
+ * source resolveSkillSource picked — vendor is already pruned by sync-vendor,
+ * but the dev-checkout skill/ fallback is not, and this normalizes both.
+ */
+export function pruneDevOnly(absRoot) {
+  for (const rel of DEV_ONLY_RELPATHS) {
+    rmSync(join(absRoot, ...rel.split('/')), { recursive: true, force: true });
+  }
+}
+
 /** Load `.archgen/.install-manifest.json`; null when absent/corrupt. */
 export function loadManifest(root) {
   const p = join(root, ...MANIFEST_REL.split('/'));
@@ -91,6 +249,7 @@ export function loadManifest(root) {
 export function saveManifest(root, manifest) {
   const p = join(root, ...MANIFEST_REL.split('/'));
   mkdirSync(dirname(p), { recursive: true });
+  assertNotSymlink(p);
   writeFileSync(p, JSON.stringify(manifest, null, 2) + '\n');
 }
 
@@ -121,7 +280,13 @@ export function moveToBackupInto(root, relPath, backupRootRel, ts = new Date().t
   const srcAbs = join(root, ...relPath.split('/'));
   try {
     renameSync(srcAbs, destAbs);
-  } catch {
+  } catch (err) {
+    // Fallback copy+remove must NEVER run on a symlinked source: cpSync would
+    // read through the link and rmSync would remove it — rethrow instead so
+    // the caller refuses the replace rather than touching the link's target.
+    let st = null;
+    try { st = lstatSync(srcAbs); } catch { /* vanished mid-move */ }
+    if (st && st.isSymbolicLink()) throw err;
     cpSync(srcAbs, destAbs, { recursive: true });
     rmSync(srcAbs, { recursive: true, force: true });
   }