@hegemonart/get-design-done 1.53.0 → 1.55.0

package/scripts/lib/detect/stack.d.cts

@@ -0,0 +1,44 @@
+// scripts/lib/detect/stack.d.cts — types for detect/stack.cjs (Phase 54 DETECT-01).
+
+export interface StackEvidence {
+  ds?: string;
+  framework?: string;
+  motion?: string[];
+  note?: string;
+}
+
+export interface DetectedStack {
+  /** Detected design-system id (tailwind / shadcn / mui / ...), or null. */
+  ds: string | null;
+  /** Detected framework id (nextjs / remix / vite-react / ...), or null. */
+  framework: string | null;
+  /** Detected motion library ids (framer-motion / gsap / ...). Possibly empty. */
+  motion_libs: string[];
+  /** Per-category evidence strings (why each value was chosen). */
+  evidence: StackEvidence;
+}
+
+export interface ReadDepsResult {
+  deps: Record<string, string>;
+  present: boolean;
+  error: string | null;
+}
+
+/**
+ * Fingerprint a project's design-system / framework / motion stack. Pure,
+ * dependency-free, NEVER throws — an absent/malformed package.json yields
+ * all-null with an evidence note.
+ * @param root project directory (defaults to process.cwd()).
+ */
+export function detectStack(root?: string): DetectedStack;
+
+export function readDeps(root: string): ReadDepsResult;
+export function hasDep(deps: Record<string, string>, name: string): boolean;
+export function hasDepPrefix(deps: Record<string, string>, prefix: string): boolean;
+export function detectDs(root: string, deps: Record<string, string>): { ds: string | null; evidence: string };
+export function detectFramework(root: string, deps: Record<string, string>): { framework: string | null; evidence: string };
+export function detectMotion(deps: Record<string, string>): { motion_libs: string[]; evidence: string[] };
+export function main(argv: string[], io?: { cwd?: string; log?: (s: string) => void; err?: (s: string) => void }): number;
+export function parseArgs(argv: string[]): { root: string | null; json: boolean; pretty: boolean; help: boolean };
+export const HELP: string;
+export const SKIP_DIRS: ReadonlySet<string> | string[];

package/scripts/lib/explore-parallel-runner/index.ts

@@ -30,6 +30,12 @@ import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs'
 // way as concurrency-tuner.cjs above. Only invoked when opts.incremental.graph
 // is supplied — the default explore path never loads its ESM/TS dependencies.
 import { planIncremental } from '../mappers/incremental-discover.cjs';
+// Phase 54 (REG-01): stack detection + addendum composition. Both CJS, imported
+// the same way. The pre-spawn step (composeMapperSpecs below) calls detectStack
+// ONCE and applyAddendums per spec; both are wrapped in try/catch so a failure
+// degrades to the unmodified Phase-21 spec roster.
+import { detectStack } from '../detect/stack.cjs';
+import { applyAddendums } from '../mapper-spawn.cjs';
 
 import {
   isParallelismSafe,
@@ -105,6 +111,129 @@ export const DEFAULT_MAPPERS: readonly MapperSpec[] = Object.freeze([
   }),
 ]);
 
