@hegemonart/get-design-done 1.20.0 → 1.22.0

package/scripts/lib/context-engine/index.ts

@@ -0,0 +1,116 @@
+// scripts/lib/context-engine/index.ts — public API for the context-engine.
+// Pipes { stage, cwd } → typed ContextBundle. Never touches the Agent SDK.
+
+import { resolve } from 'node:path';
+import { Buffer } from 'node:buffer';
+
+import type { Stage, ContextFile, ContextBundle, BundleOptions } from './types.ts';
+import { MANIFEST, manifestFor, readFileRaw } from './manifest.ts';
+import { truncateMarkdown } from './truncate.ts';
+import { getLogger } from '../logger/index.ts';
+
+/** Default 8 KiB truncation threshold. */
+const DEFAULT_THRESHOLD_BYTES = 8192;
+
+export type { Stage, ContextFile, ContextBundle, BundleOptions } from './types.ts';
+export { MANIFEST, manifestFor, readFileRaw } from './manifest.ts';
+export { truncateMarkdown } from './truncate.ts';
+
+/**
+ * Build the context bundle for a given stage. Reads every file in
+ * `MANIFEST[stage]` from disk, applies markdown-aware truncation to any file
+ * whose raw size exceeds `truncationThresholdBytes` (default 8 KiB), and
+ * returns the typed bundle.
+ *
+ * Missing files are recorded as `present: false` with empty content (unless
+ * `strict: true`, in which case the first missing file throws). ENOENT never
+ * surfaces to the caller in default mode — other IO errors still propagate.
+ */
+export function buildContextBundle(stage: Stage, opts: BundleOptions = {}): ContextBundle {
+  const cwd = opts.cwd ?? process.cwd();
+  const threshold = opts.truncationThresholdBytes ?? DEFAULT_THRESHOLD_BYTES;
+  const strict = opts.strict === true;
+
+  const manifest = manifestFor(stage);
+  const files: ContextFile[] = [];
+  let total_bytes = 0;
+
+  for (const entry of manifest) {
+    const absPath = resolve(cwd, entry);
+    const { present, raw, raw_bytes } = readFileRaw(absPath);
+
+    if (!present) {
+      if (strict) {
+        throw new Error(`context-engine: required file not found: ${entry}`);
+      }
+      files.push({
+        path: entry,
+        present: false,
+        raw_bytes: 0,
+        content: '',
+        content_bytes: 0,
+        truncated_lines: 0,
+      });
+      continue;
+    }
+
+    const { content, truncated_lines } = truncateMarkdown(raw, threshold);
+    const content_bytes = Buffer.byteLength(content, 'utf8');
+    files.push({
+      path: entry,
+      present: true,
+      raw_bytes,
+      content,
+      content_bytes,
+      truncated_lines,
+    });
+    total_bytes += content_bytes;
+  }
+
+  const bundle: ContextBundle = {
+    stage,
+    files,
+    total_bytes,
+    built_at: new Date().toISOString(),
+  };
+
+  // Diagnostic emit. Plan 21-04 Task 4: context-engine consumes the
+  // structured logger so CI and the E2E harness can observe bundle
+  // construction without screen-scraping stdout.
+  try {
+    getLogger().debug('bundle built', {
+      stage,
+      files: files.length,
+      total_bytes,
+    });
+  } catch {
+    // getLogger() is defensive; any failure here must not block bundle
+    // construction. Callers depend on buildContextBundle returning a
+    // valid ContextBundle.
+  }
+
+  return bundle;
+}
+
+/**
+ * Render a bundle as a single prompt-ready string with per-file HTML-comment
+ * headers and `\n---\n` dividers between files. Missing files render as
+ * `<!-- file: PATH (missing) -->` with no body.
+ *
+ * Consumed by pipeline-runner (21-05) and parallel runners (21-06..08) to
+ * build the system prompt's context section.
+ */
+export function renderBundle(bundle: ContextBundle): string {
+  const parts: string[] = [];
+  for (const f of bundle.files) {
+    if (!f.present) {
+      parts.push(`<!-- file: ${f.path} (missing) -->`);
+      continue;
+    }
+    parts.push(`<!-- file: ${f.path} (${f.content_bytes} bytes) -->\n${f.content}`);
+  }
+  // Ensure MANIFEST import remains live-referenced for consumers that depend
+  // on side-effects of module loading (none currently, but harmless).
+  void MANIFEST;
+  return parts.join('\n---\n');
+}

package/scripts/lib/context-engine/manifest.ts

