@tekyzinc/gsd-t 3.26.10 → 3.27.10

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.27.10] - 2026-05-19
+
+### Added — M57 CI-Parity Verify Gate
+
+Origin: a TimeTracking v1.10.12 post-mortem — `gsd-t-verify` reported
+VERIFIED, the milestone was tagged + pushed, but Cloud Build failed (a new
+top-level `hooks/` dir was committed but never added to the Dockerfile
+`COPY` directives, and `noImplicitAny` regressions passed a warm-cache
+local `tsc` but failed CI's cold build). A cross-project survey found 7/18
+registered projects have CI surfaces — systemic, not project-specific.
+
+- **`gsd-t build-coverage`** (`bin/gsd-t-build-coverage.cjs`) — detects new
+  top-level paths in a milestone commit range not referenced by a real CI
+  build input. Coverage is decided by **structurally parsing** CI files
+  (Dockerfile COPY/ADD source args incl. relative `--from=`; cloudbuild
+  `args`-positional; workflow `run`-positional via a block-scalar-aware
+  YAML walker) — never substring-matching raw config text. `node_modules`
+  never counts.
+- **`gsd-t ci-parity`** (`bin/gsd-t-ci-parity.cjs`) — reproduces the
+  project's actual CI build locally (auto-detect cloudbuild → workflows →
+  Dockerfile RUN → package scripts), clears build caches, auto-runs the
+  real `docker build` when a Dockerfile is present. `clearBuildCaches`
+  routes every config-derived delete through a containment predicate
+  (`resolved.startsWith(root+sep) && resolved!==root`) — refuses any path
+  resolving outside OR equal-to projectRoot (a Destructive Action Guard
+  requirement).
+- Both wired into `gsd-t-verify` Step 2.6 as **FAIL-blocking** checks
+  (never warning-only); either failing blocks complete-milestone.
+
+### Process note — re-plan after Red Team non-convergence
+
+The first M57 design (substring-match build-coverage + unguarded
+cache-clear) FAILED Red Team across **5 non-converging cycles** (BUG-4/6/
+9/9b: each fix spawned a new false-negative variant; plus 5 CRITICAL
+Destructive-Action-Guard violations in the cache-clearer). The autonomous
+chain was halted (Prime Rule stop #2), the design re-planned, and rebuilt
+in-session after the detached fan-out harness false-completed twice
+(contracts flipped STABLE while the code was never rewritten). The
+corrected structural design converged on the first attempt: all 7 frozen
+falsification-corpus variants flagged, containment predicate holds, full
+suite 2587 pass / 0 fail. Lessons captured in memory
+(`feedback_coverage_check_structural_not_substring`,
+`feedback_destructive_path_ops_containment`,
+`feedback_detached_fanout_false_completion`). Pair-flagged with backlog
+#25 (gsd-t-bench): the bench eval set must include a synthetic regression
+of this incident when it ships.
+
+## [3.26.11] - 2026-05-11
+
+### Changed — Effort estimates in GSD-T-native units
+
+Promoted `feedback_no_human_hour_estimates.md` from per-user memory to canonical global rule. Replaced all 7 `Estimated effort: {assessment}` placeholders that were silently producing developer-hour / dev-day / sprint output with explicit GSD-T-unit prompts.
+
+- `~/.claude/CLAUDE.md` + `templates/CLAUDE-global.md`: new MANDATORY section "Effort Estimates — GSD-T-Native Units" with the unit table (domain count, wave count, parallel-domain count, spawn count, token-spend range, rate-limit-window count) + acceptable-machine-time-references carve-out (5 min cache TTL, 14 day staleness, etc.) so the rule doesn't break legitimate system-timeout language.
+- `commands/gsd-t-milestone.md` Step 4: Pre-Partition Assessment now requires GSD-T units, presents the unit table inline.
+- `commands/gsd-t-scan.md`: 5 `Estimated effort: {assessment}` placeholders replaced with `Estimated scope: {N domains}/{N waves}/$X-Y token-spend` + memory reference.
+- `commands/gsd-t-promote-debt.md`: same swap.
+- `commands/gsd-t-scan.md`: "Dependency Update Sprint" → "Dependency Update".
+- `templates/stacks/design-to-code.md`: "estimate effort" → "scope in GSD-T units".
+
+Rationale: human-hour estimates ("30-min task", "2-3 day window") create false mental models for GSD-T workflows where the worker is Claude, not a human team. Token-spend, parallel-domain count, and rate-limit-window count are the actually-predictive units.
+
+Tests: 2547/2547 (unchanged — doc-only change).
+
 ## [3.26.10] - 2026-05-09
 
 ### Added — M56: Verify-Gate CLI Fan-Out + Upper-Stage Briefs

package/README.md

@@ -119,6 +119,8 @@ gsd-t brief --kind execute --domain X --spawn-id Y      # ≤2,500-token JSON sn
 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 build-coverage --json                             # M57: new top-level paths must be a real CI build input (structural parse)
+gsd-t ci-parity --json                                  # M57: reproduce the project's actual CI build locally (auto docker build)
 ```
 
 `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/context-budget-audit.cjs

@@ -9,15 +9,29 @@
 //   node bin/context-budget-audit.js --json           # JSON output for tooling
 //   node bin/context-budget-audit.js --top 20         # top N largest files
 //   node bin/context-budget-audit.js --threshold 5000 # flag files above N tokens
+//   node bin/context-budget-audit.js --model claude-opus-4-7  # size % to a model's window (default: 1M)
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+const { windowForModel, SAFE_DEFAULT_WINDOW } = require('./model-windows.cjs');
+
 // Token estimation: GPT/Claude tokenizers average ~4 chars/token for English+code.
 // This is a fast deterministic estimate, not a true tokenizer call. Within ~10%.
 const CHARS_PER_TOKEN = 4;
-const CONTEXT_WINDOW = 200_000; // claude-opus-4-6 default
+
+// Context window for the "% of window" math. This is a static-analysis CLI with
+// no live transcript, so the model is resolved from --model / GSD_T_MODEL when
+// provided, else the model-windows safe LARGE default (1M). A bare 200K literal
+// (the old value) overstated every percentage 5× for Opus/Sonnet sessions.
+let CONTEXT_WINDOW = (() => {
+  const fromEnv = typeof process.env.GSD_T_MODEL === 'string' ? process.env.GSD_T_MODEL : '';
+  const argIdx = process.argv.indexOf('--model');
+  const fromArg = argIdx !== -1 ? process.argv[argIdx + 1] : '';
+  const modelId = fromArg || fromEnv;
+  return modelId ? windowForModel(modelId) : SAFE_DEFAULT_WINDOW;
+})();
 
 function estimateTokens(bytes) {
   return Math.round(bytes / CHARS_PER_TOKEN);
@@ -414,8 +428,9 @@ function main() {
     else if (a === '--threshold') opts.threshold = parseInt(args[++i], 10);
     else if (a === '--project') opts.projectDir = path.resolve(args[++i]);
     else if (a === '--global') opts.globalDir = path.resolve(args[++i]);
+    else if (a === '--model') i++; // consumed at init for window sizing; skip value
     else if (a === '--help' || a === '-h') {
-      console.log('Usage: node bin/context-budget-audit.js [--json] [--top N] [--threshold N]');
+      console.log('Usage: node bin/context-budget-audit.js [--json] [--top N] [--threshold N] [--model <claude-model-id>]');
       process.exit(0);
     }
   }

package/bin/gsd-t-build-coverage.cjs

@@ -0,0 +1,438 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GSD-T build-coverage (M57 D1) — STRUCTURAL CI parsing.
+ *
+ * Detects new top-level paths added in a milestone commit range that no CI
+ * build artifact references — the TimeTracking v1.10.12 failure class (new
+ * `hooks/` dir committed, absent from Dockerfile COPY, shipped broken while
+ * local verify reported VERIFIED).
+ *
+ * DESIGN MANDATE (re-plan 2026-05-19, after the substring design failed Red
+ * Team across 5 non-converging cycles — BUG-4/6/9/9b):
+ *   Coverage is decided by STRUCTURALLY PARSING the CI files — a path
+ *   contributes coverage ONLY when it appears in a build-input position:
+ *     - Dockerfile: a COPY/ADD source argument (incl. `--from=` SOURCE,
+ *       relative AND absolute); NOT in RUN/CMD/comment/ENV.
+ *     - cloudbuild.yaml: a value inside a `steps[].args` list; NOT in a
+ *       `#` comment, a step `id:`/`name:`, or an `env:` block.
+ *     - .github/workflows/*.yml: a token inside a `jobs.<job>.steps[].run`
+ *       command or a `working-directory:` value; NOT in a step/job/workflow
+ *       `name:` (plain, quoted, OR multi-line `|`/`>` block/folded scalar),
+ *       NOT in a `#` comment.
+ *   A path whose first segment is `node_modules` NEVER contributes coverage.
+ *   There is NO code path that does `configText.includes(seg)` or regex-greps
+ *   raw config text for the segment name. (See memory:
+ *   feedback_coverage_check_structural_not_substring.md)
+ *
+ * Exports: checkBuildCoverage({ projectDir, baseRef, headRef })
+ * CLI:     node bin/gsd-t-build-coverage.cjs [--json] [--base REF] [--head REF]
+ *
+ * Contract: .gsd-t/contracts/cli-build-coverage-contract.md v1.1.0 STABLE.
+ *
+ * Exit codes (CLI):
+ *   0 — ok:true (all new paths covered, OR no CI artifacts found)
+ *   4 — ok:false (≥1 new top-level path uncovered)
+ *   2 — usage error (bad refs, not a git repo, detached HEAD)
+ *
+ * Hard rules: zero external runtime deps (Node built-ins only); functions
+ * small; never throw out of checkBuildCoverage (usage errors surface as a
+ * thrown UsageError caught by the CLI entry).
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+class UsageError extends Error {
+  constructor(message) { super(message); this.name = 'UsageError'; }
+}
+
+// ---------------------------------------------------------------------------
+// Git helpers
+// ---------------------------------------------------------------------------
+
+function gitDiffNames(projectDir, baseRef, headRef) {
+  const raw = execSync(`git diff --name-only ${baseRef}..${headRef}`, {
+    cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return raw.split('\n').map(s => s.trim()).filter(Boolean);
+}
+
+function resolveRefs(projectDir, baseRef, headRef) {
+  execSync('git rev-parse --git-dir', {
+    cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const base = baseRef || 'HEAD~1';
+  const head = headRef || 'HEAD';
+  if (base === head) throw new UsageError(`baseRef and headRef are identical: ${base}`);
+  return { base, head };
+}
+
+/** First path segment of a posix-ish path, or '' if none/`.`. */
+function topSegment(p) {
+  const cleaned = String(p).replace(/^\.\//, '').replace(/^\/+/, '');
+  const seg = cleaned.split('/')[0];
+  return (!seg || seg === '.' || seg === '..') ? '' : seg;
+}
+
+function collapseToTopLevel(filePaths) {
+  const seen = new Set();
+  for (const p of filePaths) {
+    const seg = topSegment(p);
+    if (seg) seen.add(seg);
+  }
+  return Array.from(seen).sort();
+}
+
+/**
+ * Map a build-input path reference to the workspace top-level segment it
+ * covers, or '' if it covers nothing in the workspace.
+ *  - absolute paths (`/app/dist`) reference the *image* fs, not the
+ *    workspace → no workspace coverage.
+ *  - `node_modules/...` never contributes coverage (BUG-7).
+ */
+function coverageSegment(ref) {
+  const r = String(ref).trim();
+  if (!r || r.startsWith('/')) return '';            // absolute = image fs
+  const seg = topSegment(r);
+  if (!seg || seg === 'node_modules') return '';      // BUG-7 hard rule
+  return seg;
+}
+
+// ---------------------------------------------------------------------------
+// Dockerfile — structural, line-oriented
+// ---------------------------------------------------------------------------
+
+/** Split a COPY/ADD argument string into tokens, dropping flags. */
+function copyArgTokens(argStr) {
+  return argStr.trim().split(/\s+/).filter(t => t && !t.startsWith('--'));
+}
+
+/**
+ * Parse Dockerfile structurally. Only COPY/ADD instructions contribute.
+ * Returns { coversAll, segments: Set }.
+ *   - `COPY . .` / `ADD . .` → coversAll.
+ *   - `COPY src/ ./src/` → source `src/` covers `src`.
+ *   - `COPY --from=stage <src> <dest>` → `<src>` IS a build input; a
+ *     relative src (`dist/`) covers `dist`; an absolute src (`/app/dist`)
+ *     references the build-stage image fs → covers nothing in workspace.
+ *   - flags (`--from=`, `--chown=`, `--chmod=`) are not path tokens.
+ *   - a path in RUN/CMD/ENV/comment is NOT a build input.
+ */
+function parseDockerfile(filePath) {
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+  const segments = new Set();
+  let coversAll = false;
+  for (const raw of lines) {
+    const line = raw.replace(/\t/g, ' ').trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = line.match(/^(COPY|ADD)\s+(.+)$/i);
+    if (!m) continue;                                  // RUN/CMD/ENV/FROM → ignore
+    const tokens = copyArgTokens(m[2]);
+    if (tokens.length < 2) continue;                   // need ≥1 src + 1 dest
+    const sources = tokens.slice(0, tokens.length - 1); // last = dest
+    for (const src of sources) {
+      if (src === '.') { coversAll = true; continue; }
+      const seg = coverageSegment(src);
+      if (seg) segments.add(seg);
+    }
+  }
+  return { coversAll, segments };
+}
+
+// ---------------------------------------------------------------------------
+// Minimal YAML structure walker (no YAML lib — zero-dep invariant)
+//
+// Not a general YAML parser. A line-state machine that yields, for each
+// physical line, enough context to know whether a path token on that line
+// sits in a build-input position. It tracks:
+//   - comment stripping (only outside quotes; YAML `#` must be preceded by
+//     whitespace or start-of-content to be a comment)
+//   - the current mapping key on a line (`key:` ...)
+//   - block/folded scalar regions (`key: |` / `key: >`) and their indent,
+//     so continuation lines are attributed to the OWNING key (this is the
+//     BUG-9/9b fix: a `name: |` continuation is name-prose, never a build
+//     input)
+// ---------------------------------------------------------------------------
+
+function stripYamlComment(line) {
+  // Remove a trailing `#...` comment when the # is at col 0 or preceded by
+  // whitespace and not inside a quote. Cheap quote tracking is sufficient
+  // for CI YAML (no `#` inside our path tokens).
+  let inS = false, inD = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === "'" && !inD) inS = !inS;
+    else if (c === '"' && !inS) inD = !inD;
+    else if (c === '#' && !inS && !inD && (i === 0 || /\s/.test(line[i - 1]))) {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+
+function indentOf(line) {
+  const m = line.match(/^(\s*)/);
+  return m ? m[1].length : 0;
+}
+
+/**
+ * Walk a workflow/cloudbuild YAML and invoke cb(kind, value) for every
+ * build-input-bearing token region, where kind is 'run' | 'arg' | 'workdir'.
+ * Lines inside a block/folded scalar owned by a non-build key (`name:`,
+ * `id:`, `env:`, …) are NEVER emitted.
+ */
+function walkYamlBuildInputs(content, cb) {
+  const lines = content.split('\n');
+  // Active block-scalar state: { ownerKey, indent } — continuation lines with
+  // indent > indent belong to ownerKey and are skipped unless ownerKey is a
+  // build key (run). We only treat `run:` block scalars as build input.
+  let block = null;
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    if (block) {
+      const ind = indentOf(rawLine);
+      const isBlank = rawLine.trim() === '';
+      if (isBlank || ind > block.indent) {
+        if (block.ownerKey === 'run' && !isBlank) cb('run', rawLine);
+        continue;                                      // consumed by the block
+      }
+      block = null;                                    // dedent → block ended
+    }
+    const line = stripYamlComment(rawLine);
+    if (line.trim() === '') continue;
+
+    // `- key: value` or `key: value` (list-item dash optional)
+    const km = line.match(/^(\s*)(?:-\s+)?([A-Za-z_][\w-]*)\s*:(.*)$/);
+    if (km) {
+      const key = km[2];
+      const rest = km[3].trim();
+      const keyIndent = km[1].length;
+      // Block/folded scalar opener: `key: |` `key: >` (+ chomping/indent)
+      if (/^[|>][+-]?\d*\s*$/.test(rest)) {
+        block = { ownerKey: key, indent: keyIndent };
+        continue;
+      }
+      if (key === 'run' && rest) cb('run', rest);
+      else if (key === 'working-directory' && rest) cb('workdir', rest);
+      // `name:`, `id:`, `uses:`, `env:`, `if:`, job/workflow keys → NOT
+      // build inputs; their inline value is intentionally ignored.
+      continue;
+    }
+
+    // Inside an `args:` sequence: `- 'token'` items. We only honor this when
+    // the nearest enclosing key was `args`. Track that with a light scan:
+    // a line `args:` opens arg-mode until dedent past its indent.
+    // Implemented below via argMode.
+  }
+}
+
+/**
+ * cloudbuild.yaml: collect path tokens that are VALUES inside a `steps[].args`
+ * list. Recognizes:
+ *   args: ['build', '-t', 'x', '.']        (flow sequence)
+ *   args:
+ *     - 'build'
+ *     - '.'                                (block sequence)
+ * A `.` arg is the docker *build context*, not a workspace COPY — it does NOT
+ * imply coversAll for build-coverage (the Dockerfile is the authority for
+ * what gets copied). We still record explicit path-looking args so an
+ * artifacts/copy-style step can contribute, but never from comments/`name:`.
+ */
+function parseCloudBuild(filePath) {
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+  const segments = new Set();
+  let argMode = null;                                  // { indent }
+  for (const rawLine of lines) {
+    const line = stripYamlComment(rawLine);
+    if (line.trim() === '') continue;
+    const ind = indentOf(line);
+    if (argMode && ind <= argMode.indent) argMode = null;
+
+    const flow = line.match(/^\s*(?:-\s+)?args\s*:\s*\[(.*)\]\s*$/);
+    if (flow) {
+      for (const tok of flow[1].split(',')) {
+        const v = tok.trim().replace(/^['"]|['"]$/g, '');
+        const seg = coverageSegment(v);
+        if (seg) segments.add(seg);
+      }
+      continue;
+    }
+    if (/^\s*(?:-\s+)?args\s*:\s*$/.test(line)) { argMode = { indent: ind }; continue; }
+    if (argMode) {
+      const item = line.match(/^\s*-\s+(.*)$/);
+      if (item) {
+        const v = item[1].trim().replace(/^['"]|['"]$/g, '');
+        const seg = coverageSegment(v);
+        if (seg) segments.add(seg);
+      }
+      continue;
+    }
+  }
+  return { segments };
+}
+
+/**
+ * Extract workspace path segments from a shell command string (a `run:`
+ * value or `working-directory:`). Token-splits and maps each token through
+ * coverageSegment (which already drops absolute + node_modules). Flags and
+ * option-args (`-r`, `--foo`) are ignored.
+ */
+function segmentsFromCommand(cmd) {
+  const out = [];
+  for (const tok of String(cmd).split(/\s+/)) {
+    const t = tok.replace(/^['"]|['"]$/g, '');
+    if (!t || t.startsWith('-')) continue;
+    if (!t.includes('/')) continue;                    // bare words aren't paths
+    const seg = coverageSegment(t);
+    if (seg) out.push(seg);
+  }
+  return out;
+}
+
+/** .github/workflows/*.yml: collect segments from `run:` + `working-directory:` only. */
+function parseWorkflows(workflowDir) {
+  const segments = new Set();
+  let files;
+  try { files = fs.readdirSync(workflowDir); } catch { return { segments }; }
+  for (const f of files) {
+    if (!/\.ya?ml$/.test(f)) continue;
+    const content = fs.readFileSync(path.join(workflowDir, f), 'utf8');
+    walkYamlBuildInputs(content, (kind, value) => {
+      if (kind === 'run') for (const s of segmentsFromCommand(value)) segments.add(s);
+      else if (kind === 'workdir') {
+        const seg = coverageSegment(value.replace(/^['"]|['"]$/g, ''));
+        if (seg) segments.add(seg);
+      }
+    });
+  }
+  return { segments };
+}
+
+// ---------------------------------------------------------------------------
+// CI artifact detection
+// ---------------------------------------------------------------------------
+
+function detectCIArtifacts(projectDir) {
+  const artifacts = [];
+  let coversAll = false;
+  const covered = new Set();
+
+  const dockerfilePath = path.join(projectDir, 'Dockerfile');
+  if (fs.existsSync(dockerfilePath)) {
+    artifacts.push('Dockerfile');
+    const r = parseDockerfile(dockerfilePath);
+    if (r.coversAll) coversAll = true;
+    for (const s of r.segments) covered.add(s);
+  }
+
+  const cloudbuildPath = path.join(projectDir, 'cloudbuild.yaml');
+  if (fs.existsSync(cloudbuildPath)) {
+    artifacts.push('cloudbuild.yaml');
+    for (const s of parseCloudBuild(cloudbuildPath).segments) covered.add(s);
+  }
+
+  const workflowDir = path.join(projectDir, '.github', 'workflows');
+  if (fs.existsSync(workflowDir)) {
+    const wf = parseWorkflows(workflowDir);
+    if (wf.segments.size > 0 ||
+        (fs.existsSync(workflowDir) && fs.readdirSync(workflowDir).some(f => /\.ya?ml$/.test(f)))) {
+      artifacts.push('.github/workflows');
+    }
+    for (const s of wf.segments) covered.add(s);
+  }
+
+  return { artifacts, coversAll, covered };
+}
+
+// ---------------------------------------------------------------------------
+// Main API
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} opts
+ * @param {string}  opts.projectDir
+ * @param {string}  [opts.baseRef]
+ * @param {string}  [opts.headRef]
+ * @param {string[]} [opts._newPaths] - test seam: supply diff list directly
+ * @returns {{ ok, missing, checkedAgainst, newPaths, note? }}
+ */
+function checkBuildCoverage({ projectDir, baseRef, headRef, _newPaths }) {
+  const { base, head } = resolveRefs(projectDir, baseRef, headRef);
+
+  const newPaths = _newPaths !== undefined
+    ? collapseToTopLevel(_newPaths)
+    : collapseToTopLevel(gitDiffNames(projectDir, base, head));
+
+  if (newPaths.length === 0) {
+    return { ok: true, missing: [], checkedAgainst: [], newPaths: [], note: 'empty diff' };
+  }
+
+  const { artifacts, coversAll, covered } = detectCIArtifacts(projectDir);
+
+  if (artifacts.length === 0) {
+    return { ok: true, missing: [], checkedAgainst: [], newPaths, note: 'no CI artifacts detected' };
+  }
+  if (coversAll) {
+    return { ok: true, missing: [], checkedAgainst: artifacts, newPaths };
+  }
+
+  // node_modules is never a "new path" worth gating, and never coverage.
+  const gated = newPaths.filter(p => p !== 'node_modules');
+  const missing = gated.filter(p => !covered.has(p));
+
+  return { ok: missing.length === 0, missing, checkedAgainst: artifacts, newPaths };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+function parseArgv(argv) {
+  const opts = { json: false, base: undefined, head: undefined, projectDir: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--base') opts.base = argv[++i];
+    else if (a === '--head') opts.head = argv[++i];
+    else if (a === '--project-dir') opts.projectDir = argv[++i];
+    else if (a === '-h' || a === '--help') {
+      process.stdout.write([
+        'Usage: gsd-t build-coverage [--json] [--base REF] [--head REF] [--project-dir PATH]',
+        '',
+        'Exit codes:',
+        '  0  ok:true — all new top-level paths covered, or no CI artifacts found.',
+        '  4  ok:false — ≥1 new top-level path not covered by any CI build input.',
+        '  2  usage error (bad refs, not a git repo).',
+        '',
+      ].join('\n'));
+      process.exit(0);
+    }
+  }
+  return opts;
+}
+
+if (require.main === module) {
+  const opts = parseArgv(process.argv.slice(2));
+  let result;
+  try {
+    result = checkBuildCoverage({
+      projectDir: opts.projectDir, baseRef: opts.base, headRef: opts.head,
+    });
+  } catch (e) {
+    process.stderr.write(`build-coverage: ${e && e.message ? e.message : String(e)}\n`);
+    process.exit(2);
+  }
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (result.ok) {
+    process.stdout.write(`OK: all new top-level paths covered${result.note ? ` (${result.note})` : ''}\n`);
+  } else {
+    process.stdout.write(`FAIL: uncovered paths: ${result.missing.join(', ')}\n`);
+  }
+  process.exit(result.ok ? 0 : 4);
+}
+
+module.exports = { checkBuildCoverage, _internal: { parseDockerfile, parseCloudBuild, parseWorkflows, coverageSegment, stripYamlComment } };