@tekyzinc/gsd-t 3.24.10 → 3.25.11

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.25.11] - 2026-05-09
+
+### Fixed — M55 propagation gaps + misleading update-all status
+
+Three small fixes to `bin/gsd-t.js`, all caught immediately post-v3.25.10 ship by the user noticing "18 already current" couldn't possibly be right one minute after publish.
+
+- **Patch 1**: Added `parallel-cli.cjs` to `GLOBAL_BIN_TOOLS`. M55 D5 wired 4 of 5 new substrate binaries into the global propagation list (`cli-preflight`, `gsd-t-context-brief`, `gsd-t-verify-gate`, `gsd-t-verify-gate-judge`) but missed `parallel-cli.cjs` — the substrate engine itself. Result: `~/.claude/bin/parallel-cli.cjs` was missing on every install. Now propagates.
+- **Patch 2**: Added 6 M55 binaries to `PROJECT_BIN_TOOLS` (`cli-preflight.cjs`, `parallel-cli.cjs`, `parallel-cli-tee.cjs`, `gsd-t-context-brief.cjs`, `gsd-t-verify-gate.cjs`, `gsd-t-verify-gate-judge.cjs`). M55 D5 only added them to the global tier — projects had to reach for the global CLI for every M55 dispatch. Now they're available locally per-project too, enabling `node bin/cli-preflight.cjs` style invocations from project workflows. Each registered project gets these copied on the next `gsd-t update-all`.
+- **Patch 3**: Replaced `"X — already up to date"` with `"X — no migrations needed (CLAUDE.md guard, CHANGELOG, bin tools, unattended config all current)"` in `updateSingleProject`. The previous string falsely implied the project was at the latest GSD-T version, but the function only checks 7 specific migration ops — a project showing "already up to date" was just one whose 7 migrations had already run, not one running v3.25.10. Honest message now explains what was actually checked.
+- **Tests**: 2487 / 2487 pass clean (zero regressions).
+- **Why a same-day patch and not a defer**: M55's whole point is making the new substrate available for M56 to wire into Quick + Debug + upper-stage commands. Shipping with the binaries half-propagated would force M56 to wait on a propagation fix anyway. Better to land the fix now and have a clean foundation.
+
+## [3.25.10] - 2026-05-09
+
+### Added — M55 CLI-Preflight Pattern + Parallel-CLI Substrate + Rate-Limit Map + Context Briefs + Verify-Gate (minor: new feature milestone)
+
+- **Goal**: lift the practical parallelism ceiling from ~3 LLM workers to ~6–10 mixed workers (1 LLM judge + N CLIs) by replacing deterministic LLM work with deterministic CLI work, AND gate every spawn with deterministic state-precondition checks. Two pain points addressed in one ship: (a) silent-skip regressions caught only by retrofit hooks (M48/M49/M50/M52 pattern); (b) undocumented Claude ITPM ceiling at ~3 parallel workers because every worker re-loaded ~60k context within the same 60s window.
+- **Scope**: 5 file-disjoint domains, single supervisor-driven build (5 worker iterations).
+  - **D1 m55-d1-state-precondition-library** — `bin/cli-preflight.cjs` + 6 pluggable checks under `bin/cli-preflight-checks/` (`branch-guard`, `ports-free`, `deps-installed`, `contracts-stable`, `manifest-fresh`, `working-tree-state`) returning deterministic `{ok, checks[], notes[]}` envelope. Schema-versioned, zero deps, mirroring `bin/parallelism-report.cjs`. STABLE contract `cli-preflight-contract.md` v1.0.0. Commit `bb514db`.
+  - **D2 m55-d2-parallel-cli-substrate** — `bin/parallel-cli.cjs` N-worker pool engine (`runParallel`), `bin/parallel-cli-tee.cjs` NDJSON tee, `bin/m55-substrate-proof.cjs` proof CLI. Every worker spawn flows through `bin/gsd-t-token-capture.cjs::captureSpawn` (token-capture invariant). Engine-only — does NOT touch command files yet. STABLE contract `parallel-cli-contract.md` v1.0.0. Commit `7b9e013`.
+  - **D3 m55-d3-ratelimit-probe-map** — `bin/gsd-t-ratelimit-probe.cjs` + `bin/gsd-t-ratelimit-probe-worker.cjs` synthetic-worker harness, 4 fixtures, populated `.gsd-t/ratelimit-map.json` artifact. STABLE contract `ratelimit-map-contract.md` v1.0.0. Commit `a0bef17`. **Note**: the original D3 sweep used Haiku and a synthetic Lorem-Ipsum fixture; post-milestone re-probes with Opus + Sonnet on real-prose fixtures (logged in `.gsd-t/m55-cliff-claude-sonnet-4-6.json` and partial `.gsd-t/m55-cliff-claude-opus-4-7-v4.json`) confirmed Sonnet ≥11 parallel workers without cliff and Opus ≥7 confirmed clean (full ramp interrupted by power outage + plan usage cap; cliff above 7 not yet located).
+  - **D4 m55-d4-context-brief-generator** — `bin/gsd-t-context-brief.cjs` + 6 brief kinds (`design-verify`, `execute`, `qa`, `red-team`, `scan`, `verify`) under `bin/gsd-t-context-brief-kinds/`. Produces `.gsd-t/briefs/{spawn-id}.json` (~2k JSON snapshot) replacing 30–60k context re-read per parallel worker — the dominant ITPM-relief lever. STABLE contract `context-brief-contract.md` v1.0.0. Commit `998f373`.
+  - **D5 m55-d5-verify-gate-and-wirein** — `bin/gsd-t-verify-gate.cjs` two-track gate (Track 1 consumes D1 envelope, hard-fails on `severity:error`; Track 2 fans out via D2 substrate across tsc/lint/tests/dead-code/secrets/complexity) + `bin/gsd-t-verify-gate-judge.cjs` ≤500-token LLM prompt scaffold (iterative shrink, deterministic). STABLE contract `verify-gate-contract.md` v1.0.0. Commit `b916d77`.
+- **Wire-ins** (D5):
+  - `bin/gsd-t.js` — 4 dispatch subcommands (`preflight`, `brief`, `verify-gate`, `verify-gate-judge`), all 4 added to `GLOBAL_BIN_TOOLS` for `~/.claude/bin/` propagation.
+  - `commands/gsd-t-execute.md` Step 1 — additive `<!-- M55-D5: preflight + brief wire-in -->` block running preflight + generating brief, threading `$BRIEF_PATH` into worker prompts.
+  - `commands/gsd-t-verify.md` Step 2 — additive `<!-- M55-D5: verify-gate wire-in -->` block invoking verify-gate + piping into judge.
+  - `templates/prompts/{qa,red-team,design-verify}-subagent.md` — additive `<!-- M55-D5: brief-first rule -->` line in each.
+- **Doc ripple**: `docs/architecture.md` (new "CLI-Preflight Pattern + Verify-Gate (M55)" section), `docs/requirements.md` (REQ-M55-D1..D5 + REQ-M55-VERIFY all `done`), `CLAUDE.md` project (Mandatory Preflight + Brief-First Worker Rule), `commands/gsd-t-help.md` (3 new entries), `README.md` (CLI table M55 block), `templates/CLAUDE-global.md` (Mandatory Preflight + Brief-First + Two-Track Verify-Gate after Token Capture Rule), `~/.claude/CLAUDE.md` Pre-Commit Gate addition. `.gitignore` additions: `.gsd-t/verify-gate/` (D5 raw worker output retention).
+- **Tests**: 161 new across D1–D5. Suite total **2487 / 2485 pass**, 2 pre-existing documented env-bleed failures (`event-stream.test.js` GSD_T_COMMAND leak + `watch-progress-writer.test.js` supervisor-iter id-pattern leak — unchanged from M50/M52/M54 baselines, induced by running tests inside an unattended worker session, not by M55 code). **Zero regressions.**
+- **Adversarial Red Team** (post-wave): 6/6 broken patches authored, applied, caught by tests, reverted. P1 `preflight-skip-on-error` (D1), P2 `parallel-substrate-bypasses-capture` (D2), P3 `verify-gate-falsy-true` (D5), P4 `branch-guard-typo` (D1), P5 `contract-staleness-ignored` (D1), P6 `brief-staleness-ignored` (D4) — all caught by named tests with collateral catches in 4 of 6. **VERDICT: GRUDGING PASS** — production code unchanged. Findings in `.gsd-t/red-team-report.md` § "M55 RED TEAM". Commit `fce2f18`.
+- **Falsifiable success criteria** (per `feedback_measure_dont_claim.md`):
+  - **SC1 ✅** state-preflight contract `cli-preflight-contract.md` v1.0.0 STABLE published.
+  - **SC2 ✅** substrate proves **5.57× speedup** on real fan-out scenario via `bin/m55-substrate-proof.cjs` (T_serial=1813.3ms vs T_par=325.6ms, parallelism_factor=4.61, threshold ≥3.0× — PASS).
+  - **SC3 ✅** verify-gate blocks **3 distinct preflight failure classes** in `e2e/journeys/`: wrong-branch, port-conflict, contract-draft. All 3 mapped in `.gsd-t/journey-manifest.json`; `gsd-t check-coverage` reports `OK: 21 listeners, 19 specs` exit 0.
+  - **SC4 ⚠️ DEFERRED-BY-INSTRUMENTATION-GAP** — token-log.md captured only 2 supervisor-iter-level rows for M55 with no token cells populated. Trailing-3 milestones M50/M52/M54 show similarly sparse coverage with no per-milestone totals in comparable units. Run.log envelopes recorded $25 supervisor cost across 5 iters + $14.92 Red Team iter, establishing the new baseline going forward. The token-capture invariant M55 introduces (Pattern A `captureSpawn` + Pattern B `recordSpawnRow`) is the *fix* for this gap — M56 will be the first comparable measurement. SC4 is *unmeasurable from historical data*, not *failed*. Tagging proceeds with the gap explicitly documented; M56's first execute+verify cycle will close it retroactively.
+  - **SC5 ✅** zero 429 errors at parallelism level D3 declared safe — original D3 sweep showed 0/84 429s at peak 8 (Haiku). Post-milestone re-probes with corrected classifier (`stop_reason`/`is_error`/`api_error_status` from API envelope, not regex on stderr): **Sonnet 11/11 success at N=11** (clean v3 run, no cliff observed); **Opus 7/7 success at N=7** (partial v4 run, full ramp interrupted by power outage at 18:30 PDT and plan usage cap at 18:39 PDT — cliff above 7 not yet located). `.gsd-t/ratelimit-map.json::recommended.peakConcurrency` updated 8→**12**, `safeConcurrencyAt60kContext` updated 5→**11**, per documented Sonnet evidence + Opus partial evidence.
+  - **SC6 ✅** verify-gate dogfood wall-clock **34s** vs trailing-3 verify median 681s (M50=480s, M52=882s; M52 cron-chain=0s discounted as incomplete). 34s ≤ ½ × 681s = 340s threshold met with **20× margin**. Track 1 all 6 state-preflight checks ok; Track 2 parallel CLI fan-out all workers ok; verdict PASS.
+  - **SC7 ✅** Red Team GRUDGING PASS — 6/6 broken patches caught (≥5 target exceeded), 0 real bugs.
+  - **SC8 ✅** zero regressions on `npm test` — 2487 / 2485 pass, 2 pre-existing documented env-bleed failures unchanged.
+- **Versioning**: minor bump per "new feature milestone" doctrine. Tag `v3.25.10` (local).
+- **Followup**: M56 confirmed (per user 2026-05-09 18:54 PDT) — Verify-Gate CLI Fan-Out + Upper-Stage Briefs. D1: Add Playwright + npm-test + check-coverage as native verify-gate Track 2 CLIs (no Task subagent wrapper). D2: Extend `gsd-t-context-brief.cjs` with 5 new kinds (partition, plan, discuss, impact, milestone). D3: Wire briefs into corresponding command files. Falsifiable: M56 verify wall-clock < M55's 34s; first-of-milestone context brief shaves 30–60k from each subsequent phase's read-budget.
+
 ## [3.24.10] - 2026-05-07
 
 ### Added — M54 Live Activity Visibility (minor: new feature milestone)

