@hegemonart/get-design-done 1.48.0 → 1.49.0

package/reference/visual-tells.md

@@ -0,0 +1,237 @@
+# Visual Tells Catalog (v1)
+
+The default-AI aesthetic has a fingerprint. When a model generates a front-end
+without a brand brief, it falls back to the same handful of moves it saw most in
+its training set. This catalog names those moves so the cheap regex floor in
+`hooks/gdd-design-quality-check.js` can flag them on every `.tsx` / `.vue` /
+`.svelte` / `.astro` write.
+
+Severity here is WARN (advisory), in the vocabulary of `reference/audit-scoring.md`.
+A WARN is not a FLAG: it does not block the write and it does not fail a gate. It
+is a nudge that asks "did you choose this, or did the model default to it?" Each
+category below maps 1:1 to a rule id in the hook. For the harder bans behind some
+of these tells, see `reference/anti-patterns.md` (BAN-NN and SLOP-NN).
+
+How to read each entry: a short description, three to five concrete instances of
+the tell in the wild, the diagnostic regex the hook runs (where one applies), and
+a remediation pattern you can paste in.
+
+---
+
+## default-AI-hero
+
+Rule id: `generic-cta`
+
+The stock landing-page hero: a centered headline, one line of filler subtext, and
+a button that says "Get Started". The copy carries no subject and no verb specific
+to the product. It reads like every template because it is every template.
+
+Instances:
+
+1. Button label "Get Started" with no object ("Get started with what?").
+2. Headline opener "Welcome to [Product]" instead of a value statement.
+3. "Learn More" as the secondary call to action, pointing nowhere specific.
+4. "Lorem ipsum" body copy shipped past the mockup stage.
+5. The triplet subhead with no verb (see SLOP-11 in `reference/anti-patterns.md`).
+
+Diagnostic regex (hook): `\b(?:Get Started|Welcome to|Lorem ipsum|Learn More)\b`
+(case-insensitive, word-boundaried).
+
+Remediation: write the specific promise and the specific next step. "Start a free
+trial" beats "Get Started". "Ship your first audit in ten minutes" beats "Welcome
+to GDD". Name the noun and the verb. Delete placeholder copy before review.
+
+---
+
+## gradient-spam
+
+Rule id: `gradient-spam`
+
+One tasteful gradient can anchor a page. Three or more on a single screen reads as
+decoration standing in for hierarchy. The model reaches for `bg-gradient-to-r` on
+the hero, again on the cards, again on the footer, because gradients look busy and
+busy looks "designed".
+
+Instances:
+
+1. Hero background, card backgrounds, and a CTA all using a direction gradient.
+2. `bg-gradient-to-br` on every feature tile in a grid.
+3. A gradient on text plus a gradient on its container (double application).
+4. Gradient borders faked with a gradient background and an inset child.
+
+Diagnostic regex (hook): `\bbg-gradient-to-(?:r|br|tr|b|bl|l|tl|t)\b`, flagged at
+a count of three or more occurrences in one file.
+
+Remediation: pick one surface to carry a gradient and make the rest solid. Use
+weight, size, and spacing for hierarchy instead of color washes. If you keep a
+gradient, give it a documented role (one hero, one accent) rather than spraying it.
+For the gradient-text ban specifically, see BAN-02.
+
+---
+
+## isometric-illustration-fallback
+
+Rule id: `isometric-illustration-fallback`
+
+Pastel isometric scenes with floating icons, usually pulled straight from a free
+clip-art set. The undraw.co style is the strongest tell: flat shapes, two-tone
+palette, no brand character. It signals that no real screenshot or photography was
+available, so a stock scene filled the hole.
+
+Instances:
+
+1. `src="/illustrations/undraw_dashboard.svg"` in an empty state.
+2. An `isometric-hero.png` asset behind the headline.
+3. A row of undraw spot illustrations as feature icons.
+4. The same illustration set reused across unrelated products.
+
+Diagnostic regex (hook): `\b(?:undraw|isometric)[\w./-]*` (matches the marker in an
+asset path or `src`).
+
+Remediation: show the actual product. A real screenshot, a short screen capture,
+or a purpose-drawn illustration with brand character all beat stock clip art. See
+SLOP-12 in `reference/anti-patterns.md` for the longer argument.
+
+---
+
+## centered-everything-syndrome
+
+Rule id: `centered-everything-syndrome`
+
+`mx-auto` plus `text-center` on block after block. Centered text is fine for a
+single short hero line. Applied to body copy, feature lists, and multi-line cards
+it destroys the reading edge: the eye loses the left margin it scans against, and
+every block competes for the same axis.
+
+Instances:
+
+1. A hero, a feature grid, and a testimonial section all centered.
+2. Centered multi-line paragraphs longer than two lines.
+3. A centered card with centered heading, centered body, and a centered button.
+4. Centered form labels above left-aligned inputs (axis mismatch).
+
+Diagnostic regex (hook): a quoted class string containing both `mx-auto` and
+`text-center`, in either order.
+
+Remediation: center the hero line only. Left-align body copy and lists so they
+share a reading edge. Reserve centering for short, single-line, high-emphasis text.
+Center the container for width control, but left-align its text content.
+
+---
+
+## inter-everything
+
+Rule id: `inter-everything`
+
+Inter as the default with no documented reason. Inter is a fine typeface, which is
+exactly why it is the safe pick a model makes when no brand font is specified. The
+tell is not Inter itself: it is Inter used alone, with no second font and no token
+that records a choice.
+
+Instances:
+
+1. `font-inter` on the root with no display or brand font anywhere.
+2. `font-family: 'Inter'` in CSS with no second family in the stack file.
+3. Inter paired with no `--font-display` or `--font-body` token.
+4. DM Sans, Space Grotesk, or Plus Jakarta Sans in the same role (see SLOP-05).
+
+Diagnostic regex (hook): `\bfont-inter\b` or `font-family:\s*['"]?Inter`, warned
+only when no sibling custom-font token (a `font-<name>` utility, a `--font-*`
+variable, or a second `font-family`) appears in the same file.
+
+Remediation: choose a typeface you can defend in three sentences against the brand,
+and record it as a token (`--font-display`, `--font-body`). If Inter is the right
+call, pair it with a distinct display face or a deliberate weight system so the
+choice is visible. Keeping the token is what turns a default into a decision.
+
+---
+
+## purple-violet-default
+
+Rule id: `purple-violet-default`
+
+`bg-purple-600` and `bg-violet-600` are the colors a model picks when no palette is
+given. Combined with indigo and cyan they form the exact accent set that ships on a
+large share of generated UIs (SLOP-01). The tell is the raw Tailwind shade used as
+the brand color with no theme token in sight.
+
+Instances:
+
+1. `bg-violet-600` on the primary button with no `bg-primary` token defined.
+2. `bg-purple-500` headers across the app, hardcoded per component.
+3. Purple-to-blue accent pairing on hero plus buttons (SLOP-02).
+4. `text-violet-600` links with no semantic link color.
+
+Diagnostic regex (hook): `\bbg-(?:purple|violet)-(?:500|600|700)\b`, warned only
+when no theme-token class (`bg-primary`, `bg-brand`, `bg-accent`, or a
+`bg-[var(--...)]` / `oklch` / `hsl` arbitrary value) is present in the file.
+
+Remediation: route color through a token (`bg-primary`, `--color-accent`) so the
+brand hue lives in one place. If purple is genuinely the brand, define it as the
+token and reference the token, not the raw shade. Pick one primary accent and apply
+it consistently. See the Color System rubric in `reference/audit-scoring.md`.
+
+---
+
+## glassmorphism-spam
+
+Rule id: `glassmorphism-spam`
+
+Frosted-glass panels stacked everywhere: `backdrop-blur` on cards, on the nav, on
+modals, plus `bg-white/10` fills. One blurred overlay over busy content is a valid
+move. Three or more blur or low-alpha-white treatments in one file is glass used as
+the default surface, which hides the fact that no real layout system exists.
+
+Instances:
+
+1. `backdrop-blur-lg` on every card in a grid.
+2. `bg-white/10` panels layered three deep.
+3. A blurred nav over a blurred hero over a blurred section.
+4. Glass cards on a flat background where there is nothing to blur.
+
+Diagnostic regex (hook): `\bbackdrop-blur(?:-\w+)?\b` or `\bbg-white\/(?:10|20|30)\b`,
+flagged at a count of three or more occurrences in one file.
+
+Remediation: keep blur for cases where it has a job, such as a modal dimming the
+content behind it, a floating command palette, or a sticky header over scrolling
+content. Give other surfaces solid fills and a real elevation system. See SLOP-04
+for the valid-use list.
+
+---
+
+## decorative-motion-without-intent
+
+Rule id: `decorative-motion-without-intent`
+
+`animate-pulse`, `animate-bounce`, and `animate-spin` are loading affordances. The
+tell is using them as ambient decoration: a pulsing hero badge, a bouncing arrow
+that never stops, a spinning accent that encodes no progress. Motion that loops
+forever with no state behind it reads as filler and fights `prefers-reduced-motion`.
+
+Instances:
+
+1. `animate-pulse` on a static "New" badge in the hero.
+2. `animate-bounce` on a scroll-down chevron looping with no end.
+3. `animate-spin` on a decorative ring that is not a spinner.
+4. A pulsing gradient blob behind the headline.
+
+Diagnostic regex (hook, conservative): a quoted class string containing
+`animate-(pulse|bounce|spin)` that does not also contain a loading signal
+(`loading`, `loader`, `spinner`, `skeleton`, `icon`, `i-`, or `sr-only`).
+
+Remediation: tie motion to a state. Use `animate-pulse` on skeletons while data
+loads, `animate-spin` on a real spinner during a request, and drop ambient loops.
+Respect `prefers-reduced-motion`. Enter with `ease-out`, exit shorter than enter,
+and never animate keyboard-driven actions. See the Motion Anti-Patterns section of
+`reference/anti-patterns.md`.
+
+---
+
+## Notes
+
+This is a v1 floor, not a ceiling. The regexes favor precision over recall: they
+aim to fire only on the obvious cases so the WARN stays trustworthy. A clean pass
+here does not mean the design is good. It means the eight loudest default-AI tells
+are absent. Real review still applies the full rubric in
+`reference/audit-scoring.md` and the BAN / SLOP catalog in
+`reference/anti-patterns.md`.