@@ -0,0 +1,69 @@
+// scripts/lib/context-engine/manifest.ts — locked per-stage file manifest +
+// ENOENT-tolerant disk reader. The MANIFEST object is the single
+// source-of-truth for which `.design/*.md` files each headless stage skill
+// reads; runners in Plans 21-05..08 query it indirectly via manifestFor().
+//
+// Frozen shape: outer Record and every inner array are Object.freeze()d so
+// downstream mutation attempts fail fast in strict mode (TypeScript strict
+// mode already flags them at compile time).
+
+import { readFileSync } from 'node:fs';
+import { Buffer } from 'node:buffer';
+
+import type { Stage } from './types.ts';
+
+/**
+ * Per-stage file manifest. Order within each tuple is significant — it is the
+ * order files appear in the rendered bundle (see `renderBundle` in index.ts).
+ *
+ * LOCKED: do not modify without revisiting the skill prompts for every stage
+ * listed below. Changes here cascade into Phase 21 runner prompts.
+ */
+export const MANIFEST: Readonly<Record<Stage, readonly string[]>> = Object.freeze({
+  brief:   Object.freeze(['.design/STATE.md', '.design/BRIEF.md']),
+  explore: Object.freeze(['.design/STATE.md', '.design/BRIEF.md', '.design/DESIGN-CONTEXT.md']),
+  plan:    Object.freeze([
+    '.design/STATE.md',
+    '.design/DESIGN-PLAN.md',
+    '.design/DESIGN-CONTEXT.md',
+    '.design/RESEARCH.md',
+  ]),
+  design:  Object.freeze(['.design/STATE.md', '.design/DESIGN-PLAN.md']),
+  verify:  Object.freeze(['.design/STATE.md', '.design/DESIGN-PLAN.md', '.design/SUMMARY.md']),
+  init:    Object.freeze(['.design/STATE.md']),
+});
+
+/**
+ * Return the locked manifest entries for a stage. Returned array is
+ * Object.freeze()d — callers must not mutate.
+ */
+export function manifestFor(stage: Stage): readonly string[] {
+  const entries = MANIFEST[stage];
+  // Defensive: MANIFEST is typed as Readonly<Record<Stage, ...>> but a caller
+  // passing a value that has been cast to Stage at runtime could land here
+  // with an unknown key. Return empty array rather than undefined to keep the
+  // caller's control flow simple (they iterate and get zero files).
+  return entries ?? Object.freeze([]);
+}
+
+/**
+ * Read one file from disk. Returns `{ present, raw, raw_bytes }`. Never
+ * throws on `ENOENT` — returns `{ present: false, raw: '', raw_bytes: 0 }`.
+ * Other IO errors (EACCES, EIO, EISDIR, …) propagate to the caller because
+ * those are configuration bugs, not missing-file conditions.
+ */
+export function readFileRaw(absPath: string): { present: boolean; raw: string; raw_bytes: number } {
+  try {
+    const raw = readFileSync(absPath, 'utf8');
+    return { present: true, raw, raw_bytes: Buffer.byteLength(raw, 'utf8') };
+  } catch (err) {
+    // Node fs errors carry a `.code` string. Only swallow the missing-file
+    // family; everything else is re-thrown so the caller (or strict mode in
+    // buildContextBundle) surfaces the real problem.
+    const code = (err as NodeJS.ErrnoException | null)?.code;
+    if (code === 'ENOENT') {
+      return { present: false, raw: '', raw_bytes: 0 };
+    }
+    throw err;
+  }
+}

package/scripts/lib/context-engine/truncate.ts

