archgen-skill 0.0.4 → 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,39 +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 |
-
-### 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.
+| `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 |
@@ -124,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
 
@@ -149,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

@@ -193,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

@@ -18,6 +18,7 @@
 
 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
@@ -127,8 +128,31 @@ 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
@@ -138,6 +162,22 @@ export function upsertBlock(existing, block, eol = '\n') {
   // 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) {
@@ -152,18 +192,16 @@ export function upsertBlock(existing, block, eol = '\n') {
 }
 
 /**
- * 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) {
@@ -174,18 +212,24 @@ function splitBom(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);
+  // '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);
@@ -208,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);
@@ -233,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/doctor.js

@@ -7,7 +7,7 @@
 // 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 { 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';
@@ -22,7 +22,7 @@ import {
   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 { 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';
 
@@ -98,6 +98,23 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     }
   }
 
+  // 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.
   const stampAbs = join(storeAbs, VERSION_FILE);
   let stamp = null;
@@ -146,8 +163,10 @@ 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 {
     let raw = readFileSync(agentsAbs, 'utf8');

package/lib/init.js

@@ -21,7 +21,7 @@ import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, r
 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'];
@@ -80,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);
@@ -116,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) {
@@ -129,6 +138,7 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   mkdirSync(skillsParent, { recursive: true });
   const tmp = join(skillsParent, '.archgen-tmp-' + randomBytes(6).toString('hex'));
   cpSync(source, tmp, { recursive: true });
+  pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
   writeStamp(tmp, version);
   rmSync(storeAbs, { recursive: true, force: true });
   renameSync(tmp, storeAbs);

package/lib/install.js

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

package/lib/store.js

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

package/lib/version-stamp.js

@@ -13,7 +13,7 @@
 
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { VERSION_FILE } from './store.js';
+import { VERSION_FILE, assertNotSymlink } from './store.js';
 
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 
@@ -42,6 +42,8 @@ export function readStamp(skillRoot) {
  */
 export function writeStamp(skillRoot, version) {
   const p = join(skillRoot, VERSION_FILE);
+  assertNotSymlink(skillRoot);
   mkdirSync(dirname(p), { recursive: true });
+  assertNotSymlink(p);
   writeFileSync(p, version + '\n', 'utf8');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Architecture generation & autonomous task execution for coding agents - conversational requirements in, dependency-ordered tasks out, executed wave-by-wave with verifier gates. Works with Claude Code, OpenCode, Cursor, Codex, Gemini CLI and any agentskills.io harness.",
   "license": "MIT",
   "type": "module",
@@ -38,9 +38,10 @@
   "bugs": {
     "url": "https://github.com/akashmaurya99/archgen/issues"
   },
-  "//": "vendor/skills/archgen is synced from ../skills/archgen by scripts/sync-vendor.mjs (run automatically via prepublishOnly). The extension ships separately as a VS Code vsix.",
+  "//": "vendor/skills/archgen is a full mirror of ../../skill synced by scripts/sync-vendor.mjs (run automatically via prepublishOnly). The extension ships separately as a VS Code vsix.",
   "scripts": {
     "sync:config": "node scripts/sync-config.mjs",
+    "sync:check": "node scripts/sync-config.mjs --check",
     "sync": "node scripts/sync-config.mjs && node scripts/sync-vendor.mjs",
     "prepublishOnly": "node scripts/sync-config.mjs && node scripts/sync-vendor.mjs",
     "test": "node --test test/*.test.mjs"