@hegemonart/get-design-done 1.52.0 → 1.54.0

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

@@ -26,6 +26,16 @@ import { resolve as resolvePath } from 'node:path';
 
 import { getLogger } from '../logger/index.ts';
 import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs';
+// Phase 53 (DISC-01): the incremental batching composer. CJS, imported the same
+// 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,
@@ -101,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
 // ---------------------------------------------------------------------------
@@ -119,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
@@ -128,8 +261,68 @@ 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 ----------------------------
+  //
+  // ONLY runs when a Phase-52 graph is supplied. Groups the graph into Louvain
+  // community batches, runs the change classifier against the prior fingerprint
+  // snapshot, and elects which batches to re-map (SKIP=0, PARTIAL=affected,
+  // FULL=all). The result rides on `batching`; the spec roster + rolling
+  // semaphore below are UNCHANGED. Backward-compatible: absent graph ⇒ undefined
+  // batching ⇒ the Phase-21 path is byte-for-byte the same. Never throws —
+  // batching is advisory metadata, and a planning failure must not abort mappers.
+  let batching: ExploreRunnerResult['batching'] = undefined;
+  if (opts.incremental && opts.incremental.graph !== undefined && opts.incremental.graph !== null) {
+    try {
+      const plan = await planIncremental({
+        graph: opts.incremental.graph,
+        prevFingerprints: opts.incremental.prevFingerprints,
+        opts: {
+          ...(opts.incremental.forceFull !== undefined ? { forceFull: opts.incremental.forceFull } : {}),
+          ...(opts.incremental.computeBatchesOpts !== undefined ? { computeBatchesOpts: opts.incremental.computeBatchesOpts } : {}),
+          ...(opts.incremental.neighborCap !== undefined ? { neighborCap: opts.incremental.neighborCap } : {}),
+          ...(opts.incremental.thresholds !== undefined ? { thresholds: opts.incremental.thresholds } : {}),
+        },
+      });
+      batching = Object.freeze({
+        action: plan.action,
+        method: plan.method,
+        modularity: plan.modularity,
+        batches: Object.freeze(plan.batches.map((b: { id: string; members: string[]; mergeable: boolean; kind: string; source: string }) => Object.freeze({
+          id: b.id,
+          members: Object.freeze([...b.members]),
+          mergeable: b.mergeable,
+          kind: b.kind,
+          source: b.source,
+        }))),
+        batchesToMap: Object.freeze(plan.batchesToMap.map((b: { id: string }) => b.id)),
+        neighborMaps: Object.freeze({ ...plan.neighborMaps }),
+        classification: Object.freeze({ ...plan.classification }),
+      });
+      logger.info('explore.runner.batching', {
+        action: plan.action,
+        method: plan.method,
+        batch_count: plan.batches.length,
+        batches_to_map: plan.batchesToMap.length,
+        structural_count: plan.classification.structuralCount,
+      });
+    } catch (err) {
+      // Planning failure degrades to "no batching" — the mappers still run.
+      const message: string = err instanceof Error ? err.message : String(err);
+      logger.warn('explore.runner.batching_failed', { message });
+      batching = undefined;
+    }
+  }
+
   logger.info('explore.runner.started', {
     mapper_count: specs.length,
     concurrency,
@@ -154,6 +347,7 @@ export async function run(
       parallel_count: 0,
       serial_count: 0,
       total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      ...(batching !== undefined ? { batching } : {}),
     });
   }
 
@@ -294,5 +488,6 @@ export async function run(
       output_tokens: totalOutput,
       usd_cost: totalCost,
     },
+    ...(batching !== undefined ? { batching } : {}),
   });
 }

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

