@lifeaitools/rdc-skills 0.35.15 → 0.35.17

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.35.15",
+  "version": "0.35.17",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.35.15",
+  "version": "0.35.17",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -45,7 +45,7 @@
     "rdc-design": "node scripts/rdc-design-cli.mjs",
     "test:hooks": "node scripts/test-rdc-hooks.mjs",
     "test:truth-gate": "node tests/run-evidence-gate.test.mjs && node tests/work-item-exit-gate-l2.test.mjs && node tests/work-item-exit-gate-l3.test.mjs && node tests/require-work-item-on-commit.test.mjs && node tests/harness-gates.test.mjs && node tests/foreground-process-gate.test.mjs",
-    "test:acceptance": "node tests/acceptance.test.mjs && node tests/install-rdc-skills.test.mjs && node tests/help-surface.test.mjs && node tests/manifest-contract-fields.test.mjs && node tests/plugin-namespace-names.test.mjs && node tests/skill-test-matrix.test.mjs && node tests/completion-gate-supervisor-admission.test.mjs && node tests/curl-surface.test.mjs && node tests/clauth-plugin-postinstall.test.mjs",
+    "test:acceptance": "node tests/acceptance.test.mjs && node tests/install-rdc-skills.test.mjs && node tests/help-surface.test.mjs && node tests/manifest-contract-fields.test.mjs && node tests/plugin-namespace-names.test.mjs && node tests/skill-test-matrix.test.mjs && node tests/completion-gate-supervisor-admission.test.mjs && node tests/curl-surface.test.mjs && node tests/clauth-plugin-postinstall.test.mjs && node tests/install-duplicate-purge.test.mjs",
     "acceptance": "node scripts/acceptance.mjs --changed",
     "test:mcp": "node tests/mcp.test.mjs",
     "test:mcp:remote": "node tests/mcp.test.mjs --remote",

package/scripts/install-rdc-skills.js

@@ -369,11 +369,162 @@ function buildPluginCache(cacheDir, version, gitSha) {
   }
 }
 
