@hegemonart/get-design-done 1.47.0 → 1.49.0

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';
   }
 

package/skills/brief/SKILL.md

@@ -108,6 +108,23 @@ Run this final spec-quality pass over `.design/BRIEF.md` before the brief→expl
 - Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
 - Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
 
+## Optional brief audit (non-blocking)
+
+Before the gate, you MAY spawn `agents/brief-auditor.md` via `Task` to grade the brief against the five
+brief anti-patterns (vague verbs, missing audience, immeasurable success criteria, scope creep, missing
+anti-goals). The auditor reads `.design/BRIEF.md` plus `reference/brief-quality-rubric.md` and writes
+advisory findings to `.design/BRIEF-AUDIT.md`. This step is advisory and MUST NOT block the brief to
+explore transition.
+
+If the auditor reports one or more fired anti-patterns, surface a single-line pointer to the user:
+
+```
+Brief audit flagged N issue(s) - run /gdd:discuss brief to refine, or proceed to explore.
+```
+
+The user decides. Proceeding to explore with a flagged brief is allowed; the pointer is a nudge, not a gate.
+If the auditor reports no fired anti-patterns, or you skip the audit, continue to the gate unchanged.
+
 <HARD-GATE>
 Do NOT transition to explore (or invoke `/gdd:explore`) until the brief artifact (default `.design/BRIEF.md`) is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
 </HARD-GATE>

package/skills/quality-gate/SKILL.md

@@ -39,7 +39,7 @@ Read once at start from `.design/config.json` (all optional; defaults in parens)
 Stop at the first tier that produces ≥ 1 command:
 
 1. **Authoritative config.** If `.design/config.json` has `quality_gate.commands` non-empty, use verbatim.
-2. **Auto-detect from `package.json#scripts`** - match against allowlist: `lint`, `typecheck`, `tsc` (only if `typecheck` absent), `test`, `chromatic`, `test:visual`, `lint:design` (Phase 41 - the `gdd-detect` deterministic anti-pattern gate, alongside `axe`/`pa11y`/`lighthouse`). Exclude by name: `test:e2e`, `test:integration` (if separate `test`), anything starting `dev:`, `build:`, `start:`. Run via `npm run <name>` unless `quality_gate.package_manager` overrides.
+2. **Auto-detect from `package.json#scripts`** - match against allowlist: `lint`, `typecheck`, `tsc` (only if `typecheck` absent), `test`, `chromatic`, `test:visual`, `lint:design` (Phase 41 - the `gdd-detect` deterministic anti-pattern gate), and the accessibility scripts `axe`, `pa11y`, `lighthouse`, `eslint-plugin-jsx-a11y` (or a script named `jsx-a11y`) which classify into the `a11y` bucket. Exclude by name: `test:e2e`, `test:integration` (if separate `test`), anything starting `dev:`, `build:`, `start:`. Run via `npm run <name>` unless `quality_gate.package_manager` overrides.
 3. **Skip with notice.** Emit `quality_gate_skipped` (Step 6) and write a `<run/>` with `status="skipped"`. Verify treats skipped as non-blocking.
 
 ## Step 2 - Parallel run
@@ -48,7 +48,7 @@ Emit `quality_gate_started`. Spawn each command in a separate `Bash`; collect `{
 
 ## Step 3 - Classification
 
-Spawn `quality-gate-runner` agent via `Task` with payload `{outputs: [{command, exit_code, stderr}, ...]}`. Agent returns `{status: "pass"|"fail", classified_failures: {lint, type, test, visual}}`. `pass` → Step 5. `fail` → Step 4.
+Spawn `quality-gate-runner` agent via `Task` with payload `{outputs: [{command, exit_code, stderr}, ...]}`. Agent returns `{status: "pass"|"fail", classified_failures: {lint, type, test, visual, a11y}}`. The `a11y` bucket groups accessibility failures from axe / pa11y / lighthouse / jsx-a11y. `pass` → Step 5. `fail` → Step 4.
 
 ## Step 4 - Fix loop (D-08)