@hegemonart/get-design-done 1.22.0 → 1.23.5

package/scripts/lib/reference-resolver.cjs

@@ -0,0 +1,184 @@
+/**
+ * reference-resolver.cjs — `type:<key>` → registry entry + excerpt
+ * (Plan 23-05).
+ *
+ * Builds on `scripts/lib/reference-registry.cjs#list` (Phase 14.5).
+ * Adds the resolution direction: given a key surfaced by an agent
+ * author, return the single matching entry plus a short excerpt
+ * suitable for inlining into prompts.
+ *
+ * Lookup order (first match wins):
+ *   1. exact `name` match
+ *   2. slug match against path basename without extension
+ *   3. singularize fuzzy match (strip trailing 's')
+ *   4. type==key AND only one entry exists at that type
+ *
+ * Ambiguous match → throws RangeError with candidate list.
+ * No match → returns null.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const registry = require('./reference-registry.cjs');
+
+/**
+ * @typedef {Object} ResolverHit
+ * @property {string} name
+ * @property {string} path
+ * @property {string} type
+ * @property {string} excerpt
+ * @property {string} [tier]
+ */
+
+const DEFAULT_MAX_CHARS = 200;
+
+/**
+ * Pull a 200-char excerpt from a markdown file. Strips frontmatter,
+ * fences, comments, headers; collapses whitespace; truncates with `'…'`.
+ *
+ * @param {string} absolutePath
+ * @param {{maxChars?: number}} [opts]
+ * @returns {string}
+ */
+function excerptOf(absolutePath, opts = {}) {
+  const maxChars = typeof opts.maxChars === 'number' ? opts.maxChars : DEFAULT_MAX_CHARS;
+  let raw;
+  try {
+    raw = fs.readFileSync(absolutePath, 'utf8');
+  } catch {
+    return '';
+  }
+  // Drop YAML frontmatter.
+  raw = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+  // Drop fenced code blocks.
+  raw = raw.replace(/```[\s\S]*?```/g, '');
+  // Drop HTML comments. Iterate until stable so that nested or
+  // adjacent `<!-- … -->` sequences cannot smuggle a residual `<!--`
+  // through a single regex pass (CodeQL js/incomplete-multi-character-
+  // sanitization). We're not building defense-in-depth against
+  // real markup attacks here — these excerpts are local doc files —
+  // but the loop costs nothing and silences the alert.
+  let prev;
+  do {
+    prev = raw;
+    raw = raw.replace(/<!--[\s\S]*?-->/g, '');
+  } while (raw !== prev);
+  // Drop heading lines.
+  raw = raw.replace(/^#{1,6}\s.*$/gm, '');
+  // Take first non-empty paragraph.
+  const paragraphs = raw.split(/\r?\n\s*\r?\n/).map((p) => p.trim()).filter(Boolean);
+  if (paragraphs.length === 0) return '';
+  let p = paragraphs[0].replace(/\s+/g, ' ').trim();
+  if (p.length > maxChars) {
+    p = p.slice(0, Math.max(0, maxChars - 1)) + '…';
+  }
+  return p;
+}
+
+/**
+ * Map a registry entry + cwd to a ResolverHit.
+ */
+function hitFor(entry, cwd) {
+  const abs = path.resolve(cwd, entry.path);
+  /** @type {ResolverHit} */
+  const hit = {
+    name: entry.name,
+    path: entry.path,
+    type: entry.type,
+    excerpt: excerptOf(abs),
+  };
+  if (entry.tier) hit.tier = entry.tier;
+  return hit;
+}
+
+/**
+ * Resolve `type:<key>` (or bare `<key>`) to a single registry hit.
+ *
+ * @param {string} typeKey
+ * @param {{cwd?: string}} [opts]
+ * @returns {ResolverHit | null}
+ */
+function resolve(typeKey, opts = {}) {
+  if (typeof typeKey !== 'string' || typeKey.length === 0) return null;
+  const cwd = opts.cwd ?? path.resolve(__dirname, '..', '..');
+  const key = typeKey.replace(/^type:/, '').trim().toLowerCase();
+  if (key.length === 0) return null;
+  const all = registry.list({ cwd });
+
+  // 1. Exact name match.
+  const exact = all.find((e) => e.name.toLowerCase() === key);
+  if (exact) return hitFor(exact, cwd);
+
+  // 2. Slug match against path basename (no extension).
+  const bySlug = all.filter((e) => {
+    const slug = path.posix.basename(e.path, path.posix.extname(e.path)).toLowerCase();
+    return slug === key;
+  });
+  if (bySlug.length === 1) return hitFor(bySlug[0], cwd);
+  if (bySlug.length > 1) {
+    throw new RangeError(
+      `reference-resolver: ambiguous slug match for "${typeKey}" — candidates: ${bySlug.map((e) => e.name).join(', ')}`,
+    );
+  }
+
+  // 3. Singularize: strip trailing 's' from key, then prefix-match name.
+  if (key.endsWith('s') && key.length > 1) {
+    const stem = key.slice(0, -1);
+    const stemHits = all.filter((e) => e.name.toLowerCase().startsWith(stem));
+    if (stemHits.length === 1) return hitFor(stemHits[0], cwd);
+    if (stemHits.length > 1) {
+      throw new RangeError(
+        `reference-resolver: ambiguous singularize match for "${typeKey}" — candidates: ${stemHits.map((e) => e.name).join(', ')}`,
+      );
+    }
+  }
+
+  // 4. type==key AND single entry at that type.
+  const byType = all.filter((e) => e.type.toLowerCase() === key);
+  if (byType.length === 1) return hitFor(byType[0], cwd);
+  if (byType.length > 1) {
+    throw new RangeError(
+      `reference-resolver: ambiguous type-only match for "${typeKey}" — multiple entries at type=${key}: ${byType.map((e) => e.name).join(', ')}`,
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Bulk resolver — used by the prompt-builder.
+ *
+ * @param {string[]} typeKeys
+ * @param {{cwd?: string, ignoreMissing?: boolean}} [opts]
+ * @returns {ResolverHit[]}
+ */
+function resolveAll(typeKeys, opts = {}) {
+  if (!Array.isArray(typeKeys)) {
+    throw new TypeError('reference-resolver: typeKeys must be an array');
+  }
+  /** @type {ResolverHit[]} */
+  const hits = [];
+  /** @type {string[]} */
+  const missing = [];
+  for (const k of typeKeys) {
+    const h = resolve(k, opts);
+    if (h) hits.push(h);
+    else missing.push(k);
+  }
+  if (missing.length > 0 && !opts.ignoreMissing) {
+    throw new Error(
+      `reference-resolver: unresolved keys: ${missing.join(', ')}. Pass {ignoreMissing: true} to skip.`,
+    );
+  }
+  return hits;
+}
+
+module.exports = {
+  resolve,
+  resolveAll,
+  excerptOf,
+  DEFAULT_MAX_CHARS,
+};

package/scripts/lib/touches-analyzer/index.cjs

@@ -0,0 +1,201 @@
+/**
+ * touches-analyzer/index.cjs — parse `Touches:` lines from task markdown
+ * and produce a pairwise parallelism verdict (Plan 23-03).
+ *
+ * Encodes the prompt-only heuristic from `reference/parallelism-rules.md`
+ * into auditable code. Used by /gdd:plan and /gdd:execute to decide
+ * which tasks can run concurrently in a wave.
+ *
+ * Verdict rules (first match wins):
+ *   1. empty globs            → sequential, 'unknown-touches'
+ *   2. literal glob equality  → sequential, 'shared-glob'
+ *   3. shared component dir   → sequential, 'shared-component-dir'
+ *   4. resolved-file overlap  → sequential, 'shared-file'
+ *   5. otherwise              → parallel, 'disjoint'
+ *
+ * No external deps. Designed to be required from CommonJS callers.
+ */
+
+'use strict';
+
+const { readFileSync } = require('node:fs');
+const path = require('node:path');
+
+const TOUCHES_RE = /^[ \t]{0,4}Touches:\s*(.+?)\s*$/gm;
+
+/**
+ * Normalise a glob/path: convert `\\` → `/`, lowercase for case-insensitive
+ * comparison. Returned strings are used as map keys.
+ *
+ * @param {string} g
+ * @returns {string}
+ */
+function normalize(g) {
+  return g.replace(/\\/g, '/').toLowerCase();
+}
+
+/**
+ * Extract `Touches:` lines from markdown.
+ *
+ * @param {string} markdown
+ * @returns {string[]} globs in declaration order, deduped (case-insensitive)
+ */
+function parseTouches(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return [];
+  const out = [];
+  const seen = new Set();
+  TOUCHES_RE.lastIndex = 0;
+  let m;
+  while ((m = TOUCHES_RE.exec(markdown)) !== null) {
+    const body = m[1];
+    for (const raw of body.split(',')) {
+      const trimmed = raw.trim();
+      if (trimmed.length === 0) continue;
+      const key = normalize(trimmed);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(trimmed);
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse a task markdown file by path.
+ *
+ * @param {string} filePath
+ * @returns {{taskId: string, globs: string[]}}
+ */
+function parseTouchesFile(filePath) {
+  const md = readFileSync(filePath, 'utf8');
+  const base = path.basename(filePath).replace(/\.md$/i, '');
+  return { taskId: base, globs: parseTouches(md) };
+}
+
+/**
+ * Compute the directory prefix for a glob at `componentDepth - 1` segments.
+ * Returns null when the glob's first segment is `**` or contains `..` (no
+ * meaningful prefix).
+ *
+ * @param {string} glob
+ * @param {number} componentDepth
+ * @returns {string|null}
+ */
+function componentDirPrefix(glob, componentDepth) {
+  const norm = glob.replace(/\\/g, '/');
+  if (norm.startsWith('..') || norm.startsWith('**')) return null;
+  // Strip leading './'.
+  const cleaned = norm.startsWith('./') ? norm.slice(2) : norm;
+  const segments = cleaned.split('/');
+  const wanted = Math.max(0, componentDepth - 1);
+  if (segments.length < wanted) return null;
+  const prefixSegs = segments.slice(0, wanted);
+  // The prefix must contain at least one *literal* (no `**`) segment.
+  const hasLiteral = prefixSegs.some((s) => s.length > 0 && s !== '**');
+  if (!hasLiteral) return null;
+  return prefixSegs.join('/').toLowerCase();
+}
+
+/**
+ * @typedef {Object} TouchesEntry
+ * @property {string} taskId
+ * @property {string[]} globs
+ * @property {string[]} [resolved]
+ */
+
+/**
+ * @typedef {Object} Verdict
+ * @property {'parallel'|'sequential'} verdict
+ * @property {string} reason
+ * @property {string[]} [evidence]
+ */
+
+/**
+ * Pairwise verdict.
+ *
+ * @param {TouchesEntry} a
+ * @param {TouchesEntry} b
+ * @param {{componentDepth?: number}} [opts]
+ * @returns {Verdict}
+ */
+function pairwiseVerdict(a, b, opts = {}) {
+  const componentDepth = opts.componentDepth ?? 3;
+  if (!a || !b || !Array.isArray(a.globs) || !Array.isArray(b.globs)) {
+    return { verdict: 'sequential', reason: 'unknown-touches' };
+  }
+  if (a.globs.length === 0 || b.globs.length === 0) {
+    return { verdict: 'sequential', reason: 'unknown-touches' };
+  }
+  // Rule 2: literal glob equality (case-insensitive).
+  const aSet = new Set(a.globs.map(normalize));
+  for (const bg of b.globs) {
+    if (aSet.has(normalize(bg))) {
+      return { verdict: 'sequential', reason: 'shared-glob', evidence: [bg] };
+    }
+  }
+  // Rule 3: shared component directory.
+  const aPrefixes = new Set(
+    a.globs.map((g) => componentDirPrefix(g, componentDepth)).filter((p) => p !== null),
+  );
+  const sharedPrefixes = [];
+  for (const bg of b.globs) {
+    const pfx = componentDirPrefix(bg, componentDepth);
+    if (pfx !== null && aPrefixes.has(pfx)) sharedPrefixes.push(pfx);
+  }
+  if (sharedPrefixes.length > 0) {
+    return {
+      verdict: 'sequential',
+      reason: 'shared-component-dir',
+      evidence: Array.from(new Set(sharedPrefixes)),
+    };
+  }
+  // Rule 4: resolved file intersection.
+  if (Array.isArray(a.resolved) && Array.isArray(b.resolved)) {
+    const aFiles = new Set(a.resolved.map(normalize));
+    const overlap = [];
+    for (const bf of b.resolved) {
+      if (aFiles.has(normalize(bf))) overlap.push(bf);
+    }
+    if (overlap.length > 0) {
+      return { verdict: 'sequential', reason: 'shared-file', evidence: overlap };
+    }
+  }
+  return { verdict: 'parallel', reason: 'disjoint' };
+}
+
+/**
+ * Build the upper-triangular N×N verdict table.
+ *
+ * @param {TouchesEntry[]} entries
+ * @param {{componentDepth?: number}} [opts]
+ * @returns {Array<{a: string, b: string, verdict: string, reason: string, evidence?: string[]}>}
+ */
+function verdictMatrix(entries, opts = {}) {
+  if (!Array.isArray(entries)) {
+    throw new TypeError('verdictMatrix: entries must be an array');
+  }
+  const out = [];
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const v = pairwiseVerdict(entries[i], entries[j], opts);
+      const row = {
+        a: entries[i].taskId,
+        b: entries[j].taskId,
+        verdict: v.verdict,
+        reason: v.reason,
+      };
+      if (v.evidence) row.evidence = v.evidence;
+      out.push(row);
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  parseTouches,
+  parseTouchesFile,
+  pairwiseVerdict,
+  verdictMatrix,
+  componentDirPrefix,
+  normalize,
+};

package/scripts/lib/touches-pattern-miner.cjs

@@ -0,0 +1,195 @@
+/**
+ * touches-pattern-miner.cjs — auto-crystallization PROPOSALS only
+ * (Plan 23-06).
+ *
+ * Scans archived task markdown across cycles, normalizes their
+ * `Touches:` signatures, and emits a JSON proposal file when a
+ * signature recurs in ≥ minTasks tasks across ≥ minCycles cycles.
+ *
+ * NEVER auto-applies. The reflector + `/gdd:apply-reflections`
+ * pipeline consumes the proposal JSON separately and asks the user
+ * before materializing anything.
+ *
+ * Reads:  cwd/cycleDir/cycle-{slug}/tasks/{name}.md
+ *         (cycleDir defaults to .design/archive)
+ * Writes: cwd/.design/learnings/touches-patterns.json
+ *         (atomic via .tmp sibling + rename)
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseTouches } = require('./touches-analyzer/index.cjs');
+
+const DEFAULT_CYCLE_DIR = '.design/archive';
+const DEFAULT_OUT_PATH = '.design/learnings/touches-patterns.json';
+const DEFAULT_MIN_TASKS = 3;
+const DEFAULT_MIN_CYCLES = 2;
+
+const CYCLE_DATED_RE = /^cycle-\d{4}-\d{2}-\d{2}.*/i;
+const CYCLE_SLUG_RE = /^cycle-[a-z0-9-]+$/i;
+
+/**
+ * Canonicalize a glob list into a stable signature string.
+ *
+ * @param {string[]} globs
+ * @returns {string}
+ */
+function canonicalize(globs) {
+  if (!Array.isArray(globs) || globs.length === 0) return '';
+  const norm = globs
+    .map((g) => stripCycleSlugs(String(g).replace(/\\/g, '/').toLowerCase()))
+    .filter((g) => g.length > 0);
+  const dedup = Array.from(new Set(norm));
+  dedup.sort();
+  return dedup.join(',');
+}
+
+/**
+ * Replace `cycle-2026-04-01` / `cycle-foo-bar` segments with `<cycle>`.
+ *
+ * @param {string} normalizedPath
+ * @returns {string}
+ */
+function stripCycleSlugs(normalizedPath) {
+  return normalizedPath
+    .split('/')
+    .map((seg) => (CYCLE_DATED_RE.test(seg) || CYCLE_SLUG_RE.test(seg) ? '<cycle>' : seg))
+    .join('/');
+}
+
+/**
+ * @typedef {Object} TouchesSignature
+ * @property {string} signature
+ * @property {string[]} globs
+ * @property {Array<{cycle: string, task: string}>} occurrences
+ * @property {number} cycleCount
+ * @property {number} taskCount
+ */
+
+/**
+ * @typedef {Object} MinerProposal
+ * @property {string} schema_version
+ * @property {string} generated_at
+ * @property {{minTasks: number, minCycles: number}} thresholds
+ * @property {TouchesSignature[]} proposals
+ */
+
+/**
+ * Walk archived cycles and tally signature occurrences.
+ *
+ * @param {{cwd?: string, cycleDir?: string, minTasks?: number, minCycles?: number}} [opts]
+ * @returns {Promise<MinerProposal>}
+ */
+async function mine(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const cycleDir = opts.cycleDir ?? DEFAULT_CYCLE_DIR;
+  const minTasks = opts.minTasks ?? DEFAULT_MIN_TASKS;
+  const minCycles = opts.minCycles ?? DEFAULT_MIN_CYCLES;
+
+  const archiveRoot = path.isAbsolute(cycleDir) ? cycleDir : path.join(cwd, cycleDir);
+  /** @type {Map<string, {globs: string[], occurrences: Array<{cycle: string, task: string}>, cycleSet: Set<string>}>} */
+  const byKey = new Map();
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(archiveRoot, { withFileTypes: true });
+  } catch {
+    // Archive dir missing → empty proposal envelope.
+  }
+
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    if (!ent.name.toLowerCase().startsWith('cycle-')) continue;
+    const cycleId = ent.name;
+    const tasksDir = path.join(archiveRoot, cycleId, 'tasks');
+    let taskFiles = [];
+    try {
+      taskFiles = fs
+        .readdirSync(tasksDir, { withFileTypes: true })
+        .filter((d) => d.isFile() && d.name.toLowerCase().endsWith('.md'))
+        .map((d) => d.name);
+    } catch {
+      continue;
+    }
+    for (const taskName of taskFiles) {
+      const taskPath = path.join(tasksDir, taskName);
+      let md;
+      try {
+        md = fs.readFileSync(taskPath, 'utf8');
+      } catch {
+        continue;
+      }
+      const globs = parseTouches(md);
+      if (globs.length === 0) continue;
+      const sig = canonicalize(globs);
+      if (sig.length === 0) continue;
+      let bucket = byKey.get(sig);
+      if (!bucket) {
+        bucket = {
+          globs: sig.split(','),
+          occurrences: [],
+          cycleSet: new Set(),
+        };
+        byKey.set(sig, bucket);
+      }
+      bucket.occurrences.push({ cycle: cycleId, task: taskName });
+      bucket.cycleSet.add(cycleId);
+    }
+  }
+
+  /** @type {TouchesSignature[]} */
+  const proposals = [];
+  for (const [signature, bucket] of byKey) {
+    if (bucket.occurrences.length < minTasks) continue;
+    if (bucket.cycleSet.size < minCycles) continue;
+    proposals.push({
+      signature,
+      globs: bucket.globs,
+      occurrences: bucket.occurrences.slice(),
+      cycleCount: bucket.cycleSet.size,
+      taskCount: bucket.occurrences.length,
+    });
+  }
+  proposals.sort((a, b) => {
+    if (a.taskCount !== b.taskCount) return b.taskCount - a.taskCount;
+    return a.signature < b.signature ? -1 : a.signature > b.signature ? 1 : 0;
+  });
+
+  return {
+    schema_version: '1.0.0',
+    generated_at: new Date().toISOString(),
+    thresholds: { minTasks, minCycles },
+    proposals,
+  };
+}
+
+/**
+ * Atomic write of the proposal envelope. Returns the absolute path
+ * written.
+ *
+ * @param {MinerProposal} proposal
+ * @param {{cwd?: string, outPath?: string}} [opts]
+ * @returns {string}
+ */
+function writeProposals(proposal, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const outRel = opts.outPath ?? DEFAULT_OUT_PATH;
+  const out = path.isAbsolute(outRel) ? outRel : path.join(cwd, outRel);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const tmp = out + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(proposal, null, 2));
+  fs.renameSync(tmp, out);
+  return out;
+}
+
+module.exports = {
+  mine,
+  writeProposals,
+  canonicalize,
+  stripCycleSlugs,
+  DEFAULT_CYCLE_DIR,
+  DEFAULT_OUT_PATH,
+};