@hegemonart/get-design-done 1.59.3 → 1.59.5

package/scripts/build-skills.cjs

@@ -0,0 +1,146 @@
+'use strict';
+// Phase 42 — multi-harness skill build orchestrator.
+// v1.58.0 renamed source/skills/ → skill-templates/ (the source/ wrapper held only skills/
+// and added nothing). v1.58.0 ALSO gitignored skills/ as a pure build artifact — that broke
+// the Claude Code marketplace install path (Claude Code git-clones the plugin without running
+// `npm install`, so `./skills/` was absent post-clone). v1.58.1 reverts the gitignore:
+// skills/ is committed again so git-clone-based installs work; scripts/skill-templates/ remains the
+// canonical editable source; `prepare` still regenerates skills/ on contributor checkouts.
+//
+//   node scripts/build-skills.cjs [--harness <id>] [--check] [--zip]
+//
+// Reads scripts/skill-templates/**/*.md, applies the pure factory per harness config, and writes:
+//   - skills/**                            (the committed Claude-Code surface, regenerated in place)
+//   - dist/<bundleSlug>/<configDir>/skills/**  (per-harness bundles; build-only artifacts, gitignored)
+//
+// --check : no writes; verify the committed skills/ equals compile(scripts/skill-templates/),
+//           exit 1 on any byte drift. This is the CI drift gate.
+// --harness <id> : restrict to one harness (skips the skills/ in-place regen unless id === claude).
+// --zip   : after building, tar -czf dist/<bundleSlug>.tgz each bundle (graceful skip if tar absent).
+//
+// Idempotent + byte-stable: file walk is sorted; bytes are written verbatim (line endings preserved).
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { compile } = require('./lib/build/factory.cjs');
+const { CONFIGS, byId, claude } = require('./lib/build/harness-configs.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const SRC = path.join(ROOT, 'scripts', 'skill-templates');
+const SKILLS = path.join(ROOT, 'skills');
+const DIST = path.join(ROOT, 'dist');
+
+function parseArgs(argv) {
+  const out = { check: false, zip: false, harness: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check') out.check = true;
+    else if (a === '--zip') out.zip = true;
+    else if (a === '--harness') out.harness = argv[++i];
+    else if (a.startsWith('--harness=')) out.harness = a.slice('--harness='.length);
+  }
+  return out;
+}
+
+function walkMd(dir) {
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((x, y) => x.name.localeCompare(y.name))) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkMd(p));
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+/** Compile every source file for one config -> Map<relPath, string>. */
+function compileAll(config) {
+  const result = new Map();
+  for (const abs of walkMd(SRC)) {
+    const rel = path.relative(SRC, abs).split(path.sep).join('/');
+    result.set(rel, compile(fs.readFileSync(abs, 'utf8'), config));
+  }
+  return result;
+}
+
+function writeMap(map, destRoot) {
+  let written = 0;
+  for (const [rel, text] of map) {
+    const dst = path.join(destRoot, rel.split('/').join(path.sep));
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.writeFileSync(dst, text);
+    written++;
+  }
+  return written;
+}
+
+function bundleDir(config) {
+  return path.join(DIST, config.bundleSlug, config.configDir, 'skills');
+}
+
+/** Compare a compiled map against on-disk files under destRoot. Returns array of drifting rel paths. */
+function diffMap(map, destRoot) {
+  const drift = [];
+  for (const [rel, text] of map) {
+    const dst = path.join(destRoot, rel.split('/').join(path.sep));
+    let cur = null;
+    try { cur = fs.readFileSync(dst, 'utf8'); } catch { /* missing */ }
+    if (cur !== text) drift.push(rel);
+  }
+  return drift;
+}
+
+function runCheck() {
+  // v1.58.1: skills/ is committed (reverts v1.58.0 gitignore — Claude Code marketplace
+  // git-clones the plugin without running npm install, so `./skills/` MUST exist post-clone).
+  // --check is back to its original Phase 42 semantics: gate that committed skills/ matches
+  // compile(scripts/skill-templates/). If contributors edit scripts/skill-templates/ without re-running
+  // `npm run build:skills`, this catches the drift.
+  const cfg = claude();
+  const map = compileAll(cfg);
+  const driftSkills = diffMap(map, SKILLS);
+  if (driftSkills.length) {
+    process.stderr.write('build-skills --check: DRIFT detected (run `npm run build:skills` and commit).\n');
+    for (const r of driftSkills.slice(0, 10)) process.stderr.write(`  skills/${r}\n`);
+    if (driftSkills.length > 10) process.stderr.write('  ...\n');
+    return 1;
+  }
+  process.stderr.write(`build-skills --check: OK - skills/ matches scripts/skill-templates/ (${map.size} files).\n`);
+  return 0;
+}
+
+function tarBundle(config) {
+  const tgz = path.join(DIST, `${config.bundleSlug}.tgz`);
+  const r = spawnSync('tar', ['-czf', tgz, '-C', DIST, config.bundleSlug], { stdio: 'ignore' });
+  if (r.error || r.status !== 0) {
+    process.stderr.write(`  (zip skipped for ${config.bundleSlug}: tar unavailable)\n`);
+    return false;
+  }
+  return true;
+}
+
+function runBuild(opts) {
+  const targets = opts.harness ? [byId(opts.harness)].filter(Boolean) : CONFIGS;
+  if (opts.harness && targets.length === 0) {
+    process.stderr.write(`build-skills: unknown harness '${opts.harness}'\n`);
+    return 1;
+  }
+  let total = 0;
+  for (const cfg of targets) {
+    const map = compileAll(cfg);
+    total += writeMap(map, bundleDir(cfg));
+    if (cfg.id === 'claude') writeMap(map, SKILLS); // regenerate the committed Claude surface in place
+    if (opts.zip) tarBundle(cfg);
+    process.stderr.write(`  built ${cfg.bundleSlug} (${map.size} files)${cfg.id === 'claude' ? ' + skills/' : ''}\n`);
+  }
+  process.stderr.write(`build-skills: wrote ${total} files across ${targets.length} harness bundle(s).\n`);
+  return 0;
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  return opts.check ? runCheck() : runBuild(opts);
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+module.exports = { main, parseArgs, compileAll, bundleDir };

package/scripts/generate-skill-frontmatter.cjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * generate-skill-frontmatter.cjs — Phase 46 (Skill UX Polish).
+ *
+ * scripts/lib/manifest/skills.json is the single source of truth for the
+ * universal skill frontmatter fields (description, argument-hint, tools,
+ * user-invocable, disable-model-invocation). This script regenerates the
+ * frontmatter block of every scripts/skill-templates/<name>/SKILL.md from that manifest,
+ * preserving the markdown body and any non-managed frontmatter lines verbatim.
+ *
+ * Direction is forward (manifest -> source frontmatter); build-skills.cjs then
+ * propagates scripts/skill-templates -> skills/ + dist/claude-code/. A CI drift gate
+ * (--check) keeps committed frontmatter == generated.
+ *
+ * Modes:
+ *   (no flag)   regenerate scripts/skill-templates/<name>/SKILL.md frontmatter from skills.json
+ *   --check     exit 1 if any committed frontmatter differs from generated (no writes)
+ *   --extract   reverse: read current source frontmatter -> rewrite skills.json
+ *               (seed/refresh the SoT from ground truth; idempotent with forward)
+ *
+ * Managed keys (emitted in this canonical order, only when present):
+ *   name, description, argument-hint, tools, user-invocable, disable-model-invocation
+ * Everything else (color, model, writes:, ...) is carried verbatim in the record's
+ * `extra_frontmatter` array and re-emitted after the managed block.
+ *
+ * Exit: 0 ok / 1 drift (--check) / 2 error.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const SRC = path.join(ROOT, 'scripts', 'skill-templates');
+const SKILLS_JSON = path.join(ROOT, 'scripts', 'lib', 'manifest', 'skills.json');
+
+// Managed frontmatter keys <-> manifest record keys, in canonical emit order.
+const MANAGED = [
+  { fm: 'name', rec: 'name', kind: 'name' },
+  { fm: 'description', rec: 'description', kind: 'qstr' },
+  { fm: 'argument-hint', rec: 'argument_hint', kind: 'qstr' },
+  { fm: 'tools', rec: 'tools', kind: 'bare' },
+  { fm: 'user-invocable', rec: 'user_invocable', kind: 'bool' },
+  { fm: 'disable-model-invocation', rec: 'disable_model_invocation', kind: 'bool' },
+];
+const MANAGED_FM = new Set(MANAGED.map((m) => m.fm));
+
+function fail(msg) {
+  process.stderr.write(`generate-skill-frontmatter: ${msg}\n`);
+  process.exit(2);
+}
+
+function listSkillDirs() {
+  if (!fs.existsSync(SRC)) fail(`source dir not found: ${SRC}`);
+  return fs
+    .readdirSync(SRC, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(SRC, e.name, 'SKILL.md')))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/** Split a SKILL.md into { fmLines, body }. fmLines excludes the --- fences. */
+function splitFrontmatter(text, id) {
+  const norm = text.replace(/\r\n/g, '\n');
+  if (!norm.startsWith('---\n')) fail(`${id}: SKILL.md does not start with a --- frontmatter fence`);
+  const end = norm.indexOf('\n---\n', 4);
+  if (end === -1) fail(`${id}: unterminated frontmatter`);
+  const fmBlock = norm.slice(4, end + 1); // include trailing \n of last fm line
+  const body = norm.slice(end + 5); // after "\n---\n"
+  const fmLines = fmBlock.replace(/\n$/, '').split('\n');
+  return { fmLines, body };
+}
+
+function unquote(v) {
+  const t = v.trim();
+  if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) {
+    return t.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+  return t;
+}
+function quote(s) {
+  return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+/** Parse one skill's frontmatter lines into an enriched record. */
+function recordFromFrontmatter(id, fmLines) {
+  const rec = { name: id };
+  const extra = [];
+  let i = 0;
+  while (i < fmLines.length) {
+    const line = fmLines[i];
+    const m = /^([A-Za-z][\w-]*):(.*)$/.exec(line);
+    if (!m) {
+      // stray non-key line at top level — preserve verbatim
+      extra.push(line);
+      i += 1;
+      continue;
+    }
+    const key = m[1];
+    const rawVal = m[2];
+    // gather continuation lines (indented or list items or blank-within-block)
+    const block = [line];
+    let j = i + 1;
+    while (j < fmLines.length && /^(\s+\S|\s*-\s|\s*$)/.test(fmLines[j]) && !/^[A-Za-z][\w-]*:/.test(fmLines[j])) {
+      block.push(fmLines[j]);
+      j += 1;
+    }
+    const managed = MANAGED.find((mm) => mm.fm === key);
+    if (managed && block.length === 1) {
+      const v = rawVal.trim();
+      if (managed.kind === 'name') {
+        if (v !== `gdd-${id}`) rec.frontmatter_name = v;
+      } else if (managed.kind === 'bool') {
+        rec[managed.rec] = v === 'true';
+      } else if (managed.kind === 'qstr') {
+        rec[managed.rec] = unquote(v);
+      } else {
+        rec[managed.rec] = v; // bare (tools)
+      }
+    } else {
+      extra.push(...block);
+    }
+    i = j;
+  }
+  if (extra.length) rec.extra_frontmatter = extra;
+  return rec;
+}
+
+/**
+ * Emit the frontmatter block (without --- fences) for a record.
+ *
+ * Order-preserving: `name` always leads, then the managed keys are emitted in
+ * the record's own insertion order (which --extract captures from the original
+ * file order), then any non-managed lines verbatim. This keeps forward
+ * generation a byte-for-byte fixed point on the committed tree, so existing
+ * frontmatter-snapshot baselines never churn. New skills authored directly in
+ * skills.json get whatever key order their record uses.
+ */
+function frontmatterFromRecord(rec) {
+  const out = [`name: ${rec.frontmatter_name || `gdd-${rec.name}`}`];
+  const byRec = new Map(MANAGED.filter((m) => m.kind !== 'name').map((m) => [m.rec, m]));
+  for (const key of Object.keys(rec)) {
+    const m = byRec.get(key);
+    if (!m) continue; // name / frontmatter_name / extra_frontmatter / registered_in_phase / aliases / ...
+    const v = rec[key];
+    if (v === undefined || v === null) continue;
+    if (m.kind === 'bool') out.push(`${m.fm}: ${v ? 'true' : 'false'}`);
+    else if (m.kind === 'qstr') out.push(`${m.fm}: ${quote(v)}`);
+    else out.push(`${m.fm}: ${v}`);
+  }
+  if (Array.isArray(rec.extra_frontmatter)) out.push(...rec.extra_frontmatter);
+  return out.join('\n');
+}
+
+function readSkillsJson() {
+  return JSON.parse(fs.readFileSync(SKILLS_JSON, 'utf8'));
+}
+function recordMap(json) {
+  const map = new Map();
+  for (const r of json.skills || []) map.set(r.name, r);
+  return map;
+}
+
+/** Build the regenerated SKILL.md text for one skill from its record. */
+function renderSkill(id, rec) {
+  const abs = path.join(SRC, id, 'SKILL.md');
+  const { body } = splitFrontmatter(fs.readFileSync(abs, 'utf8'), id);
+  return `---\n${frontmatterFromRecord(rec)}\n---\n${body}`;
+}
+
+function modeForward(check) {
+  const json = readSkillsJson();
+  const map = recordMap(json);
+  const dirs = listSkillDirs();
+  const drift = [];
+  let written = 0;
+  for (const id of dirs) {
+    const rec = map.get(id);
+    if (!rec) {
+      if (check) { drift.push(`${id} (missing from skills.json)`); continue; }
+      fail(`${id}: present in scripts/skill-templates but missing from skills.json — add a record (run --extract)`);
+    }
+    const abs = path.join(SRC, id, 'SKILL.md');
+    const cur = fs.readFileSync(abs, 'utf8').replace(/\r\n/g, '\n');
+    const next = renderSkill(id, rec);
+    if (cur === next) continue;
+    if (check) drift.push(id);
+    else { fs.writeFileSync(abs, next); written += 1; }
+  }
+  // records in skills.json with no source dir (e.g. not yet authored) are tolerated
+  if (check) {
+    if (drift.length) {
+      process.stderr.write(
+        `generate-skill-frontmatter --check: ${drift.length} skill(s) drift from skills.json:\n  ${drift.slice(0, 20).join('\n  ')}\n` +
+          `Run \`npm run generate:skill-frontmatter\` then \`npm run build:skills\`.\n`,
+      );
+      process.exit(1);
+    }
+    process.stdout.write(`generate-skill-frontmatter --check: OK — ${dirs.length} skills match skills.json.\n`);
+    return;
+  }
+  process.stdout.write(`generate-skill-frontmatter: regenerated ${written}/${dirs.length} skill frontmatter block(s).\n`);
+}
+
+function modeExtract() {
+  const existing = fs.existsSync(SKILLS_JSON) ? readSkillsJson() : { schema_version: 1, skills: [] };
+  const prevMap = recordMap(existing);
+  const dirs = listSkillDirs();
+  const skills = [];
+  for (const id of dirs) {
+    const { fmLines } = splitFrontmatter(fs.readFileSync(path.join(SRC, id, 'SKILL.md'), 'utf8'), id);
+    const rec = recordFromFrontmatter(id, fmLines);
+    // preserve curated fields that live only in the manifest (not frontmatter)
+    const prev = prevMap.get(id);
+    if (prev && prev.registered_in_phase != null) rec.registered_in_phase = prev.registered_in_phase;
+    if (prev && prev.aliases != null) rec.aliases = prev.aliases;
+    skills.push(rec);
+  }
+  const out = { schema_version: existing.schema_version || 1 };
+  if (existing.note) out.note = existing.note;
+  out.skills = skills;
+  fs.writeFileSync(SKILLS_JSON, JSON.stringify(out, null, 2) + '\n');
+  process.stdout.write(`generate-skill-frontmatter --extract: wrote ${skills.length} enriched records to skills.json.\n`);
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes('--extract')) return modeExtract();
+  return modeForward(args.includes('--check'));
+}
+
+if (require.main === module) main(process.argv);
+
+module.exports = {
+  splitFrontmatter,
+  recordFromFrontmatter,
+  frontmatterFromRecord,
+  renderSkill,
+  unquote,
+  quote,
+  MANAGED,
+  MANAGED_FM,
+  main,
+};

package/scripts/lib/bandit-router/integration.cjs

@@ -35,6 +35,12 @@
 
 const banditRouter = require('../bandit-router.cjs');
 const adaptiveModeLib = require('../adaptive-mode.cjs');
+// Phase 56 (CAL-01) per-agent risk calibration. recordOutcome feeds the same
+// {agent, status} signal it gives the bandit into this table so calibration
+// learns from the post-spawn outcome too. Lazy-tolerant: the call is wrapped in
+// its own best-effort try/catch (D-04) so a calibration write can never break
+// the bandit path.
+const calibration = require('../risk/calibration.cjs');
 
 const DELEGATE_NONE = banditRouter.DELEGATE_NONE; // 'none'
 const VALID_DELEGATES = banditRouter.DEFAULT_DELEGATES; // ['none','gemini','codex','cursor','copilot','qwen']
@@ -299,6 +305,38 @@ function recordOutcome(input) {
     }
   }
 
