archgen-skill 0.0.2 → 0.0.4

package/lib/doctor.js

@@ -0,0 +1,283 @@
+// doctor.js — `archgen doctor [dir] [--check]` health-check + safe auto-repair.
+//
+// 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.
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } 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 { resolveSkillSource } from './init.js';
+import { CLAUDE_LINK_REL, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, hashDir, loadManifest, 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; }
+}
+
+function countOccurrences(haystack, needle) {
+  let n = 0;
+  for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + needle.length)) n++;
+  return n;
+}
+
+function relJoin(rel) {
+  return join(...rel.split('/'));
+}
+
+/**
+ * @param {string} projectDir project root to inspect
+ * @param {string} packageRoot dir containing this CLI package
+ * @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}} `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 — 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)');
+    }
+  }
+
+  // 2. Version stamp currency.
+  const stampAbs = join(storeAbs, VERSION_FILE);
+  let stamp = null;
+  try { stamp = readFileSync(stampAbs, 'utf8').trim(); } catch { /* absent */ }
+  if (!existsSync(storeAbs)) {
+    // already reported above; skip stamp handling without touching anything
+  } else if (stamp === version) {
+    add('OK', `version stamp ${version} (current)`);
+  } else if (checkOnly) {
+    add('WOULD-FIX', `version stamp ${stamp || 'missing'} is stale -> ${version}`);
+  } else {
+    attempt(() => writeStamp(storeAbs, version), 'FIXED',
+      `version stamp updated ${stamp || 'missing'} -> ${version}`, 'cannot write version stamp');
+  }
+
+  // 3. Claude link resolution.
+  const repairLink = () => {
+    if (checkOnly) {
+      add('WOULD-FIX', 'claude link missing/dangling -> ../../.agents/skills/archgen');
+      return;
+    }
+    try {
+      try { unlinkSync(claudeAbs); } catch { /* absent */ }
+      mkdirSync(dirname(claudeAbs), { recursive: true });
+      symlinkSync('../../.agents/skills/archgen', claudeAbs);
+      add('FIXED', 'claude link recreated -> ../../.agents/skills/archgen');
+    } catch (e) {
+      add('FAIL', 'cannot recreate claude link: ' + e.message);
+    }
+  };
+  const st = lstatSafe(claudeAbs);
+  if (st && st.isSymbolicLink()) {
+    const target = resolve(dirname(claudeAbs), readlinkSync(claudeAbs));
+    if (target === storeAbs && existsSync(claudeAbs)) add('OK', 'claude link resolves to the canonical store');
+    else if (existsSync(claudeAbs)) add('WARN', 'claude link is foreign (points elsewhere) - left untouched');
+    else repairLink();
+  } else if (st && st.isDirectory()) {
+    add('WARN', '.claude/skills/archgen is a real directory (not managed) - inspect manually');
+  } else if (st) {
+    add('WARN', '.claude/skills/archgen is a regular file - left untouched');
+  } else {
+    repairLink();
+  }
+
+  // 4. AGENTS.md — managed block exactly once, features registry inside.
+  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');
+    }
+  } 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');
+        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');
+      }
+    }
+  }
+
+  // 5. CLAUDE.md — @AGENTS.md bridge present exactly once.
+  if (!existsSync(claudeMdAbs)) {
+    if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing -> created with @AGENTS.md bridge');
+    else {
+      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');
+    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');
+    }
+  }
+
+  for (const [status, msg] of deferredStoreFindings) add(status, msg);
+
+  // 6. Manifest entries resolve.
+  const manifest = loadManifest(root);
+  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 {
+    const resolves = (e) => e && typeof e.path === 'string' && existsSync(join(root, ...e.path.split('/')));
+    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`);
+    } else if (checkOnly) {
+      add('WOULD-FIX', `manifest: ${stale.length} stale entr${stale.length === 1 ? 'y' : 'ies'} -> pruned`);
+    } else {
+      saveManifest(root, { ...manifest, entries: manifest.entries.filter(resolves) });
+      add('FIXED', `manifest: pruned ${stale.length} stale entr${stale.length === 1 ? 'y' : 'ies'}`);
+    }
+  }
+
+  // 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: opFailures };
+}

package/lib/init.js

@@ -1,13 +1,28 @@
-// init.js — project-local skill install + AGENTS.md/CLAUDE.md context files.
+// init.js — single-store project installer + AGENTS.md/CLAUDE.md context files.
 //
-// `archgen init` makes a repository SELF-CONTAINED: the skill is copied into
-// .agents/skills/archgen (committed to git, team-shared) and mirrored at
-// .claude/skills/archgen for Claude Code; AGENTS.md + CLAUDE.md carry a
-// managed pointer block so every agent harness auto-discovers the workflow.
+// `archgen init` makes a repository SELF-CONTAINED with ONE real copy of the
+// skill: the canonical store at .agents/skills/archgen (committed to git,
+// team-shared). .claude/skills/archgen becomes a RELATIVE symlink to the
+// store — skipped gracefully where symlinks are unavailable, never a second
+// copy. AGENTS.md carries a managed pointer block with an embedded features
+// registry; CLAUDE.md carries a one-line `@AGENTS.md` bridge. Every created
+// artifact is recorded in .archgen/.install-manifest.json.
+//
+// Verified-surgical safety semantics:
+// - existing paths are fingerprinted (stable-order sha256 over relpaths +
+//   contents) BEFORE any mutation;
+// - an identical store is refreshed in place; a divergent one is moved to
+//   .archgen/.backup/<timestamp>/ FIRST, then reinstalled fresh;
+// - a real-directory claude copy identical to the vendor skill is migrated
+//   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, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { renderBlock, upsertBlock } from './block.js';
+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 { writeStamp } from './version-stamp.js';
 
 const CONTEXT_FILES = ['AGENTS.md', 'CLAUDE.md'];
 
@@ -21,36 +36,124 @@ export function resolveSkillSource(packageRoot) {
   throw new Error('bundled archgen skill not found (expected vendor/skills/archgen)');
 }
 
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+function relJoin(rel) {
+  return join(...rel.split('/'));
+}
+
+/**
+ * Create the claude adapter: `<project>/.claude/skills/archgen` as a RELATIVE
+ * symlink into the canonical store. Never copies. Migration/keep semantics:
+ * - ours already -> 'existing'
+ * - real dir identical to vendor -> replaced with symlink ('migrated')
+ * - real dir modified / foreign live symlink / stray file -> hands off + warn
+ * - dangling symlink -> recreated
+ * - symlink creation fails (privileges/FS) -> skipped + warning
+ */
+function installClaudeAdapter(root, source, warnings) {
+  const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
+  const storeAbs = join(root, relJoin(STORE_REL));
+  const st = lstatSafe(claudeAbs);
+  let migrating = false;
+
+  if (st && st.isSymbolicLink()) {
+    const resolvedTarget = resolve(dirname(claudeAbs), readlinkSync(claudeAbs));
+    if (resolvedTarget === storeAbs && existsSync(claudeAbs)) return 'existing';
+    if (existsSync(claudeAbs)) {
+      warnings.push('.claude/skills/archgen is a foreign symlink - left untouched');
+      return 'kept-divergent';
+    }
+    unlinkSync(claudeAbs); // dangling: recreate ours below
+  } else if (st && st.isDirectory()) {
+    if (hashDir(claudeAbs) === hashDir(source)) {
+      rmSync(claudeAbs, { recursive: true }); // legacy dual copy -> migrate
+      migrating = true;
+    } else {
+      warnings.push('user-customized claude copy kept at .claude/skills/archgen (not managed)');
+      return 'kept-divergent';
+    }
+  } else if (st) {
+    warnings.push('.claude/skills/archgen exists and is not a directory - left untouched');
+    return 'kept-divergent';
+  }
+
+  try {
+    mkdirSync(dirname(claudeAbs), { recursive: true });
+    symlinkSync('../../.agents/skills/archgen', claudeAbs);
+    appendEntry(root, 'link', CLAUDE_LINK_REL);
+    return migrating ? 'migrated' : 'created';
+  } catch (e) {
+    warnings.push('claude adapter skipped: symlink unavailable (' + e.message + ')');
+    return 'skipped';
+  }
+}
+
 /**
- * Initialize a project: copy the skill locally + write context pointers.
+ * Initialize a project: install the single canonical skill store, wire the
+ * claude adapter, and write context pointers.
  * @param {string} projectDir target repo root
  * @param {string} packageRoot dir containing this CLI package
- * @returns {{skillCopies: string[], contextFiles: string[], createdContextFiles: string[]}}
+ * @param {{force?: boolean}} opts --force proceeds automatically; divergent
+ *   copies are always auto-backed-up (never refused, never destroyed)
+ * @returns {{storePath: string, claudeLink: 'created'|'existing'|'migrated'|'skipped'|'kept-divergent',
+ *            backups: string[], contextFiles: string[], createdContextFiles: string[], warnings: string[]}}
  */
-export function initProject(projectDir, packageRoot) {
+export function initProject(projectDir, packageRoot, opts = {}) {
+  // --force is accepted for explicitness: this installer never refuses and
+  // never destroys data — divergent copies are backed up automatically, so
+  // both plain and --force runs take the same safe path.
+  const force = opts.force === true;
+  void force;
+
   const root = resolve(projectDir);
   const source = resolveSkillSource(packageRoot);
+  const version = cliVersion(packageRoot);
+  const warnings = [];
+  const backups = [];
+
+  const storeAbs = join(root, relJoin(STORE_REL));
+
+  // 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));
+  }
+
+  // Atomic install: build in a temp sibling dir, then rename into place.
+  const skillsParent = dirname(storeAbs);
+  mkdirSync(skillsParent, { recursive: true });
+  const tmp = join(skillsParent, '.archgen-tmp-' + randomBytes(6).toString('hex'));
+  cpSync(source, tmp, { recursive: true });
+  writeStamp(tmp, version);
+  rmSync(storeAbs, { recursive: true, force: true });
+  renameSync(tmp, storeAbs);
+  appendEntry(root, 'dir', STORE_REL);
 
-  // 1. Skill copies — real files (not symlinks) so git carries them for the team.
-  const agentsSkills = join(root, '.agents', 'skills', 'archgen');
-  const claudeSkills = join(root, '.claude', 'skills', 'archgen');
-  mkdirSync(agentsSkills, { recursive: true });
-  cpSync(source, agentsSkills, { recursive: true });
-  mkdirSync(join(root, '.claude', 'skills'), { recursive: true });
-  cpSync(agentsSkills, claudeSkills, { recursive: true });
+  // 2. Claude adapter — relative symlink, never a second copy.
+  const claudeLink = installClaudeAdapter(root, source, warnings);
 
-  // 2. Context pointer files — managed blocks, user content preserved.
-  const block = renderBlock('.agents/skills/archgen');
+  // 3. Context files — managed blocks, user content preserved.
   const contextFiles = [];
-  const created = [];
+  const createdContextFiles = [];
   for (const name of CONTEXT_FILES) {
-    const p = join(root, name);
-    const existed = existsSync(p);
-    const next = upsertBlock(existed ? readFileSync(p, 'utf8') : '', block);
-    writeFileSync(p, next);
+    const abs = join(root, name);
+    if (name === 'CLAUDE.md' && importsAgents(abs)) {
+      warnings.push('CLAUDE.md already imports @AGENTS.md - skipped (already-imports)');
+      continue;
+    }
+    const existed = upsertManagedFile(
+      abs,
+      name === 'AGENTS.md' ? renderBlock(STORE_REL).split('\n') : [START, '@AGENTS.md', END],
+    );
     contextFiles.push(name);
-    if (!existed) created.push(name);
+    if (!existed) createdContextFiles.push(name);
+    appendEntry(root, 'block', name);
   }
 
-  return { skillCopies: [agentsSkills, claudeSkills], contextFiles, createdContextFiles: created };
+  return { storePath: storeAbs, claudeLink, backups, contextFiles, createdContextFiles, warnings };
 }

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 { cliVersion, hashDir, moveToBackupInto } 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'),
@@ -32,15 +44,33 @@ 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')];
@@ -50,23 +80,84 @@ export function installGlobal(opts = {}) {
     try {
       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);
+        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
+          cpSync(source, dest, { recursive: true });
+          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()) {