@hegemonart/get-design-done 1.19.5 → 1.20.0

package/scripts/lib/gdd-errors/index.ts

@@ -0,0 +1,218 @@
+// scripts/lib/gdd-errors/index.ts — unified GDD error taxonomy.
+//
+// Three classes exactly — mirrors the GSD errors.ts discipline:
+//
+//   * ValidationError       — throw at boundary; "fix your input"
+//   * StateConflictError    — throw; lockfile contention or transition guard
+//                             failed; retryable by upstream
+//   * OperationFailedError  — return in data.error; "couldn't complete in
+//                             this state"; expected failure mode the caller
+//                             should branch on, not crash on
+//
+// MCP tool handlers place OperationFailedError instances into data.error
+// so the model can see and reason about them. ValidationError and
+// StateConflictError are thrown (non-zero exit path).
+//
+// Plan 20-01 introduced LockAcquisitionError and TransitionGateFailed as
+// local Error subclasses; this module re-exports taxonomy-compliant
+// versions so the existing `gdd-state` surface (tests + consumers) keeps
+// working unchanged. Plan 20-05 wires `toToolError` into MCP tool
+// handlers; Plan 20-06 emits error events to the telemetry stream.
+
+/** Short machine-readable code. Example: "VALIDATION_MISSING_FIELD". */
+export type GDDErrorCode = string;
+
+/**
+ * Abstract base class — every GDD taxonomy error inherits from this.
+ *
+ * Subclasses set a literal `kind` discriminant so `classify()` can
+ * branch on it without `instanceof` chains, and `toJSON()` produces a
+ * lossless payload for tool-result transport.
+ */
+export abstract class GDDError extends Error {
+  abstract readonly kind: 'validation' | 'state_conflict' | 'operation_failed';
+  readonly code: GDDErrorCode;
+  readonly context: Readonly<Record<string, unknown>>;
+
+  constructor(
+    message: string,
+    code: GDDErrorCode,
+    context: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.code = code;
+    this.context = Object.freeze({ ...context });
+    // Set .name to the concrete subclass name (LockAcquisitionError,
+    // ValidationError, etc.) so error serialization is human-meaningful.
+    this.name = new.target.name;
+  }
+
+  /**
+   * Serialize to a plain object safe for JSON.stringify. Round-trips
+   * through JSON without loss of `name`, `kind`, `code`, `message`, or
+   * `context`. Does NOT include the stack trace — MCP tool handlers do
+   * not forward stacks to the model.
+   */
+  toJSON(): {
+    name: string;
+    kind: GDDError['kind'];
+    code: GDDErrorCode;
+    message: string;
+    context: Readonly<Record<string, unknown>>;
+  } {
+    return {
+      name: this.name,
+      kind: this.kind,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+    };
+  }
+}
+
+/**
+ * Throw at boundary when the caller's input is malformed.
+ *
+ * Example: MCP tool handler receives an argument that fails schema
+ * validation; the correct response is `throw new ValidationError(...)`
+ * so the harness catches it and returns a structured error to the model.
+ * The model should fix its input and retry.
+ */
+export class ValidationError extends GDDError {
+  readonly kind = 'validation' as const;
+  constructor(
+    message: string,
+    code: GDDErrorCode = 'VALIDATION',
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, context);
+  }
+}
+
+/**
+ * Throw when a concurrency primitive or transition guard vetoes the
+ * operation. Retryable by upstream — the caller may try again after a
+ * backoff, or surface the blocker to the operator.
+ *
+ * Examples: lockfile contention (LockAcquisitionError), transition
+ * gate failure (TransitionGateFailed).
+ */
+export class StateConflictError extends GDDError {
+  readonly kind = 'state_conflict' as const;
+  constructor(
+    message: string,
+    code: GDDErrorCode = 'STATE_CONFLICT',
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, context);
+  }
+}
+
+/**
+ * Return as `data.error` — do NOT throw. This is the expected failure
+ * mode the caller should branch on: the operation is well-formed, the
+ * state is valid, but the specific request cannot complete right now.
+ *
+ * Example: "try to advance to `design`, but no plan exists yet" — the
+ * model should be told, not crashed on.
+ */
+export class OperationFailedError extends GDDError {
+  readonly kind = 'operation_failed' as const;
+  constructor(
+    message: string,
+    code: GDDErrorCode = 'OPERATION_FAILED',
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, context);
+  }
+}
+
+// -----------------------------------------------------------------------
+// Plan 20-01 compatibility re-exports.
+//
+// These keep the `gdd-state` module's public surface stable post-refactor:
+// - LockAcquisitionError — lockfile contention (plan 20-01 lockfile.ts)
+// - TransitionGateFailed — transition gate veto (plan 20-01 transition())
+// Both are StateConflictError subclasses (retryable / contention-class
+// errors).
+// -----------------------------------------------------------------------
+
+/**
+ * Error thrown when `acquire()` cannot obtain the lockfile within
+ * `maxWaitMs`. Carries the contents of the offending lockfile (as
+ * text — may be JSON, may be garbage if corrupted) so callers can
+ * surface them to operators.
+ *
+ * The `lockPath` and `lockContents` instance properties are preserved
+ * from the Plan 20-01 shape for API compat; they're also stored in
+ * the frozen `context` object for uniform GDDError serialization.
+ */
+export class LockAcquisitionError extends StateConflictError {
+  readonly lockPath: string;
+  readonly lockContents: string;
+  readonly waitedMs: number;
+  constructor(
+    lockPath: string,
+    lockContents: string,
+    waitedMs: number,
+    context?: Record<string, unknown>,
+  ) {
+    super(
+      `failed to acquire lock at ${lockPath} after ${waitedMs}ms; current holder: ${lockContents}`,
+      'LOCK_ACQUISITION',
+      { ...context, lockPath, lockContents, waitedMs },
+    );
+    this.lockPath = lockPath;
+    this.lockContents = lockContents;
+    this.waitedMs = waitedMs;
+  }
+}
+
+/**
+ * Error thrown when a transition gate vetoes a stage advance. Carries
+ * the frozen list of blocker messages so callers can surface them to
+ * operators or retry after resolving.
+ *
+ * The `blockers` instance property is preserved from the Plan 20-01
+ * shape (readonly string[]) for API compat; it's also mirrored into
+ * the frozen `context` object for uniform GDDError serialization.
+ */
+export class TransitionGateFailed extends StateConflictError {
+  readonly blockers: readonly string[];
+  readonly toStage: string;
+  constructor(
+    toStage: string,
+    blockers: string[],
+    context?: Record<string, unknown>,
+  ) {
+    super(
+      `transition to "${toStage}" blocked by gate: ${blockers.join('; ') || '(no detail)'}`,
+      'TRANSITION_GATE_FAILED',
+      { ...context, toStage, blockers: [...blockers] },
+    );
+    this.toStage = toStage;
+    this.blockers = Object.freeze([...blockers]);
+  }
+}
+
+/**
+ * Error thrown by STATE.md `parse()` when the input cannot be
+ * interpreted. `ValidationError` semantics: the caller (likely the
+ * operator or an upstream generator) gave us malformed input — fix
+ * your STATE.md and retry.
+ *
+ * The `line` instance property points at the 1-indexed line in the
+ * source markdown where the parser gave up. It's also mirrored into
+ * the frozen `context` object.
+ */
+export class ParseError extends ValidationError {
+  readonly line: number;
+  constructor(message: string, line: number, context?: Record<string, unknown>) {
+    super(
+      `STATE.md parse error at line ${line}: ${message}`,
+      'PARSE_ERROR',
+      { ...context, line },
+    );
+    this.line = line;
+  }
+}

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