+// ---------------------------------------------------------------------------
+// Phase 54 (REG-01) — pre-spawn stack-addendum composition
+// ---------------------------------------------------------------------------
+
+/** Derive the agent name an addendum's composes_into list matches against. */
+function agentNameOf(spec: MapperSpec): string {
+  // Addendum composes_into uses the AGENT filename (token-mapper,
+  // component-taxonomy-mapper, motion-mapper, visual-hierarchy-mapper), not the
+  // short MapperSpec.name (token, component-taxonomy, ...). Derive it from the
+  // agentPath basename so the registry match keys line up.
+  const base = spec.agentPath
+    .replace(/\\/g, '/')
+    .split('/')
+    .pop()
+    ?.replace(/\.md$/i, '');
+  return base && base.length > 0 ? base : spec.name;
+}
+
+/**
+ * Compose stack-specific guidance into each mapper spec BEFORE spawn.
+ *
+ * Detects the project stack ONCE (detect/stack.cjs#detectStack) and, for each
+ * spec, appends the matching `type:"stack-addendum"` reference bodies to the
+ * prompt (mapper-spawn.cjs#applyAddendums, cap 1 system + 1 framework + 1
+ * motion). The match is keyed by the spec's AGENT name against the registry
+ * `composes_into` list.
+ *
+ * Contract:
+ *   * ADDITIVE + BACKWARD-COMPATIBLE: a spec with no matching addendum (or no
+ *     detected stack) is returned with a byte-for-byte unchanged prompt. When
+ *     NOTHING matches across all specs, the original `specs` array is returned
+ *     unchanged (same reference), so the Phase-21 path is identical.
+ *   * NEVER THROWS: detection / registry / file-read failures degrade to the
+ *     unmodified roster. Dispatch is never blocked by this step.
+ *   * The frozen DEFAULT_MAPPERS entries are never mutated — a spec that gains
+ *     an addendum is returned as a fresh object.
+ *
+ * @returns `{ specs, missingByMapper }` — the (possibly) recomposed roster +
+ *          a per-agent-name list of detected stack values that had NO addendum
+ *          for that mapper (drives the R6 fallback flag / health coverage row).
+ */
+function composeMapperSpecs(
+  specs: readonly MapperSpec[],
+  cwd: string,
+  addendumOpts: ExploreRunnerOptions['addendums'],
+  logger: ReturnType<typeof getLogger>,
+): { specs: readonly MapperSpec[]; missingByMapper: Record<string, string[]> } {
+  const missingByMapper: Record<string, string[]> = {};
+  const opt = addendumOpts ?? {};
+  if (opt.enabled === false) return { specs, missingByMapper };
+
+  try {
+    const root: string = typeof opt.root === 'string' ? opt.root : cwd;
+    const detect = typeof opt.detectStack === 'function' ? opt.detectStack : detectStack;
+    const stack = detect(root) as {
+      ds?: string | null;
+      framework?: string | null;
+      motion_libs?: string[];
+    } | null;
+
+    // Resolve the registry + refDir. Defaults read the shipped registry and the
+    // repo reference/ dir; tests inject both. A missing registry simply yields
+    // no matches (applyAddendums degrades to an empty block).
+    let registry: unknown = opt.registry;
+    const refDir: string =
+      typeof opt.refDir === 'string'
+        ? opt.refDir
+        : resolvePath(cwd, 'reference');
+    if (registry === undefined) {
+      try {
+        // Lazy require so the default path only touches disk when enabled.
+        const { loadRegistry } = require('../reference-registry.cjs') as {
+          loadRegistry: (o: { cwd?: string }) => unknown;
+        };
+        registry = loadRegistry({ cwd });
+      } catch {
+        registry = undefined; // no registry ⇒ no addendums (unchanged prompts)
+      }
+    }
+
+    let anyChanged = false;
+    const recomposed: MapperSpec[] = specs.map((spec) => {
+      const agentName = agentNameOf(spec);
+      // applyAddendums mutates a spec-shaped object's `.prompt` in place; we feed
+      // it a throwaway carrying the AGENT name so the registry match keys align,
+      // then copy the (possibly) augmented prompt back onto a fresh spec.
+      const carrier = { name: agentName, prompt: spec.prompt };
+      const { block, missing } = applyAddendums(carrier, stack, {
+        registry,
+        refDir,
+      }) as { block: string; used: string[]; missing: string[] };
+
+      if (Array.isArray(missing) && missing.length > 0) {
+        missingByMapper[agentName] = missing;
+      }
+      if (block && block.length > 0 && carrier.prompt !== spec.prompt) {
+        anyChanged = true;
+        return Object.freeze({ ...spec, prompt: carrier.prompt });
+      }
+      return spec;
+    });
+
+    if (anyChanged) {
+      logger.info('explore.runner.addendums_composed', {
+        mappers_augmented: recomposed.filter((s, i) => s !== specs[i]).length,
+        ds: stack && stack.ds ? stack.ds : null,
+        framework: stack && stack.framework ? stack.framework : null,
+        motion_libs:
+          stack && Array.isArray(stack.motion_libs) ? stack.motion_libs.length : 0,
+      });
+      return { specs: Object.freeze(recomposed), missingByMapper };
+    }
+    // Nothing matched — return the original roster reference unchanged.
+    return { specs, missingByMapper };
+  } catch (err) {
+    // The addendum step must NEVER break dispatch. Degrade to the unmodified
+    // roster + surface a warn for observability.
+    const message: string = err instanceof Error ? err.message : String(err);
+    logger.warn('explore.runner.addendums_failed', { message });
+    return { specs, missingByMapper };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // run — main orchestrator
 // ---------------------------------------------------------------------------
@@ -123,7 +252,7 @@ export const DEFAULT_MAPPERS: readonly MapperSpec[] = Object.freeze([
 export async function run(
   opts: ExploreRunnerOptions,
 ): Promise<ExploreRunnerResult> {
-  const specs: readonly MapperSpec[] = opts.mappers ?? DEFAULT_MAPPERS;
+  const baseSpecs: readonly MapperSpec[] = opts.mappers ?? DEFAULT_MAPPERS;
   const cwd: string = opts.cwd ?? process.cwd();
   // Phase 27.6 D-07: data-driven concurrency default. Falls back to
   // min(cpu-1, 8) when no `parallelism.verdict` events exist in
@@ -132,6 +261,14 @@ export async function run(
 
   const logger = getLogger().child('explore.runner');
 
+  // --- Phase 54 (REG-01): compose stack addendums into mapper prompts -------
+  //
+  // Fingerprint the project ONCE and append the matching stack-addendum bodies
+  // to each mapper's prompt BEFORE partitioning / spawn. ADDITIVE +
+  // backward-compatible: no detected stack / no matching addendum ⇒ `specs` is
+  // the unchanged roster reference. NEVER throws (composeMapperSpecs guards).
+  const { specs } = composeMapperSpecs(baseSpecs, cwd, opts.addendums, logger);
+
   const outputPath: string = resolvePath(cwd, '.design/DESIGN-PATTERNS.md');
 
   // --- Phase 53 (DISC-01): incremental batching ----------------------------

package/scripts/lib/explore-parallel-runner/types.ts

@@ -138,6 +138,33 @@ export interface ExploreRunnerOptions {
     /** Forwarded into classify's projectStats.thresholds. */
     readonly thresholds?: unknown;
   };
+  /**
+   * Phase 54 (REG-01) — OPTIONAL composable stack addendums. Before spawning,
+   * the runner fingerprints the project (`scripts/lib/detect/stack.cjs#detectStack`)
+   * ONCE and appends the matching `type:"stack-addendum"` reference bodies to
+   * each mapper's prompt via `scripts/lib/mapper-spawn.cjs#applyAddendums`
+   * (cap 1 design-system + 1 framework + 1 motion per spawn). The addendum is
+   * selected by the mapper's AGENT name (e.g. token-mapper) against the
+   * registry `composes_into` list.
+   *
+   * BACKWARD-COMPATIBLE + ADDITIVE: defaults ON, but a project with no
+   * detected stack (or no matching addendum) gets a byte-for-byte unchanged
+   * prompt. The whole step is wrapped in try/catch so a detection/registry
+   * failure NEVER aborts dispatch. Set `enabled: false` to opt out entirely.
+   * The `detectStack` / `registry` / `refDir` fields are test-injection seams.
+   */
+  readonly addendums?: {
+    /** Opt out of stack-addendum composition entirely. Default: enabled. */
+    readonly enabled?: boolean;
+    /** Detection root. Defaults to `cwd`. */
+    readonly root?: string;
+    /** Injected detectStack (tests). Defaults to detect/stack.cjs#detectStack. */
+    readonly detectStack?: (root: string) => unknown;
+    /** Injected registry object (tests). Defaults to reference/registry.json. */
+    readonly registry?: unknown;
+    /** Reference dir addendum paths resolve against. Defaults to repo reference/. */
+    readonly refDir?: string;
+  };
 }
 
 /**

package/scripts/lib/health-mirror/index.cjs

@@ -8,7 +8,7 @@
 // Surface:
 //   async getHealthChecks(rootDir) → { checks: HealthCheck[] }
 //
-// The 7 checks (in stable order) are:
+// The 10 checks (in stable order) are:
 //   1. claude_md            — CLAUDE.md presence
 //   2. planning_dir         — .planning/ presence
 //   3. design_dir           — .design/ presence
@@ -16,6 +16,9 @@
 //   5. issue_reporter       — kill-switch state (Plan 30-06 / D-08)
 //   6. figma_extract        — extract readiness + Free-tier signal (Plan 31-09)
 //   7. skill_discipline     — using-gdd bootstrap + SessionStart inject (Plan 32-07)
+//   8. harness_freshness    — per-harness last_verified age (Phase 44)
+//   9. stack_addendums      — Phase 54 coverage: N/M detected stacks have addendums
+//  10. dashboard_reachable  — Phase 55: bin/gdd-dashboard on disk + data plane loads
 //
 // Check 5 was added in Plan 30-06 — surfaces the report-issue kill-switch
 // (env or config disable) so users can verify why the command is
@@ -46,6 +49,22 @@
 //                                           inject-using-gdd entry)
 // status: 'ok' when ready, 'warn' otherwise. PURE read-only (rootDir-relative
 // file + JSON inspection only) — NEVER throws, NEVER networks.
+//
+// Check 10 was added in Phase 55 — surfaces whether the GDD dashboard is
+// reachable so a user running /gdd:health knows the `gdd dashboard` entrypoint
+// is wired. GRACEFUL-ABSENT by design (D-8 risk surfacing precedent): the
+// dashboard is an opt-in, read-only surface that also works via file-scrape, so
+// a missing bin or absent data plane is a 'warn' (actionable note), NEVER a
+// hard 'fail'. The status is 'ok' when BOTH the bin/gdd-dashboard trampoline
+// resolves on disk (located via a package-root walk-up — the Phase 53/54 lesson,
+// NEVER a fixed __dirname jump) AND the dashboard data plane module
+// (sdk/dashboard/data/source.cjs) loads + exposes loadDashboardModel. The detail
+// line is one of:
+//   - "dashboard: bin/gdd-dashboard present; data plane ok"
+//   - "dashboard: bin missing"                 (trampoline not on disk)
+//   - "dashboard: data plane unavailable"      (bin present, source.cjs absent)
+//   - "dashboard: bin missing; data plane unavailable"
+// PURE read-only (fs.statSync + a wrapped require) — NEVER throws, NEVER networks.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -238,6 +257,109 @@ async function getHealthChecks(rootDir) {
     checks.push({ name: 'harness_freshness', status, detail });
   }
 
+  // 9. stack_addendums — Phase 54 coverage row. Fingerprints the project
+  // (detect/stack.cjs) and reports how many DETECTED stacks (design-system +
+  // framework + motion libs) have a registered type:"stack-addendum" entry in
+  // reference/registry.json. PURE read-only (detection reads files but never
+  // networks; registry is a local JSON read). GRACEFUL-ABSENT: no detected
+  // stack -> "no stacks detected"; an unreadable registry -> "registry
+  // unavailable". status is 'ok' on full coverage or nothing-to-cover,
+  // otherwise 'warn'. NEVER throws.
+  {
+    let status = 'ok';
+    let detail;
+    try {
+      const { detectStack } = require('../detect/stack.cjs');
+      const stack = detectStack(rootDir) || { ds: null, framework: null, motion_libs: [] };
+
+      // The detected stack values to cover, paired with the category an
+      // addendum must classify into to count as coverage.
+      const wanted = [];
+      if (typeof stack.ds === 'string' && stack.ds) wanted.push({ category: 'system', key: stack.ds });
+      if (typeof stack.framework === 'string' && stack.framework) {
+        wanted.push({ category: 'framework', key: stack.framework });
+      }
+      if (Array.isArray(stack.motion_libs)) {
+        for (const m of stack.motion_libs) {
+          if (typeof m === 'string' && m) wanted.push({ category: 'motion', key: m });
+        }
+      }
+
+      if (wanted.length === 0) {
+        detail = 'stack addendums: no stacks detected';
+        status = 'ok';
+      } else {
+        // Load the registry + classify its stack-addendum entries. A missing or
+        // malformed registry counts as zero coverage (warn), never a throw.
+        let entries = [];
+        try {
+          const reg = JSON.parse(
+            fs.readFileSync(path.join(rootDir, 'reference', 'registry.json'), 'utf8')
+          );
+          entries = Array.isArray(reg.entries) ? reg.entries : [];
+        } catch {
+          entries = null; // distinguish "registry unavailable" from "zero coverage"
+        }
+
+        if (entries === null) {
+          detail = 'stack addendums: registry unavailable';
+          status = 'warn';
+        } else {
+          const { classifyEntry } = require('../mapper-spawn.cjs');
+          // Build the set of {category|key} an addendum exists for.
+          const covered = new Set();
+          for (const e of entries) {
+            if (!e || e.type !== 'stack-addendum') continue;
+            const { category, key } = classifyEntry(e);
+            if (category && key) covered.add(category + '|' + key);
+          }
+          const have = wanted.filter((w) => covered.has(w.category + '|' + String(w.key).toLowerCase())).length;
+          const total = wanted.length;
+          status = have >= total ? 'ok' : 'warn';
+          detail = `stack addendums: ${have}/${total} detected stacks have addendums`;
+        }
+      }
+    } catch {
+      // Absolute safety net — the health probe must never crash on this check.
+      status = 'warn';
+      detail = 'stack addendums: unavailable';
+    }
+    checks.push({ name: 'stack_addendums', status, detail });
+  }
+
+  // 10. dashboard_reachable — Phase 55. GRACEFUL-ABSENT: reports whether the
+  // GDD dashboard entrypoint is wired (bin/gdd-dashboard on disk) AND its data
+  // plane module loads. NEVER 'fail' — a missing bin is a 'warn' note because
+  // the dashboard is opt-in and also works via file-scrape. PURE read-only
+  // (fs.statSync + a wrapped require); NEVER throws, NEVER networks.
+  {
+    let status;
+    let detail;
+    try {
+      const gddRoot = resolveDashboardRoot(rootDir);
+      const binPresent = dashboardBinResolves(gddRoot);
+      const dataPlaneOk = dashboardDataPlaneLoads(gddRoot);
+      if (binPresent && dataPlaneOk) {
+        status = 'ok';
+        detail = 'dashboard: bin/gdd-dashboard present; data plane ok';
+      } else {
+        status = 'warn';
+        if (!binPresent && !dataPlaneOk) {
+          detail = 'dashboard: bin missing; data plane unavailable';
+        } else if (!binPresent) {
+          detail = 'dashboard: bin missing';
+        } else {
+          detail = 'dashboard: data plane unavailable';
+        }
+      }
+    } catch {
+      // Absolute safety net — the health probe must never crash on this check.
+      status = 'warn';
+      detail = 'dashboard: unavailable';
+    }
+    checks.push({ name: 'dashboard_reachable', status, detail });
+  }
+
   return { checks };
 }
 
@@ -330,4 +452,99 @@ function figmaVariablesBlockedLocally(rootDir) {
   }
 }
 
+/**
+ * Walk UP from `startDir` to the GDD package root (the first ancestor whose
+ * package.json `name` is the GDD package). This mirrors the Phase 53/54 lesson
+ * (sdk/dashboard/data/_pkg-root.cjs): NEVER resolve a cross-tree sibling via a
+ * fixed __dirname-relative jump. The shipped package name is scoped
+ * ("@hegemonart/get-design-done"); dev/self-host/fixture roots may use the bare
+ * "get-design-done" — both match. Bounded climb; defensive. Returns null if no
+ * GDD root marker is found.
+ *
+ * @param {string} startDir
+ * @returns {string|null} absolute package-root dir, or null
+ */
+function findGddPackageRoot(startDir) {
+  try {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < 12; i++) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        if (pkg && typeof pkg.name === 'string') {
+          if (pkg.name === 'get-design-done' || /\/get-design-done$/.test(pkg.name)) {
+            return dir;
+          }
+        }
+      } catch {
+        // no/garbage package.json at this level — keep climbing
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the AUTHORITATIVE GDD package root for the dashboard probe, given the
+ * project root being health-checked. Resolution (D-7 walk-up, never a fixed
+ * __dirname jump):
+ *   - If `rootDir` itself sits inside a GDD checkout (dev / self-host / a
+ *     hermetic fixture that declares the GDD name), THAT root is authoritative —
+ *     its own bin/ + sdk/dashboard/ are the truth. No cross-root fallback (so a
+ *     fixture is hermetic + deterministic regardless of the shipped tree).
+ *   - Otherwise `rootDir` is an unrelated CONSUMER project (no GDD marker); the
+ *     dashboard ships alongside THIS module, so walk up from __dirname.
+ * Returns null only if neither resolves (degrades the check to 'warn').
+ *
+ * @param {string} rootDir project root passed to getHealthChecks
+ * @returns {string|null}
+ */
+function resolveDashboardRoot(rootDir) {
+  const fromRoot = findGddPackageRoot(rootDir);
+  if (fromRoot) return fromRoot;
+  return findGddPackageRoot(__dirname);
+}
+
+/**
+ * Does the bin/gdd-dashboard trampoline resolve on disk under the authoritative
+ * GDD root? (Phase 55, check 10.) `fs.statSync` follows symlinks, so an npm
+ * bin-linked trampoline (a symlink resolving to a file) counts as present. PURE
+ * read-only; NEVER throws.
+ *
+ * @param {string} gddRoot authoritative GDD root (or null)
+ * @returns {boolean} true iff bin/gdd-dashboard is present on disk
+ */
+function dashboardBinResolves(gddRoot) {
+  if (!gddRoot) return false;
+  try {
+    return fs.statSync(path.join(gddRoot, 'bin', 'gdd-dashboard')).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Does the dashboard data plane module load + expose loadDashboardModel under
+ * the authoritative GDD root? (Phase 55, check 10.) The data plane is
+ * sdk/dashboard/data/source.cjs (R1 — the in-process shared-lib read surface the
+ * dashboard renders). A missing module or a require error degrades to false
+ * (→ 'warn'), NEVER throws.
+ *
+ * @param {string} gddRoot authoritative GDD root (or null)
+ * @returns {boolean} true iff source.cjs loads and exports loadDashboardModel
+ */
+function dashboardDataPlaneLoads(gddRoot) {
+  if (!gddRoot) return false;
+  try {
+    const mod = require(path.join(gddRoot, 'sdk', 'dashboard', 'data', 'source.cjs'));
+    return !!(mod && typeof mod.loadDashboardModel === 'function');
+  } catch {
+    return false;
+  }
+}
+
 module.exports = { getHealthChecks };

package/scripts/lib/manifest/skills.json

@@ -260,6 +260,14 @@
       "user_invocable": true,
       "registered_in_phase": "52"
     },
+    {
+      "name": "new-addendum",
+      "description": "Scaffolds a new Phase-54 composable reference addendum for a design-system, framework, or motion library: validates the kind and the slug, defaults composes_into by kind, and writes a 4-section skeleton at reference/{systems|frameworks|motion}/<name>.md from the pure generator. Use when adding stack-specific guidance that an explore mapper should compose at spawn time and you want the frontmatter, the composes_into wiring, and the mandatory sections correct from the first commit. Activates for requests involving authoring a reference addendum, adding stack-specific mapper guidance, scaffolding a systems or frameworks or motion doc, or registering a new design-system.",
+      "argument_hint": "<kind> <name>",
+      "tools": "Read, Write, Bash, AskUserQuestion",
+      "user_invocable": true,
+      "registered_in_phase": "54"
+    },
     {
       "name": "new-cycle",
       "description": "Start a new design cycle. Creates cycle scope in STATE.md, initializes .design/CYCLES.md entry. Each cycle has its own goal and tracks its own decisions/tasks/pipeline runs.",