@tekyzinc/gsd-t 3.23.11 → 3.25.10

package/bin/parallel-cli.cjs

@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GSD-T parallel-cli substrate (M55 D2)
+ *
+ * N-worker pool runner. Every worker spawn flows through
+ * `bin/gsd-t-token-capture.cjs::captureSpawn`. Per-worker tee log streams
+ * via `bin/parallel-cli-tee.cjs`. Lifecycle / per-worker timeout / fail-fast
+ * policy.
+ *
+ * Engine-only — does NOT touch any command file in M55.
+ *
+ * Contract: .gsd-t/contracts/parallel-cli-contract.md v1.0.0 STABLE.
+ *
+ * Hard rules:
+ *   1. Zero external runtime deps. Only Node built-ins + sibling D2 helper.
+ *   2. NEVER call child_process.spawn directly outside `_makeSpawnFn`.
+ *   3. Every spawn flows through captureSpawn (the wrapper logs the row).
+ *   4. results[] sorted by id ASC. Sort runs AFTER all workers complete.
+ *   5. wallClockMs = orchestrator real time, NOT cumulative worker time.
+ *   6. Fail-fast: SIGTERM in-flight, escalate SIGKILL after 5s grace.
+ */
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { captureSpawn } = require('./gsd-t-token-capture.cjs');
+const { attachTee, VALID_ID_RE } = require('./parallel-cli-tee.cjs');
+
+const SCHEMA_VERSION = '1.0.0';
+const SIGKILL_GRACE_MS = 5000;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * @param {object} opts
+ * @param {Array<object>} opts.workers
+ * @param {number} opts.maxConcurrency
+ * @param {boolean} [opts.failFast=false]
+ * @param {string} [opts.teeDir]
+ * @param {string} [opts.projectDir]
+ * @param {string} [opts.command='parallel-cli']
+ * @param {string} [opts.step='parallel']
+ * @param {string} [opts.domain='-']
+ * @param {string} [opts.task='-']
+ * @returns {Promise<object>}  envelope per contract
+ */
+async function runParallel(opts) {
+  _validateOpts(opts);
+
+  const workers = opts.workers;
+  const maxConcurrency = opts.maxConcurrency;
+  const failFast = !!opts.failFast;
+  const teeDir = opts.teeDir || null;
+  const projectDir = opts.projectDir || process.cwd();
+  const command = opts.command || 'parallel-cli';
+  const step = opts.step || 'parallel';
+  const domain = opts.domain || '-';
+  const task = opts.task || '-';
+
+  const notes = [];
+  const orchestratorStart = process.hrtime.bigint();
+
+  // Shared cancellation flag (fail-fast). Children registered for cancel.
+  const inFlight = new Map(); // workerId → child handle
+  const failFastTriggered = { value: false };
+
+  // Rolling pool: walk workers in declaration order, but throttle to maxConcurrency.
+  const pending = workers.slice();
+  const running = [];
+  const results = [];
+
+  while (pending.length > 0 || running.length > 0) {
+    // Once failFast trips, do not start any new workers — drain only.
+    if (failFast && failFastTriggered.value) {
+      pending.length = 0;
+    }
+    while (running.length < maxConcurrency && pending.length > 0) {
+      const w = pending.shift();
+      const p = _runOneWorker({
+        worker: w,
+        teeDir,
+        projectDir,
+        command,
+        step,
+        domain,
+        task,
+        inFlight,
+        failFastTriggered,
+        failFast,
+      })
+        .then((r) => ({ workerId: w.id, result: r }))
+        .catch((err) => ({
+          workerId: w.id,
+          result: _errorResult(w.id, err),
+        }));
+      running.push(p);
+
+      // If failFast, attach a callback to trigger cancel-siblings on first failure.
+      p.then(({ result }) => {
+        if (failFast && !failFastTriggered.value && result && result.ok === false && !result.cancelled) {
+          failFastTriggered.value = true;
+          for (const [otherId, child] of inFlight.entries()) {
+            if (otherId === result.id) continue;
+            _terminateChild(child);
+          }
+        }
+      }).catch(() => { /* swallowed; result already shaped */ });
+    }
+
+    // Wait for the next worker to finish — Promise.race over current `running`.
+    const settled = await Promise.race(running.map((p, idx) => p.then((v) => ({ idx, v }))));
+    running.splice(settled.idx, 1);
+    results.push(settled.v.result);
+  }
+
+  // Deterministic sort by id ASC, AFTER all workers complete.
+  results.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  notes.sort();
+
+  const orchestratorEnd = process.hrtime.bigint();
+  const wallClockMs = Math.round(Number(orchestratorEnd - orchestratorStart) / 1e6);
+
+  const ok = !results.some((r) => r.ok === false);
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    ok,
+    wallClockMs,
+    maxConcurrencyApplied: maxConcurrency,
+    failFast,
+    results,
+    notes,
+  };
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+function _validateOpts(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('runParallel: opts is required');
+  }
+  if (!Array.isArray(opts.workers) || opts.workers.length === 0) {
+    throw new Error('runParallel: opts.workers must be a non-empty array');
+  }
+  if (!Number.isInteger(opts.maxConcurrency) || opts.maxConcurrency < 1) {
+    throw new Error('runParallel: opts.maxConcurrency must be a positive integer');
+  }
+  const seen = new Set();
+  for (const w of opts.workers) {
+    if (!w || typeof w !== 'object') {
+      throw new Error('runParallel: every worker must be an object');
+    }
+    if (typeof w.id !== 'string' || w.id === '') {
+      throw new Error('runParallel: worker.id is required and must be a non-empty string');
+    }
+    if (!VALID_ID_RE.test(w.id)) {
+      throw new Error('runParallel: worker.id contains illegal characters: ' + w.id);
+    }
+    if (seen.has(w.id)) {
+      throw new Error('runParallel: duplicate worker.id: ' + w.id);
+    }
+    seen.add(w.id);
+    if (typeof w.cmd !== 'string' || w.cmd === '') {
+      throw new Error('runParallel: worker.cmd is required (worker ' + w.id + ')');
+    }
+    if (!Array.isArray(w.args)) {
+      throw new Error('runParallel: worker.args must be an array (worker ' + w.id + ')');
+    }
+    if (w.timeoutMs != null && (!Number.isFinite(w.timeoutMs) || w.timeoutMs <= 0)) {
+      throw new Error('runParallel: worker.timeoutMs must be a positive finite number or null (worker ' + w.id + ')');
+    }
+  }
+}
+
+// ── Per-worker run ──────────────────────────────────────────────────────────
+
+async function _runOneWorker(ctx) {
+  const w = ctx.worker;
+  const startNs = process.hrtime.bigint();
+
+  // captureSpawn-wrapped. spawnFn wires the actual child_process.spawn.
+  const wrapped = await captureSpawn({
+    command: ctx.command,
+    step: ctx.step,
+    model: w.model || 'cli',
+    description: w.description || w.id,
+    projectDir: ctx.projectDir,
+    domain: ctx.domain,
+    task: ctx.task,
+    spawnFn: () => _makeSpawnFn({
+      worker: w,
+      teeDir: ctx.teeDir,
+      projectDir: ctx.projectDir,
+      inFlight: ctx.inFlight,
+      failFastTriggered: ctx.failFastTriggered,
+    })(),
+    notes: 'parallel-cli worker',
+  });
+
+  const endNs = process.hrtime.bigint();
+  const durationMs = Math.round(Number(endNs - startNs) / 1e6);
+
+  // captureSpawn returns { result, usage, rowWritten }; we tunneled our
+  // structured result through `result`.
+  const r = wrapped.result || {};
+  return {
+    id: w.id,
+    ok: r.exitCode === 0 && !r.cancelled && !r.timedOut && r.signal == null,
+    exitCode: typeof r.exitCode === 'number' ? r.exitCode : null,
+    signal: r.signal || null,
+    durationMs,
+    stdoutPath: r.stdoutPath || null,
+    stderrPath: r.stderrPath || null,
+    stdoutBytes: typeof r.stdoutBytes === 'number' ? r.stdoutBytes : 0,
+    stderrBytes: typeof r.stderrBytes === 'number' ? r.stderrBytes : 0,
+    stdoutTruncatedToTemp: !!r.stdoutTruncatedToTemp,
+    stderrTruncatedToTemp: !!r.stderrTruncatedToTemp,
+    timedOut: !!r.timedOut,
+    cancelled: !!r.cancelled,
+  };
+}
+
+function _errorResult(id, err) {
+  return {
+    id,
+    ok: false,
+    exitCode: null,
+    signal: null,
+    durationMs: 0,
+    stdoutPath: null,
+    stderrPath: null,
+    stdoutBytes: 0,
+    stderrBytes: 0,
+    stdoutTruncatedToTemp: false,
+    stderrTruncatedToTemp: false,
+    timedOut: false,
+    cancelled: false,
+    error: err && err.message ? err.message : String(err),
+  };
+}
+
+// ── Spawn factory ───────────────────────────────────────────────────────────
+
+function _makeSpawnFn(ctx) {
+  const w = ctx.worker;
+  return function spawnAndWait() {
+    return new Promise((resolve) => {
+      const child = spawn(w.cmd, w.args || [], {
+        cwd: w.cwd || ctx.projectDir,
+        env: { ...process.env, ...(w.env || {}) },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell: false,
+      });
+
+      const tee = attachTee(child, { workerId: w.id, teeDir: ctx.teeDir });
+
+      let timedOut = false;
+      let cancelled = false;
+      let timeoutTimer = null;
+      let killTimer = null;
+
+      // Attach cancel hook BEFORE inFlight registration so the orchestrator
+      // never observes a child without its hook.
+      child.__pcli_cancel = () => {
+        if (cancelled) return;
+        cancelled = true;
+        _killChild(child, killTimer);
+      };
+      ctx.inFlight.set(w.id, child);
+
+      if (Number.isFinite(w.timeoutMs) && w.timeoutMs > 0) {
+        timeoutTimer = setTimeout(() => {
+          timedOut = true;
+          cancelled = true;
+          _killChild(child, killTimer);
+        }, w.timeoutMs);
+      }
+
+      child.on('close', async (code, signal) => {
+        if (timeoutTimer) clearTimeout(timeoutTimer);
+        if (killTimer) clearTimeout(killTimer);
+        ctx.inFlight.delete(w.id);
+        await tee.close();
+        // captureSpawn does not consume `usage` from this object (no `usage`
+        // field present), so the token-log row will render `—`.
+        resolve({
+          exitCode: typeof code === 'number' ? code : null,
+          signal: signal || null,
+          stdoutPath: tee.stdoutPath,
+          stderrPath: tee.stderrPath,
+          stdoutBytes: tee.stdoutBytes(),
+          stderrBytes: tee.stderrBytes(),
+          stdoutTruncatedToTemp: tee.stdoutTruncatedToTemp(),
+          stderrTruncatedToTemp: tee.stderrTruncatedToTemp(),
+          timedOut,
+          cancelled,
+        });
+      });
+
+      child.on('error', async (err) => {
+        if (timeoutTimer) clearTimeout(timeoutTimer);
+        if (killTimer) clearTimeout(killTimer);
+        ctx.inFlight.delete(w.id);
+        await tee.close();
+        resolve({
+          exitCode: null,
+          signal: null,
+          stdoutPath: tee.stdoutPath,
+          stderrPath: tee.stderrPath,
+          stdoutBytes: tee.stdoutBytes(),
+          stderrBytes: tee.stderrBytes(),
+          stdoutTruncatedToTemp: tee.stdoutTruncatedToTemp(),
+          stderrTruncatedToTemp: tee.stderrTruncatedToTemp(),
+          timedOut,
+          cancelled,
+          error: err && err.message ? err.message : String(err),
+        });
+      });
+    });
+  };
+}
+
+function _killChild(child, killTimer) {
+  if (!child) return;
+  try { child.kill('SIGTERM'); } catch (_) { /* may be dead already */ }
+  if (!killTimer) {
+    setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch (_) { /* may be dead already */ }
+    }, SIGKILL_GRACE_MS).unref?.();
+  }
+}
+
+function _terminateChild(child) {
+  if (!child || typeof child.__pcli_cancel !== 'function') return;
+  child.__pcli_cancel();
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+function _parseCliArgs(argv) {
+  const out = {
+    plan: null,
+    maxConcurrency: null,
+    failFast: false,
+    teeDir: null,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--plan') out.plan = argv[++i];
+    else if (a === '--max-concurrency') out.maxConcurrency = parseInt(argv[++i], 10);
+    else if (a === '--fail-fast') out.failFast = true;
+    else if (a === '--tee-dir') out.teeDir = argv[++i];
+    else if (a === '--json') out.json = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+    else throw new Error('unknown flag: ' + a);
+  }
+  return out;
+}
+
+function _readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+async function _cliMain(argv) {
+  let parsed;
+  try {
+    parsed = _parseCliArgs(argv);
+  } catch (e) {
+    process.stderr.write('parallel-cli: ' + e.message + '\n');
+    process.exit(2);
+  }
+
+  if (parsed.help) {
+    process.stdout.write([
+      'Usage: node bin/parallel-cli.cjs --max-concurrency N [--plan FILE] [--fail-fast] [--tee-dir DIR] [--json]',
+      '',
+      'Reads worker plan from --plan FILE or stdin. Plan shape:',
+      '  { "workers": [ { "id": "lint", "cmd": "npx", "args": ["biome","check"] }, ... ] }',
+      '',
+    ].join('\n'));
+    process.exit(0);
+  }
+
+  if (!Number.isInteger(parsed.maxConcurrency) || parsed.maxConcurrency < 1) {
+    process.stderr.write('parallel-cli: --max-concurrency is required (positive integer)\n');
+    process.exit(2);
+  }
+
+  let planText;
+  try {
+    if (parsed.plan) {
+      planText = fs.readFileSync(parsed.plan, 'utf8');
+    } else {
+      planText = await _readStdin();
+    }
+  } catch (e) {
+    process.stderr.write('parallel-cli: cannot read plan: ' + e.message + '\n');
+    process.exit(2);
+  }
+
+  let plan;
+  try {
+    plan = JSON.parse(planText);
+  } catch (e) {
+    process.stderr.write('parallel-cli: plan JSON parse error: ' + e.message + '\n');
+    process.exit(2);
+  }
+  if (!plan || !Array.isArray(plan.workers)) {
+    process.stderr.write('parallel-cli: plan.workers must be an array\n');
+    process.exit(2);
+  }
+
+  let envelope;
+  try {
+    envelope = await runParallel({
+      workers: plan.workers,
+      maxConcurrency: parsed.maxConcurrency,
+      failFast: parsed.failFast,
+      teeDir: parsed.teeDir,
+      command: 'parallel-cli',
+      step: 'cli',
+    });
+  } catch (e) {
+    process.stderr.write('parallel-cli: runtime error: ' + (e && e.stack || e) + '\n');
+    process.exit(3);
+  }
+
+  if (parsed.json) {
+    process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+  } else {
+    process.stdout.write(_renderText(envelope));
+  }
+  process.exit(envelope.ok ? 0 : 1);
+}
+
+function _renderText(envelope) {
+  const lines = [];
+  lines.push('parallel-cli: ' + (envelope.ok ? 'OK' : 'FAIL') +
+             '  (workers=' + envelope.results.length +
+             ', maxConcurrency=' + envelope.maxConcurrencyApplied +
+             ', wallClockMs=' + envelope.wallClockMs + ')');
+  for (const r of envelope.results) {
+    const tag = r.ok ? '✓' : '✗';
+    lines.push('  ' + tag + ' ' + r.id +
+               ' exit=' + r.exitCode +
+               ' sig=' + r.signal +
+               ' ' + r.durationMs + 'ms' +
+               (r.timedOut ? ' [TIMEOUT]' : '') +
+               (r.cancelled ? ' [CANCELLED]' : ''));
+  }
+  return lines.join('\n') + '\n';
+}
+
+if (require.main === module) {
+  _cliMain(process.argv.slice(2)).catch((e) => {
+    process.stderr.write('parallel-cli: unhandled: ' + (e && e.stack || e) + '\n');
+    process.exit(3);
+  });
+}
+
+module.exports = {
+  runParallel,
+  SCHEMA_VERSION,
+  SIGKILL_GRACE_MS,
+  // exposed for tests
+  _validateOpts,
+  _renderText,
+};

package/commands/gsd-t-execute.md

@@ -84,6 +84,37 @@ Identify:
 - Which tasks are unblocked (no pending dependencies)
 - Which tasks are blocked (waiting on checkpoints)
 
+<!-- M55-D5: preflight + brief wire-in -->
+**M55 Preflight + Context-Brief (mandatory before fan-out):**
+
+Once per execute invocation, before spawning ANY worker subagent:
+
+1. Run state preflight:
+   ```bash
+   gsd-t preflight --json > /tmp/gsd-t-preflight.json || true
+   ```
+   If exit code is `4`, STOP. Read `/tmp/gsd-t-preflight.json`, surface the failed
+   `severity:"error"` checks (wrong branch, occupied port, etc.) to the user, and
+   do NOT spawn any workers. The verify-gate (Track 1) will hard-fail the same
+   way at verify time — fail-early here saves the round-trip.
+
+2. For each domain `D` about to receive a worker spawn, generate a context brief
+   ONCE per domain per spawn (replaces 30–60k context re-read with ≤2,500-token
+   JSON snapshot — M55 charter Pattern B):
+   ```bash
+   SPAWN_ID="execute-${D}-$(date -u +%Y%m%dT%H%M%SZ)"
+   gsd-t brief --kind execute --domain "${D}" --spawn-id "${SPAWN_ID}" --out ".gsd-t/briefs/${SPAWN_ID}.json"
+   export BRIEF_PATH=".gsd-t/briefs/${SPAWN_ID}.json"
+   ```
+
+3. Pass `$BRIEF_PATH` into each worker's prompt scaffold so the worker greps the
+   brief instead of re-walking the repo. Workers receive the canonical
+   instruction "check the brief first" via the subagent protocols
+   (`templates/prompts/{qa,red-team,design-verify}-subagent.md`).
+
+The `.gsd-t/briefs/` directory is gitignored — briefs are per-spawn ephemera,
+not committed artifacts.
+
 ## Step 1.5: Graph-Enhanced Domain Isolation Check (if available)
 
 ```bash

package/commands/gsd-t-help.md

@@ -434,6 +434,27 @@ Use these when user asks for help on a specific command:
 - **Files**: `.gsd-t/backlog-settings.md`
 - **Use when**: Customizing the classification dimensions for your project
 
+### preflight (M55)
+- **Summary**: Deterministic state-precondition check (`bin/cli-preflight.cjs`); 6 built-in checks (branch-guard, contracts-stable, deps-installed, manifest-fresh, ports-free, working-tree-state). Exit 0/4. Pluggable, zero-dep, captureSpawn-exempt.
+- **Auto-invoked**: Yes — by `gsd-t-execute` Step 1 and `gsd-t verify-gate` Track 1
+- **Files**: `bin/cli-preflight.cjs`, `bin/cli-preflight-checks/`
+- **Use when**: Before any worker spawn or verify run — catches drift (wrong branch, port collision, DRAFT contracts) early.
+- **CLI**: `gsd-t preflight [--project DIR] [--json | --text] [--skip id1,id2]`
+
+### brief (M55)
+- **Summary**: Generate a ≤10 KB / ≤2,500-token context brief for a worker spawn (`bin/gsd-t-context-brief.cjs`); 6 kinds (`execute`, `verify`, `qa`, `red-team`, `design-verify`, `scan`). Replaces 30–60k context re-read with structured JSON snapshot.
+- **Auto-invoked**: Yes — by `gsd-t-execute` Step 1 (one brief per domain spawn)
+- **Files**: `bin/gsd-t-context-brief.cjs`, `bin/gsd-t-context-brief-kinds/`, `.gsd-t/briefs/` (gitignored)
+- **Use when**: Replacing repo re-reads with a structured snapshot for parallel workers.
+- **CLI**: `gsd-t brief --kind X --domain Y --spawn-id Z [--out PATH] [--strict]`
+
+### verify-gate (M55)
+- **Summary**: Two-track verify-gate (`bin/gsd-t-verify-gate.cjs`); Track 1 runs preflight (hard-fail on severity:error), Track 2 fans out tsc/lint/tests/dead-code/secrets/complexity via `bin/parallel-cli.cjs::runParallel`. Returns ≤500-token JSON summary an LLM judges. Defensive on missing `.gsd-t/ratelimit-map.json`.
+- **Auto-invoked**: Yes — by `gsd-t-verify` Step 2
+- **Files**: `bin/gsd-t-verify-gate.cjs`, `bin/gsd-t-verify-gate-judge.cjs`
+- **Use when**: Final pre-merge gate. Both tracks always run; both report. `ok` is purely deterministic — LLM verdict is advisory.
+- **CLI**: `gsd-t verify-gate [--skip-track1] [--skip-track2] [--max-concurrency N] [--fail-fast] [--json]`. Exit 0/4/2/3.
+
 ## Unknown Command
 
 If user asks for help on unrecognized command:

package/commands/gsd-t-verify.md

@@ -64,6 +64,44 @@ Run the full test audit directly:
 
 Verification cannot complete if any test fails or critical contract gaps remain.
 
+<!-- M55-D5: verify-gate wire-in -->
+**M55 Verify-Gate (mandatory two-track gate):**
+
+Before finalizing the verify report, invoke the M55 verify-gate. It runs Track 1
+(`bin/cli-preflight.cjs::runPreflight` — preflight envelope; hard-fails on any
+`severity:"error"` check) AND Track 2 (`bin/parallel-cli.cjs::runParallel` fans
+out off-the-shelf CLIs: tsc, biome/ruff, npm test, knip, gitleaks, scc/lizard).
+Both tracks always run; both report. The gate's `ok` flag is purely
+deterministic (`track1.ok && track2.ok`) — the LLM judge's verdict is advisory.
+
+```bash
+gsd-t verify-gate --json > /tmp/gsd-t-verify-gate.json || true
+GATE_OK=$(node -e "const e=require('/tmp/gsd-t-verify-gate.json');console.log(e.ok?'true':'false')")
+```
+
+If `GATE_OK=false`, surface the failed track to the user and do NOT mark verify
+complete. The summary in the envelope is ≤500 tokens — pipe it to the LLM judge
+for a confirming verdict:
+
+```bash
+cat /tmp/gsd-t-verify-gate.json | gsd-t verify-gate-judge > /tmp/gsd-t-verify-gate-prompt.txt
+```
+
+The judge prompt (`bin/gsd-t-verify-gate-judge.cjs`) is ≤500 tokens regardless
+of envelope size — feed it to the LLM judge to render a `PASS` / `FAIL` verdict
+on the deterministic summary. The LLM verdict NEVER overrides `ok` — it
+confirms or contradicts. A contradiction is a Red Team finding, not a gate
+override.
+
+Raw worker output stays at `.gsd-t/verify-gate/{runId}/{workerId}.{stdout,stderr}.ndjson`
+for human-only inspection. The directory is gitignored.
+
+Defensive on missing `.gsd-t/ratelimit-map.json` — verify-gate falls back to
+`maxConcurrency=2` and logs a structured note. Override with
+`gsd-t verify-gate --max-concurrency N --json` if needed.
+
+Contract: `.gsd-t/contracts/verify-gate-contract.md` v1.0.0 STABLE.
+
 ## Step 2.5: High-Risk Domain Gate (MANDATORY — Categories 2 and 7)
 
 ```bash