@@ -0,0 +1,216 @@
+// scripts/lib/gdd-state/gates.ts — pure transition-gate functions.
+//
+// Plan 20-02 (SDK-03): the typed, single-source-of-truth implementation
+// of "can this pipeline advance?" that replaces prose-encoded guards in
+// each stage's SKILL.md. Each gate is a pure function of a `ParsedState`
+// and returns `{ pass, blockers }` — never throws, never does I/O, never
+// reads the clock or random state. Deterministic for a given input.
+//
+// Gate semantics (distilled from the current SKILL.md guards):
+//
+//   briefToExplore
+//     Stage-parity check: `frontmatter.stage === 'brief'` AND
+//     `position.stage === 'brief'`. No file-existence checks — gates are
+//     pure; `.design/BRIEF.md` presence is verified by the caller.
+//
+//   exploreToPlan
+//     Stage-parity on 'explore'. Additionally `connections` map MUST
+//     have at least one entry with status `available` OR `not_configured`
+//     (i.e., the probe ran and populated the map). An empty connections
+//     map means the probe never ran — fail with an actionable blocker.
+//
+//   planToDesign
+//     Stage-parity on 'plan'. `must_haves` MUST be non-empty (at minimum
+//     M-01 exists). `decisions` MUST contain ≥1 `locked` entry. Any
+//     `must_haves` entry with `status: fail` MUST have a matching
+//     `decisions` entry to reconcile it — otherwise fail with
+//     "M-XX marked fail without a decision to reconcile".
+//
+//   designToVerify
+//     Stage-parity on 'design'. `must_haves` MUST NOT contain any entry
+//     with `status: pending` whose text references a design-stage
+//     deliverable (keywords: `component`, `token`, `style`, `copy`,
+//     `layout`). Pending entries outside that vocabulary are verify-stage
+//     responsibilities and are allowed through.
+//
+// Invalid transitions (e.g., brief→verify skipping explore/plan/design,
+// or verify→verify no-op, or anything not in the forward chain) return
+// `null` from `gateFor()`. The caller turns `null` into a
+// `TransitionGateFailed` with an "Invalid transition" message.
+
+import type { ParsedState, Stage } from './types.ts';
+
+/**
+ * Result of a single gate invocation.
+ *
+ * When `pass === true`, `blockers` is `[]`. When `pass === false`,
+ * `blockers` has ≥1 entry and each entry is a non-empty, human-readable
+ * one-line reason suitable for surfacing to operators.
+ */
+export interface GateResult {
+  pass: boolean;
+  blockers: string[];
+}
+
+/** Signature every gate satisfies. Pure — no I/O, no clock, no randomness. */
+export type GateFn = (state: ParsedState) => GateResult;
+
+/**
+ * Keywords whose presence in a pending `must_haves` line marks the item
+ * as a design-stage deliverable (must be resolved BEFORE verify). Kept
+ * lowercase-matched on the full text so phrasing like "Primary CTA
+ * component" or "color token" both hit.
+ *
+ * Adjust in lockstep with the designToVerify prose-guard removal in
+ * Plans 20-07 through 20-11 — the keyword set there must match this one.
+ */
+const DESIGN_KEYWORDS = ['component', 'token', 'style', 'copy', 'layout'] as const;
+
+/**
+ * Shared parity helper — every gate requires the frontmatter + position
+ * stages to agree with the expected FROM stage. Returns `null` on pass
+ * (so the caller can keep going) or a blocker string on fail.
+ */
+function stageParity(state: ParsedState, expected: Stage): string | null {
+  if (!state.position || typeof state.position.stage !== 'string') {
+    return 'position block missing or malformed';
+  }
+  if (!state.frontmatter || typeof state.frontmatter.stage !== 'string') {
+    return 'frontmatter stage missing or malformed';
+  }
+  if (state.position.stage !== expected) {
+    return `position.stage is "${state.position.stage}" — expected "${expected}"`;
+  }
+  if (state.frontmatter.stage !== expected) {
+    return `frontmatter.stage is "${state.frontmatter.stage}" — expected "${expected}"`;
+  }
+  return null;
+}
+
+/**
+ * Brief → Explore: only a stage-parity check.
+ *
+ * `.design/BRIEF.md` existence is verified by the calling skill — gates
+ * are pure and cannot touch the filesystem.
+ */
+export const briefToExplore: GateFn = (s) => {
+  const blockers: string[] = [];
+  const parity = stageParity(s, 'brief');
+  if (parity) blockers.push(parity);
+  return { pass: blockers.length === 0, blockers };
+};
+
+/**
+ * Explore → Plan: stage parity + non-empty connections map.
+ *
+ * An empty `<connections>` map (no keys at all) means the explore-stage
+ * probe never ran. We require at least one entry so we can assert the
+ * probe wrote something — the value can be `available` or
+ * `not_configured`; both are evidence of a real probe result.
+ * `unavailable` alone also counts (probe ran, service down).
+ */
+export const exploreToPlan: GateFn = (s) => {
+  const blockers: string[] = [];
+  const parity = stageParity(s, 'explore');
+  if (parity) blockers.push(parity);
+  const connKeys = Object.keys(s.connections ?? {});
+  if (connKeys.length === 0) {
+    blockers.push(
+      'connections map is empty — run the explore-stage probe before advancing',
+    );
+  }
+  return { pass: blockers.length === 0, blockers };
+};
+
+/**
+ * Plan → Design: stage parity + must_haves non-empty + ≥1 locked
+ * decision + every `status: fail` must_have is reconciled by a matching
+ * decision ID.
+ *
+ * Matching rule for reconciliation: a `must_haves` entry `M-XX` with
+ * `status: fail` is considered reconciled when ANY `decisions` entry's
+ * `text` mentions the substring `M-XX`. This is the convention used in
+ * the current SKILL.md prose ("D-03 reconciles M-05 by …"); it is not
+ * a structural link yet — Plan 20-08 may promote it to a typed field.
+ */
+export const planToDesign: GateFn = (s) => {
+  const blockers: string[] = [];
+  const parity = stageParity(s, 'plan');
+  if (parity) blockers.push(parity);
+  if ((s.must_haves ?? []).length === 0) {
+    blockers.push('must_haves is empty — discover stage must land at least M-01');
+  }
+  const hasLocked = (s.decisions ?? []).some((d) => d.status === 'locked');
+  if (!hasLocked) {
+    blockers.push('no locked decision in <decisions> — at least one must be locked');
+  }
+  const failing = (s.must_haves ?? []).filter((m) => m.status === 'fail');
+  for (const mh of failing) {
+    const reconciled = (s.decisions ?? []).some((d) => d.text.includes(mh.id));
+    if (!reconciled) {
+      blockers.push(`${mh.id} marked fail without a decision to reconcile`);
+    }
+  }
+  return { pass: blockers.length === 0, blockers };
+};
+
+/**
+ * Design → Verify: stage parity + no pending must_haves whose text
+ * references a design-stage deliverable.
+ *
+ * Pending items outside the design-keyword set are verify-stage
+ * responsibilities (e.g., "ARIA live region announcement") and are
+ * allowed through.
+ */
+export const designToVerify: GateFn = (s) => {
+  const blockers: string[] = [];
+  const parity = stageParity(s, 'design');
+  if (parity) blockers.push(parity);
+  const pending = (s.must_haves ?? []).filter((m) => m.status === 'pending');
+  for (const mh of pending) {
+    const lower = mh.text.toLowerCase();
+    const hit = DESIGN_KEYWORDS.find((kw) => lower.includes(kw));
+    if (hit) {
+      blockers.push(
+        `${mh.id} is pending and mentions "${hit}" — resolve in design before verify`,
+      );
+    }
+  }
+  return { pass: blockers.length === 0, blockers };
+};
+
+/**
+ * Registry of every gate keyed by `${from}To${Capitalize<to>}`. Frozen
+ * so downstream callers cannot mutate the gate set at runtime.
+ */
+export const GATES: Readonly<{
+  briefToExplore: GateFn;
+  exploreToPlan: GateFn;
+  planToDesign: GateFn;
+  designToVerify: GateFn;
+}> = Object.freeze({
+  briefToExplore,
+  exploreToPlan,
+  planToDesign,
+  designToVerify,
+});
+
+/**
+ * Pick the gate for a source → target transition.
+ *
+ * Returns `null` for:
+ *   - skip-stage transitions (e.g., `brief → verify`),
+ *   - backward transitions (e.g., `explore → brief`),
+ *   - same-stage transitions (e.g., `verify → verify`),
+ *   - any transition whose `from` or `to` is outside the `Stage` union.
+ *
+ * The caller (`transition()` in `index.ts`) converts a `null` response
+ * into a `TransitionGateFailed` carrying an "Invalid transition" message.
+ */
+export function gateFor(from: Stage, to: Stage): GateFn | null {
+  if (from === 'brief' && to === 'explore') return briefToExplore;
+  if (from === 'explore' && to === 'plan') return exploreToPlan;
+  if (from === 'plan' && to === 'design') return planToDesign;
+  if (from === 'design' && to === 'verify') return designToVerify;
+  return null;
+}

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