+  // CAL-01: also fold the same outcome into the per-agent risk calibration
+  // table so the calibration layer (compute-risk feedback) learns from the
+  // identical post-spawn signal the bandit just saw. Independent best-effort
+  // try/catch (D-04): a calibration write failure must NEVER throw into or
+  // break the bandit path above. The bandit signal carries no emitted risk
+  // score, so `risk` degrades to 0 via normalizeRecord; status drives the
+  // correctness axis (completed → applied-correct, anything else → not-correct).
+  // Writes to calibration.DEFAULT_CALIBRATION_PATH ('.design/telemetry/
+  // calibration.json') under baseDir — the module's own canonical location.
+  try {
+    calibration.updateCalibration(
+      input.agent,
+      {
+        accepted: true,
+        post_apply_correct: input.status === 'completed',
+      },
+      { root: input.baseDir, baseDir: input.baseDir },
+    );
+  } catch (err) {
+    if (process.env.GDD_BANDIT_DEBUG === '1') {
+      try {
+        process.stderr.write(
+          '[bandit-integration] recordOutcome calibration swallowed: ' +
+            (err && err.message ? err.message : String(err)) +
+            '\n',
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+
   return undefined;
 }
 

package/scripts/lib/install/installer.cjs

@@ -334,6 +334,58 @@ function listSourceSkills(skillsRoot) {
     });
 }
 
+/**
+ * Enumerate co-located sibling `*.md` reference files for a skill.
+ *
+ * A skill source directory may ship reference files next to SKILL.md
+ * (e.g. `<name>-procedure.md`, `<name>-rules.md`, `cache-policy.md`).
+ * SKILL.md references these via relative links; if they are not installed
+ * the links resolve to nothing. This returns the top-level sibling `.md`
+ * files only (NOT SKILL.md itself, NOT files in nested subdirectories).
+ *
+ * Best-effort: any fs error yields an empty list (never throws). A single
+ * unreadable skill dir must not crash the whole install.
+ *
+ * @param {string} skillSrcDir  absolute path to `<skillsRoot>/<name>`
+ * @returns {string[]} basenames of sibling `.md` files (excluding SKILL.md)
+ */
+function listSiblingRefFiles(skillSrcDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(skillSrcDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((ent) => {
+      if (!ent.isFile()) return false;
+      if (ent.name === 'SKILL.md') return false;
+      return ent.name.toLowerCase().endsWith('.md');
+    })
+    .map((ent) => ent.name);
+}
+
+/**
+ * Wrap a passthrough sibling reference file's content with a plugin
+ * fingerprint header so foreign-file protection + uninstall can recognize
+ * it as plugin-owned. Idempotent: re-wrapping a file that already carries
+ * the fingerprint returns it unchanged.
+ *
+ * The fingerprint matches `merge.cjs#GDD_ADAPTER_FINGERPRINT`, the same
+ * marker every SKILL converter injects via `shared.ensureAdapterHeader`,
+ * so `isPluginOwned` treats the sibling as owned.
+ *
+ * @param {string} raw  source sibling file content
+ * @returns {string}
+ */
+function fingerprintSiblingRef(raw) {
+  const text = typeof raw === 'string' ? raw : '';
+  if (isPluginOwned(text)) return text;
+  const header =
+    '<!-- gdd: auto-generated from Claude SKILL.md. Reference adapter -->\n\n';
+  return header + text;
+}
+
 /**
  * Install all artifacts for a `multi-artifact` runtime.
  *
@@ -395,6 +447,48 @@ function installMultiArtifact(runtime, configDir, dryRun, opts) {
         action: writeResult.action,
         ...(writeResult.reason ? { reason: writeResult.reason } : {}),
       });
+
+      // Batch H6: carry co-located sibling `*.md` reference files alongside
+      // SKILL.md. The skills layout only stages SKILL.md per skill, so
+      // reference siblings (e.g. `<name>-procedure.md`) are otherwise lost.
+      // Scoped to cursor (the audited flat-layout runtime); other runtimes
+      // keep their prior single-SKILL.md behavior. Siblings are passthrough
+      // copies fingerprinted so foreign-file protection + uninstall treat
+      // them as plugin-owned. Broader skillsKind-runtime carry is deferred
+      // (see converters/cursor.cjs KNOWN LIMITATION).
+      if (kind.kind === 'skills' && runtime.id === 'cursor' && item.srcPath) {
+        const skillSrcDir = path.dirname(item.srcPath);
+        const skillDestDir = path.dirname(destPath);
+        for (const sibling of listSiblingRefFiles(skillSrcDir)) {
+          let rawSibling;
+          try {
+            rawSibling = fs.readFileSync(
+              path.join(skillSrcDir, sibling),
+              'utf8',
+            );
+          } catch (err) {
+            perFile.push({
+              kind: 'skill-ref',
+              path: path.join(skillDestDir, sibling),
+              action: 'skipped-foreign',
+              reason: `Could not read sibling ${sibling}: ${err.message}`,
+            });
+            continue;
+          }
+          const siblingDest = path.join(skillDestDir, sibling);
+          const siblingWrite = writeFingerprinted(
+            siblingDest,
+            fingerprintSiblingRef(rawSibling),
+            dryRun,
+          );
+          perFile.push({
+            kind: 'skill-ref',
+            path: siblingDest,
+            action: siblingWrite.action,
+            ...(siblingWrite.reason ? { reason: siblingWrite.reason } : {}),
+          });
+        }
+      }
     }
   }
 
@@ -489,7 +583,45 @@ function uninstallMultiArtifact(runtime, configDir, dryRun, opts) {
 
       // If we removed a SKILL.md, remember to trim its now-empty parent.
       if (kind.kind === 'skills') {
-        skillDirsToTrim.push(path.dirname(destPath));
+        const skillDestDir = path.dirname(destPath);
+        skillDirsToTrim.push(skillDestDir);
+
+        // Batch H6: symmetric cleanup for the sibling reference files the
+        // cursor install carries alongside SKILL.md. Remove only the
+        // plugin-owned siblings so a now-empty dir can be trimmed below;
+        // user-authored siblings are left in place (foreign-file discipline).
+        if (runtime.id === 'cursor') {
+          for (const sibling of listSiblingRefFiles(skillDestDir)) {
+            const siblingPath = path.join(skillDestDir, sibling);
+            let siblingContent;
+            try {
+              siblingContent = fs.readFileSync(siblingPath, 'utf8');
+            } catch (err) {
+              perFile.push({
+                kind: 'skill-ref',
+                path: siblingPath,
+                action: 'skipped-foreign',
+                reason: `Could not read sibling ${sibling}: ${err.message}`,
+              });
+              continue;
+            }
+            if (!isPluginOwned(siblingContent)) {
+              perFile.push({
+                kind: 'skill-ref',
+                path: siblingPath,
+                action: 'skipped-foreign',
+                reason: `Existing ${sibling} was not authored by this plugin; not removing.`,
+              });
+              continue;
+            }
+            if (!dryRun) fs.unlinkSync(siblingPath);
+            perFile.push({
+              kind: 'skill-ref',
+              path: siblingPath,
+              action: 'removed',
+            });
+          }
+        }
       }
     }
   }

package/scripts/lib/manifest/scaffolder.cjs

@@ -3,7 +3,7 @@
  * scripts/lib/manifest/scaffolder.cjs — Phase 50 (Authoring Contract v3).
  *
  * Pure, dependency-free generator behind the `/gdd:new-skill` scaffolder skill.
- * The SKILL.md (skill-templates/new-skill/SKILL.md) drives the interactive
+ * The SKILL.md (scripts/skill-templates/new-skill/SKILL.md) drives the interactive
  * prompts; this module is the deterministic core it (and the test suite) call.
  *
  * Exports:

package/scripts/lib/manifest/schemas/skills.schema.json

@@ -25,7 +25,7 @@
           "name": {
             "type": "string",
             "minLength": 1,
-            "description": "Skill id = skill-templates/<name>/ directory name."
+            "description": "Skill id = scripts/skill-templates/<name>/ directory name."
           },
           "frontmatter_name": {
             "type": "string",

package/scripts/lib/manifest/skills.json

@@ -319,7 +319,7 @@
     },
     {
       "name": "new-skill",
-      "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
+      "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes scripts/skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
       "argument_hint": "<skill-name>",
       "tools": "Read, Write, Bash, AskUserQuestion",
       "user_invocable": true,

package/scripts/lib/new-addendum.cjs

@@ -3,7 +3,7 @@
  * scripts/lib/new-addendum.cjs — Phase 54 (Composable Reference Addendums), REG-01.
  *
  * Pure, dependency-free generator behind the `/gdd:new-addendum <kind> <name>`
- * scaffolder skill (skill-templates/new-addendum/SKILL.md). The SKILL.md drives
+ * scaffolder skill (scripts/skill-templates/new-addendum/SKILL.md). The SKILL.md drives
  * the prompts; this module is the deterministic core it (and the test suite)
  * call. Mirrors scripts/lib/manifest/scaffolder.cjs (the Phase 50 skill
  * scaffolder): same ReDoS-safe NAME_RE, same throw-on-invalid contract, same