@tekyzinc/gsd-t 3.13.15 → 3.15.10

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.15.10] - 2026-04-20
+
+### Added — Universal Token Capture Across GSD-T (M41)
+
+Every subagent spawn across GSD-T now routes through a single shared wrapper, retiring the silent `| N/A |` Tokens convention that preceded M41. Every spawn's input/output/cache tokens and cost USD land in both the human-readable `.gsd-t/token-log.md` and the machine-readable `.gsd-t/metrics/token-usage.jsonl` (schema v1, reused from M40 D4).
+
+**Token-capture wrapper (D1)**: `bin/gsd-t-token-capture.cjs` exports `captureSpawn({command, step, model, description, projectDir, spawnFn, domain?, task?})` and `recordSpawnRow({...})`. Parses bare + `.result`-wrapped + stream-json envelopes with assistant-vs-result precedence. Missing usage renders `—`, never `0`, never `N/A`. Migration-in-place upgrades existing `.gsd-t/token-log.md` to the canonical 12-column header (adds Tokens + Compacted columns).
+
+**Command-file doc-ripple (D2)**: all 20 spawn-capable `commands/*.md` files converted from inline `T_START=$(date +%s)` bash blocks to `captureSpawn`/`recordSpawnRow` pattern. `templates/CLAUDE-global.md` and the project `CLAUDE.md` carry the Token Capture Rule (MANDATORY). A canonical-block drift-guard test (`test/m41-canonical-block-drift.test.js`) asserts no legacy blocks remain and every OBSERVABILITY LOGGING declaration pairs with a wrapper call.
+
+**Historical backfill (D3)**: `bin/gsd-t-token-backfill.cjs` + `gsd-t backfill-tokens [--since YYYY-MM-DD] [--patch-log] [--dry-run]`. Walks `.gsd-t/events/*.jsonl`, `.gsd-t/stream-feed/*.jsonl`, and `.gsd-t/headless-*.log`. Handles both event-stream frames and stream-json frames. Idempotent via `source: "backfill"` key-tuple tracking. `--patch-log` atomically rewrites legacy `N/A`/`0`/`—` Tokens cells in place using tmp+rename.
+
+**Token dashboard (D4)**: `bin/gsd-t-token-dashboard.cjs` + `gsd-t tokens [--since] [--milestone] [--format table|json]`. Streams JSONL via `readline.createInterface`; aggregates byDay/byCommand/byModel; top-10 spawns by cost desc; cache-hit rate per model; rolling 7-day projection (daily avg × 30). Injects a 3-line token block at the tail of `gsd-t status`. Perf gate: 22ms on 10k-line JSONL (budget 500ms).
+
+**Enforcement (D5)**: `bin/gsd-t-capture-lint.cjs` + `gsd-t capture-lint [--staged|--all]`. Greps for `Task({`, `spawn('claude', ...)`, and `claude -p` without a surrounding `captureSpawn`/`recordSpawnRow` within ±20 lines. Balanced-quote heuristic excludes JS-string-literal false positives. Whitelists: wrapper/linter modules themselves, `test/**`, `commands/gsd-t-help.md`, comment-only lines, markdown prose outside fences, any line with `GSD-T-CAPTURE-LINT: skip` marker nearby. Opt-in pre-commit hook via `gsd-t init --install-hooks` — appends idempotently to `.git/hooks/pre-commit` with a `# GSD-T capture lint` marker; never overwrites existing hooks.
+
+Tests: +27 net (1479/1479 total). No new contracts — reuses M40's `metrics-schema-contract.md` v1 and `stream-json-sink-contract.md` v1.1.0.
+
+## [3.14.10] - 2026-04-20
+
+### Added — External Task Orchestrator + Streaming Watcher UI (M40)
+
+JS orchestrator (`bin/gsd-t-orchestrator.js`) drives `claude -p` one task per spawn: short-lived, fresh context, architecturally compaction-free. Benchmark gate PASS: 226s orchestrator vs 316s in-session on 20-task/3-wave/4-domain fixture (0.72× wall-clock, threshold 1.05×).
+
+**Orchestrator core (D1)**: wave-barrier join, per-wave Promise.all parallelism (default 3, ceiling 15 per Team Mode §15), workerPid attribution, SIGINT handler, retry policy per completion-signal-contract (first FAIL → single retry; second FAIL → halt wave), state.json atomic writes, task-boundary + wave-boundary synthetic frames emitted to stream-feed clients.
+
+**Task brief builder (D2)**: `bin/gsd-t-task-brief.js` composes 2–5 KB self-contained per-task briefs from `.gsd-t/domains/{domain}/{scope,constraints,tasks}.md` + named contract excerpts + stack rules + Done Signal section; drop-order compactor guarantees non-droppable sections always survive.
+
+**Completion protocol (D3)**: `bin/gsd-t-completion-check.cjs` `assertCompletion()` returns `{ok, missing[], details}` by checking commit-on-expected-branch + progress.md entry + test exit. Ambiguous tasks (commit present but no progress entry) are flagged for operator triage — never silently claimed done.
+
+**Stream-feed server (D4)**: `scripts/gsd-t-stream-feed-server.js` — HTTP POST /ingest, WebSocket /feed?from=N replay, 127.0.0.1:7842, JSONL persist-before-broadcast. `scripts/gsd-t-token-aggregator.js` parses assistant + result envelope usage and writes `.gsd-t/metrics/token-usage.jsonl` schema v1 + rewrites `.gsd-t/token-log.md` in place. New CLI: `gsd-t stream-feed`.
+
+**Stream-feed UI (D5)**: `scripts/gsd-t-stream-feed.html` — 47.5 KB, zero-dep, zero-token-cost local dashboard. Dark-mode claude.ai-style continuous feed with task/wave banners (duration + cost/tokens chips), token corner bar (running total), localStorage-persisted filters (tasks/domains/waves), auto-scroll pause + "↓ Jump to live" button.
+
+**Recovery and resume (D6)**: `bin/gsd-t-orchestrator-recover.cjs` `recoverRunState()` reconciles interrupted runs via assertCompletion replay; `--resume` + `--no-archive` flags on `gsd-t orchestrate`; `/gsd-t-resume` Step 0.3 auto-detects in-flight state.json and surfaces resume invocation; 24 recovery unit tests cover fresh/terminal/resume modes + ambiguous classification + PID liveness.
+
+**Contracts**: `stream-json-sink-contract.md` v1.0.0 → **v1.1.0** (new §"Usage field propagation" documenting assistant vs result envelope semantics); `wave-join-contract.md`, `completion-signal-contract.md`, `metrics-schema-contract.md` — all test-backed.
+
+**Tests**: 1421/1421 pass (up from 1240 at M39 close, +181). 16 new M40 test files. Zero coverage gaps. Zero placeholder patterns (goal-backward PASS).
+
+**New CLI subcommands**: `gsd-t orchestrate`, `gsd-t benchmark-orchestrator`, `gsd-t stream-feed`.
+
+**Files**: `bin/gsd-t-orchestrator.js`, `bin/gsd-t-orchestrator-worker.cjs`, `bin/gsd-t-orchestrator-queue.cjs`, `bin/gsd-t-orchestrator-config.cjs`, `bin/gsd-t-orchestrator-recover.cjs`, `bin/gsd-t-completion-check.cjs`, `bin/gsd-t-benchmark-orchestrator.js`, `bin/gsd-t-task-brief.js`, `bin/gsd-t-task-brief-template.cjs`, `bin/gsd-t-task-brief-compactor.cjs`, `scripts/gsd-t-stream-feed-server.js`, `scripts/gsd-t-stream-feed.html`, `scripts/gsd-t-token-aggregator.js`, `templates/prompts/m40-task-brief.md`, 16 M40 test files, 4 new/updated contracts, `commands/gsd-t-resume.md` Step 0.3.
+
+## [3.13.16] - 2026-04-17
+
+### Changed — Removed proactive suggestions to use `/gsd-t-unattended`; positioned as overnight/idle-only
+
+The unattended supervisor remains supported for genuine overnight or multi-hour idle runs but is no longer pitched as a general workflow option. In practice it runs 5–10× slower than in-session execution because every worker iteration pays cold-context startup cost (re-reads CLAUDE.md, progress.md, all domain files) before doing real work, then is bounded to a 270s cache-warm budget. Daytime work belongs in-session.
+
+**Files**:
+- `templates/CLAUDE-global.md` — removed the "Unattended Execution (M36)" section that pitched it as a feature alongside in-session.
+- `commands/gsd-t-help.md` — repositioned the `unattended*` rows under AUTOMATION as overnight-only with a slowness caveat.
+- `README.md` — removed the top-level "Unattended execution" feature bullet; renamed the commands-table heading and the full section heading to "Overnight / Idle-Run …" with a leading callout that daytime work runs in-session; reworded the M38 headless-by-default bullet to drop "via the unattended supervisor" framing.
+
+**No behavioral changes.** Commands `/gsd-t-unattended`, `/gsd-t-unattended-watch`, `/gsd-t-unattended-stop` continue to work exactly as before. The supervisor contract is unchanged.
+
 ## [3.13.15] - 2026-04-17
 
 ### Fixed — Self-protection guard now uses package-name identity + narrow `bin/*.cjs` gitignore rule

