@hegemonart/get-design-done 1.28.5 → 1.28.7

package/scripts/lib/install/runtime-homes.cjs

@@ -0,0 +1,225 @@
+'use strict';
+
+/**
+ * scripts/lib/install/runtime-homes.cjs — Phase 28.7 (Plan 28.7-01).
+ *
+ * Pure config-dir + skills-base resolver per runtime. Returns absolute paths
+ * to each runtime's global config directory and global skills directory,
+ * respecting env-var overrides + XDG conventions.
+ *
+ * Architecture ported from gsd-build/get-shit-done (MIT) — per Phase 28.7 D-02
+ * (port architecture, not source). See NOTICE for upstream attribution.
+ *
+ * Scope: the 14 GDD runtimes locked by Phase 24 D-02. Phase 28.7 D-03 + D-10
+ * keep `hermes` OUT of scope; the upstream `hermes` and `grok` branches are
+ * deliberately NOT ported.
+ *
+ * Pure / side-effect-free: no `fs.*` calls at any time, no `process.env`
+ * writes, no top-level work beyond `require('os')` + `require('path')`.
+ * Safe to require() at module-load time.
+ *
+ * Runtime-specific notes:
+ *   opencode + kilo — XDG: honor `XDG_CONFIG_HOME` when the runtime's own
+ *                     env var is unset. Default: `~/.config/<runtime>`.
+ *   antigravity   — Nested under Gemini's home (`~/.gemini/antigravity`).
+ *   windsurf      — Nested under Codeium's home (`~/.codeium/windsurf`).
+ *   cline         — Rules-based runtime (D-09). `getGlobalSkillsBase('cline')`
+ *                   returns `null` so callers can route to the `.clinerules`
+ *                   embedding path instead of a skills/ tree.
+ */
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * Expand a leading `~` to `os.homedir()`. Returns the input unchanged if no
+ * leading tilde is present (including `null`/`undefined`/empty).
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function expandTilde(p) {
+  if (!p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * Return the global config base directory for the given runtime.
+ *
+ * Precedence per branch:
+ *   1. Runtime's dedicated env var (e.g. `CLAUDE_CONFIG_DIR`, `CODEX_HOME`),
+ *      tilde-expanded if present.
+ *   2. XDG path for opencode + kilo (when `XDG_CONFIG_HOME` is set).
+ *   3. Home-relative default (`~/.claude`, `~/.codex`, etc.).
+ *
+ * Throws `RangeError` on unknown runtime IDs (loud-fail — typos in caller
+ * code should fail at the resolver, not silently fall back to Claude paths).
+ *
+ * @param {string} runtime
+ * @returns {string} Absolute path to the runtime's global config directory.
+ */
+function getGlobalConfigDir(runtime) {
+  const home = os.homedir();
+  const env = process.env;
+
+  switch (runtime) {
+    // ── Claude Code ──────────────────────────────────────────────────────────
+    case 'claude':
+      return env.CLAUDE_CONFIG_DIR
+        ? expandTilde(env.CLAUDE_CONFIG_DIR)
+        : path.join(home, '.claude');
+
+    // ── OpenCode (XDG) ───────────────────────────────────────────────────────
+    case 'opencode': {
+      if (env.OPENCODE_CONFIG_DIR) return expandTilde(env.OPENCODE_CONFIG_DIR);
+      if (env.XDG_CONFIG_HOME) return path.join(expandTilde(env.XDG_CONFIG_HOME), 'opencode');
+      return path.join(home, '.config', 'opencode');
+    }
+
+    // ── Gemini CLI ───────────────────────────────────────────────────────────
+    case 'gemini':
+      return env.GEMINI_CONFIG_DIR
+        ? expandTilde(env.GEMINI_CONFIG_DIR)
+        : path.join(home, '.gemini');
+
+    // ── Kilo Code (XDG) ──────────────────────────────────────────────────────
+    case 'kilo': {
+      if (env.KILO_CONFIG_DIR) return expandTilde(env.KILO_CONFIG_DIR);
+      if (env.XDG_CONFIG_HOME) return path.join(expandTilde(env.XDG_CONFIG_HOME), 'kilo');
+      return path.join(home, '.config', 'kilo');
+    }
+
+    // ── Codex ────────────────────────────────────────────────────────────────
+    case 'codex':
+      return env.CODEX_HOME
+        ? expandTilde(env.CODEX_HOME)
+        : path.join(home, '.codex');
+
+    // ── Copilot (VS Code / CLI) ──────────────────────────────────────────────
+    case 'copilot':
+      return env.COPILOT_CONFIG_DIR
+        ? expandTilde(env.COPILOT_CONFIG_DIR)
+        : path.join(home, '.copilot');
+
+    // ── Cursor ───────────────────────────────────────────────────────────────
+    case 'cursor':
+      return env.CURSOR_CONFIG_DIR
+        ? expandTilde(env.CURSOR_CONFIG_DIR)
+        : path.join(home, '.cursor');
+
+    // ── Windsurf (nested under Codeium home) ─────────────────────────────────
+    case 'windsurf':
+      return env.WINDSURF_CONFIG_DIR
+        ? expandTilde(env.WINDSURF_CONFIG_DIR)
+        : path.join(home, '.codeium', 'windsurf');
+
+    // ── Antigravity (nested under Gemini home) ───────────────────────────────
+    case 'antigravity':
+      return env.ANTIGRAVITY_CONFIG_DIR
+        ? expandTilde(env.ANTIGRAVITY_CONFIG_DIR)
+        : path.join(home, '.gemini', 'antigravity');
+
+    // ── Augment ──────────────────────────────────────────────────────────────
+    case 'augment':
+      return env.AUGMENT_CONFIG_DIR
+        ? expandTilde(env.AUGMENT_CONFIG_DIR)
+        : path.join(home, '.augment');
+
+    // ── Trae ─────────────────────────────────────────────────────────────────
+    case 'trae':
+      return env.TRAE_CONFIG_DIR
+        ? expandTilde(env.TRAE_CONFIG_DIR)
+        : path.join(home, '.trae');
+
+    // ── Qwen Code ────────────────────────────────────────────────────────────
+    case 'qwen':
+      return env.QWEN_CONFIG_DIR
+        ? expandTilde(env.QWEN_CONFIG_DIR)
+        : path.join(home, '.qwen');
+
+    // ── CodeBuddy ────────────────────────────────────────────────────────────
+    case 'codebuddy':
+      return env.CODEBUDDY_CONFIG_DIR
+        ? expandTilde(env.CODEBUDDY_CONFIG_DIR)
+        : path.join(home, '.codebuddy');
+
+    // ── Cline (rules-based — see getGlobalSkillsBase) ────────────────────────
+    case 'cline':
+      return env.CLINE_CONFIG_DIR
+        ? expandTilde(env.CLINE_CONFIG_DIR)
+        : path.join(home, '.cline');
+
+    // ── Unknown ──────────────────────────────────────────────────────────────
+    default:
+      throw new RangeError(
+        `Unknown runtime "${runtime}". Known: claude, opencode, gemini, kilo, ` +
+          'codex, copilot, cursor, windsurf, antigravity, augment, trae, qwen, ' +
+          'codebuddy, cline.'
+      );
+  }
+}
+
+/**
+ * Return the global skills base directory for the given runtime.
+ *
+ * - `cline` → `null` (Phase 28.7 D-09: rules-based, no skills dir; caller
+ *             routes to the `.clinerules` embedding path).
+ * - All other 13 runtimes → `<configDir>/skills`.
+ *
+ * Note: gsd-build's upstream nests Hermes skills under `skills/gsd/<name>/`
+ * (their #2841). Hermes is NOT in our 14-runtime set (D-03 + D-10), so the
+ * nested layout is NOT ported.
+ *
+ * @param {string} runtime
+ * @returns {string|null} Absolute path to skills base, or `null` for cline.
+ */
+function getGlobalSkillsBase(runtime) {
+  if (runtime === 'cline') return null;
+  const configDir = getGlobalConfigDir(runtime);
+  return path.join(configDir, 'skills');
+}
+
+/**
+ * Return the full path to a specific skill's directory for the given runtime.
+ * Returns `null` for runtimes that don't use a skills directory (cline).
+ *
+ * @param {string} runtime
+ * @param {string} skillName e.g. `'gdd-executor'`.
+ * @returns {string|null}
+ */
+function getGlobalSkillDir(runtime, skillName) {
+  const base = getGlobalSkillsBase(runtime);
+  if (base === null) return null;
+  return path.join(base, skillName);
+}
+
+/**
+ * Return a human-readable display path for a global skill (for log messages).
+ * Replaces the home-directory prefix with `~` for readability.
+ *
+ * @param {string} runtime
+ * @param {string} skillName
+ * @returns {string}
+ */
+function getGlobalSkillDisplayPath(runtime, skillName) {
+  const dir = getGlobalSkillDir(runtime, skillName);
+  if (!dir) return `(${runtime} does not use a skills directory)`;
+  const home = os.homedir();
+  if (dir === home) return '~';
+  if (dir.startsWith(home + path.sep)) {
+    return '~' + dir.slice(home.length);
+  }
+  return dir;
+}
+
+module.exports = {
+  expandTilde,
+  getGlobalConfigDir,
+  getGlobalSkillsBase,
+  getGlobalSkillDir,
+  getGlobalSkillDisplayPath,
+};

package/scripts/lib/install/runtime-slash.cjs

@@ -0,0 +1,172 @@
+'use strict';
+
+/**
+ * scripts/lib/install/runtime-slash.cjs — Phase 28.7 (Plan 28.7-03).
+ *
+ * Per-runtime slash-command surface emitter. Maps a bare command name
+ * (e.g. `'explore'`) to the runtime's expected slash-command shape:
+ *   codex → `$gdd-explore`     (shell-variable form)
+ *   all other 13 runtimes → `/gdd-explore`
+ *
+ * The legacy colon form `/gdd:explore` is NEVER emitted — Phase 28.7
+ * standardizes on the dash form across the GDD brand. Inputs in legacy
+ * colon shape are accepted (and normalized) for backward compatibility.
+ *
+ * Architecture ported from gsd-build/get-shit-done (MIT) — per Phase
+ * 28.7 D-02 (port architecture, not source). See NOTICE for upstream
+ * attribution. Per Phase 28.7 D-11 this is the v1 surface; future
+ * per-runtime variations beyond codex shell-var may extend the switch.
+ *
+ * Idempotency: any prior shape (`/gdd-x`, `gdd-x`, `/gdd:x`, `gdd:x`,
+ * `$gdd-x`, `$gdd:x`) is stripped and re-emitted in canonical form for
+ * the target runtime. Argument tails (whitespace + remainder) round-trip
+ * untouched — this preserves Windows paths verbatim (Phase 28.6 lesson).
+ *
+ * Pure / side-effect-free at module load: only `require('fs')` and
+ * `require('path')` are taken at top level. `fs.readFileSync` is the
+ * sole `fs.*` caller, invoked exclusively from `resolveRuntime` when a
+ * project directory is provided — and wrapped in try/catch so malformed
+ * `.planning/config.json` cannot throw.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// formatGddSlash — pure rewrite of a single command token
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip any known GDD prefix from the head of `s`.
+ *
+ * Matches (case-insensitive):
+ *   `/gdd-`, `/gdd:`, `gdd-`, `gdd:`, `$gdd-`, `$gdd:`
+ *
+ * Returns the substring after the matched prefix, or the original string
+ * unchanged if no prefix matches.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function stripGddPrefix(s) {
+  const m = s.match(/^[/$]?gdd[-:]/i);
+  if (m) return s.slice(m[0].length);
+  return s;
+}
+
+/**
+ * Rewrite a command name to the slash-command shape for `runtime`.
+ *
+ * Behavior:
+ *   - Non-string `commandName` returned unchanged (type-guard).
+ *   - Empty string returned as `''`.
+ *   - Any of `/gdd-`, `/gdd:`, `gdd-`, `gdd:`, `$gdd-`, `$gdd:` is
+ *     stripped first (case-insensitive). Bare names pass through.
+ *   - If the stripped result is empty / whitespace-only, return `''`
+ *     (never re-emit `/gdd-` or `$gdd-` with no token — degenerate input).
+ *   - Split on the first whitespace: the leading token is rewritten,
+ *     everything after the first space (the argument tail) round-trips
+ *     untouched. This preserves Windows paths in argument position.
+ *   - codex → `$gdd-<token-lowercased><tail>`
+ *   - all other runtimes → `/gdd-<token><tail>`
+ *   - Unknown / falsy runtime → defaults to `'claude'` shape (`/gdd-`).
+ *
+ * @param {string} commandName  e.g. `'explore'`, `'/gdd-debug'`, `'do x y'`.
+ * @param {string} [runtime]    runtime ID; defaults to `'claude'`.
+ * @returns {string}
+ */
+function formatGddSlash(commandName, runtime) {
+  // Type-guard: only operate on strings; pass everything else through.
+  if (typeof commandName !== 'string') return commandName;
+  if (commandName === '') return '';
+
+  // 1. Strip any prior GDD prefix (idempotent normalization).
+  const bare = stripGddPrefix(commandName);
+
+  // 2. Defensive: empty / whitespace-only token → empty (never `/gdd-`).
+  if (bare === '' || /^\s+$/.test(bare)) return '';
+
+  // 3. Split into leading token + argument tail. The tail (including its
+  //    leading whitespace) round-trips untouched for Windows-path safety.
+  const m = bare.match(/^(\S+)(\s[\s\S]*)?$/);
+  /* istanbul ignore next — `bare` is non-empty + non-whitespace-only, so
+     this regex always matches; defensive fallback only. */
+  if (!m) return '';
+  const token = m[1];
+  const tail = m[2] || '';
+
+  // 4. Runtime-specific emission.
+  const rt = String(runtime || 'claude').toLowerCase();
+  if (rt === 'codex') {
+    return '$gdd-' + token.toLowerCase() + tail;
+  }
+  return '/gdd-' + token + tail;
+}
+
+// ---------------------------------------------------------------------------
+// resolveRuntime — read-only runtime ID resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active runtime ID for the given project directory.
+ *
+ * Precedence:
+ *   1. `process.env.GDD_RUNTIME` (lowercased) if truthy.
+ *   2. `<projectDir>/.planning/config.json#runtime` (lowercased) if the
+ *      file exists, parses as JSON, and contains a non-empty `runtime`
+ *      string. Malformed JSON, missing file, or missing key all fall
+ *      through silently — this function MUST NOT throw on bad config.
+ *   3. Default `'claude'`.
+ *
+ * Side-effect-free: only `fs.readFileSync` (wrapped in try/catch), no
+ * env mutation, no writes.
+ *
+ * @param {string} [projectDir]  absolute path to project root.
+ * @returns {string}  runtime ID, always lowercase.
+ */
+function resolveRuntime(projectDir) {
+  // 1. Env-var override
+  if (process.env.GDD_RUNTIME) {
+    return String(process.env.GDD_RUNTIME).toLowerCase();
+  }
+
+  // 2. .planning/config.json#runtime
+  if (projectDir) {
+    try {
+      const cfgPath = path.join(projectDir, '.planning', 'config.json');
+      const raw = fs.readFileSync(cfgPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed.runtime === 'string' && parsed.runtime) {
+        return String(parsed.runtime).toLowerCase();
+      }
+    } catch {
+      /* fall through — malformed JSON / missing file / missing key */
+    }
+  }
+
+  // 3. Default
+  return 'claude';
+}
+
+// ---------------------------------------------------------------------------
+// formatGddSlashFor — convenience that combines the two
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the runtime for `projectDir` and rewrite `commandName` accordingly.
+ * Convenience wrapper for callers that already have a project directory in
+ * hand and don't want to wire `resolveRuntime` themselves.
+ *
+ * @param {string} projectDir
+ * @param {string} commandName
+ * @returns {string}
+ */
+function formatGddSlashFor(projectDir, commandName) {
+  return formatGddSlash(commandName, resolveRuntime(projectDir));
+}
+
+module.exports = {
+  formatGddSlash,
+  resolveRuntime,
+  formatGddSlashFor,
+};

package/scripts/lib/install/runtimes.cjs

@@ -7,15 +7,21 @@
 // (Phase 24 D-02). Two `kind`s exist:
 //
 //   - `claude-marketplace` — register a marketplace entry + flip
-//     `enabledPlugins[<name>@<marketplace>]` in settings.json. Today only
-//     Claude Code uses this.
+//     `enabledPlugins[<plugin>@<marketplace>]` in settings.json. Claude
+//     Code only.
 //
-//   - `agents-md` — drop a runtime-specific instructions file (AGENTS.md /
-//     GEMINI.md) into the runtime's config directory. Most modern AI coding
-//     CLIs follow this convention.
+//   - `multi-artifact` — per Phase 28.7: install one or more artifact kinds
+//     (skills, commands, agents) using runtime-artifact-layout.cjs +
+//     per-runtime converters at scripts/lib/install/converters/<runtime>.cjs.
+//     Replaces the broken Phase 24 `agents-md` placeholder which dropped a
+//     single AGENTS.md file per runtime (Phase 28.7 D-02 + D-08). The actual
+//     install logic now lives in installer.cjs → runtime-artifact-layout.cjs;
+//     `files:` is intentionally absent on these entries because destination
+//     paths are computed by the artifact-layout resolver.
 //
 // Adding a new runtime: append to RUNTIMES below, append the same id to the
-// alphabetised baseline at test-fixture/baselines/phase-24/runtimes.txt.
+// alphabetised baseline at test-fixture/baselines/phase-24/runtimes.txt,
+// and add a matching branch in runtime-artifact-layout.cjs (Phase 28.7).
 
 const REPO = 'hegemonart/get-design-done';
 const MARKETPLACE_NAME = 'get-design-done';
@@ -40,16 +46,14 @@ const RUNTIMES = Object.freeze([
     displayName: 'OpenCode',
     configDirEnv: 'OPENCODE_CONFIG_DIR',
     configDirFallback: '.config/opencode',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'gemini',
     displayName: 'Gemini CLI',
     configDirEnv: 'GEMINI_CONFIG_DIR',
     configDirFallback: '.gemini',
-    kind: 'agents-md',
-    files: ['GEMINI.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'gemini.cmd' : 'gemini',
   },
@@ -58,16 +62,14 @@ const RUNTIMES = Object.freeze([
     displayName: 'Kilo Code',
     configDirEnv: 'KILO_CONFIG_DIR',
     configDirFallback: '.kilo',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'codex',
     displayName: 'OpenAI Codex CLI',
     configDirEnv: 'CODEX_HOME',
     configDirFallback: '.codex',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ASP protocol.
     peerBinary: process.platform === 'win32' ? 'codex.cmd' : 'codex',
   },
@@ -76,8 +78,7 @@ const RUNTIMES = Object.freeze([
     displayName: 'GitHub Copilot CLI',
     configDirEnv: 'COPILOT_CONFIG_DIR',
     configDirFallback: '.copilot',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'copilot.cmd' : 'copilot',
   },
@@ -86,8 +87,7 @@ const RUNTIMES = Object.freeze([
     displayName: 'Cursor',
     configDirEnv: 'CURSOR_CONFIG_DIR',
     configDirFallback: '.cursor',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'cursor-agent.cmd' : 'cursor-agent',
   },
@@ -96,40 +96,35 @@ const RUNTIMES = Object.freeze([
     displayName: 'Windsurf',
     configDirEnv: 'WINDSURF_CONFIG_DIR',
     configDirFallback: '.windsurf',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'antigravity',
     displayName: 'Antigravity',
     configDirEnv: 'ANTIGRAVITY_CONFIG_DIR',
     configDirFallback: '.antigravity',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'augment',
     displayName: 'Augment',
     configDirEnv: 'AUGMENT_CONFIG_DIR',
     configDirFallback: '.augment',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'trae',
     displayName: 'Trae',
     configDirEnv: 'TRAE_CONFIG_DIR',
     configDirFallback: '.trae',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'qwen',
     displayName: 'Qwen Code',
     configDirEnv: 'QWEN_CONFIG_DIR',
     configDirFallback: '.qwen',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'qwen.cmd' : 'qwen',
   },
@@ -138,16 +133,14 @@ const RUNTIMES = Object.freeze([
     displayName: 'CodeBuddy',
     configDirEnv: 'CODEBUDDY_CONFIG_DIR',
     configDirFallback: '.codebuddy',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'cline',
     displayName: 'Cline',
     configDirEnv: 'CLINE_CONFIG_DIR',
     configDirFallback: '.cline',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
 ]);
 

package/skills/apply-reflections/SKILL.md

@@ -52,7 +52,7 @@ Based on user choice:
 
 ### 4. Apply Logic by Proposal Type
 
-After the user chooses `a` (apply) or `e` (edit-then-apply), branch on the proposal's bracketed type tag and follow the per-type apply procedure in `./reference/apply-reflections-procedure.md` — one numbered procedure each for `[FRONTMATTER]`, `[REFERENCE]`, `[BUDGET]`, `[QUESTION]`, `[GLOBAL-SKILL]`. All branches end with `**Applied**: <date>` appended to the proposal block in the reflections file.
+After the user chooses `a` (apply) or `e` (edit-then-apply), branch on the proposal's bracketed type tag and follow the per-type apply procedure in `./apply-reflections-procedure.md` — one numbered procedure each for `[FRONTMATTER]`, `[REFERENCE]`, `[BUDGET]`, `[QUESTION]`, `[GLOBAL-SKILL]`. All branches end with `**Applied**: <date>` appended to the proposal block in the reflections file.
 
 ### 5. Summary
 

package/skills/cache-manager/SKILL.md

@@ -38,7 +38,7 @@ You are the deterministic cache-key computer and cache-manifest writer for the o
 
 ## Deterministic Input-Hash Algorithm
 
-The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./reference/cache-policy.md#deterministic-input-hash-algorithm-layer-b` — it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
+The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` — it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
 
 ## Integration Points
 
@@ -63,4 +63,4 @@ Per D-09:
 
 ## TTL Semantics
 
-Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10. `expires_at` is computed at write time and stored; readers do not recompute. Stale entries are lazily cleaned on read (no eager reaper in v1). Full TTL discussion: `./reference/cache-policy.md#ttl-semantics-layer-b`.
+Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10. `expires_at` is computed at write time and stored; readers do not recompute. Stale entries are lazily cleaned on read (no eager reaper in v1). Full TTL discussion: `./cache-policy.md#ttl-semantics-layer-b`.

package/skills/compare/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 Standalone delta command. Computes the difference between the scan baseline (`DESIGN.md`) and the verification result (`DESIGN-VERIFICATION.md`), and flags design drift for any regression not covered by an explicit task in `DESIGN-PLAN.md`. Writes one artifact: `.design/COMPARE-REPORT.md`.
 
-For the full step-by-step methodology (score parsing, set arithmetic for anti-patterns, drift-coverage map, screenshot-delta probe, and `COMPARE-REPORT.md` template), see `../../reference/compare-rubric.md`. For the cross-skill output discipline (artifact prefix, completion marker, MUST-NOT-write list, connection-probe pattern), see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`. For the underlying 0–10 category-scoring rubric the delta is computed against, see `../../reference/audit-scoring.md`.
+For the full step-by-step methodology (score parsing, set arithmetic for anti-patterns, drift-coverage map, screenshot-delta probe, and `COMPARE-REPORT.md` template), see `./compare-rubric.md`. For the cross-skill output discipline (artifact prefix, completion marker, MUST-NOT-write list, connection-probe pattern), see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`. For the underlying 0–10 category-scoring rubric the delta is computed against, see `../../reference/audit-scoring.md`.
 
 ---
 
@@ -45,13 +45,13 @@ Probe `preview` connection per `../../reference/shared-preamble.md#connection-ha
 
 ## Workflow
 
-1. **Parse Category Scores** — extract baseline + result score tables, normalize names, flag unmatched. Detail: `../../reference/compare-rubric.md#step-1--parse-category-scores`.
-2. **Compute Score Delta** — `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `../../reference/compare-rubric.md#step-2--compute-score-delta-comp-03`.
-3. **Anti-Pattern Delta** — set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `../../reference/compare-rubric.md#step-3--anti-pattern-delta`.
-4. **Must-Have Pass/Fail Change** — read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `../../reference/compare-rubric.md#step-4--must-have-passfail-change`.
-5. **Design Drift Detection (COMP-04)** — build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `../../reference/compare-rubric.md#step-5--design-drift-detection-comp-04`.
-6. **Screenshot Delta (preview: available only)** — capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `../../reference/compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
-7. **Write `.design/COMPARE-REPORT.md`** — full template at `../../reference/compare-rubric.md#step-6--compare-reportmd-template`.
+1. **Parse Category Scores** — extract baseline + result score tables, normalize names, flag unmatched. Detail: `./compare-rubric.md#step-1--parse-category-scores`.
+2. **Compute Score Delta** — `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `./compare-rubric.md#step-2--compute-score-delta-comp-03`.
+3. **Anti-Pattern Delta** — set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `./compare-rubric.md#step-3--anti-pattern-delta`.
+4. **Must-Have Pass/Fail Change** — read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `./compare-rubric.md#step-4--must-have-passfail-change`.
+5. **Design Drift Detection (COMP-04)** — build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `./compare-rubric.md#step-5--design-drift-detection-comp-04`.
+6. **Screenshot Delta (preview: available only)** — capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `./compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
+7. **Write `.design/COMPARE-REPORT.md`** — full template at `./compare-rubric.md#step-6--compare-reportmd-template`.
 
 ---
 

package/skills/connections/SKILL.md

@@ -12,7 +12,7 @@ Interactive onboarding for the 12 external integrations the pipeline supports. R
 
 Canonical per-connection specs live in `../../connections/<name>.md` (one file per integration). The capability matrix + probe-pattern spec live in `../../connections/connections.md`. This skill is the **user-facing front end** for those specs.
 
-For the 12 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `../../reference/connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
+For the 12 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `./connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
 
 ---
 
@@ -38,20 +38,20 @@ For the 12 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization
 
 ## Workflow
 
-1. **Probe all 12 connections** — run every probe script per `../../reference/connections-onboarding.md#step-1--probe-all-12-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
-2. **Categorize + build summary** — bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `../../reference/connections-onboarding.md#step-2--bucket-categorization`.
-3. **Print summary table** — show buckets + value-prop one-liners (verbatim from `../../reference/connections-onboarding.md#step-3--summary-table`).
-4. **Route by mode** — `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `../../reference/connections-onboarding.md#step-4--route-by-mode`.
-5. **Per-connection setup screen** — for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `../../reference/connections-onboarding.md#step-5--per-connection-setup-screen`.
-6. **Verification pass** — re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `../../reference/connections-onboarding.md#step-6--verification-pass`.
+1. **Probe all 12 connections** — run every probe script per `./connections-onboarding.md#step-1--probe-all-12-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
+2. **Categorize + build summary** — bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `./connections-onboarding.md#step-2--bucket-categorization`.
+3. **Print summary table** — show buckets + value-prop one-liners (verbatim from `./connections-onboarding.md#step-3--summary-table`).
+4. **Route by mode** — `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `./connections-onboarding.md#step-4--route-by-mode`.
+5. **Per-connection setup screen** — for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `./connections-onboarding.md#step-5--per-connection-setup-screen`.
+6. **Verification pass** — re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `./connections-onboarding.md#step-6--verification-pass`.
 
-If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry → enter **resume flow**: run Step 6 immediately; if clean, exit; otherwise fall through to Step 3. Detail: `../../reference/connections-onboarding.md#resumability`.
+If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry → enter **resume flow**: run Step 6 immediately; if clean, exit; otherwise fall through to Step 3. Detail: `./connections-onboarding.md#resumability`.
 
 ---
 
 ## Do Not
 
-Per `../../reference/connections-onboarding.md#do-not`:
+Per `./connections-onboarding.md#do-not`:
 
 - Never run `npm install -g` globals automatically.
 - Never write to `~/.bashrc`, `~/.zshrc`, or shell RC files.