@hegemonart/get-design-done 1.30.6 → 1.31.5

package/sdk/mcp/gdd-state/server.js

@@ -0,0 +1,2790 @@
+#!/usr/bin/env -S node --experimental-strip-types
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name12 in all)
+    __defProp(target, name12, { get: all[name12], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// sdk/mcp/gdd-state/server.ts
+var server_exports = {};
+__export(server_exports, {
+  buildServer: () => buildServer,
+  runStdio: () => runStdio
+});
+module.exports = __toCommonJS(server_exports);
+var import_node_fs4 = require("node:fs");
+var import_node_path2 = require("node:path");
+var import_server = require("@modelcontextprotocol/sdk/server/index.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_types8 = require("@modelcontextprotocol/sdk/types.js");
+
+// sdk/errors/index.ts
+var GDDError = class extends Error {
+  code;
+  context;
+  constructor(message, code, context = {}) {
+    super(message);
+    this.code = code;
+    this.context = Object.freeze({ ...context });
+    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() {
+    return {
+      name: this.name,
+      kind: this.kind,
+      code: this.code,
+      message: this.message,
+      context: this.context
+    };
+  }
+};
+var ValidationError = class extends GDDError {
+  kind = "validation";
+  constructor(message, code = "VALIDATION", context) {
+    super(message, code, context);
+  }
+};
+var StateConflictError = class extends GDDError {
+  kind = "state_conflict";
+  constructor(message, code = "STATE_CONFLICT", context) {
+    super(message, code, context);
+  }
+};
+var OperationFailedError = class extends GDDError {
+  kind = "operation_failed";
+  constructor(message, code = "OPERATION_FAILED", context) {
+    super(message, code, context);
+  }
+};
+var LockAcquisitionError = class extends StateConflictError {
+  lockPath;
+  lockContents;
+  waitedMs;
+  constructor(lockPath, lockContents, waitedMs, context) {
+    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;
+  }
+};
+var TransitionGateFailed = class extends StateConflictError {
+  blockers;
+  toStage;
+  constructor(toStage, blockers, context) {
+    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]);
+  }
+};
+var ParseError = class extends ValidationError {
+  line;
+  constructor(message, line, context) {
+    super(
+      `STATE.md parse error at line ${line}: ${message}`,
+      "PARSE_ERROR",
+      { ...context, line }
+    );
+    this.line = line;
+  }
+};
+
+// sdk/errors/classification.ts
+function classify(err) {
+  if (err instanceof ValidationError) {
+    return {
+      kind: "validation",
+      shouldThrow: true,
+      retryable: false,
+      code: err.code,
+      message: err.message
+    };
+  }
+  if (err instanceof StateConflictError) {
+    return {
+      kind: "state_conflict",
+      shouldThrow: true,
+      retryable: true,
+      code: err.code,
+      message: err.message
+    };
+  }
+  if (err instanceof OperationFailedError) {
+    return {
+      kind: "operation_failed",
+      shouldThrow: false,
+      retryable: false,
+      code: err.code,
+      message: err.message
+    };
+  }
+  if (err instanceof Error) {
+    return {
+      kind: "unknown",
+      shouldThrow: true,
+      retryable: false,
+      code: "UNKNOWN",
+      message: err.message
+    };
+  }
+  return {
+    kind: "unknown",
+    shouldThrow: true,
+    retryable: false,
+    code: "UNKNOWN",
+    message: String(err)
+  };
+}
+function toToolError(err) {
+  const c = classify(err);
+  const out = {
+    error: {
+      code: c.code,
+      message: c.message,
+      kind: c.kind
+    }
+  };
+  if (err instanceof GDDError) {
+    out.error.context = err.context;
+  }
+  return out;
+}
+
+// sdk/mcp/gdd-state/tools/get.ts
+var get_exports = {};
+__export(get_exports, {
+  handle: () => handle,
+  name: () => name,
+  schemaPath: () => schemaPath
+});
+
+// sdk/state/index.ts
+var import_node_fs2 = require("node:fs");
+
+// sdk/state/lockfile.ts
+var import_node_fs = require("node:fs");
+var import_node_os = require("node:os");
+
+// sdk/state/types.ts
+function isStage(value) {
+  return value === "brief" || value === "explore" || value === "plan" || value === "design" || value === "verify";
+}
+function isConnectionStatus(value) {
+  return value === "available" || value === "unavailable" || value === "not_configured";
+}
+function isDecisionStatus(value) {
+  return value === "locked" || value === "tentative";
+}
+function isMustHaveStatus(value) {
+  return value === "pending" || value === "pass" || value === "fail";
+}
+function isSpikeVerdict(value) {
+  return value === "yes" || value === "no" || value === "partial";
+}
+function isPrototypingEntryStatus(value) {
+  return value === "resolved";
+}
+function isQualityGateStatus(value) {
+  return value === "pass" || value === "fail" || value === "timeout" || value === "skipped";
+}
+
+// sdk/state/lockfile.ts
+var DEFAULTS = {
+  staleMs: 6e4,
+  maxWaitMs: 5e3,
+  pollMs: 50
+};
+async function acquire(path, opts = {}) {
+  const staleMs = opts.staleMs ?? DEFAULTS.staleMs;
+  const maxWaitMs = opts.maxWaitMs ?? DEFAULTS.maxWaitMs;
+  const pollMs = opts.pollMs ?? DEFAULTS.pollMs;
+  const lockPath = `${path}.lock`;
+  const startedAt = Date.now();
+  const payload = {
+    pid: process.pid,
+    host: (0, import_node_os.hostname)(),
+    acquired_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const payloadText = JSON.stringify(payload);
+  if (maxWaitMs < 0 || pollMs < 0 || staleMs < 0) {
+    throw new Error(
+      `invalid AcquireOptions: staleMs=${staleMs}, maxWaitMs=${maxWaitMs}, pollMs=${pollMs}`
+    );
+  }
+  while (true) {
+    try {
+      (0, import_node_fs.writeFileSync)(lockPath, payloadText, { flag: "wx", encoding: "utf8" });
+      return makeRelease(lockPath);
+    } catch (err) {
+      const code = getErrnoCode(err);
+      if (code !== "EEXIST" && code !== "EPERM" && code !== "EBUSY") {
+        throw err;
+      }
+      const existing = readLockSafe(lockPath);
+      if (existing === null) {
+        continue;
+      }
+      const parsed = parseLock(existing);
+      if (parsed !== null && isStale(parsed, staleMs)) {
+        try {
+          (0, import_node_fs.unlinkSync)(lockPath);
+        } catch (delErr) {
+          const delCode = getErrnoCode(delErr);
+          if (delCode !== "ENOENT") {
+          }
+        }
+        continue;
+      }
+      if (Date.now() - startedAt >= maxWaitMs) {
+        throw new LockAcquisitionError(lockPath, existing, Date.now() - startedAt);
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+function makeRelease(lockPath) {
+  let released = false;
+  return async () => {
+    if (released) return;
+    released = true;
+    try {
+      (0, import_node_fs.unlinkSync)(lockPath);
+    } catch (err) {
+      const code = getErrnoCode(err);
+      if (code !== "ENOENT") {
+        if (code === "EPERM" || code === "EBUSY") {
+          await sleep(50);
+          try {
+            if ((0, import_node_fs.existsSync)(lockPath)) (0, import_node_fs.unlinkSync)(lockPath);
+          } catch {
+          }
+        }
+      }
+    }
+  };
+}
+function readLockSafe(path) {
+  try {
+    return (0, import_node_fs.readFileSync)(path, "utf8");
+  } catch (err) {
+    const code = getErrnoCode(err);
+    if (code === "ENOENT") return null;
+    return "<unreadable>";
+  }
+}
+function parseLock(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (typeof obj === "object" && obj !== null && typeof obj["pid"] === "number" && typeof obj["host"] === "string" && typeof obj["acquired_at"] === "string") {
+      return obj;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function isStale(payload, staleMs) {
+  if (!isPidAlive(payload.pid, payload.host)) return true;
+  const acquiredAt = Date.parse(payload.acquired_at);
+  if (!Number.isFinite(acquiredAt)) return true;
+  return Date.now() - acquiredAt > staleMs;
+}
+function isPidAlive(pid, host) {
+  if (host !== (0, import_node_os.hostname)()) {
+    return true;
+  }
+  if (pid === process.pid) {
+    return true;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = getErrnoCode(err);
+    if (code === "ESRCH") return false;
+    return true;
+  }
+}
+function getErrnoCode(err) {
+  if (typeof err === "object" && err !== null && "code" in err) {
+    const code = err.code;
+    if (typeof code === "string") return code;
+  }
+  return void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+
+// sdk/state/parser.ts
+var BLOCK_ORDER = [
+  "position",
+  "decisions",
+  "must_haves",
+  "prototyping",
+  "quality_gate",
+  "connections",
+  "blockers",
+  "parallelism_decision",
+  "todos",
+  "timestamps"
+];
+var EMPTY_RAW_BODIES = {
+  position: null,
+  decisions: null,
+  must_haves: null,
+  prototyping: null,
+  quality_gate: null,
+  connections: null,
+  blockers: null,
+  parallelism_decision: null,
+  todos: null,
+  timestamps: null
+};
+function parse(raw) {
+  const line_ending = raw.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = line_ending === "\r\n" ? raw.replace(/\r\n/g, "\n") : raw;
+  const trailing_newline = normalized.endsWith("\n");
+  if (!normalized.startsWith("---\n")) {
+    throw new ParseError('file must begin with "---" frontmatter fence', 1);
+  }
+  const fmEnd = normalized.indexOf("\n---\n", 4);
+  if (fmEnd === -1) {
+    throw new ParseError('unterminated frontmatter (missing closing "---")', 1);
+  }
+  const fmText = normalized.slice(4, fmEnd);
+  const frontmatter = parseFrontmatter(fmText);
+  const afterFm = fmEnd + 5;
+  const body = normalized.slice(afterFm);
+  const lines = body.split("\n");
+  const blocks = [];
+  const seen = /* @__PURE__ */ new Set();
+  const blockOpen = /^<([a-z_]+)>\s*$/;
+  const blockClose = /^<\/([a-z_]+)>\s*$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const openMatch = line.match(blockOpen);
+    if (!openMatch) continue;
+    const name12 = openMatch[1];
+    if (!BLOCK_ORDER.includes(name12)) {
+      continue;
+    }
+    if (seen.has(name12)) {
+      throw new ParseError(`duplicate block <${name12}>`, lineToFileLine(afterFm, normalized, i));
+    }
+    let close = -1;
+    for (let j = i + 1; j < lines.length; j++) {
+      const cm = (lines[j] ?? "").match(blockClose);
+      if (cm && cm[1] === name12) {
+        close = j;
+        break;
+      }
+    }
+    if (close === -1) {
+      throw new ParseError(
+        `unterminated block <${name12}> (no </${name12}>)`,
+        lineToFileLine(afterFm, normalized, i)
+      );
+    }
+    blocks.push({ name: name12, openLine: i, closeLine: close });
+    seen.add(name12);
+    i = close;
+  }
+  let body_preamble;
+  let body_trailer;
+  const block_gaps = {
+    position: "",
+    decisions: "",
+    must_haves: "",
+    prototyping: "",
+    quality_gate: "",
+    connections: "",
+    blockers: "",
+    parallelism_decision: "",
+    todos: "",
+    timestamps: ""
+  };
+  if (blocks.length === 0) {
+    body_preamble = body;
+    body_trailer = "";
+  } else {
+    const firstBlock = blocks[0];
+    const lastBlock = blocks[blocks.length - 1];
+    if (firstBlock === void 0 || lastBlock === void 0) {
+      throw new ParseError("internal: block index inconsistency", 1);
+    }
+    body_preamble = lines.slice(0, firstBlock.openLine).join("\n");
+    if (firstBlock.openLine > 0) body_preamble += "\n";
+    body_trailer = lines.slice(lastBlock.closeLine + 1).join("\n");
+    for (let bi = 0; bi < blocks.length; bi++) {
+      const cur = blocks[bi];
+      if (cur === void 0) continue;
+      if (bi === 0) {
+        block_gaps[cur.name] = body_preamble;
+      } else {
+        const prev = blocks[bi - 1];
+        if (prev === void 0) continue;
+        const gapLines = lines.slice(prev.closeLine + 1, cur.openLine);
+        let gap = gapLines.join("\n");
+        if (cur.openLine > prev.closeLine + 1) gap += "\n";
+        block_gaps[cur.name] = gap;
+      }
+    }
+  }
+  const raw_bodies = { ...EMPTY_RAW_BODIES };
+  let position = null;
+  let decisions = [];
+  let must_haves = [];
+  let connections = {};
+  let blockers = [];
+  let parallelism_decision = null;
+  let todos = null;
+  let prototyping = null;
+  let quality_gate = null;
+  let timestamps = {};
+  for (const blk of blocks) {
+    const rawBody = lines.slice(blk.openLine + 1, blk.closeLine).join("\n");
+    raw_bodies[blk.name] = rawBody;
+    const fileLineOfBody = lineToFileLine(afterFm, normalized, blk.openLine + 1);
+    switch (blk.name) {
+      case "position":
+        position = parsePositionBody(rawBody, fileLineOfBody);
+        break;
+      case "decisions":
+        decisions = parseDecisionsBody(rawBody, fileLineOfBody);
+        break;
+      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;
+      case "blockers":
+        blockers = parseBlockersBody(rawBody, fileLineOfBody);
+        break;
+      case "parallelism_decision":
+        parallelism_decision = rawBody;
+        break;
+      case "todos":
+        todos = rawBody;
+        break;
+      case "timestamps":
+        timestamps = parseTimestampsBody(rawBody, fileLineOfBody);
+        break;
+      default: {
+        const _exhaustive = blk.name;
+        void _exhaustive;
+      }
+    }
+  }
+  if (position === null) {
+    throw new ParseError(
+      "missing required <position> block (run scan to initialize STATE.md)",
+      1
+    );
+  }
+  const state = {
+    frontmatter,
+    position,
+    decisions,
+    must_haves,
+    connections,
+    blockers,
+    parallelism_decision,
+    todos,
+    prototyping,
+    quality_gate,
+    timestamps,
+    body_preamble,
+    body_trailer
+  };
+  return {
+    state,
+    raw_bodies,
+    raw_frontmatter: fmText,
+    block_gaps,
+    line_ending,
+    trailing_newline
+  };
+}
+function lineToFileLine(bodyStartOffset, normalized, bodyLineIdx) {
+  const prefix = normalized.slice(0, bodyStartOffset);
+  const prefixLines = prefix.split("\n").length - 1;
+  return prefixLines + bodyLineIdx + 1;
+}
+function parseFrontmatter(raw) {
+  const out = {};
+  const lines = raw.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (key === "wave") {
+      const n = Number(value);
+      out[key] = Number.isFinite(n) ? n : value;
+    } else {
+      out[key] = value;
+    }
+  }
+  const fm = {
+    pipeline_state_version: String(out["pipeline_state_version"] ?? "1.0"),
+    stage: String(out["stage"] ?? ""),
+    cycle: String(out["cycle"] ?? ""),
+    wave: typeof out["wave"] === "number" ? out["wave"] : 1,
+    started_at: String(out["started_at"] ?? ""),
+    last_checkpoint: String(out["last_checkpoint"] ?? "")
+  };
+  for (const [k, v] of Object.entries(out)) {
+    if (!(k in fm)) fm[k] = v;
+  }
+  return fm;
+}
+function parsePositionBody(body, startLine) {
+  const fields = {};
+  const lines = body.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("<!--")) continue;
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    fields[key] = value;
+  }
+  const stage = fields["stage"] ?? "";
+  const waveRaw = fields["wave"] ?? "1";
+  const waveNum = Number(waveRaw);
+  if (!Number.isFinite(waveNum)) {
+    throw new ParseError(`<position> wave not numeric: ${waveRaw}`, startLine);
+  }
+  return {
+    stage,
+    wave: waveNum,
+    task_progress: fields["task_progress"] ?? "0/0",
+    status: fields["status"] ?? "initialized",
+    handoff_source: fields["handoff_source"] ?? "",
+    handoff_path: fields["handoff_path"] ?? "",
+    skipped_stages: fields["skipped_stages"] ?? ""
+  };
+}
+function parseDecisionsBody(body, startLine) {
+  const out = [];
+  const lines = body.split("\n");
+  const re = /^(D-\d+):\s*(.*?)\s*\((locked|tentative)\)\s*$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] ?? "").trim();
+    if (line === "" || line.startsWith("<!--")) continue;
+    const m = line.match(re);
+    if (!m) {
+      continue;
+    }
+    const id = m[1] ?? "";
+    const text = m[2] ?? "";
+    const status = m[3];
+    if (!isDecisionStatus(status)) {
+      throw new ParseError(
+        `<decisions> invalid status for ${id}: ${status}`,
+        startLine + i
+      );
+    }
+    out.push({ id, text, status });
+  }
+  return out;
+}
+function parseMustHavesBody(body, startLine) {
+  const out = [];
+  const lines = body.split("\n");
+  const re = /^(M-\d+):\s*(.*?)\s*\|\s*status:\s*(pending|pass|fail)\s*$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] ?? "").trim();
+    if (line === "" || line.startsWith("<!--")) continue;
+    const m = line.match(re);
+    if (!m) continue;
+    const id = m[1] ?? "";
+    const text = m[2] ?? "";
+    const status = m[3];
+    if (!isMustHaveStatus(status)) {
+      throw new ParseError(
+        `<must_haves> invalid status for ${id}: ${status}`,
+        startLine + i
+      );
+    }
+    out.push({ id, text, status });
+  }
+  return out;
+}
+function parseConnectionsBody(body, startLine) {
+  const out = {};
+  const lines = body.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("<!--")) continue;
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    if (!isConnectionStatus(value)) {
+      throw new ParseError(
+        `<connections> invalid status for ${key}: ${value}`,
+        startLine + i
+      );
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function parseBlockersBody(body, startLine) {
+  const out = [];
+  const lines = body.split("\n");
+  const re = /^\[([^\]]+)\]\s*\[([^\]]+)\]:\s*(.*)$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = (lines[i] ?? "").trim();
+    if (line === "" || line.startsWith("<!--")) continue;
+    const m = line.match(re);
+    if (!m) {
+      throw new ParseError(
+        `<blockers> malformed line: "${line}"`,
+        startLine + i
+      );
+    }
+    out.push({ stage: m[1] ?? "", date: m[2] ?? "", text: m[3] ?? "" });
+  }
+  return out;
+}
+function parsePrototypingBody(body, startLine) {
+  const sketches = [];
+  const spikes = [];
+  const skipped = [];
+  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) {
+      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));
+    }
+  }
+  return { sketches, spikes, skipped };
+}
+function parsePrototypingAttrs(span) {
+  const out = {};
+  const re = /([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s/>]+))/g;
+  let m;
+  while ((m = re.exec(span)) !== null) {
+    const key = m[1] ?? "";
+    const value = (m[2] !== void 0 ? m[2] : void 0) ?? (m[3] !== void 0 ? m[3] : void 0) ?? m[4] ?? "";
+    if (key !== "") out[key] = value;
+  }
+  return out;
+}
+function buildSketchEntry(attrs, fileLine) {
+  const slug = attrs["slug"];
+  const cycle = attrs["cycle"];
+  const decision = attrs["decision"];
+  const status = attrs["status"] ?? "resolved";
+  if (slug === void 0) {
+    throw new ParseError("<sketch/> missing required attribute slug", fileLine);
+  }
+  if (cycle === void 0) {
+    throw new ParseError("<sketch/> missing required attribute cycle", fileLine);
+  }
+  if (decision === void 0) {
+    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,
+    extra_attrs: extractExtraAttrs(attrs, ["slug", "cycle", "decision", "status"])
+  };
+}
+function buildSpikeEntry(attrs, fileLine) {
+  const slug = attrs["slug"];
+  const cycle = attrs["cycle"];
+  const decision = attrs["decision"];
+  const verdict = attrs["verdict"];
+  const status = attrs["status"] ?? "resolved";
+  if (slug === void 0) {
+    throw new ParseError("<spike/> missing required attribute slug", fileLine);
+  }
+  if (cycle === void 0) {
+    throw new ParseError("<spike/> missing required attribute cycle", fileLine);
+  }
+  if (decision === void 0) {
+    throw new ParseError(
+      "<spike/> missing required attribute decision",
+      fileLine
+    );
+  }
+  if (verdict === void 0) {
+    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,
+    status,
+    extra_attrs: extractExtraAttrs(attrs, [
+      "slug",
+      "cycle",
+      "decision",
+      "verdict",
+      "status"
+    ])
+  };
+}
+function buildSkippedEntry(attrs, fileLine) {
+  const at = attrs["at"];
+  const cycle = attrs["cycle"];
+  const reason = attrs["reason"];
+  if (at === void 0) {
+    throw new ParseError("<skipped/> missing required attribute at", fileLine);
+  }
+  if (cycle === void 0) {
+    throw new ParseError(
+      "<skipped/> missing required attribute cycle",
+      fileLine
+    );
+  }
+  if (reason === void 0) {
+    throw new ParseError(
+      "<skipped/> missing required attribute reason",
+      fileLine
+    );
+  }
+  return {
+    at,
+    cycle,
+    reason,
+    extra_attrs: extractExtraAttrs(attrs, ["at", "cycle", "reason"])
+  };
+}
+function extractExtraAttrs(all, known) {
+  const out = {};
+  for (const [k, v] of Object.entries(all)) {
+    if (!known.includes(k)) out[k] = v;
+  }
+  return out;
+}
+function parseQualityGateBody(body, startLine) {
+  let run = 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) {
+      continue;
+    }
+    const tag = m[1] ?? "";
+    if (tag !== "run") continue;
+    const attrs = parsePrototypingAttrs(m[2] ?? "");
+    run = buildQualityGateRun(attrs, startLine + i);
+  }
+  return { run };
+}
+function buildQualityGateRun(attrs, fileLine) {
+  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 === void 0) {
+    throw new ParseError(
+      "<quality_gate> <run/> missing required attribute started_at",
+      fileLine
+    );
+  }
+  if (completed_at === void 0) {
+    throw new ParseError(
+      "<quality_gate> <run/> missing required attribute completed_at",
+      fileLine
+    );
+  }
+  if (status === void 0) {
+    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 === void 0) {
+    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 === void 0) {
+    throw new ParseError(
+      "<quality_gate> <run/> missing required attribute commands_run",
+      fileLine
+    );
+  }
+  return {
+    started_at,
+    completed_at,
+    status,
+    iteration,
+    commands_run,
+    extra_attrs: extractExtraAttrs(attrs, [
+      "started_at",
+      "completed_at",
+      "status",
+      "iteration",
+      "commands_run"
+    ])
+  };
+}
+function parseTimestampsBody(body, _startLine) {
+  const out = {};
+  const lines = body.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("<!--")) continue;
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    out[key] = value;
+  }
+  return out;
+}
+
+// sdk/state/mutator.ts
+function serialize(state, fidelity = {}) {
+  const {
+    raw_frontmatter,
+    raw_bodies,
+    block_gaps,
+    line_ending = "\n"
+  } = fidelity;
+  const out = [];
+  out.push("---\n");
+  out.push(emitFrontmatter(state.frontmatter, raw_frontmatter));
+  out.push("---\n");
+  for (const name12 of BLOCK_ORDER) {
+    const rawBody = raw_bodies?.[name12] ?? null;
+    const emitted = emitBlock(name12, state, rawBody);
+    if (emitted === null) {
+      continue;
+    }
+    const gap = block_gaps?.[name12] ?? (out.length > 0 && isFirstEmission(out) ? "" : "\n");
+    out.push(gap);
+    out.push(`<${name12}>
+`);
+    out.push(emitted);
+    if (!emitted.endsWith("\n")) out.push("\n");
+    out.push(`</${name12}>
+`);
+  }
+  out.push(state.body_trailer);
+  const joined = out.join("");
+  return line_ending === "\r\n" ? joined.replace(/\n/g, "\r\n") : joined;
+}
+function isFirstEmission(out) {
+  return out.length <= 3;
+}
+function emitFrontmatter(fm, raw_frontmatter) {
+  if (raw_frontmatter !== void 0) {
+    const reparsed = tryReparseFrontmatter(raw_frontmatter);
+    if (reparsed !== null && frontmatterEqual(reparsed, fm)) {
+      return raw_frontmatter + "\n";
+    }
+  }
+  return canonicalFrontmatter(fm);
+}
+function tryReparseFrontmatter(raw) {
+  try {
+    const out = {};
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("#")) continue;
+      const idx = line.indexOf(":");
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim();
+      let value = line.slice(idx + 1).trim();
+      if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+        value = value.slice(1, -1);
+      }
+      if (key === "wave") {
+        const n = Number(value);
+        out[key] = Number.isFinite(n) ? n : value;
+      } else {
+        out[key] = value;
+      }
+    }
+    const fm = {
+      pipeline_state_version: String(out["pipeline_state_version"] ?? "1.0"),
+      stage: String(out["stage"] ?? ""),
+      cycle: String(out["cycle"] ?? ""),
+      wave: typeof out["wave"] === "number" ? out["wave"] : 1,
+      started_at: String(out["started_at"] ?? ""),
+      last_checkpoint: String(out["last_checkpoint"] ?? "")
+    };
+    for (const [k, v] of Object.entries(out)) {
+      if (!(k in fm)) fm[k] = v;
+    }
+    return fm;
+  } catch {
+    return null;
+  }
+}
+function frontmatterEqual(a, b) {
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (!(k in b)) return false;
+    if (a[k] !== b[k]) {
+      if (String(a[k]) !== String(b[k])) return false;
+    }
+  }
+  return true;
+}
+function canonicalFrontmatter(fm) {
+  const fixed = [
+    "pipeline_state_version",
+    "stage",
+    "cycle",
+    "wave",
+    "started_at",
+    "last_checkpoint"
+  ];
+  const lines = [];
+  const emitted = /* @__PURE__ */ new Set();
+  for (const k of fixed) {
+    if (k in fm) {
+      lines.push(`${k}: ${formatFrontmatterValue(fm[k])}`);
+      emitted.add(k);
+    }
+  }
+  for (const k of Object.keys(fm)) {
+    if (emitted.has(k)) continue;
+    lines.push(`${k}: ${formatFrontmatterValue(fm[k])}`);
+  }
+  return lines.join("\n") + "\n";
+}
+function formatFrontmatterValue(v) {
+  if (v === null || v === void 0) return "";
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  if (typeof v === "string") return v;
+  return JSON.stringify(v);
+}
+function emitBlock(name12, state, rawBody) {
+  switch (name12) {
+    case "position":
+      return emitPosition(state.position, rawBody);
+    case "decisions":
+      return emitDecisions(state.decisions, rawBody);
+    case "must_haves":
+      return emitMustHaves(state.must_haves, rawBody);
+    case "prototyping":
+      return emitPrototyping(state.prototyping, rawBody);
+    case "quality_gate":
+      return emitQualityGate(state.quality_gate, rawBody);
+    case "connections":
+      return emitConnections(state.connections, rawBody);
+    case "blockers":
+      return emitBlockers(state.blockers, rawBody);
+    case "parallelism_decision":
+      if (rawBody !== null) {
+        if (state.parallelism_decision === rawBody) return rawBody;
+        return state.parallelism_decision ?? "";
+      }
+      return state.parallelism_decision;
+    case "todos":
+      if (rawBody !== null) {
+        if (state.todos === rawBody) return rawBody;
+        return state.todos ?? "";
+      }
+      return state.todos;
+    case "timestamps":
+      return emitTimestamps(state.timestamps, rawBody);
+    default: {
+      const _exhaustive = name12;
+      void _exhaustive;
+      return null;
+    }
+  }
+}
+function emitPosition(pos, rawBody) {
+  if (rawBody !== null) {
+    const reparsed = tryReparsePosition(rawBody);
+    if (reparsed !== null && positionEqual(reparsed, pos)) return rawBody;
+  }
+  return [
+    `stage: ${pos.stage}`,
+    `wave: ${pos.wave}`,
+    `task_progress: ${pos.task_progress}`,
+    `status: ${pos.status}`,
+    `handoff_source: ${quoteIfEmpty(pos.handoff_source)}`,
+    `handoff_path: ${quoteIfEmpty(pos.handoff_path)}`,
+    `skipped_stages: ${quoteIfEmpty(pos.skipped_stages)}`
+  ].join("\n");
+}
+function quoteIfEmpty(v) {
+  return v === "" ? '""' : v;
+}
+function emitDecisions(decisions, rawBody) {
+  if (rawBody !== null) {
+    const reparsed = tryReparseDecisions(rawBody);
+    if (reparsed !== null && decisionsEqual(reparsed, decisions)) return rawBody;
+  }
+  if (decisions.length === 0) return "";
+  return decisions.map((d) => `${d.id}: ${d.text} (${d.status})`).join("\n");
+}
+function emitMustHaves(mh, rawBody) {
+  if (rawBody !== null) {
+    const reparsed = tryReparseMustHaves(rawBody);
+    if (reparsed !== null && mustHavesEqual(reparsed, mh)) return rawBody;
+  }
+  if (mh.length === 0) return "";
+  return mh.map((m) => `${m.id}: ${m.text} | status: ${m.status}`).join("\n");
+}
+function emitConnections(conns, rawBody) {
+  if (rawBody !== null) {
+    const reparsed = tryReparseConnections(rawBody);
+    if (reparsed !== null && connectionsEqual(reparsed, conns)) return rawBody;
+  }
+  const keys = Object.keys(conns);
+  if (keys.length === 0) return "";
+  return keys.map((k) => `${k}: ${conns[k]}`).join("\n");
+}
+function emitBlockers(blockers, rawBody) {
+  if (rawBody !== null) {
+    const reparsed = tryReparseBlockers(rawBody);
+    if (reparsed !== null && blockersEqual(reparsed, blockers)) return rawBody;
+  }
+  if (blockers.length === 0) return "";
+  return blockers.map((b) => `[${b.stage}] [${b.date}]: ${b.text}`).join("\n");
+}
+function emitPrototyping(block, rawBody) {
+  if (block === null && rawBody === null) return null;
+  if (block === null) {
+    return null;
+  }
+  if (rawBody !== null) {
+    const reparsed = tryReparsePrototyping(rawBody);
+    if (reparsed !== null && prototypingEqual(reparsed, block)) {
+      return rawBody;
+    }
+  }
+  return canonicalPrototyping(block);
+}
+function canonicalPrototyping(block) {
+  const lines = [];
+  for (const s of block.sketches) {
+    lines.push(canonicalSketch(s));
+  }
+  for (const sp of block.spikes) {
+    lines.push(canonicalSpike(sp));
+  }
+  for (const sk of block.skipped) {
+    lines.push(canonicalSkipped(sk));
+  }
+  return lines.join("\n");
+}
+function canonicalSketch(s) {
+  const parts = [
+    `slug=${formatPrototypingAttr(s.slug)}`,
+    `cycle=${formatPrototypingAttr(s.cycle)}`,
+    `decision=${formatPrototypingAttr(s.decision)}`,
+    `status=${formatPrototypingAttr(s.status)}`
+  ];
+  for (const [k, v] of Object.entries(s.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<sketch ${parts.join(" ")}/>`;
+}
+function canonicalSpike(s) {
+  const parts = [
+    `slug=${formatPrototypingAttr(s.slug)}`,
+    `cycle=${formatPrototypingAttr(s.cycle)}`,
+    `decision=${formatPrototypingAttr(s.decision)}`,
+    `verdict=${formatPrototypingAttr(s.verdict)}`,
+    `status=${formatPrototypingAttr(s.status)}`
+  ];
+  for (const [k, v] of Object.entries(s.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<spike ${parts.join(" ")}/>`;
+}
+function canonicalSkipped(s) {
+  const parts = [
+    `at=${formatPrototypingAttr(s.at)}`,
+    `cycle=${formatPrototypingAttr(s.cycle)}`,
+    `reason=${formatPrototypingAttr(s.reason)}`
+  ];
+  for (const [k, v] of Object.entries(s.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<skipped ${parts.join(" ")}/>`;
+}
+function formatPrototypingAttr(v) {
+  return `"${v.replace(/"/g, "&quot;")}"`;
+}
+function emitQualityGate(block, rawBody) {
+  if (block === null && rawBody === null) return null;
+  if (block === null) {
+    return null;
+  }
+  if (rawBody !== null) {
+    const reparsed = tryReparseQualityGate(rawBody);
+    if (reparsed !== null && qualityGateEqual(reparsed, block)) {
+      return rawBody;
+    }
+  }
+  return canonicalQualityGate(block);
+}
+function canonicalQualityGate(block) {
+  if (block.run === null) return "";
+  return canonicalQualityGateRun(block.run);
+}
+function canonicalQualityGateRun(run) {
+  const parts = [
+    `started_at=${formatPrototypingAttr(run.started_at)}`,
+    `completed_at=${formatPrototypingAttr(run.completed_at)}`,
+    `status=${formatPrototypingAttr(run.status)}`,
+    `iteration=${formatPrototypingAttr(String(run.iteration))}`,
+    `commands_run=${formatPrototypingAttr(run.commands_run)}`
+  ];
+  for (const [k, v] of Object.entries(run.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<run ${parts.join(" ")}/>`;
+}
+function emitTimestamps(ts, rawBody) {
+  if (rawBody !== null) {
+    const reparsed = tryReparseTimestamps(rawBody);
+    if (reparsed !== null && recordsEqual(reparsed, ts)) return rawBody;
+  }
+  const keys = Object.keys(ts);
+  if (keys.length === 0) return "";
+  return keys.map((k) => `${k}: ${ts[k]}`).join("\n");
+}
+function positionEqual(a, b) {
+  return a.stage === b.stage && a.wave === b.wave && a.task_progress === b.task_progress && a.status === b.status && a.handoff_source === b.handoff_source && a.handoff_path === b.handoff_path && a.skipped_stages === b.skipped_stages;
+}
+function decisionsEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === void 0 || y === void 0) return false;
+    if (x.id !== y.id || x.text !== y.text || x.status !== y.status) return false;
+  }
+  return true;
+}
+function mustHavesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === void 0 || y === void 0) return false;
+    if (x.id !== y.id || x.text !== y.text || x.status !== y.status) return false;
+  }
+  return true;
+}
+function connectionsEqual(a, b) {
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (let i = 0; i < ak.length; i++) {
+    if (ak[i] !== bk[i]) return false;
+    const key = ak[i];
+    if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
+function blockersEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === void 0 || y === void 0) return false;
+    if (x.stage !== y.stage || x.date !== y.date || x.text !== y.text) return false;
+  }
+  return true;
+}
+function prototypingEqual(a, b) {
+  if (a.sketches.length !== b.sketches.length) return false;
+  if (a.spikes.length !== b.spikes.length) return false;
+  if (a.skipped.length !== b.skipped.length) return false;
+  for (let i = 0; i < a.sketches.length; i++) {
+    if (!sketchEqual(a.sketches[i], b.sketches[i])) return false;
+  }
+  for (let i = 0; i < a.spikes.length; i++) {
+    if (!spikeEqual(a.spikes[i], b.spikes[i])) return false;
+  }
+  for (let i = 0; i < a.skipped.length; i++) {
+    if (!skippedEqual(a.skipped[i], b.skipped[i])) return false;
+  }
+  return true;
+}
+function sketchEqual(a, b) {
+  return a.slug === b.slug && a.cycle === b.cycle && a.decision === b.decision && a.status === b.status && extraAttrsEqual(a.extra_attrs, b.extra_attrs);
+}
+function spikeEqual(a, b) {
+  return a.slug === b.slug && a.cycle === b.cycle && a.decision === b.decision && a.verdict === b.verdict && a.status === b.status && extraAttrsEqual(a.extra_attrs, b.extra_attrs);
+}
+function skippedEqual(a, b) {
+  return a.at === b.at && a.cycle === b.cycle && a.reason === b.reason && extraAttrsEqual(a.extra_attrs, b.extra_attrs);
+}
+function extraAttrsEqual(a, b) {
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (let i = 0; i < ak.length; i++) {
+    if (ak[i] !== bk[i]) return false;
+    const key = ak[i];
+    if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
+function qualityGateEqual(a, b) {
+  if (a.run === null && b.run === null) return true;
+  if (a.run === null || b.run === null) return false;
+  return qualityGateRunEqual(a.run, b.run);
+}
+function qualityGateRunEqual(a, b) {
+  return a.started_at === b.started_at && a.completed_at === b.completed_at && a.status === b.status && a.iteration === b.iteration && a.commands_run === b.commands_run && extraAttrsEqual(a.extra_attrs, b.extra_attrs);
+}
+function recordsEqual(a, b) {
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (let i = 0; i < ak.length; i++) {
+    if (ak[i] !== bk[i]) return false;
+    const key = ak[i];
+    if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
+function tryReparsePosition(raw) {
+  try {
+    const fields = {};
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("<!--")) continue;
+      const idx = line.indexOf(":");
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim();
+      let value = line.slice(idx + 1).trim();
+      if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+        value = value.slice(1, -1);
+      }
+      fields[key] = value;
+    }
+    const waveNum = Number(fields["wave"] ?? "1");
+    if (!Number.isFinite(waveNum)) return null;
+    return {
+      stage: fields["stage"] ?? "",
+      wave: waveNum,
+      task_progress: fields["task_progress"] ?? "0/0",
+      status: fields["status"] ?? "initialized",
+      handoff_source: fields["handoff_source"] ?? "",
+      handoff_path: fields["handoff_path"] ?? "",
+      skipped_stages: fields["skipped_stages"] ?? ""
+    };
+  } catch {
+    return null;
+  }
+}
+function tryReparseDecisions(raw) {
+  try {
+    const out = [];
+    const re = /^(D-\d+):\s*(.*?)\s*\((locked|tentative)\)\s*$/;
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (t === "" || t.startsWith("<!--")) continue;
+      const m = t.match(re);
+      if (!m) continue;
+      out.push({
+        id: m[1] ?? "",
+        text: m[2] ?? "",
+        status: m[3]
+      });
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+function tryReparseMustHaves(raw) {
+  try {
+    const out = [];
+    const re = /^(M-\d+):\s*(.*?)\s*\|\s*status:\s*(pending|pass|fail)\s*$/;
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (t === "" || t.startsWith("<!--")) continue;
+      const m = t.match(re);
+      if (!m) continue;
+      out.push({
+        id: m[1] ?? "",
+        text: m[2] ?? "",
+        status: m[3]
+      });
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+function tryReparseConnections(raw) {
+  try {
+    const out = {};
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("<!--")) continue;
+      const idx = line.indexOf(":");
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim();
+      const value = line.slice(idx + 1).trim();
+      if (value !== "available" && value !== "unavailable" && value !== "not_configured") {
+        return null;
+      }
+      out[key] = value;
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+function tryReparseBlockers(raw) {
+  try {
+    const out = [];
+    const re = /^\[([^\]]+)\]\s*\[([^\]]+)\]:\s*(.*)$/;
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (t === "" || t.startsWith("<!--")) continue;
+      const m = t.match(re);
+      if (!m) return null;
+      out.push({ stage: m[1] ?? "", date: m[2] ?? "", text: m[3] ?? "" });
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+function tryReparsePrototyping(raw) {
+  try {
+    const sketches = [];
+    const spikes = [];
+    const skipped = [];
+    const selfClose = /^<([a-z_]+)(\s+[^>]*?)?\s*\/>\s*$/;
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (t === "" || t.startsWith("<!--")) continue;
+      const m = t.match(selfClose);
+      if (!m) {
+        return null;
+      }
+      const tag = m[1] ?? "";
+      const attrs = parseAttrInline(m[2] ?? "");
+      if (tag === "sketch") {
+        const slug = attrs["slug"];
+        const cycle = attrs["cycle"];
+        const decision = attrs["decision"];
+        const status = attrs["status"] ?? "resolved";
+        if (slug === void 0 || cycle === void 0 || decision === void 0) {
+          return null;
+        }
+        if (status !== "resolved") return null;
+        sketches.push({
+          slug,
+          cycle,
+          decision,
+          status: "resolved",
+          extra_attrs: extractExtras(attrs, [
+            "slug",
+            "cycle",
+            "decision",
+            "status"
+          ])
+        });
+      } else if (tag === "spike") {
+        const slug = attrs["slug"];
+        const cycle = attrs["cycle"];
+        const decision = attrs["decision"];
+        const verdict = attrs["verdict"];
+        const status = attrs["status"] ?? "resolved";
+        if (slug === void 0 || cycle === void 0 || decision === void 0 || verdict === void 0) {
+          return null;
+        }
+        if (verdict !== "yes" && verdict !== "no" && verdict !== "partial") {
+          return null;
+        }
+        if (status !== "resolved") return null;
+        spikes.push({
+          slug,
+          cycle,
+          decision,
+          verdict,
+          status: "resolved",
+          extra_attrs: extractExtras(attrs, [
+            "slug",
+            "cycle",
+            "decision",
+            "verdict",
+            "status"
+          ])
+        });
+      } else if (tag === "skipped") {
+        const at = attrs["at"];
+        const cycle = attrs["cycle"];
+        const reason = attrs["reason"];
+        if (at === void 0 || cycle === void 0 || reason === void 0) {
+          return null;
+        }
+        skipped.push({
+          at,
+          cycle,
+          reason,
+          extra_attrs: extractExtras(attrs, ["at", "cycle", "reason"])
+        });
+      } else {
+        return null;
+      }
+    }
+    return { sketches, spikes, skipped };
+  } catch {
+    return null;
+  }
+}
+function parseAttrInline(span) {
+  const out = {};
+  const re = /([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s/>]+))/g;
+  let m;
+  while ((m = re.exec(span)) !== null) {
+    const key = m[1] ?? "";
+    const value = (m[2] !== void 0 ? m[2] : void 0) ?? (m[3] !== void 0 ? m[3] : void 0) ?? m[4] ?? "";
+    if (key !== "") out[key] = value;
+  }
+  return out;
+}
+function extractExtras(all, known) {
+  const out = {};
+  for (const [k, v] of Object.entries(all)) {
+    if (!known.includes(k)) out[k] = v;
+  }
+  return out;
+}
+function tryReparseQualityGate(raw) {
+  try {
+    let run = null;
+    const selfClose = /^<([a-z_]+)(\s+[^>]*?)?\s*\/>\s*$/;
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (t === "" || t.startsWith("<!--")) continue;
+      const m = t.match(selfClose);
+      if (!m) {
+        return null;
+      }
+      const tag = m[1] ?? "";
+      if (tag !== "run") {
+        return null;
+      }
+      const attrs = parseAttrInline(m[2] ?? "");
+      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 === void 0 || completed_at === void 0 || status === void 0 || iterationRaw === void 0 || commands_run === void 0) {
+        return null;
+      }
+      if (status !== "pass" && status !== "fail" && status !== "timeout" && status !== "skipped") {
+        return null;
+      }
+      const iteration = Number(iterationRaw);
+      if (!Number.isFinite(iteration) || !Number.isInteger(iteration) || iteration < 0) {
+        return null;
+      }
+      run = {
+        started_at,
+        completed_at,
+        status,
+        iteration,
+        commands_run,
+        extra_attrs: extractExtras(attrs, [
+          "started_at",
+          "completed_at",
+          "status",
+          "iteration",
+          "commands_run"
+        ])
+      };
+    }
+    return { run };
+  } catch {
+    return null;
+  }
+}
+function tryReparseTimestamps(raw) {
+  try {
+    const out = {};
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed.startsWith("<!--")) continue;
+      const idx = line.indexOf(":");
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim();
+      const value = line.slice(idx + 1).trim();
+      out[key] = value;
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+// sdk/state/gates.ts
+var DESIGN_KEYWORDS = ["component", "token", "style", "copy", "layout"];
+function stageParity(state, expected) {
+  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}" \u2014 expected "${expected}"`;
+  }
+  if (state.frontmatter.stage !== expected) {
+    return `frontmatter.stage is "${state.frontmatter.stage}" \u2014 expected "${expected}"`;
+  }
+  return null;
+}
+var briefToExplore = (s) => {
+  const blockers = [];
+  const parity = stageParity(s, "brief");
+  if (parity) blockers.push(parity);
+  return { pass: blockers.length === 0, blockers };
+};
+var exploreToPlan = (s) => {
+  const blockers = [];
+  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 \u2014 run the explore-stage probe before advancing"
+    );
+  }
+  return { pass: blockers.length === 0, blockers };
+};
+var planToDesign = (s) => {
+  const blockers = [];
+  const parity = stageParity(s, "plan");
+  if (parity) blockers.push(parity);
+  if ((s.must_haves ?? []).length === 0) {
+    blockers.push("must_haves is empty \u2014 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> \u2014 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 };
+};
+var designToVerify = (s) => {
+  const blockers = [];
+  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}" \u2014 resolve in design before verify`
+      );
+    }
+  }
+  return { pass: blockers.length === 0, blockers };
+};
+var GATES = Object.freeze({
+  briefToExplore,
+  exploreToPlan,
+  planToDesign,
+  designToVerify
+});
+function gateFor(from, to) {
+  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;
+}
+
+// sdk/state/index.ts
+async function read(path) {
+  const raw = (0, import_node_fs2.readFileSync)(path, "utf8");
+  return parse(raw).state;
+}
+async function mutate(path, fn) {
+  const release = await acquire(path);
+  const tmpPath = `${path}.tmp`;
+  try {
+    const raw = (0, import_node_fs2.readFileSync)(path, "utf8");
+    const { state, raw_bodies, raw_frontmatter, block_gaps, line_ending } = parse(raw);
+    const clone = structuredClone(state);
+    const next = fn(clone);
+    const out = serialize(next, {
+      raw_frontmatter,
+      raw_bodies,
+      block_gaps,
+      line_ending
+    });
+    (0, import_node_fs2.writeFileSync)(tmpPath, out, "utf8");
+    try {
+      (0, import_node_fs2.renameSync)(tmpPath, path);
+    } catch (err) {
+      const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+      if (code === "EPERM" || code === "EBUSY") {
+        await new Promise((r) => setTimeout(r, 50));
+        (0, import_node_fs2.renameSync)(tmpPath, path);
+      } else {
+        throw err;
+      }
+    }
+    return next;
+  } catch (err) {
+    try {
+      if ((0, import_node_fs2.existsSync)(tmpPath)) (0, import_node_fs2.unlinkSync)(tmpPath);
+    } catch {
+    }
+    throw err;
+  } finally {
+    await release();
+  }
+}
+async function transition(path, toStage) {
+  const beforeMutate = await read(path);
+  const from = beforeMutate.position.stage;
+  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} \u2192 ${toStage}`
+    ]);
+  }
+  const gateResult = gate(beforeMutate);
+  if (!gateResult.pass) {
+    throw new TransitionGateFailed(toStage, gateResult.blockers);
+  }
+  const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+  const nextState = await mutate(path, (s) => {
+    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 };
+}
+
+// sdk/event-stream/index.ts
+var import_node_os2 = require("node:os");
+
+// sdk/event-stream/emitter.ts
+var import_node_events = require("node:events");
+var DEFAULT_MAX_LISTENERS = 50;
+var EventBus = class extends import_node_events.EventEmitter {
+  constructor() {
+    super();
+    this.setMaxListeners(DEFAULT_MAX_LISTENERS);
+  }
+  /**
+   * Subscribe to one specific event type. The handler fires for every
+   * subsequent `emit(type, ev)` call where `ev.type === type`. Returns
+   * a closure that detaches the listener on invocation.
+   *
+   * @example
+   * const off = bus.subscribe<StateMutationEvent>('state.mutation', (ev) => {
+   *   console.log(ev.payload.tool);
+   * });
+   * // …later
+   * off();
+   */
+  subscribe(type, handler) {
+    const listener = handler;
+    this.on(type, listener);
+    return () => {
+      this.off(type, listener);
+    };
+  }
+  /**
+   * Subscribe to *every* event regardless of type. Listeners registered
+   * here fire on the special `'*'` channel, which `appendEvent()`
+   * re-emits to on every event. Returns an unsubscribe closure.
+   */
+  subscribeAll(handler) {
+    const listener = handler;
+    this.on("*", listener);
+    return () => {
+      this.off("*", listener);
+    };
+  }
+};
+
+// sdk/event-stream/writer.ts
+var import_node_fs3 = require("node:fs");
+var import_node_path = require("node:path");
+var import_node_module = require("node:module");
+function _findRepoRoot() {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if ((0, import_node_fs3.existsSync)((0, import_node_path.join)(dir, "package.json"))) return dir;
+    const parent = (0, import_node_path.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+var _redact;
+try {
+  const _root = _findRepoRoot();
+  const _candidate = (0, import_node_path.resolve)(_root, "scripts/lib/redact.cjs");
+  if ((0, import_node_fs3.existsSync)(_candidate)) {
+    const _redactRequire = (0, import_node_module.createRequire)((0, import_node_path.join)(_root, "package.json"));
+    const _mod = _redactRequire(_candidate);
+    _redact = _mod.redact;
+  } else {
+    const _altRoot = (0, import_node_path.resolve)(_root, "..", "..");
+    const _altCandidate = (0, import_node_path.resolve)(_altRoot, "scripts/lib/redact.cjs");
+    if ((0, import_node_fs3.existsSync)(_altCandidate)) {
+      const _altRequire = (0, import_node_module.createRequire)((0, import_node_path.join)(_altRoot, "package.json"));
+      const _altMod = _altRequire(_altCandidate);
+      _redact = _altMod.redact;
+    } else {
+      _redact = (v) => v;
+    }
+  }
+} catch {
+  _redact = (v) => v;
+}
+var redact = _redact;
+var DEFAULT_EVENTS_PATH = ".design/telemetry/events.jsonl";
+var DEFAULT_MAX_LINE_BYTES = 64 * 1024;
+var EventWriter = class {
+  /** Resolved absolute target path. */
+  path;
+  /** Maximum line size in bytes (see {@link WriterOptions.maxLineBytes}). */
+  maxLineBytes;
+  /** Number of failed append attempts since construction. */
+  writeErrors = 0;
+  /** The most recent write error, or `null` if none has occurred. */
+  lastError = null;
+  /** `true` once we've ensured the target directory exists. */
+  directoryEnsured = false;
+  constructor(opts = {}) {
+    const rawPath = opts.path ?? DEFAULT_EVENTS_PATH;
+    this.path = (0, import_node_path.isAbsolute)(rawPath) ? rawPath : (0, import_node_path.resolve)(process.cwd(), rawPath);
+    this.maxLineBytes = opts.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+  }
+  /**
+   * Append one event to the target file.
+   *
+   * Contract:
+   *   * SYNC — returns when the write has been accepted by the kernel.
+   *   * NEVER throws — I/O errors increment {@link writeErrors} and update
+   *     {@link lastError}; a diagnostic is written to stderr and
+   *     execution continues.
+   *   * Truncates oversized payloads rather than dropping the event.
+   */
+  append(ev) {
+    try {
+      const line = this.serialize(ev);
+      this.ensureDirectory();
+      (0, import_node_fs3.appendFileSync)(this.path, line, { flag: "a" });
+    } catch (err) {
+      this.writeErrors += 1;
+      this.lastError = err instanceof Error ? err : new Error(String(err));
+      try {
+        process.stderr.write(
+          `[event-stream] write failed: ${this.lastError.message}
+`
+        );
+      } catch {
+      }
+    }
+  }
+  /**
+   * Produce the on-disk JSONL representation of an event, truncating
+   * oversized payloads so the line fits within {@link maxLineBytes}.
+   *
+   * Exposed on the instance for unit-testability; callers should use
+   * {@link append}.
+   */
+  serialize(ev) {
+    const scrubbed = redact(ev);
+    const raw = JSON.stringify(scrubbed) + "\n";
+    if (Buffer.byteLength(raw, "utf8") <= this.maxLineBytes) {
+      return raw;
+    }
+    const truncated = {
+      type: scrubbed.type,
+      timestamp: scrubbed.timestamp,
+      sessionId: scrubbed.sessionId,
+      payload: { _truncated_placeholder: true },
+      _truncated: true
+    };
+    if (scrubbed.stage !== void 0) truncated.stage = scrubbed.stage;
+    if (scrubbed.cycle !== void 0) truncated.cycle = scrubbed.cycle;
+    if (scrubbed._meta !== void 0) truncated._meta = scrubbed._meta;
+    return JSON.stringify(truncated) + "\n";
+  }
+  /**
+   * Ensure the target directory exists. Memoized so we only pay the
+   * filesystem stat cost once per writer lifetime.
+   */
+  ensureDirectory() {
+    if (this.directoryEnsured) return;
+    (0, import_node_fs3.mkdirSync)((0, import_node_path.dirname)(this.path), { recursive: true });
+    this.directoryEnsured = true;
+  }
+};
+
+// sdk/event-stream/index.ts
+var defaultWriter = null;
+var defaultBus = null;
+var cachedHost = null;
+function getWriter(opts) {
+  if (defaultWriter === null) {
+    const envPath = process.env["GDD_EVENTS_PATH"];
+    const finalOpts = opts?.path === void 0 && envPath !== void 0 && envPath.length > 0 ? { ...opts ?? {}, path: envPath } : opts ?? {};
+    defaultWriter = new EventWriter(finalOpts);
+  }
+  return defaultWriter;
+}
+function getBus() {
+  if (defaultBus === null) {
+    defaultBus = new EventBus();
+  }
+  return defaultBus;
+}
+function appendEvent(ev) {
+  if (ev._meta === void 0) {
+    if (cachedHost === null) {
+      try {
+        cachedHost = (0, import_node_os2.hostname)();
+      } catch {
+        cachedHost = "unknown";
+      }
+    }
+    const meta = {
+      pid: process.pid,
+      host: cachedHost,
+      source: "event-stream"
+    };
+    ev._meta = meta;
+  }
+  getWriter().append(ev);
+  const bus = getBus();
+  bus.emit(ev.type, ev);
+  bus.emit("*", ev);
+}
+
+// sdk/mcp/gdd-state/tools/shared.ts
+function makeSessionId() {
+  const iso = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  return `gdd-mcp-${iso}-${process.pid}`;
+}
+var CACHED_SESSION_ID = null;
+function getSessionId() {
+  if (CACHED_SESSION_ID === null) CACHED_SESSION_ID = makeSessionId();
+  return CACHED_SESSION_ID;
+}
+function resolveStatePath() {
+  const override = process.env["GDD_STATE_PATH"];
+  if (typeof override === "string" && override.length > 0) return override;
+  return ".design/STATE.md";
+}
+function isStageValue(value) {
+  return value === "brief" || value === "explore" || value === "plan" || value === "design" || value === "verify";
+}
+function emitStateMutation(tool, diff, stateAfter) {
+  const stage = isStageValue(stateAfter.position.stage) ? stateAfter.position.stage : void 0;
+  const ev = {
+    type: "state.mutation",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    sessionId: getSessionId(),
+    ...stage !== void 0 ? { stage } : {},
+    ...typeof stateAfter.frontmatter.cycle === "string" && stateAfter.frontmatter.cycle.length > 0 ? { cycle: stateAfter.frontmatter.cycle } : {},
+    payload: { tool, diff }
+  };
+  appendEvent(ev);
+}
+function emitStateTransition(from, to, pass, blockers, state) {
+  const cycle = state !== null && typeof state.frontmatter.cycle === "string" && state.frontmatter.cycle.length > 0 ? state.frontmatter.cycle : void 0;
+  const ev = {
+    type: "state.transition",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    sessionId: getSessionId(),
+    stage: pass ? to : from,
+    ...cycle !== void 0 ? { cycle } : {},
+    payload: { from, to, blockers: [...blockers], pass }
+  };
+  appendEvent(ev);
+}
+function errorResponse(err) {
+  const payload = toToolError(err);
+  return { success: false, error: payload.error };
+}
+function okResponse(data) {
+  return { success: true, data };
+}
+function throwValidation(codeSuffix, message, context) {
+  throw new ValidationError(message, `VALIDATION_${codeSuffix}`, context);
+}
+function operationFailed(codeSuffix, message, context) {
+  throw new OperationFailedError(
+    message,
+    `OPERATION_${codeSuffix}`,
+    context
+  );
+}
+
+// sdk/mcp/gdd-state/tools/get.ts
+var name = "gdd_state__get";
+var schemaPath = "../schemas/get.schema.json";
+function project(state, fields) {
+  const allowed = new Set(fields);
+  const out = {};
+  for (const [k, v] of Object.entries(state)) {
+    if (allowed.has(k)) out[k] = v;
+  }
+  return out;
+}
+async function handle(input) {
+  try {
+    const typed = input ?? {};
+    const path = resolveStatePath();
+    const state = await read(path);
+    const fields = Array.isArray(typed.fields) ? typed.fields : null;
+    const stateOut = fields === null || fields.length === 0 ? state : project(state, fields);
+    return okResponse({ state: stateOut, path });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/update_progress.ts
+var update_progress_exports = {};
+__export(update_progress_exports, {
+  handle: () => handle2,
+  name: () => name2,
+  schemaPath: () => schemaPath2
+});
+var name2 = "gdd_state__update_progress";
+var schemaPath2 = "../schemas/update_progress.schema.json";
+var TASK_PROGRESS_RE = /^[0-9]+\/[0-9]+$/;
+var STATUSES = /* @__PURE__ */ new Set([
+  "initialized",
+  "in_progress",
+  "completed",
+  "blocked"
+]);
+async function handle2(input) {
+  try {
+    const typed = input ?? {};
+    if (typed.task_progress === void 0 && typed.status === void 0) {
+      throwValidation(
+        "MISSING_FIELD",
+        "update_progress requires at least one of task_progress / status"
+      );
+    }
+    if (typed.task_progress !== void 0) {
+      if (!TASK_PROGRESS_RE.test(typed.task_progress)) {
+        throwValidation(
+          "TASK_PROGRESS_FORMAT",
+          `task_progress "${typed.task_progress}" must match N/M (digits)`
+        );
+      }
+    }
+    if (typed.status !== void 0 && !STATUSES.has(typed.status)) {
+      throwValidation(
+        "STATUS_INVALID",
+        `status "${typed.status}" is not one of initialized/in_progress/completed/blocked`
+      );
+    }
+    const path = resolveStatePath();
+    const diff = {};
+    const after = await mutate(path, (s) => {
+      if (typed.task_progress !== void 0) {
+        diff["task_progress"] = {
+          before: s.position.task_progress,
+          after: typed.task_progress
+        };
+        s.position.task_progress = typed.task_progress;
+      }
+      if (typed.status !== void 0) {
+        diff["status"] = { before: s.position.status, after: typed.status };
+        s.position.status = typed.status;
+      }
+      return s;
+    });
+    emitStateMutation(name2, diff, after);
+    return okResponse({ position: after.position });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/transition_stage.ts
+var transition_stage_exports = {};
+__export(transition_stage_exports, {
+  handle: () => handle3,
+  name: () => name3,
+  schemaPath: () => schemaPath3
+});
+var name3 = "gdd_state__transition_stage";
+var schemaPath3 = "../schemas/transition_stage.schema.json";
+async function handle3(input) {
+  try {
+    const typed = input ?? {};
+    if (!isStage(typed.to)) {
+      throwValidation(
+        "STAGE_INVALID",
+        `to "${String(typed.to)}" is not a recognized Stage`
+      );
+    }
+    const path = resolveStatePath();
+    const before = await read(path);
+    const fromValue = before.position.stage;
+    try {
+      const result = await transition(path, typed.to);
+      const fromNarrow = isStage(fromValue) ? fromValue : typed.to;
+      emitStateTransition(fromNarrow, typed.to, true, [], result.state);
+      return okResponse({
+        from: fromValue,
+        to: typed.to,
+        state: result.state
+      });
+    } catch (inner) {
+      if (inner instanceof TransitionGateFailed) {
+        const fromNarrow = isStage(fromValue) ? fromValue : typed.to;
+        emitStateTransition(
+          fromNarrow,
+          typed.to,
+          false,
+          [...inner.blockers],
+          before
+        );
+      }
+      throw inner;
+    }
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/add_blocker.ts
+var add_blocker_exports = {};
+__export(add_blocker_exports, {
+  handle: () => handle4,
+  name: () => name4,
+  schemaPath: () => schemaPath4
+});
+var name4 = "gdd_state__add_blocker";
+var schemaPath4 = "../schemas/add_blocker.schema.json";
+var DATE_RE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+async function handle4(input) {
+  try {
+    const typed = input ?? {};
+    if (typeof typed.text !== "string" || typed.text.length === 0) {
+      throwValidation("MISSING_FIELD", "add_blocker requires a non-empty text");
+    }
+    if (typed.date !== void 0 && !DATE_RE.test(typed.date)) {
+      throwValidation(
+        "DATE_FORMAT",
+        `date "${typed.date}" must be YYYY-MM-DD`
+      );
+    }
+    const path = resolveStatePath();
+    let appended = null;
+    let countAfter = 0;
+    const after = await mutate(path, (s) => {
+      const blocker = {
+        stage: typed.stage ?? s.position.stage ?? "",
+        date: typed.date ?? today(),
+        text: typed.text
+      };
+      s.blockers.push(blocker);
+      appended = blocker;
+      countAfter = s.blockers.length;
+      return s;
+    });
+    if (appended === null) {
+      throwValidation("INTERNAL", "blocker was not appended (unreachable)");
+    }
+    emitStateMutation(name4, { appended, count: countAfter }, after);
+    return okResponse({ blocker: appended, count: countAfter });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/resolve_blocker.ts
+var resolve_blocker_exports = {};
+__export(resolve_blocker_exports, {
+  handle: () => handle5,
+  name: () => name5,
+  schemaPath: () => schemaPath5
+});
+var name5 = "gdd_state__resolve_blocker";
+var schemaPath5 = "../schemas/resolve_blocker.schema.json";
+async function handle5(input) {
+  try {
+    const typed = input ?? {};
+    const hasIndex = typeof typed.index === "number";
+    const hasText = typeof typed.text === "string" && typed.text.length > 0;
+    if (hasIndex === hasText) {
+      throwValidation(
+        "ONEOF_REQUIRED",
+        "resolve_blocker requires exactly one of: index OR text"
+      );
+    }
+    if (hasIndex && typed.index < 0) {
+      throwValidation("INDEX_NEGATIVE", "index must be >= 0");
+    }
+    const path = resolveStatePath();
+    let removed = null;
+    let countAfter = 0;
+    const after = await mutate(path, (s) => {
+      if (hasIndex) {
+        const idx = typed.index;
+        if (idx >= s.blockers.length) {
+          operationFailed(
+            "BLOCKER_NOT_FOUND",
+            `no blocker at index ${idx} (length=${s.blockers.length})`,
+            { index: idx, length: s.blockers.length }
+          );
+        }
+        const [deleted] = s.blockers.splice(idx, 1);
+        removed = deleted ?? null;
+      } else {
+        const target = typed.text;
+        const idx = s.blockers.findIndex((b) => b.text === target);
+        if (idx === -1) {
+          operationFailed(
+            "BLOCKER_NOT_FOUND",
+            `no blocker matches text "${target}"`,
+            { text: target }
+          );
+        }
+        const [deleted] = s.blockers.splice(idx, 1);
+        removed = deleted ?? null;
+      }
+      countAfter = s.blockers.length;
+      return s;
+    });
+    if (removed === null) {
+      operationFailed("BLOCKER_NOT_FOUND", "no blocker was removed (unreachable)");
+    }
+    emitStateMutation(name5, { removed, count: countAfter }, after);
+    return okResponse({ removed, count: countAfter });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/add_decision.ts
+var add_decision_exports = {};
+__export(add_decision_exports, {
+  handle: () => handle6,
+  name: () => name6,
+  schemaPath: () => schemaPath6
+});
+var name6 = "gdd_state__add_decision";
+var schemaPath6 = "../schemas/add_decision.schema.json";
+var ID_RE = /^D-([0-9]+)$/;
+function nextDecisionId(existing) {
+  let max = 0;
+  for (const d of existing) {
+    const m = d.id.match(ID_RE);
+    if (m && m[1] !== void 0) {
+      const n = Number.parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  }
+  return `D-${max + 1}`;
+}
+async function handle6(input) {
+  try {
+    const typed = input ?? {};
+    if (typeof typed.text !== "string" || typed.text.length === 0) {
+      throwValidation("MISSING_FIELD", "add_decision requires a non-empty text");
+    }
+    if (typed.status !== void 0 && typed.status !== "locked" && typed.status !== "tentative") {
+      throwValidation(
+        "STATUS_INVALID",
+        `status "${String(typed.status)}" is not one of locked/tentative`
+      );
+    }
+    if (typed.id !== void 0 && !ID_RE.test(typed.id)) {
+      throwValidation("ID_FORMAT", `id "${typed.id}" must match D-<digits>`);
+    }
+    const path = resolveStatePath();
+    let appended = null;
+    let countAfter = 0;
+    const after = await mutate(path, (s) => {
+      const decision = {
+        id: typed.id ?? nextDecisionId(s.decisions),
+        text: typed.text,
+        status: typed.status ?? "tentative"
+      };
+      s.decisions.push(decision);
+      appended = decision;
+      countAfter = s.decisions.length;
+      return s;
+    });
+    if (appended === null) {
+      throwValidation("INTERNAL", "decision was not appended (unreachable)");
+    }
+    emitStateMutation(name6, { appended, count: countAfter }, after);
+    return okResponse({ decision: appended, count: countAfter });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/add_must_have.ts
+var add_must_have_exports = {};
+__export(add_must_have_exports, {
+  handle: () => handle7,
+  name: () => name7,
+  schemaPath: () => schemaPath7
+});
+var name7 = "gdd_state__add_must_have";
+var schemaPath7 = "../schemas/add_must_have.schema.json";
+var ID_RE2 = /^M-([0-9]+)$/;
+function nextMustHaveId(existing) {
+  let max = 0;
+  for (const m of existing) {
+    const match = m.id.match(ID_RE2);
+    if (match && match[1] !== void 0) {
+      const n = Number.parseInt(match[1], 10);
+      if (Number.isFinite(n) && n > max) max = n;
+    }
+  }
+  return `M-${max + 1}`;
+}
+async function handle7(input) {
+  try {
+    const typed = input ?? {};
+    if (typeof typed.text !== "string" || typed.text.length === 0) {
+      throwValidation(
+        "MISSING_FIELD",
+        "add_must_have requires a non-empty text"
+      );
+    }
+    if (typed.status !== void 0 && typed.status !== "pending" && typed.status !== "pass" && typed.status !== "fail") {
+      throwValidation(
+        "STATUS_INVALID",
+        `status "${String(typed.status)}" is not one of pending/pass/fail`
+      );
+    }
+    if (typed.id !== void 0 && !ID_RE2.test(typed.id)) {
+      throwValidation("ID_FORMAT", `id "${typed.id}" must match M-<digits>`);
+    }
+    const path = resolveStatePath();
+    let written = null;
+    let action = "insert";
+    let countAfter = 0;
+    const after = await mutate(path, (s) => {
+      const mh = {
+        id: typed.id ?? nextMustHaveId(s.must_haves),
+        text: typed.text,
+        status: typed.status ?? "pending"
+      };
+      const existingIdx = typed.id !== void 0 ? s.must_haves.findIndex((existing) => existing.id === mh.id) : -1;
+      if (existingIdx >= 0) {
+        s.must_haves[existingIdx] = mh;
+        action = "update";
+      } else {
+        s.must_haves.push(mh);
+        action = "insert";
+      }
+      written = mh;
+      countAfter = s.must_haves.length;
+      return s;
+    });
+    if (written === null) {
+      throwValidation("INTERNAL", "must_have was not written (unreachable)");
+    }
+    emitStateMutation(
+      name7,
+      { must_have: written, action, count: countAfter },
+      after
+    );
+    return okResponse({ must_have: written, action, count: countAfter });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/set_status.ts
+var set_status_exports = {};
+__export(set_status_exports, {
+  handle: () => handle8,
+  name: () => name8,
+  schemaPath: () => schemaPath8
+});
+var name8 = "gdd_state__set_status";
+var schemaPath8 = "../schemas/set_status.schema.json";
+var STATUSES2 = /* @__PURE__ */ new Set([
+  "initialized",
+  "in_progress",
+  "completed",
+  "blocked"
+]);
+async function handle8(input) {
+  try {
+    const typed = input ?? {};
+    if (typeof typed.status !== "string" || !STATUSES2.has(typed.status)) {
+      throwValidation(
+        "STATUS_INVALID",
+        `status "${String(typed.status)}" is not one of initialized/in_progress/completed/blocked`
+      );
+    }
+    const path = resolveStatePath();
+    const diff = {};
+    const after = await mutate(path, (s) => {
+      diff["status"] = { before: s.position.status, after: typed.status };
+      s.position.status = typed.status;
+      return s;
+    });
+    emitStateMutation(name8, diff, after);
+    return okResponse({ status: after.position.status });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/checkpoint.ts
+var checkpoint_exports = {};
+__export(checkpoint_exports, {
+  handle: () => handle9,
+  name: () => name9,
+  schemaPath: () => schemaPath9
+});
+var name9 = "gdd_state__checkpoint";
+var schemaPath9 = "../schemas/checkpoint.schema.json";
+async function handle9(input) {
+  try {
+    const typed = input ?? {};
+    if (typed.label !== void 0 && (typeof typed.label !== "string" || typed.label.length === 0)) {
+      throwValidation("LABEL_FORMAT", "label must be a non-empty string");
+    }
+    const path = resolveStatePath();
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    let timestampKey = "";
+    const after = await mutate(path, (s) => {
+      s.frontmatter.last_checkpoint = nowIso;
+      const stage = typeof s.position.stage === "string" ? s.position.stage : "";
+      timestampKey = typed.label !== void 0 ? `${typed.label}_at` : stage.length > 0 ? `${stage}_checkpoint_at` : "checkpoint_at";
+      s.timestamps[timestampKey] = nowIso;
+      return s;
+    });
+    emitStateMutation(
+      name9,
+      { last_checkpoint: nowIso, timestamp_key: timestampKey },
+      after
+    );
+    return okResponse({ last_checkpoint: nowIso, timestamp_key: timestampKey });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/probe_connections.ts
+var probe_connections_exports = {};
+__export(probe_connections_exports, {
+  handle: () => handle10,
+  name: () => name10,
+  schemaPath: () => schemaPath10
+});
+var name10 = "gdd_state__probe_connections";
+var schemaPath10 = "../schemas/probe_connections.schema.json";
+async function handle10(input) {
+  try {
+    const typed = input ?? {};
+    if (!Array.isArray(typed.probe_results) || typed.probe_results.length === 0) {
+      throwValidation(
+        "MISSING_FIELD",
+        "probe_connections requires a non-empty probe_results array"
+      );
+    }
+    for (const p of typed.probe_results) {
+      if (!p || typeof p.name !== "string" || p.name.length === 0) {
+        throwValidation(
+          "PROBE_RESULT_NAME",
+          "each probe_result must have a non-empty name"
+        );
+      }
+      if (!isConnectionStatus(p.status)) {
+        throwValidation(
+          "PROBE_RESULT_STATUS",
+          `status "${String(p.status)}" is not one of available/unavailable/not_configured`
+        );
+      }
+    }
+    const path = resolveStatePath();
+    const updated = [];
+    const diff = {};
+    const after = await mutate(path, (s) => {
+      for (const p of typed.probe_results) {
+        const before = Object.prototype.hasOwnProperty.call(s.connections, p.name) ? s.connections[p.name] : null;
+        s.connections[p.name] = p.status;
+        updated.push(p.name);
+        diff[p.name] = { before, after: p.status };
+      }
+      return s;
+    });
+    emitStateMutation(name10, { diff }, after);
+    return okResponse({ updated, connections: after.connections });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/frontmatter_update.ts
+var frontmatter_update_exports = {};
+__export(frontmatter_update_exports, {
+  FORBIDDEN_KEYS: () => FORBIDDEN_KEYS,
+  handle: () => handle11,
+  name: () => name11,
+  schemaPath: () => schemaPath11
+});
+var name11 = "gdd_state__frontmatter_update";
+var schemaPath11 = "../schemas/frontmatter_update.schema.json";
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+  "pipeline_state_version",
+  "stage"
+]);
+function isScalar(v) {
+  return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+async function handle11(input) {
+  try {
+    const typed = input ?? {};
+    if (typed.patch === void 0 || typed.patch === null || typeof typed.patch !== "object") {
+      throwValidation(
+        "MISSING_FIELD",
+        "frontmatter_update requires an object patch"
+      );
+    }
+    const keys = Object.keys(typed.patch);
+    if (keys.length === 0) {
+      throwValidation("EMPTY_PATCH", "patch must contain at least one key");
+    }
+    for (const k of keys) {
+      if (FORBIDDEN_KEYS.has(k)) {
+        throwValidation(
+          "FORBIDDEN_KEY",
+          `patching "${k}" is not allowed via frontmatter_update (stage must go through transition_stage)`,
+          { key: k }
+        );
+      }
+      const value = typed.patch[k];
+      if (!isScalar(value)) {
+        throwValidation(
+          "NON_SCALAR_VALUE",
+          `patch value for "${k}" must be a string, number, or boolean`,
+          { key: k }
+        );
+      }
+    }
+    const path = resolveStatePath();
+    const diff = {};
+    const after = await mutate(path, (s) => {
+      for (const k of keys) {
+        const before = s.frontmatter[k];
+        const value = typed.patch[k];
+        s.frontmatter[k] = value;
+        diff[k] = { before, after: value };
+      }
+      return s;
+    });
+    emitStateMutation(name11, { diff }, after);
+    return okResponse({ frontmatter: after.frontmatter, keys });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
+
+// sdk/mcp/gdd-state/tools/index.ts
+var TOOL_MODULES = [
+  get_exports,
+  add_blocker_exports,
+  add_decision_exports,
+  add_must_have_exports,
+  checkpoint_exports,
+  frontmatter_update_exports,
+  probe_connections_exports,
+  resolve_blocker_exports,
+  set_status_exports,
+  transition_stage_exports,
+  update_progress_exports
+];
+var TOOL_COUNT = TOOL_MODULES.length;
+
+// sdk/mcp/gdd-state/server.ts
+var SERVER_NAME = "gdd-state";
+var SERVER_VERSION = "1.20.0";
+function here() {
+  const expectedRel = (0, import_node_path2.join)("sdk", "mcp", "gdd-state");
+  const entry = process.argv[1];
+  if (typeof entry === "string" && entry.length > 0) {
+    const entryDir = (0, import_node_path2.dirname)((0, import_node_path2.resolve)(entry));
+    if ((0, import_node_fs4.existsSync)((0, import_node_path2.join)(entryDir, "tools", "index.ts"))) {
+      return entryDir;
+    }
+  }
+  const candidate = (0, import_node_path2.resolve)(process.cwd(), expectedRel);
+  if ((0, import_node_fs4.existsSync)((0, import_node_path2.join)(candidate, "tools", "index.ts"))) {
+    return candidate;
+  }
+  return candidate;
+}
+function loadTools() {
+  const baseDir = here();
+  return TOOL_MODULES.map((m) => {
+    const absPath = (0, import_node_path2.join)(baseDir, "tools", m.schemaPath);
+    const raw = (0, import_node_fs4.readFileSync)(absPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const rawInput = parsed.properties?.input;
+    const inputSchema = rawInput !== void 0 && typeof rawInput === "object" ? rawInput : { type: "object" };
+    if (!("type" in inputSchema)) inputSchema["type"] = "object";
+    return { ...m, inputSchema };
+  });
+}
+var TOOL_DESCRIPTIONS = {
+  gdd_state__get: "Read current STATE.md (parsed). Read-only; no event emitted. Optionally projects a subset of fields.",
+  gdd_state__update_progress: "Update <position>.task_progress and/or status. Emits state.mutation.",
+  gdd_state__transition_stage: "Run gate and advance <position>.stage on pass. Gate vetoes return {success:false, error:{context:{blockers:[...]}}}; never crashes the server. Emits state.transition.",
+  gdd_state__add_blocker: "Append one entry to <blockers>. Defaults stage to current position.stage and date to today (UTC). Emits state.mutation.",
+  gdd_state__resolve_blocker: "Remove one <blockers> entry by 0-based index or exact text match. Returns operation_failed when no row matches. Emits state.mutation on removal.",
+  gdd_state__add_decision: "Append one entry to <decisions>. Auto-allocates D-N id when not supplied. Emits state.mutation.",
+  gdd_state__add_must_have: "Append one entry to <must_haves>. Auto-allocates M-N id when not supplied. Emits state.mutation.",
+  gdd_state__set_status: "Update <position>.status. Emits state.mutation.",
+  gdd_state__checkpoint: "Update frontmatter.last_checkpoint and append a <timestamps> entry. Emits state.mutation.",
+  gdd_state__probe_connections: "Merge probe results into <connections>. Overwrites keys present in the input; does NOT delete keys not in the input. Emits state.mutation.",
+  gdd_state__frontmatter_update: "Patch one or more frontmatter fields. Rejects pipeline_state_version and stage (use transition_stage). Emits state.mutation."
+};
+var TOOL_READONLY = {
+  gdd_state__get: true
+};
+function buildServer() {
+  const tools = loadTools();
+  const byName = /* @__PURE__ */ new Map();
+  for (const t of tools) byName.set(t.name, t);
+  const server = new import_server.Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      capabilities: { tools: {} }
+    }
+  );
+  server.setRequestHandler(import_types8.ListToolsRequestSchema, async () => {
+    return {
+      tools: tools.map((t) => {
+        const description = TOOL_DESCRIPTIONS[t.name] ?? t.name;
+        const readOnly = TOOL_READONLY[t.name] ?? false;
+        return {
+          name: t.name,
+          description,
+          inputSchema: t.inputSchema,
+          annotations: {
+            readOnlyHint: readOnly,
+            destructiveHint: !readOnly,
+            idempotentHint: false
+          }
+        };
+      })
+    };
+  });
+  server.setRequestHandler(import_types8.CallToolRequestSchema, async (req) => {
+    const { name: toolName, arguments: args } = req.params;
+    const tool = byName.get(toolName);
+    if (tool === void 0) {
+      const payload = toToolError(
+        new Error(`unknown tool: ${toolName}`)
+      );
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: JSON.stringify({ success: false, error: payload.error }) }
+        ],
+        structuredContent: { success: false, error: payload.error }
+      };
+    }
+    let response;
+    try {
+      response = await tool.handle(args ?? {});
+    } catch (err) {
+      const payload = toToolError(err);
+      response = { success: false, error: payload.error };
+    }
+    const text = JSON.stringify(response);
+    if (response.success === true) {
+      return {
+        content: [{ type: "text", text }],
+        structuredContent: response
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: "text", text }],
+      structuredContent: response
+    };
+  });
+  return server;
+}
+async function runStdio() {
+  const server = buildServer();
+  const transport = new import_stdio.StdioServerTransport();
+  const shutdown = async (signal) => {
+    if (SHUTTING_DOWN) return;
+    SHUTTING_DOWN = true;
+    try {
+      await server.close();
+    } catch {
+    }
+    process.exit(signal === "SIGTERM" ? 0 : 0);
+  };
+  process.on("SIGINT", () => {
+    void shutdown("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    void shutdown("SIGTERM");
+  });
+  await server.connect(transport);
+}
+var SHUTTING_DOWN = false;
+function isMain() {
+  const entry = process.argv[1];
+  if (typeof entry !== "string" || entry.length === 0) return false;
+  return /sdk\/mcp\/gdd-state\/server\.(ts|js|cjs|mjs)$/.test(
+    entry.replace(/\\/g, "/")
+  );
+}
+if (isMain()) {
+  runStdio().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[gdd-state] fatal: ${msg}`);
+    process.exit(1);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildServer,
+  runStdio
+});