package/README.md

@@ -10,11 +10,11 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Protects existing work** — destructive action guard prevents schema drops, architecture replacements, and data loss without explicit approval.
 **Visualizes execution in real time** — live browser dashboard renders agent hierarchy, tool activity, and phase progression from the event stream.
 **Generates visual scan reports** — every `/gsd-t-scan` produces a self-contained HTML report with 6 live architectural diagrams, a tech debt register, and domain health scores; optional DOCX/PDF export via `--export docx|pdf`.
-**Unattended execution** — `gsd-t unattended --hours=N` spawns a detached OS-process supervisor that drives the active milestone to completion over hours or days with zero human intervention. A ScheduleWakeup watch loop ticks every 270 seconds; `/clear` + resume transparently re-attaches to the running supervisor.
 **Self-learning rule engine** — declarative rules in rules.jsonl detect failure patterns from task metrics. Candidate patches progress through a 5-stage lifecycle (candidate, applied, measured, promoted, graduated) with >55% improvement gates before becoming permanent methodology artifacts.
 **Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
 **Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and mandatory visual verification: every screen is rendered in a real browser, screenshotted at mobile/tablet/desktop, and compared pixel-by-pixel against the Figma design. Auto-bootstraps during partition when design references are detected. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
-**Headless-by-Default Spawn (M38, v3.12.10)** — long-running workflow commands (execute, wave, integrate, debug repair loops) spawn detached by default via the unattended supervisor. The interactive session prints a launch banner, logs the event-stream path, and exits. Pass `--watch` to keep a live status block in the session (270s `ScheduleWakeup` ticks, cache-window-safe). The supervisor emits JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl` at every phase boundary — shared by watch command and dashboard. See `.gsd-t/contracts/headless-default-contract.md` v1.0.0 and `unattended-event-stream-contract.md` v1.0.0.
+**External Task Orchestrator + Streaming Watcher UI (M40, v3.14.10)** — JS orchestrator drives `claude -p` one task per spawn: short-lived, fresh context, architecturally compaction-free. Benchmarks 0.72× wall-clock vs in-session on 20-task/3-wave workloads. Paired with a zero-Claude-cost local streaming UI at `127.0.0.1:7842` that renders all workers' stream-json output as a continuous claude.ai-style feed — task/wave banners, duration + usage chips, token corner bar, localStorage filters, replay via `WS /feed?from=N`. Recovery: `--resume` reconciles interrupted runs using commit + progress.md evidence; ambiguous tasks (commit without progress entry) are flagged for operator triage, never silently claimed done. CLI: `gsd-t orchestrate`, `gsd-t benchmark-orchestrator`, `gsd-t stream-feed`. Contracts: `stream-json-sink-contract.md` v1.1.0, `wave-join-contract.md`, `completion-signal-contract.md`, `metrics-schema-contract.md`.
+**Headless-by-Default Spawn (M38, v3.12.10)** — long-running workflow commands (execute, wave, integrate, debug repair loops) spawn detached by default. The interactive session prints a launch banner, logs the event-stream path, and exits. Pass `--watch` to keep a live status block in the session (270s `ScheduleWakeup` ticks, cache-window-safe). Detached workers emit JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl` at every phase boundary — shared by watch command and dashboard. See `.gsd-t/contracts/headless-default-contract.md` v1.0.0 and `unattended-event-stream-contract.md` v1.0.0.
 - **Surgical model selection** — `bin/model-selector.js` assigns haiku/sonnet/opus per phase via a declarative rules table; `/advisor` escalation path with convention-based fallback.
 - **Per-spawn token telemetry** — `.gsd-t/token-metrics.jsonl` records one 18-field row per Task subagent spawn.
 **Context Meter (M34/M38)** — PostToolUse hook writes `.gsd-t/.context-meter-state.json` via local token estimation. Single-band model (`context-meter-contract.md` v1.3.0): one threshold (default 85%), one action — hand off to a detached headless spawn. The meter informs spawn-time routing, not in-flight pauses.
