@hegemonart/get-design-done 1.24.2 → 1.25.0

package/scripts/lib/gdd-state/parser.ts

@@ -31,6 +31,9 @@ import {
   isConnectionStatus,
   isDecisionStatus,
   isMustHaveStatus,
+  isPrototypingEntryStatus,
+  isQualityGateStatus,
+  isSpikeVerdict,
   type Blocker,
   type ConnectionStatus,
   type Decision,
@@ -40,13 +43,34 @@ import {
   type MustHaveStatus,
   type ParsedState,
   type Position,
+  type PrototypingBlock,
+  type PrototypingEntryStatus,
+  type QualityGateBlock,
+  type QualityGateRun,
+  type QualityGateStatus,
+  type SketchEntry,
+  type SkippedEntry,
+  type SpikeEntry,
+  type SpikeVerdict,
 } from './types.ts';
 
-/** Block names recognized by the parser in canonical order. */
+/** Block names recognized by the parser in canonical order.
+ *
+ * Phase 25 Plan 25-01 inserted `prototyping` between `must_haves` and
+ * `connections` (matches the position chosen for STATE-TEMPLATE.md). The
+ * block is OPTIONAL — most fresh files don't carry it, so the serializer
+ * omits the block entirely when `state.prototyping === null`.
+ *
+ * Phase 25 Plan 25-03 inserted `quality_gate` immediately after
+ * `prototyping` (the two are conceptually related — both are
+ * checkpoint-style blocks that surface mid-pipeline gate outcomes). Same
+ * optionality rules as `prototyping`. */
 export const BLOCK_ORDER = [
   'position',
   'decisions',
   'must_haves',
+  'prototyping',
+  'quality_gate',
   'connections',
   'blockers',
   'parallelism_decision',
@@ -62,6 +86,8 @@ export interface RawBlockBodies {
   position: string | null;
   decisions: string | null;
   must_haves: string | null;
+  prototyping: string | null;
+  quality_gate: string | null;
   connections: string | null;
   blockers: string | null;
   parallelism_decision: string | null;
@@ -77,6 +103,8 @@ export interface BlockGaps {
   position: string;
   decisions: string;
   must_haves: string;
+  prototyping: string;
+  quality_gate: string;
   connections: string;
   blockers: string;
   parallelism_decision: string;
@@ -106,6 +134,8 @@ const EMPTY_RAW_BODIES: RawBlockBodies = {
   position: null,
   decisions: null,
   must_haves: null,
+  prototyping: null,
+  quality_gate: null,
   connections: null,
   blockers: null,
   parallelism_decision: null,
@@ -193,6 +223,8 @@ export function parse(raw: string): ParseResult {
     position: '',
     decisions: '',
     must_haves: '',
+    prototyping: '',
+    quality_gate: '',
     connections: '',
     blockers: '',
     parallelism_decision: '',
@@ -244,6 +276,8 @@ export function parse(raw: string): ParseResult {
   let blockers: Blocker[] = [];
   let parallelism_decision: string | null = null;
   let todos: string | null = null;
+  let prototyping: PrototypingBlock | null = null;
+  let quality_gate: QualityGateBlock | null = null;
   let timestamps: Record<string, string> = {};
 
   for (const blk of blocks) {
@@ -262,6 +296,12 @@ export function parse(raw: string): ParseResult {
       case 'must_haves':
         must_haves = parseMustHavesBody(rawBody, fileLineOfBody);
         break;
+      case 'prototyping':
+        prototyping = parsePrototypingBody(rawBody, fileLineOfBody);
+        break;
+      case 'quality_gate':
+        quality_gate = parseQualityGateBody(rawBody, fileLineOfBody);
+        break;
       case 'connections':
         connections = parseConnectionsBody(rawBody, fileLineOfBody);
         break;
@@ -305,6 +345,8 @@ export function parse(raw: string): ParseResult {
     blockers,
     parallelism_decision,
     todos,
+    prototyping,
+    quality_gate,
     timestamps,
     body_preamble,
     body_trailer,
@@ -504,6 +546,314 @@ function parseBlockersBody(body: string, startLine: number): Blocker[] {
   return out;
 }
 
+/**
+ * Parse the body of a `<prototyping>` block (Phase 25 Plan 25-01 / D-01).
+ *
+ * Recognized self-closing children (each on its own line, attribute order
+ * tolerant, unknown attributes preserved into `extra_attrs` for forward
+ * compat):
+ *   <sketch slug=… cycle=… decision=D-XX status=resolved/>
+ *   <spike slug=… cycle=… decision=D-XX verdict=yes|no|partial status=resolved/>
+ *   <skipped at=… cycle=… reason=…/>
+ *
+ * Lines that are blank, HTML comments, or unrecognized self-closing tags
+ * are tolerated (forward-compat). Required attributes that are missing or
+ * carry an invalid enum value throw `ParseError` so operators see a real
+ * problem instead of a silent drop.
+ */
+function parsePrototypingBody(body: string, startLine: number): PrototypingBlock {
+  const sketches: SketchEntry[] = [];
+  const spikes: SpikeEntry[] = [];
+  const skipped: SkippedEntry[] = [];
+  const lines = body.split('\n');
+  // Match an XML-ish self-closing tag: `<name attr=value attr="quoted"/>`.
+  // We capture the tag name and the attribute span; attributes are split
+  // by `parsePrototypingAttrs` (handles both quoted and bare values).
+  const selfClose = /^<([a-z_]+)(\s+[^>]*?)?\s*\/>\s*$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] ?? '').trim();
+    if (line === '' || line.startsWith('<!--')) continue;
+    const m = line.match(selfClose);
+    if (!m) {
+      // Unknown shape inside the block — tolerate (forward-compat). Don't
+      // throw; downstream sketch/spike-wrap-up flows may add new child
+      // tags before the parser learns about them.
+      continue;
+    }
+    const tag = m[1] ?? '';
+    const attrs = parsePrototypingAttrs(m[2] ?? '');
+    const fileLine = startLine + i;
+    if (tag === 'sketch') {
+      sketches.push(buildSketchEntry(attrs, fileLine));
+    } else if (tag === 'spike') {
+      spikes.push(buildSpikeEntry(attrs, fileLine));
+    } else if (tag === 'skipped') {
+      skipped.push(buildSkippedEntry(attrs, fileLine));
+    }
+    // else: unknown self-closing tag inside <prototyping> — ignore.
+  }
+  return { sketches, spikes, skipped };
+}
+
+/**
+ * Split a self-closing-tag attribute span into a `{name → value}` map.
+ * Handles double-quoted, single-quoted, and bare (no-whitespace) values.
+ * Unknown to whitespace tokenization is fine here because attribute names
+ * in our schema are simple identifiers.
+ */
+function parsePrototypingAttrs(span: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  // Token shape: `name="dq"`, `name='sq'`, or `name=bare`. Bare values run
+  // until the next whitespace or EOS. Greedy regex with three alternatives
+  // walks the span position-by-position.
+  const re = /([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s/>]+))/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(span)) !== null) {
+    const key = m[1] ?? '';
+    const value: string =
+      (m[2] !== undefined ? m[2] : undefined) ??
+      (m[3] !== undefined ? m[3] : undefined) ??
+      m[4] ??
+      '';
+    if (key !== '') out[key] = value;
+  }
+  return out;
+}
+
+function buildSketchEntry(
+  attrs: Record<string, string>,
+  fileLine: number,
+): SketchEntry {
+  const slug = attrs['slug'];
+  const cycle = attrs['cycle'];
+  const decision = attrs['decision'];
+  const status = attrs['status'] ?? 'resolved';
+  if (slug === undefined) {
+    throw new ParseError('<sketch/> missing required attribute slug', fileLine);
+  }
+  if (cycle === undefined) {
+    throw new ParseError('<sketch/> missing required attribute cycle', fileLine);
+  }
+  if (decision === undefined) {
+    throw new ParseError(
+      '<sketch/> missing required attribute decision',
+      fileLine,
+    );
+  }
+  if (!isPrototypingEntryStatus(status)) {
+    throw new ParseError(
+      `<sketch/> invalid status: ${status}`,
+      fileLine,
+    );
+  }
+  return {
+    slug,
+    cycle,
+    decision,
+    status: status as PrototypingEntryStatus,
+    extra_attrs: extractExtraAttrs(attrs, ['slug', 'cycle', 'decision', 'status']),
+  };
+}
+
+function buildSpikeEntry(
+  attrs: Record<string, string>,
+  fileLine: number,
+): SpikeEntry {
+  const slug = attrs['slug'];
+  const cycle = attrs['cycle'];
+  const decision = attrs['decision'];
+  const verdict = attrs['verdict'];
+  const status = attrs['status'] ?? 'resolved';
+  if (slug === undefined) {
+    throw new ParseError('<spike/> missing required attribute slug', fileLine);
+  }
+  if (cycle === undefined) {
+    throw new ParseError('<spike/> missing required attribute cycle', fileLine);
+  }
+  if (decision === undefined) {
+    throw new ParseError(
+      '<spike/> missing required attribute decision',
+      fileLine,
+    );
+  }
+  if (verdict === undefined) {
+    throw new ParseError(
+      '<spike/> missing required attribute verdict',
+      fileLine,
+    );
+  }
+  if (!isSpikeVerdict(verdict)) {
+    throw new ParseError(
+      `<spike/> invalid verdict: ${verdict}`,
+      fileLine,
+    );
+  }
+  if (!isPrototypingEntryStatus(status)) {
+    throw new ParseError(
+      `<spike/> invalid status: ${status}`,
+      fileLine,
+    );
+  }
+  return {
+    slug,
+    cycle,
+    decision,
+    verdict: verdict as SpikeVerdict,
+    status: status as PrototypingEntryStatus,
+    extra_attrs: extractExtraAttrs(attrs, [
+      'slug',
+      'cycle',
+      'decision',
+      'verdict',
+      'status',
+    ]),
+  };
+}
+
+function buildSkippedEntry(
+  attrs: Record<string, string>,
+  fileLine: number,
+): SkippedEntry {
+  const at = attrs['at'];
+  const cycle = attrs['cycle'];
+  const reason = attrs['reason'];
+  if (at === undefined) {
+    throw new ParseError('<skipped/> missing required attribute at', fileLine);
+  }
+  if (cycle === undefined) {
+    throw new ParseError(
+      '<skipped/> missing required attribute cycle',
+      fileLine,
+    );
+  }
+  if (reason === undefined) {
+    throw new ParseError(
+      '<skipped/> missing required attribute reason',
+      fileLine,
+    );
+  }
+  return {
+    at,
+    cycle,
+    reason,
+    extra_attrs: extractExtraAttrs(attrs, ['at', 'cycle', 'reason']),
+  };
+}
+
+function extractExtraAttrs(
+  all: Record<string, string>,
+  known: readonly string[],
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(all)) {
+    if (!known.includes(k)) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Parse the body of a `<quality_gate>` block (Phase 25 Plan 25-03).
+ *
+ * The block houses at most one self-closing `<run/>` element. Multiple
+ * `<run/>` lines are not part of the v1.25 schema — append-mode would
+ * be overkill (the SKILL overwrites on every gate completion). If the
+ * source carries multiple, we accept the LAST one (most recent wins) so
+ * a hand-edit that adds a newer entry above an older one still parses
+ * sensibly. Lines that are blank or HTML comments are tolerated.
+ *
+ * Required attributes: `started_at`, `completed_at`, `status`,
+ * `iteration`, `commands_run`. Missing attributes throw `ParseError` so
+ * operators see the problem (mirrors prototyping behavior). `iteration`
+ * must parse as a finite non-negative integer.
+ */
+function parseQualityGateBody(body: string, startLine: number): QualityGateBlock {
+  let run: QualityGateRun | null = null;
+  const lines = body.split('\n');
+  const selfClose = /^<([a-z_]+)(\s+[^>]*?)?\s*\/>\s*$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] ?? '').trim();
+    if (line === '' || line.startsWith('<!--')) continue;
+    const m = line.match(selfClose);
+    if (!m) {
+      // Forward-compat: tolerate unknown shapes inside the block.
+      continue;
+    }
+    const tag = m[1] ?? '';
+    if (tag !== 'run') continue; // forward-compat for unknown child tags
+    const attrs = parsePrototypingAttrs(m[2] ?? '');
+    run = buildQualityGateRun(attrs, startLine + i);
+  }
+  return { run };
+}
+
+function buildQualityGateRun(
+  attrs: Record<string, string>,
+  fileLine: number,
+): QualityGateRun {
+  const started_at = attrs['started_at'];
+  const completed_at = attrs['completed_at'];
+  const status = attrs['status'];
+  const iterationRaw = attrs['iteration'];
+  const commands_run = attrs['commands_run'];
+  if (started_at === undefined) {
+    throw new ParseError(
+      '<quality_gate> <run/> missing required attribute started_at',
+      fileLine,
+    );
+  }
+  if (completed_at === undefined) {
+    throw new ParseError(
+      '<quality_gate> <run/> missing required attribute completed_at',
+      fileLine,
+    );
+  }
+  if (status === undefined) {
+    throw new ParseError(
+      '<quality_gate> <run/> missing required attribute status',
+      fileLine,
+    );
+  }
+  if (!isQualityGateStatus(status)) {
+    throw new ParseError(
+      `<quality_gate> <run/> invalid status: ${status}`,
+      fileLine,
+    );
+  }
+  if (iterationRaw === undefined) {
+    throw new ParseError(
+      '<quality_gate> <run/> missing required attribute iteration',
+      fileLine,
+    );
+  }
+  const iteration = Number(iterationRaw);
+  if (!Number.isFinite(iteration) || !Number.isInteger(iteration) || iteration < 0) {
+    throw new ParseError(
+      `<quality_gate> <run/> iteration not a non-negative integer: ${iterationRaw}`,
+      fileLine,
+    );
+  }
+  if (commands_run === undefined) {
+    throw new ParseError(
+      '<quality_gate> <run/> missing required attribute commands_run',
+      fileLine,
+    );
+  }
+  return {
+    started_at,
+    completed_at,
+    status: status as QualityGateStatus,
+    iteration,
+    commands_run,
+    extra_attrs: extractExtraAttrs(attrs, [
+      'started_at',
+      'completed_at',
+      'status',
+      'iteration',
+      'commands_run',
+    ]),
+  };
+}
+
 function parseTimestampsBody(
   body: string,
   _startLine: number,

package/scripts/lib/gdd-state/types.ts

@@ -36,6 +36,23 @@ export type DecisionStatus = 'locked' | 'tentative';
 /** Verification state for a `<must_haves>` entry. */
 export type MustHaveStatus = 'pending' | 'pass' | 'fail';
 
+/**
+ * Verdict for a `<spike>` entry — the answer the spike produced.
+ * Phase 25 Plan 25-01: spikes resolve a "can this work?" question with one
+ * of three outcomes. `partial` means the spike answered for some cases but
+ * not all (e.g., works on one platform, not another).
+ */
+export type SpikeVerdict = 'yes' | 'no' | 'partial';
+
+/**
+ * Resolution status for a sketch or spike entry. Phase 25 keeps the surface
+ * minimal — `resolved` is the only value v1.25 writes (sketches and spikes
+ * either complete and produce a D-XX, or they get a `<skipped/>` entry).
+ * Kept as a string union to leave room for `pending`/`abandoned` later
+ * without a parser change.
+ */
+export type PrototypingEntryStatus = 'resolved';
+
 /**
  * Frontmatter block (between leading `---` fences). STATE.md frontmatter is
  * flat `key: value` — we parse it with a tiny hand-rolled reader (no YAML
@@ -90,6 +107,77 @@ export interface Blocker {
   text: string;
 }
 
+/**
+ * Single `<sketch/>` child entry inside the `<prototyping>` block.
+ *
+ * Phase 25 Plan 25-01 (D-01): a sketch records a resolved exploration of a
+ * visual / direction question. The wrap-up flow (Plan 25-05) writes the
+ * resolution as a D-XX decision AND appends a `<sketch slug=… cycle=…
+ * decision=D-XX status=resolved/>` entry here so the decision-injector
+ * (Plan 25-06) can surface prior sketch outcomes to downstream agents.
+ *
+ * Unknown attributes seen by the parser are preserved in `extra_attrs` so
+ * forward-compat additions (e.g., a future `confidence=` attribute) round-
+ * trip through parse → serialize without loss.
+ */
+export interface SketchEntry {
+  slug: string;
+  cycle: string;
+  decision: string;
+  status: PrototypingEntryStatus;
+  /** Verbatim copy of any attributes the parser did not recognize. Keys
+   *  are attribute names; values are the unquoted attribute strings. */
+  extra_attrs: Record<string, string>;
+}
+
+/**
+ * Single `<spike/>` child entry inside the `<prototyping>` block.
+ *
+ * Phase 25 Plan 25-01 (D-01): a spike records a resolved feasibility
+ * probe. The `verdict` field captures the answer (`yes` / `no` /
+ * `partial`); the `decision` field links to the D-XX written by
+ * `spike-wrap-up` (Plan 25-05).
+ */
+export interface SpikeEntry {
+  slug: string;
+  cycle: string;
+  decision: string;
+  verdict: SpikeVerdict;
+  status: PrototypingEntryStatus;
+  /** Forward-compat passthrough — same semantics as on `SketchEntry`. */
+  extra_attrs: Record<string, string>;
+}
+
+/**
+ * Single `<skipped/>` child entry inside the `<prototyping>` block.
+ *
+ * Phase 25 Plan 25-01 (D-02): cycle-scoped suppression of further prototype
+ * gate prompts. `at` is the firing point that was skipped (typically
+ * `explore` or `plan`); `cycle` mirrors the active cycle id; `reason` is a
+ * short free-form string captured at skip time.
+ */
+export interface SkippedEntry {
+  at: string;
+  cycle: string;
+  reason: string;
+  /** Forward-compat passthrough — same semantics as on `SketchEntry`. */
+  extra_attrs: Record<string, string>;
+}
+
+/**
+ * Parsed `<prototyping>` block. `null` on `ParsedState` when the block is
+ * absent; an instance with all three arrays empty represents a present-but-
+ * empty block (rare — wrap-up flows always append something).
+ *
+ * The three arrays preserve insertion order — round-trip serialization
+ * emits children in the same order they appeared in the source file.
+ */
+export interface PrototypingBlock {
+  sketches: SketchEntry[];
+  spikes: SpikeEntry[];
+  skipped: SkippedEntry[];
+}
+
 /**
  * Canonical parsed shape of a STATE.md file. Consumers mutate this in-place
  * inside `mutate(path, fn)`, then the serializer projects it back to
@@ -115,6 +203,24 @@ export interface ParsedState {
    * with illustrative comments, so most fresh files carry a non-null body.
    */
   todos: string | null;
+  /**
+   * Parsed `<prototyping>` block (Phase 25 Plan 25-01 / D-01). `null` when
+   * the block is absent in the source — the serializer omits the block
+   * entirely in that case rather than emitting an empty `<prototyping>`
+   * pair. A non-null instance with all three arrays empty is permitted
+   * but only emitted when the source already had a present-but-empty
+   * block (preserves byte-identical round-trip).
+   */
+  prototyping: PrototypingBlock | null;
+  /**
+   * Parsed `<quality_gate>` block (Phase 25 Plan 25-03 / D-06..D-09).
+   * `null` when the block is absent in the source — the serializer omits
+   * the block entirely in that case rather than emitting an empty
+   * `<quality_gate>` pair. A non-null instance with `run === null` is
+   * permitted but only emitted when the source already had a present-but-
+   * empty block (preserves byte-identical round-trip).
+   */
+  quality_gate: QualityGateBlock | null;
   timestamps: Record<string, string>;
   /** Verbatim span between frontmatter end and the first recognized block. */
   body_preamble: string;
@@ -177,3 +283,90 @@ export function isDecisionStatus(value: unknown): value is DecisionStatus {
 export function isMustHaveStatus(value: unknown): value is MustHaveStatus {
   return value === 'pending' || value === 'pass' || value === 'fail';
 }
+
+/** Type-guard for `SpikeVerdict`. */
+export function isSpikeVerdict(value: unknown): value is SpikeVerdict {
+  return value === 'yes' || value === 'no' || value === 'partial';
+}
+
+/** Type-guard for `PrototypingEntryStatus`. */
+export function isPrototypingEntryStatus(
+  value: unknown,
+): value is PrototypingEntryStatus {
+  return value === 'resolved';
+}
+
+/**
+ * Status of a `<quality_gate>` run (Phase 25 Plan 25-03 / D-06..D-09).
+ *
+ * - `pass`     — every detected command exited 0 within the timeout budget.
+ * - `fail`     — at least one command failed AND the fix loop reached
+ *                `max_iters` without producing a clean run. Verify entry
+ *                refuses on this status (Plan 25-07 territory).
+ * - `timeout`  — the parallel command run exceeded
+ *                `quality_gate.timeout_seconds`. Treated as a non-blocking
+ *                warning per D-07 — verify entry warns, does not refuse.
+ * - `skipped`  — the detection chain (D-06) resolved zero commands. The
+ *                gate emits a notice and continues; verify entry does not
+ *                block on `skipped`.
+ */
+export type QualityGateStatus = 'pass' | 'fail' | 'timeout' | 'skipped';
+
+/**
+ * Single resolved run captured in the `<quality_gate>` block (Phase 25
+ * Plan 25-03 / D-06..D-09). Append-mode would be overkill — only the most
+ * recent run is retained. The wrap-up flow (the SKILL's Step 5) overwrites
+ * this entry on every gate completion.
+ *
+ * Shape mirrors the corresponding `<run …/>` self-closing tag attribute set:
+ *   `<run started_at=… completed_at=… status=… iteration=N commands_run="lint,typecheck,test"/>`
+ *
+ * `commands_run` is a comma-separated list rather than a `string[]` so the
+ * STATE block stays a single self-closing tag — no nested children, no
+ * order ambiguity in serialization.
+ *
+ * Unknown attributes seen on the `<run/>` tag are preserved in `extra_attrs`
+ * for forwards-compat (mirrors the prototyping pattern).
+ */
+export interface QualityGateRun {
+  /** ISO 8601 timestamp at which Step 2 (parallel run) entered. */
+  started_at: string;
+  /** ISO 8601 timestamp at which the gate produced its terminal status. */
+  completed_at: string;
+  /** Terminal status emitted by Step 6 (event emission). */
+  status: QualityGateStatus;
+  /**
+   * Loop count from Step 4 (fix loop). `1` = single clean pass; `2..N` =
+   * required at least one fixer iteration; `N === max_iters` with
+   * `status === 'fail'` = bounded exhaustion.
+   */
+  iteration: number;
+  /**
+   * Comma-separated list of command names actually executed in Step 2 —
+   * e.g. `"lint,typecheck,test"`. Empty string when `status === 'skipped'`.
+   */
+  commands_run: string;
+  /** Forward-compat passthrough — same semantics as on `SketchEntry`. */
+  extra_attrs: Record<string, string>;
+}
+
+/**
+ * Parsed `<quality_gate>` block. The block houses a single most-recent
+ * `<run/>` entry; `null` on `ParsedState` means the block is absent in the
+ * source (no gate has run yet on this STATE.md). `run === null` inside a
+ * non-null block represents a present-but-empty block (rare — the SKILL
+ * always writes a `<run/>` before closing).
+ */
+export interface QualityGateBlock {
+  run: QualityGateRun | null;
+}
+
+/** Type-guard for `QualityGateStatus`. */
+export function isQualityGateStatus(value: unknown): value is QualityGateStatus {
+  return (
+    value === 'pass' ||
+    value === 'fail' ||
+    value === 'timeout' ||
+    value === 'skipped'
+  );
+}