archgen-skill 0.0.3 → 0.0.5

package/README.md

@@ -32,15 +32,15 @@ What `init` writes (nothing is ever duplicated):
 
 | Path | What |
 | --- | --- |
-| `.agents/skills/archgen/` | **The only real copy** — the agentskills.io standard location read natively by OpenCode, Cursor, Codex, Gemini CLI, Copilot and Antigravity |
-| `.claude/skills/archgen → ../../.agents/skills/archgen` | Relative symlink for Claude Code (the one harness needing it). Skipped gracefully where symlinks need privileges — Claude still works via the bridge below |
-| `AGENTS.md` | Managed hub block: skill pointer + quick triggers + a features registry that stays current as you add features |
-| `CLAUDE.md` | One-line bridge: `@AGENTS.md` (existing files keep all their content; if it already imports AGENTS.md we write nothing) |
+| `.agents/skills/archgen/` | **The only real copy** — the agentskills.io standard location, read natively by OpenCode, Cursor, Codex, Gemini CLI, Copilot, and Antigravity |
+| `.claude/skills/archgen → ../../.agents/skills/archgen` | Relative symlink for Claude Code (the one harness that needs it); skipped gracefully where symlinks require privileges |
+| `AGENTS.md` | Managed hub block: skill pointer, quick triggers, and a features registry that stays current as you add features |
+| `CLAUDE.md` | One-line bridge: `@AGENTS.md` (existing content is preserved; nothing is written if it already imports AGENTS.md) |
 
-Existing projects with user content are safe: managed blocks upsert between
-markers, modified skill copies are backed up to `.archgen/.backup/<timestamp>/`
-before refresh, and legacy dual-copy layouts are migrated to symlinks
-automatically. Verify anytime with `archgen-skill doctor`.
+Existing projects are safe: managed blocks upsert between markers, modified skill
+copies are backed up to `.archgen/.backup/<timestamp>/` before refresh, and legacy
+dual-copy layouts are migrated to symlinks automatically. Verify anytime with
+`archgen-skill doctor`.
 
 **Or install globally** into every detected harness:
 
@@ -49,12 +49,13 @@ npx archgen-skill install          # symlinks; --copy for real copies
 ```
 
 Prefer shell? Clone the repo and run `./install.sh` (same behavior, plus
-`--init`, `--project`, `--uninstall`). Requires Node.js ≥ 18.
-The skill itself has zero npm dependencies.
+`--init`, `--project`, `--uninstall`). Requires Node.js ≥ 18. The skill itself
+has zero npm dependencies.
 
 ## Quick start
 
-After `npx archgen-skill init`, open your project in any supported agent and talk naturally:
+After `npx archgen-skill init`, open your project in any supported agent and talk
+naturally:
 
 | You say | What runs |
 | --- | --- |
@@ -64,29 +65,33 @@ After `npx archgen-skill init`, open your project in any supported agent and tal
 | *"roll back the auth changes"* | Impact analysis → reverse-order revert plan → approval |
 
 Everything archgen produces lives in one reviewable `.archgen/<slug>/` folder —
-architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — versioned by git.
+architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — versioned
+by git.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `npx archgen-skill init [dir]` | Install the single canonical skill store at `.agents/skills/archgen`, add the Claude symlink adapter, write the AGENTS.md hub + CLAUDE.md `@AGENTS.md` bridge |
+| `npx archgen-skill init [dir]` | Prepare a project: canonical skill store at `.agents/skills/archgen`, Claude symlink adapter, AGENTS.md hub + CLAUDE.md bridge |
 | `npx archgen-skill install [--copy]` | Install into global harness skill dirs (symlinks by default, real copies with `--copy`) |
 | `npx archgen-skill uninstall` | Remove globally-installed copies (manifest-recorded, safe removal) |
-| `npx archgen-skill uninstall --project [dir]` | Remove project install: strips managed blocks, our symlink and the store **only if unmodified** — feature folders in `.archgen/` and all user content are preserved |
-| `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 |
+| `npx archgen-skill uninstall --project [dir]` | Remove a project install: strips managed blocks, symlink, and store **only if unmodified** — `.archgen/` feature folders and all user content are preserved |
+| `npx archgen-skill doctor [dir] [--check]` | Verify and auto-repair an installation: store integrity, version stamp, Claude link, managed blocks, manifest (`--check` reports without fixing) |
+| `npx archgen-skill update [dir]` | Check npm for a newer `archgen-skill`, upgrade the global install if outdated, then re-init the project and run doctor against the new version |
+| `npx archgen-skill restore` | List backup snapshots; `--snapshot <ts>` restores one (current state is backed up first) |
+| `npx archgen-skill migrate [dir] [--apply]` | Evolve generated-artifact formats in place (`--check` by default; every touched file is backed up) |
+| `npx archgen-skill --version` / `--help` | Print the CLI version / show help |
 
 ## Why archgen
 
 AI coding agents fail at scale for predictable reasons: plans with hidden cycles,
 workers editing the same files, tasks without objective acceptance criteria, and no
 human checkpoint before execution. archgen makes each of these a *structural*
