@hegemonart/get-design-done 1.21.0 → 1.23.0

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

package/scripts/lib/trajectory/index.cjs

@@ -0,0 +1,126 @@
+/**
+ * trajectory/index.cjs — per-tool-call trajectory stream (Plan 22-03).
+ *
+ * Records every agent tool-use as one JSONL line at
+ *   `.design/telemetry/trajectories/<cycle>.jsonl`
+ *
+ * Why hash args/result instead of storing full content:
+ *   * keeps line size bounded regardless of argument payload
+ *   * de-identifies prompts that may contain user-private content
+ *   * still allows replay via dedup-by-hash if a future analyzer wants it
+ *
+ * Schema (one JSONL line):
+ *   {
+ *     ts:          ISO-8601 with ms,
+ *     session_id:  string | null,
+ *     cycle:       string,                  // 'current' if not supplied
+ *     agent:       string,                  // calling agent name
+ *     tool:        string,                  // 'Bash' / 'Edit' / 'mcp__…'
+ *     args_hash:   16-char sha256 prefix of canonical-JSON args
+ *     result_hash: 16-char sha256 prefix of canonical-JSON result
+ *     latency_ms:  number,
+ *     status:      'ok' | 'error',
+ *   }
+ *
+ * Side effects:
+ *   * appendFileSync to the trajectory file (atomic per line on POSIX/NT)
+ *   * NEVER throws — IO failure logs to stderr and returns silently
+ *   * Optionally appends a `tool_call.completed` event to the
+ *     event-stream so live subscribers can see the same call without
+ *     scanning trajectory files. Skipped if `event_stream` arg is null.
+ */
+
+'use strict';
+
+const { appendFileSync, mkdirSync } = require('node:fs');
+const { dirname, isAbsolute, join, resolve } = require('node:path');
+const { createHash } = require('node:crypto');
+
+const DEFAULT_TRAJECTORY_DIR = '.design/telemetry/trajectories';
+
+/**
+ * Compute a stable 16-char sha256-hex prefix for arbitrary JSON-shaped
+ * input. Falls back to `'0'.repeat(16)` if `JSON.stringify` throws.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function hashOf(value) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(value ?? null);
+  } catch {
+    return '0'.repeat(16);
+  }
+  return createHash('sha256').update(serialized ?? '').digest('hex').slice(0, 16);
+}
+
+/**
+ * Resolve the on-disk trajectory file for `cycle` against `baseDir`.
+ *
+ * @param {{baseDir?: string, cycle?: string, dir?: string}} [opts]
+ * @returns {string}
+ */
+function trajectoryPath(opts = {}) {
+  const baseDir = opts.baseDir ?? process.cwd();
+  const dir = opts.dir ?? DEFAULT_TRAJECTORY_DIR;
+  const cycle = (opts.cycle ?? 'current').replace(/[^A-Za-z0-9._-]/g, '_');
+  const resolvedDir = isAbsolute(dir) ? dir : resolve(baseDir, dir);
+  return join(resolvedDir, `${cycle}.jsonl`);
+}
+
+/**
+ * Append one trajectory record. Returns the recorded line for tests
+ * that want to assert on shape without re-reading the file.
+ *
+ * @param {{
+ *   cycle?: string,
+ *   session_id?: string | null,
+ *   agent: string,
+ *   tool: string,
+ *   args?: unknown,
+ *   result?: unknown,
+ *   latency_ms?: number,
+ *   status?: 'ok' | 'error',
+ *   baseDir?: string,
+ *   path?: string,
+ * }} call
+ * @returns {string} the JSONL line that was appended (without trailing \n)
+ */
+function recordCall(call) {
+  const ts = new Date().toISOString();
+  const record = {
+    ts,
+    session_id: call.session_id ?? null,
+    cycle: call.cycle ?? 'current',
+    agent: call.agent,
+    tool: call.tool,
+    args_hash: hashOf(call.args),
+    result_hash: hashOf(call.result),
+    latency_ms: typeof call.latency_ms === 'number' ? call.latency_ms : 0,
+    status: call.status ?? 'ok',
+  };
+
+  const path = call.path ?? trajectoryPath({ baseDir: call.baseDir, cycle: record.cycle });
+  const line = JSON.stringify(record);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, line + '\n', { flag: 'a' });
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[trajectory] write failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+  return line;
+}
+
+module.exports = {
+  recordCall,
+  trajectoryPath,
+  hashOf,
+  DEFAULT_TRAJECTORY_DIR,
+};

package/scripts/lib/transports/ws.cjs

