@hegemonart/get-design-done 1.22.0 → 1.23.0

package/scripts/lib/parse-contract.cjs

@@ -204,11 +204,176 @@ function loadMotionMapSchema(projectRoot) {
   return JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
 }
 
+// ---------------------------------------------------------------------------
+// Phase 23 Plan 23-01 — planner + verifier decision contracts.
+//
+// These parsers ride the same extract→parse→validate pipeline as
+// parseMotionMap. Validation is structural (required fields, enums,
+// types) — full JSON Schema validation is delegated to ajv when callers
+// want strict enforcement; the in-line validators keep the no-deps
+// guarantee for the hot path.
+// ---------------------------------------------------------------------------
+
+const VALID_VERIFIER_VERDICTS = ['pass', 'fail', 'gap'];
+const VALID_GAP_SEVERITIES = ['P0', 'P1', 'P2', 'P3'];
+const VALID_VERIFIER_CONFIDENCE = ['high', 'med', 'low'];
+
+function validatePlannerDecision(data) {
+  const errors = [];
+  if (!data || typeof data !== 'object') {
+    return { ok: false, errors: ['Top-level value is not an object'] };
+  }
+  if (data.schema_version !== '1.0.0') {
+    errors.push(`schema_version must be "1.0.0" (got ${JSON.stringify(data.schema_version)})`);
+  }
+  if (typeof data.plan_id !== 'string' || data.plan_id.length === 0) {
+    errors.push('plan_id is required (non-empty string)');
+  }
+  if (!Array.isArray(data.tasks) || data.tasks.length === 0) {
+    errors.push('tasks must be a non-empty array');
+  } else {
+    data.tasks.forEach((task, i) => {
+      const tag = `tasks[${i}]`;
+      if (!task || typeof task !== 'object') {
+        errors.push(`${tag} is not an object`);
+        return;
+      }
+      if (typeof task.task_id !== 'string' || task.task_id.length === 0) {
+        errors.push(`${tag}.task_id is required (non-empty string)`);
+      }
+      if (typeof task.summary !== 'string' || task.summary.length < 3) {
+        errors.push(`${tag}.summary required, ≥3 chars`);
+      }
+      if (!Array.isArray(task.touches) || task.touches.some((t) => typeof t !== 'string')) {
+        errors.push(`${tag}.touches must be an array of strings`);
+      }
+      if (task.dependencies !== undefined &&
+          (!Array.isArray(task.dependencies) ||
+           task.dependencies.some((d) => typeof d !== 'string'))) {
+        errors.push(`${tag}.dependencies must be an array of strings`);
+      }
+      if (task.parallel_safe !== undefined && typeof task.parallel_safe !== 'boolean') {
+        errors.push(`${tag}.parallel_safe must be boolean`);
+      }
+      if (task.estimated_minutes !== undefined &&
+          (typeof task.estimated_minutes !== 'number' || task.estimated_minutes < 0)) {
+        errors.push(`${tag}.estimated_minutes must be a non-negative number`);
+      }
+    });
+  }
+  if (!Array.isArray(data.waves) || data.waves.length === 0) {
+    errors.push('waves must be a non-empty array');
+  } else {
+    data.waves.forEach((wave, i) => {
+      const tag = `waves[${i}]`;
+      if (!wave || typeof wave !== 'object') {
+        errors.push(`${tag} is not an object`);
+        return;
+      }
+      if (typeof wave.wave !== 'string' || wave.wave.length === 0) {
+        errors.push(`${tag}.wave required (non-empty string)`);
+      }
+      if (!Array.isArray(wave.task_ids) || wave.task_ids.length === 0) {
+        errors.push(`${tag}.task_ids must be a non-empty array`);
+      }
+    });
+  }
+  return errors.length === 0 ? { ok: true, data } : { ok: false, errors };
+}
+
+function validateVerifierDecision(data) {
+  const errors = [];
+  if (!data || typeof data !== 'object') {
+    return { ok: false, errors: ['Top-level value is not an object'] };
+  }
+  if (data.schema_version !== '1.0.0') {
+    errors.push(`schema_version must be "1.0.0" (got ${JSON.stringify(data.schema_version)})`);
+  }
+  if (!VALID_VERIFIER_VERDICTS.includes(data.verdict)) {
+    errors.push(`verdict must be one of [${VALID_VERIFIER_VERDICTS.join('|')}] (got ${JSON.stringify(data.verdict)})`);
+  }
+  if (!Array.isArray(data.gaps)) {
+    errors.push('gaps must be an array');
+  } else {
+    data.gaps.forEach((gap, i) => {
+      const tag = `gaps[${i}]`;
+      if (!gap || typeof gap !== 'object') {
+        errors.push(`${tag} is not an object`);
+        return;
+      }
+      if (typeof gap.id !== 'string' || gap.id.length === 0) {
+        errors.push(`${tag}.id is required (non-empty string)`);
+      }
+      if (!VALID_GAP_SEVERITIES.includes(gap.severity)) {
+        errors.push(`${tag}.severity must be one of [${VALID_GAP_SEVERITIES.join('|')}]`);
+      }
+      if (typeof gap.area !== 'string' || gap.area.length === 0) {
+        errors.push(`${tag}.area is required (non-empty string)`);
+      }
+      if (typeof gap.summary !== 'string' || gap.summary.length < 3) {
+        errors.push(`${tag}.summary required, ≥3 chars`);
+      }
+    });
+  }
+  if (!Array.isArray(data.must_fix_before_ship) ||
+      data.must_fix_before_ship.some((s) => typeof s !== 'string')) {
+    errors.push('must_fix_before_ship must be an array of strings');
+  }
+  if (!VALID_VERIFIER_CONFIDENCE.includes(data.confidence)) {
+    errors.push(`confidence must be one of [${VALID_VERIFIER_CONFIDENCE.join('|')}]`);
+  }
+  return errors.length === 0 ? { ok: true, data } : { ok: false, errors };
+}
+
+/**
+ * Extract + validate the planner decision JSON block from markdown output.
+ * @param {string} markdown
+ * @returns {{ ok: true, data: object } | { ok: false, error: string }}
+ */
+function parsePlannerDecision(markdown) {
+  const extracted = extractJsonBlock(markdown);
+  if (!extracted.ok) return { ok: false, error: extracted.error };
+  const parsed = parseJson(extracted.raw);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  const validated = validatePlannerDecision(parsed.data);
+  if (!validated.ok) {
+    return {
+      ok: false,
+      error: `Planner decision contract violations:\n${validated.errors.map((e) => `  - ${e}`).join('\n')}`,
+    };
+  }
+  return { ok: true, data: validated.data };
+}
+
+/**
+ * Extract + validate the verifier decision JSON block from markdown output.
+ * @param {string} markdown
+ * @returns {{ ok: true, data: object } | { ok: false, error: string }}
+ */
+function parseVerifierDecision(markdown) {
+  const extracted = extractJsonBlock(markdown);
+  if (!extracted.ok) return { ok: false, error: extracted.error };
+  const parsed = parseJson(extracted.raw);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  const validated = validateVerifierDecision(parsed.data);
+  if (!validated.ok) {
+    return {
+      ok: false,
+      error: `Verifier decision contract violations:\n${validated.errors.map((e) => `  - ${e}`).join('\n')}`,
+    };
+  }
+  return { ok: true, data: validated.data };
+}
+
 module.exports = {
   parseMotionMap,
+  parsePlannerDecision,
+  parseVerifierDecision,
   parseGenericContract,
   loadMotionMapSchema,
   validateMotionMap,
+  validatePlannerDecision,
+  validateVerifierDecision,
   extractJsonBlock,
   parseJson,
   // Exported for testing
@@ -217,4 +382,7 @@ module.exports = {
   VALID_TRANSITION_FAMILIES,
   VALID_DURATION_CLASSES,
   VALID_TRIGGERS,
+  VALID_VERIFIER_VERDICTS,
+  VALID_GAP_SEVERITIES,
+  VALID_VERIFIER_CONFIDENCE,
 };

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,
+};