@hegemonart/get-design-done 1.57.1 → 1.57.3

package/connections/cursor.md

@@ -0,0 +1,72 @@
+# Cursor — Runtime Install Notes
+
+This file documents the get-design-done install path on Cursor and one known limitation.
+
+Cursor is one of the 14 first-class runtimes for `gdd install` (see `reference/runtimes.md` for the full set). It uses the `multi-artifact` install kind: skills land as `~/.cursor/skills/<gdd-name>/SKILL.md` after passing through `scripts/lib/install/converters/cursor.cjs`.
+
+## Install
+
+```
+gdd install --runtime cursor          # global → ~/.cursor/skills/
+gdd install --runtime cursor --local  # repo-local → .cursor/skills/
+```
+
+Each installed skill is name-prefixed with `gdd-` (e.g. `gdd-explore`, `gdd-discover`) so it cannot collide with user-authored Cursor skills.
+
+## Converter behavior
+
+`converters/cursor.cjs#convert` is a pure string→string transform that:
+
+- Normalizes the frontmatter `name:` field to `gdd-<skill>` (no double-prefix).
+- Rewrites mixed-shape slash references (`gdd-x`, `/gdd:x`) to a consistent `/gdd-<name>` shape.
+- Passes the Claude tool vocabulary through unchanged (Read / Write / Bash / Edit / Grep / Glob — Cursor accepts these).
+- Injects a 1-line HTML adapter header recording auto-generation.
+
+The output is byte-stable per source — re-running `gdd install --runtime cursor` is a no-op when nothing has changed.
+
+## Known limitation — sibling .md files are NOT installed
+
+Some skills ship procedure detail in sibling `.md` files next to `SKILL.md`. For example:
+
+```
+skills/discover/
+├── SKILL.md                      ← installed
+└── discover-procedure.md         ← NOT installed (sibling)
+```
+
+`SKILL.md` references the sibling via a relative link (e.g. `./discover-procedure.md`). On Cursor, that link resolves to nothing.
+
+This is a systemic limitation of the current `multi-artifact` install pipeline (`scripts/lib/install/runtime-artifact-layout.cjs#skillsKind`), not a Cursor-specific bug. It affects every runtime that uses `skillsKind`: claude global, cursor, codex, copilot, antigravity, windsurf, augment, trae, qwen, codebuddy. Skills with sibling files currently affected:
+
+- `apply-reflections/apply-reflections-procedure.md`
+- `cache-manager/cache-policy.md`
+- `compare/compare-rubric.md`
+- `connections/connections-onboarding.md`
+- `darkmode/darkmode-audit-procedure.md`
+- `debug/debug-feedback-loops.md`
+- `design/design-procedure.md`
+- `discover/discover-procedure.md`
+- `explore/explore-procedure.md`
+- `health/health-mcp-detection.md`
+- `health/health-skill-length-report.md`
+- `peer-cli-add/peer-cli-protocol.md`
+- `plan/plan-procedure.md`
+- `quality-gate/threat-modeling.md`
+- `report-issue/report-issue-procedure.md`
+- `router/capability-gap-emitter.md`
+- `router/router-pick-emitter.md`
+- `router/router-rules.md`
+- `scan/scan-procedure.md`
+- `start/start-procedure.md`
+- `style/style-doc-procedure.md`
+- `verify/verify-procedure.md`
+
+### Workarounds until a fix lands
+
+1. **Use the cursor-marketplace distribution channel** — `scripts/lib/install/converters/cursor-marketplace.cjs` copies the entire `skills/` tree byte-for-byte (siblings included). Install through the marketplace plugin rather than per-skill if you need the full procedure detail.
+2. **Clone the repo locally** — Cursor can read sibling files directly from the source checkout if you point it at the repo tree.
+3. **Inline-grep the source** — for one-off questions, read the source `SKILL.md` directly; siblings are short and self-contained.
+
+### Fix scope (tracked as follow-up beyond batch H6)
+
+Properly enumerating siblings requires extending the StagedArtifact contract to emit multiple files per skill (one SKILL.md + N siblings), updating `computeDestPath` for non-SKILL.md paths inside a skill subdir, the foreign-file detection in `installer.cjs#detectMultiArtifactInstalled`, and the uninstall enumeration in `uninstallMultiArtifact`. See the `KNOWN LIMITATION` block at the top of `scripts/lib/install/converters/cursor.cjs` for the technical detail.

package/connections/preview.md

