archgen-skill 0.0.3 → 0.0.4

package/README.md

@@ -77,6 +77,16 @@ architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — vers
 | `npx archgen-skill doctor [dir] [--check]` | Verify + auto-repair an installation: store integrity, version stamp, Claude link, blocks present exactly once, manifest resolution (`--check` reports without fixing) |
 | `npx archgen-skill --help` | Help |
 
+### Version stamp (`.archgen-version`)
+
+Every skill tree the CLI writes carries a one-line `MAJOR.MINOR.PATCH\n` stamp
+at its root — the canonical store from `init`, each `install --copy` tree, and
+the real directory behind global symlink installs. `update` refreshes it via
+its init/doctor pass. `doctor` lists every detected install with its stamped
+version (`missing` / `unknown (pre-0.1 stamp)` when absent or unparseable).
+The VS Code extension reads the same file to warn about outdated skills;
+absent or corrupt means "unknown (legacy)", never an error.
+
 ## Why archgen
 
 AI coding agents fail at scale for predictable reasons: plans with hidden cycles,

package/bin/archgen.mjs

@@ -8,6 +8,8 @@
 //                               (Claude Code, OpenCode, Cursor, agentskills)
 //   npx archgen-skill uninstall       Remove globally-installed copies (manifest-based)
 //     --project [dir]           Remove archgen from a specific project instead
+//   npx archgen-skill restore          List/restore archgen backups (project + global vaults)
+//   npx archgen-skill migrate [dir]    Evolve generated-artifact formats (--check default)
 //
 // Zero dependencies. Cross-platform (Windows included — no bash required).
 
@@ -17,6 +19,8 @@ import { installGlobal, uninstallGlobal } from '../lib/install.js';
 import { initProject } from '../lib/init.js';
 import { doctorProject } from '../lib/doctor.js';
 import { uninstallProject } from '../lib/uninstall-project.js';
+import { restoreMain } from '../lib/restore.js';
+import { migrateMain } from '../lib/migrate.js';
 import { compareSemver, fetchLatestVersion } from '../lib/version.js';
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
@@ -54,6 +58,14 @@ Usage:
                                   managed blocks, canonical store (kept when
                                   customized) and manifest; .archgen feature
                                   folders and backups are preserved
+  npx archgen-skill restore           List backup snapshots across the project and
+                                  global vaults; nothing is restored by default
+    [--snapshot <ts>]             restore that snapshot (current state is backed
+                                  up first); --project <dir> / --global scope it
+  npx archgen-skill migrate [dir]     Evolve generated-artifact formats in place;
+                                  --check (default) lists pending migrations
+    [--apply]                     apply them (every touched file is backed up)
+    [--migration <id>]            target a single migration
   npx archgen-skill update [dir]      Check npm for a newer archgen-skill, upgrade
                                   the global install when outdated, then
                                   re-init this project + doctor against the
@@ -132,6 +144,17 @@ try {
       }
       break;
     }
