@tekyzinc/gsd-t 2.72.10 → 2.73.11

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.73.11] - 2026-04-08
+
+### Changed (reviewer — Playwright-first visual inspection)
+- **Playwright is now the PRIMARY reviewer method** — every contract-specified visual property is verified via `getComputedStyle()` in a real browser. Code review demoted to supplement for non-visual concerns (props, events, accessibility). CSS box math (cascade, specificity, flex/grid computation, relative units) can only be verified at render time, not from source code.
+
+## [2.73.10] - 2026-04-08
+
+### Added (orchestrator — parallel execution)
+- **`--parallel N` flag** — runs N build+review items concurrently via async `spawnClaudeAsync()` and `_runWithConcurrency()`. Default: 1 (sequential). Recommended: 3. Reduces 15-element pipeline from ~30min to ~10min at 3x parallelism.
+- **`--clean` artifact cleanup expanded** — now clears `auto-review/`, `build-logs/`, `queue/`, `feedback/`, `review-complete.json`, `orchestrator-state.json` on fresh start (not just build output).
+
+### Changed
+- **Orchestrator `run()` is now async** — callers (`bin/gsd-t.js`, `bin/design-orchestrator.js`) updated with `.catch()` for proper error handling.
+
 ## [2.72.10] - 2026-04-08
 
 ### Added (orchestrator — per-item pipeline, stream-json, verbose, clean)

package/bin/design-orchestrator.js

@@ -365,25 +365,39 @@ ${componentList}
 ${measurementContext}
 ## Review Process
 
-**Step 1 — Code review (do this FIRST for ALL components):**
-For each component, read the design contract file and the source file. Check that every contract-specified value (colors, sizes, spacing, border-radius, font, layout, chart type, etc.) is correctly implemented in the code. This is your primary review — most issues are catchable from code alone.
-
-**Step 2 — Playwright spot-check (do this AFTER code review):**
-Use Playwright to render components at http://localhost:${ports.reviewPort}/ and verify:
-- Components render without errors and have correct dimensions
-- Chart types, orientations, and data structures are correct
-- Interactive elements respond correctly (hover, click, states)
-
-Focus Playwright on components where code review raised concerns or where visual behavior can't be verified from code alone (e.g., SVG rendering, computed layouts). You do NOT need to re-measure every CSS property — the orchestrator already ran Playwright measurements above.
+**Step 1 — Playwright visual inspection (PRIMARY — do this FIRST):**
+Every UI component is visual and MUST be visually inspected. For each component:
+1. Open http://localhost:${ports.reviewPort}/ in Playwright
+2. Navigate to / render the component using its selector
+3. For EVERY contract-specified visual property, use \`page.locator(selector).evaluate(el => getComputedStyle(el))\` to measure the actual computed value:
+   - **Box model**: width, height, padding, margin, gap, border-width, border-radius
+   - **Colors**: background-color, color, border-color (compare computed rgb/rgba values)
+   - **Typography**: font-family, font-size, font-weight, line-height, letter-spacing
+   - **Layout**: display, flex-direction, justify-content, align-items, grid-template-columns
+   - **Spacing**: gap, row-gap, column-gap, padding (all sides), margin (all sides)
+   - **Visual**: opacity, box-shadow, overflow, text-overflow
+4. Compare each measured value against the contract specification
+5. Check that the component renders without console errors
+6. For charts/SVGs: verify chart type, orientation, data structure, and proportions visually
+
+Code review alone CANNOT verify CSS box math — cascade, specificity, flex/grid computation, relative units, and parent constraints all affect the final rendered result. Only computed styles from a running browser are authoritative.
+
+**Step 2 — Code review (supplement for non-visual concerns):**
+Read the source file to check:
+- Prop interfaces match contract definitions
+- Event handlers and interactivity are wired correctly
+- Data binding and state management are correct
+- Accessibility attributes (aria-*, role) are present
+- Component structure matches contract hierarchy
 
 ## Output Format
 
-Output your findings between these markers. Each issue must have component, severity (critical/high/medium/low), and description with SPECIFIC contract vs. actual values:
+Output your findings between these markers. Each issue must have component, severity (critical/high/medium/low), and description with SPECIFIC contract value vs. actual computed value:
 
 [REVIEW_ISSUES]
 [
   {"component": "ComponentName", "severity": "critical", "description": "Contract specifies donut chart but rendered as pie chart (no inner radius)"},
-  {"component": "ComponentName", "severity": "high", "description": "Grid gap: contract 16px, actual 24px"}
+  {"component": "ComponentName", "severity": "high", "description": "Grid gap: contract 16px, computed 24px"}
 ]
 [/REVIEW_ISSUES]
 
@@ -395,9 +409,10 @@ If ALL components match their contracts, output:
 ## CRITICAL — Output Rules
 - Output MUST contain the [REVIEW_ISSUES] markers — the orchestrator parses your result from these markers. Without them, your review is lost.
 - You write ZERO code. You ONLY review.
+- You MUST run Playwright for every component. Skipping visual inspection is a review failure.
 - Be HARSH. Your value is in catching what the builder missed.
-- NEVER say "looks close" or "appears to match" — give SPECIFIC values.
-- Every contract property must be verified. Missing verification = missed issue.
+- NEVER say "looks close" or "appears to match" — give SPECIFIC computed values.
+- Every contract property must be verified via computed style. Missing verification = missed issue.
 - Severity guide: critical = wrong component type, missing element, broken render. high = wrong dimensions, colors, layout. medium = spacing/padding off. low = minor visual difference.`;
 }
 
