archgen-skill 0.0.3 → 0.0.5

package/lib/doctor.js

@@ -3,20 +3,28 @@
 // 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). Exit non-zero only for unrepairable failures.
+// (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.
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+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 { globalTargets } from './install.js';
 import {
   END,
   FEATURES_END,
   FEATURES_START,
   START,
+  detectBlockVersion,
   renderBlock,
   upsertFeaturesRegistry,
   upsertManagedFile,
 } from './block.js';
-import { CLAUDE_LINK_REL, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, loadManifest, saveManifest } from './store.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 { compareSemver, parseSemver } from './version.js';
+import { readStamp, writeStamp } from './version-stamp.js';
 
 function lstatSafe(p) {
   try { return lstatSync(p); } catch { return null; }
@@ -35,27 +43,76 @@ function relJoin(rel) {
 /**
  * @param {string} projectDir project root to inspect
  * @param {string} packageRoot dir containing this CLI package
- * @param {{check?: boolean}} opts check=true → report-only, no mutations
+ * @param {{check?: boolean, home?: string}} opts check=true → report-only, no
+ *   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}}
+ *            tally: Record<string, number>, failures: number}} `failures` counts
+ *   repair operations that THEMSELVES threw — advisory FAIL rows are reported
+ *   but never fail the run.
  */
 export function doctorProject(projectDir, packageRoot, opts = {}) {
   const root = resolve(projectDir);
   const checkOnly = opts.check === true;
+  const homeDir = opts.home ?? homedir();
   const version = cliVersion(packageRoot);
   const checks = [];
   const add = (status, msg) => checks.push({ status, msg });
+  let opFailures = 0;
+  // 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).
+  const attempt = (fn, okStatus, okMsg, failLabel) => {
+    try {
+      fn();
+      add(okStatus, okMsg);
+    } catch (e) {
+      opFailures++;
+      add('FAIL', `${failLabel}: ${e.message} - fix manually`);
+    }
+  };
 
   const storeAbs = join(root, relJoin(STORE_REL));
   const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
   const agentsAbs = join(root, 'AGENTS.md');
   const claudeMdAbs = join(root, 'CLAUDE.md');
 
-  // 1. Canonical store validity.
-  if (existsSync(join(storeAbs, 'SKILL.md'))) {
-    add('OK', 'store .agents/skills/archgen (SKILL.md present)');
-  } else {
+  // 1. Canonical store validity — SKILL.md alone is not enough: a store
+  //    missing whole subtrees (scripts/, references/) green-lights installs
+  //    whose entry points are gone. Divergence from the packaged skill is a
+  //    WARN, not a failure: user customization is legitimate.
+  const deferredStoreFindings = [];
+  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)));
+    if (missingCore.length > 0) {
+      // Deferred so the managed-block FAIL rows below stay FIRST: existing
+      // consumers read checks.find(FAIL) expecting the marker verdict.
+      deferredStoreFindings.push(['FAIL', `store .agents/skills/archgen is missing core ${missingCore.map((d) => d + '/').join(', ')} - run \`archgen init\``]);
+    } else {
+      let diverged = false;
+      try {
+        diverged = hashDir(storeAbs) !== hashDir(resolveSkillSource(packageRoot));
+      } catch { /* packaged skill unavailable — skip the divergence probe */ }
+      if (diverged) add('WARN', 'store .agents/skills/archgen diverges from packaged skill (customized?)');
+      else add('OK', 'store .agents/skills/archgen (SKILL.md present)');
+    }
+  }
+
+  // 1b. Prune dev-only artifacts (scripts/test) that older installers shipped
+  //     into the store. They are repo-only CI tooling and never belong in an
+  //     installed tree; removing them here cleans existing stores without a
+  //     full backup+re-copy. hashDir ignores the same subtrees, so this prune
+  //     neither masks real customization nor reads as divergence.
+  if (existsSync(storeAbs)) {
+    const devOnlyPresent = DEV_ONLY_RELPATHS.filter((rel) => existsSync(join(storeAbs, ...rel.split('/'))));
+    if (devOnlyPresent.length > 0) {
+      if (checkOnly) {
+        add('WOULD-FIX', `store carries dev-only ${devOnlyPresent.join(', ')} -> pruned`);
+      } else {
+        attempt(() => pruneDevOnly(storeAbs), 'FIXED',
+          `dev-only ${devOnlyPresent.join(', ')} pruned from store`, 'cannot prune dev-only artifacts');
+      }
+    }
   }
 
   // 2. Version stamp currency.