@@ -0,0 +1,179 @@
+/**
+ * transports/ws.cjs — WebSocket event-stream transport (Plan 22-07).
+ *
+ * Optional dep: requires `ws`. probeOptional() returns null if absent;
+ * importer renders a clear install hint.
+ *
+ * Wire format:
+ *   * One event per WebSocket text frame, JSON-encoded.
+ *   * If `tailFrom` is supplied at startup, replay that file's contents
+ *     to each new connection BEFORE subscribing to live events.
+ *   * Live events come from a caller-supplied `subscribe(handler) →
+ *     unsub` — typically the event-stream bus's subscribeAll. Decoupling
+ *     keeps this CommonJS module independent of the TS bus implementation.
+ *
+ * Auth:
+ *   * `Authorization: Bearer <token>` header required on the upgrade.
+ *   * Mismatched / missing token → HTTP 401 close on the upgrade socket.
+ *
+ * Backpressure:
+ *   * Fire-and-forget. If a client's socket is not in OPEN state we drop
+ *     the event for that client and log a warning. No queue.
+ */
+
+'use strict';
+
+const http = require('node:http');
+const { readFileSync, existsSync } = require('node:fs');
+const { probeOptional } = require('../probe-optional.cjs');
+
+const ws = probeOptional('ws');
+if (!ws) {
+  // Importer (gdd-events.mjs) handles this throw and renders the hint.
+  throw new Error(
+    "ws module not installed (optional dep). Install via: npm i -D ws",
+  );
+}
+const { WebSocketServer } = ws;
+
+/**
+ * Synchronously read a JSONL events file and yield parsed objects.
+ * Matches reader.ts line semantics: skip blank lines + invalid JSON.
+ *
+ * @param {string} path
+ * @returns {Generator<Record<string, unknown>>}
+ */
+function* readEventsSync(path) {
+  if (!existsSync(path)) return;
+  const raw = readFileSync(path, 'utf8');
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      yield JSON.parse(line);
+    } catch {
+      /* skip invalid */
+    }
+  }
+}
+
+/**
+ * Start the WebSocket server. Returns a handle with `close()`.
+ *
+ * @param {{
+ *   port: number,
+ *   token: string,
+ *   tailFrom?: string,
+ *   subscribe?: (handler: (ev: unknown) => void) => () => void,
+ * }} opts
+ * @returns {Promise<{close: () => void, port: number}>}
+ */
+async function startServer(opts) {
+  if (typeof opts.port !== 'number' || !Number.isFinite(opts.port)) {
+    throw new TypeError('startServer: port (number) required');
+  }
+  if (typeof opts.token !== 'string' || opts.token.length < 8) {
+    throw new TypeError('startServer: token (string, ≥8 chars) required');
+  }
+
+  const httpServer = http.createServer((_req, res) => {
+    res.statusCode = 426; // Upgrade Required
+    res.setHeader('Content-Type', 'text/plain');
+    res.end('upgrade required');
+  });
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  /** @type {Set<import('ws').WebSocket>} */
+  const clients = new Set();
+
+  /** @type {() => void} */
+  let unsub = () => {};
+  if (typeof opts.subscribe === 'function') {
+    unsub = opts.subscribe((ev) => {
+      const frame = JSON.stringify(ev);
+      for (const client of clients) {
+        if (client.readyState === ws.OPEN) {
+          try {
+            client.send(frame);
+          } catch (err) {
+            try {
+              process.stderr.write(`[ws] send failed: ${err.message}\n`);
+            } catch {
+              /* swallow */
+            }
+          }
+        }
+      }
+    });
+  }
+
+  httpServer.on('upgrade', (req, socket, head) => {
+    const auth = req.headers['authorization'];
+    if (!auth || auth !== `Bearer ${opts.token}`) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (client) => {
+      clients.add(client);
+
+      if (opts.tailFrom) {
+        try {
+          for (const ev of readEventsSync(opts.tailFrom)) {
+            try {
+              client.send(JSON.stringify(ev));
+            } catch {
+              break;
+            }
+          }
+        } catch (err) {
+          try {
+            process.stderr.write(`[ws] replay failed: ${err.message}\n`);
+          } catch {
+            /* swallow */
+          }
+        }
+      }
+
+      client.on('close', () => clients.delete(client));
+      client.on('error', () => clients.delete(client));
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(opts.port, () => resolve(undefined));
+  });
+
+  const addr = httpServer.address();
+  return {
+    port: typeof addr === 'object' && addr ? addr.port : opts.port,
+    close() {
+      try {
+        unsub();
+      } catch {
+        /* swallow */
+      }
+      for (const c of clients) {
+        try {
+          c.close();
+        } catch {
+          /* swallow */
+        }
+      }
+      clients.clear();
+      try {
+        wss.close();
+      } catch {
+        /* swallow */
+      }
+      try {
+        httpServer.close();
+      } catch {
+        /* swallow */
+      }
+    },
+  };
+}
+
+module.exports = { startServer, readEventsSync };