@tekyzinc/gsd-t 2.71.13 → 2.71.14

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.71.14] - 2026-04-08
+
+### Added (design-build orchestrator)
+- **Abstract workflow orchestrator** (`bin/orchestrator.js`) — base engine for deterministic multi-phase pipelines. Handles Claude spawning, review queue management, ironclad JS polling gates, state persistence/resume, server lifecycle, and cleanup. Workflow definitions plug in via a simple interface (phases, prompts, measurement, feedback). Zero external dependencies.
+- **Design-build workflow** (`bin/design-orchestrator.js`) — first workflow implementation: elements → widgets → pages. Discovers contracts from `.gsd-t/contracts/design/`, builds per-tier Claude prompts, Playwright measurement, and review queue items. Plugs into the base orchestrator.
+- **CLI subcommand** — `gsd-t design-build [--resume] [--tier] [--dev-port] [--review-port]` delegates to the orchestrator. Integrated into `bin/gsd-t.js` help and switch statement.
+- **Resume capability** — orchestrator persists state to `orchestrator-state.json`, supports `--resume` to continue from where it left off after interruption.
+
+### Why
+Three separate attempts to enforce review gates via prompt instructions all failed — Claude Code agents optimize for task completion and skip any instruction to pause indefinitely. The orchestrator moves flow control out of prompts entirely into deterministic JavaScript.
+
 ## [2.71.13] - 2026-04-08
 
 ### Fixed (design-decompose — successor hint)