@@ -69,9 +126,8 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   } else if (checkOnly) {
     add('WOULD-FIX', `version stamp ${stamp || 'missing'} is stale -> ${version}`);
   } else {
-    mkdirSync(dirname(stampAbs), { recursive: true });
-    writeFileSync(stampAbs, version + '\n');
-    add('FIXED', `version stamp updated ${stamp || 'missing'} -> ${version}`);
+    attempt(() => writeStamp(storeAbs, version), 'FIXED',
+      `version stamp updated ${stamp || 'missing'} -> ${version}`, 'cannot write version stamp');
   }
 
   // 3. Claude link resolution.
@@ -107,32 +163,62 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!existsSync(agentsAbs)) {
     if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing -> created with managed block');
     else {
-      writeFileSync(agentsAbs, renderBlock(STORE_REL) + '\n');
-      add('FIXED', 'AGENTS.md created with managed block');
+      // Through the guarded upsert (not raw writeFileSync): existsSync follows
+      // symlinks, so a dangling symlink would otherwise be written through.
+      attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
+        'AGENTS.md created with managed block', 'cannot create AGENTS.md managed block');
     }
   } else {
-    const raw = readFileSync(agentsAbs, 'utf8');
+    let raw = readFileSync(agentsAbs, 'utf8');
     const starts = countOccurrences(raw, START);
     const ends = countOccurrences(raw, END);
-    if (starts === 0) {
+    if (starts === 0 && ends === 0) {
       if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
       else {
-        upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n'));
-        add('FIXED', 'AGENTS.md managed block added');
+        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 (ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
+    } 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);
-      if (fsCount === 1 && feCount === 1) add('OK', 'AGENTS.md block + features registry present');
-      else if (fsCount === 0 && feCount === 0) {
+      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 {
-          upsertFeaturesRegistry(agentsAbs, []);
-          add('FIXED', 'AGENTS.md features registry inserted');
+          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');
@@ -144,8 +230,8 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!existsSync(claudeMdAbs)) {
     if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing -> created with @AGENTS.md bridge');
     else {
-      upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]);
-      add('FIXED', 'CLAUDE.md created with @AGENTS.md bridge');
+      attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+        'CLAUDE.md created with @AGENTS.md bridge', 'cannot create CLAUDE.md bridge');
     }
   } else {
     const raw = readFileSync(claudeMdAbs, 'utf8');
@@ -155,13 +241,16 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     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 {
-      upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]);
-      add('FIXED', 'CLAUDE.md @AGENTS.md bridge written');
+      attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+        'CLAUDE.md @AGENTS.md bridge written', 'cannot write CLAUDE.md bridge');
     }
   }
 
+  for (const [status, msg] of deferredStoreFindings) add(status, msg);
+
   // 6. Manifest entries resolve.
   const manifest = loadManifest(root);
   if (!manifest) {
@@ -180,7 +269,34 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     }
   }
 