package/README.md

@@ -112,6 +112,13 @@ gsd-t parallel --dry-run                                # Print worker plan tabl
 gsd-t parallel --mode in-session --dry-run              # 85% orchestrator-CW ceiling; N=1 floor
 gsd-t parallel --mode unattended --dry-run              # 60% per-worker ceiling; > 60% → task_split
 gsd-t parallel --milestone M44 --domain m44-d2-parallel-cli --dry-run
+
+# CLI-Preflight + Brief + Verify-Gate (M55 — deterministic state checks + parallel substrate)
+gsd-t preflight --json                                  # 6 built-in state checks; exit 0/4
+gsd-t brief --kind execute --domain X --spawn-id Y      # ≤2,500-token JSON snapshot for worker spawn
+gsd-t verify-gate --json                                # Two-track gate: D1 preflight + D2 parallel CLIs
+gsd-t verify-gate --skip-track1 --json                  # Diagnostic: Track 2 only
+gsd-t verify-gate --max-concurrency 4 --json            # Override D3-map default
 ```
 
 `gsd-t parallel` consumes the M44 task-graph (D1) and applies three pre-spawn gates (D4 depgraph validation → D5 file-disjointness → D6 economics) followed by mode-aware headroom/split math. Extends — does not replace — the M40 orchestrator. Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.

package/bin/cli-preflight-checks/branch-guard.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * branch-guard — verify current git branch matches CLAUDE.md "Expected branch" rule.
+ *
+ * Severity: error (blocks). If CLAUDE.md has no "Expected branch:" line, the check
+ * passes with `msg: "no expected-branch rule set"` (info-grade pass).
+ *
+ * Pure inspection — runs `git branch --show-current` (read-only) and reads CLAUDE.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ID = 'branch-guard';
+
+function _readClaudeMd(projectDir) {
+  const file = path.join(projectDir, 'CLAUDE.md');
+  if (!fs.existsSync(file)) return null;
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (_) {
+    return null;
+  }
+}
+
+function _extractExpectedBranch(text) {
+  if (!text) return null;
+  // Match `Expected branch:` (case-insensitive), allowing markdown emphasis like `**Expected branch**`,
+  // backticks around the value, optional surrounding whitespace.
+  // Examples that must match:
+  //   "Expected branch: main"
+  //   "Expected branch: `main`"
+  //   "**Expected branch**: `develop`"
+  //   "_Expected branch_: feature/foo"
+  const re = /\*{0,2}\s*expected\s+branch\s*\*{0,2}\s*:\s*\**\s*`?([^\s`*\n]+)`?/i;
+  const m = text.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function _currentBranch(projectDir) {
+  // execSync is synchronous and read-only here.
+  const stdout = execSync('git branch --show-current', {
+    cwd: projectDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return String(stdout || '').trim();
+}
+
+function run({ projectDir }) {
+  const md = _readClaudeMd(projectDir);
+  if (md == null) {
+    return {
+      ok: true,
+      msg: 'no CLAUDE.md found, skipping',
+    };
+  }
+  const expected = _extractExpectedBranch(md);
+  if (!expected) {
+    return {
+      ok: true,
+      msg: 'no expected-branch rule set',
+    };
+  }
+
+  let actual;
+  try {
+    actual = _currentBranch(projectDir);
+  } catch (err) {
+    return {
+      ok: false,
+      msg: 'git branch --show-current failed: ' + (err && err.message || err),
+      details: { expected },
+    };
+  }
+
+  if (!actual) {
+    return {
+      ok: false,
+      msg: 'detached HEAD or empty branch (expected ' + expected + ')',
+      details: { expected, actual: '' },
+    };
+  }
+
+  if (actual === expected) {
+    return {
+      ok: true,
+      msg: 'on expected branch ' + expected,
+      details: { expected, actual },
+    };
+  }
+
+  return {
+    ok: false,
+    msg: 'on ' + actual + ', expected ' + expected,
+    details: { expected, actual },
+  };
+}
+
+module.exports = {
+  id: ID,
+  severity: 'error',
+  run,
+  // Test-only exports
+  _extractExpectedBranch,
+  _readClaudeMd,
+  _currentBranch,
+};

package/bin/cli-preflight-checks/contracts-stable.cjs

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * contracts-stable — flag DRAFT/PROPOSED contracts when project is past
+ * the PARTITIONED milestone state.
+ *
+ * Severity: warn.
+ *
+ * Reads:
+ *   - .gsd-t/contracts/*.md  (looking for `Status: DRAFT` or `Status: PROPOSED`)
+ *   - .gsd-t/progress.md     (looking for milestone state past PARTITIONED:
+ *                             ACTIVE, EXECUTING, EXECUTED, INTEGRATING, INTEGRATED,
+ *                             VERIFYING, VERIFIED, COMPLETED, etc.)
+ *
+ * If the project is NOT past PARTITIONED, this check is a noop pass — DRAFT/PROPOSED
+ * contracts are expected pre-execute. After execute starts, they should all be STABLE.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ID = 'contracts-stable';
+
+// States that count as "past PARTITIONED". Anything strictly before partition
+// (DEFINED, PARTITIONED itself) is fine to have DRAFT/PROPOSED contracts.
+const POST_PARTITIONED_STATES = [
+  'ACTIVE',
+  'EXECUTING',
+  'EXECUTED',
+  'TEST-SYNCING',
+  'TEST-SYNCED',
+  'INTEGRATING',
+  'INTEGRATED',
+  'VERIFYING',
+  'VERIFIED',
+  'COMPLETED',
+];
+
+function _isPastPartitioned(progressContent) {
+  if (!progressContent) return false;
+  // Look for any "Status: <state>" line where state is post-partitioned.
+  // Match on lines (case-insensitive); exclude comments.
+  const re = /^\s*Status\s*:\s*\**\s*([A-Za-z\-]+)/gim;
+  let match;
+  while ((match = re.exec(progressContent)) !== null) {
+    const state = match[1].toUpperCase();
+    if (POST_PARTITIONED_STATES.includes(state)) return true;
+  }
+  return false;
+}
+
+function _scanContracts(contractsDir) {
+  if (!fs.existsSync(contractsDir)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(contractsDir);
+  } catch (_) {
+    return [];
+  }
+  const offenders = [];
+  for (const filename of entries) {
+    if (!filename.endsWith('.md')) continue;
+    const full = path.join(contractsDir, filename);
+    let content;
+    try {
+      content = fs.readFileSync(full, 'utf8');
+    } catch (_) {
+      continue;
+    }
+    // Match a Status field anywhere; capture DRAFT/PROPOSED specifically.
+    // Must allow markdown emphasis like `**DRAFT**` and surrounding `>` blockquotes.
+    const re = /^[\s>]*Status\s*:\s*\**\s*(DRAFT|PROPOSED)\s*\**/im;
+    const m = content.match(re);
+    if (m) {
+      offenders.push({ file: filename, status: m[1].toUpperCase() });
+    }
+  }
+  return offenders;
+}
+
+function run({ projectDir }) {
+  const contractsDir = path.join(projectDir, '.gsd-t', 'contracts');
+  const progressFile = path.join(projectDir, '.gsd-t', 'progress.md');
+
+  let progressContent = null;
+  if (fs.existsSync(progressFile)) {
+    try {
+      progressContent = fs.readFileSync(progressFile, 'utf8');
+    } catch (_) {
+      progressContent = null;
+    }
+  }
+
+  const offenders = _scanContracts(contractsDir);
+  const past = _isPastPartitioned(progressContent);
+
+  if (!past) {
+    return {
+      ok: true,
+      msg: 'project not past PARTITIONED; ' + offenders.length + ' DRAFT/PROPOSED contract(s) acceptable',
+      details: { offenders },
+    };
+  }
+
+  if (offenders.length === 0) {
+    return {
+      ok: true,
+      msg: 'all contracts STABLE',
+    };
+  }
+
+  return {
+    ok: false,
+    msg: offenders.length + ' DRAFT/PROPOSED contract(s) past PARTITIONED: ' +
+      offenders.map((o) => o.file + '(' + o.status + ')').join(', '),
+    details: { offenders },
+  };
+}
+
+module.exports = {
+  id: ID,
+  severity: 'warn',
+  run,
+  // Test-only exports
+  _isPastPartitioned,
+  _scanContracts,
+  POST_PARTITIONED_STATES,
+};

package/bin/cli-preflight-checks/deps-installed.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * deps-installed — verify Node deps are installed and lockfile is fresh.
+ *
+ * Severity: warn (records, does not block).
+ *
+ * Pass conditions:
+ *   - `node_modules/` exists AND
+ *   - `package-lock.json` mtime ≥ `package.json` mtime
+ *
+ * Edge cases:
+ *   - No `package.json` at all → ok:true (non-Node project; nothing to check)
+ *   - `package.json` exists but no `package-lock.json` → ok:false
+ *   - `node_modules/` missing → ok:false
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ID = 'deps-installed';
+
+function _mtime(file) {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch (_) {
+    return null;
+  }
+}
+
+function run({ projectDir }) {
+  const pkgPath = path.join(projectDir, 'package.json');
+  const lockPath = path.join(projectDir, 'package-lock.json');
+  const nmPath = path.join(projectDir, 'node_modules');
+
+  const pkgMtime = _mtime(pkgPath);
+  if (pkgMtime == null) {
+    return {
+      ok: true,
+      msg: 'no package.json (non-Node project)',
+    };
+  }
+
+  const lockMtime = _mtime(lockPath);
+  const nmExists = fs.existsSync(nmPath);
+
+  if (!nmExists && lockMtime == null) {
+    return {
+      ok: false,
+      msg: 'node_modules/ missing AND package-lock.json missing',
+      details: { nmExists, hasLock: false },
+    };
+  }
+  if (!nmExists) {
+    return {
+      ok: false,
+      msg: 'node_modules/ missing — run `npm install`',
+      details: { nmExists: false, hasLock: lockMtime != null },
+    };
+  }
+  if (lockMtime == null) {
+    return {
+      ok: false,
+      msg: 'package-lock.json missing',
+      details: { nmExists: true, hasLock: false },
+    };
+  }
+  if (lockMtime < pkgMtime) {
+    return {
+      ok: false,
+      msg: 'package-lock.json older than package.json — run `npm install`',
+      details: { lockMtime, pkgMtime, ageDelta_ms: pkgMtime - lockMtime },
+    };
+  }
+
+  return {
+    ok: true,
+    msg: 'node_modules/ present, lockfile fresh',
+    details: { lockMtime, pkgMtime },
+  };
+}
+
+module.exports = {
+  id: ID,
+  severity: 'warn',
+  run,
+  // Test-only exports
+  _mtime,
+};

package/bin/cli-preflight-checks/manifest-fresh.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * manifest-fresh — verify .gsd-t/journey-manifest.json is newer than every
+ * file under e2e/journeys/.
+ *
+ * Severity: info. Never blocks (top-level `ok` only flips on error-severity).
+ *
+ * If the manifest or the e2e/journeys/ dir is missing, the check is an
+ * info-grade noop pass with `msg: "no manifest, skipping"`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ID = 'manifest-fresh';
+
+function _walkSync(dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      _walkSync(full, out);
+    } else if (e.isFile()) {
+      out.push(full);
+    }
+  }
+}
+
+function _mtime(file) {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch (_) {
+    return null;
+  }
+}
+
+function run({ projectDir }) {
+  const manifestPath = path.join(projectDir, '.gsd-t', 'journey-manifest.json');
+  const journeysDir = path.join(projectDir, 'e2e', 'journeys');
+
+  const manifestMtime = _mtime(manifestPath);
+  const journeysExists = fs.existsSync(journeysDir);
+
+  if (manifestMtime == null || !journeysExists) {
+    return {
+      ok: true,
+      msg: 'no manifest, skipping',
+    };
+  }
+
+  const files = [];
+  _walkSync(journeysDir, files);
+
+  if (files.length === 0) {
+    return {
+      ok: true,
+      msg: 'manifest present, no journey files to compare',
+    };
+  }
+
+  const stale = [];
+  for (const f of files) {
+    const m = _mtime(f);
+    if (m == null) continue;
+    if (m > manifestMtime) {
+      stale.push({ file: path.relative(projectDir, f), mtime: m });
+    }
+  }
+
+  if (stale.length === 0) {
+    return {
+      ok: true,
+      msg: 'manifest fresher than ' + files.length + ' journey file(s)',
+      details: { manifestMtime, scanned: files.length },
+    };
+  }
+
+  return {
+    ok: false,
+    msg: 'manifest stale: ' + stale.length + ' journey file(s) newer',
+    details: { manifestMtime, stale, scanned: files.length },
+  };
+}
+
+module.exports = {
+  id: ID,
+  severity: 'info',
+  run,
+  // Test-only exports
+  _walkSync,
+  _mtime,
+};

