feat(setup,gen-skill-docs): prune renders of skills that no longer exist

setup gains _prune_stale_generated for every host tree and the doc generator removes gstack-* output dirs it did not write, so a skill removed from the source tree can never linger in an install.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

test/gen-skill-docs-prune-stale.test.ts

@@ -0,0 +1,36 @@
+/**
+ * gen-skill-docs prunes stale external-host renders.
+ *
+ * The generator only ever wrote outputs, so a skill deleted from the source
+ * tree stayed rendered under every host's skills/ dir (and setup kept linking
+ * it). Now a render removes `gstack-*` dirs it did not write.
+ */
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+
+describe('gen-skill-docs stale-render prune', () => {
+  test('a gstack-* dir for a skill that no longer exists is removed; the sidecar symlink and real skills stay', () => {
+    const out = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-prune-'));
+    const skills = path.join(out, '.agents', 'skills');
+    fs.mkdirSync(path.join(skills, 'gstack-retired-zzz'), { recursive: true });
+    fs.writeFileSync(path.join(skills, 'gstack-retired-zzz', 'SKILL.md'), '---\nname: gstack-retired-zzz\n---\nstale\n');
+    fs.mkdirSync(path.join(skills, 'not-ours'), { recursive: true });
+    fs.symlinkSync(ROOT, path.join(skills, 'gstack'));
+    try {
+      const r = spawnSync('bun', ['run', 'scripts/gen-skill-docs.ts', '--host', 'codex', '--out-dir', out], { cwd: ROOT, encoding: 'utf-8', timeout: 180_000 });
+      expect(r.status).toBe(0);
+      expect(r.stdout).toContain('pruned stale codex render: gstack-retired-zzz');
+      expect(fs.existsSync(path.join(skills, 'gstack-retired-zzz'))).toBe(false);
+      expect(fs.existsSync(path.join(skills, 'not-ours'))).toBe(true);
+      expect(fs.lstatSync(path.join(skills, 'gstack')).isSymbolicLink()).toBe(true);
+      expect(fs.existsSync(path.join(skills, 'gstack-ship', 'SKILL.md'))).toBe(true);
+    } finally {
+      fs.rmSync(out, { recursive: true, force: true });
+    }
+  }, 200_000);
+});

test/setup-prune-stale-generated.test.ts