+  // 7. Version-stamp inventory — every archgen skill tree visible from this
+  //    project/machine, one line each, for tools that probe
+  //    <skillRoot>/.archgen-version (the VS Code extension reads it to warn
+  //    "skill outdated"). Report-only: doctor repairs the project stamp in
+  //    section 2, never global installs.
+  const seen = new Set();
+  const installs = [];
+  const noteInstall = (p) => {
+    // Dedupe by realpath (two harness dirs may link one tree) but DISPLAY the
+    // discovered path — that is the path tools probe <skillRoot>/.archgen-version through.
+    let real;
+    try { real = realpathSync(p); } catch { return; } // vanished mid-scan
+    if (!seen.has(real)) { seen.add(real); installs.push(p); }
+  };
+  if (existsSync(storeAbs)) noteInstall(storeAbs);
+  for (const t of globalTargets(homeDir)) {
+    const p = join(t, 'archgen');
+    if (existsSync(p)) noteInstall(p);
+  }
+  const ghSkills = join(root, '.github', 'skills', 'archgen');
+  if (existsSync(ghSkills)) noteInstall(ghSkills);
+  for (const p of installs) {
+    const v = readStamp(p);
+    const slot = v ?? (existsSync(join(p, VERSION_FILE)) ? 'unknown (pre-0.1 stamp)' : 'missing');
+    add(v ? 'OK' : 'WARN', `skill ${p}: ${slot}`);
+  }
+
   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: tally.FAIL };
+  return { root, checks, tally, failures: opFailures };
 }

package/lib/init.js

@@ -17,11 +17,12 @@
 //   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, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, 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';
 
 const CONTEXT_FILES = ['AGENTS.md', 'CLAUDE.md'];
 
@@ -79,6 +80,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);
@@ -115,6 +119,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) {
@@ -128,7 +138,8 @@ 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 });
-  writeFileSync(join(tmp, VERSION_FILE), version + '\n');
+  pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
+  writeStamp(tmp, version);
   rmSync(storeAbs, { recursive: true, force: true });
   renameSync(tmp, storeAbs);
   appendEntry(root, 'dir', STORE_REL);

package/lib/install.js

@@ -2,19 +2,31 @@
 // Installs the archgen skill into every EXISTING harness skills dir; manifest
 // records entries so --uninstall removes exactly what we put there.
 
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, lstatSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync, lstatSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 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';
 
 // 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.
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const MANIFEST_NAME = '.archgen-install-manifest.list';
+export const MANIFEST_NAME = loadConfig().files.globalManifest;
 
