@hegemonart/get-design-done 1.59.7 → 1.59.8

package/hooks/gdd-sessionstart-recap.js

@@ -57,17 +57,21 @@ function detectHarness() {
 }
 
 // ---------------------------------------------------------------------------
-// Lazy event-stream emit (best-effort)
+// Event emit (best-effort) — delegate to the shared _hook-emit helper, which
+// uses the SDK writer when loadable (modern Node) and an inline JSONL appender
+// otherwise. The previous direct `require('../sdk/event-stream')` resolved to
+// the `.ts` ESM index and threw under plain `node` on Node 22.0–22.17, leaving
+// recap.emitted permanently no-op'd. emitEvent lands the line on every Node.
 // ---------------------------------------------------------------------------
 
-function getAppendEvent() {
+function getEmitEvent() {
   try {
-    const m = require('../sdk/event-stream');
-    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+    const m = require('./_hook-emit.js');
+    if (m && typeof m.emitEvent === 'function') return m.emitEvent;
   } catch {
-    /* swallow — event-stream is optional infrastructure */
+    /* swallow — telemetry is optional infrastructure */
   }
-  return function noopAppend(_ev) {
+  return function noopEmit(_ev) {
     /* no-op */
   };
 }
@@ -87,9 +91,12 @@ function readStateMd(paths) {
   }
 
   const frontmatter = {};
-  const fmMatch = body.match(/^---\n([\s\S]*?)\n---\n/);
+  // Tolerate CRLF line endings — the STATE.md mutator preserves CRLF, so a
+  // strict `\n`-only anchor fails to match the frontmatter block on Windows
+  // checkouts and the recap silently reports an empty cycle/decisions diff.
+  const fmMatch = body.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
   if (fmMatch) {
-    for (const line of fmMatch[1].split('\n')) {
+    for (const line of fmMatch[1].split(/\r?\n/)) {
       const m = line.match(/^(\w+):\s*(.+)$/);
       if (m) frontmatter[m[1]] = m[2].trim();
     }
@@ -273,9 +280,9 @@ async function main() {
   }
 
   // Best-effort event emit.
-  const appendEvent = getAppendEvent();
+  const emitEvent = getEmitEvent();
   try {
-    appendEvent({
+    emitEvent({
       type: 'recap.emitted',
       timestamp: new Date().toISOString(),
       sessionId: process.env.GDD_SESSION_ID || 'sessionstart-hook',
@@ -300,9 +307,11 @@ async function main() {
   process.exit(0);
 }
 
-try {
-  main();
-} catch (err) {
+// `main` is async: a sync try/catch cannot observe a rejected promise, so a
+// throw inside an `await` boundary would escape as an unhandled rejection and
+// exit non-zero — violating the silent-exit-0 contract for SessionStart hooks.
+// Attach `.catch` so every failure mode is swallowed and we exit 0.
+main().catch((err) => {
   try {
     process.stderr.write(
       '[gdd-sessionstart-recap] uncaught: ' +
@@ -313,4 +322,4 @@ try {
     /* swallow */
   }
   process.exit(0);
-}
+});

package/hooks/hooks.json

@@ -45,7 +45,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Agent",
+        "matcher": "Task|Agent",
         "hooks": [
           {
             "type": "command",
@@ -119,7 +119,7 @@
         ]
       },
       {
-        "matcher": "Agent",
+        "matcher": "Task|Agent",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.59.7",
+  "version": "1.59.8",
   "description": "A design-quality pipeline for AI coding agents: brief, explore, plan, design, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -10,7 +10,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.6.0"
   },
   "files": [
     ".claude-plugin/",

package/reference/bandit-integration.md

@@ -10,7 +10,7 @@ description: Bandit posterior + production-integration shim cheat sheet - signat
 
 **Phase 27.5 (v1.27.5).** Reference for the bandit production-integration surface. Authoring or modifying a caller of the bandit posterior? Debugging a routing decision at the code level? Start here.
 
-For ops-level guidance (when bandit fires, how to disable, posterior inspection), see `docs/BANDIT-INTEGRATION.md`.
+For ops-level guidance (when bandit fires, how to disable, posterior inspection), use the read-only diagnostic surfaces: `/gdd:bandit-status` (per-arm posterior snapshots) and `/gdd:bandit-reset` (confirm-then-reset). The `adaptive_mode` gate below covers enable/disable.
 
 In-scope modules:
 
@@ -104,6 +104,17 @@ Phase 27.5 passes `wallTimeMs: 0` always (D-08 unchanged from Phase 23.5).
 
 ---
 
+## Where adaptive routing actually learns
+
+This is a deliberate design boundary, not a bug - read it before assuming the bandit "learns" in every runtime.
+
+- **The posterior is updated only on the SDK / headless path.** `recordOutcome` (the learning update that moves `alpha`/`beta`) is called from `scripts/lib/session-runner/index.ts` after a session terminates. That path runs in the SDK / headless `session-runner` execution model. It is the only place a reward is folded back into the posterior.
+- **In interactive Claude Code with `adaptive_mode: full`, the bandit samples but does not currently learn from in-session outcomes.** When a plugin/interactive run consults the bandit, `consultBandit` performs a Thompson sample from the *configured priors* (and whatever the SDK path has already written), and `pull()` bumps `last_used` + `count` - but no `recordOutcome` fires from an interactive Claude Code hook, so the success/fail posterior does not move within the interactive session. With an un-seeded posterior, sampling therefore reflects the informed `TIER_PRIOR` (which leans toward the higher tiers, e.g. opus). Wiring `recordOutcome` into an interactive hook is intentionally out of scope for this phase.
+- **`adaptive_mode` defaults to `static` - the feature is opt-in.** Per `scripts/lib/adaptive-mode.cjs`, the default mode is `static`, in which the bandit is fully silent (no reads, no writes) and `default-tier:` is authoritative. Adaptive routing only engages when an operator explicitly sets `adaptive_mode: full` in `.design/budget.json`.
+- **Contextual dimensions are supplied by the caller, not inferred here.** The `bin` (glob-count bucket via `binForGlobCount`) and `delegate` dimensions are passed in at the call site; the router does not derive them from ambient session state.
+
+Net: enable `adaptive_mode: full` and run the SDK/headless `session-runner` path to accumulate a posterior that genuinely reflects observed outcomes. In interactive Claude Code, `full` mode gives you prior-driven Thompson sampling, not in-session reinforcement.
+
 ## `adaptive_mode` gate semantics
 
 Phase 23.5 ladder (D-07):
@@ -154,7 +165,7 @@ Phase 27.5 wires these consumers:
 
 ## Cross-references
 
-- `docs/BANDIT-INTEGRATION.md` - operator guide (when bandit fires, how to disable, troubleshooting).
+- `/gdd:bandit-status` + `/gdd:bandit-reset` - read-only operator surfaces (when bandit fires, posterior inspection, reset). Disable/enable is the `adaptive_mode` gate in `.design/budget.json` (see above).
 - `reference/peer-protocols.md` - Phase 27 ACP/ASP cheat sheet (peer-CLI delegation transport).
 - `scripts/lib/bandit-router.cjs` - Phase 23.5 primitives surface.
 - `scripts/lib/bandit-router/integration.cjs` - Phase 27.5 production shim.

package/scripts/bootstrap.cjs

@@ -148,6 +148,14 @@ function filesEqual(a, b) {
   }
 }
 
+/**
+ * Network timeout (ms) for the git clone/pull. SessionStart hooks must never
+ * block the harness: without a timeout, a hung network connection would stall
+ * the whole session-start sequence indefinitely. spawnSync kills the child
+ * with `killSignal` once this elapses and reports it as a failure.
+ */
+const GIT_TIMEOUT_MS = 15000;
+
 /**
  * Match the .sh `clone_or_update`:
  *   - target/.git exists  → `git -C target pull --quiet --ff-only`, log on fail
@@ -157,8 +165,14 @@ function filesEqual(a, b) {
  * We invoke the `git` CLI directly via spawnSync. spawnSync('git', …) is fine —
  * the prohibition is on spawnSync('bash', …).
  *
+ * Returns true ONLY when the repo is in a good post-condition (pull/clone
+ * succeeded, or a pre-existing non-git dir we intentionally skip). Returns
+ * false when a network op failed or timed out — so the caller can withhold the
+ * success marker and retry next session instead of recording failure as done.
+ *
  * @param {string} repoUrl
  * @param {string} target
+ * @returns {boolean} success
  */
 function cloneOrUpdate(repoUrl, target) {
   let isGitCheckout = false;
@@ -177,16 +191,22 @@ function cloneOrUpdate(repoUrl, target) {
     const r = spawnSync('git', ['-C', target, 'pull', '--quiet', '--ff-only'], {
       stdio: ['ignore', 'ignore', 'ignore'],
       windowsHide: true,
+      timeout: GIT_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
     });
     if (r.error || r.status !== 0) {
-      log(`pull failed for ${target} (continuing)`);
+      const why = r.error && r.error.code === 'ETIMEDOUT' ? 'timed out' : 'failed';
+      log(`pull ${why} for ${target} (continuing)`);
+      return false;
     }
-    return;
+    return true;
   }
 
   if (targetExists) {
     log(`${target} exists and is not a git checkout — skipping`);
-    return;
+    // A pre-existing non-git dir is a stable post-condition, not a failure:
+    // re-running won't change it, so don't force a retry every session.
+    return true;
   }
 
   // Defense in depth: refuse repoUrl / target arguments that look like git
@@ -196,7 +216,7 @@ function cloneOrUpdate(repoUrl, target) {
   if (typeof repoUrl !== 'string' || repoUrl.startsWith('-') ||
       typeof target !== 'string' || target.startsWith('-')) {
     log(`refusing suspicious clone args for ${repoUrl} -> ${target}`);
-    return;
+    return false;
   }
 
   log(`cloning ${repoUrl} -> ${target}`);
@@ -205,10 +225,15 @@ function cloneOrUpdate(repoUrl, target) {
   const r = spawnSync('git', ['clone', '--quiet', '--depth', '1', '--', repoUrl, target], {
     stdio: ['ignore', 'ignore', 'ignore'],
     windowsHide: true,
+    timeout: GIT_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
   });
   if (r.error || r.status !== 0) {
-    log(`clone failed for ${repoUrl}`);
+    const why = r.error && r.error.code === 'ETIMEDOUT' ? 'timed out' : 'failed';
+    log(`clone ${why} for ${repoUrl}`);
+    return false;
   }
+  return true;
 }
 
 /**
@@ -315,7 +340,7 @@ function run(opts = {}) {
   }
 
   // Required library: VoltAgent/awesome-design-md.
-  cloneOrUpdate(
+  const repoOk = cloneOrUpdate(
     'https://github.com/VoltAgent/awesome-design-md.git',
     ctx.awesomeRepoTarget
   );
@@ -332,8 +357,15 @@ function run(opts = {}) {
   // Phase 10.1: .design/budget.json + .design/telemetry/ (D-12).
   ensureDesignDir(cwd);
 
-  // Record success so we don't re-run until the bundled manifest changes.
-  copyManifestToMarker(ctx.manifest, ctx.marker);
+  // Record success ONLY when the network provisioning actually succeeded.
+  // Writing the marker unconditionally records a failed clone as "done" and
+  // never retries — leaving the required library permanently absent. Gating on
+  // repoOk means a transient network failure/timeout is retried next session.
+  if (repoOk) {
+    copyManifestToMarker(ctx.manifest, ctx.marker);
+  } else {
+    log('skipping success marker — provisioning incomplete, will retry next session');
+  }
 
   return 0;
 }

package/scripts/install.cjs

@@ -211,6 +211,28 @@ async function main() {
       }
       runtimes = picked.runtimes;
       if (picked.location) location = picked.location;
+    } else if (uninstall) {
+      // B4 fix (Phase 59.8): bare `--uninstall` in a non-TTY context must NOT
+      // silently default to removing claude. The interactive path is the only
+      // safe way to pick what to remove without an explicit flag; in non-TTY
+      // we refuse and require an explicit runtime flag so a scripted/CI
+      // invocation can never destroy an install the operator didn't name.
+      // (See the comment at shouldUseInteractive: bare --uninstall is meant to
+      // trigger the interactive select-which-to-remove flow.)
+      process.stderr.write(
+        [
+          'Refusing to uninstall: no runtime specified and not running in an',
+          'interactive terminal.',
+          '',
+          'Re-run with an explicit runtime flag, e.g.:',
+          '  npx @hegemonart/get-design-done --uninstall --claude',
+          '  npx @hegemonart/get-design-done --uninstall --all',
+          '',
+          'Run with --help to list available runtime flags.',
+          '',
+        ].join('\n'),
+      );
+      process.exit(2);
     } else {
       // Non-TTY zero-flag fallback: back-compat with v1.23.5 behaviour.
       runtimes = ['claude'];
@@ -359,7 +381,7 @@ async function maybeNudgePeerCli({ flags }) {
       '✓ Detected peer CLIs: ' + detectedDisplay,
       '',
       'gdd v1.27.0 introduced optional peer-CLI delegation. With your',
-      'agents\\u2019 frontmatter `delegate_to:` set, gdd can route specific',
+      "agents' frontmatter `delegate_to:` set, gdd can route specific",
       'roles through these peer CLIs (cost or quality wins per Phase 23.5',
       'bandit). You can change this anytime via .design/config.json.',
       '',

package/scripts/lib/bandit-router.cjs

@@ -38,7 +38,9 @@
  *   - The `prior_class` value is persisted on the arm so subsequent
  *     reads + decay calculations preserve it (forward-compat).
  *
- * Atomic .tmp + rename. Discounted Thompson via per-arm time-decay
+ * Atomic per-pid-unique .tmp + rename (Phase 59-8 C2: unique tmp name per
+ * process so parallel waves never interleave writes on one scratch file).
+ * Discounted Thompson via per-arm time-decay
  * factor `rho^days_since_last_use` applied at sample time, not stored.
  *
  * Reward computation (D-06): two-stage lexicographic — UNCHANGED.
@@ -57,6 +59,17 @@ const path = require('node:path');
 const DEFAULT_POSTERIOR_PATH = '.design/telemetry/posterior.json';
 const SCHEMA_VERSION = '1.0.0';
 
+// C2 fix (Phase 59-8): monotonic per-process counter for tmp-file naming.
+// Combined with process.pid it guarantees that two concurrent writers — even
+// within the same process, even firing in the same millisecond — never target
+// the same `.tmp` path. The old fixed `p + '.tmp'` name let parallel agent
+// waves interleave partial writes on one tmp file, producing truncated JSON
+// that loadPosterior() then silently reset to an empty posterior (losing all
+// learned arms). Unique tmp + atomic rename makes a half-written file
+// invisible to readers: rename is atomic on the same filesystem, so a reader
+// sees either the old complete file or the new complete file, never a partial.
+let _tmpCounter = 0;
+
 // Decay factor — 60-day half-life.
 const DEFAULT_DECAY = 0.988;
 
@@ -136,6 +149,12 @@ function loadPosterior(opts = {}) {
     }
     return data;
   } catch {
+    // Corrupt-JSON recovery (preserved, Phase 59-8 C2): fall back to an empty
+    // posterior. With the per-pid unique-tmp + atomic-rename write discipline
+    // (see savePosterior), a reader can no longer observe a half-written file
+    // — rename publishes the complete file in one step — so this branch should
+    // now only fire on genuine on-disk corruption (e.g. external truncation),
+    // not on a write/read race during a parallel agent wave.
     return { schema_version: SCHEMA_VERSION, generated_at: new Date().toISOString(), arms: [] };
   }
 }
@@ -159,9 +178,19 @@ function savePosterior(posterior, opts = {}) {
   const p = resolvePath(opts);
   fs.mkdirSync(path.dirname(p), { recursive: true });
   posterior.generated_at = new Date().toISOString();
-  const tmp = p + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(posterior, null, 2));
-  fs.renameSync(tmp, p);
+  // C2 fix (Phase 59-8): per-process-unique tmp name (pid + monotonic
+  // counter) so concurrent writers never collide on the same scratch file.
+  // The atomic rename then publishes the fully-written file in one step.
+  const tmp = `${p}.${process.pid}.${_tmpCounter++}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(posterior, null, 2));
+    fs.renameSync(tmp, p);
+  } catch (err) {
+    // Best-effort cleanup of the orphaned tmp on failure so a crashed
+    // write never leaves stale scratch files behind. ENOENT is fine.
+    try { fs.unlinkSync(tmp); } catch { /* already gone */ }
+    throw err;
+  }
   return p;
 }
 
@@ -347,7 +376,20 @@ function decayArm(arm, opts = {}) {
   const factor = Math.pow(decay, days);
   // Decay shrinks both α and β toward the prior. We never go below the
   // initial prior strength — caller can rebuild a fresh prior via reset().
-  const { alpha: pa, beta: pb } = priorFor(arm.tier, opts.strength ?? PRIOR_STRENGTH);
+  //
+  // C1 fix (Phase 59-8): decay MUST target the SAME prior the arm was
+  // bootstrapped with. The arm persists `prior_class` (Phase 29 Plan 06 /
+  // D-04), so pass it through to priorFor — otherwise a promoted-incubator
+  // arm (Beta(2,8)) would drift back toward the informed TIER_PRIOR while
+  // idle, undoing the D-04 preferential-selection suppression. Default-class
+  // arms have no `prior_class` field, so `arm.prior_class` is undefined and
+  // priorFor falls through to the Phase 23.5 informed prior (byte-for-byte
+  // unchanged).
+  const { alpha: pa, beta: pb } = priorFor(
+    arm.tier,
+    opts.strength ?? PRIOR_STRENGTH,
+    arm.prior_class,
+  );
   return {
     alpha: pa + factor * Math.max(0, arm.alpha - pa),
     beta: pb + factor * Math.max(0, arm.beta - pb),

package/scripts/lib/detect/cli.cjs

@@ -45,13 +45,23 @@ function isUrl(p) {
   return /^https?:\/\//i.test(String(p || ''));
 }
 
-/** Select the detection engine. Returns { mode, warning }. Regex-fast is the dep-free default. */
+/**
+ * Select the detection engine. Returns { mode, warning }.
+ *
+ * There is exactly one engine path: regex over file text (see engine.cjs#run, which takes no
+ * jsdom/DOM parameter and is byte-identical whether or not jsdom is installed). So the truthful
+ * mode is always 'regex-fast'. We still probe jsdom (unless --fast) to surface a one-line hint
+ * that a DOM-aware path is not wired in this build — but we no longer claim a 'dom-aware' mode the
+ * engine does not have.
+ */
 function selectEngine(opts, requireFn) {
   if (opts.fast) return { mode: 'regex-fast', warning: null };
   let hasJsdom = false;
   try { requireFn('jsdom'); hasJsdom = true; } catch { hasJsdom = false; }
-  if (hasJsdom) return { mode: 'dom-aware', warning: null };
-  return { mode: 'regex-fast', warning: 'jsdom not installed — using regex-fast (install jsdom for DOM-aware mode, or pass --fast to silence this).' };
+  // jsdom presence does not change the engine — only emit a hint when it's absent, and never
+  // promise a mode we can't deliver.
+  const warning = hasJsdom ? null : 'jsdom not installed — running regex-fast (the only wired mode; a DOM-aware path is not implemented). Pass --fast to silence this.';
+  return { mode: 'regex-fast', warning };
 }
 
 function renderHuman(result, mode) {

package/scripts/lib/install/converters/cursor.cjs

@@ -25,25 +25,17 @@
  * Pure / side-effect-free: no fs, no env, no path. `convert` is a
  * deterministic string → string transform.
  *
- * KNOWN LIMITATION — sibling .md files (audit batch H6, 2026-06-04):
- *   The Cursor install drops ONLY `skills/<name>/SKILL.md`. Sibling
- *   `.md` files living next to SKILL.md (e.g. `discover-procedure.md`,
- *   `explore-procedure.md`, `cache-policy.md`) are NOT enumerated by
- *   `runtime-artifact-layout.cjs#skillsKind` and therefore NOT installed.
- *   Source SKILL.md files reference siblings via relative paths
- *   (e.g. `./discover-procedure.md`); on Cursor those links resolve to
- *   nothing.
- *
- *   This is a systemic limitation of the current `multi-artifact`
- *   pipeline, not a Cursor-specific bug — it affects every runtime that
- *   uses `skillsKind` (claude global, cursor, codex, copilot, antigravity,
- *   windsurf, augment, trae, qwen, codebuddy). Fix requires extending the
- *   StagedArtifact contract to emit multiple files per skill (one
- *   SKILL.md + N siblings), updating `computeDestPath`, the foreign-file
- *   detection in `detectMultiArtifactInstalled`, and the uninstall
- *   enumeration in `uninstallMultiArtifact`. Tracked as a follow-up
- *   beyond batch H6 scope. See `connections/cursor.md` for user-facing
- *   guidance.
+ * SIBLING .md FILES — RESOLVED (audit AR6, Phase 59.8):
+ *   The install now carries co-located sibling `*.md` reference files
+ *   (e.g. `discover-procedure.md`, `cache-policy.md`) alongside SKILL.md
+ *   for EVERY skillsKind runtime, not just Cursor. The carry happens in
+ *   `installer.cjs#installMultiArtifact` (gated on `kind.kind === 'skills'`
+ *   plus `item.srcPath`), with symmetric removal in `uninstallMultiArtifact`.
+ *   Siblings are passthrough copies fingerprinted via `fingerprintSiblingRef`
+ *   so foreign-file protection + uninstall treat them as plugin-owned. Only
+ *   top-level `*.md` siblings are carried; nested subdirectories are out of
+ *   scope. Previously this was a Batch-H6 cursor-only patch (the audit AR6
+ *   finding); it is now generalized across all skillsKind runtimes.
  */
 
 const shared = require('./shared.cjs');

package/scripts/lib/install/installer.cjs

@@ -163,12 +163,17 @@ function installClaudeMarketplace(runtime, configDir, dryRun) {
       dryRun,
     };
   }
+  // B1 fix (Phase 59.8): decide created-vs-updated BEFORE the write. The
+  // settings.json file is written by atomicWrite below, so testing
+  // `existsSync(settingsPath)` afterwards always returned 'updated' (the file
+  // we just wrote exists). Capture the pre-write existence instead.
+  const existedBefore = fs.existsSync(settingsPath);
   const formatted = `${JSON.stringify(next, null, 2)}\n`;
   if (!dryRun) atomicWrite(settingsPath, formatted);
   return {
     runtime: runtime.id,
     path: settingsPath,
-    action: fs.existsSync(settingsPath) ? 'updated' : 'created',
+    action: existedBefore ? 'updated' : 'created',
     dryRun,
   };
 }
@@ -439,6 +444,20 @@ function installMultiArtifact(runtime, configDir, dryRun, opts) {
       continue;
     }
     for (const item of staged) {
+      // AR7 fix (Phase 59.8): never write a 0-byte / empty artifact. The old
+      // agents path staged `content: ''` for every skill name that had no
+      // matching agent file, producing empty `gdd-<name>.md` placeholders.
+      // Even with the layout-side enumeration fix, guard defensively here so
+      // no converter/kind can ever emit an empty file to disk.
+      if (!item.content || !String(item.content).trim()) {
+        perFile.push({
+          kind: kind.kind,
+          path: computeDestPath(configDir, kind, item.name),
+          action: 'skipped-empty',
+          reason: `Refusing to write empty artifact ${item.name}`,
+        });
+        continue;
+      }
       const destPath = computeDestPath(configDir, kind, item.name);
       const writeResult = writeFingerprinted(destPath, item.content, dryRun);
       perFile.push({
@@ -448,15 +467,16 @@ function installMultiArtifact(runtime, configDir, dryRun, opts) {
         ...(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) {
+      // AR6 fix (Phase 59.8): carry co-located sibling `*.md` reference files
+      // alongside SKILL.md for EVERY skillsKind runtime (cursor, codex,
+      // copilot, antigravity, windsurf, augment, trae, qwen, codebuddy, and
+      // claude global). The skills layout only stages SKILL.md per skill, so
+      // reference siblings (e.g. `<name>-procedure.md`) were otherwise lost on
+      // every runtime except cursor — shipping dead relative links. Siblings
+      // are passthrough copies fingerprinted so foreign-file protection +
+      // uninstall treat them as plugin-owned. Was previously scoped to cursor
+      // only (Batch H6); see converters/cursor.cjs former KNOWN LIMITATION.
+      if (kind.kind === 'skills' && item.srcPath) {
         const skillSrcDir = path.dirname(item.srcPath);
         const skillDestDir = path.dirname(destPath);
         for (const sibling of listSiblingRefFiles(skillSrcDir)) {
@@ -550,8 +570,27 @@ function uninstallMultiArtifact(runtime, configDir, dryRun, opts) {
   const skillDirsToTrim = [];
 
   for (const kind of layout.kinds) {
-    for (const bareName of skillNames) {
-      const itemName = (kind.prefix || '') + bareName;
+    // AR7 fix (Phase 59.8): derive the artifact names from the SAME staging
+    // pass install uses, so uninstall stays symmetric. The `agents` kind
+    // enumerates `agents/*.md` (real agent role names), NOT skill names — the
+    // old `gdd-<skillName>.md` derivation never matched any installed agent
+    // file and left every real agent on disk after `--uninstall`.
+    let stagedNames;
+    try {
+      const staged = kind.stage({
+        skillsRoot,
+        skillNames,
+        scope,
+        runtime: runtime.id,
+        configDir,
+      });
+      stagedNames = staged.map((item) => item.name);
+    } catch {
+      // Fall back to the prior skill-name derivation if staging fails (e.g.
+      // a converter throws); skills/commands kinds match this shape exactly.
+      stagedNames = skillNames.map((n) => (kind.prefix || '') + n);
+    }
+    for (const itemName of stagedNames) {
       const destPath = computeDestPath(configDir, kind, itemName);
       if (!fs.existsSync(destPath)) {
         perFile.push({ kind: kind.kind, path: destPath, action: 'unchanged' });
@@ -586,11 +625,12 @@ function uninstallMultiArtifact(runtime, configDir, dryRun, opts) {
         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') {
+        // AR6 fix (Phase 59.8): symmetric cleanup for the sibling reference
+        // files every skillsKind 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). Was previously scoped to cursor only (Batch H6).
+        if (kind.kind === 'skills') {
           for (const sibling of listSiblingRefFiles(skillDestDir)) {
             const siblingPath = path.join(skillDestDir, sibling);
             let siblingContent;
@@ -682,11 +722,22 @@ function installCline(runtime, configDir, skillsRoot, skillNames, dryRun) {
   const cline = require('./converters/cline.cjs');
   ensureDir(configDir, dryRun);
 
-  const blocks = skillNames.map((name) => {
+  // B2 fix (Phase 59.8): wrap the per-skill read in try/catch. Previously a
+  // single unreadable SKILL.md threw out of `installCline`, aborting the
+  // entire cline install (and, when cline is one runtime in a multi-runtime
+  // batch, every runtime queued after it). Skip the unreadable skill and keep
+  // going, mirroring the best-effort sibling reads elsewhere in this file.
+  const blocks = [];
+  for (const name of skillNames) {
     const srcPath = path.join(skillsRoot, name, 'SKILL.md');
-    const raw = fs.readFileSync(srcPath, 'utf8');
-    return { name, block: cline.convert(raw, name, { runtime: 'cline' }) };
-  });
+    let raw;
+    try {
+      raw = fs.readFileSync(srcPath, 'utf8');
+    } catch {
+      continue; // unreadable skill — skip, don't abort the whole install
+    }
+    blocks.push({ name, block: cline.convert(raw, name, { runtime: 'cline' }) });
+  }
 
   const desired = cline.buildClinerulesFile(blocks);
   const target = path.join(configDir, '.clinerules');

package/scripts/lib/install/merge.cjs

@@ -111,11 +111,39 @@ function buildAgentsFileContent(runtime, payloadHeader) {
 const GDD_ADAPTER_FINGERPRINT = 'gdd: auto-generated from Claude SKILL.md';
 const CLINERULES_HEADER_FINGERPRINT = '# get-design-done rules';
 
+// B5/S4 fix (Phase 59.8): ownership detection is WHOLE-LINE anchored, not a
+// loose `String.includes` substring scan. The old substring match treated any
+// user-authored file that merely *mentioned* a marker string (e.g. a doc that
+// quotes "get-design-done plugin instructions", or a code fence containing
+// "gdd: auto-generated from Claude SKILL.md") as plugin-owned — so install
+// would overwrite it and uninstall would delete it. We now require the marker
+// to appear on a recognized GENERATED line:
+//
+//   - `<!-- ... <fingerprint> ... -->`  HTML-comment marker line. Both the
+//     Phase-24 plugin fingerprint and the per-runtime/sibling adapter header
+//     are emitted as a standalone HTML comment line; we accept the marker only
+//     when it sits inside an HTML comment that occupies the whole (trimmed)
+//     line. A bare prose mention of the same words no longer qualifies.
+//   - `# get-design-done rules`  cline rules header — must be the exact, whole
+//     trimmed line (a Markdown H1), matching converters/cline.cjs.
+//
+// Scanning line-by-line keeps detection of genuinely plugin-owned files intact
+// (the generated marker line is always present near the top) while refusing to
+// claim ownership of user files that merely contain the words somewhere.
+function isHtmlCommentMarkerLine(line, fingerprint) {
+  const t = line.trim();
+  if (!t.startsWith('<!--') || !t.endsWith('-->')) return false;
+  return t.includes(fingerprint);
+}
+
 function isPluginOwned(content) {
   if (!content || typeof content !== 'string') return false;
-  if (content.includes(PLUGIN_FINGERPRINT)) return true;
-  if (content.includes(GDD_ADAPTER_FINGERPRINT)) return true;
-  if (content.includes(CLINERULES_HEADER_FINGERPRINT)) return true;
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    if (isHtmlCommentMarkerLine(line, PLUGIN_FINGERPRINT)) return true;
+    if (isHtmlCommentMarkerLine(line, GDD_ADAPTER_FINGERPRINT)) return true;
+    if (line.trim() === CLINERULES_HEADER_FINGERPRINT) return true;
+  }
   return false;
 }