@hegemonart/get-design-done 1.21.0 → 1.23.0

package/scripts/lib/event-stream/writer.ts

@@ -21,11 +21,64 @@
 //     `payload` with `{ _truncated_placeholder: true }`, then re-serialize
 //     and stamp `_truncated: true` on the line.
 
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, resolve, isAbsolute, join } from 'node:path';
+import { createRequire } from 'node:module';
 
 import type { BaseEvent } from './types.ts';
 
+// Phase 22 Plan 22-02: write-time secret scrubbing. `redact()` deep-walks
+// the event and replaces secret-shaped strings with `[REDACTED:<type>]`
+// placeholders before serialization. Loaded via createRequire so the
+// CommonJS `redact.cjs` interops cleanly. We avoid `import.meta.url` —
+// tsc's Node16 module mode classifies this .ts file as CJS output for
+// typecheck purposes (even though it runs as ESM under
+// `--experimental-strip-types`), and `import.meta` is forbidden in CJS
+// output. Mirror the pattern from `scripts/lib/session-runner/errors.ts`:
+// anchor createRequire on the repo-root package.json discovered by
+// walking up from `process.cwd()`.
+function _findRepoRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+// Soft load: if redact.cjs is unreachable from the runtime cwd (e.g. a
+// hook subprocess running in a temp test dir three directories above
+// the plugin root), fall through to the identity function. The writer
+// keeps working — events just aren't scrubbed in that environment.
+// Production callers always run from inside the plugin tree.
+let _redact: (v: unknown) => unknown;
+try {
+  const _root = _findRepoRoot();
+  const _candidate = resolve(_root, 'scripts/lib/redact.cjs');
+  if (existsSync(_candidate)) {
+    const _redactRequire = createRequire(join(_root, 'package.json'));
+    const _mod = _redactRequire(_candidate) as { redact: (v: unknown) => unknown };
+    _redact = _mod.redact;
+  } else {
+    // Fallback: also try walking up from this source file's logical
+    // position (3 dirs above writer.ts → repo root).
+    const _altRoot = resolve(_root, '..', '..');
+    const _altCandidate = resolve(_altRoot, 'scripts/lib/redact.cjs');
+    if (existsSync(_altCandidate)) {
+      const _altRequire = createRequire(join(_altRoot, 'package.json'));
+      const _altMod = _altRequire(_altCandidate) as { redact: (v: unknown) => unknown };
+      _redact = _altMod.redact;
+    } else {
+      _redact = (v) => v;
+    }
+  }
+} catch {
+  _redact = (v) => v;
+}
+const redact = _redact;
+
 /** Default relative path for the persisted event stream. */
 export const DEFAULT_EVENTS_PATH = '.design/telemetry/events.jsonl';
 