package/scripts/lib/confidence-route.cjs

@@ -0,0 +1,60 @@
+'use strict';
+/**
+ * scripts/lib/confidence-route.cjs — pure routing helper for the reviewer
+ * confidence gate (Phase 49). Decides where a single finding/gap goes based on
+ * its severity, its `confidence` score (0.0-1.0), and whether the reviewer
+ * parked it in the `## Tentative` section.
+ *
+ * Canonical rule (mirrors reference/reviewer-confidence-gate.md):
+ *   - A finding in `## Tentative`            -> 'drop'         (never reaches design-fixer)
+ *   - confidence < 0.5                       -> 'drop'         (low-confidence floor; stays tentative)
+ *   - HIGH/CRITICAL (BLOCKER|MAJOR) needs    -> 'fix' only when confidence >= 0.8,
+ *                                               otherwise 'user-review'
+ *   - confidence in [0.5, 0.8)               -> 'user-review'  (surfaced, not auto-fixed)
+ *   - confidence >= 0.8                       -> 'fix'
+ *
+ * Returns one of: 'fix' | 'user-review' | 'drop'. Dependency-free and side
+ * effect free so the routing matrix is unit-testable in isolation.
+ */
+
+const HIGH_FLOOR = 0.8; // BLOCKER/MAJOR must clear this to auto-fix
+const SURFACE_FLOOR = 0.5; // below this a finding is dropped (stays tentative)
+
+// Severity labels that count as HIGH/CRITICAL for the auto-fix floor.
+const HIGH_SEVERITIES = new Set(['blocker', 'major', 'high', 'critical']);
+
+function isHighSeverity(severity) {
+  if (typeof severity !== 'string') return false;
+  return HIGH_SEVERITIES.has(severity.trim().toLowerCase());
+}
+
+/**
+ * Route a finding/gap.
+ * @param {object} finding
+ * @param {string} finding.severity   - BLOCKER | MAJOR | MINOR | COSMETIC (case-insensitive).
+ * @param {number} finding.confidence - 0.0-1.0 confidence score.
+ * @param {boolean} [finding.tentative] - true when the finding sits in `## Tentative`.
+ * @returns {'fix'|'user-review'|'drop'}
+ */
+function route({ severity, confidence, tentative = false } = {}) {
+  // 1. Tentative findings never reach the fixer, regardless of score.
+  if (tentative === true) return 'drop';
+
+  // 2. A missing/non-numeric confidence is treated as the lowest tier: surface
+  //    for user review rather than silently auto-fixing or dropping.
+  const c = typeof confidence === 'number' && Number.isFinite(confidence) ? confidence : 0;
+
+  // 3. Low-confidence floor: anything under 0.5 is dropped (stays tentative).
+  if (c < SURFACE_FLOOR) return 'drop';
+
+  // 4. HIGH/CRITICAL findings must clear the 0.8 floor to auto-fix; otherwise
+  //    they are routed to the user instead of the fixer.
+  if (isHighSeverity(severity)) {
+    return c >= HIGH_FLOOR ? 'fix' : 'user-review';
+  }
+
+  // 5. Lower-severity findings: 0.5-0.8 surfaces for review, >= 0.8 auto-fixes.
+  return c >= HIGH_FLOOR ? 'fix' : 'user-review';
+}
+
+module.exports = { route, isHighSeverity, HIGH_FLOOR, SURFACE_FLOOR };