-function globalTargets(home = homedir()) {
+// Global backup vault: global installs live OUTSIDE any project, so there is
+// no project root to host `.archgen/.backup/`. Convention chosen instead: each
+// harness skills dir keeps its own sibling vault at
+//   <skills-dir>/.archgen-backups/<ISO-timestamp>/archgen/
+// — a dot-prefixed sibling (never scanned as a skill by harnesses), colocated
+// with what it protects, and discovered by lib/restore.js alongside the
+// project vault.
+export const GLOBAL_BACKUP_REL = '.archgen-backups';
+
+export function globalTargets(home = homedir()) {
   return [
     join(home, '.claude', 'skills'),
     join(home, '.agents', 'skills'),
@@ -24,6 +36,7 @@ function globalTargets(home = homedir()) {
 }
 
 function record(manifest, kind, path) {
+  assertNotSymlink(manifest);
   const line = `${kind}\t${path}`;
   let dup = false;
   if (existsSync(manifest)) {
@@ -32,41 +45,136 @@ function record(manifest, kind, path) {
   if (!dup) writeFileSync(manifest, (existsSync(manifest) ? readFileSync(manifest, 'utf8').replace(/\n*$/, '\n') : '') + line + '\n');
 }
 
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+/** Collision-free timestamp for `<tdir>/.archgen-backups/<ts>/` (ms clock can tick twice). */
+function nextBackupTs(tdir) {
+  for (;;) {
+    const ts = new Date().toISOString().replace(/:/g, '-');
+    if (!existsSync(join(tdir, GLOBAL_BACKUP_REL, ts))) return ts;
+  }
+}
+
 /**
- * @param {{copy?: boolean, home?: string}} opts
+ * @param {{copy?: boolean, home?: string, packageRoot?: string}} 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.
  */
 export function installGlobal(opts = {}) {
   const home = opts.home ?? homedir();
   if (!home) throw new Error('$HOME is not set; cannot resolve target directories.');
-  const source = resolve(resolveSkillSource(opts.packageRoot ?? PACKAGE_ROOT));
+  const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+  const source = resolve(resolveSkillSource(packageRoot));
+  const version = cliVersion(packageRoot);
   const manifest = join(home, MANIFEST_NAME);
   const rows = [];
+  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) {
-        rmSync(dest, { force: true, recursive: true });
-        cpSync(source, dest, { recursive: true });
-        record(manifest, 'copy', dest);
-        rows.push(['OK', 'copy', dest]);
+        // 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; }
+        }
+        if (identical) {
+          stampNote(rows, dest, () => writeStamp(dest, version));
+          record(manifest, 'copy', dest);
+          rows.push(['SAME', 'copy', dest]);
+        } else {
+          if (prev) {
+            const loc = moveToBackupInto(tdir, 'archgen', GLOBAL_BACKUP_REL, nextBackupTs(tdir));
+            const abs = join(tdir, ...loc.split('/'));
+            backups.push(abs);
+            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]);
+        }
       } else {
-        let same = false;
-        try { same = lstatSync(dest).isSymbolicLink(); } catch { /* absent */ }
-        if (!same) symlinkSync(source, dest, 'dir');
+        let status = 'OK';
+        const prev = lstatSafe(dest);
+        if (prev && prev.isSymbolicLink()) {
+          if (existsSync(dest)) {
+            // A live link resolving anywhere but our source belongs to the
+            // user: leave it untouched and OUT of the uninstall manifest, or
+            // `uninstall` would later delete their link. (install.sh replaces
+            // foreign links via ln -sfn — that destructive semantic is
+            // deliberately NOT copied here.)
+            const linkTarget = resolve(dirname(dest), readlinkSync(dest));
+            if (linkTarget !== source) {
+              rows.push(['KEPT', '-', dest + ' (foreign symlink, not recorded)']);
+              continue;
+            }
+            status = 'SAME';
+          } else {
+            // Dangling (npx cache eviction): recreate against the current
+            // source instead of leaving users broken while reporting SAME.
+            unlinkSync(dest); // removes the link itself, never any target
+            symlinkSync(source, dest, 'dir');
+            status = 'REPAIRED';
+          }
+        } else if (!prev) {
+          symlinkSync(source, dest, 'dir');
+        } else {
+          // Real directory/file at dest is NEVER clobbered: symlinkSync fails
+          // with EEXIST and surfaces as FAILED below (historical behavior).
+          symlinkSync(source, dest, 'dir');
+        }
+        // The link itself holds no bytes: the stamp must live INSIDE the real
+        // directory the link resolves to (the shared copy) so a read of
+        // <link>/.archgen-version sees it — true for symlinks and Windows
+        // junctions alike.
+        stampNote(rows, dest, () => writeStamp(source, version));
         record(manifest, 'link', dest);
-        rows.push([same ? 'SAME' : 'OK', 'link', dest]);
+        rows.push([status, 'link', dest]);
       }
     } catch (e) {
       failures++;
       rows.push(['FAILED', '-', dest + ' (' + e.message + ')']);
     }
   }
-  return { rows, failures, manifest };
+  return { rows, failures, manifest, backups };
+}
+
+/** Install succeeded even when the stamp could not be written (e.g. read-only vendor); surface it without failing. */
+function stampNote(rows, dest, write) {
+  try {
+    write();
+  } catch (e) {
+    rows.push(['WARN', '-', dest + ' (installed; version stamp not written: ' + e.message + ')']);
+  }
 }
 
 export function uninstallGlobal(home = homedir()) {

package/lib/migrate.js

@@ -0,0 +1,88 @@
+// migrate.js — `archgen migrate [dir] [--check] [--apply] [--migration <id>]`.
+//
+// Evolves generated-artifact formats in existing projects with zero data loss.
+// Tone and safety model mirror doctor: dry-run is the DEFAULT (--check lists
+// pending migrations and the exact files they would touch, writing nothing);
+// --apply runs them, snapshotting every affected file into
+// .archgen/.backup/<ts>/migrate/ BEFORE any modification. Exit codes:
+//   0  nothing pending, or all migrations applied cleanly
+//   1  a migration failed mid-apply (earlier files stay backed up)
+//   2  usage error (unknown flag / unknown --migration id / --check + --apply)
+//
+// bin/archgen.mjs wiring (integrator):
+//   case 'migrate': process.exitCode = await migrateMain(rest); break;
+
+import { applyMigration, listMigrations, pendingMigrations } from './migrations/index.mjs';
+import { resolve } from 'node:path';
+
+const USAGE = 'usage: archgen-skill migrate [dir] [--check|--apply] [--migration <id>]';
+
+/**
+ * @param {string[]} argv args AFTER the subcommand, e.g. ['myproj', '--apply']
+ * @returns {Promise<number>} exit code int
+ */
+export async function migrateMain(argv = []) {
+  let dir = null;
+  let check = false;
+  let apply = false;
+  let target = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check') check = true;
+    else if (a === '--apply') apply = true;
+    else if (a === '--migration') {
+      target = argv[++i];
+      if (!target || target.startsWith('-')) { console.error(USAGE); return 2; }
+    } else if (a.startsWith('-')) {
+      console.error(`unknown flag: ${a}\n${USAGE}`);
+      return 2;
+    } else if (dir === null) dir = a;
+    else { console.error(`unexpected argument: ${a}\n${USAGE}`); return 2; }
+  }
+  if (check && apply) { console.error('--check and --apply are mutually exclusive\n' + USAGE); return 2; }
+
+  const dryRun = !apply; // check mode is the default, always
+  const root = resolve(dir ?? process.cwd());
+
+  const all = await listMigrations();
+  if (target && !all.some((m) => m.id === target)) {
+    console.error(`unknown migration '${target}' (available: ${all.map((m) => m.id).join(', ') || 'none'})`);
+    return 2;
+  }
+
+  const pending = (await pendingMigrations(root)).filter((p) => !target || p.id === target);
+
+  console.log('archgen migrate — ' + root + (dryRun ? '  (check mode: no changes made)' : ''));
+
+  if (pending.length === 0) {
+    console.log('  = nothing to do — all migrations applied');
+    console.log('Summary: up to date — 0 pending');
+    return 0;
+  }
+
+  let fileCount = 0;
+  let failed = 0;
+  for (const p of pending) {
+    if (dryRun) {
+      console.log(`  [would-apply] ${p.id} — ${p.description}`);
+      for (const f of p.files) console.log(`      ${f}`);
+      fileCount += p.files.length;
+      continue;
+    }
+    try {
+      const r = await applyMigration(p.id, root, { dryRun: false });
+      if (r.status === 'clean') { console.log(`  [skip] ${r.id} — already applied`); continue; }
+      console.log(`  [applied] ${r.id} — ${r.description}`);
+      for (const b of r.backups ?? []) console.log(`      ${b.file}  (backup: ${b.backup})`);
+      fileCount += (r.files ?? []).length;
+    } catch (e) {
+      failed++;
+      console.log(`  [fail] ${p.id} — ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  if (dryRun) console.log(`Summary: ${pending.length} migration(s) pending, ${fileCount} file(s) would change`);
+  else console.log(`Summary: ${pending.length - failed} applied, ${fileCount} file(s) changed, ${failed} failure(s)`);
+  return failed > 0 ? 1 : 0;
+}