@@ -0,0 +1,282 @@
+// scripts/lib/context-engine/truncate.ts — markdown-aware truncation that
+// preserves frontmatter verbatim, every heading line, and the first paragraph
+// of each section. Files at or below the threshold pass through byte-identical.
+//
+// Algorithm is deterministic and line-based: no regex over the full buffer,
+// no streaming. Designed for `.design/*.md` files which are short enough that
+// a line array fits comfortably in memory.
+
+import { Buffer } from 'node:buffer';
+
+/** Byte budget for preamble text between frontmatter close and the first heading. */
+const PREAMBLE_BYTE_BUDGET = 500;
+/** Cap on frontmatter scan depth to avoid pathological files. */
+const FRONTMATTER_SCAN_CAP = 200;
+/** Marker emitted when preamble exceeds its byte budget. */
+const PREAMBLE_MARKER = '<!-- truncated preamble -->';
+
+export interface TruncateResult {
+  content: string;
+  /** Lines removed in aggregate. */
+  truncated_lines: number;
+}
+
+/**
+ * If `raw` is at or under `thresholdBytes`, returns the input byte-identical
+ * with `truncated_lines: 0`. Otherwise applies markdown-aware truncation per
+ * the Plan 21-02 spec.
+ */
+export function truncateMarkdown(raw: string, thresholdBytes: number): TruncateResult {
+  if (Buffer.byteLength(raw, 'utf8') <= thresholdBytes) {
+    return { content: raw, truncated_lines: 0 };
+  }
+
+  // Split on \n; JavaScript's split drops the trailing empty fragment only
+  // when the string ends with exactly one \n, so a file ending in "\n" gives
+  // us an empty last entry we must preserve to round-trip exactly.
+  const lines = raw.split('\n');
+
+  const frontmatterEnd = detectFrontmatterEnd(lines);
+  const frontmatterLines = frontmatterEnd >= 0 ? lines.slice(0, frontmatterEnd + 1) : [];
+  const bodyStart = frontmatterEnd >= 0 ? frontmatterEnd + 1 : 0;
+  const body = lines.slice(bodyStart);
+
+  // First heading index inside the body slice (relative to body, not lines).
+  const firstHeadingInBody = body.findIndex(isHeadingLine);
+
+  // Preamble: lines between frontmatter close and the first heading.
+  let preambleLines: string[] = [];
+  let preambleDrops = 0;
+  let preambleEndInBody = 0;
+  if (firstHeadingInBody < 0) {
+    // No headings at all. Everything in body is preamble — and the spec says
+    // "entire body becomes one preamble -> truncated preamble marker" when
+    // there are no headings in an over-threshold file. We still apply the
+    // 500-byte budget: short prose is kept, long prose is replaced.
+    preambleEndInBody = body.length;
+    const preambleRaw = body.join('\n');
+    if (Buffer.byteLength(preambleRaw, 'utf8') <= PREAMBLE_BYTE_BUDGET && preambleRaw.length > 0) {
+      preambleLines = body.slice();
+    } else if (body.length > 0) {
+      preambleLines = [PREAMBLE_MARKER];
+      preambleDrops = body.length;
+    }
+  } else {
+    preambleEndInBody = firstHeadingInBody;
+    if (firstHeadingInBody > 0) {
+      const preambleSlice = body.slice(0, firstHeadingInBody);
+      // Strip leading + trailing blanks so spacing is owned by the output
+      // assembler, not double-emitted here. Leading blanks come from the
+      // `\n` that follows frontmatter's closing `---`; trailing blanks
+      // come from the gap before the first heading.
+      const trimmed = stripTrailingBlank(stripLeadingBlank(preambleSlice));
+      const preambleRaw = trimmed.join('\n');
+      if (trimmed.length === 0) {
+        preambleLines = [];
+      } else if (Buffer.byteLength(preambleRaw, 'utf8') <= PREAMBLE_BYTE_BUDGET) {
+        preambleLines = trimmed;
+      } else {
+        preambleLines = [PREAMBLE_MARKER];
+        preambleDrops = trimmed.length;
+      }
+    }
+  }
+
+  // Walk headings + first paragraphs from the first heading onward.
+  const afterPreamble = body.slice(preambleEndInBody);
+  const { kept, droppedLines } = walkHeadingsAndParagraphs(afterPreamble);
+
+  // Assemble output: frontmatter + (optional blank) + preamble + (optional blank) + kept.
+  const out: string[] = [];
+  if (frontmatterLines.length > 0) {
+    out.push(...frontmatterLines);
+  }
+  if (preambleLines.length > 0) {
+    // Spacing: ensure exactly one blank line between frontmatter and preamble
+    // if both are present.
+    if (out.length > 0 && out[out.length - 1] !== '') {
+      out.push('');
+    }
+    out.push(...preambleLines);
+  }
+  if (kept.length > 0) {
+    if (out.length > 0 && out[out.length - 1] !== '') {
+      out.push('');
+    }
+    out.push(...kept);
+  }
+
+  const content = out.join('\n');
+  const truncated_lines = preambleDrops + droppedLines;
+  return { content, truncated_lines };
+}
+
+/**
+ * Detect a YAML frontmatter block's closing index. Returns the index of the
+ * closing `---` line, or -1 if no well-formed frontmatter is present.
+ *
+ * A well-formed frontmatter requires: first non-empty line is `---`, AND a
+ * matching closing `---` exists within the first FRONTMATTER_SCAN_CAP lines
+ * OR within the file length (whichever is smaller).
+ */
+function detectFrontmatterEnd(lines: string[]): number {
+  // Find the first non-empty line.
+  let firstNonEmpty = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if ((lines[i] ?? '').length > 0) {
+      firstNonEmpty = i;
+      break;
+    }
+  }
+  if (firstNonEmpty < 0) return -1;
+  if (lines[firstNonEmpty] !== '---') return -1;
+
+  const scanCap = Math.min(FRONTMATTER_SCAN_CAP, lines.length - 1);
+  for (let i = firstNonEmpty + 1; i <= scanCap; i++) {
+    if (lines[i] === '---') return i;
+  }
+  return -1;
+}
+
+/**
+ * True when `line` starts with 1-6 hashes followed by whitespace and at
+ * least one non-whitespace character — i.e. a real ATX heading, not `####`
+ * on its own (which is legal markdown but uninformative here).
+ */
+function isHeadingLine(line: string): boolean {
+  // Quick reject: must start with '#'.
+  if (line.length === 0 || line.charCodeAt(0) !== 35 /* '#' */) return false;
+  return /^#{1,6}\s+\S/.test(line);
+}
+
+function stripTrailingBlank(arr: string[]): string[] {
+  let end = arr.length;
+  while (end > 0 && arr[end - 1] === '') end--;
+  return arr.slice(0, end);
+}
+
+function stripLeadingBlank(arr: string[]): string[] {
+  let start = 0;
+  while (start < arr.length && arr[start] === '') start++;
+  return arr.slice(start);
+}
+
+/**
+ * Core walker over the post-preamble body. Produces `kept` — the output
+ * lines (headings, first paragraphs, markers) — and `droppedLines` — the
+ * aggregate count of lines classified as drop.
+ *
+ * Classification per line:
+ *   - heading (#{1,6} + space) -> keep
+ *   - non-blank line immediately after a heading or after a prior keep-para
+ *     line (still in the same first-paragraph run) -> keep
+ *   - blank line -> terminates the current paragraph; itself dropped
+ *     from output (we re-insert exactly one blank between preserved chunks)
+ *   - everything else -> drop (counts into droppedLines)
+ *
+ * When a run of drop lines flushes (i.e. the next keeper arrives), we emit
+ * `<!-- truncated: N lines removed -->` exactly once before that keeper.
+ */
+function walkHeadingsAndParagraphs(body: string[]): { kept: string[]; droppedLines: number } {
+  const kept: string[] = [];
+  let droppedLines = 0;
+  let pendingDropCount = 0;
+  // Modes:
+  //   'start'        — before the first heading (normally empty after preamble).
+  //   'await-para'   — after a heading, skipping leading blanks until the
+  //                    first non-blank line (which starts the first paragraph).
+  //                    Blank lines in this mode are neither kept nor counted
+  //                    as drops — they are standard heading/paragraph gaps.
+  //   'para'         — collecting first-paragraph lines under the current
+  //                    heading. Terminates on blank or next heading.
+  //   'gap'          — after the paragraph's terminating blank; dropping
+  //                    until the next heading.
+  type Mode = 'start' | 'await-para' | 'para' | 'gap';
+  let mode: Mode = 'start';
+
+  const flushDropsBeforeKeeper = (): void => {
+    if (pendingDropCount > 0) {
+      // Separate the marker from whatever preceded it with a blank line,
+      // but only if `kept` is non-empty and its last line is not already
+      // blank. This matches the spec's "single blank between preserved
+      // runs" rule.
+      if (kept.length > 0 && kept[kept.length - 1] !== '') {
+        kept.push('');
+      }
+      kept.push(`<!-- truncated: ${pendingDropCount} lines removed -->`);
+      pendingDropCount = 0;
+    }
+  };
+
+  for (let i = 0; i < body.length; i++) {
+    const line = body[i] ?? '';
+    const heading = isHeadingLine(line);
+
+    if (heading) {
+      flushDropsBeforeKeeper();
+      // Ensure a single blank line before the heading if the previous output
+      // isn't already blank (and there is previous output).
+      if (kept.length > 0 && kept[kept.length - 1] !== '') {
+        kept.push('');
+      }
+      kept.push(line);
+      // Enter await-para: standard markdown wraps heading/paragraph with a
+      // blank line; we must skip that blank before collecting the first
+      // paragraph, otherwise the paragraph is dropped entirely.
+      mode = 'await-para';
+      continue;
+    }
+
+    if (mode === 'await-para') {
+      if (line === '') {
+        // Leading blank between heading and its first paragraph. Skip it —
+        // do not count as a drop (it is structural whitespace).
+        continue;
+      }
+      // First non-blank line after the heading: emit our blank separator
+      // (so the heading is followed by exactly one blank) and start the
+      // paragraph run.
+      kept.push('');
+      kept.push(line);
+      mode = 'para';
+      continue;
+    }
+
+    if (mode === 'para') {
+      if (line === '') {
+        // End the first-paragraph run; switch to drop-gap mode. The blank
+        // itself is not kept (the next heading will re-insert one blank
+        // before its own line).
+        mode = 'gap';
+        continue;
+      }
+      // Non-blank line inside first-paragraph run: keep verbatim.
+      kept.push(line);
+      continue;
+    }
+
+    // mode is 'start' or 'gap' — drop everything until the next heading.
+    if (line === '') {
+      // Blank lines inside the drop-gap don't count as lines-we-dropped for
+      // byte-saving purposes but the spec counts dropped lines strictly, so
+      // include them in the count. This matches plan acceptance 3.8:
+      // "truncated_lines count matches exactly the number of dropped lines".
+      pendingDropCount += 1;
+      droppedLines += 1;
+      continue;
+    }
+    pendingDropCount += 1;
+    droppedLines += 1;
+  }
+
+  // Trailing drop run: emit the marker so callers can see the removed count
+  // for the file tail even when no heading follows.
+  if (pendingDropCount > 0) {
+    if (kept.length > 0 && kept[kept.length - 1] !== '') {
+      kept.push('');
+    }
+    kept.push(`<!-- truncated: ${pendingDropCount} lines removed -->`);
+  }
+
+  return { kept, droppedLines };
+}