-guarantee rather than a hope:
+guarantee:
 
 | Guarantee | Mechanism |
 | --- | --- |
-| Plans are valid before work starts | Verifier gate — catches cycles, dangling refs, ownership overlaps, plan↔task coverage gaps |
+| Plans are valid before work starts | Verifier gate — cycles, dangling refs, ownership overlaps, plan↔task coverage |
 | You approve before code is written | Explicit user gate after verifier approval |
 | Parallel workers never collide | Disjoint `file_ownership` globs enforced per wave |
 | Task order is always correct | Topological waves from `depends_on`; chains stay sequential |
@@ -114,23 +119,17 @@ guarantee rather than a hope:
 
 ## Supported harnesses
 
-| Harness | Global install | Project-local (`init`) |
-| --- | --- | --- |
-| Claude Code | ✅ | ✅ |
-| OpenCode | ✅ | ✅ |
-| Cursor | ✅ | ✅ |
-| Codex | ✅ | ✅ |
-| Gemini CLI | ✅ | ✅ |
-| Antigravity | ✅ | ✅ |
-| Any agentskills.io harness | ✅ | ✅ |
+Claude Code, OpenCode, Cursor, Codex, Gemini CLI, Antigravity — and any
+agentskills.io-compatible harness. Both global install and project-local `init`
+are supported for all of them.
 
 ## VS Code extension (optional)
 