+// ── Is this entry a duplicate of a skill WE ship? ─────────────────────────────
+//
+// THE PREDICATE THIS REPLACES WAS DEAD. It removed an entry only when its
+// frontmatter name startsWith('rdc:'). Skills were later renamed to bare names
+// (`name: build`, not `name: rdc:build`) — the same rename the marketplace-sync
+// comment below refers to when it describes "/rdc:rdc:plan" appearing beside
+// "/rdc:plan". Measured 2026-08-30: 0 of 44 shipped skills carry an rdc: prefix.
+// So the purge matched nothing, removed nothing, and reported 0 while duplicate
+// registrations kept accumulating. Nothing failed loudly, because a purge that
+// finds nothing and a purge that cannot match anything print the same number.
+//
+// The replacement never keys on a prefix. It asks three independent questions,
+// any one of which is sufficient:
+//
+//   1. LEGACY NAME — the old rdc: prefix, kept so pre-rename installs still get
+//      cleaned. Dropping it would strand exactly the machines this function was
+//      written for.
+//   2. SYMLINK INTO OUR OWN PACKAGE — if the entry resolves to a file inside this
+//      package's skills/ tree, it IS our file, wearing a second name. That is
+//      unambiguous and survives any future rename.
+//   3. SHIPPED NAME + OUR MARKER — the name matches one we ship AND the body
+//      carries the output-contract line every rdc skill opens with. Name alone
+//      is deliberately NOT enough: a user skill legitimately called "build" must
+//      survive, and on this machine ~/.claude/skills holds clauth, coolify-*,
+//      leaflet-maps and notebooklm — none of which may ever be touched.
+//
+// Signal 3 covers 43 of 44 shipped skills; behavior-audit lacks the marker and
+// is caught by signal 2 when symlinked. A skill that is neither symlinked nor
+// marked is deliberately left alone — under-removing is recoverable, deleting a
+// user's own work is not.
+let _shippedSkillNames = null;
+function shippedSkillNames() {
+  if (_shippedSkillNames) return _shippedSkillNames;
+  _shippedSkillNames = new Set();
+  const dir = path.join(repoRoot, 'skills');
+  try {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      _shippedSkillNames.add(e.name);
+      for (const sf of ['SKILL.md', 'skill.md']) {
+        const p = path.join(dir, e.name, sf);
+        if (fs.existsSync(p)) {
+          const fm = readFrontmatter(p);
+          if (fm.name) _shippedSkillNames.add(fm.name);
+          break;
+        }
+      }
+    }
+  } catch { /* no skills/ dir — handled by the emptiness check below */ }
+  // H5: an EMPTY set silently collapses isRdcSkillDuplicate back to the legacy
+  // rdc: prefix test — i.e. back to the exact dead predicate this whole change
+  // exists to fix, reporting "0 removed", indistinguishable from success. Say so
+  // rather than returning quietly; that is the same reasoning applied to the
+  // post-purge verifier.
+  if (_shippedSkillNames.size === 0) {
+    console.warn('  ! shippedSkillNames() is EMPTY — skills/ missing or unreadable. '
+      + 'Duplicate detection is degraded to the legacy rdc: prefix only.');
+  }
+  return _shippedSkillNames;
+}
+
+const RDC_SKILL_MARKER = 'guides/output-contract.md';
+
+function resolvesInsideOurSkills(candidate) {
+  try {
+    const real = fs.realpathSync(candidate);
+    const ours = fs.realpathSync(path.join(repoRoot, 'skills'));
+    const rel = path.relative(ours, real);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is this entry PROVABLY ours, as opposed to merely suspect?
+ *
+ * Only two signals are unambiguous:
+ *   1. the legacy `rdc:` frontmatter prefix — no user names a skill that
+ *   2. it resolves inside our own skills/ tree — then it IS our file
+ *
+ * The third signal (shipped name + output-contract marker) is NOT proof: the
+ * marker is a documentation path every agent is told to follow, and 14 of the
+ * shipped names are bare generic words. A user skill called "report" that cites
+ * the output contract matches it. That entry gets quarantined, never deleted.
+ */
+function isProvablyOurRdcSkill(candidate, skillFile) {
+  const fm = readFrontmatter(skillFile);
+  if (fm.name && fm.name.startsWith('rdc:')) return true;
+  return resolvesInsideOurSkills(candidate);
+}
+
+/** Where quarantined entries go. Printed, never silently removed. */
+function rdcQuarantineDir(userSkillsDir) {
+  return path.join(userSkillsDir, '.rdc-quarantine');
+}
+
+/**
+ * Remove a duplicate — or, when we cannot prove it is ours, move it aside and
+ * say so. Returns 1 if the entry was dealt with, 0 if it was left alone.
+ *
+ * The log line is not decoration. The previous version deleted inside
+ * try{}catch{} and reported only a count, so a wrongly-removed user skill left
+ * no trace at all — indistinguishable from having removed nothing.
+ */
+function disposeRdcDuplicate(candidate, skillFile, { isDir, log = console.log } = {}) {
+  if (!isRdcSkillDuplicate(candidate, skillFile)) return 0;
+
+  if (isProvablyOurRdcSkill(candidate, skillFile)) {
+    try {
+      if (isDir) fs.rmSync(candidate, { recursive: true, force: true });
+      else fs.unlinkSync(candidate);
+      return 1;
+    } catch { return 0; }
+  }
+
+  // Suspect only. Quarantine, and name the path so it can be put back.
+  try {
+    const parent = path.dirname(candidate);
+    const qdir = rdcQuarantineDir(parent);
+    fs.mkdirSync(qdir, { recursive: true });
+    const dest = path.join(qdir, path.basename(candidate));
+    if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+    fs.renameSync(candidate, dest);
+    log(`      quarantined (name matches a shipped skill, but provenance unproven): ${candidate} -> ${dest}`);
+    return 1;
+  } catch {
+    return 0;
+  }
+}
+
+function isRdcSkillDuplicate(candidate, skillFile) {
+  const fm = readFrontmatter(skillFile);
+
+  // 1. legacy rdc: prefix — pre-rename installs
+  if (fm.name && fm.name.startsWith('rdc:')) return true;
+
+  // 2. it literally is our file, reached by another path
+  if (resolvesInsideOurSkills(candidate)) return true;
+
+  // 3. our name AND our marker — both, never name alone
+  if (fm.name && shippedSkillNames().has(fm.name)) {
+    try {
+      if (fs.readFileSync(skillFile, 'utf8').includes(RDC_SKILL_MARKER)) return true;
+    } catch { /* unreadable → not a duplicate we are confident about */ }
+  }
+
+  return false;
+}
+
 // ── User-skills cleanup ───────────────────────────────────────────────────────
 // Older installer versions wrote skill files directly to ~/.claude/skills/user/.
 // Claude Code loads that directory AND the plugin cache, so any rdc skills left
 // there produce duplicate registrations and break the resolver.
-// This function nukes any entry whose frontmatter name starts with "rdc:".
+// It delegates to isRdcSkillDuplicate() above — a prefix test alone has not
+// matched anything since skills were renamed to bare names.
 // Scans BOTH the immediate dir and nested .md files (e.g. `user/skill.md`,
 // `user/rdc-build/SKILL.md`) so pre-plugin orphans are caught regardless of
 // naming convention.
@@ -390,19 +541,13 @@ function cleanUserSkills(userSkillsDir) {
         if (fs.existsSync(p)) { skillFile = p; break; }
       }
       if (!skillFile) continue;
-      const fm = readFrontmatter(skillFile);
-      if (fm.name && fm.name.startsWith('rdc:')) {
-        try { fs.rmSync(candidate, { recursive: true, force: true }); removed++; } catch {}
-      }
+      removed += disposeRdcDuplicate(candidate, skillFile, { isDir: true });
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
       // ANY .md file at this level — including skill.md / SKILL.md / README.md
       // if their frontmatter declares an rdc:* skill. A previous version skipped
       // those names; that left an orphan rdc:build copy at user/skill.md which
       // registered as a duplicate "user" skill.
-      const fm = readFrontmatter(candidate);
-      if (fm.name && fm.name.startsWith('rdc:')) {
-        try { fs.unlinkSync(candidate); removed++; } catch {}
-      }
+      removed += disposeRdcDuplicate(candidate, candidate, { isDir: false });
     }
   }
   return removed;