package/scripts/lib/context-engine/types.ts

@@ -0,0 +1,59 @@
+// scripts/lib/context-engine/types.ts — typed shapes for the context-engine
+// module. The context-engine deterministically assembles the per-stage file
+// manifest a headless Phase 21 session needs. Types are data-only; all
+// behavior lives in sibling modules (manifest.ts, truncate.ts, index.ts).
+
+/**
+ * Pipeline stage identifier. Mirrors the `stage` field in `.design/STATE.md`
+ * and the orchestrator routes in skills/*. The `init` stage is headless-only —
+ * it prepares a fresh working directory before the `brief` stage begins.
+ */
+export type Stage = 'brief' | 'explore' | 'plan' | 'design' | 'verify' | 'init';
+
+/**
+ * Per-file record inside a {@link ContextBundle}. Captures both raw on-disk
+ * size and post-truncation content size so callers can preview prompt budget
+ * before invoking the Agent SDK.
+ */
+export interface ContextFile {
+  /** Absolute or cwd-relative path as given in the manifest. */
+  path: string;
+  /** True if the file exists on disk at bundling time. */
+  present: boolean;
+  /** Raw UTF-8 byte length on disk. 0 when present=false. */
+  raw_bytes: number;
+  /** File content, with markdown-aware truncation applied when > 8 KiB. Empty string when present=false. */
+  content: string;
+  /** Byte length of .content (post-truncation). */
+  content_bytes: number;
+  /** Number of lines stripped by truncation; 0 when file was <= 8 KiB. */
+  truncated_lines: number;
+}
+
+/**
+ * Typed context bundle returned by {@link buildContextBundle}. Consumed by
+ * pipeline-runner (21-05), explore-parallel-runner (21-06),
+ * discuss-parallel-runner (21-07), and init (21-08).
+ */
+export interface ContextBundle {
+  stage: Stage;
+  /** Ordered list of files for this stage (manifest order preserved). */
+  files: ContextFile[];
+  /** Total .content_bytes summed across files. Used by pipeline-runner for budget preview. */
+  total_bytes: number;
+  /** ISO 8601 timestamp when bundle was built. */
+  built_at: string;
+}
+
+/**
+ * Options accepted by {@link buildContextBundle}. Every field is optional;
+ * default cwd is `process.cwd()` and default threshold is 8192 bytes.
+ */
+export interface BundleOptions {
+  /** Repo root / working directory; defaults to process.cwd(). */
+  cwd?: string;
+  /** Override 8 KiB truncation threshold (bytes). Default 8192. */
+  truncationThresholdBytes?: number;
+  /** When true, throw on any missing manifest file instead of recording present:false. */
+  strict?: boolean;
+}