@hegemonart/get-design-done 1.53.0 → 1.54.0

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 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

@@ -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.",

package/scripts/lib/mapper-spawn.cjs

@@ -0,0 +1,257 @@
+'use strict';
+// scripts/lib/mapper-spawn.cjs - Phase 54 (Composable Reference Addendums), executor B (COMP-01).
+//
+// Pre-spawn composition step for the explore mappers. Given a mapper name + a
+// detected stack fingerprint, select the matching stack-addendum registry
+// entries, read their bodies from the reference dir, and concat them into a
+// single "## Stack-specific guidance" block that the runner appends to
+// spec.prompt BEFORE spawnMapper (the agent bodies are NOT edited; addendums
+// ride in spec.prompt).
+//
+// Design notes:
+//   * PURE w.r.t. its inputs: takes a stack OBJECT (does NOT import
+//     detect/stack.cjs - independent of executor A) and an explicit registry
+//     object + refDir. Reads addendum file bodies via node:fs only.
+//   * DEP-FREE (node:fs + node:path only) and NEVER throws. An absent
+//     registry, an entry with no readable file, or a malformed stack all
+//     degrade to an empty block; detected-but-unmatched stacks land in
+//     `missing` so the runner can raise the fallback flag (R6).
+//   * CAP 3 per spawn: at most one DS + one framework + one motion addendum.
+//     A 4th category (or a second entry in the same category) is ignored.
+//
+// Matching rule (so executor F wires it + executors C/D/E name addendums
+// consistently): each stack-addendum entry resolves to a {category, key}:
+//   - category: explicit entry.kind / entry.category if present
+//       ('system'|'framework'|'motion'), else inferred from the path dir
+//       (reference/systems/* -> 'system', reference/frameworks/* ->
+//       'framework', reference/motion/* -> 'motion').
+//   - key: explicit entry.stack if present, else the path basename without
+//       '.md', else the trailing '-'-segment of entry.name. Compared
+//       case-insensitively.
+//   The detected stack supplies the values to match:
+//     stack.ds          matches a 'system'   addendum whose key === ds
+//     stack.framework   matches a 'framework' addendum whose key === framework
+//     stack.motion_libs matches a 'motion'    addendum whose key is in the list
+//   The first matching entry per (category, value) wins; later duplicates are
+//   skipped. This keeps the cap at 1+1+1 = 3 without any category priority math.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BLOCK_HEADER = '## Stack-specific guidance';
+const ADDENDUM_SEPARATOR = '\n\n---\n\n';
+
+// Map a detected-stack field onto the addendum category it selects from.
+// Order is the canonical 1 DS + 1 framework + 1 motion fill order.
+const CATEGORY_ORDER = ['system', 'framework', 'motion'];
+
+/** Lowercase + trim a value to a comparable key, or '' for non-strings. */
+function normKey(value) {
+  return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+
+/** Path basename without a trailing `.md` (forward-slash + back-slash safe). */
+function baseNameNoExt(p) {
+  if (typeof p !== 'string' || p.length === 0) return '';
+  const tail = p.replace(/\\/g, '/').split('/').pop() || '';
+  return tail.replace(/\.md$/i, '');
+}
+
+/**
+ * Classify a stack-addendum registry entry into { category, key }.
+ * `category` is one of CATEGORY_ORDER or null when it cannot be determined;
+ * `key` is the normalized stack identifier ('' when absent).
+ */
+function classifyEntry(entry) {
+  // Category: explicit kind/category wins, else infer from the path directory.
+  let category = null;
+  const explicitKind = normKey(entry.kind || entry.category);
+  if (explicitKind === 'system' || explicitKind === 'ds' || explicitKind === 'design-system') {
+    category = 'system';
+  } else if (explicitKind === 'framework') {
+    category = 'framework';
+  } else if (explicitKind === 'motion') {
+    category = 'motion';
+  } else if (typeof entry.path === 'string') {
+    const p = entry.path.replace(/\\/g, '/');
+    if (/(^|\/)reference\/systems\//i.test(p) || /(^|\/)systems\//i.test(p)) category = 'system';
+    else if (/(^|\/)reference\/frameworks\//i.test(p) || /(^|\/)frameworks\//i.test(p)) category = 'framework';
+    else if (/(^|\/)reference\/motion\//i.test(p) || /(^|\/)motion\//i.test(p)) category = 'motion';
+  }
+
+  // Key: explicit `stack` field wins, else path basename, else name tail.
+  let key = normKey(entry.stack);
+  if (key === '') key = normKey(baseNameNoExt(entry.path));
+  if (key === '') {
+    // Fall back to the trailing '-'-segment of the entry name
+    // (e.g. "addendum-system-tailwind" -> "tailwind").
+    const nameParts = normKey(entry.name).split('-').filter(Boolean);
+    key = nameParts.length > 0 ? nameParts[nameParts.length - 1] : '';
+  }
+
+  return { category, key };
+}
+
+/** True when `entry` is a stack-addendum that composes into `mapperName`. */
+function composesInto(entry, mapperName) {
+  if (!entry || entry.type !== 'stack-addendum') return false;
+  const list = entry.composes_into;
+  if (!Array.isArray(list)) return false;
+  return list.some((m) => normKey(m) === normKey(mapperName));
+}
+
+/**
+ * Read an addendum body from disk. Returns the trimmed file contents, or null
+ * when the file is missing / unreadable / empty. `entry.path` is resolved
+ * relative to `refDir` when it is not already absolute; a leading
+ * `reference/` segment is tolerated so registry paths (which are repo-root
+ * relative, e.g. "reference/systems/tailwind.md") resolve against a refDir
+ * that already points at the reference dir.
+ */
+function readAddendumBody(entry, refDir) {
+  if (typeof entry.path !== 'string' || entry.path.length === 0) return null;
+  const rel = entry.path.replace(/\\/g, '/');
+  const candidates = [];
+  if (path.isAbsolute(rel)) {
+    candidates.push(rel);
+  } else {
+    candidates.push(path.resolve(refDir, rel));
+    // refDir may itself be the `reference/` dir; strip a redundant leading
+    // `reference/` so "reference/systems/x.md" still resolves.
+    const stripped = rel.replace(/^reference\//i, '');
+    if (stripped !== rel) candidates.push(path.resolve(refDir, stripped));
+  }
+  for (const abs of candidates) {
+    let body;
+    try {
+      body = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    const trimmed = body.replace(/\s+$/, '').replace(/^/, '');
+    if (trimmed.trim().length > 0) return trimmed;
+  }
+  return null;
+}
+
+/**
+ * Compose the stack-specific guidance block for one mapper.
+ *
+ * @param {string} mapperName  the mapper the addendums must compose into
+ *                             (e.g. "token-mapper").
+ * @param {{ds?: string|null, framework?: string|null, motion_libs?: string[]}} stack
+ *                             the detected stack fingerprint (executor A shape).
+ *                             Null / undefined / {} -> empty block.
+ * @param {{registry?: object, refDir?: string, cap?: number}} [opts]
+ *        - registry: the parsed reference/registry.json object ({ entries: [] }).
+ *        - refDir:   directory addendum `path`s resolve against (repo root or
+ *                    the reference/ dir).
+ *        - cap:      max addendums in the block (default 3).
+ * @returns {{block: string, used: string[], missing: string[]}}
+ *        - block:   "## Stack-specific guidance" text (incl. trailing bodies),
+ *                   or '' when nothing matched.
+ *        - used:    names (or path basenames) of the addendums included, in
+ *                   system -> framework -> motion order.
+ *        - missing: detected stack values that had NO matching addendum, in the
+ *                   same order (drives the fallback flag).
+ */
+function composeAddendums(mapperName, stack, opts) {
+  const used = [];
+  const missing = [];
+  const empty = () => ({ block: '', used, missing });
+
+  const o = opts || {};
+  const cap = Number.isInteger(o.cap) && o.cap >= 0 ? o.cap : 3;
+  const refDir = typeof o.refDir === 'string' && o.refDir.length > 0 ? o.refDir : process.cwd();
+
+  if (!stack || typeof stack !== 'object' || cap === 0) return empty();
+
+  const registry = o.registry;
+  const entries = registry && Array.isArray(registry.entries) ? registry.entries : [];
+
+  // The detected value we want to match, per category.
+  const detected = {
+    system: normKey(stack.ds),
+    framework: normKey(stack.framework),
+    // motion is a list; take the first non-empty entry (cap allows only one
+    // motion addendum, so the leading detected lib wins).
+    motion: Array.isArray(stack.motion_libs)
+      ? normKey(stack.motion_libs.find((m) => normKey(m) !== ''))
+      : '',
+  };
+
+  // Pre-classify candidate entries (only those composing into this mapper).
+  const candidates = [];
+  for (const entry of entries) {
+    if (!composesInto(entry, mapperName)) continue;
+    const { category, key } = classifyEntry(entry);
+    if (category === null || key === '') continue;
+    candidates.push({ entry, category, key });
+  }
+
+  const bodies = [];
+  for (const category of CATEGORY_ORDER) {
+    if (used.length >= cap) break;
+    const want = detected[category];
+    if (want === '') continue; // nothing detected in this category
+
+    const hit = candidates.find((c) => c.category === category && c.key === want);
+    if (!hit) {
+      // Detected this stack but no addendum registered for it -> fallback flag.
+      missing.push(want);
+      continue;
+    }
+    const body = readAddendumBody(hit.entry, refDir);
+    if (body === null) {
+      // Entry exists but the file is missing/empty: treat as no coverage.
+      missing.push(want);
+      continue;
+    }
+    bodies.push(body);
+    used.push(typeof hit.entry.name === 'string' && hit.entry.name.length > 0
+      ? hit.entry.name
+      : hit.key);
+  }
+
+  if (bodies.length === 0) return empty();
+
+  const block = `${BLOCK_HEADER}\n\n${bodies.join(ADDENDUM_SEPARATOR)}`;
+  return { block, used, missing };
+}
+
+/**
+ * Pre-spawn mutation helper for the explore runner. Composes the addendum
+ * block for `spec.name` and, when non-empty, APPENDS it to `spec.prompt`
+ * (separated by a blank line). Returns the same `spec` object (mutated in
+ * place) plus the compose metadata so the caller can surface `missing`.
+ *
+ * Backward-compatible + additive: an empty block leaves `spec.prompt`
+ * byte-for-byte unchanged. Never throws: a malformed spec returns unchanged
+ * with empty metadata.
+ *
+ * @param {{name?: string, prompt?: string}} spec  a MapperSpec-shaped object.
+ * @param {object} stack  detected stack (see composeAddendums).
+ * @param {object} [opts] registry/refDir/cap (see composeAddendums).
+ * @returns {{spec: object, block: string, used: string[], missing: string[]}}
+ */
+function applyAddendums(spec, stack, opts) {
+  if (!spec || typeof spec !== 'object') {
+    return { spec, block: '', used: [], missing: [] };
+  }
+  const mapperName = typeof spec.name === 'string' ? spec.name : '';
+  const { block, used, missing } = composeAddendums(mapperName, stack, opts);
+  if (block !== '') {
+    const base = typeof spec.prompt === 'string' ? spec.prompt : '';
+    spec.prompt = base === '' ? block : `${base}\n\n${block}`;
+  }
+  return { spec, block, used, missing };
+}
+
+module.exports = {
+  composeAddendums,
+  applyAddendums,
+  // Exported for unit-level coverage + reuse by the runner wiring (executor F).
+  classifyEntry,
+  composesInto,
+  BLOCK_HEADER,
+};

package/scripts/lib/mapper-spawn.d.cts

@@ -0,0 +1,60 @@
+// scripts/lib/mapper-spawn.d.cts — types for mapper-spawn.cjs (Phase 54 COMP-01).
+
+export interface DetectedStackInput {
+  ds?: string | null;
+  framework?: string | null;
+  motion_libs?: string[];
+}
+
+export interface ComposeAddendumsOptions {
+  /** Parsed reference/registry.json object ({ entries: [...] }). */
+  registry?: unknown;
+  /** Directory addendum `path`s resolve against (repo root or reference/). */
+  refDir?: string;
+  /** Max addendums in the block (default 3 = 1 system + 1 framework + 1 motion). */
+  cap?: number;
+}
+
+export interface ComposeAddendumsResult {
+  /** "## Stack-specific guidance" block text, or '' when nothing matched. */
+  block: string;
+  /** Names (or path basenames) of the addendums included. */
+  used: string[];
+  /** Detected stack values that had NO matching addendum (fallback flag). */
+  missing: string[];
+}
+
+export interface ApplyAddendumsResult extends ComposeAddendumsResult {
+  /** The (possibly mutated) spec object passed in. */
+  spec: unknown;
+}
+
+export interface ClassifiedEntry {
+  category: 'system' | 'framework' | 'motion' | null;
+  key: string;
+}
+
+/**
+ * Compose the stack-specific guidance block for one mapper. Pure (reads files);
+ * NEVER throws. Detected-but-unmatched stack values land in `missing`.
+ */
+export function composeAddendums(
+  mapperName: string,
+  stack: DetectedStackInput | null | undefined,
+  opts?: ComposeAddendumsOptions,
+): ComposeAddendumsResult;
+
+/**
+ * Pre-spawn helper: composes the block for `spec.name` and APPENDS it to
+ * `spec.prompt` (mutated in place) when non-empty. Backward-compatible: an
+ * empty block leaves `spec.prompt` byte-for-byte unchanged. NEVER throws.
+ */
+export function applyAddendums(
+  spec: { name?: string; prompt?: string } | null | undefined,
+  stack: DetectedStackInput | null | undefined,
+  opts?: ComposeAddendumsOptions,
+): ApplyAddendumsResult;
+
+export function classifyEntry(entry: Record<string, unknown>): ClassifiedEntry;
+export function composesInto(entry: Record<string, unknown>, mapperName: string): boolean;
+export const BLOCK_HEADER: string;