@@ -421,15 +436,30 @@ function buildSingleItemReviewPrompt(phase, item, measurements, projectDir, port
 ${measurementContext}
 ## Review Process
 
-1. Read the design contract file — note every specified property value
-2. Read the source file — check that every contract-specified value is implemented correctly
-3. If needed, use Playwright to render at http://localhost:${ports.reviewPort}/ and verify visual behavior
+**Step 1 — Playwright visual inspection (PRIMARY):**
+This is a UI component — visual inspection is mandatory, not optional.
+1. Read the design contract file — note every specified visual property value
+2. Open http://localhost:${ports.reviewPort}/ in Playwright
+3. Render the component using its selector
+4. For EVERY contract-specified visual property, measure the actual computed value:
+   \`page.locator(selector).evaluate(el => getComputedStyle(el))\`
+   - Box model: width, height, padding, margin, gap, border-width, border-radius
+   - Colors: background-color, color, border-color (compare computed rgb/rgba)
+   - Typography: font-family, font-size, font-weight, line-height
+   - Layout: display, flex-direction, justify-content, align-items
+5. Compare each computed value against the contract specification
+6. For charts/SVGs: verify type, orientation, proportions visually
+
+Code review alone cannot verify CSS — cascade, specificity, flex/grid, and relative units all affect computed output.
+
+**Step 2 — Code review (non-visual concerns):**
+Read the source file to check prop interfaces, event handlers, data binding, and accessibility attributes.
 
 ## Output Format
 
 [REVIEW_ISSUES]
 [
-  {"component": "${item.componentName}", "severity": "high", "description": "Contract specifies X, code has Y"}
+  {"component": "${item.componentName}", "severity": "high", "description": "Contract specifies X, computed value is Y"}
 ]
 [/REVIEW_ISSUES]
 
@@ -439,8 +469,9 @@ If the component matches its contract, output:
 [/REVIEW_ISSUES]
 
 ## Rules
+- You MUST run Playwright. Skipping visual inspection is a review failure.
 - You write ZERO code. You ONLY review.
-- Be HARSH — specific values only, no "looks close."
+- Be HARSH — specific computed values only, no "looks close."
 - Output MUST contain [REVIEW_ISSUES] markers.`;
 }
 
@@ -485,6 +516,9 @@ ${BOLD}Options:${RESET}
   --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)
+  --clean           Clear all stale artifacts before starting
+  --verbose, -v     Show Claude's tool calls and prompts in terminal
+  --parallel <N>    Run N items concurrently (default: 1 = sequential)
   --help            Show this help
 
 ${BOLD}Pipeline:${RESET}