@@ -172,11 +172,11 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-verify` | Run quality gates + goal-backward behavior verification | In wave |
 | `/gsd-t-complete-milestone` | Archive + git tag (goal-backward gate required) | In wave |
 
-### Unattended Execution
+### Overnight / Idle-Run Commands (slower than in-session — use only for unattended overnight or multi-hour idle runs)
 
 | Command | Purpose | Auto |
 |---------|---------|------|
-| `/gsd-t-unattended` | Launch detached supervisor — runs active milestone to completion with zero human intervention | Manual |
+| `/gsd-t-unattended` | Launch detached supervisor for overnight/idle runs only | Manual |
 | `/gsd-t-unattended-watch` | Watch tick — fires every 270s via ScheduleWakeup, reports supervisor status | Auto |
 | `/gsd-t-unattended-stop` | Touch stop sentinel — supervisor halts after current worker finishes | Manual |
 
@@ -314,15 +314,15 @@ your-project/
 
 ---
 
-## Unattended Execution (M36 — v3.10.10+)
+## Overnight / Idle-Run Supervisor (M36 — v3.10.10+)
 
-Run the active milestone to completion over hours or days — no human in the loop.
+> **Daytime work runs in-session.** This supervisor is provided for unattended overnight or multi-hour idle runs only — it is dramatically slower than in-session execution because every worker iteration pays cold-context startup cost (re-reads CLAUDE.md, progress.md, all domain files) before doing real work, then is bounded to a 270s cache-warm budget. Reach for it only when you genuinely cannot supervise the run.
 
 ```bash
 # Launch from the CLI (detached OS process)
 gsd-t unattended --hours=24
 
