@tekyzinc/gsd-t 2.71.21 → 2.73.10

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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)
+- **Per-item build+review pipeline** — when workflow provides `buildSingleItemPrompt` + `buildSingleItemReviewPrompt`, each component is built and reviewed individually (1 contract + 1 source per Claude spawn) instead of all-at-once. Fixes reviewer timeout caused by 30+ files in a single context. Each item gets up to 4 auto-review fix cycles independently.
+- **`--output-format stream-json`** — Claude spawns now use streaming JSON output. On timeout, partial output is captured and parsed instead of returning empty string. Enables diagnosing what the reviewer was doing before being killed.
+- **`--verbose` / `-v` flag** — streams Claude's stderr to terminal for real-time tool call visibility, saves prompts to `build-logs/` for post-mortem, logs completion stats after each spawn.
+- **`--clean` flag** — deletes previous build output files before each phase's build step for fresh builds.
+- **Version display** — orchestrator shows GSD-T version in startup header.
+
+### Changed
+- **Reviewer timeout increased** — 300s → 600s for all-at-once review mode (per-item uses 120s per component).
+- **Design orchestrator** — added `buildSingleItemPrompt` and `buildSingleItemReviewPrompt` for per-item pipeline support. Reviewer prompt restructured: code review first, Playwright spot-check second.
+
 ## [2.71.21] - 2026-04-08
 
 ### Fixed (orchestrator — timeout false-pass, review server health, stale cleanup)

package/bin/design-orchestrator.js