@@ -542,12 +576,12 @@ const designBuildWorkflow = {
 
 // ─── Entry Point ────────────────────────────────────────────────────────────
 
-function run(args) {
-  new Orchestrator(designBuildWorkflow).run(args || []);
+async function run(args) {
+  await new Orchestrator(designBuildWorkflow).run(args || []);
 }
 
 if (require.main === module) {
-  run(process.argv.slice(2));
+  run(process.argv.slice(2)).catch(e => { console.error(e); process.exit(1); });
 }
 
 module.exports = { run, workflow: designBuildWorkflow };

package/bin/gsd-t.js

@@ -2699,7 +2699,7 @@ if (require.main === module) {
       break;
     case "design-build": {
       const orchestrator = require("./design-orchestrator.js");
-      orchestrator.run(args.slice(1));
+      orchestrator.run(args.slice(1)).catch(e => { console.error(e); process.exit(1); });
       break;
     }
     case "scan": {

package/bin/orchestrator.js

@@ -25,7 +25,7 @@
 
 const fs = require("fs");
 const path = require("path");
-const { execFileSync, spawn: cpSpawn } = require("child_process");
+const { execFileSync, execFile, spawn: cpSpawn } = require("child_process");
 
 // ─── ANSI Colors ────────────────────────────────────────────────────────────
 
@@ -136,6 +136,7 @@ class Orchestrator {
         case "--skip-measure": opts.skipMeasure = true; break;
         case "--clean": opts.clean = true; break;
         case "--verbose": case "-v": opts.verbose = true; break;
+        case "--parallel": opts.parallel = parseInt(argv[++i], 10) || 3; break;
         case "--help":
         case "-h":
           if (this.wf.showUsage) this.wf.showUsage();
@@ -162,7 +163,8 @@ ${BOLD}Options:${RESET}
   --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)
-  --clean               Delete previous build output before building each phase
+  --clean               Clear all artifacts from previous runs + delete build output
+  --parallel <N>        Run N items concurrently (default: 1, recommended: 3)
   --verbose, -v         Show Claude's tool calls and prompts in terminal
   --help                Show this help
 
@@ -237,6 +239,71 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
 
   // ─── Server Management ───────────────────────────────────────────────
 
+  /**
+   * Async Claude spawn — returns a Promise. Used for parallel execution.
+   */
+  spawnClaudeAsync(projectDir, prompt, timeout, opts = {}) {
+    const start = Date.now();
+    const verbose = this._verbose;
+
+    const args = ["-p", "--dangerously-skip-permissions", "--output-format", "stream-json"];
+    if (verbose) args.push("--verbose");
+    args.push(prompt);
+
+    if (verbose && opts.label) {
+      const logDir = path.join(this.getReviewDir(projectDir), "build-logs");
+      ensureDir(logDir);
+      fs.writeFileSync(
+        path.join(logDir, `${opts.label}-prompt.txt`),
+        `--- Prompt (${new Date().toISOString()}) ---\nTimeout: ${(timeout || 120_000) / 1000}s\nCWD: ${projectDir}\n\n${prompt}`
+      );
+    }
+
+    return new Promise((resolve) => {
+      const child = execFile("claude", args, {
+        encoding: "utf8",
+        timeout: timeout || 120_000,
+        cwd: projectDir,
+        maxBuffer: 10 * 1024 * 1024,
+      }, (err, stdout, stderr) => {
+        const raw = err ? ((err.stdout || "") + (err.stderr || "")) : (stdout || "");
+        const output = this._parseStreamJson(raw, false);
+        const exitCode = err ? (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ? 1 : (err.killed ? 143 : (err.code || 1))) : 0;
+        const duration = Math.round((Date.now() - start) / 1000);
+
+        if (verbose) {
+          dim(`  ${opts.label || "claude"}: exit=${exitCode}, ${duration}s, ${output.length} chars`);
+        }
+
+        resolve({ output, exitCode, duration });
+      });
+    });
+  }
+
+  /**
+   * Run tasks with concurrency limit. Returns results in same order as tasks.
+   * @param {Array<Function>} taskFns — array of () => Promise<result>
+   * @param {number} concurrency — max concurrent tasks
+   */
+  async _runWithConcurrency(taskFns, concurrency) {
+    const results = new Array(taskFns.length).fill(null);
+    let nextIdx = 0;
+
+    async function runNext() {
+      while (nextIdx < taskFns.length) {
+        const idx = nextIdx++;
+        results[idx] = await taskFns[idx]();
+      }
+    }
+
+    const workers = [];
+    for (let i = 0; i < Math.min(concurrency, taskFns.length); i++) {
+      workers.push(runNext());
+    }
+    await Promise.all(workers);
+    return results;
+  }
+
   _parseStreamJson(raw, verbose) {
     // stream-json format: one JSON object per line
     // We want assistant text content and tool use visibility
@@ -554,7 +621,7 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
 
   // ─── Main Pipeline ──────────────────────────────────────────────────
 
-  run(argv) {
+  async run(argv) {
     const opts = this.wf.parseArgs
       ? this.wf.parseArgs(argv, this.parseBaseArgs.bind(this))
       : this.parseBaseArgs(argv || []);
@@ -597,6 +664,29 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
       }
     } else {
       state = this._createState();
+
+      // Clean all orchestrator artifacts on fresh start (not --resume)
+      if (opts.clean) {
+        const reviewDir = this.getReviewDir(projectDir);
+        const dirsToClean = ["auto-review", "build-logs", "queue", "feedback"];
+        let cleaned = 0;
+        for (const dir of dirsToClean) {
+          const full = path.join(reviewDir, dir);
+          if (fs.existsSync(full)) {
+            for (const f of fs.readdirSync(full)) {
+              try { fs.unlinkSync(path.join(full, f)); cleaned++; } catch { /* ignore */ }
+            }
+          }
+        }
+        // Remove signal and state files
+        for (const f of ["review-complete.json", "orchestrator-state.json", "shutdown.json"]) {
+          const full = path.join(reviewDir, f);
+          if (fs.existsSync(full)) {
+            try { fs.unlinkSync(full); cleaned++; } catch { /* ignore */ }
+          }
+        }
+        if (cleaned > 0) info(`--clean: removed ${cleaned} stale artifact(s)`);
+      }
     }
 
     // 4. Start servers
@@ -691,24 +781,30 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
       let measurements = {};
 
       // ── Per-item pipeline: build ONE → review ONE → fix if needed ──
-      // Preferred when workflow provides single-item prompts.
-      // Each Claude spawn reads 1 contract + 1 source = tiny context, fast completion.
+      // Each item is independent: 1 contract + 1 source = tiny context.
+      // With --parallel N, runs N items concurrently.
       if (this.wf.buildSingleItemPrompt && this.wf.buildSingleItemReviewPrompt) {
-        log(`\n${CYAN}  ⚙${RESET} Building and reviewing ${items.length} ${phase} one at a time...`);
+        const concurrency = opts.parallel || 1;
+        if (concurrency > 1) {
+          log(`\n${CYAN}  ⚙${RESET} Building and reviewing ${items.length} ${phase} (${concurrency} parallel)...`);
+        } else {
+          log(`\n${CYAN}  ⚙${RESET} Building and reviewing ${items.length} ${phase} one at a time...`);
+        }
 
-        for (let idx = 0; idx < items.length; idx++) {
-          const item = items[idx];
-          heading(`  [${idx + 1}/${items.length}] ${item.componentName}`);
+        // Each task: build → review → fix loop for one item
+        const processItem = async (item, idx) => {
+          const label = `[${idx + 1}/${items.length}] ${item.componentName}`;
+          log(`\n  ${BOLD}${label}${RESET}`);
 
-          // Build one item
+          // Build
           const buildPrompt = this.wf.buildSingleItemPrompt(phase, item, prevResults, projectDir);
           dim(`  Building...`);
-          const buildResult = this.spawnClaude(projectDir, buildPrompt, perItemTimeout, { label: `${phase}-build-${item.id}` });
+          const buildResult = await this.spawnClaudeAsync(projectDir, buildPrompt, perItemTimeout, { label: `${phase}-build-${item.id}` });
 
           if (buildResult.exitCode === 0) {
-            success(`  Built (${buildResult.duration}s)`);
+            success(`  ${item.componentName}: built (${buildResult.duration}s)`);
           } else {
-            warn(`  Build exited with code ${buildResult.exitCode} (${buildResult.duration}s)`);
+            warn(`  ${item.componentName}: build exit ${buildResult.exitCode} (${buildResult.duration}s)`);
           }
 
           fs.writeFileSync(
@@ -716,12 +812,12 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
             `Exit code: ${buildResult.exitCode}\nDuration: ${buildResult.duration}s\n\n--- OUTPUT ---\n${buildResult.output.slice(0, 5000)}`
           );
 
-          // Review one item (up to maxAutoReviewCycles)
+          // Review cycles
           let itemClean = false;
           for (let cycle = 1; cycle <= maxAutoReviewCycles && !itemClean; cycle++) {
-            dim(`  Review cycle ${cycle}/${maxAutoReviewCycles}...`);
+            dim(`  ${item.componentName}: review c${cycle}...`);
             const reviewPrompt = this.wf.buildSingleItemReviewPrompt(phase, item, {}, projectDir, { devPort, reviewPort });
-            const reviewResult = this.spawnClaude(projectDir, reviewPrompt, perItemTimeout, { label: `${phase}-review-${item.id}-c${cycle}` });
+            const reviewResult = await this.spawnClaudeAsync(projectDir, reviewPrompt, perItemTimeout, { label: `${phase}-review-${item.id}-c${cycle}` });
 
             const isCrash = reviewResult.exitCode !== 0 && reviewResult.duration < 10;
             const isKilled = [143, 137].includes(reviewResult.exitCode);
@@ -730,7 +826,7 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
             let itemIssues = [];
             if (isCrash || isKilled || isEmptyFail) {
               const reason = isCrash ? "crashed" : isKilled ? "killed/timed out" : "failed with no output";
-              warn(`  Reviewer ${reason} (${reviewResult.duration}s)`);
+              warn(`  ${item.componentName}: reviewer ${reason} (${reviewResult.duration}s)`);
               itemIssues = [{ component: item.componentName, severity: "critical", description: `Reviewer ${reason}` }];
             } else {
               itemIssues = this.wf.parseReviewResult
@@ -740,28 +836,34 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
 
             if (itemIssues.length === 0) {
               itemClean = true;
-              success(`  Clean (${reviewResult.duration}s)`);
+              success(`  ${item.componentName}: clean (${reviewResult.duration}s)`);
             } else {
-              warn(`  ${itemIssues.length} issue(s) found`);
+              warn(`  ${item.componentName}: ${itemIssues.length} issue(s)`);
               for (const issue of itemIssues) {
-                dim(`    ${issue.description || issue.reason || "issue"} [${issue.severity || "medium"}]`);
+                dim(`    ${issue.description || "issue"} [${issue.severity || "medium"}]`);
               }
 
               if (cycle < maxAutoReviewCycles) {
-                // Fix this one item
                 const fixPrompt = this.wf.buildAutoFixPrompt
                   ? this.wf.buildAutoFixPrompt(phase, itemIssues, [item], projectDir)
                   : this._defaultAutoFixPrompt(phase, itemIssues);
-                dim(`  Fixing...`);
-                const fixResult = this.spawnClaude(projectDir, fixPrompt, perItemTimeout, { label: `${phase}-fix-${item.id}-c${cycle}` });
-                if (fixResult.exitCode === 0) success(`  Fixed (${fixResult.duration}s)`);
-                else warn(`  Fix exited with code ${fixResult.exitCode}`);
+                dim(`  ${item.componentName}: fixing...`);
+                const fixResult = await this.spawnClaudeAsync(projectDir, fixPrompt, perItemTimeout, { label: `${phase}-fix-${item.id}-c${cycle}` });
+                if (fixResult.exitCode === 0) success(`  ${item.componentName}: fixed (${fixResult.duration}s)`);
+                else warn(`  ${item.componentName}: fix exit ${fixResult.exitCode}`);
               }
             }
           }
 
-          builtPaths.push(item.sourcePath || (this.wf.guessPaths ? this.wf.guessPaths(phase, item) : ""));
-        }
+          return item.sourcePath || (this.wf.guessPaths ? this.wf.guessPaths(phase, item) : "");
+        };
+
+        // Run with concurrency
+        const taskFns = items.map((item, idx) => () => processItem(item, idx));
+        const startTime = Date.now();
+        builtPaths = await this._runWithConcurrency(taskFns, concurrency);
+        const totalSec = Math.round((Date.now() - startTime) / 1000);
+        success(`All ${items.length} ${phase} processed in ${totalSec}s (${concurrency}x parallel)`);
 
         // Measure ALL at once (one Playwright run after all items built)
         if (!skipMeasure && this.wf.measure) {

package/commands/gsd-t-design-build.md

@@ -33,7 +33,8 @@ Pass any of these as `$ARGUMENTS`:
 | `--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) |
-| `--clean`           | Delete previous build output before building each phase |
+| `--clean`           | Clear all stale artifacts + delete build output before each phase |
+| `--parallel <N>`    | Run N items concurrently (default: 1, recommended: 3) |
 | `--verbose`, `-v`   | Show Claude's tool calls and prompts in terminal |
 
 ## Prerequisites

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.72.10",
+  "version": "2.73.11",
   "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",