package/scripts/lib/worktree-resolve.cjs

@@ -0,0 +1,221 @@
+'use strict';
+/**
+ * scripts/lib/worktree-resolve.cjs — Phase 49 (Quick Anti-Slop Floor).
+ *
+ * Redirect `.design/` and `.planning/` writes to the MAIN repo root when GDD
+ * runs inside a git WORKTREE. A worktree has its own ephemeral checkout dir; a
+ * naive `process.cwd()`-relative `.design/STATE.md` write would land inside the
+ * throwaway worktree and get lost (or leak) when the worktree is removed. We
+ * detect the worktree, resolve the main repo root, and point artifact writes
+ * there so state survives across worktree lifecycles.
+ *
+ * Detection: `git rev-parse --git-dir` and `--git-common-dir` DIFFER inside a
+ * linked worktree (git-dir is `<main>/.git/worktrees/<name>`, common-dir is
+ * `<main>/.git`); in the main checkout they are EQUAL. The main repo root is the
+ * PARENT of the common git dir.
+ *
+ * Pure + dependency-free except for spawning `git`, and the `git` call is fully
+ * injectable via an `exec` parameter so tests run without a real worktree. NEVER
+ * throws: when git is unavailable (no repo, git not on PATH) every resolver
+ * degrades gracefully to the caller's `cwd`, so non-git consumers are unaffected.
+ *
+ * No top-level `Date.now()` / `Math.random()` — the only module-level mutable
+ * state is the one-shot `noticeOnce` flag, intentionally per-process.
+ *
+ * CommonJS so it ships in the npm package and loads from `.cjs` callers and the
+ * dual-mode `.ts`/`.js` MCP servers alike.
+ */
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+/**
+ * Default `exec`: synchronously run `git <args...>` in `cwd` and return its
+ * trimmed stdout. Returns null on ANY failure (git missing, non-zero exit,
+ * not a repo) so callers can treat "no git" as "not a worktree".
+ *
+ * @param {string[]} args git arguments, e.g. ['rev-parse', '--git-dir']
+ * @param {string} cwd working directory to run git in
+ * @returns {string | null} trimmed stdout, or null on failure
+ */
+function defaultExec(args, cwd) {
+  try {
+    const res = spawnSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (!res || res.status !== 0 || typeof res.stdout !== 'string') return null;
+    const out = res.stdout.trim();
+    return out.length ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalize an injectable `exec` into a uniform `(args, cwd) => string|null`.
+ *
+ * The injectable form callers/tests pass is `(cmd, args) => string` where `cmd`
+ * is the literal `'git'` and `args` is the argv array (matching the prompt
+ * contract). We adapt it here and swallow throws into null so a test exec that
+ * throws models "git unavailable" exactly like the real one returning null.
+ *
+ * @param {undefined | ((cmd: string, args: string[]) => string)} exec
+ * @param {string} cwd
+ * @returns {(args: string[]) => string | null}
+ */
+function makeRunner(exec, cwd) {
+  if (typeof exec === 'function') {
+    return (args) => {
+      try {
+        const out = exec('git', args);
+        if (typeof out !== 'string') return null;
+        const trimmed = out.trim();
+        return trimmed.length ? trimmed : null;
+      } catch {
+        return null;
+      }
+    };
+  }
+  return (args) => defaultExec(args, cwd);
+}
+
+/**
+ * Resolve the absolute git-dir and git-common-dir for `cwd`.
+ *
+ * `git rev-parse` prints these relative to `cwd` in some setups and absolute in
+ * others; we resolve both against `cwd` so comparison and parent-of logic is
+ * always done on absolute, normalized paths.
+ *
+ * @returns {{ gitDir: string, commonDir: string } | null} null when not a repo
+ */
+function gitDirs(run, cwd) {
+  const gitDirRaw = run(['rev-parse', '--git-dir']);
+  if (gitDirRaw == null) return null;
+  const commonDirRaw = run(['rev-parse', '--git-common-dir']);
+  if (commonDirRaw == null) return null;
+  const gitDir = path.resolve(cwd, gitDirRaw);
+  const commonDir = path.resolve(cwd, commonDirRaw);
+  return { gitDir, commonDir };
+}
+
+/**
+ * True when `cwd` sits inside a linked git WORKTREE (git-dir !== git-common-dir).
+ * False in the main checkout, and false (degrade gracefully) when git is
+ * unavailable or `cwd` is not inside any repo.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {(cmd: string, args: string[]) => string} [exec] injectable git runner
+ * @returns {boolean}
+ */
+function isWorktree(cwd = process.cwd(), exec) {
+  const run = makeRunner(exec, cwd);
+  const dirs = gitDirs(run, cwd);
+  if (dirs == null) return false;
+  return dirs.gitDir !== dirs.commonDir;
+}
+
+/**
+ * Resolve the MAIN repo root for `cwd`.
+ *
+ *   - In a worktree: the parent of the git-common-dir (`<main>/.git` -> `<main>`).
+ *   - In the main checkout: the toplevel (`git rev-parse --show-toplevel`).
+ *   - git unavailable / not a repo: falls back to `path.resolve(cwd)`.
+ *
+ * Never throws.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {(cmd: string, args: string[]) => string} [exec] injectable git runner
+ * @returns {string} absolute main repo root
+ */
+function resolveRepoRoot(cwd = process.cwd(), exec) {
+  const run = makeRunner(exec, cwd);
+  const dirs = gitDirs(run, cwd);
+  if (dirs == null) {
+    // Not a repo / git unavailable — degrade to cwd.
+    return path.resolve(cwd);
+  }
+  if (dirs.gitDir !== dirs.commonDir) {
+    // Worktree: the main repo root is the parent of the common `.git` dir.
+    // common-dir is typically `<main>/.git`; its dirname is `<main>`. Guard the
+    // (unusual) bare-repo case where common-dir has no `.git` basename by only
+    // climbing when the basename looks like a git dir.
+    const base = path.basename(dirs.commonDir);
+    if (base === '.git' || base.endsWith('.git')) {
+      return path.dirname(dirs.commonDir);
+    }
+    // Bare/relocated git dir: best effort — fall through to toplevel below.
+  }
+  // Main checkout (or odd common-dir shape): prefer the toplevel.
+  const top = run(['rev-parse', '--show-toplevel']);
+  if (top != null) return path.resolve(cwd, top);
+  // Last resort: parent of the git dir, else cwd.
+  const base = path.basename(dirs.commonDir);
+  if (base === '.git' || base.endsWith('.git')) return path.dirname(dirs.commonDir);
+  return path.resolve(cwd);
+}
+
+/**
+ * Absolute `.design` root in the MAIN repo (worktree-safe).
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {(cmd: string, args: string[]) => string} [exec]
+ * @returns {string}
+ */
+function resolveDesignRoot(cwd = process.cwd(), exec) {
+  return path.join(resolveRepoRoot(cwd, exec), '.design');
+}
+
+/**
+ * Absolute `.planning` root in the MAIN repo (worktree-safe).
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {(cmd: string, args: string[]) => string} [exec]
+ * @returns {string}
+ */
+function resolvePlanningRoot(cwd = process.cwd(), exec) {
+  return path.join(resolveRepoRoot(cwd, exec), '.planning');
+}
+
+/** One-shot guard so the redirect notice prints at most once per process. */
+let NOTICE_EMITTED = false;
+
+/**
+ * Emit a single one-line stderr notice — exactly once per process — announcing
+ * that worktree redirection is in effect. Subsequent calls are no-ops, so a
+ * caller can invoke this freely on every redirect without spamming stderr.
+ *
+ * @param {string} targetRoot the resolved MAIN repo root writes are redirected to
+ * @param {(line: string) => void} [write] injectable sink (default process.stderr)
+ * @returns {boolean} true if THIS call emitted the notice, false if already emitted
+ */
+function noticeOnce(targetRoot, write) {
+  if (NOTICE_EMITTED) return false;
+  NOTICE_EMITTED = true;
+  const line = `worktree detected -> .design/.planning redirected to ${targetRoot}\n`;
+  try {
+    if (typeof write === 'function') {
+      write(line);
+    } else {
+      process.stderr.write(line);
+    }
+  } catch {
+    /* never let a logging failure break a write path */
+  }
+  return true;
+}
+
+/** Test-only: reset the one-shot notice flag. Not part of the public contract. */
+function _resetNoticeForTests() {
+  NOTICE_EMITTED = false;
+}
+
+module.exports = {
+  isWorktree,
+  resolveRepoRoot,
+  resolveDesignRoot,
+  resolvePlanningRoot,
+  noticeOnce,
+  _resetNoticeForTests,
+};

package/sdk/mcp/gdd-state/server.js

@@ -35,7 +35,7 @@ __export(server_exports, {
   runStdio: () => runStdio
 });
 module.exports = __toCommonJS(server_exports);
-var import_node_fs4 = require("node:fs");
+var import_node_fs5 = require("node:fs");
 var import_node_path3 = require("node:path");
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
@@ -1799,6 +1799,8 @@ async function transition(path2, toStage) {
 
 // sdk/mcp/gdd-state/tools/shared.ts
 var import_node_path2 = __toESM(require("node:path"));
+var import_node_fs4 = require("node:fs");
+var import_node_module2 = require("node:module");
 
 // sdk/event-stream/index.ts
 var import_node_os2 = require("node:os");
@@ -2012,9 +2014,40 @@ function getSessionId() {
   if (CACHED_SESSION_ID === null) CACHED_SESSION_ID = makeSessionId();
   return CACHED_SESSION_ID;
 }
+function _findRepoRoot2() {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if ((0, import_node_fs4.existsSync)(import_node_path2.default.join(dir, "package.json"))) return dir;
+    const parent = import_node_path2.default.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+var _worktree = (() => {
+  try {
+    const root = _findRepoRoot2();
+    const candidate = import_node_path2.default.resolve(root, "scripts/lib/worktree-resolve.cjs");
+    if (!(0, import_node_fs4.existsSync)(candidate)) return null;
+    const req = (0, import_node_module2.createRequire)(import_node_path2.default.join(root, "package.json"));
+    return req(candidate);
+  } catch {
+    return null;
+  }
+})();
 function resolveStatePath() {
   const override = process.env["GDD_STATE_PATH"];
   if (typeof override !== "string" || override.length === 0) {
+    if (_worktree !== null) {
+      try {
+        const designRoot = _worktree.resolveDesignRoot();
+        if (_worktree.isWorktree()) {
+          _worktree.noticeOnce(import_node_path2.default.dirname(designRoot));
+        }
+        return import_node_path2.default.join(designRoot, "STATE.md");
+      } catch {
+      }
+    }
     return ".design/STATE.md";
   }
   if (import_node_path2.default.isAbsolute(override)) {
@@ -2734,12 +2767,12 @@ function here() {
   const entry = process.argv[1];
   if (typeof entry === "string" && entry.length > 0) {
     const entryDir = (0, import_node_path3.dirname)((0, import_node_path3.resolve)(entry));
-    if ((0, import_node_fs4.existsSync)((0, import_node_path3.join)(entryDir, "tools", "index.ts"))) {
+    if ((0, import_node_fs5.existsSync)((0, import_node_path3.join)(entryDir, "tools", "index.ts"))) {
       return entryDir;
     }
   }
   const candidate = (0, import_node_path3.resolve)(process.cwd(), expectedRel);
-  if ((0, import_node_fs4.existsSync)((0, import_node_path3.join)(candidate, "tools", "index.ts"))) {
+  if ((0, import_node_fs5.existsSync)((0, import_node_path3.join)(candidate, "tools", "index.ts"))) {
     return candidate;
   }
   return candidate;
@@ -2748,7 +2781,7 @@ function loadTools() {
   const baseDir = here();
   return TOOL_MODULES.map((m) => {
     const absPath = (0, import_node_path3.join)(baseDir, "tools", m.schemaPath);
-    const raw = (0, import_node_fs4.readFileSync)(absPath, "utf8");
+    const raw = (0, import_node_fs5.readFileSync)(absPath, "utf8");
     const parsed = JSON.parse(raw);
     const rawInput = parsed.properties?.input;
     const inputSchema = rawInput !== void 0 && typeof rawInput === "object" ? rawInput : { type: "object" };

package/sdk/mcp/gdd-state/tools/shared.ts

@@ -12,6 +12,8 @@
 // {success:false, error} — handlers never propagate exceptions."
 
 import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import {
   ValidationError,
   OperationFailedError,
@@ -50,6 +52,49 @@ export function getSessionId(): string {
   return CACHED_SESSION_ID;
 }
 
+/**
+ * Worktree redirect (Phase 49). When GDD runs inside a git WORKTREE, a naive
+ * `process.cwd()`-relative `.design/STATE.md` write lands in the ephemeral
+ * worktree and is lost when it is removed. `scripts/lib/worktree-resolve.cjs`
+ * resolves the MAIN repo root and points STATE writes there.
+ *
+ * Soft-loaded via createRequire (mirrors sdk/event-stream/writer.ts): tsc's
+ * Node16 module mode classifies this .ts as CJS output, so `import.meta` is
+ * unavailable — we anchor createRequire on the repo-root package.json found by
+ * walking up from cwd. If the helper is unreachable (a test subprocess running
+ * far above the plugin tree), every resolver degrades to a null shim and the
+ * default falls back to the legacy relative path. Production callers always run
+ * inside the plugin tree.
+ */
+interface WorktreeResolver {
+  resolveDesignRoot: (cwd?: string) => string;
+  isWorktree: (cwd?: string) => boolean;
+  noticeOnce: (targetRoot: string) => boolean;
+}
+
+function _findRepoRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+const _worktree: WorktreeResolver | null = (() => {
+  try {
+    const root = _findRepoRoot();
+    const candidate = path.resolve(root, 'scripts/lib/worktree-resolve.cjs');
+    if (!existsSync(candidate)) return null;
+    const req = createRequire(path.join(root, 'package.json'));
+    return req(candidate) as WorktreeResolver;
+  } catch {
+    return null;
+  }
+})();
+
 /**
  * Resolve the target STATE.md path from the environment, with a
  * PATH-TRAVERSAL guard (Plan 33.5-03, D-08).
@@ -69,6 +114,22 @@ export function getSessionId(): string {
 export function resolveStatePath(): string {
   const override = process.env['GDD_STATE_PATH'];
   if (typeof override !== 'string' || override.length === 0) {
+    // No override: resolve STATE.md under the worktree-aware `.design` root
+    // (Phase 49). Outside a worktree this equals the legacy `<cwd>/.design`
+    // (when cwd is the repo root) so behavior is unchanged; inside a worktree
+    // the design root points at the MAIN repo so state is not lost. The notice
+    // fires at most once per process, only on an actual worktree redirect.
+    if (_worktree !== null) {
+      try {
+        const designRoot = _worktree.resolveDesignRoot();
+        if (_worktree.isWorktree()) {
+          _worktree.noticeOnce(path.dirname(designRoot));
+        }
+        return path.join(designRoot, 'STATE.md');
+      } catch {
+        // Fall through to the legacy relative default on any resolver fault.
+      }
+    }
     return '.design/STATE.md';
   }