@@ -0,0 +1,167 @@
+// scripts/lib/gdd-state/index.ts — public API for the gdd-state module.
+//
+// This is the ONLY file consumers should import from. The module exposes
+// exactly five surface-level names:
+//   * read(path)                    — parse STATE.md from disk
+//   * mutate(path, fn)              — atomic read-modify-write under a lock
+//   * transition(path, toStage)     — gate + stage-advance helper
+//   * ParsedState (type)            — consumer-visible shape
+//   * Stage (type)                  — stage enum
+//
+// Plan 20-02 wired the real transition gates in via `gateFor(from, to)`
+// imported from `./gates.ts`. Plan 20-04 migrated the error classes
+// (TransitionGateFailed, LockAcquisitionError, ParseError) to the
+// unified `gdd-errors` taxonomy — `types.ts` re-exports them verbatim
+// so consumers of `gdd-state` need no changes.
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+
+import { acquire } from './lockfile.ts';
+import { parse } from './parser.ts';
+import { serialize } from './mutator.ts';
+import { gateFor } from './gates.ts';
+import {
+  TransitionGateFailed,
+  isStage,
+  type ParsedState,
+  type Stage,
+  type TransitionResult,
+} from './types.ts';
+
+export type { ParsedState, Stage } from './types.ts';
+export { TransitionGateFailed, LockAcquisitionError, ParseError } from './types.ts';
+
+/**
+ * Read STATE.md from disk and return the parsed state.
+ *
+ * Shared-read: no lock is taken. Reads are snapshot-safe for markdown
+ * (the OS guarantees a coherent view even if a writer is mid-rename —
+ * we either see the old file or the new file, never a torn write,
+ * because `mutate()` uses atomic rename).
+ */
+export async function read(path: string): Promise<ParsedState> {
+  const raw: string = readFileSync(path, 'utf8');
+  return parse(raw).state;
+}
+
+/**
+ * Atomic read-modify-write on STATE.md.
+ *
+ * Flow:
+ *   1. Acquire sibling `.lock` file (PID+timestamp advisory lock).
+ *   2. Read current contents.
+ *   3. Apply `fn`.
+ *   4. Serialize to a `.tmp` file next to `path`.
+ *   5. `renameSync(.tmp, path)` — POSIX-atomic; on Windows EPERM means
+ *      a scanner held it briefly, retry once.
+ *   6. Release the lock (in `finally` — released even on mid-fn throw).
+ *
+ * Crash between write and rename is benign: STATE.md is untouched; the
+ * `.tmp` file is orphaned (cleaned up on the next acquire by the caller).
+ */
+export async function mutate(
+  path: string,
+  fn: (s: ParsedState) => ParsedState,
+): Promise<ParsedState> {
+  const release = await acquire(path);
+  const tmpPath: string = `${path}.tmp`;
+  try {
+    const raw: string = readFileSync(path, 'utf8');
+    const { state, raw_bodies, raw_frontmatter, block_gaps, line_ending } =
+      parse(raw);
+    // Deep-clone so the consumer's fn cannot mutate the state we just
+    // parsed (defensive — apply() does this too for pure callers).
+    const clone = structuredClone(state);
+    const next = fn(clone);
+    const out = serialize(next, {
+      raw_frontmatter,
+      raw_bodies,
+      block_gaps,
+      line_ending,
+    });
+    writeFileSync(tmpPath, out, 'utf8');
+    try {
+      renameSync(tmpPath, path);
+    } catch (err) {
+      // Windows EPERM retry — AV / indexer holding STATE.md briefly.
+      const code =
+        typeof err === 'object' && err !== null && 'code' in err
+          ? (err as { code?: unknown }).code
+          : undefined;
+      if (code === 'EPERM' || code === 'EBUSY') {
+        await new Promise((r) => setTimeout(r, 50));
+        renameSync(tmpPath, path);
+      } else {
+        throw err;
+      }
+    }
+    return next;
+  } catch (err) {
+    // Clean up the orphaned tmp file on failure so we don't pollute.
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch {
+      // best-effort; a leftover tmp file does not corrupt STATE.md.
+    }
+    throw err;
+  } finally {
+    await release();
+  }
+}
+
+/**
+ * Advance to `toStage` under the locked RMW protocol.
+ *
+ * Steps:
+ *   1. Read current state (outside the lock) to pass to the gate.
+ *   2. Resolve the gate via `gateFor(position.stage, toStage)`.
+ *        - `null` → TransitionGateFailed "Invalid transition" (skip-stage,
+ *          backward, same-stage, or from outside the Stage union).
+ *   3. Invoke the gate. If `pass: false`, throw TransitionGateFailed with
+ *      the gate's blockers verbatim.
+ *   4. If `pass: true`, mutate STATE.md under the lock:
+ *        - frontmatter.stage = toStage
+ *        - position.stage = toStage
+ *        - frontmatter.last_checkpoint = now (ISO)
+ *        - timestamps[`${toStage}_started_at`] = now (ISO)
+ *
+ * Returns the updated state plus the gate response (for callers that
+ * want to log blockers — on pass, `blockers` is always `[]`).
+ */
+export async function transition(
+  path: string,
+  toStage: Stage,
+): Promise<TransitionResult> {
+  // Read (outside the lock) to pass current state to the gate — the
+  // mutate() below will re-read under the lock before applying changes.
+  // This two-phase pattern matches the GSD reference implementation.
+  const beforeMutate = await read(path);
+  const from: string = beforeMutate.position.stage;
+  // `position.stage` is typed as `string` in ParsedState (parser tolerates
+  // `scan` and other pre-brief values). Narrow it to `Stage` before asking
+  // the gate registry — anything outside the union is an invalid FROM.
+  if (!isStage(from)) {
+    throw new TransitionGateFailed(toStage, [
+      `Invalid transition: from="${from}" is not a recognized Stage`,
+    ]);
+  }
+  const gate = gateFor(from, toStage);
+  if (gate === null) {
+    throw new TransitionGateFailed(toStage, [
+      `Invalid transition: ${from} → ${toStage}`,
+    ]);
+  }
+  const gateResult = gate(beforeMutate);
+  if (!gateResult.pass) {
+    throw new TransitionGateFailed(toStage, gateResult.blockers);
+  }
+  const nowIso: string = new Date().toISOString();
+  const nextState = await mutate(path, (s): ParsedState => {
+    s.frontmatter.stage = toStage;
+    s.frontmatter.last_checkpoint = nowIso;
+    s.position.stage = toStage;
+    s.timestamps[`${toStage}_started_at`] = nowIso;
+    return s;
+  });
+  return { pass: true, blockers: gateResult.blockers, state: nextState };
+}