@@ -113,22 +166,26 @@ export class EventWriter {
    * {@link append}.
    */
   serialize(ev: BaseEvent): string {
-    const raw = JSON.stringify(ev) + '\n';
+    // Phase 22 Plan 22-02: scrub secrets from the entire event (envelope +
+    // payload) before serialization. Redaction is non-mutating and runs
+    // exactly once per event, here at the write boundary.
+    const scrubbed = redact(ev) as BaseEvent;
+    const raw = JSON.stringify(scrubbed) + '\n';
     if (Buffer.byteLength(raw, 'utf8') <= this.maxLineBytes) {
       return raw;
     }
 
     // Truncate: keep envelope fields, drop payload content.
     const truncated: BaseEvent = {
-      type: ev.type,
-      timestamp: ev.timestamp,
-      sessionId: ev.sessionId,
+      type: scrubbed.type,
+      timestamp: scrubbed.timestamp,
+      sessionId: scrubbed.sessionId,
       payload: { _truncated_placeholder: true },
       _truncated: true,
     };
-    if (ev.stage !== undefined) truncated.stage = ev.stage;
-    if (ev.cycle !== undefined) truncated.cycle = ev.cycle;
-    if (ev._meta !== undefined) truncated._meta = ev._meta;
+    if (scrubbed.stage !== undefined) truncated.stage = scrubbed.stage;
+    if (scrubbed.cycle !== undefined) truncated.cycle = scrubbed.cycle;
+    if (scrubbed._meta !== undefined) truncated._meta = scrubbed._meta;
     return JSON.stringify(truncated) + '\n';
   }
 

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/redact.cjs

@@ -0,0 +1,122 @@
+/**
+ * redact.cjs — secret scrubbing for event-stream payloads (Plan 22-02).
+ *
+ * Deep-walks a value, replacing any string that matches a known secret
+ * pattern with a `[REDACTED:<type>]` placeholder. Non-mutating — returns
+ * a new structure; the input is not modified.
+ *
+ * Called from `event-stream/writer.ts` at serialize time so every event
+ * that hits disk (and every bus subscriber) sees the redacted form.
+ *
+ * Patterns are intentionally conservative: false-positives on redaction
+ * are low-cost (logged telemetry becomes slightly harder to read); false-
+ * negatives (real secrets leaking) are high-cost. When in doubt, match.
+ *
+ * Adding a pattern: append an entry to `PATTERNS` with a stable `type`
+ * key. The type string is the label emitted into the placeholder.
+ */
+
+'use strict';
+
+/** @type {Array<{type: string, re: RegExp}>} */
+const PATTERNS = [
+  // PEM first — must redact before generic base64 patterns would hit.
+  {
+    type: 'pem',
+    re: /-----BEGIN [A-Z ]+-----[\s\S]+?-----END [A-Z ]+-----/g,
+  },
+  // JWT — 3 dot-separated base64url segments, beginning with eyJ.
+  {
+    type: 'jwt',
+    re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+  },
+  // Anthropic API keys (sk-ant-…) — matched before generic sk- to win.
+  {
+    type: 'anthropic',
+    re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+  },
+  // Stripe live secret key.
+  {
+    type: 'stripe',
+    re: /\bsk_live_[A-Za-z0-9]{20,}\b/g,
+  },
+  // Slack tokens — xoxb/xoxp/xoxa/xoxr/xoxs.
+  {
+    type: 'slack',
+    re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+  },
+  // GitHub personal access token.
+  {
+    type: 'github_pat',
+    re: /\bghp_[A-Za-z0-9]{36,}\b/g,
+  },
+  // AWS access key ID.
+  {
+    type: 'aws',
+    re: /\bAKIA[0-9A-Z]{16}\b/g,
+  },
+  // Generic OpenAI-style sk-… (last in the sk-* family — lower priority
+  // than anthropic/stripe which start with `sk_live_`/`sk-ant-`).
+  {
+    type: 'sk',
+    re: /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+  },
+];
+
+/**
+ * Redact every secret-shaped substring in `s`, returning the scrubbed
+ * string. Patterns are applied in `PATTERNS` order — more-specific
+ * patterns (anthropic, stripe) first so they win over the generic
+ * `sk-` catch-all.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function redactString(s) {
+  if (typeof s !== 'string' || s.length < 10) return s;
+  let out = s;
+  for (const { type, re } of PATTERNS) {
+    re.lastIndex = 0; // safety: `g` flag carries state across calls
+    out = out.replace(re, `[REDACTED:${type}]`);
+  }
+  return out;
+}
+
+/**
+ * Deep-walk `value`, redacting every string encountered. Arrays and
+ * plain objects recurse; everything else returns unchanged.
+ *
+ * Cycle-safe via a WeakSet.
+ *
+ * @param {unknown} value
+ * @param {WeakSet<object>} [seen]
+ * @returns {unknown}
+ */
+function redact(value, seen) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return redactString(value);
+  if (typeof value !== 'object') return value;
+
+  const visited = seen ?? new WeakSet();
+  if (visited.has(/** @type {object} */ (value))) return value;
+  visited.add(/** @type {object} */ (value));
+
+  if (Array.isArray(value)) {
+    return value.map((v) => redact(v, visited));
+  }
+
+  // Plain object. Don't try to preserve class instances — event payloads
+  // are expected to be JSON-shaped bags.
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const key of Object.keys(/** @type {object} */ (value))) {
+    out[key] = redact(/** @type {Record<string, unknown>} */ (value)[key], visited);
+  }
+  return out;
+}
+
+module.exports = {
+  redact,
+  redactString,
+  PATTERNS,
+};

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