@@ -109,6 +109,62 @@ export interface ExploreRunnerOptions {
   readonly pollIntervalMs?: number;
   /** Override the file-watch timeout (ms). Default 600_000 (10 min). */
   readonly timeoutMs?: number;
+  /**
+   * Phase 53 (DISC-01) — OPTIONAL incremental batching. When supplied with a
+   * Phase-52 DesignContext `graph`, the runner runs the change classifier
+   * (`scripts/lib/mappers/incremental-discover.cjs#planIncremental`) FIRST,
+   * groups the graph into Louvain community batches, attaches a per-batch
+   * neighborMap sidecar, and dispatches only the batches the classifier elects
+   * to re-map (SKIP=0, PARTIAL=affected, FULL=all). The mapper SPEC roster is
+   * unchanged — batching is metadata threaded onto the result so the explore
+   * stage can scope each mapper to its community; the rolling semaphore still
+   * spawns the spec roster at the tuned concurrency.
+   *
+   * BACKWARD-COMPATIBLE: when `incremental` is absent (or `graph` is missing),
+   * the runner behaves EXACTLY as before — no batching, no classifier, the
+   * Phase-21 partition-then-spawn path runs untouched.
+   */
+  readonly incremental?: {
+    /** Phase-52 DesignContext graph ({ nodes, edges }). Required to batch. */
+    readonly graph: unknown;
+    /** Prior fingerprint snapshot (store.readCurrent().fingerprints). Absent ⇒ bootstrap ⇒ FULL. */
+    readonly prevFingerprints?: unknown;
+    /** The `--full` opt-out: force a FULL re-map regardless of the classifier. */
+    readonly forceFull?: boolean;
+    /** Forwarded to computeBatches (resolution, maxCommunitySize, configCwd, …). */
+    readonly computeBatchesOpts?: unknown;
+    /** buildNeighborMap cap (default 50). */
+    readonly neighborCap?: number;
+    /** 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;
+  };
 }
 
 /**
@@ -136,4 +192,33 @@ export interface ExploreRunnerResult {
     readonly output_tokens: number;
     readonly usd_cost: number;
   };
+  /**
+   * Phase 53 (DISC-01) — present ONLY when `ExploreRunnerOptions.incremental`
+   * was supplied. Carries the classifier verdict + the community batch plan so
+   * the explore stage can scope each mapper to its community and skip re-mapping
+   * unchanged batches. Absent (undefined) on the backward-compatible default
+   * path — existing consumers that never set `incremental` never see this key.
+   */
+  readonly batching?: {
+    /** SKIP | PARTIAL_UPDATE | ARCHITECTURE_UPDATE | FULL_UPDATE (post `--full`). */
+    readonly action: string;
+    /** Batching method actually used. */
+    readonly method: 'louvain' | 'count-fallback';
+    /** Modularity of the Louvain partition (null on the count-fallback). */
+    readonly modularity: number | null;
+    /** Every community batch (opaque ids + members). */
+    readonly batches: ReadonlyArray<{
+      readonly id: string;
+      readonly members: readonly string[];
+      readonly mergeable: boolean;
+      readonly kind: string;
+      readonly source: string;
+    }>;
+    /** The batch ids elected for re-map this cycle (SKIP ⇒ empty). */
+    readonly batchesToMap: readonly string[];
+    /** Per-batch neighborMap sidecar, keyed by batch id (selected batches only). */
+    readonly neighborMaps: Readonly<Record<string, unknown>>;
+    /** The change classifier's full result (structuralCount, pct, hints, reason, …). */
+    readonly classification: Readonly<Record<string, unknown>>;
+  };
 }

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 9 checks (in stable order) are:
 //   1. claude_md            — CLAUDE.md presence
 //   2. planning_dir         — .planning/ presence
 //   3. design_dir           — .design/ presence
@@ -16,6 +16,8 @@
 //   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
 //
 // 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
@@ -238,6 +240,76 @@ 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 });
+  }
+
   return { checks };
 }
 

package/scripts/lib/manifest/skills.json

@@ -135,7 +135,7 @@
       "name": "discover",
       "frontmatter_name": "discover",
       "description": "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after {{command_prefix}}scan when a fast-path context build is wanted instead of the full {{command_prefix}}explore. Activates for requests involving detecting an existing design system, inventorying tokens and components, or onboarding a brownfield repo.",
-      "argument_hint": "[--auto]",
+      "argument_hint": "[--auto] [--incremental] [--full]",
       "user_invocable": true
     },
     {
@@ -153,7 +153,7 @@
     {
       "name": "explore",
       "description": "Stage 2 of 5 - unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after {{command_prefix}}brief to map the existing system and lock decisions before planning. Activates for requests involving researching design direction, gathering references, or exploring visual options.",
-      "argument_hint": "[--skip-interview] [--skip-scan]",
+      "argument_hint": "[--skip-interview] [--skip-scan] [--incremental] [--full]",
       "tools": "Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__probe_connections, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__add_decision",
       "next_skills": [
         "plan"
@@ -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.",