package/bin/cli-preflight-checks/ports-free.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * ports-free — verify required dev ports are unbound.
+ *
+ * Severity: error (blocks).
+ *
+ * Reads `requiredFreePorts: number[]` from `.gsd-t/.unattended/config.json`.
+ * If absent or empty, check is a noop pass.
+ *
+ * For each port, runs `lsof -nP -iTCP:<port> -sTCP:LISTEN`. Exit 0 + non-empty
+ * stdout means a process is listening (FAIL). Exit 1 means no listener (PASS).
+ * Anything else (lsof missing, etc.) is treated as a soft fail with note.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ID = 'ports-free';
+
+function _readRequiredPorts(projectDir) {
+  const cfgPath = path.join(projectDir, '.gsd-t', '.unattended', 'config.json');
+  if (!fs.existsSync(cfgPath)) return [];
+  let raw;
+  try {
+    raw = fs.readFileSync(cfgPath, 'utf8');
+  } catch (_) {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_) {
+    return [];
+  }
+  const ports = parsed && parsed.requiredFreePorts;
+  if (!Array.isArray(ports)) return [];
+  // Coerce + filter to positive integers.
+  return ports
+    .map((p) => Number(p))
+    .filter((p) => Number.isInteger(p) && p > 0 && p < 65536);
+}
+
+function _portInUse(port) {
+  // execSync throws on non-zero exit. lsof exits 1 when nothing matches.
+  try {
+    const stdout = execSync('lsof -nP -iTCP:' + port + ' -sTCP:LISTEN', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return { listening: String(stdout || '').trim().length > 0 };
+  } catch (err) {
+    // lsof exits 1 when no match — that's the happy "port free" path.
+    if (err && err.status === 1) return { listening: false };
+    // Anything else (e.g., lsof not installed) — surface as unknown.
+    return { listening: false, error: err && err.message || String(err) };
+  }
+}
+
+function run({ projectDir }) {
+  const ports = _readRequiredPorts(projectDir);
+  if (ports.length === 0) {
+    return {
+      ok: true,
+      msg: 'no requiredFreePorts configured',
+    };
+  }
+
+  const occupied = [];
+  const errors = [];
+  for (const port of ports) {
+    const r = _portInUse(port);
+    if (r.error) errors.push({ port, error: r.error });
+    if (r.listening) occupied.push(port);
+  }
+
+  if (occupied.length === 0 && errors.length === 0) {
+    return {
+      ok: true,
+      msg: 'all ' + ports.length + ' required ports are free',
+      details: { ports },
+    };
+  }
+
+  if (occupied.length > 0) {
+    return {
+      ok: false,
+      msg: 'occupied ports: ' + occupied.join(', '),
+      details: { ports, occupied, errors },
+    };
+  }
+
+  // Only errors, no occupancy — fail closed: an error-severity check shouldn't
+  // pass when we can't actually verify the ports.
+  return {
+    ok: false,
+    msg: 'lsof probe failed for ' + errors.length + ' port(s)',
+    details: { ports, errors },
+  };
+}
+
+module.exports = {
+  id: ID,
+  severity: 'error',
+  run,
+  // Test-only exports
+  _readRequiredPorts,
+  _portInUse,
+};