package/bin/design-orchestrator.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Design Build Workflow
+ *
+ * Workflow definition for the design-build pipeline (elements → widgets → pages).
+ * Plugs into the base Orchestrator engine for deterministic flow control.
+ *
+ * Usage:
+ *   gsd-t design-build [--resume] [--tier elements|widgets|pages] [--dev-port N] [--review-port N]
+ *
+ * Or directly:
+ *   node bin/design-orchestrator.js [options]
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { Orchestrator, info, warn, success, error, log, BOLD, RESET, DIM } = require("./orchestrator.js");
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const PHASES = ["elements", "widgets", "pages"];
+const PHASE_SINGULAR = { elements: "element", widgets: "widget", pages: "page" };
+const CONTRACTS_DIR = ".gsd-t/contracts/design";
+
+// ─── Contract Discovery ─────────────────────────────────────────────────────
+
+function discoverWork(projectDir) {
+  const contractsDir = path.join(projectDir, CONTRACTS_DIR);
+  const indexPath = path.join(contractsDir, "INDEX.md");
+
+  if (!fs.existsSync(indexPath)) {
+    error("No design contracts found. Run /user:gsd-t-design-decompose first.");
+    process.exit(1);
+  }
+
+  const result = { elements: [], widgets: [], pages: [] };
+  const indexContent = fs.readFileSync(indexPath, "utf8");
+  const linkRegex = /^\s*-\s+\[([^\]]+)\]\(([^)]+)\)/gm;
+  let match;
+
+  while ((match = linkRegex.exec(indexContent)) !== null) {
+    const name = match[1];
+    const relPath = match[2];
+    const fullPath = path.join(contractsDir, relPath);
+
+    if (!fs.existsSync(fullPath)) {
+      warn(`Contract file missing: ${relPath}`);
+      continue;
+    }
+
+    let phase = null;
+    for (const p of PHASES) {
+      if (relPath.startsWith(`${p}/`)) { phase = p; break; }
+    }
+    if (!phase) continue;
+
+    const contract = parseContract(fullPath, name);
+    contract.contractPath = relPath;
+    contract.fullContractPath = fullPath;
+    result[phase].push(contract);
+  }
+
+  return result;
+}
+
+function parseContract(filePath, fallbackName) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const contract = {
+    id: fallbackName,
+    name: fallbackName,
+    sourcePath: null,
+    selector: null,
+    route: "/",
+  };
+
+  const nameMatch = content.match(/\|\s*(?:element|widget|page)\s*\|\s*(.+?)\s*\|/i);
+  if (nameMatch) contract.id = nameMatch[1].trim();
+
+  const sourceMatch = content.match(/\|\s*source_path\s*\|\s*(.+?)\s*\|/i);
+  if (sourceMatch) contract.sourcePath = sourceMatch[1].trim();
+
+  const selectorMatch = content.match(/\|\s*selector\s*\|\s*(.+?)\s*\|/i);
+  if (selectorMatch) contract.selector = selectorMatch[1].trim();
+
+  const routeMatch = content.match(/\|\s*route\s*\|\s*(.+?)\s*\|/i);
+  if (routeMatch) contract.route = routeMatch[1].trim();
+
+  contract.componentName = contract.id
+    .split("-")
+    .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("");
+
+  return contract;
+}
+
+// ─── Prompt Building ────────────────────────────────────────────────────────
+
+function buildPrompt(phase, items, prevResults, projectDir) {
+  const singular = PHASE_SINGULAR[phase];
+  const contractList = items.map(c => {
+    const sourcePath = c.sourcePath || guessPaths(phase, c);
+    return `- ${c.componentName}: read contract at ${c.fullContractPath}, write to ${sourcePath}`;
+  }).join("\n");
+
+  const prevPaths = [];
+  for (const [, result] of Object.entries(prevResults)) {
+    if (result.builtPaths) prevPaths.push(...result.builtPaths);
+  }
+
+  const importInstructions = prevPaths.length > 0
+    ? `\n## Imports from Previous Tier\nImport these already-built components — do NOT rebuild their functionality inline:\n${prevPaths.map(p => `- ${p}`).join("\n")}\n`
+    : "";
+
+  return `You are building ${singular} components for a Vue 3 + TypeScript project.
+
+## Task
+Build ONLY the following ${items.length} ${phase} components from their design contracts.
+Read each contract file for exact visual specs — do NOT approximate values.
+
+## Components to Build
+${contractList}
+
+${importInstructions}
+## Rules
+- Read each contract file (the full path is given above) for exact property values
+- Write components to the specified source paths
+- Follow the project's existing code conventions (check existing files in src/)
+- Use the project's existing dependencies (check package.json)
+- When ALL ${items.length} components are complete, STOP. Do not start a dev server, do not ask for review, do not build components from other tiers.
+
+## Important
+This is a FINITE task. Build the ${items.length} ${phase} listed above, then EXIT.`;
+}
+
+// ─── Measurement ────────────────────────────────────────────────────────────
+
+function hasPlaywright(projectDir) {
+  try {
+    return fs.existsSync(path.join(projectDir, "node_modules", "@playwright", "test", "package.json"));
+  } catch {
+    return false;
+  }
+}
+
+function measure(projectDir, phase, items, ports) {
+  if (!hasPlaywright(projectDir)) {
+    warn("Playwright not found — skipping automated measurement. Human review only.");
+    const results = {};
+    for (const c of items) results[c.id] = [];
+    return results;
+  }
+
+  info(`Measuring ${items.length} ${phase} with Playwright...`);
+
+  const measureScript = buildMeasureScript(items, ports.reviewPort);
+  const scriptDir = path.join(projectDir, ".gsd-t", "design-review");
+  try { fs.mkdirSync(scriptDir, { recursive: true }); } catch { /* exists */ }
+  const scriptPath = path.join(scriptDir, "_measure.mjs");
+  fs.writeFileSync(scriptPath, measureScript);
+
+  const results = {};
+  try {
+    const output = execFileSync("node", [scriptPath], {
+      encoding: "utf8",
+      timeout: 60_000,
+      cwd: projectDir,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    try {
+      const parsed = JSON.parse(output.trim());
+      for (const [id, measurements] of Object.entries(parsed)) {
+        results[id] = measurements;
+      }
+    } catch {
+      warn("Could not parse measurement output — proceeding without measurements");
+    }
+  } catch (e) {
+    warn(`Measurement failed: ${(e.message || "").slice(0, 100)}`);
+  }
+
+  try { fs.unlinkSync(scriptPath); } catch { /* ignore */ }
+
+  let passing = 0, failing = 0;
+  for (const measurements of Object.values(results)) {
+    for (const m of measurements) {
+      if (m.pass) passing++; else failing++;
+    }
+  }
+  if (failing > 0) warn(`Measurements: ${passing} pass, ${failing} fail`);
+  else if (passing > 0) success(`Measurements: ${passing} pass, 0 fail`);
+
+  return results;
+}
+
+function buildMeasureScript(items, reviewPort) {
+  const selectors = items
+    .filter(c => c.selector)
+    .map(c => `  "${c.id}": "${c.selector}"`)
+    .join(",\n");
+
+  return `
+import { chromium } from "playwright";
+
+const SELECTORS = {
+${selectors}
+};
+
+async function measure() {
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+  await page.setViewportSize({ width: 1440, height: 900 });
+
+  try {
+    await page.goto("http://localhost:${reviewPort}/", { waitUntil: "networkidle", timeout: 15000 });
+  } catch {
+    await page.goto("http://localhost:${reviewPort}/", { waitUntil: "load", timeout: 10000 });
+  }
+
+  await page.waitForTimeout(2000);
+
+  const results = {};
+
+  for (const [id, selector] of Object.entries(SELECTORS)) {
+    try {
+      const measurements = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return [{ property: "element exists", expected: "yes", actual: "no", pass: false, severity: "critical" }];
+
+        const s = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+
+        return [
+          { property: "element exists", expected: "yes", actual: "yes", pass: true },
+          { property: "display", expected: "visible", actual: s.display === "none" ? "hidden" : "visible", pass: s.display !== "none" },
+          { property: "width", expected: ">0", actual: String(Math.round(rect.width)) + "px", pass: rect.width > 0 },
+          { property: "height", expected: ">0", actual: String(Math.round(rect.height)) + "px", pass: rect.height > 0 },
+        ];
+      }, selector);
+
+      results[id] = measurements;
+    } catch {
+      results[id] = [{ property: "measurement", expected: "success", actual: "error", pass: false, severity: "critical" }];
+    }
+  }
+
+  await browser.close();
+  process.stdout.write(JSON.stringify(results));
+}
+
+measure().catch(e => {
+  process.stderr.write(e.message);
+  process.exit(1);
+});
+`;
+}
+
+// ─── Queue Items ────────────────────────────────────────────────────────────
+
+function buildQueueItem(phase, item, measurements) {
+  const singular = PHASE_SINGULAR[phase];
+  const sourcePath = item.sourcePath || guessPaths(phase, item);
+  return {
+    id: `${singular}-${item.id}`,
+    name: item.componentName,
+    type: singular,
+    selector: item.selector || `.${item.id}`,
+    sourcePath,
+    route: item.route || "/",
+    measurements: (measurements && measurements[item.id]) || [],
+  };
+}
+
+// ─── Path Guessing ──────────────────────────────────────────────────────────
+
+function guessPaths(phase, item) {
+  const dirMap = {
+    elements: "src/components/elements",
+    widgets: "src/components/widgets",
+    pages: "src/views",
+  };
+  return `${dirMap[phase]}/${item.componentName}.vue`;
+}
+
+// ─── Fix Prompt ─────────────────────────────────────────────────────────────
+
+function buildFixPrompt(phase, needsWork) {
+  const fixes = needsWork.map(item => {
+    const parts = [`Fix ${item.id}:`];
+    if (item.changes?.length) {
+      for (const c of item.changes) {
+        parts.push(`  - ${c.property}: change from ${c.oldValue} to ${c.newValue} in ${c.path || "the component file"}`);
+      }
+    }
+    if (item.comment) parts.push(`  - Additional: ${item.comment}`);
+    return parts.join("\n");
+  }).join("\n\n");
+
+  return `Apply these specific fixes to ${phase} components:\n\n${fixes}\n\nApply the changes and EXIT. Do not rebuild anything else.`;
+}
+
+// ─── Summary ────────────────────────────────────────────────────────────────
+
+function formatSummary(phase, result) {
+  return `${phase}: ${result.builtPaths.length} components built (${result.reviewCycles} review cycle${result.reviewCycles > 1 ? "s" : ""})`;
+}
+
+// ─── Usage ──────────────────────────────────────────────────────────────────
+
+function showUsage() {
+  log(`
+${BOLD}GSD-T Design Build Orchestrator${RESET}
+
+${BOLD}Usage:${RESET}
+  gsd-t design-build [options]
+
+${BOLD}Options:${RESET}
+  --resume          Resume from last saved state
+  --tier <name>     Start from specific tier (elements, widgets, pages)
+  --project <dir>   Project directory (default: cwd)
+  --dev-port <N>    Dev server port (default: 5173)
+  --review-port <N> Review server port (default: 3456)
+  --timeout <sec>   Claude timeout per tier in seconds (default: 600)
+  --skip-measure    Skip Playwright measurement (human-review only)
+  --help            Show this help
+
+${BOLD}Pipeline:${RESET}
+  1. Read contracts from .gsd-t/contracts/design/
+  2. Start dev server + review server
+  3. For each tier (elements → widgets → pages):
+     a. Spawn Claude to build components
+     b. Measure with Playwright
+     c. Queue for human review
+     d. Wait for review submission (blocks until human approves)
+     e. Process feedback, proceed to next tier
+`);
+}
+
+// ─── Workflow Definition ────────────────────────────────────────────────────
+
+const designBuildWorkflow = {
+  name: "Design Build",
+  command: "design-build",
+  phases: PHASES,
+  reviewDir: ".gsd-t/design-review",
+  stateFile: ".gsd-t/design-review/orchestrator-state.json",
+  defaults: {
+    devPort: 5173,
+    reviewPort: 3456,
+    timeout: 600_000,
+    devServerTimeout: 30_000,
+    maxReviewCycles: 3,
+  },
+  completionMessage: "All done. Run your app to verify: npm run dev",
+
+  discoverWork,
+  buildPrompt,
+  measure,
+  buildQueueItem,
+  buildFixPrompt,
+  guessPaths,
+  formatSummary,
+  showUsage,
+
+  // Use --tier as alias for --phase (design-build convention)
+  parseArgs(argv, parseBase) {
+    return parseBase(argv);
+  },
+};
+
+// ─── Entry Point ────────────────────────────────────────────────────────────
+
+function run(args) {
+  new Orchestrator(designBuildWorkflow).run(args || []);
+}
+
+if (require.main === module) {
+  run(process.argv.slice(2));
+}
+
+module.exports = { run, workflow: designBuildWorkflow };

package/bin/gsd-t.js

@@ -2562,6 +2562,7 @@ function showHelp() {
   log(`  ${CYAN}changelog${RESET}      Open changelog in the browser`);
   log(`  ${CYAN}graph${RESET}          Code graph operations (index, status, query)`);
   log(`  ${CYAN}headless${RESET}       Non-interactive execution via claude -p + fast state queries`);
+  log(`  ${CYAN}design-build${RESET}   Deterministic design→code pipeline (elements → widgets → pages)`);
   log(`  ${CYAN}help${RESET}           Show this help\n`);
   log(`${BOLD}Examples:${RESET}`);
   log(`  ${DIM}$${RESET} npx @tekyzinc/gsd-t install`);
@@ -2696,6 +2697,11 @@ if (require.main === module) {
     case "headless":
       doHeadless(args.slice(1));
       break;
+    case "design-build": {
+      const orchestrator = require("./design-orchestrator.js");
+      orchestrator.run(args.slice(1));
+      break;
+    }
     case "scan": {
       const exportFlag = args.find(a => a.startsWith('--export='));
       const exportFormat = exportFlag ? exportFlag.split('=')[1] : null;

package/bin/orchestrator.js

@@ -0,0 +1,682 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Workflow Orchestrator — Base Engine
+ *
+ * Abstract pipeline engine that runs deterministic, multi-phase workflows.
+ * Each phase: spawn Claude → measure → gate (human review) → feedback → next phase.
+ *
+ * Workflow definitions plug into this engine by providing:
+ *   - phases: ordered list of phase names
+ *   - discoverWork(projectDir): returns { [phase]: items[] }
+ *   - buildPrompt(phase, items, previousResults, projectDir): returns string
+ *   - measure(projectDir, phase, items, ports): returns measurements
+ *   - buildQueueItem(phase, item, measurements): returns queue item object
+ *   - processFeedback(projectDir, phase, items): returns { approved[], needsWork[] }
+ *   - buildFixPrompt(phase, needsWork): returns string
+ *   - guessPaths(phase, item): returns source path
+ *   - formatSummary(phase, result): returns string for final report
+ *
+ * Usage:
+ *   const { Orchestrator } = require("./orchestrator.js");
+ *   const workflow = require("./workflows/design-build.js");
+ *   new Orchestrator(workflow).run(process.argv.slice(2));
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync, spawn: cpSpawn } = require("child_process");
+
+// ─── ANSI Colors ────────────────────────────────────────────────────────────
+
+const BOLD = "\x1b[1m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const CYAN = "\x1b[36m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+// ─── Helpers (exported for workflows) ───────────────────────────────────────
+
+function log(msg) { console.log(msg); }
+function heading(msg) { log(`\n${BOLD}${msg}${RESET}\n`); }
+function success(msg) { log(`${GREEN}  ✓${RESET} ${msg}`); }
+function warn(msg) { log(`${YELLOW}  ⚠${RESET} ${msg}`); }
+function error(msg) { log(`${RED}  ✗${RESET} ${msg}`); }
+function info(msg) { log(`${CYAN}  ℹ${RESET} ${msg}`); }
+function dim(msg) { log(`${DIM}    ${msg}${RESET}`); }
+
+function ensureDir(dir) {
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* exists */ }
+}
+
+function syncSleep(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    try { execFileSync("sleep", [String(ms / 1000)], { stdio: "pipe" }); } catch { /* ignore */ }
+  }
+}
+
+function openBrowser(url) {
+  try {
+    if (process.platform === "darwin") {
+      cpSpawn("open", [url], { detached: true, stdio: "ignore" }).unref();
+    } else {
+      cpSpawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+  } catch { /* user can open manually */ }
+}
+
+function isPortInUse(port) {
+  try {
+    execFileSync("curl", ["-sf", "-o", "/dev/null", `http://localhost:${port}`], {
+      timeout: 2000, stdio: "pipe"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Orchestrator Class ────────────────────────────────────────────────────
+
+class Orchestrator {
+  /**
+   * @param {object} workflow — workflow definition object
+   * @param {string} workflow.name — display name (e.g., "Design Build")
+   * @param {string[]} workflow.phases — ordered phase names (e.g., ["elements", "widgets", "pages"])
+   * @param {object} [workflow.defaults] — default port/timeout overrides
+   * @param {string} [workflow.reviewDir] — review directory relative to project (default: ".gsd-t/design-review")
+   * @param {string} [workflow.stateFile] — state file relative to project
+   * @param {Function} workflow.discoverWork — (projectDir) => { [phase]: items[] }
+   * @param {Function} workflow.buildPrompt — (phase, items, prevResults, projectDir) => string
+   * @param {Function} [workflow.measure] — (projectDir, phase, items, ports) => measurements
+   * @param {Function} [workflow.buildQueueItem] — (phase, item, measurements) => queue item
+   * @param {Function} [workflow.processFeedback] — (projectDir, phase, items) => { approved[], needsWork[] }
+   * @param {Function} [workflow.buildFixPrompt] — (phase, needsWork) => string
+   * @param {Function} [workflow.guessPaths] — (phase, item) => sourcePath
+   * @param {Function} [workflow.formatSummary] — (phase, result) => string
+   * @param {Function} [workflow.parseArgs] — (argv, defaults) => opts (extend base arg parsing)
+   * @param {Function} [workflow.showUsage] — () => void (custom usage text)
+   * @param {Function} [workflow.startServers] — (projectDir, opts) => { pids[], devPort, reviewPort }
+   * @param {Function} [workflow.validate] — (projectDir) => void (pre-flight checks, may exit)
+   */
+  constructor(workflow) {
+    this.wf = workflow;
+    this.pids = [];
+  }
+
+  // ─── CLI ─────────────────────────────────────────────────────────────
+
+  parseBaseArgs(argv) {
+    const defaults = this.wf.defaults || {};
+    const opts = {
+      projectDir: process.cwd(),
+      resume: false,
+      startPhase: null,
+      devPort: defaults.devPort || 5173,
+      reviewPort: defaults.reviewPort || 3456,
+      timeout: defaults.timeout || 600_000,
+      skipMeasure: false,
+    };
+
+    for (let i = 0; i < argv.length; i++) {
+      switch (argv[i]) {
+        case "--resume": opts.resume = true; break;
+        case "--phase":
+        case "--tier": opts.startPhase = argv[++i]; break;
+        case "--project": opts.projectDir = path.resolve(argv[++i]); break;
+        case "--dev-port": opts.devPort = parseInt(argv[++i], 10); break;
+        case "--review-port": opts.reviewPort = parseInt(argv[++i], 10); break;
+        case "--timeout": opts.timeout = parseInt(argv[++i], 10) * 1000; break;
+        case "--skip-measure": opts.skipMeasure = true; break;
+        case "--help":
+        case "-h":
+          if (this.wf.showUsage) this.wf.showUsage();
+          else this._showDefaultUsage();
+          process.exit(0);
+      }
+    }
+
+    return opts;
+  }
+
+  _showDefaultUsage() {
+    log(`
+${BOLD}GSD-T ${this.wf.name} Orchestrator${RESET}
+
+${BOLD}Usage:${RESET}
+  gsd-t ${this.wf.command || "orchestrate"} [options]
+
+${BOLD}Options:${RESET}
+  --resume              Resume from last saved state
+  --phase <name>        Start from specific phase (${this.wf.phases.join(", ")})
+  --project <dir>       Project directory (default: cwd)
+  --dev-port <N>        Dev server port (default: ${this.wf.defaults?.devPort || 5173})
+  --review-port <N>     Review server port (default: ${this.wf.defaults?.reviewPort || 3456})
+  --timeout <sec>       Claude timeout per phase in seconds (default: 600)
+  --skip-measure        Skip automated measurement (human-review only)
+  --help                Show this help
+
+${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
+`);
+  }
+
+  // ─── Claude ──────────────────────────────────────────────────────────
+
+  verifyClaude() {
+    try {
+      execFileSync("claude", ["--version"], {
+        encoding: "utf8", timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      return true;
+    } catch {
+      error("claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code");
+      return false;
+    }
+  }
+
+  spawnClaude(projectDir, prompt, timeout) {
+    const start = Date.now();
+    let output = "";
+    let exitCode = 0;
+
+    try {
+      output = execFileSync("claude", ["-p", prompt], {
+        encoding: "utf8",
+        timeout: timeout || this.wf.defaults?.timeout || 600_000,
+        stdio: ["pipe", "pipe", "pipe"],
+        cwd: projectDir,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    } catch (e) {
+      output = (e.stdout || "") + (e.stderr || "");
+      exitCode = e.status || 1;
+      if (e.killed) warn(`Claude timed out after ${(timeout || 600_000) / 1000}s`);
+    }
+
+    const duration = Math.round((Date.now() - start) / 1000);
+    return { output, exitCode, duration };
+  }
+
+  // ─── Server Management ───────────────────────────────────────────────
+
+  startDevServer(projectDir, port) {
+    if (isPortInUse(port)) {
+      success(`Dev server already running on port ${port}`);
+      return { pid: null, port, alreadyRunning: true };
+    }
+
+    const pkgPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+      error("No package.json found — cannot start dev server");
+      process.exit(1);
+    }
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    if (!pkg.scripts?.dev) {
+      error("No 'dev' script in package.json — cannot start dev server");
+      process.exit(1);
+    }
+
+    info("Starting dev server: npm run dev");
+    const child = cpSpawn("npm", ["run", "dev"], {
+      cwd: projectDir,
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, PORT: String(port) },
+    });
+    child.unref();
+
+    const start = Date.now();
+    const timeout = this.wf.defaults?.devServerTimeout || 30_000;
+    while (Date.now() - start < timeout) {
+      if (isPortInUse(port)) {
+        success(`Dev server ready on port ${port} (PID: ${child.pid})`);
+        return { pid: child.pid, port, alreadyRunning: false };
+      }
+      syncSleep(1000);
+    }
+
+    error(`Dev server failed to start within ${timeout / 1000}s`);
+    process.exit(1);
+  }
+
+  startReviewServer(projectDir, devPort, reviewPort) {
+    if (isPortInUse(reviewPort)) {
+      success(`Review server already running on port ${reviewPort}`);
+      return { pid: null, port: reviewPort, alreadyRunning: true };
+    }
+
+    const pkgRoot = path.resolve(__dirname, "..");
+    const reviewScript = path.join(pkgRoot, "scripts", "gsd-t-design-review-server.js");
+    if (!fs.existsSync(reviewScript)) {
+      error(`Review server script not found: ${reviewScript}`);
+      process.exit(1);
+    }
+
+    info(`Starting review server on port ${reviewPort}`);
+    const child = cpSpawn("node", [
+      reviewScript,
+      "--port", String(reviewPort),
+      "--target", `http://localhost:${devPort}`,
+      "--project", projectDir,
+    ], {
+      cwd: projectDir,
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+
+    const start = Date.now();
+    while (Date.now() - start < 10_000) {
+      if (isPortInUse(reviewPort)) {
+        success(`Review server ready on port ${reviewPort} (PID: ${child.pid})`);
+        return { pid: child.pid, port: reviewPort, alreadyRunning: false };
+      }
+      syncSleep(1000);
+    }
+
+    error("Review server failed to start within 10s");
+    process.exit(1);
+  }
+
+  // ─── Review Queue ────────────────────────────────────────────────────
+
+  getReviewDir(projectDir) {
+    return path.join(projectDir, this.wf.reviewDir || ".gsd-t/design-review");
+  }
+
+  writeQueueItem(projectDir, item) {
+    const queueDir = path.join(this.getReviewDir(projectDir), "queue");
+    ensureDir(queueDir);
+    fs.writeFileSync(path.join(queueDir, `${item.id}.json`), JSON.stringify(item, null, 2));
+  }
+
+  clearQueue(projectDir) {
+    const reviewDir = this.getReviewDir(projectDir);
+    for (const sub of ["queue", "feedback", "rejected"]) {
+      const dir = path.join(reviewDir, sub);
+      if (fs.existsSync(dir)) {
+        for (const f of fs.readdirSync(dir)) {
+          try { fs.unlinkSync(path.join(dir, f)); } catch { /* ignore */ }
+        }
+      }
+    }
+    // Remove review-complete signal
+    try { fs.unlinkSync(path.join(reviewDir, "review-complete.json")); } catch { /* ignore */ }
+  }
+
+  updateStatus(projectDir, phase, state) {
+    const statusPath = path.join(this.getReviewDir(projectDir), "status.json");
+    fs.writeFileSync(statusPath, JSON.stringify({
+      phase,
+      state,
+      startedAt: new Date().toISOString(),
+    }, null, 2));
+  }
+
+  queuePhaseItems(projectDir, phase, items, measurements) {
+    this.clearQueue(projectDir);
+    let order = 1;
+
+    for (const item of items) {
+      const queueItem = this.wf.buildQueueItem
+        ? this.wf.buildQueueItem(phase, item, measurements)
+        : this._defaultQueueItem(phase, item, measurements, order);
+      queueItem.order = order++;
+      this.writeQueueItem(projectDir, queueItem);
+    }
+
+    this.updateStatus(projectDir, phase, "review");
+    return order - 1;
+  }
+
+  _defaultQueueItem(phase, item, measurements, order) {
+    return {
+      id: `${phase}-${item.id}`,
+      name: item.name || item.id,
+      type: phase,
+      order,
+      selector: item.selector || `.${item.id}`,
+      sourcePath: item.sourcePath || "",
+      route: item.route || "/",
+      measurements: (measurements && measurements[item.id]) || [],
+    };
+  }
+
+  // ─── Review Gate ─────────────────────────────────────────────────────
+
+  waitForReview(projectDir, phase, queueCount, reviewPort) {
+    const signalPath = path.join(this.getReviewDir(projectDir), "review-complete.json");
+
+    heading(`⏸  Waiting for human review of ${phase}`);
+    log(`  ${queueCount} items queued for review`);
+    log(`  ${BOLD}Review UI:${RESET} http://localhost:${reviewPort}/review`);
+    log(`  ${DIM}Submit your review in the browser to continue...${RESET}`);
+    log("");
+
+    openBrowser(`http://localhost:${reviewPort}/review`);
+
+    // IRONCLAD GATE — JavaScript polling loop
+    while (true) {
+      if (fs.existsSync(signalPath)) {
+        try {
+          const data = JSON.parse(fs.readFileSync(signalPath, "utf8"));
+          success("Review submitted!");
+          return data;
+        } catch { /* malformed — wait for rewrite */ }
+      }
+      syncSleep(3000);
+    }
+  }
+
+  // ─── Feedback ────────────────────────────────────────────────────────
+
+  defaultProcessFeedback(projectDir, phase, items) {
+    const fbDir = path.join(this.getReviewDir(projectDir), "feedback");
+    const approved = [];
+    const needsWork = [];
+
+    if (!fs.existsSync(fbDir)) {
+      return { approved: items.map(c => c.id), needsWork: [] };
+    }
+
+    const fbFiles = fs.readdirSync(fbDir).filter(f => f.endsWith(".json"));
+
+    for (const f of fbFiles) {
+      try {
+        const fb = JSON.parse(fs.readFileSync(path.join(fbDir, f), "utf8"));
+        if (fb.verdict === "approved" || (!fb.changes?.length && !fb.comment)) {
+          approved.push(fb.id);
+        } else {
+          needsWork.push(fb);
+        }
+      } catch { /* skip malformed */ }
+    }
+
+    // Items without feedback are approved by default
+    const fbIds = new Set([...approved, ...needsWork.map(w => w.id)]);
+    for (const item of items) {
+      const queueId = `${phase}-${item.id}`;
+      if (!fbIds.has(queueId) && !fbIds.has(item.id)) {
+        approved.push(item.id);
+      }
+    }
+
+    if (needsWork.length > 0) {
+      warn(`${needsWork.length} items need changes`);
+      for (const item of needsWork) {
+        dim(`${item.id}: ${item.comment || "property changes requested"}`);
+      }
+    }
+
+    return { approved, needsWork };
+  }
+
+  // ─── State Persistence ───────────────────────────────────────────────
+
+  getStatePath(projectDir) {
+    const stateFile = this.wf.stateFile || ".gsd-t/design-review/orchestrator-state.json";
+    return path.join(projectDir, stateFile);
+  }
+
+  saveState(projectDir, state) {
+    const statePath = this.getStatePath(projectDir);
+    ensureDir(path.dirname(statePath));
+    state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+  }
+
+  loadState(projectDir) {
+    const statePath = this.getStatePath(projectDir);
+    if (!fs.existsSync(statePath)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(statePath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  // ─── Cleanup ─────────────────────────────────────────────────────────
+
+  cleanup(projectDir) {
+    const shutdownPath = path.join(this.getReviewDir(projectDir), "shutdown.json");
+    try {
+      fs.writeFileSync(shutdownPath, JSON.stringify({ shutdown: true, at: new Date().toISOString() }));
+    } catch { /* ignore */ }
+
+    for (const pid of this.pids) {
+      if (pid) {
+        try { process.kill(pid); } catch { /* already dead */ }
+        try { process.kill(-pid); } catch { /* ignore */ }
+      }
+    }
+    dim("Servers stopped");
+  }
+
+  // ─── Main Pipeline ──────────────────────────────────────────────────
+
+  run(argv) {
+    const opts = this.wf.parseArgs
+      ? this.wf.parseArgs(argv, this.parseBaseArgs.bind(this))
+      : this.parseBaseArgs(argv || []);
+
+    const { projectDir, resume, startPhase, devPort, reviewPort, skipMeasure } = opts;
+    const phases = this.wf.phases;
+    const maxReviewCycles = this.wf.defaults?.maxReviewCycles || 3;
+
+    heading(`GSD-T ${this.wf.name} Orchestrator`);
+    log(`  Project: ${projectDir}`);
+    log(`  Ports:   dev=${devPort} review=${reviewPort}`);
+    log(`  Phases:  ${phases.join(" → ")}`);
+    log("");
+
+    // 1. Verify prerequisites
+    if (!this.verifyClaude()) process.exit(1);
+    if (this.wf.validate) this.wf.validate(projectDir);
+
+    // 2. Discover work items
+    info("Discovering work...");
+    const work = this.wf.discoverWork(projectDir);
+    const counts = phases.map(p => `${p}: ${(work[p] || []).length}`).join(", ");
+    success(`Found: ${counts}`);
+
+    // 3. Load/create state
+    let state;
+    if (resume) {
+      state = this.loadState(projectDir);
+      if (state) {
+        info(`Resuming from: ${state.currentPhase || "start"} (completed: ${state.completedPhases.join(", ") || "none"})`);
+      } else {
+        warn("No saved state found — starting fresh");
+        state = this._createState();
+      }
+    } else {
+      state = this._createState();
+    }
+
+    // 4. Start servers
+    heading("Starting Infrastructure");
+    if (this.wf.startServers) {
+      const serverInfo = this.wf.startServers(projectDir, opts, this);
+      this.pids = serverInfo.pids || [];
+    } else {
+      const devInfo = this.startDevServer(projectDir, devPort);
+      const reviewInfo = this.startReviewServer(projectDir, devPort, reviewPort);
+      this.pids = [devInfo.pid, reviewInfo.pid].filter(Boolean);
+    }
+
+    // Register cleanup on exit
+    process.on("SIGINT", () => { this.cleanup(projectDir); process.exit(0); });
+    process.on("SIGTERM", () => { this.cleanup(projectDir); process.exit(0); });
+
+    // 5. Determine starting phase
+    let startIdx = 0;
+    if (startPhase) {
+      startIdx = phases.indexOf(startPhase);
+      if (startIdx < 0) {
+        error(`Unknown phase: ${startPhase}. Use: ${phases.join(", ")}`);
+        this.cleanup(projectDir);
+        process.exit(1);
+      }
+    } else if (state.completedPhases.length > 0) {
+      const lastCompleted = state.completedPhases[state.completedPhases.length - 1];
+      startIdx = phases.indexOf(lastCompleted) + 1;
+    }
+
+    // 6. Phase loop — THE MAIN PIPELINE
+    for (let i = startIdx; i < phases.length; i++) {
+      const phase = phases[i];
+      const items = work[phase] || [];
+
+      if (items.length === 0) {
+        info(`No ${phase} items — skipping`);
+        state.completedPhases.push(phase);
+        continue;
+      }
+
+      heading(`Phase ${i + 1}/${phases.length}: ${phase} (${items.length} items)`);
+
+      state.currentPhase = phase;
+      this.saveState(projectDir, state);
+
+      // 6a. Collect results from previous phases
+      const prevResults = {};
+      for (let j = 0; j < i; j++) {
+        const prevPhase = phases[j];
+        if (state.phaseResults[prevPhase]) {
+          prevResults[prevPhase] = state.phaseResults[prevPhase];
+        }
+      }
+
+      // 6b. Spawn Claude for this phase
+      const prompt = this.wf.buildPrompt(phase, items, prevResults, projectDir);
+      log(`\n${CYAN}  ⚙${RESET} Spawning Claude to build ${items.length} ${phase}...`);
+      dim(`Timeout: ${(opts.timeout || 600_000) / 1000}s`);
+
+      const buildResult = this.spawnClaude(projectDir, prompt, opts.timeout);
+      if (buildResult.exitCode === 0) {
+        success(`Claude finished building ${phase} in ${buildResult.duration}s`);
+      } else {
+        warn(`Claude exited with code ${buildResult.exitCode} after ${buildResult.duration}s`);
+      }
+
+      // 6c. Collect built paths
+      const builtPaths = items.map(item =>
+        item.sourcePath || (this.wf.guessPaths ? this.wf.guessPaths(phase, item) : "")
+      );
+
+      // 6d. Measure
+      let measurements = {};
+      if (!skipMeasure && this.wf.measure) {
+        measurements = this.wf.measure(projectDir, phase, items, { devPort, reviewPort }) || {};
+      }
+
+      // 6e. Review cycle
+      let reviewCycle = 0;
+      let allApproved = false;
+
+      while (reviewCycle < maxReviewCycles && !allApproved) {
+        const queueCount = this.queuePhaseItems(projectDir, phase, items, measurements);
+        this.waitForReview(projectDir, phase, queueCount, reviewPort);
+
+        const feedback = this.wf.processFeedback
+          ? this.wf.processFeedback(projectDir, phase, items)
+          : this.defaultProcessFeedback(projectDir, phase, items);
+
+        if (feedback.needsWork.length === 0) {
+          allApproved = true;
+          success(`All ${phase} approved!`);
+        } else {
+          reviewCycle++;
+          if (reviewCycle < maxReviewCycles) {
+            info(`Review cycle ${reviewCycle + 1}/${maxReviewCycles} — applying fixes...`);
+            const fixPrompt = this.wf.buildFixPrompt
+              ? this.wf.buildFixPrompt(phase, feedback.needsWork)
+              : this._defaultFixPrompt(phase, feedback.needsWork);
+            info(`Spawning Claude to apply ${feedback.needsWork.length} fixes...`);
+            const fixResult = this.spawnClaude(projectDir, fixPrompt, 120_000);
+            if (fixResult.exitCode === 0) success("Fixes applied");
+            else warn(`Fix attempt returned code ${fixResult.exitCode}`);
+          } else {
+            warn(`Max review cycles reached for ${phase} — proceeding with remaining issues`);
+            allApproved = true;
+          }
+        }
+      }
+
+      // 6f. Record phase completion
+      state.phaseResults[phase] = {
+        completed: true,
+        builtPaths,
+        reviewCycles: reviewCycle + 1,
+        completedAt: new Date().toISOString(),
+      };
+      state.completedPhases.push(phase);
+      this.clearQueue(projectDir);
+      this.saveState(projectDir, state);
+
+      success(`${phase} phase complete`);
+    }
+
+    // 7. Cleanup & report
+    heading(`${this.wf.name} Complete`);
+
+    for (const phase of phases) {
+      const result = state.phaseResults[phase];
+      if (result?.completed) {
+        const summary = this.wf.formatSummary
+          ? this.wf.formatSummary(phase, result)
+          : `${phase}: ${result.builtPaths.length} items built (${result.reviewCycles} review cycle${result.reviewCycles > 1 ? "s" : ""})`;
+        success(summary);
+      }
+    }
+
+    log("");
+    this.cleanup(projectDir);
+
+    // Remove state file on success
+    try { fs.unlinkSync(this.getStatePath(projectDir)); } catch { /* ignore */ }
+
+    success(this.wf.completionMessage || "All done. Run your app to verify: npm run dev");
+  }
+
+  _createState() {
+    return {
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString(),
+      currentPhase: null,
+      completedPhases: [],
+      phaseResults: {},
+    };
+  }
+
+  _defaultFixPrompt(phase, needsWork) {
+    const fixes = needsWork.map(item => {
+      const parts = [`Fix ${item.id}:`];
+      if (item.changes?.length) {
+        for (const c of item.changes) {
+          parts.push(`  - ${c.property}: change from ${c.oldValue} to ${c.newValue} in ${c.path || "the component file"}`);
+        }
+      }
+      if (item.comment) parts.push(`  - Additional: ${item.comment}`);
+      return parts.join("\n");
+    }).join("\n\n");
+
+    return `Apply these specific fixes to ${phase} components:\n\n${fixes}\n\nApply the changes and EXIT. Do not rebuild anything else.`;
+  }
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  Orchestrator,
+  // Export helpers for workflow definitions to use
+  log, heading, success, warn, error, info, dim,
+  ensureDir, syncSleep, openBrowser, isPortInUse,
+  BOLD, GREEN, YELLOW, RED, CYAN, DIM, RESET,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.71.13",
+  "version": "2.71.14",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 56 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",