@@ -0,0 +1,115 @@
+/**
+ * setup: _prune_stale_generated — generated skill dirs whose source template
+ * is gone are pruned from the per-host render tree AND from the host's skills
+ * dir, so a skill removed from the source tree can't stay live on
+ * Codex/Factory/OpenCode/Cursor/Kiro after `./setup` re-links.
+ *
+ * gen-skill-docs never deletes stale out-dir entries; setup is the one place
+ * every host install passes through. Behavior fixture: extract the helper and
+ * its gate from setup, run it against a temp tree.
+ */
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const SETUP_SRC = fs.readFileSync(path.join(ROOT, 'setup'), 'utf-8');
+
+function extractFn(name: string): string {
+  const start = SETUP_SRC.indexOf(`${name}() {`);
+  const end = SETUP_SRC.indexOf('\n}\n', start);
+  if (start < 0 || end < 0) throw new Error(`Could not locate ${name}() in setup`);
+  return SETUP_SRC.slice(start, end + 2);
+}
+
+const BANNER = '<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->\n';
+
+function mk(t: string) {
+  const src = path.join(t, 'src');
+  const gen = path.join(t, 'gen');
+  const host = path.join(t, 'host');
+  // Source templates: a flat skill and the one prefixed source (gstack-upgrade).
+  for (const s of ['qa', 'gstack-upgrade']) {
+    fs.mkdirSync(path.join(src, s), { recursive: true });
+    fs.writeFileSync(path.join(src, s, 'SKILL.md.tmpl'), 'x');
+  }
+  // Generated tree: live renders + two retired ones + the gstack sidecar.
+  for (const g of ['gstack-qa', 'gstack-upgrade', 'gstack-oldskill', 'gstack-gone', 'gstack']) {
+    fs.mkdirSync(path.join(gen, g), { recursive: true });
+    fs.writeFileSync(path.join(gen, g, 'SKILL.md'), `${BANNER}# ${g}\n`);
+  }
+  fs.mkdirSync(host, { recursive: true });
+  // Host entries: symlink (Unix), bannered real copy (Windows/Kiro), user's own dir.
+  fs.symlinkSync(path.join(gen, 'gstack-qa') + '/', path.join(host, 'gstack-qa'));
+  fs.symlinkSync(path.join(gen, 'gstack-oldskill') + '/', path.join(host, 'gstack-oldskill'));
+  fs.mkdirSync(path.join(host, 'gstack-gone'));
+  fs.writeFileSync(path.join(host, 'gstack-gone', 'SKILL.md'), `${BANNER}copy\n`);
+  fs.mkdirSync(path.join(host, 'gstack-mine'));
+  fs.writeFileSync(path.join(host, 'gstack-mine', 'SKILL.md'), '---\nname: mine\n---\nuser skill\n');
+  return { src, gen, host };
+}
+
+function runPrune(src: string, gen: string, host?: string) {
+  const script = [
+    'set -e',
+    extractFn('_owned_for_windows_refresh'),
+    extractFn('_prune_stale_generated'),
+    `_prune_stale_generated "${src}" "${gen}" ${host ? `"${host}"` : ''}`,
+  ].join('\n');
+  return spawnSync('bash', ['-c', script], { encoding: 'utf-8', timeout: 30_000 });
+}
+
+describe('setup: _prune_stale_generated', () => {
+  test('call sites: every host link + the always-run codex render are pruned', () => {
+    for (const site of [
+      '"$SOURCE_GSTACK_DIR/.agents/skills"',
+      '"$SOURCE_GSTACK_DIR/.agents/skills" "$CODEX_SKILLS"',
+      '"$SOURCE_GSTACK_DIR/.factory/skills" "$FACTORY_SKILLS"',
+      '"$SOURCE_GSTACK_DIR/.opencode/skills" "$OPENCODE_SKILLS"',
+      '"$SOURCE_GSTACK_DIR/.cursor/skills" "$CURSOR_SKILLS"',
+      '"$AGENTS_DIR" "$KIRO_SKILLS"',
+    ]) {
+      expect(SETUP_SRC).toContain(`_prune_stale_generated "$SOURCE_GSTACK_DIR" ${site}`);
+    }
+  });
+
+  test('retired renders go; live, prefixed-source, and sidecar dirs stay; host entries follow provenance', () => {
+    const t = fs.mkdtempSync(path.join(os.tmpdir(), 'prune-'));
+    try {
+      const { src, gen, host } = mk(t);
+      const r = runPrune(src, gen, host);
+      expect(r.status).toBe(0);
+      expect(r.stdout).toContain('pruned retired skill: gstack-oldskill');
+      expect(r.stdout).toContain('pruned retired skill: gstack-gone');
+
+      expect(fs.readdirSync(gen).sort()).toEqual(['gstack', 'gstack-qa', 'gstack-upgrade']);
+      // Symlink to a retired render + bannered copy of one: removed.
+      expect(fs.existsSync(path.join(host, 'gstack-oldskill'))).toBe(false);
+      expect(fs.lstatSync(path.join(host, 'gstack-oldskill'), { throwIfNoEntry: false })).toBeUndefined();
+      expect(fs.existsSync(path.join(host, 'gstack-gone'))).toBe(false);
+      // Live link and the user's own (unbannered) dir: untouched.
+      expect(fs.lstatSync(path.join(host, 'gstack-qa')).isSymbolicLink()).toBe(true);
+      expect(fs.readFileSync(path.join(host, 'gstack-mine', 'SKILL.md'), 'utf-8')).toContain('user skill');
+    } finally {
+      fs.rmSync(t, { recursive: true, force: true });
+    }
+  });
+
+  test('no host dir → prunes the render tree only; missing render tree → no-op', () => {
+    const t = fs.mkdtempSync(path.join(os.tmpdir(), 'prune-'));
+    try {
+      const { src, gen, host } = mk(t);
+      expect(runPrune(src, gen).status).toBe(0);
+      expect(fs.existsSync(path.join(gen, 'gstack-oldskill'))).toBe(false);
+      expect(fs.lstatSync(path.join(host, 'gstack-oldskill')).isSymbolicLink()).toBe(true); // dangling, but not ours to touch here
+
+      const r = runPrune(src, path.join(t, 'nope'), host);
+      expect(r.status).toBe(0);
+      expect(r.stdout).toBe('');
+    } finally {
+      fs.rmSync(t, { recursive: true, force: true });
+    }
+  });
+});