-# Or from within Claude Code (starts a 270s watch loop)
+# Or from within Claude Code
 /gsd-t-unattended
 
 # Stop (graceful — supervisor halts after the current worker finishes)

package/bin/gsd-t-benchmark-orchestrator.js

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+'use strict';
+
+// D0-T2 — M40 speed-benchmark gate driver.
+// Compares wall-clock time for two ways of executing the same fixed workload:
+//   (a) orchestrator path  — one `claude -p` spawn per task, wave-join loop
+//                            driven by bin/gsd-t-orchestrator.js
+//   (b) in-session path    — a single `claude -p` session that runs the same
+//                            tasks sequentially (the honest "one Claude Code
+//                            window" comparison)
+// Contract: .gsd-t/contracts/wave-join-contract.md v1.0.0
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const DEFAULT_FIXTURE = path.join(PKG_ROOT, 'test', 'fixtures', 'm40-benchmark-workload');
+const PASS_TOLERANCE = 1.05;
+
+function parseCliArgs(argv) {
+  const args = {
+    runs: 3,
+    reportPath: null,
+    resultsPath: null,
+    fixtureDir: DEFAULT_FIXTURE,
+    mockClaude: null,
+    projectDir: process.cwd(),
+    keepTmp: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') { args.help = true; }
+    else if (a === '--runs') { args.runs = parseInt(argv[++i], 10); }
+    else if (a === '--report-path') { args.reportPath = argv[++i]; }
+    else if (a === '--results-path') { args.resultsPath = argv[++i]; }
+    else if (a === '--fixture-dir') { args.fixtureDir = path.resolve(argv[++i]); }
+    else if (a === '--mock-claude') { args.mockClaude = path.resolve(argv[++i]); }
+    else if (a === '--project-dir') { args.projectDir = path.resolve(argv[++i]); }
+    else if (a === '--keep-tmp') { args.keepTmp = true; }
+  }
+  if (!Number.isInteger(args.runs) || args.runs < 1) {
+    throw new Error('--runs must be a positive integer');
+  }
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write([
+    'Usage: gsd-t benchmark-orchestrator [options]',
+    '',
+    'Runs the M40 speed-benchmark kill-switch gate: compares orchestrator',
+    'path vs in-session path on a fixed workload and emits a verdict.',
+    '',
+    'Options:',
+    '  --runs <n>             Number of runs per side (default 3).',
+    '  --report-path <path>   Human-readable report (default docs/m40-benchmark-report.md).',
+    '  --results-path <path>  Machine-readable JSON (default .gsd-t/benchmark-results.json).',
+    '  --fixture-dir <path>   Override benchmark workload fixture directory.',
+    '  --mock-claude <path>   Use this binary as `claude` (for smoke tests).',
+    '  --project-dir <path>   Project directory to write outputs into (default cwd).',
+    '  --keep-tmp             Preserve per-run tmp directories for diagnosis.',
+    '  -h, --help             Show this help.',
+    '',
+    'Verdict is PASS when median(orchestrator_ms) <= median(in-session_ms) * 1.05.',
+    '',
+  ].join('\n'));
+}
+
+function median(nums) {
+  if (!nums.length) return 0;
+  const sorted = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+
+function copyDirSync(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) copyDirSync(s, d);
+    else if (entry.isSymbolicLink()) fs.symlinkSync(fs.readlinkSync(s), d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function gitInitRepo(dir) {
+  const opts = { cwd: dir, stdio: 'ignore' };
+  spawnSync('git', ['init', '-q', '-b', 'main'], opts);
+  spawnSync('git', ['config', 'user.email', 'bench@gsd-t.local'], opts);
+  spawnSync('git', ['config', 'user.name', 'benchmark'], opts);
+  spawnSync('git', ['config', 'commit.gpgsign', 'false'], opts);
+  spawnSync('git', ['add', '-A'], opts);
+  spawnSync('git', ['commit', '-q', '-m', 'benchmark fixture baseline'], opts);
+}
+
+function prepareRun(fixtureDir, label, runIdx) {
+  const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), `m40-bench-${label}-${runIdx}-`));
+  const dest = path.join(tmpBase, 'workload');
+  copyDirSync(fixtureDir, dest);
+  gitInitRepo(dest);
+  return { tmpBase, dest };
+}
+
+function cleanupRun(tmpBase) {
+  try { fs.rmSync(tmpBase, { recursive: true, force: true }); } catch (_) { /* best effort */ }
+}
+
+function buildChildEnv(mockClaude) {
+  const env = { ...process.env };
+  if (mockClaude) env.GSD_T_CLAUDE_BIN = mockClaude;
+  return env;
+}
+
+function captureOutput(res) {
+  const parts = [];
+  if (res && res.stdout) parts.push('--- stdout ---\n' + String(res.stdout));
+  if (res && res.stderr) parts.push('--- stderr ---\n' + String(res.stderr));
+  return parts.join('\n').slice(-4096);
+}
+
+function runOrchestratorSide({ fixtureDir, runIdx, mockClaude, logger, keepTmp = false, spawnImpl = spawnSync }) {
+  const { tmpBase, dest } = prepareRun(fixtureDir, 'orch', runIdx);
+  const bin = path.join(__dirname, 'gsd-t-orchestrator.js');
+  const t0 = Date.now();
+  let exitCode = null;
+  let output = '';
+  try {
+    const res = spawnImpl(process.execPath, [
+      bin,
+      '--milestone', 'M40-bench',
+      '--project-dir', dest,
+      '--max-parallel', '8',
+      '--worker-timeout', '180000',
+    ], {
+      env: buildChildEnv(mockClaude),
+      encoding: 'utf8',
+      timeout: 900000,
+    });
+    exitCode = res.status;
+    output = captureOutput(res);
+  } catch (e) {
+    output = 'spawn_error: ' + (e && e.message);
+  }
+  const durationMs = Date.now() - t0;
+  const commitAudit = auditTaskCommits(dest);
+  if (logger) logger.log(`[bench orch #${runIdx}] exit=${exitCode} duration=${durationMs}ms commits=${commitAudit.taskCommitCount}/${commitAudit.expectedTaskCount}`);
+  if (keepTmp && logger) logger.log(`  kept: ${tmpBase}`);
+  if (!keepTmp) cleanupRun(tmpBase);
+  return {
+    durationMs,
+    exitCode,
+    stderr: output,
+    tmpDir: keepTmp ? tmpBase : null,
+    commitAudit
+  };
+}
+
+function runInsessionSide({ fixtureDir, runIdx, mockClaude, logger, keepTmp = false, spawnImpl = spawnSync }) {
+  const { tmpBase, dest } = prepareRun(fixtureDir, 'insession', runIdx);
+  const claudeBin = mockClaude || process.env.GSD_T_CLAUDE_BIN || 'claude';
+  const prompt = [
+    '# In-session equivalent — M40 benchmark control',
+    '',
+    'You are simulating a single Claude Code window running /gsd-t-execute',
+    'against this fixture sequentially (no external orchestrator).',
+    '',
+    `Project dir: ${dest}`,
+    '',
+    '## Required discipline (enforces parity with orchestrator path)',
+    '',
+    'For the benchmark to be a fair comparison, you MUST apply the same',
+    'per-task discipline the external orchestrator enforces on its workers.',
+    'Shortcuts that collapse multiple tasks into one batch INVALIDATE the',
+    'benchmark.',
+    '',
+    '1. Read `.gsd-t/contracts/completion-signal-contract.md` once at the start.',
+    '2. Read every `.gsd-t/domains/*/tasks.md` to enumerate the tasks.',
+    '3. Process tasks strictly in wave order: ALL wave 0 before ANY wave 1,',
+    '   ALL wave 1 before ANY wave 2, etc. Within a wave you may interleave',
+    '   tasks but each task MUST complete its own commit before the next',
+    '   task begins writing files.',
+    '4. For EACH task, in order:',
+    '   a. Read the task body from its domain tasks.md',
+    '   b. Create/modify ONLY the files listed in that task\'s `**Files**:` field',
+    '   c. Run `npm test` and verify it passes',
+    '   d. `git add` ONLY that task\'s owned files',
+    '   e. `git commit` with a message starting with the canonical task id',
+    '      (e.g. `bench-d1-t1: …`) on branch `main`',
+    '   f. Add a Decision Log entry to `.gsd-t/progress.md` naming the task id',
+    '   g. Commit the progress.md update as part of (e) OR as a follow-up',
+    '      commit whose message also starts with the same task id',
+    '',
+    '## Hard rules',
+    '- ONE commit per task minimum. Twenty tasks → at least twenty commits',
+    '  beyond the baseline commit. DO NOT bulk-commit multiple tasks.',
+    '- DO NOT write files for task N+1 before task N is committed.',
+    '- DO NOT spawn subagents — you are the single-session baseline.',
+    '- DO NOT push to any git remote (no `git push`).',
+    '- If you finish early, STOP. Do not run extra work.',
+    '',
+    'This is the baseline the external orchestrator is being compared to.',
+    'The comparison is only meaningful if both sides obey the same rules.',
+    '',
+  ].join('\n');
+  const t0 = Date.now();
+  let exitCode = null;
+  let output = '';
+  try {
+    const res = spawnImpl(claudeBin, [
+      '-p',
+      '--dangerously-skip-permissions',
+      '--output-format', 'stream-json',
+      '--verbose',
+      '--model', 'sonnet',
+    ], {
+      cwd: dest,
+      env: buildChildEnv(mockClaude),
+      input: prompt,
+      encoding: 'utf8',
+      timeout: 900000,
+    });
+    exitCode = res.status;
+    output = captureOutput(res);
+  } catch (e) {
+    output = 'spawn_error: ' + (e && e.message);
+  }
+  const durationMs = Date.now() - t0;
+  const commitAudit = auditTaskCommits(dest);
+  if (logger) logger.log(`[bench insession #${runIdx}] exit=${exitCode} duration=${durationMs}ms commits=${commitAudit.taskCommitCount}/${commitAudit.expectedTaskCount}`);
+  if (keepTmp && logger) logger.log(`  kept: ${tmpBase}`);
+  if (!keepTmp) cleanupRun(tmpBase);
+  return {
+    durationMs,
+    exitCode,
+    stderr: output,
+    tmpDir: keepTmp ? tmpBase : null,
+    commitAudit
+  };
+}
+
+function auditTaskCommits(workloadDir) {
+  const { spawnSync: ss } = require('child_process');
+  const res = ss('git', ['-C', workloadDir, 'log', '--pretty=%s'], { encoding: 'utf8' });
+  const subjects = String(res.stdout || '').split('\n').filter(Boolean);
+  const taskIdRe = /^bench-d\d+-t\d+[:\s]/;
+  const taskCommits = subjects.filter((s) => taskIdRe.test(s));
+  const uniqueTaskIds = new Set(taskCommits.map((s) => s.split(/[:\s]/)[0]));
+  const expectedTaskCount = 20;
+  return {
+    totalCommits: subjects.length,
+    taskCommitCount: taskCommits.length,
+    uniqueTaskIds: uniqueTaskIds.size,
+    expectedTaskCount,
+    discipline: uniqueTaskIds.size >= expectedTaskCount ? 'compliant' : 'noncompliant'
+  };
+}
+
+function collectEnv() {
+  return {
+    node: process.version,
+    platform: `${process.platform}-${os.release()}`,
+    arch: process.arch,
+    cpuCount: os.cpus().length,
+    totalMemMb: Math.round(os.totalmem() / (1024 * 1024)),
+    freeMemMb: Math.round(os.freemem() / (1024 * 1024)),
+  };
+}
+
+function renderReportMd(results) {
+  const lines = [];
+  lines.push('# M40 Speed Benchmark — Gate Verdict');
+  lines.push('');
+  lines.push(`- **Generated**: ${results.generatedAt}`);
+  lines.push(`- **Runs per side**: ${results.runs}`);
+  lines.push(`- **Fixture**: ${results.fixtureDir}`);
+  lines.push(`- **Verdict**: **${results.verdict}** — ${results.verdictDetail}`);
+  lines.push('');
+  lines.push('## Environment');
+  lines.push('');
+  lines.push(`- Node: ${results.env.node}`);
+  lines.push(`- Platform: ${results.env.platform} (${results.env.arch})`);
+  lines.push(`- CPUs: ${results.env.cpuCount}`);
+  lines.push(`- RAM: ${results.env.freeMemMb} MB free / ${results.env.totalMemMb} MB total`);
+  lines.push('');
+  lines.push('## Per-run timings (ms) and commit-discipline audit');
+  lines.push('');
+  lines.push('| # | Orchestrator (ms / exit / commits) | In-session (ms / exit / commits) |');
+  lines.push('|---|------------------------------------|----------------------------------|');
+  for (let i = 0; i < results.runs; i++) {
+    const o = results.orchestrator[i] || {};
+    const s = results.insession[i] || {};
+    const oc = o.commitAudit || {};
+    const sc = s.commitAudit || {};
+    const oCommits = `${oc.uniqueTaskIds ?? '—'}/${oc.expectedTaskCount ?? '—'}`;
+    const sCommits = `${sc.uniqueTaskIds ?? '—'}/${sc.expectedTaskCount ?? '—'}`;
+    lines.push(`| ${i + 1} | ${o.durationMs ?? '—'} / ${o.exitCode ?? '—'} / ${oCommits} | ${s.durationMs ?? '—'} / ${s.exitCode ?? '—'} / ${sCommits} |`);
+  }
+  lines.push('');
+  lines.push(`- **Median orchestrator**: ${results.summary.medianOrchMs} ms`);
+  lines.push(`- **Median in-session**:  ${results.summary.medianInsessionMs} ms`);
+  lines.push(`- **Threshold** (insession × ${PASS_TOLERANCE}): ${results.summary.thresholdMs} ms`);
+  lines.push('');
+  lines.push('## Methodology');
+  lines.push('');
+  lines.push('- Same fixture (`test/fixtures/m40-benchmark-workload/`) copied to a fresh');
+  lines.push('  tmp dir per run; git initialized; no cross-run state.');
+  lines.push('- Orchestrator path: `bin/gsd-t-orchestrator.js` drives waves via the');
+  lines.push('  D1 spawn loop + D2 brief builder.');
+  lines.push('- In-session path: a single `claude -p` session handed the tasks');
+  lines.push('  sequentially — no subagents.');
+  lines.push('- `Date.now()` wall-clock, millisecond precision. Both sides include');
+  lines.push('  their full lifecycle (startup + work + teardown).');
+  lines.push('- PASS when `median(orchestrator_ms) ≤ median(in-session_ms) × 1.05`.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function computeVerdict(orchTimings, insessionTimings) {
+  const orchOk = orchTimings.length && orchTimings.every((r) => r.exitCode === 0);
+  const insOk = insessionTimings.length && insessionTimings.every((r) => r.exitCode === 0);
+  const orchCompliant = orchTimings.every((r) => !r.commitAudit || r.commitAudit.discipline === 'compliant');
+  const insCompliant = insessionTimings.every((r) => !r.commitAudit || r.commitAudit.discipline === 'compliant');
+  const medianOrchMs = median(orchTimings.map((r) => r.durationMs));
+  const medianInsessionMs = median(insessionTimings.map((r) => r.durationMs));
+  const thresholdMs = Math.round(medianInsessionMs * PASS_TOLERANCE);
+  let verdict = 'FAIL';
+  let verdictDetail;
+  if (!orchOk || !insOk) {
+    verdictDetail = `one or more runs failed (orchestrator_ok=${orchOk}, insession_ok=${insOk}) — cannot trust comparison — M40 HALT RECOMMENDED`;
+  } else if (!orchCompliant || !insCompliant) {
+    verdict = 'INVALID';
+    verdictDetail = `commit-discipline audit failed (orchestrator_compliant=${orchCompliant}, insession_compliant=${insCompliant}) — one side did not produce one-commit-per-task; timing comparison is meaningless until both sides obey the same rules`;
+  } else if (medianOrchMs <= thresholdMs) {
+    verdict = 'PASS';
+    verdictDetail = `orchestrator ${medianOrchMs}ms ≤ in-session ${medianInsessionMs}ms × ${PASS_TOLERANCE} (${thresholdMs}ms) — Waves 2+3+4 unlocked`;
+  } else {
+    verdictDetail = `orchestrator ${medianOrchMs}ms > in-session ${medianInsessionMs}ms × ${PASS_TOLERANCE} (${thresholdMs}ms) — M40 HALT RECOMMENDED`;
+  }
+  return { verdict, verdictDetail, medianOrchMs, medianInsessionMs, thresholdMs, orchCompliant, insCompliant };
+}
+
+async function runBenchmark(opts) {
+  const {
+    runs,
+    fixtureDir,
+    mockClaude,
+    projectDir,
+    reportPath,
+    resultsPath,
+    keepTmp = false,
+    logger = console,
+    orchestratorImpl = runOrchestratorSide,
+    insessionImpl = runInsessionSide,
+  } = opts;
+
+  if (!fs.existsSync(fixtureDir)) {
+    throw new Error(`Fixture dir not found: ${fixtureDir}`);
+  }
+
+  const orchestrator = [];
+  const insession = [];
+  for (let i = 1; i <= runs; i++) {
+    orchestrator.push(orchestratorImpl({ fixtureDir, runIdx: i, mockClaude, logger, keepTmp }));
+    insession.push(insessionImpl({ fixtureDir, runIdx: i, mockClaude, logger, keepTmp }));
+  }
+
+  const summary = computeVerdict(orchestrator, insession);
+  const results = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    runs,
+    fixtureDir,
+    env: collectEnv(),
+    orchestrator,
+    insession,
+    summary,
+    verdict: summary.verdict,
+    verdictDetail: summary.verdictDetail,
+  };
+
+  const rp = resultsPath || path.join(projectDir, '.gsd-t', 'benchmark-results.json');
+  const rrp = reportPath || path.join(projectDir, 'docs', 'm40-benchmark-report.md');
+  fs.mkdirSync(path.dirname(rp), { recursive: true });
+  fs.mkdirSync(path.dirname(rrp), { recursive: true });
+  fs.writeFileSync(rp, JSON.stringify(results, null, 2));
+  fs.writeFileSync(rrp, renderReportMd(results));
+
+  const verdictLine = results.verdict === 'PASS'
+    ? `BENCHMARK: PASS — orchestrator ${summary.medianOrchMs}ms vs in-session ${summary.medianInsessionMs}ms — Waves 2+3+4 unlocked`
+    : `BENCHMARK: FAIL — orchestrator ${summary.medianOrchMs}ms vs in-session ${summary.medianInsessionMs}ms — M40 HALT RECOMMENDED`;
+  logger.log('');
+  logger.log(verdictLine);
+  logger.log(`  Results: ${rp}`);
+  logger.log(`  Report:  ${rrp}`);
+
+  return { results, resultsPath: rp, reportPath: rrp };
+}
+
+async function main() {
+  let args;
+  try { args = parseCliArgs(process.argv.slice(2)); }
+  catch (e) { process.stderr.write(`Error: ${e.message}\n\n`); printHelp(); process.exit(2); }
+  if (args.help) { printHelp(); process.exit(0); }
+
+  try {
+    const { results } = await runBenchmark(args);
+    process.exit(results.verdict === 'PASS' ? 0 : 1);
+  } catch (e) {
+    process.stderr.write(`benchmark-orchestrator failed: ${e && e.message}\n`);
+    if (e && e.stack) process.stderr.write(e.stack + '\n');
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parseCliArgs,
+  median,
+  copyDirSync,
+  gitInitRepo,
+  prepareRun,
+  cleanupRun,
+  collectEnv,
+  renderReportMd,
+  computeVerdict,
+  runOrchestratorSide,
+  runInsessionSide,
+  runBenchmark,
+  PASS_TOLERANCE,
+};