@@ -134,6 +134,39 @@ ${importInstructions}
 This is a FINITE task. Build the ${items.length} ${phase} listed above, then EXIT.`;
 }
 
+function buildSingleItemPrompt(phase, item, prevResults, projectDir) {
+  const singular = PHASE_SINGULAR[phase];
+  const sourcePath = item.sourcePath || guessPaths(phase, item);
+
+  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 ONE ${singular} component for a Vue 3 + TypeScript project.
+
+## Task
+Build this component from its design contract. Read the contract for exact visual specs — do NOT approximate values.
+
+## Component
+- **${item.componentName}**
+- Contract: ${item.fullContractPath}
+- Write to: ${sourcePath}
+${importInstructions}
+## Rules
+- Read the contract file for exact property values
+- Write the component to the specified source path
+- Follow the project's existing code conventions (check existing files in src/)
+- Use the project's existing dependencies (check package.json)
+- When the component is complete, STOP. Do not start a dev server or build other components.
+
+This is a FINITE task. Build this ONE ${singular}, then EXIT.`;
+}
+
 // ─── Measurement ────────────────────────────────────────────────────────────
 
 function hasPlaywright(projectDir) {
@@ -332,16 +365,16 @@ ${componentList}
 ${measurementContext}
 ## Review Process
 
-For EACH component:
-1. Read the design contract file (path given above) — note every specified property value
-2. Read the source file — check that specified values are implemented correctly
-3. Use Playwright to render the component at http://localhost:${ports.reviewPort}/ and measure:
-   - Does the component render and have correct dimensions?
-   - Do colors, fonts, spacing, border-radius match the contract?
-   - For charts: correct chart type, orientation, axis labels, legend position, data format?
-   - For layouts: correct grid columns, gap, padding, child count and arrangement?
-   - For interactive elements: correct states, hover effects, click behavior?
-4. Compare contract values against actual rendered values — be SPECIFIC (exact px, hex, counts)
+**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.
 
 ## Output Format
 
@@ -359,7 +392,8 @@ If ALL components match their contracts, output:
 []
 [/REVIEW_ISSUES]
 
-## Rules
+## 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.
 - Be HARSH. Your value is in catching what the builder missed.
 - NEVER say "looks close" or "appears to match" — give SPECIFIC values.
@@ -367,6 +401,49 @@ If ALL components match their contracts, output:
 - Severity guide: critical = wrong component type, missing element, broken render. high = wrong dimensions, colors, layout. medium = spacing/padding off. low = minor visual difference.`;
 }
 
+function buildSingleItemReviewPrompt(phase, item, measurements, projectDir, ports) {
+  const sourcePath = item.sourcePath || guessPaths(phase, item);
+
+  // Include measurement failures for this item
+  const m = measurements[item.id] || [];
+  const failures = m.filter(x => !x.pass);
+  const measurementContext = failures.length > 0
+    ? `\n## Measurement Failures\nPlaywright detected: ${failures.map(f => `${f.property}: expected ${f.expected}, got ${f.actual}`).join("; ")}\n`
+    : "";
+
+  return `You are an INDEPENDENT design reviewer. Review this ONE component against its design contract.
+
+## Component
+- **${item.componentName}**
+- Contract: ${item.fullContractPath}
+- Source: ${sourcePath}
+- Selector: \`${item.selector || "." + item.id}\`
+${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
+
+## Output Format
+
+[REVIEW_ISSUES]
+[
+  {"component": "${item.componentName}", "severity": "high", "description": "Contract specifies X, code has Y"}
+]
+[/REVIEW_ISSUES]
+
+If the component matches its contract, output:
+[REVIEW_ISSUES]
+[]
+[/REVIEW_ISSUES]
+
+## Rules
+- You write ZERO code. You ONLY review.
+- Be HARSH — specific values only, no "looks close."
+- Output MUST contain [REVIEW_ISSUES] markers.`;
+}
+
 function buildAutoFixPrompt(phase, issues, items, projectDir) {
   const issueList = issues.map((issue, i) => {
     const item = items.find(c => c.componentName === issue.component);
@@ -408,6 +485,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}
@@ -439,13 +519,16 @@ const designBuildWorkflow = {
     devServerTimeout: 30_000,
     maxReviewCycles: 3,
     maxAutoReviewCycles: 4,
-    reviewTimeout: 300_000,
+    reviewTimeout: 600_000,
+    perItemTimeout: 120_000,
   },
   completionMessage: "All done. Run your app to verify: npm run dev",
 
   discoverWork,
   buildPrompt,
   buildReviewPrompt,
+  buildSingleItemPrompt,
+  buildSingleItemReviewPrompt,
   buildAutoFixPrompt,
   measure,
   buildQueueItem,
@@ -462,12 +545,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 ────────────────────────────────────────────────────────────
 
@@ -134,6 +134,9 @@ class Orchestrator {
         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 "--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();
@@ -160,6 +163,9 @@ ${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               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
 
 ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
@@ -185,31 +191,163 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
     const start = Date.now();
     let output = "";
     let exitCode = 0;
+    const verbose = this._verbose;
 
     // Build args: -p for print mode, --dangerously-skip-permissions so spawned
     // Claude can write files without interactive permission prompts
-    const args = ["-p", "--dangerously-skip-permissions", prompt];
+    const args = ["-p", "--dangerously-skip-permissions", "--output-format", "stream-json"];
+    if (verbose) args.push("--verbose");
+    args.push(prompt);
+
+    // Log prompt to file for debugging
+    if (verbose) {
+      const logDir = path.join(this.getReviewDir(projectDir), "build-logs");
+      ensureDir(logDir);
+      const label = opts.label || "claude";
+      fs.writeFileSync(
+        path.join(logDir, `${label}-prompt.txt`),
+        `--- Prompt (${new Date().toISOString()}) ---\nTimeout: ${(timeout || 600_000) / 1000}s\nCWD: ${projectDir}\n\n${prompt}`
+      );
+    }
 
     try {
-      output = execFileSync("claude", args, {
+      const raw = execFileSync("claude", args, {
         encoding: "utf8",
         timeout: timeout || this.wf.defaults?.timeout || 600_000,
         stdio: ["pipe", "pipe", "pipe"],
         cwd: projectDir,
         maxBuffer: 10 * 1024 * 1024,
       });
+      // Parse stream-json: each line is a JSON event, extract assistant text
+      output = this._parseStreamJson(raw, verbose);
     } catch (e) {
-      output = (e.stdout || "") + (e.stderr || "");
+      // On timeout/error, still parse any partial stream-json output we got
+      const rawOut = (e.stdout || "") + (e.stderr || "");
+      output = this._parseStreamJson(rawOut, verbose);
       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);
+
+    if (verbose) {
+      dim(`Claude finished: exit=${exitCode}, duration=${duration}s, output=${output.length} chars`);
+    }
+
     return { output, exitCode, duration };
   }
 
   // ─── 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
+    const textParts = [];
+    const toolCalls = [];
+
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const event = JSON.parse(line);
+        // Assistant text messages
+        if (event.type === "assistant" && event.message?.content) {
+          for (const block of event.message.content) {
+            if (block.type === "text") textParts.push(block.text);
+          }
+        }
+        // Content block deltas (partial streaming)
+        if (event.type === "content_block_delta" && event.delta?.text) {
+          textParts.push(event.delta.text);
+        }
+        // Result message
+        if (event.type === "result" && event.result) {
+          // result contains the final response text
+          if (typeof event.result === "string") textParts.push(event.result);
+        }
+        // Tool use tracking for verbose
+        if (verbose && event.type === "assistant" && event.message?.content) {
+          for (const block of event.message.content) {
+            if (block.type === "tool_use") {
+              toolCalls.push(block.name);
+              dim(`  → ${block.name}${block.input?.command ? ": " + String(block.input.command).slice(0, 80) : ""}`);
+            }
+          }
+        }
+      } catch { /* skip non-JSON lines */ }
+    }
+
+    if (verbose && toolCalls.length > 0) {
+      dim(`  Tool calls: ${toolCalls.length} (${[...new Set(toolCalls)].join(", ")})`);
+    }
+
+    return textParts.join("");
+  }
+
   startDevServer(projectDir, port) {
     if (isPortInUse(port)) {
       success(`Dev server already running on port ${port}`);
@@ -483,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 || []);
@@ -491,11 +629,17 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
     const { projectDir, resume, startPhase, devPort, reviewPort, skipMeasure } = opts;
     const phases = this.wf.phases;
     const maxReviewCycles = this.wf.defaults?.maxReviewCycles || 3;
+    this._verbose = opts.verbose || false;
 
+    const pkgVersion = (() => {
+      try { return require(path.join(__dirname, "..", "package.json")).version; } catch { return "unknown"; }
+    })();
     heading(`GSD-T ${this.wf.name} Orchestrator`);
+    log(`  Version: ${BOLD}v${pkgVersion}${RESET}`);
     log(`  Project: ${projectDir}`);
     log(`  Ports:   dev=${devPort} review=${reviewPort}`);
     log(`  Phases:  ${phases.join(" → ")}`);
+    if (this._verbose) log(`  ${YELLOW}Verbose mode: ON${RESET}`);
     log("");
 
     // 1. Verify prerequisites
@@ -520,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
@@ -577,129 +744,268 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
         }
       }
 
-      // 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`);
+      // Clean previous build output if --clean
+      if (opts.clean && this.wf.guessPaths) {
+        const cleaned = [];
+        for (const item of items) {
+          const guessed = this.wf.guessPaths(phase, item);
+          const paths = Array.isArray(guessed) ? guessed : [guessed];
+          for (const p of paths) {
+            const full = path.join(projectDir, p);
+            if (fs.existsSync(full)) {
+              fs.unlinkSync(full);
+              cleaned.push(p);
+            }
+          }
+        }
+        if (cleaned.length > 0) {
+          info(`--clean: removed ${cleaned.length} existing file(s) for ${phase}`);
+        }
+      }
 
-      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`);
+      // Clear stale auto-review files from previous runs
+      const arDir = path.join(this.getReviewDir(projectDir), "auto-review");
+      if (fs.existsSync(arDir)) {
+        for (const f of fs.readdirSync(arDir)) {
+          if (f.startsWith(`${phase}-`)) {
+            try { fs.unlinkSync(path.join(arDir, f)); } catch { /* ignore */ }
+          }
+        }
       }
 
-      // Log build output for debugging
       const buildLogDir = path.join(this.getReviewDir(projectDir), "build-logs");
       ensureDir(buildLogDir);
-      fs.writeFileSync(
-        path.join(buildLogDir, `${phase}-build.log`),
-        `Exit code: ${buildResult.exitCode}\nDuration: ${buildResult.duration}s\nPrompt length: ${prompt.length}\n\n--- OUTPUT ---\n${buildResult.output.slice(0, 20000)}`
-      );
-
-      // 6c. Collect built paths
-      const builtPaths = items.map(item =>
-        item.sourcePath || (this.wf.guessPaths ? this.wf.guessPaths(phase, item) : "")
-      );
-
-      // 6d. Measure
+      const maxAutoReviewCycles = this.wf.defaults?.maxAutoReviewCycles || 4;
+      const perItemTimeout = this.wf.defaults?.perItemTimeout || 120_000;
+      let builtPaths = [];
       let measurements = {};
-      if (!skipMeasure && this.wf.measure) {
-        measurements = this.wf.measure(projectDir, phase, items, { devPort, reviewPort }) || {};
-      }
 
-      // 6d.5. Automated AI review loop (Term 2 equivalent)
-      // Spawns an independent reviewer Claude that compares built output against contracts.
-      // If issues found → spawn fixer Claude → re-measure → re-review until clean.
-      const maxAutoReviewCycles = this.wf.defaults?.maxAutoReviewCycles || 4;
-      if (this.wf.buildReviewPrompt) {
-        // Clear stale auto-review files from previous runs for this phase
-        const arDir = path.join(this.getReviewDir(projectDir), "auto-review");
-        if (fs.existsSync(arDir)) {
-          for (const f of fs.readdirSync(arDir)) {
-            if (f.startsWith(`${phase}-`)) {
-              try { fs.unlinkSync(path.join(arDir, f)); } catch { /* ignore */ }
-            }
-          }
+      // ── Per-item pipeline: build ONE → review ONE → fix if needed ──
+      // Each item is independent: 1 contract + 1 source = tiny context.
+      // With --parallel N, runs N items concurrently.
+      if (this.wf.buildSingleItemPrompt && this.wf.buildSingleItemReviewPrompt) {
+        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...`);
         }
 