@@ -107,10 +107,10 @@ When preview is `not_configured` or `unavailable`, stages degrade gracefully —
 
 **verify stage (`skills/verify/SKILL.md` + `agents/design-verifier.md`):**
 
-- Skip Phase 4B screenshot evidence loop entirely
+- Skip Stage 4B screenshot evidence loop entirely
 - Keep existing `? VISUAL` static analysis path for H-02, H-06, H-07 heuristics
-- Mark all Phase 4B checks: `[SKIPPED — browser not available]`
-- Design-verifier continues to Phase 5 gap analysis with partial scores
+- Mark all Stage 4B checks: `[SKIPPED — browser not available]`
+- Design-verifier continues to Stage 5 gap analysis with partial scores
 
 **compare stage (`skills/compare/SKILL.md`):**
 

package/hooks/first-run-nudge.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * get-design-done — first-run nudge (Phase 14.7)
+ *
+ * Port of hooks/first-run-nudge.sh to pure Node CommonJS (Phase 28.x).
+ * SessionStart hook. Silent-on-failure by policy: exits 0 on every error path.
+ * Prints exactly one restrained line pointing at /gdd:start when all gates
+ * pass, and nothing otherwise.
+ *
+ * Non-obvious behavior preserved:
+ *  - Logger is silent unless GDD_NUDGE_DEBUG=1 (matches bash `${VAR:-0}`).
+ *  - HOME falls back to USERPROFILE (Windows). Mirrors bash `${HOME:-$USERPROFILE}`.
+ *  - read_state_stage uses the same regex shape as the bash sed: drops an
+ *    optional surrounding double-quote and stops at the first whitespace.
+ *  - has_recent_gdd_command is a placeholder that always returns false (matches
+ *    the bash `return 1` → `is_active` boolean false).
+ *  - Sourcing guard: helpers are exported on module.exports; main() only runs
+ *    when invoked as the entry point (require.main === module).
+ *  - Always exit 0 — every error path is swallowed.
+ *  - The locked nudge copy appears exactly once in this file (test asserts
+ *    the nudge string occurs exactly once in the hook source).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const NUDGE_LINE =
+  'Tip: run /gdd:start to let GDD inspect this codebase and suggest one first fix.\n';
+
+function log(msg) {
+  if (process.env.GDD_NUDGE_DEBUG === '1') {
+    process.stderr.write(`[gdd first-run-nudge] ${msg}\n`);
+  }
+}
+
+/**
+ * Gate 1 — repo already has GDD state, suppress.
+ * @param {string} designDir absolute path to <cwd>/.design
+ * @returns {boolean}
+ */
+function hasDesignState(designDir) {
+  try {
+    const config = path.join(designDir, 'config.json');
+    const state = path.join(designDir, 'STATE.md');
+    return isFile(config) || isFile(state);
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Gate 2 — per-install dismissal flag.
+ * @param {string} homeDir resolved HOME (or USERPROFILE on Windows)
+ * @returns {boolean}
+ */
+function isDismissed(homeDir) {
+  try {
+    if (!homeDir) return false;
+    return isFile(path.join(homeDir, '.claude', 'gdd-nudge-dismissed'));
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Reads the first `stage:` line out of STATE.md and strips surrounding quoting
+ * the way the bash sed expression does (drops an optional surrounding double
+ * quote, captures non-quote/non-whitespace chars, ignores any trailing text).
+ *
+ * @param {string} stateFilePath absolute path to STATE.md
+ * @returns {string} the captured stage value, or '' if unavailable
+ */
+function readStateStage(stateFilePath) {
+  try {
+    if (!isFile(stateFilePath)) return '';
+    const text = fs.readFileSync(stateFilePath, 'utf8');
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+      if (/^stage:/.test(line)) {
+        const m = line.match(/^stage:[ \t]*"?([^"\s]+)"?.*/);
+        if (m && m[1]) return m[1];
+        return '';
+      }
+    }
+    return '';
+  } catch (_e) {
+    return '';
+  }
+}
+
+const ACTIVE_STAGES = new Set(['plan', 'design', 'verify', 'executing', 'discussing']);
+
+/**
+ * Gate 3 — STATE.md stage belongs to an active pipeline window.
+ * @param {string} stateFilePath absolute path to STATE.md
+ * @returns {boolean}
+ */
+function isActiveStage(stateFilePath) {
+  const s = readStateStage(stateFilePath);
+  return ACTIVE_STAGES.has(s);
+}
+
+/**
+ * Gate 4 — recent session history has a gdd:* command.
+ * Placeholder: no portable transcript path exposed to SessionStart hooks today.
+ * Mirrors the bash version's `return 1` (false) so we never falsely suppress.
+ * @returns {boolean}
+ */
+function hasRecentGddCommand() {
+  return false;
+}
+
+function isFile(p) {
+  try {
+    const st = fs.statSync(p);
+    return st.isFile();
+  } catch (_e) {
+    return false;
+  }
+}
+
+function resolveHomeDir() {
+  // bash: ${HOME:-$USERPROFILE} — HOME wins if set (even on Windows), else USERPROFILE.
+  return process.env.HOME || process.env.USERPROFILE || '';
+}
+
+function main() {
+  try {
+    const cwd = process.cwd();
+    const designDir = path.join(cwd, '.design');
+    const stateFile = path.join(designDir, 'STATE.md');
+    const homeDir = resolveHomeDir();
+
+    if (hasDesignState(designDir)) {
+      log('design state present — suppress');
+      process.exit(0);
+    }
+    if (isDismissed(homeDir)) {
+      log('dismissal flag present — suppress');
+      process.exit(0);
+    }
+    if (isActiveStage(stateFile)) {
+      log('active stage — suppress');
+      process.exit(0);
+    }
+    if (hasRecentGddCommand()) {
+      log('recent gdd:* command detected — suppress');
+      process.exit(0);
+    }
+    // All gates passed — emit the locked one-line nudge.
+    process.stdout.write(NUDGE_LINE);
+    process.exit(0);
+  } catch (_e) {
+    // Silent-on-failure: every error path exits 0.
+    process.exit(0);
+  }
+}
+
+module.exports = {
+  hasDesignState,
+  isDismissed,
+  readStateStage,
+  isActiveStage,
+  hasRecentGddCommand,
+};
+
+if (require.main === module) {
+  main();
+}

package/hooks/gdd-intel-trigger.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-intel-trigger.js — D5 (PostToolUse on Edit|Write)
+ *
+ * On every Edit/Write that touches a design-authoritative surface
+ * (skills/**, agents/**, reference/**, source/skills/**), spawn a
+ * background, detached refresh of the .design/intel/ store so downstream
+ * consumers (router, planner, audits) see the latest extracts without the
+ * user paying for a full rebuild on the next /gdd run.
+ *
+ * Contract:
+ *   1. Read the PostToolUse payload from stdin. Tolerate snake_case and
+ *      camelCase field names (tool_name/toolName, tool_input/toolInput,
+ *      file_path/filePath/path).
+ *   2. If the edited path matches
+ *        ^(skills|agents|reference|source/skills)/.*\.(md|json)$
+ *      (path-separator-agnostic), schedule a background refresh.
+ *   3. Otherwise no-op — write {continue:true} and exit 0.
+ *   4. Always exit 0. Never block. Never surface errors. Errors only ever
+ *      land as a stderr breadcrumb (best-effort).
+ *
+ * Opt-out:
+ *   Set GDD_DISABLE_INTEL_TRIGGER=1 to silence this hook completely
+ *   (still writes {continue:true}, exits 0, spawns nothing).
+ *
+ * Dedup lock:
+ *   .design/.intel-trigger.lock — a JSON file with {ts: <epoch_ms>}.
+ *   If the lock is younger than 5 minutes, we assume a refresh is already
+ *   in flight (or recently ran) and skip spawning again. Rapid sequential
+ *   edits coalesce into one background rebuild. The lock is best-effort:
+ *   if the .design/ dir does not exist or we cannot read/write the lock,
+ *   we still proceed (or still no-op safely).
+ *
+ * Refresh path:
+ *   scripts/build-intel.cjs is the rebuilder. It has no `--incremental`
+ *   flag (incremental is its DEFAULT behavior — invoking it without
+ *   `--force` re-extracts only changed files via mtime/git-hash). The
+ *   task spec said "if --incremental exists, spawn it; else emit a
+ *   breadcrumb." Since the script DOES do incremental by default, we
+ *   spawn it as `node scripts/build-intel.cjs` (no flags) and surface
+ *   the convention in the breadcrumb so future maintainers know why
+ *   no `--incremental` was passed. If the script is ever missing, we
+ *   emit only a breadcrumb and continue.
+ *
+ * Spawn shape:
+ *   child_process.spawn('node', [script], { detached: true,
+ *     stdio: 'ignore', windowsHide: true }) followed by child.unref().
+ *   This decouples the child from our process tree so the hook returns
+ *   immediately and the rebuild happens out of band.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const LOCK_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const TARGET_RE = /^(?:skills|agents|reference|source\/skills)\/.*\.(?:md|json)$/;
+
+/**
+ * Extract the edited file path + tool name from a PostToolUse payload.
+ * Returns { tool, filename } or null when nothing usable was found.
+ */
+function extractTarget(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const tool = payload.tool_name || payload.toolName;
+  if (tool !== 'Write' && tool !== 'Edit') return null;
+  const input = payload.tool_input || payload.toolInput || {};
+  const filename =
+    input.file_path ||
+    input.filePath ||
+    input.path ||
+    (payload.tool_response &&
+      (payload.tool_response.filePath || payload.tool_response.file_path)) ||
+    '';
+  if (!filename) return null;
+  return { tool, filename: String(filename) };
+}
+
+/**
+ * Decide whether the given (absolute or relative) filename, considered
+ * relative to `cwd`, lives under one of the design-authoritative roots
+ * and is .md or .json. Returns true/false. Path-separator-agnostic.
+ */
+function isDesignSurface(filename, cwd) {
+  if (!filename) return false;
+  let rel;
+  try {
+    rel = path.isAbsolute(filename)
+      ? path.relative(cwd, filename)
+      : filename;
+  } catch {
+    return false;
+  }
+  if (!rel || rel.startsWith('..')) return false;
+  const normalised = rel.replace(/\\/g, '/');
+  return TARGET_RE.test(normalised);
+}
+
+/**
+ * Best-effort: returns true if the lockfile exists AND its timestamp is
+ * younger than LOCK_TTL_MS. False on any error (missing dir, parse fail,
+ * stat fail) — fail-open so we still trigger the rebuild.
+ */
+function lockIsFresh(lockPath) {
+  try {
+    if (!fs.existsSync(lockPath)) return false;
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const ts = Number(parsed && parsed.ts);
+    if (!Number.isFinite(ts)) return false;
+    return Date.now() - ts < LOCK_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Best-effort: write {ts: Date.now()} to the lockfile, ensuring its
+ * parent dir exists. Swallows all errors — locking is purely an
+ * optimisation; failure to lock just means the next edit may re-trigger.
+ */
+function writeLock(lockPath) {
+  try {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    fs.writeFileSync(lockPath, JSON.stringify({ ts: Date.now() }), 'utf8');
+  } catch {
+    /* swallow */
+  }
+}
+
+/**
+ * Spawn the intel rebuild as a detached background process. The child is
+ * fully decoupled (stdio:'ignore', detached:true, unref()) so the hook
+ * returns immediately. Errors are swallowed — the worst case is a stale
+ * intel store, which is no worse than the pre-hook baseline.
+ */
+function spawnRebuild(cwd, script) {
+  try {
+    const child = spawn(process.execPath, [script], {
+      cwd,
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      env: process.env,
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Core hook entry. Returns the decision object to write to stdout.
+ * Always returns {continue: true}. Exported for unit testing.
+ *
+ * Optional `opts.spawnImpl` overrides the spawn-rebuild side effect
+ * (so tests can assert it was called without forking a real node).
+ */
+function main(payload, opts = {}) {
+  // Opt-out shortcut — read here (not at module top) so tests can flip the
+  // env between calls without re-requiring the module.
+  if (process.env.GDD_DISABLE_INTEL_TRIGGER === '1') {
+    return { continue: true };
+  }
+
+  const cwd = (payload && payload.cwd) || opts.cwd || process.cwd();
+  const target = extractTarget(payload);
+  if (!target) return { continue: true };
+  if (!isDesignSurface(target.filename, cwd)) return { continue: true };
+
+  const lockPath = path.join(cwd, '.design', '.intel-trigger.lock');
+  if (lockIsFresh(lockPath)) return { continue: true };
+
+  const script = path.join(cwd, 'scripts', 'build-intel.cjs');
+  if (!fs.existsSync(script)) {
+    // Follow-up: a missing rebuilder is not this hook's problem to fix.
+    try {
+      process.stderr.write(
+        '[gdd-intel-trigger] would refresh .design/intel/ if scripts/build-intel.cjs --incremental existed\n'
+      );
+    } catch {
+      /* swallow */
+    }
+    return { continue: true };
+  }
+
+  // Lock first (idempotent if write fails), then spawn. Locking first
+  // means a sibling Edit racing this one will see a fresh lock and skip
+  // even if our spawn has not yet completed.
+  writeLock(lockPath);
+  const doSpawn = typeof opts.spawnImpl === 'function' ? opts.spawnImpl : spawnRebuild;
+  doSpawn(cwd, script);
+
+  return { continue: true };
+}
+
+/** CLI entrypoint — read JSON from stdin, decide, write {continue:true}. */
+async function run(stdin = process.stdin, stdout = process.stdout) {
+  let buf = '';
+  try {
+    for await (const chunk of stdin) buf += chunk;
+  } catch {
+    stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(buf || '{}');
+  } catch {
+    stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+  let decision;
+  try {
+    decision = main(payload);
+  } catch {
+    decision = { continue: true };
+  }
+  stdout.write(JSON.stringify(decision || { continue: true }));
+}
+
+if (require.main === module) {
+  run().catch(() => {
+    try {
+      process.stdout.write(JSON.stringify({ continue: true }));
+    } catch {
+      /* swallow */
+    }
+  });
+}
+
+module.exports = {
+  main,
+  extractTarget,
+  isDesignSurface,
+  lockIsFresh,
+  writeLock,
+  spawnRebuild,
+  LOCK_TTL_MS,
+  TARGET_RE,
+};

package/hooks/gdd-mcp-circuit-breaker.js

@@ -40,15 +40,70 @@ function loadBudget(cwd) {
   return defaults;
 }
 
+/**
+ * Classify the outcome of an MCP tool call as 'success' | 'timeout' | 'error'.
+ *
+ * The previous implementation substring-matched 'timeout' / 'failed' against
+ * the ENTIRE JSON-stringified response. That fired false positives on legit
+ * successful payloads whose content happens to mention those words — e.g. a
+ * Figma node literally named "TimeoutBanner", or a summary line "2 of 5 nodes
+ * failed to update, retrying...". When the breaker false-positives, it
+ * advances consecutive_timeouts and eventually trips on healthy traffic.
+ *
+ * The fix: use the structured isError / is_error envelope as the primary
+ * signal. MCP tool results carry isError=true|false. Anything without an
+ * explicit error flag is treated as success — full stop. Only when the
+ * envelope says "error" do we then inspect the ERROR-message fields
+ * (content[*].text + error.message + error.code + top-level message) to
+ * decide between 'timeout' and generic 'error'. Arbitrary content text is
+ * never scanned.
+ */
 function classifyOutcome(toolResponse) {
   if (!toolResponse || typeof toolResponse !== 'object') return 'error';
-  const text = JSON.stringify(toolResponse).slice(0, 4000).toLowerCase();
-  // Check timeout FIRST — a timed-out call may also set is_error, but we want
-  // to classify it as "timeout" so consecutive_timeouts advances correctly.
-  if (text.includes('timeout') || text.includes('timed out') || text.includes('deadline exceeded')) return 'timeout';
-  if (toolResponse.is_error) return 'error';
-  if (text.includes('"error"') || text.includes('failed')) return 'error';
-  return 'success';
+
+  // MCP standard envelope: isError (camelCase). Claude Code historically
+  // passes is_error (snake_case). Accept either; treat absence as success.
+  const isError =
+    toolResponse.isError === true || toolResponse.is_error === true;
+
+  if (!isError) return 'success';
+
+  // Error path: classify timeout vs generic by reading ONLY the dedicated
+  // error-message fields, not the entire payload.
+  const messageBits = [];
+
+  // content[] may be a string (legacy) or an array of {type,text} (spec).
+  if (typeof toolResponse.content === 'string') {
+    messageBits.push(toolResponse.content);
+  } else if (Array.isArray(toolResponse.content)) {
+    for (const c of toolResponse.content) {
+      if (c && typeof c.text === 'string') messageBits.push(c.text);
+    }
+  }
+
+  if (toolResponse.error && typeof toolResponse.error === 'object') {
+    if (typeof toolResponse.error.message === 'string') {
+      messageBits.push(toolResponse.error.message);
+    }
+    if (typeof toolResponse.error.code === 'string') {
+      messageBits.push(toolResponse.error.code);
+    }
+  }
+  if (typeof toolResponse.message === 'string') {
+    messageBits.push(toolResponse.message);
+  }
+
+  const combined = messageBits.join(' ').toLowerCase();
+  // \btimeout\b matches "timeout" and "request timeout"; \btimed?\s*out\b
+  // matches "timed out"; deadline exceeded is gRPC; etimedout is Node fs.
+  if (
+    /\btimeout\b|\btimed?\s*out\b|\bdeadline\s+exceeded\b|\betimedout\b/.test(
+      combined,
+    )
+  ) {
+    return 'timeout';
+  }
+  return 'error';
 }
 
 function readJsonlTail(filePath) {