-A read-only visual layer that renders `.archgen/` as a live task DAG (running tasks
-pulse, edges animate), your code-dependency graph, and rendered docs — with a ▶
-button that launches your agent on any task. Install the `.vsix` from
-[GitHub Releases](https://github.com/akashmaurya99/archgen/releases). It is strictly
-a viewer: uninstalling it loses nothing.
+A read-only visual layer that renders `.archgen/` as a live task DAG, your
+code-dependency graph, and rendered docs — with a ▶ button that hands any task to
+your agent. Install it from the VS Code Marketplace or from a `.vsix` on
+[GitHub Releases](https://github.com/akashmaurya99/archgen/releases). It never
+edits anything: uninstalling it loses nothing.
 
 ## Documentation
 
@@ -139,7 +138,6 @@ a viewer: uninstalling it loses nothing.
 | [Architecture walkthrough](https://github.com/akashmaurya99/archgen/blob/main/docs/architecture.md) | Dual-mode design, gates, wave mechanics, platform detection |
 | [The skill contract](https://github.com/akashmaurya99/archgen/blob/main/skill/SKILL.md) | The full skill specification agents execute |
 | [Changelog](https://github.com/akashmaurya99/archgen/blob/main/CHANGELOG.md) | Release history |
-| [Contributing](https://github.com/akashmaurya99/archgen/blob/main/CONTRIBUTING.md) | Development setup and PR guide |
 
 ## Contributing
 

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();
@@ -170,7 +193,14 @@ try {
         break;
       }
       console.log('\nre-running init + doctor with the new binary (' + latest + ')…');
-      spawnSync(freshBin, ['init', dir], { stdio: 'inherit' });
+      const upInit = spawnSync(freshBin, ['init', dir], { stdio: 'inherit' });
+      if (upInit.status !== 0) {
+        // An aborted init (e.g. symlink refusal) must surface as a failure —
+        // running doctor over a half-finished install would mask it.
+        console.error('  ! init failed during update - doctor skipped (see message above)');
+        process.exitCode = upInit.status ?? 1;
+        break;
+      }
       spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
       break;
     }

package/lib/block.js

@@ -8,13 +8,71 @@
 // 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';
+import { assertNotSymlink } from './store.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();
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+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 + ' -->';
+}
+
+const PROVENANCE_LINE_RE = /^<!--\s*archgen:block\s+v[^\s>]*\s*-->$/;
+
+/**
+ * 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);
+}
 
-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 -->';
+/**
+ * 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 +82,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,40 +111,97 @@ 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');
+}
+
+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 stripCompleteBlocks(text) {
+  let out = text;
+  for (;;) {
+    const s = out.indexOf(START);
+    if (s === -1) break;
+    const e = out.indexOf(END, s + START.length);
+    if (e === -1) break;
+    out = out.slice(0, s) + out.slice(e + END.length);
+  }
+  return out;
+}
+
 /**
  * Insert or replace the managed block inside existing file content.
+ * Corrupted input with DUPLICATED markers (more than one START or END, e.g. a
+ * twice-appended block) is normalized: the first complete block is replaced
+ * in place, every later complete block is removed, and anything outside the
+ * markers survives — the result carries exactly one block. Orphan markers
+ * left over after normalization still throw, as does a single orphan marker.
  * @param {string} existing file contents ('' when creating new)
  * @param {string} block rendered block
  * @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 starts = countOccurrences(trimmed, START);
+  const ends = countOccurrences(trimmed, END);
+
+  if (starts > 1 || ends > 1) {
+    const s = trimmed.indexOf(START);
+    const e = s === -1 ? -1 : trimmed.indexOf(END, s + START.length);
+    if (s === -1 || e === -1) {
+      throw new Error('found only one archgen marker - fix or remove it manually');
+    }
+    const tail = stripCompleteBlocks(trimmed.slice(e + END.length));
+    if (tail.includes(START) || tail.includes(END)) {
+      throw new Error('found only one archgen marker - fix or remove it manually');
+    }
+    return trimmed.slice(0, s) + fresh + tail;
+  }
+
   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;
 }
 
 /**
- * Strip the managed block from file contents.
+ * Strip EVERY managed block from file contents (duplicated markers normalize
+ * to zero blocks, matching upsertBlock's one-block guarantee).
  * @returns {{content: string, hadBlock: boolean}}
  */
 export function stripBlock(existing) {
   const trimmed = existing ?? '';
-  const startIdx = trimmed.indexOf(START);
-  const endIdx = trimmed.indexOf(END);
-  if (startIdx === -1 || endIdx === -1) return { content: trimmed, hadBlock: false };
-  let out = trimmed.slice(0, startIdx) + trimmed.slice(endIdx + END.length);
+  const out = stripCompleteBlocks(trimmed);
+  if (out === trimmed) return { content: trimmed, hadBlock: false };
   // Collapse whitespace left behind; drop file if nothing else remains.
-  out = out.replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
-  return { content: out, hadBlock: true };
+  return { content: out.replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n'), hadBlock: true };
 }
 
 function splitBom(raw) {
@@ -93,20 +209,33 @@ 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();
+  // 'wx' (O_CREAT|O_EXCL): if the tmp name already exists — e.g. an attacker
+  // planted a symlink there to redirect the write — fail instead of following.
+  writeFileSync(tmp, data, { flag: 'wx' });
+  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.
+ * Refuses (throws) when the target is a symlink: managed files must never be
+ * written through a link (the final rename replaces the link itself, but the
+ * read+upsert would otherwise operate on attacker-chosen content).
  * @param {string} absPath target file (created when missing)
  * @param {string[]} blockLines lines between the managed markers
  * @returns {boolean} whether the file existed before the call
  */
 export function upsertManagedFile(absPath, blockLines) {
+  assertNotSymlink(absPath);
   const existed = existsSync(absPath);
   const raw = existed ? readFileSync(absPath, 'utf8') : '';
   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;
 }
 
@@ -123,6 +252,7 @@ export function importsAgents(absPath) {
 
 /** Strip the managed block from a file on disk, preserving BOM. */
 export function stripManagedFile(absPath) {
+  assertNotSymlink(absPath);
   let raw = '';
   try { raw = readFileSync(absPath, 'utf8'); } catch { return { hadBlock: false }; }
   const { bom, body } = splitBom(raw);
@@ -148,6 +278,7 @@ function renderRow(row) {
  * @returns {string} the new file content
  */
 export function upsertFeaturesRegistry(fileAbsPath, rows = []) {
+  assertNotSymlink(fileAbsPath);
   const raw = readFileSync(fileAbsPath, 'utf8');
   const table = [
     '| Feature | Status | Updated |',

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;
+}