+    case 'restore': {
+      // restoreMain parses its own flags and returns its own exit code.
+      process.exitCode = await restoreMain(rest);
+      break;
+    }
+    case 'migrate': {
+      // migrateMain parses its own args and returns its own exit code
+      // (0 ok, 1 apply failure, 2 usage error).
+      process.exitCode = await migrateMain(rest);
+      break;
+    }
     case 'update': {
       const dir = positionalDir();
       const current = cliVersion();

package/lib/block.js

@@ -8,13 +8,70 @@
 // AGENTS.md carries the full pointer block with an embedded features registry
 // (between FEATURES_START/FEATURES_END). CLAUDE.md carries a one-line
 // `@AGENTS.md` bridge inside the same managed markers.
+//
+// Block provenance: the FIRST line inside every managed block is a machine-
+// readable `<!-- archgen:block vX.Y.Z -->` stamp sourced from the canonical
+// config (lib/config.js loadConfig()). upsertBlock normalizes every block it
+// writes to carry the CURRENT stamp, so legacy unversioned blocks upgrade in
+// place on the next init/doctor pass and detectBlockVersion() lets doctor
+// report stale formats precisely.
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { loadConfig } from './config.js';
+
+// Markers + block-format version come from the single source of truth.
+// Module-level load is safe: config resolution is module-relative and
+// deterministic, and a missing/corrupt config fails loudly at import by design.
+const CONFIG = loadConfig();
+
+export const START = CONFIG.markers.start;
+export const END = CONFIG.markers.end;
+export const FEATURES_START = CONFIG.markers.featuresStart;
+export const FEATURES_END = CONFIG.markers.featuresEnd;
+
+/** The exact provenance line rendered as the first line of a managed block. */
+export function provenanceLine() {
+  return '<!-- archgen:block v' + CONFIG.version + ' -->';
+}
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+const PROVENANCE_LINE_RE = /^<!--\s*archgen:block\s+v[^\s>]*\s*-->$/;
 
-export const START = '<!-- archgen:start (managed block - do not edit between markers) -->';
-export const END = '<!-- archgen:end -->';
-export const FEATURES_START = '<!-- archgen:features:start -->';
-export const FEATURES_END = '<!-- archgen:features:end -->';
+/**
+ * Normalize an archgen-rendered block so the current provenance line sits
+ * immediately after START: stale/differently-versioned stamps are dropped and
+ * the canonical one inserted. Blocks not beginning with START pass through
+ * untouched. Preserves the block's own CRLF/LF convention.
+ */
+function injectProvenance(block) {
+  if (typeof block !== 'string' || !block.startsWith(START)) return block;
+  const eol = block.includes('\r\n') ? '\r\n' : '\n';
+  const lines = block.split(/\r?\n/).filter((l, i) => i === 0 || !PROVENANCE_LINE_RE.test(l.trim()));
+  lines.splice(1, 0, provenanceLine());
+  return lines.join(eol);
+}
+
+/**
+ * Detect the provenance stamp of a managed block inside file content.
+ * @param {string} content file contents (BOM/CRLF tolerated)
+ * @returns {{present: boolean, version: string|null}} present=true when a
+ *   provenance line is found as the first non-empty line after START; version
+ *   is the stamped semver, or null when the line is malformed.
+ */
+export function detectBlockVersion(content) {
+  const src = String(content ?? '');
+  const s = src.indexOf(START);
+  if (s === -1) return { present: false, version: null };
+  const e = src.indexOf(END, s + START.length);
+  const head = src.slice(s + START.length, e === -1 ? undefined : e);
+  for (const line of head.split(/\r?\n/)) {
+    const t = line.trim();
+    if (t === '') continue;
+    if (!t.includes('archgen:block')) return { present: false, version: null };
+    const m = /^<!--\s*archgen:block\s+v([^\s>]+)\s*-->$/.exec(t);
+    return { present: true, version: m ? m[1] : null };
+  }
+  return { present: false, version: null };
+}
 
 /**
  * Render the archgen pointer block for a project.
@@ -24,6 +81,7 @@ export const FEATURES_END = '<!-- archgen:features:end -->';
 export function renderBlock(skillRelPath = '.agents/skills/archgen', eol = '\n') {
   return [
     START,
+    provenanceLine(),
     '# ArchGen - Architecture Generation & Autonomous Task Execution',
     '',
     'This project uses the **archgen** skill, installed at `' + skillRelPath + '/`.',
@@ -52,6 +110,23 @@ export function renderBlock(skillRelPath = '.agents/skills/archgen', eol = '\n')
   ].join(eol);
 }
 
+/**
+ * Canonical AGENTS.md managed-block text (LF-joined, provenance included).
+ * Integration contract: install.sh's heredoc is regenerated byte-identically
+ * from this function's output — do not let the two drift.
+ */
+export function renderManagedBlockText() {
+  return renderBlock();
+}
+
+/**
+ * Canonical CLAUDE.md bridge text (LF-joined, provenance included).
+ * Same integration contract as renderManagedBlockText().
+ */
+export function renderClaudeBridgeText() {
+  return [START, provenanceLine(), '@AGENTS.md', END].join('\n');
+}
+
 /**
  * Insert or replace the managed block inside existing file content.
  * @param {string} existing file contents ('' when creating new)
@@ -59,18 +134,21 @@ export function renderBlock(skillRelPath = '.agents/skills/archgen', eol = '\n')
  * @param {string} eol line ending used when appending to empty/missing files
  */
 export function upsertBlock(existing, block, eol = '\n') {
+  // Every write carries the CURRENT provenance stamp regardless of what the
+  // caller rendered — this is what upgrades legacy unversioned blocks in place.
+  const fresh = injectProvenance(block);
   const trimmed = existing ?? '';
   const startIdx = trimmed.indexOf(START);
   const endIdx = trimmed.indexOf(END);
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    return trimmed.slice(0, startIdx) + block + trimmed.slice(endIdx + END.length);
+    return trimmed.slice(0, startIdx) + fresh + trimmed.slice(endIdx + END.length);
   }
   if (startIdx !== -1 || endIdx !== -1) {
     throw new Error('found only one archgen marker - fix or remove it manually');
   }
-  if (trimmed.trim() === '') return block + eol;
+  if (trimmed.trim() === '') return fresh + eol;
   const core = trimmed.replace(/(?:\r?\n)+$/, '');
-  return core + eol + eol + block + eol;
+  return core + eol + eol + fresh + eol;
 }
 
 /**
@@ -93,6 +171,13 @@ function splitBom(raw) {
   return { bom, body: bom ? raw.slice(1) : raw };
 }
 
+/** Write via sibling temp file + rename so readers never observe partial content. */
+function atomicWrite(absPath, data) {
+  const tmp = absPath + '.tmp-' + process.pid + '-' + Date.now();
+  writeFileSync(tmp, data);
+  renameSync(tmp, absPath);
+}
+
 /**
  * BOM/EOL-aware upsert of a managed block directly into a file.
  * Preserves a leading UTF-8 BOM and the file's CRLF/LF convention.
@@ -106,7 +191,7 @@ export function upsertManagedFile(absPath, blockLines) {
   const { bom, body } = splitBom(raw);
   const eol = body.includes('\r\n') ? '\r\n' : '\n';
   const next = upsertBlock(body, blockLines.join(eol), eol);
-  writeFileSync(absPath, (bom ? '\uFEFF' : '') + next);
+  atomicWrite(absPath, (bom ? '\uFEFF' : '') + next);
   return existed;
 }
 

package/lib/config.js

@@ -0,0 +1,96 @@
+// config.js — loader for the single-source-of-truth archgen.config.json.
+//
+// WHY: the version, managed-block marker strings, and well-known filenames
+// were hardcoded independently in block.js, store.js, install.js, install.sh,
+// and SKILL.md frontmatter — and drifted (SKILL.md advertised 1.0.0 while the
+// CLI shipped 0.0.x). The canonical file lives at <repo-root>/archgen.config.json;
+// a byte-identical derived copy ships inside the published npm package at
+// vendor/skills/archgen/archgen.config.json (kept in sync by
+// scripts/sync-config.mjs + scripts/sync-vendor.mjs).
+//
+// Resolution is module-relative (cwd-independent), tried in order:
+//   1. ../../../archgen.config.json                  — monorepo checkout
+//   2. ../vendor/skills/archgen/archgen.config.json  — published package layout
+// The first readable candidate wins; a candidate that exists but cannot be
+// parsed/validated fails LOUDLY rather than silently falling through to a
+// possibly stale copy. Cached per process.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // packages/cli/lib
+
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+/** Candidate canonical-config paths for a given lib directory. */
+export function configCandidates(baseDir = HERE) {
+  return [
+    resolve(baseDir, '../../../archgen.config.json'),
+    resolve(baseDir, '../vendor/skills/archgen/archgen.config.json'),
+  ];
+}
+
+/**
+ * Parse + validate raw config JSON text.
+ * @param {string} text file contents
+ * @param {string} sourcePath path used in error messages
+ */
+export function parseConfig(text, sourcePath) {
+  let cfg;
+  try {
+    cfg = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`cannot load ${sourcePath}: invalid JSON (${e.message})`);
+  }
+  const bad = (msg) => new Error(`cannot load ${sourcePath}: ${msg}`);
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw bad('expected a JSON object');
+  if (typeof cfg.version !== 'string' || !SEMVER_RE.test(cfg.version)) {
+    throw bad(`"version" must be MAJOR.MINOR.PATCH, got ${JSON.stringify(cfg.version ?? null)}`);
+  }
+  if (typeof cfg.skillName !== 'string' || !cfg.skillName) throw bad('"skillName" must be a non-empty string');
+  const m = cfg.markers;
+  if (!m || typeof m !== 'object') throw bad('"markers" object is required');
+  for (const k of ['start', 'end', 'featuresStart', 'featuresEnd']) {
+    if (typeof m[k] !== 'string' || !m[k]) throw bad(`"markers.${k}" must be a non-empty string`);
+  }
+  const f = cfg.files;
+  if (!f || typeof f !== 'object') throw bad('"files" object is required');
+  for (const k of ['stamp', 'projectManifest', 'globalManifest', 'backupDir']) {
+    if (typeof f[k] !== 'string' || !f[k]) throw bad(`"files.${k}" must be a non-empty string`);
+  }
+  return cfg;
+}
+
+/**
+ * Resolve + parse the canonical config relative to `baseDir` (a lib dir).
+ * @returns {object} the validated config object
+ */
+export function loadConfigFrom(baseDir) {
+  const candidates = configCandidates(baseDir);
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    let text = '';
+    try {
+      text = readFileSync(p, 'utf8');
+    } catch (e) {
+      throw new Error(`cannot load ${p}: ${e.message}`);
+    }
+    return parseConfig(text, p);
+  }
+  throw new Error(
+    'archgen config not found. Expected one of:\n' +
+      candidates.map((c) => '  - ' + c).join('\n') +
+      '\nIn a repository checkout archgen.config.json lives at the repo root; ' +
+      'in the published package it is vendored at vendor/skills/archgen/. ' +
+      'Run `npm run sync:config` inside packages/cli to (re)generate both.',
+  );
+}
+
+let cached = null;
+
+/** Load the canonical config for this process (cached after first call). */
+export function loadConfig() {
+  if (!cached) cached = loadConfigFrom(HERE);
+  return cached;
+}

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, 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 { CLAUDE_LINK_REL, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, loadManifest, saveManifest } from './store.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; }
@@ -35,27 +43,59 @@ 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)');
+    }
   }
 
   // 2. Version stamp currency.
@@ -69,9 +109,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.
@@ -111,28 +150,56 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
       add('FIXED', 'AGENTS.md created with 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 +211,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 +222,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 +250,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 { writeStamp } from './version-stamp.js';
 
 const CONTEXT_FILES = ['AGENTS.md', 'CLAUDE.md'];
 
@@ -128,7 +129,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 });
-  writeFileSync(join(tmp, VERSION_FILE), version + '\n');
+  writeStamp(tmp, version);
   rmSync(storeAbs, { recursive: true, force: true });
   renameSync(tmp, storeAbs);
   appendEntry(root, 'dir', STORE_REL);