@@ -417,10 +562,7 @@ function cleanGlobalSkillsRoot(skillsDir) {
     if (entry.name === 'user') continue; // handled separately
     const candidate = path.join(skillsDir, entry.name);
     if (entry.isFile() && entry.name.endsWith('.md')) {
-      const fm = readFrontmatter(candidate);
-      if (fm.name && fm.name.startsWith('rdc:')) {
-        try { fs.unlinkSync(candidate); removed++; } catch {}
-      }
+      removed += disposeRdcDuplicate(candidate, candidate, { isDir: false });
     }
   }
   return removed;
@@ -797,11 +939,7 @@ function registerCodexTarget(targetDir) {
       fs.rmSync(candidate, { recursive: true, force: true });
       removed++;
     } else {
-      const fm = readFrontmatter(path.join(candidate, 'SKILL.md'));
-      if (fm.name && fm.name.startsWith('rdc:')) {
-        fs.rmSync(candidate, { recursive: true, force: true });
-        removed++;
-      }
+      removed += disposeRdcDuplicate(candidate, path.join(candidate, 'SKILL.md'), { isDir: true });
     }
   }
 
@@ -1331,8 +1469,11 @@ async function main() {
             ? ['SKILL.md','skill.md'].map(s => path.join(p, s)).find(fs.existsSync)
             : (f.endsWith('.md') ? p : null);
           if (!skillFile) return false;
-          const fm = readFrontmatter(skillFile);
-          return fm.name && fm.name.startsWith('rdc:');
+          // Must use the SAME predicate the purge uses. When this asked a
+          // different (and dead) question, the purge removed nothing and this
+          // confirmed nothing was left — the two agreed, and agreement between
+          // a broken fix and a broken check is indistinguishable from success.
+          return isRdcSkillDuplicate(p, skillFile);
         })
       : [];
     if (stillThere.length === 0) {
@@ -1385,7 +1526,7 @@ async function main() {
 // scripts/probe-installed-hooks.mjs verify the real install path instead of
 // re-implementing it — a probe that copies its own way proves nothing about what
 // ships. Without this guard, requiring the module would run a full install.
-module.exports = { copyHookFiles, assertHooksLoadable, registerCodexTarget, syncMarketplaceCheckout, RDC_ENV_HOOK_TIMEOUT_SEC };
+module.exports = { copyHookFiles, assertHooksLoadable, registerCodexTarget, syncMarketplaceCheckout, RDC_ENV_HOOK_TIMEOUT_SEC, isRdcSkillDuplicate, cleanUserSkills, cleanGlobalSkillsRoot, shippedSkillNames, isProvablyOurRdcSkill, disposeRdcDuplicate, rdcQuarantineDir };
 
 if (require.main === module) {
   main().catch(e => { fail(e.message); process.exit(1); });

package/tests/install-duplicate-purge.test.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * The duplicate-skill purge — the predicate, not the plumbing.
+ *
+ * cleanUserSkills() and cleanGlobalSkillsRoot() removed an entry only when its
+ * frontmatter name startsWith('rdc:'). Skills were later renamed to bare names
+ * (`name: build`), and measured 2026-08-30 exactly 0 of 44 shipped skills carry
+ * an rdc: prefix. So the purge matched nothing and removed nothing, while
+ * reporting 0 — indistinguishable from "there was nothing to remove".
+ *
+ * The first test below is the one that was failing in production and could not
+ * fail here, because nothing asserted the bare-name case. The rest exist so the
+ * fix cannot over-reach: a user's own skill must survive even when it shares a
+ * name with one we ship.
+ */
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const require = createRequire(import.meta.url);
+const {
+  isRdcSkillDuplicate, cleanUserSkills, cleanGlobalSkillsRoot, shippedSkillNames,
+  isProvablyOurRdcSkill, rdcQuarantineDir,
+} = require(join(REPO_ROOT, 'scripts', 'install-rdc-skills.js'));
+
+const MARKER = 'guides/output-contract.md';
+let sandbox;
+function fresh() {
+  sandbox = mkdtempSync(join(tmpdir(), 'rdc-purge-'));
+  return sandbox;
+}
+function skillDir(root, name, body) {
+  const d = join(root, name);
+  mkdirSync(d, { recursive: true });
+  writeFileSync(join(d, 'SKILL.md'), body);
+  return d;
+}
+function fm(name, extra = '') {
+  return `---\nname: ${name}\ndescription: test fixture\n---\n\n${extra}\n`;
+}
+
+// ── 0. the shipped set is real, not empty ────────────────────────────────────
+// If this is empty every other assertion below passes vacuously.
+const shipped = shippedSkillNames();
+assert.ok(shipped.size > 10, `shippedSkillNames() returned ${shipped.size} — too few to be real`);
+assert.ok(shipped.has('build'), 'expected "build" among shipped skill names');
+
+// ── 1. THE REGRESSION: a bare-named copy of a skill we ship is a duplicate ───
+// This is precisely what the old startsWith('rdc:') predicate could not see.
+{
+  const root = fresh();
+  const d = skillDir(root, 'build', fm('build', `> OUTPUT CONTRACT: \`${MARKER}\``));
+  assert.equal(isRdcSkillDuplicate(d, join(d, 'SKILL.md')), true,
+    'a bare-named copy of a shipped skill must be detected as a duplicate');
+  const removed = cleanUserSkills(root);
+  assert.equal(removed, 1, 'cleanUserSkills should remove exactly the duplicate');
+  assert.equal(existsSync(d), false, 'the duplicate directory should be gone');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// ── 2. legacy rdc:-prefixed entries still get cleaned ────────────────────────
+// Pre-rename installs are the machines this function was originally written for.
+{
+  const root = fresh();
+  const d = skillDir(root, 'rdc-build', fm('rdc:build'));
+  assert.equal(isRdcSkillDuplicate(d, join(d, 'SKILL.md')), true, 'legacy rdc: prefix must still match');
+  assert.equal(cleanUserSkills(root), 1);
+  assert.equal(existsSync(d), false);
+  rmSync(root, { recursive: true, force: true });
+}
+
+// ── 3. SAFETY: a user's own skill with an unrelated name survives ────────────
+{
+  const root = fresh();
+  const d = skillDir(root, 'leaflet-maps', fm('leaflet-maps'));
+  assert.equal(isRdcSkillDuplicate(d, join(d, 'SKILL.md')), false);
+  assert.equal(cleanUserSkills(root), 0, 'must not touch a user skill');
+  assert.equal(existsSync(d), true, "the user's own skill must survive");
+  rmSync(root, { recursive: true, force: true });
+}
+
+// ── 4. SAFETY: a shipped NAME alone is not enough to delete ──────────────────
+// Someone may legitimately write their own skill called "build". Name plus our
+// marker is required; name alone must never be sufficient.
+{
+  const root = fresh();
+  const d = skillDir(root, 'build', fm('build', 'my own build skill, nothing to do with rdc'));
+  assert.equal(isRdcSkillDuplicate(d, join(d, 'SKILL.md')), false,
+    'shipped name WITHOUT our marker must not be treated as ours');
+  assert.equal(cleanUserSkills(root), 0);
+  assert.equal(existsSync(d), true);
+  rmSync(root, { recursive: true, force: true });
+}
+
+// ── 5. a symlink into our own skills/ tree is unambiguously ours ─────────────
+// Skipped where the platform refuses symlink creation without privileges; the
+// skip is loud, so it can never be mistaken for a pass.
+{
+  const root = fresh();
+  const target = join(REPO_ROOT, 'skills', 'build');
+  let made = true;
+  try { symlinkSync(target, join(root, 'build'), 'junction'); }
+  catch { made = false; }
+  if (made) {
+    assert.equal(isRdcSkillDuplicate(join(root, 'build'), join(root, 'build', 'SKILL.md')), true,
+      'a symlink resolving inside our skills/ tree must be detected');
+  } else {
+    console.log('  SKIP symlink case — platform refused symlink creation');
+  }
+  rmSync(root, { recursive: true, force: true });
+}
+
+// ── 6. cleanGlobalSkillsRoot: flat .md orphans at the top level ─────────────
+{
+  const root = fresh();
+  const flat = join(root, 'build.md');
+  writeFileSync(flat, fm('build', `> OUTPUT CONTRACT: \`${MARKER}\``));
+  const mine = join(root, 'coolify-verify.md');
+  writeFileSync(mine, fm('coolify-verify'));
+  const removed = cleanGlobalSkillsRoot(root);
+  assert.equal(removed, 1, 'exactly the rdc orphan should go');
+  assert.equal(existsSync(flat), false, 'flat rdc orphan should be removed');
+  assert.equal(existsSync(mine), true, "the user's own flat skill must survive");
+  rmSync(root, { recursive: true, force: true });
+}
+
+// ── 7. absent directory is not an error ──────────────────────────────────────
+assert.equal(cleanUserSkills(join(tmpdir(), 'rdc-purge-does-not-exist')), 0);
+assert.equal(cleanGlobalSkillsRoot(join(tmpdir(), 'rdc-purge-does-not-exist')), 0);
+
+// ── 8. C2 REGRESSION: a user's own skill is never irrecoverably deleted ──────
+//
+// Found by independent code review and proven against the real module. Signal 3
+// is "shipped name AND body cites guides/output-contract.md" — but that marker
+// is a DOCUMENTATION PATH that CLAUDE.md and AGENTS.md tell every agent to
+// follow, and 14 of the shipped names are bare generic words (build, report,
+// status, design, open, edit, plan, deploy, help, watch, convert, release,
+// collab, review). A user skill called "report" that cites the output contract
+// matched, and was rmSync'd recursively with no backup and no log.
+//
+// It must still be MOVED (it does shadow a shipped skill), but it must be
+// recoverable, and the entry must not be classed as provably ours.
+{
+  const root = fresh();
+  const d = skillDir(root, 'report',
+    fm('report', 'My own reporting skill. House style: follow .rdc/guides/output-contract.md.'));
+
+  assert.equal(isProvablyOurRdcSkill(d, join(d, 'SKILL.md')), false,
+    "a user's own skill citing the output contract must NOT be classed as provably ours");
+
+  const removed = cleanUserSkills(root);
+  assert.equal(removed, 1, 'it still shadows a shipped skill, so it is dealt with');
+  assert.equal(existsSync(d), false, 'moved out of the load path');
+
+  const quarantined = join(rdcQuarantineDir(root), 'report');
+  assert.equal(existsSync(quarantined), true,
+    'RECOVERABLE: it must be in quarantine, never deleted');
+  assert.equal(existsSync(join(quarantined, 'SKILL.md')), true, 'contents preserved intact');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// ── 9. provably-ours entries ARE deleted outright, not quarantined ───────────
+// Quarantine is for uncertainty. A legacy rdc:-prefixed copy is unambiguous, and
+// leaving it in a sibling directory would just be litter.
+{
+  const root = fresh();
+  const d = skillDir(root, 'rdc-plan', fm('rdc:plan'));
+  assert.equal(isProvablyOurRdcSkill(d, join(d, 'SKILL.md')), true);
+  assert.equal(cleanUserSkills(root), 1);
+  assert.equal(existsSync(d), false);
+  assert.equal(existsSync(join(rdcQuarantineDir(root), 'rdc-plan')), false,
+    'provably ours is deleted, not quarantined');
+  rmSync(root, { recursive: true, force: true });
+}
+
+console.log('install-rdc-skills duplicate-purge test — PASS');