-        let autoReviewCycle = 0;
-        let autoReviewClean = false;
-
-        while (autoReviewCycle < maxAutoReviewCycles && !autoReviewClean) {
-          autoReviewCycle++;
-          heading(`Automated Review — ${phase} (cycle ${autoReviewCycle}/${maxAutoReviewCycles})`);
-
-          // Spawn reviewer Claude — independent, no builder context
-          const reviewPrompt = this.wf.buildReviewPrompt(phase, items, measurements, projectDir, { devPort, reviewPort });
-          log(`\n${CYAN}  ⚙${RESET} Spawning reviewer Claude for ${phase}...`);
-          const reviewTimeout = this.wf.defaults?.reviewTimeout || 300_000;
-          const reviewResult = this.spawnClaude(projectDir, reviewPrompt, reviewTimeout);
-
-          // Parse reviewer output for issues
-          let issues;
-
-          // Treat reviewer failure as a failed review, not a pass:
-          // - crash: non-zero exit + very short duration (< 10s)
-          // - timeout/kill: exit codes 143 (SIGTERM) or 137 (SIGKILL)
-          // - empty output with non-zero exit: reviewer produced nothing useful
-          const isCrash = reviewResult.exitCode !== 0 && reviewResult.duration < 10;
-          const isKilled = [143, 137].includes(reviewResult.exitCode);
-          const isEmptyFail = reviewResult.exitCode !== 0 && !reviewResult.output.trim();
-
-          if (isCrash || isKilled || isEmptyFail) {
-            const reason = isCrash ? "crashed" : isKilled ? "killed/timed out" : "failed with no output";
-            warn(`Reviewer ${reason} (code ${reviewResult.exitCode}, ${reviewResult.duration}s) — treating as review failure, will retry`);
-            issues = [{ component: "ALL", severity: "critical", description: `Reviewer ${reason} with exit code ${reviewResult.exitCode} — review not performed` }];
-          } else {
-            issues = this.wf.parseReviewResult
-              ? this.wf.parseReviewResult(reviewResult.output, phase)
-              : this._parseDefaultReviewResult(reviewResult.output);
+        // 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}`);
 
-            if (reviewResult.exitCode === 0) {
-              success(`Reviewer finished in ${reviewResult.duration}s`);
-            } else {
-              warn(`Reviewer exited with code ${reviewResult.exitCode} after ${reviewResult.duration}s`);
-            }
+          // Build
+          const buildPrompt = this.wf.buildSingleItemPrompt(phase, item, prevResults, projectDir);
+          dim(`  Building...`);
+          const buildResult = await this.spawnClaudeAsync(projectDir, buildPrompt, perItemTimeout, { label: `${phase}-build-${item.id}` });
+
+          if (buildResult.exitCode === 0) {
+            success(`  ${item.componentName}: built (${buildResult.duration}s)`);
+          } else {
+            warn(`  ${item.componentName}: build exit ${buildResult.exitCode} (${buildResult.duration}s)`);
           }
 
-          // Write review report
-          const reportDir = path.join(this.getReviewDir(projectDir), "auto-review");
-          ensureDir(reportDir);
           fs.writeFileSync(
-            path.join(reportDir, `${phase}-cycle-${autoReviewCycle}.json`),
-            JSON.stringify({ cycle: autoReviewCycle, issues, exitCode: reviewResult.exitCode, duration: reviewResult.duration, output: reviewResult.output.slice(0, 5000) }, null, 2)
+            path.join(buildLogDir, `${phase}-build-${item.id}.log`),
+            `Exit code: ${buildResult.exitCode}\nDuration: ${buildResult.duration}s\n\n--- OUTPUT ---\n${buildResult.output.slice(0, 5000)}`
           );
 
-          if (issues.length === 0) {
-            autoReviewClean = true;
-            success(`Automated review passed — no issues found in ${phase}`);
-          } else {
-            warn(`Automated review found ${issues.length} issue(s) in ${phase}`);
-            for (const issue of issues) {
-              dim(`${issue.component || "?"}: ${issue.description || issue.reason || "issue"} [${issue.severity || "medium"}]`);
+          // Review cycles
+          let itemClean = false;
+          for (let cycle = 1; cycle <= maxAutoReviewCycles && !itemClean; cycle++) {
+            dim(`  ${item.componentName}: review c${cycle}...`);
+            const reviewPrompt = this.wf.buildSingleItemReviewPrompt(phase, item, {}, projectDir, { devPort, reviewPort });
+            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);
+            const isEmptyFail = reviewResult.exitCode !== 0 && !reviewResult.output.trim();
+
+            let itemIssues = [];
+            if (isCrash || isKilled || isEmptyFail) {
+              const reason = isCrash ? "crashed" : isKilled ? "killed/timed out" : "failed with no output";
+              warn(`  ${item.componentName}: reviewer ${reason} (${reviewResult.duration}s)`);
+              itemIssues = [{ component: item.componentName, severity: "critical", description: `Reviewer ${reason}` }];
+            } else {
+              itemIssues = this.wf.parseReviewResult
+                ? this.wf.parseReviewResult(reviewResult.output, phase)
+                : this._parseDefaultReviewResult(reviewResult.output);
+            }
+
+            if (itemIssues.length === 0) {
+              itemClean = true;
+              success(`  ${item.componentName}: clean (${reviewResult.duration}s)`);
+            } else {
+              warn(`  ${item.componentName}: ${itemIssues.length} issue(s)`);
+              for (const issue of itemIssues) {
+                dim(`    ${issue.description || "issue"} [${issue.severity || "medium"}]`);
+              }
+
+              if (cycle < maxAutoReviewCycles) {
+                const fixPrompt = this.wf.buildAutoFixPrompt
+                  ? this.wf.buildAutoFixPrompt(phase, itemIssues, [item], projectDir)
+                  : this._defaultAutoFixPrompt(phase, itemIssues);
+                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}`);
+              }
             }
+          }
+
+          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) {
+          heading("Measuring all built components");
+          measurements = this.wf.measure(projectDir, phase, items, { devPort, reviewPort }) || {};
+        }
+
+      } else {
+        // ── Legacy pipeline: build ALL → measure ALL → review loop ──
+        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, { label: `${phase}-build` });
+        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`);
+        }
 
-            if (autoReviewCycle < maxAutoReviewCycles) {
-              // Spawn fixer Claude with the issues
-              const fixPrompt = this.wf.buildAutoFixPrompt
-                ? this.wf.buildAutoFixPrompt(phase, issues, items, projectDir)
-                : this._defaultAutoFixPrompt(phase, issues);
+        fs.writeFileSync(
+          path.join(buildLogDir, `${phase}-build.log`),
+          `Exit code: ${buildResult.exitCode}\nDuration: ${buildResult.duration}s\nPrompt length: ${prompt.length}\n\n--- OUTPUT ---\n${buildResult.output.slice(0, 20000)}`
+        );
 
-              log(`\n${CYAN}  ⚙${RESET} Spawning fixer Claude for ${issues.length} issue(s)...`);
-              const fixResult = this.spawnClaude(projectDir, fixPrompt, opts.timeout || 600_000);
-              if (fixResult.exitCode === 0) success(`Fixer finished in ${fixResult.duration}s`);
-              else warn(`Fixer exited with code ${fixResult.exitCode}`);
+        builtPaths = items.map(item =>
+          item.sourcePath || (this.wf.guessPaths ? this.wf.guessPaths(phase, item) : "")
+        );
 
-              // Re-measure after fixes
-              if (!skipMeasure && this.wf.measure) {
-                measurements = this.wf.measure(projectDir, phase, items, { devPort, reviewPort }) || {};
+        // Measure
+        if (!skipMeasure && this.wf.measure) {
+          measurements = this.wf.measure(projectDir, phase, items, { devPort, reviewPort }) || {};
+        }
+
+        // Auto-review loop (legacy all-at-once)
+        if (this.wf.buildReviewPrompt || this.wf.buildSingleItemReviewPrompt) {
+          let autoReviewCycle = 0;
+          let autoReviewClean = false;
+
+          while (autoReviewCycle < maxAutoReviewCycles && !autoReviewClean) {
+            autoReviewCycle++;
+            heading(`Automated Review — ${phase} (cycle ${autoReviewCycle}/${maxAutoReviewCycles})`);
+
+            const reviewTimeout = this.wf.defaults?.reviewTimeout || 300_000;
+            let issues = [];
+
+            if (this.wf.buildSingleItemReviewPrompt) {
+              // Per-item review even in legacy build mode
+              log(`\n${CYAN}  ⚙${RESET} Reviewing ${items.length} ${phase} one at a time...`);
+              let totalDuration = 0;
+
+              for (let idx = 0; idx < items.length; idx++) {
+                const item = items[idx];
+                const itemMeasurements = { [item.id]: measurements[item.id] || [] };
+                const reviewPrompt = this.wf.buildSingleItemReviewPrompt(phase, item, itemMeasurements, projectDir, { devPort, reviewPort });
+
+                dim(`  [${idx + 1}/${items.length}] ${item.componentName}...`);
+                const reviewResult = this.spawnClaude(projectDir, reviewPrompt, Math.min(reviewTimeout, perItemTimeout), { label: `${phase}-review-c${autoReviewCycle}-${item.id}` });
+                totalDuration += reviewResult.duration;
+
+                const isCrash = reviewResult.exitCode !== 0 && reviewResult.duration < 10;
+                const isKilled = [143, 137].includes(reviewResult.exitCode);
+                const isEmptyFail = reviewResult.exitCode !== 0 && !reviewResult.output.trim();
+
+                if (isCrash || isKilled || isEmptyFail) {
+                  const reason = isCrash ? "crashed" : isKilled ? "killed/timed out" : "failed with no output";
+                  warn(`  ${item.componentName}: reviewer ${reason} (${reviewResult.duration}s)`);
+                  issues.push({ component: item.componentName, severity: "critical", description: `Reviewer ${reason} — review not performed` });
+                } else {
+                  const itemIssues = this.wf.parseReviewResult
+                    ? this.wf.parseReviewResult(reviewResult.output, phase)
+                    : this._parseDefaultReviewResult(reviewResult.output);
+
+                  if (itemIssues.length > 0) {
+                    warn(`  ${item.componentName}: ${itemIssues.length} issue(s) (${reviewResult.duration}s)`);
+                    issues.push(...itemIssues);
+                  } else {
+                    success(`  ${item.componentName}: clean (${reviewResult.duration}s)`);
+                  }
+                }
               }
+              log(`\n  Total review time: ${totalDuration}s for ${items.length} items`);
+
             } else {
-              warn(`Max auto-review cycles reached — ${issues.length} issue(s) will go to human review`);
-              // Attach unresolved issues to measurements for human visibility
-              const issueFile = path.join(this.getReviewDir(projectDir), "auto-review", `${phase}-unresolved.json`);
-              fs.writeFileSync(issueFile, JSON.stringify(issues, null, 2));
+              // All-at-once review
+              const reviewPrompt = this.wf.buildReviewPrompt(phase, items, measurements, projectDir, { devPort, reviewPort });
+              log(`\n${CYAN}  ⚙${RESET} Spawning reviewer Claude for all ${phase}...`);
+              const reviewTimeout2 = this.wf.defaults?.reviewTimeout || 300_000;
+              const reviewResult = this.spawnClaude(projectDir, reviewPrompt, reviewTimeout2, { label: `${phase}-review-cycle${autoReviewCycle}` });
+
+              const isCrash = reviewResult.exitCode !== 0 && reviewResult.duration < 10;
+              const isKilled = [143, 137].includes(reviewResult.exitCode);
+              const isEmptyFail = reviewResult.exitCode !== 0 && !reviewResult.output.trim();
+
+              if (isCrash || isKilled || isEmptyFail) {
+                const reason = isCrash ? "crashed" : isKilled ? "killed/timed out" : "failed with no output";
+                warn(`Reviewer ${reason} (code ${reviewResult.exitCode}, ${reviewResult.duration}s)`);
+                issues = [{ component: "ALL", severity: "critical", description: `Reviewer ${reason} with exit code ${reviewResult.exitCode}` }];
+              } else {
+                issues = this.wf.parseReviewResult
+                  ? this.wf.parseReviewResult(reviewResult.output, phase)
+                  : this._parseDefaultReviewResult(reviewResult.output);
+                if (reviewResult.exitCode === 0) success(`Reviewer finished in ${reviewResult.duration}s`);
+                else warn(`Reviewer exited with code ${reviewResult.exitCode} after ${reviewResult.duration}s`);
+              }
+            }
+
+            // Write review report
+            const reportDir = path.join(this.getReviewDir(projectDir), "auto-review");
+            ensureDir(reportDir);
+            fs.writeFileSync(
+              path.join(reportDir, `${phase}-cycle-${autoReviewCycle}.json`),
+              JSON.stringify({ cycle: autoReviewCycle, issues, itemCount: items.length }, null, 2)
+            );
+
+            if (issues.length === 0) {
+              autoReviewClean = true;
+              success(`Automated review passed — no issues found in ${phase}`);
+            } else {
+              warn(`Automated review found ${issues.length} issue(s) in ${phase}`);
+              for (const issue of issues) {
+                dim(`${issue.component || "?"}: ${issue.description || issue.reason || "issue"} [${issue.severity || "medium"}]`);
+              }
+
+              if (autoReviewCycle < maxAutoReviewCycles) {
+                const fixPrompt = this.wf.buildAutoFixPrompt
+                  ? this.wf.buildAutoFixPrompt(phase, issues, items, projectDir)
+                  : this._defaultAutoFixPrompt(phase, issues);
+
+                log(`\n${CYAN}  ⚙${RESET} Spawning fixer Claude for ${issues.length} issue(s)...`);
+                const fixResult = this.spawnClaude(projectDir, fixPrompt, opts.timeout || 600_000, { label: `${phase}-fix-cycle${autoReviewCycle}` });
+                if (fixResult.exitCode === 0) success(`Fixer finished in ${fixResult.duration}s`);
+                else warn(`Fixer exited with code ${fixResult.exitCode}`);
+
+                if (!skipMeasure && this.wf.measure) {
+                  measurements = this.wf.measure(projectDir, phase, items, { devPort, reviewPort }) || {};
+                }
+              } else {
+                warn(`Max auto-review cycles reached — ${issues.length} issue(s) will go to human review`);
+                const issueFile = path.join(this.getReviewDir(projectDir), "auto-review", `${phase}-unresolved.json`);
+                fs.writeFileSync(issueFile, JSON.stringify(issues, null, 2));
+              }
             }
           }
         }
@@ -728,7 +1034,7 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
               ? 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, opts.timeout || 600_000);
+            const fixResult = this.spawnClaude(projectDir, fixPrompt, opts.timeout || 600_000, { label: `${phase}-human-fix` });
             if (fixResult.exitCode === 0) success("Fixes applied");
             else warn(`Fix attempt returned code ${fixResult.exitCode}`);
           } else {

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

@@ -33,6 +33,9 @@ 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`           | 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.71.21",
+  "version": "2.73.10",
   "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",