@tekyzinc/gsd-t 5.11.24 → 5.11.27

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.11.27] - 2026-08-11
+
+### Fixed — the scan's volume probe returned a stand-in, and the whole run was built on it
+
+HiloAviation, this morning. The probe answered `totals: {"trackedFiles": 5036}`
+and `slices: [{"key": "test", "paths": ["src/"]}]` — one slice for a 4,900-file
+application, keyed "test", and none of the six measurements the prompt asked for.
+The schema accepted it (one slice is legal, `totals` takes any object), so the
+scan read that single slice, produced 3 findings, and headed the register
+"Coverage: FULL".
+
+The probe had no retry. Every finder gets re-run when it answers `{"findings":[]}`;
+the probe — which decides what every finder will ever look at — got one call, and
+whatever came back became the plan.
+
+The tell is not the slice count; a small repo really is one slice. It is that the
+fields explicitly requested are absent: the shape of an answer with none of the
+work behind it. So the result is now inspected before it is trusted, retried on
+opus with the fault named, and a second stand-in HALTS the scan rather than
+scanning it — a register that under-counts while claiming full coverage is worse
+than no register.
+
+- `templates/workflows/gsd-t-scan.workflow.js`: `probePlaceholderFaults()` +
+  retry-on-opus + halt; the prompt is now a reusable constant so the retry sends
+  the same task; the slice count and totals are logged at probe time, so a thin
+  plan is visible before the run rather than inferred afterwards from a thin
+  register.
+- `test/m112-probe-placeholder.test.js`: 11 regressions, including the verbatim
+  payload that produced the 3-finding scan.
+
+The whole-tree tell only fires when the measurements are missing too. A small
+project genuinely is one slice covering `src/`, and halting that scan would be a
+false alarm on every small repo — worse than the bug being fixed.
+
+## [5.11.26] - 2026-08-11
+
+### Fixed — a quarter of every import edge pointed at a string no file matched
+
+A project writes `import x from "@/lib/foo"` and declares what `@/` means in its
+tsconfig. Stored raw, that target resolves to nothing — the graph records an edge
+pointing at `@/lib/foo`, and no file is ever named that.
+
+**Measured on HiloAviation: 5,738 of 23,263 import edges — 25% — were
+unexpanded shortcuts.** Ask "does anything import this file?" and a quarter of
+the real answers are missing, so live code looks unreferenced. A reachability
+rule built on that data would have called **1,919 files of a working app dead**.
+
+The indexer now reads `paths` (and `baseUrl`) from `tsconfig.json` or
+`jsconfig.json` once per build, and expands every import target before storing
+it. A package import like `react` is left exactly as written — rewriting it
+would invent an edge to a file that does not exist.
+
+A config that is present but unreadable or unparseable is **announced**, never
+silently skipped: skipping expansion while reporting a successful build is the
+failure this fixes. A project with no such config says so too.
+
+Config files routinely carry comments and trailing commas, so both are stripped
+— but never inside a string, or a URL like `https://…` loses everything after
+the `//`.
+
+- `bin/gsd-t-graph-index.cjs`: `loadPathAliases()` + `expandAlias()`, applied where import edges are stored
+- `test/m112-import-alias-expansion.test.js`: 6 tests — expansion, packages untouched, comments + URL, no config, `baseUrl`, and that a broken config is announced
+
+**Rebuild the index to benefit:** `gsd-t graph index`. An index built before this
+release still holds the raw shortcuts.
+
 ## [5.11.24] - 2026-08-11
 
 ### Fixed — the code graph never reached a single scanning agent for six weeks

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.11.24** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.11.27** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-graph-index.cjs

@@ -70,6 +70,89 @@ function errLog(msg){ log(`${C.red}[IDX ERR]${C.reset} ${msg}`); }
 
 // ── Source-file extensions + skip dirs (matches D2 / K2 probe) ───────────────
 
+// ── Import path shortcuts (tsconfig `paths`) ────────────────────────────────
+//
+// A project writes `import x from "@/lib/foo"` and declares what `@/` means in
+// tsconfig: `"@/*": ["./src/*"]`. Stored raw, that target resolves to nothing —
+// the graph records an edge pointing at a string no file matches.
+//
+// Measured on HiloAviation: 5,738 of 23,263 import edges (25%) pointed at an
+// unexpanded shortcut. Ask "does anything import this file?" and a quarter of
+// the real answers are missing, so live code looks unreferenced. A reachability
+// rule built on that would have called 1,919 files of a working app dead.
+//
+// Read once per index build, applied to every import target before it is stored.
+// A project with no tsconfig, or none with paths, simply has nothing to expand.
+function loadPathAliases(projectDir) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    const file = path.join(projectDir, name);
+    if (!fs.existsSync(file)) continue;
+
+    let raw;
+    try {
+      raw = fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      // Present but unreadable is a real problem, not an absent config: every
+      // shortcut in the project would silently go unresolved.
+      warn(`${name} could not be read (${e.message}) — import shortcuts will NOT be expanded`);
+      return null;
+    }
+
+    // These files routinely carry comments and trailing commas, which JSON does
+    // not allow. Strip them rather than fail — but never strip inside a string,
+    // or a URL like "https://..." loses everything after the //.
+    const stripped = raw
+      .replace(/("(?:[^"\\]|\\.)*")|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (m, str) => str || '')
+      .replace(/,(\s*[}\]])/g, '$1');
+
+    let cfg;
+    try {
+      cfg = JSON.parse(stripped);
+    } catch (e) {
+      warn(`${name} is not parseable (${e.message}) — import shortcuts will NOT be expanded`);
+      return null;
+    }
+
+    const opts  = (cfg && cfg.compilerOptions) || {};
+    const paths = opts.paths;
+    if (!paths || typeof paths !== 'object') continue;
+
+    const base = opts.baseUrl ? path.join(projectDir, opts.baseUrl) : projectDir;
+    const rules = [];
+    for (const [pattern, targets] of Object.entries(paths)) {
+      if (!Array.isArray(targets) || targets.length === 0) continue;
+      rules.push({
+        prefix: pattern.replace(/\*$/, ''),          // "@/*"      -> "@/"
+        target: String(targets[0]).replace(/\*$/, ''), // "./src/*" -> "./src/"
+        wildcard: pattern.endsWith('*'),
+        base,
+      });
+    }
+    if (rules.length) {
+      info(`import shortcuts: ${rules.length} rule(s) from ${name} (${rules.map((r) => r.prefix + '*').join(', ')})`);
+      return rules;
+    }
+  }
+  return null;
+}
+
+// Turn one import target into a project-relative path when a rule matches it.
+// Returns the original string untouched when nothing matches — a package import
+// like "react" is not a shortcut and must stay exactly as written.
+function expandAlias(spec, rules, projectDir) {
+  if (!rules || !spec || typeof spec !== 'string') return spec;
+  for (const r of rules) {
+    if (!r.wildcard) {
+      if (spec !== r.prefix) continue;
+    } else if (!spec.startsWith(r.prefix)) continue;
+
+    const rest = r.wildcard ? spec.slice(r.prefix.length) : '';
+    const abs = path.resolve(r.base, r.target + rest);
+    return path.relative(projectDir, abs);
+  }
+  return spec;
+}
+
 const PARSED_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py']);
 const SKIP_DIRS = new Set([
   'node_modules', '.next', 'dist', 'build', '.git',
@@ -332,10 +415,14 @@ function parse_and_put(absPath, relPath, options) {
   // Normalize edges to store schema (map from parser-floor shape to store shape)
   const storeEdges = finalEdges.map(edge => {
     if (edge.kind === 'import' || edge.kind === 'require') {
+      // Expand a path shortcut ("@/lib/foo") into a real project path before it
+      // is stored. Stored raw it points at a string no file matches, and every
+      // question about what-imports-what silently loses that edge.
+      const rawDst = edge.target || edge.dst;
       return {
         kind: 'IMPORT',
         src: edge.source || edge.src,
-        dst: edge.target || edge.dst,
+        dst: expandAlias(rawDst, (options && options.aliasRules) || null, (options && options.projectDir) || '.'),
         partial: 0,
       };
     }
@@ -429,6 +516,14 @@ function build_index(repoRoot, options) {
     }
   }
 
+  // Read the project's import shortcuts ONCE for the whole build. Every import
+  // target is expanded through these before it is stored, so an edge points at a
+  // real path rather than at a string nothing matches.
+  const aliasRules = loadPathAliases(repoRoot);
+  if (!aliasRules) {
+    info('import shortcuts: none declared (no tsconfig/jsconfig paths) — import targets stored as written');
+  }
+
   const t0 = Date.now();
   let fileCount = 0;
   let entityCount = 0;
@@ -441,7 +536,7 @@ function build_index(repoRoot, options) {
   // Stream: parse + put each file one at a time (never accumulate the full set)
   for (const { absPath, relPath } of files) {
     try {
-      const result = parse_and_put(absPath, relPath, { db, scip: scipCtx });
+      const result = parse_and_put(absPath, relPath, { db, scip: scipCtx, aliasRules, projectDir: repoRoot });
       fileCount++;
       entityCount += result.entities.length;
       edgeCount += result.edges.length;

package/bin/gsd-t-slice-budget.cjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gsd-t-slice-budget.cjs — measure a slice plan in LINES and split what is too big.
+ *
+ * [RULE] slice-budget-measured-in-lines-not-files
+ * [RULE] slice-budget-splits-never-drops
+ * [RULE] slice-budget-reports-every-decision
+ *
+ * A reviewer is told to read every file in its slice. Whether it can depends on
+ * how much code it was handed — and files are a terrible proxy for that. In the
+ * HiloAviation codebase the median source file is 233 lines and the largest is
+ * 23,664: a hundred to one. "120 files" means nothing.
+ *
+ * Lines track what actually happened. Across three real scans of the same
+ * project:
+ *
+ *     47 slices · 54,000 lines each · 297 findings
+ *     28 slices · 91,000 lines each · —
+ *     24 slices · 106,000 lines each · 194 findings
+ *      1 slice  · 2,545,000 lines   · 3 findings
+ *
+ * Half the lines per reviewer, half again as many findings. So slices are sized
+ * by line count, and anything over the ceiling is SPLIT — never dropped, and
+ * never merged to tidy a count.
+ *
+ * ─── Usage ──────────────────────────────────────────────────────────────────
+ *   node gsd-t-slice-budget.cjs --project <dir> --slices '<json>' [--min N] [--max N]
+ *
+ *   <json> is the probe's slice list: [{ key, paths: [...], ... }]
+ *
+ * ─── Exit codes ─────────────────────────────────────────────────────────────
+ *   0  a plan was produced (possibly unchanged)
+ *   64 bad input — unreadable project, malformed slice list
+ *
+ * There is no "give up and return the original" path: a slice list that cannot
+ * be measured is an error, not a plan to proceed with.
+ *
+ * Zero dependencies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const EXIT_OK = 0;
+const EXIT_BAD_INPUT = 64;
+
+// Provisional, and recorded as such. 54,000 lines per reviewer produced the best
+// real scan observed; these sit deliberately below it, because that run still
+// cited only 266 of 4,785 files. Nothing yet proves smaller keeps helping — the
+// numbers move when a comparison run says they should.
+const DEFAULT_MIN = 30000;
+const DEFAULT_MAX = 50000;
+
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py']);
+const SKIP_DIRS = new Set([
+  'node_modules', '.next', 'dist', 'build', '.git', '.cache', '__pycache__',
+  'coverage', 'out', '.turbo', '.venv', 'venv', 'Pods', 'vendor', '.gradle',
+]);
+
+/** Lines in one file. A file that cannot be read is reported, never counted as 0. */
+function countLines(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  if (text.length === 0) return 0;
+  let n = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) n++;
+  }
+  if (text.endsWith('\n')) return n;
+  return n + 1;
+}
+
+/** Every source file under a path, with its line count. */
+function measurePath(projectDir, rel, problems) {
+  const abs = path.resolve(projectDir, rel);
+  const out = [];
+
+  let stat;
+  try {
+    stat = fs.statSync(abs);
+  } catch (e) {
+    problems.push(`${rel}: ${(e && e.message) || e}`);
+    return out;
+  }
+
+  if (stat.isFile()) {
+    if (!SOURCE_EXTS.has(path.extname(abs))) return out;
+    try {
+      out.push({ file: path.relative(projectDir, abs), lines: countLines(abs) });
+    } catch (e) {
+      problems.push(`${rel}: ${(e && e.message) || e}`);
+    }
+    return out;
+  }
+
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      // A directory that cannot be read may hold most of a slice. Recorded, so
+      // the caller sees an incomplete measurement rather than a small number.
+      problems.push(`${path.relative(projectDir, dir)}: ${(e && e.message) || e}`);
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        walk(path.join(dir, ent.name));
+        continue;
+      }
+      if (!SOURCE_EXTS.has(path.extname(ent.name))) continue;
+      const full = path.join(dir, ent.name);
+      try {
+        out.push({ file: path.relative(projectDir, full), lines: countLines(full) });
+      } catch (e) {
+        problems.push(`${path.relative(projectDir, full)}: ${(e && e.message) || e}`);
+      }
+    }
+  };
+  walk(abs);
+  return out;
+}
+
+/**
+ * Split one oversized slice into parts that fit the ceiling.
+ *
+ * Files are taken largest-first so a big file settles early and the rest packs
+ * around it; the alternative leaves a huge file for last and forces a part far
+ * over budget.
+ *
+ * A single file larger than the ceiling becomes its OWN part. A file is the
+ * smallest thing a reviewer can read, so the budget cannot be honoured below
+ * that — and pretending otherwise would mean splitting a file mid-function.
+ */
+function splitSlice(slice, files, min, max, oversizedFiles) {
+  const sorted = files.slice().sort((a, b) => b.lines - a.lines);
+  const parts = [];
+  let cur = [];
+  let curLines = 0;
+
+  for (const f of sorted) {
+    if (f.lines > max) {
+      oversizedFiles.push(f);
+      parts.push({ files: [f.file], lines: f.lines, soloOversizedFile: true });
+      continue;
+    }
+    if (curLines + f.lines > max && curLines >= min) {
+      parts.push({ files: cur, lines: curLines });
+      cur = [];
+      curLines = 0;
+    }
+    cur.push(f.file);
+    curLines += f.lines;
+  }
+  if (cur.length) parts.push({ files: cur, lines: curLines });
+
+  // One part means nothing was split — hand the slice back untouched so its
+  // original paths and metadata survive.
+  if (parts.length <= 1) {
+    const total = files.reduce((s, f) => s + f.lines, 0);
+    return [{ ...slice, _lines: total }];
+  }
+
+  return parts.map((p, i) => {
+    const part = {
+      ...slice,
+      key: `${slice.key}-part${i + 1}`,
+      paths: p.files,
+      _lines: p.lines,
+      _splitFrom: slice.key,
+    };
+    if (p.soloOversizedFile) part._soloOversizedFile = true;
+    return part;
+  });
+}
+
+function plan(projectDir, slices, min, max) {
+  const problems = [];
+  const oversizedFiles = [];
+  const out = [];
+  let measuredLines = 0;
+  let measuredFiles = 0;
+
+  for (const slice of slices) {
+    const paths = Array.isArray(slice.paths) ? slice.paths : [];
+    const files = [];
+    const seen = new Set();
+    for (const p of paths) {
+      for (const f of measurePath(projectDir, p, problems)) {
+        // A file listed under two paths of one slice is one file, counted once.
+        if (seen.has(f.file)) continue;
+        seen.add(f.file);
+        files.push(f);
+      }
+    }
+    measuredFiles += files.length;
+    const lines = files.reduce((s, f) => s + f.lines, 0);
+    measuredLines += lines;
+
+    if (lines <= max) {
+      out.push({ ...slice, _lines: lines });
+    } else {
+      out.push(...splitSlice(slice, files, min, max, oversizedFiles));
+    }
+  }
+
+  const sizes = out.map((s) => s._lines).sort((a, b) => a - b);
+  const mean = out.length ? Math.round(measuredLines / out.length) : 0;
+  const median = sizes.length ? sizes[Math.floor(sizes.length / 2)] : 0;
+  const largest = sizes.length ? sizes[sizes.length - 1] : 0;
+
+  return {
+    ok: true,
+    exitCode: EXIT_OK,
+    budget: { min, max, provisional: true },
+    before: { slices: slices.length },
+    after: {
+      slices: out.length,
+      files: measuredFiles,
+      lines: measuredLines,
+      meanLinesPerSlice: mean,
+      medianLinesPerSlice: median,
+      largestSlice: largest,
+      overBudget: out.filter((s) => s._lines > max && !s._soloOversizedFile).length,
+    },
+    // A file bigger than the ceiling cannot be split, so the budget is broken by
+    // the code itself. Named, so it reads as a fact about the codebase rather
+    // than a rule quietly ignored.
+    soloOversizedFiles: oversizedFiles
+      .sort((a, b) => b.lines - a.lines)
+      .map((f) => ({ file: f.file, lines: f.lines })),
+    problems,
+    slices: out,
+  };
+}
+
+function parseArgs(argv) {
+  const args = { project: process.cwd(), min: DEFAULT_MIN, max: DEFAULT_MAX };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') args.project = argv[++i];
+    else if (a === '--slices') args.slices = argv[++i];
+    else if (a === '--slices-file') args.slicesFile = argv[++i];
+    else if (a === '--min') args.min = parseInt(argv[++i], 10);
+    else if (a === '--max') args.max = parseInt(argv[++i], 10);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const fail = (reason) => {
+    process.stdout.write(JSON.stringify({ ok: false, exitCode: EXIT_BAD_INPUT, reason }, null, 2) + '\n');
+    process.exit(EXIT_BAD_INPUT);
+  };
+
+  const projectDir = path.resolve(args.project);
+  if (!fs.existsSync(projectDir)) fail(`project directory not found: ${projectDir}`);
+
+  // Each budget rule checked on its own, so the message names the one that broke.
+  if (!Number.isFinite(args.min)) fail(`--min must be a number, got ${args.min}`);
+  if (!Number.isFinite(args.max)) fail(`--max must be a number, got ${args.max}`);
+  if (args.min <= 0) fail(`--min must be above zero, got ${args.min}`);
+  if (args.max <= args.min) fail(`--max (${args.max}) must be above --min (${args.min})`);
+
+  let raw = args.slices;
+  if (args.slicesFile) {
+    try {
+      raw = fs.readFileSync(args.slicesFile, 'utf8');
+    } catch (e) {
+      fail(`could not read ${args.slicesFile}: ${(e && e.message) || e}`);
+    }
+  }
+  if (!raw) fail('no slices given — pass --slices <json> or --slices-file <path>');
+
+  let slices;
+  try {
+    slices = JSON.parse(raw);
+  } catch (e) {
+    fail(`slices is not valid JSON: ${(e && e.message) || e}`);
+  }
+  if (!Array.isArray(slices)) fail('slices must be an array');
+  if (slices.length === 0) fail('slices must not be empty');
+
+  const result = plan(projectDir, slices, args.min, args.max);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  process.exit(result.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { plan, splitSlice, measurePath, countLines, DEFAULT_MIN, DEFAULT_MAX };

package/bin/gsd-t.js

@@ -1786,6 +1786,9 @@ const GLOBAL_BIN_TOOLS = [
   // this by absolute path, so it MUST ship wherever the verify gate ships or the
   // schema-id check throws ENOENT. Same class as the M99 store-resolver omission below.
   "gsd-t-schema-id-check.cjs",
+  // M112 — measures a slice plan in LINES and splits what is too big. Called by
+  // the scan workflow before any reviewing starts.
+  "gsd-t-slice-budget.cjs",
   // v5.5.10 — PseudoCode §1.1 flow-line style gate (contract v1.2.0). The verify
   // workflow fires it on the same doc set as the guard-map gate, so it must ship
   // wherever verify ships. Also in PROJECT_BIN_TOOLS below — a tool wired into a
@@ -3290,6 +3293,9 @@ const PROJECT_BIN_TOOLS = [
   // it via an absolute path in the Track 2 plan, so a project that has the verify gate
   // but NOT this file gets an ENOENT on every verify. Ships alongside the gate itself.
   "gsd-t-schema-id-check.cjs",
+  // M112 — measures a slice plan in LINES and splits what is too big. Called by
+  // the scan workflow before any reviewing starts.
+  "gsd-t-slice-budget.cjs",
   // M82 — Competition Mode judge + its disjointness oracle dependency, so a
   // project's gsd-t-phase workflow can score candidate partitions via the
   // project-local bin (runCli prefers bin/<tool>.cjs over the global binary).
@@ -5739,6 +5745,22 @@ if (require.main === module) {
       process.exit(res.status == null ? 1 : res.status);
     }
 
+    case "slice-budget": {
+      // M112 — `gsd-t slice-budget --project <dir> --slices <json>` measures a
+      // slice plan in LINES and splits what is over the ceiling. Deterministic:
+      // no agent re-slices, so nothing can be lost or invented.
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-slice-budget.cjs");
+      if (!require("node:fs").existsSync(js)) {
+        error(`gsd-t-slice-budget.cjs not found at ${js} — reinstall GSD-T`);
+        process.exit(1);
+      }
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
+
     case "pseudocode-style": {
       // Contract v1.2.0 §1.1 — `gsd-t pseudocode-style (--doc <f> | --dir <d>)` thin
       // dispatcher to the PseudoCode flow-line STYLE gate. Sibling of `guard-map`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.11.24",
+  "version": "5.11.27",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/workflows/gsd-t-scan.workflow.js

@@ -399,7 +399,7 @@ log(`preflight ok — branch=${pre.branch}, repo=${repoName}, priorRegister=${pr
 
 // Volume probe — an agent measures the codebase (its own Bash) and carves slices.
 phase("Probe");
-const probe = await agent(
+const PROBE_PROMPT =
   [
     `⛔ TARGET DIRECTORY IS FIXED: you MUST scan ONLY the project at the absolute path \`${projectDir}\`. Before any measurement, \`cd ${projectDir}\` (or pass that exact path to every Read/Grep/Bash). Do NOT scan your current working directory, the GSD-T package, or any other tree — every file you measure and every slice path you emit MUST be under \`${projectDir}\`. If \`${projectDir}\` does not exist or is empty, return a single slice noting that.`,
     ``,
@@ -437,14 +437,116 @@ const probe = await agent(
     ``,
     `Measure with real tooling and report in \`totals\`: files, loc, routes, tables, components, featureDomains (distinct business/feature areas). Read \`${projectDir}/package.json\` for the stack. Return JSON per the schema: totals + slices.`,
     SHAPE_RULE,
-  ].join("\n"),
-  { label: "volume-probe", phase: "Probe", schema: PROBE_SCHEMA, model: "sonnet" }
-);
+  ].join("\n");
+
+// Did the probe MEASURE the codebase, or return something shaped like an answer?
+//
+// [RULE] probe-placeholder-is-rejected-not-scanned
+//
+// HiloAviation, 2026-08-11. The probe returned:
+//
+//     totals : {"trackedFiles": 5036}
+//     slices : [{"key": "test", "paths": ["src/"]}]
+//
+// One slice for a 4,900-file application, keyed "test", and a totals object
+// carrying none of the six numbers the prompt asked for. The schema accepted it
+// — one slice is legal, and totals takes any object — so the scan ran that one
+// slice, found 3 findings, and the register's header read "Coverage: FULL".
+//
+// The tell is not the slice count. It is that the fields explicitly named in the
+// prompt are simply absent: the agent produced the SHAPE of an answer without
+// doing the work, the same instinct that sends `{"findings":[]}` through a
+// finder. So the probe result is inspected before it is trusted, and a probe
+// that did not measure is retried on a stronger model rather than scanned.
+function probePlaceholderFaults(result) {
+  const faults = [];
+  const totals = (result && result.totals) || {};
+  const slices = (result && Array.isArray(result.slices) && result.slices) || [];
+
+  // Every number the prompt asks for by name. None present means the agent
+  // reported whatever it had to hand instead of measuring.
+  const asked = ["files", "loc", "routes", "tables", "components", "featureDomains"];
+  const present = asked.filter((k) => totals[k] !== undefined && totals[k] !== null);
+  if (present.length === 0) {
+    faults.push(
+      `totals contains none of the six requested measurements (${asked.join(", ")}) — it holds ` +
+      `${JSON.stringify(totals).slice(0, 160)}`
+    );
+  }
+
+  // A single slice whose path is the whole source tree has decomposed nothing —
+  // but ONLY when the totals are missing too. A small repo genuinely is one
+  // slice covering src/, and halting that scan would be a false alarm on every
+  // small project. What separates the two is whether the agent measured: a real
+  // probe reports the numbers AND explains the single slice. Both tells together
+  // are one judgment, not two independent ones.
+  const WHOLE_TREE = new Set([".", "./", "*", "src", "src/", "./src", "./src/", projectDir]);
+  if (slices.length === 1 && present.length === 0) {
+    const paths = Array.isArray(slices[0].paths) ? slices[0].paths : [];
+    if (paths.length && paths.every((p) => WHOLE_TREE.has(String(p).trim().replace(/\/+$/, "/")) || WHOLE_TREE.has(String(p).trim()))) {
+      faults.push(
+        `the one slice "${slices[0].key}" owns the entire source tree (${JSON.stringify(paths)}) — ` +
+        `that is not a decomposition`
+      );
+    }
+  }
+
+  return faults;
+}
+
+let probe = await agent(PROBE_PROMPT, {
+  label: "volume-probe", phase: "Probe", schema: PROBE_SCHEMA, model: "sonnet",
+});
+
+let probeFaults = probePlaceholderFaults(probe);
+if (probeFaults.length) {
+  log(`⚠ PROBE DID NOT MEASURE — the answer has the right shape but not the work behind it:`);
+  for (const f of probeFaults) log(`   · ${f}`);
+  log(`   retrying on opus with the fault named.`);
+
+  const retry = await agent(
+    [
+      PROBE_PROMPT,
+      ``,
+      `!! A PREVIOUS ATTEMPT AT THIS EXACT TASK WAS REJECTED. What was wrong with it:`,
+      ...probeFaults.map((f) => `   · ${f}`),
+      ``,
+      `RUN THE MEASUREMENTS. Do not answer from a guess, and do not return a minimal stand-in to see whether it is accepted — it will not be.`,
+      `Count the files. Count the lines. Find the routes, the database tables, the components, and the distinct business areas. Those NUMBERS go in \`totals\`.`,
+      `Then carve the codebase into slices by business capability, one slice per real area of the product. A single slice owning the whole tree is not an answer.`,
+    ].join("\n"),
+    { label: "volume-probe (retry on opus)", phase: "Probe", schema: PROBE_SCHEMA, model: "opus" }
+  );
+
+  const retryFaults = probePlaceholderFaults(retry);
+  if (retry && Array.isArray(retry.slices) && retry.slices.length && retryFaults.length === 0) {
+    log(`✓ probe recovered on opus — ${retry.slices.length} slice(s), totals=${JSON.stringify(retry.totals)}`);
+    probe = retry;
+  } else {
+    // Both attempts produced a stand-in. Scanning it would read a fraction of the
+    // codebase and print "Coverage: FULL" over the result — a register that lies
+    // is worse than no register.
+    log(`✗ PROBE FAILED — two attempts, neither measured the codebase.`);
+    for (const f of (retryFaults.length ? retryFaults : probeFaults)) log(`   · ${f}`);
+    return {
+      status: "failed",
+      reason: "probe-placeholder",
+      message:
+        "The probe never measured the codebase, on either attempt. Nothing was scanned: a run on this " +
+        "answer would have covered a fraction of the project while reporting full coverage.",
+      probe: retry || probe,
+    };
+  }
+}
+
 const rawSlices = (probe && Array.isArray(probe.slices) && probe.slices) || [];
 if (!rawSlices.length) {
   log("probe returned no slices — halting");
   return { status: "failed", reason: "no-slices", probe };
 }
+// What the plan actually is, before anything runs on it. A thin plan was only
+// ever visible afterwards, in a thin register.
+log(`probe: ${rawSlices.length} slice(s) — totals=${JSON.stringify(probe.totals || {})}`);
 // Did the probe slice the way it was told? A layer prefix is the tell.
 //
 // The instruction alone is not enough — a prompt is advice, and this axis flipped
@@ -478,123 +580,52 @@ if (layerShaped.length > 2) {
 // So the cap is now on SIZE, and the count follows from it. A slice too large to
 // read is SPLIT, never dropped. More agents is the correct answer to more code.
 const computedCap = computeSliceCap(probe.totals || {});
-const totalFiles = Number((probe.totals || {}).files || (probe.totals || {}).total_files || 0);
-
-// Files one agent can genuinely read and reason about. Above this, enumeration
-// degrades into sampling.
-const MAX_FILES_PER_SLICE = 120;
-
-let slices = rawSlices;
-
-// A count far above the structural estimate means the probe sliced per file or
-// per module rather than by capability — the failure the old cap existed to
-// catch (a 5-file repo cut into ~20 slices). Still worth NAMING, but never worth
-// deleting code over: it is reported and everything still runs.
-// maxSlicesHint used to TRUNCATE here. Nothing may be left out of a scan, so
-// the hint no longer deletes: it is reported and every slice still runs.
-if (maxSlicesOverride && rawSlices.length > maxSlicesOverride) {
-  log(`⚠ maxSlicesHint=${maxSlicesOverride} is below the ${rawSlices.length} slices the probe found. IGNORING it — dropping slices would leave code unscanned. Running all ${rawSlices.length}.`);
-} else if (rawSlices.length > computedCap * 2) {
-  log(`⚠ probe returned ${rawSlices.length} slices against a structural estimate of ~${computedCap} — it may have sliced per file/module rather than by capability. Running all ${rawSlices.length} anyway: dropping a slice would silently remove code from the scan.`);
-}
-
-// Slices too big to read honestly. The probe owns the split (it knows the
-// paths); this reports the ones that will under-read so it is visible in the
-// log rather than hidden in a thin finding count.
-if (totalFiles > 0 && slices.length > 0) {
-  const avgFiles = Math.round(totalFiles / slices.length);
-  if (avgFiles > MAX_FILES_PER_SLICE) {
-    // Warning about it is not enough — the run would go on and under-read every
-    // slice. Send the decomposition back to be split, and use the result.
-    const wanted = Math.ceil(totalFiles / MAX_FILES_PER_SLICE);
-    log(`⚠ SLICES TOO LARGE TO ENUMERATE — ~${avgFiles} files each across ${slices.length} slices (${totalFiles} files). The finder must read EVERY file; above ~${MAX_FILES_PER_SLICE} it samples instead, and a sampled slice reports fewer findings while looking complete. Re-slicing to ~${wanted}.`);
-
-    const resliced = await gatedAgent(
-      [
-        `Re-slice a codebase decomposition that came out too coarse. Project: \`${projectDir}\`.`,
-        ``,
-        `Here are the current slices — ${slices.length} of them, averaging ~${avgFiles} files each:`,
-        JSON.stringify(slices.map((sl) => ({ key: sl.key, paths: sl.paths, dimension: sl.dimension })), null, 1),
-        ``,
-        `Each slice is read by ONE agent that must open EVERY file it owns. At ~${avgFiles} files that is not possible, so those agents will sample and report a thin slice as a clean one.`,
-        `SPLIT them so no slice exceeds ~${MAX_FILES_PER_SLICE} files. Target roughly ${wanted} slices in total.`,
-        ``,
-        `RULES:`,
-        `· Split along the feature's own seams, still VERTICALLY: "billing-invoicing" and "billing-payments", never "billing-routes" and "billing-schema".`,
-        `· EVERY path in the input must appear in exactly one output slice. Losing a path removes that code from the scan entirely.`,
-        `· Never merge two slices to tidy the count. Splitting is the only operation here.`,
-        `· A slice already under ~${MAX_FILES_PER_SLICE} files passes through unchanged.`,
-        `Return the full new slice list — every slice, not only the ones you split.`,
-        SHAPE_RULE,
-      ].join("\n"),
-      { label: "probe:reslice", phase: "Probe", schema: PROBE_SCHEMA, model: "opus" }
-    );
-
-    const newSlices = (resliced && Array.isArray(resliced.slices) && resliced.slices) || [];
-    // Accept it only if it is genuinely finer AND kept the paths. A re-slice
-    // that lost code would be worse than the coarse decomposition it replaced.
-    const pathsBefore = new Set(slices.flatMap((sl) => sl.paths || []));
-    const pathsAfter  = new Set(newSlices.flatMap((sl) => sl.paths || []));
-    const lost = [...pathsBefore].filter((x) => !pathsAfter.has(x));
-
-    if (newSlices.length > slices.length && lost.length === 0) {
-      log(`✓ re-sliced ${slices.length} → ${newSlices.length} slices (~${Math.round(totalFiles / newSlices.length)} files each), every path preserved`);
-      slices = newSlices;
-    } else {
-      // A rejected re-slice leaves the scan under-reading every slice — that is
-      // continuing past a failure, so it gets a second try that names exactly
-      // what went wrong, on the same model. If that fails too, the slices are
-      // split MECHANICALLY below: a crude split that reads every file beats a
-      // tidy one that reads half.
-      const why = newSlices.length <= slices.length
-        ? `it returned ${newSlices.length} slices — no finer than the ${slices.length} it was given`
-        : `it dropped ${lost.length} path(s): ${lost.slice(0, 6).join(", ")}${lost.length > 6 ? ", …" : ""}`;
-      log(`⚠ re-slice attempt 1 rejected — ${why}. Retrying with the fault named.`);
-
-      const retry = await gatedAgent(
-        [
-          `Your previous re-slice was REJECTED because ${why}.`,
-          ``,
-          `Split these ${slices.length} slices so none exceeds ~${MAX_FILES_PER_SLICE} files. Target ~${wanted} slices.`,
-          JSON.stringify(slices.map((sl) => ({ key: sl.key, paths: sl.paths, dimension: sl.dimension })), null, 1),
-          ``,
-          `The output MUST contain more slices than the input, and EVERY input path must appear in exactly one output slice. Splitting is the only operation — never merge, never drop.`,
-          `Split along the feature's own seams, still vertically.`,
-          SHAPE_RULE,
-        ].join("\n"),
-        { label: "probe:reslice (retry)", phase: "Probe", schema: PROBE_SCHEMA, model: "opus" }
-      );
-
-      const retrySlices = (retry && Array.isArray(retry.slices) && retry.slices) || [];
-      const retryAfter  = new Set(retrySlices.flatMap((sl) => sl.paths || []));
-      const retryLost   = [...pathsBefore].filter((x) => !retryAfter.has(x));
+// ── Size every slice in LINES, and split what is too big ────────────────────
+//
+// Files are a terrible measure of how much code a reviewer was handed: in the
+// HiloAviation codebase the median source file is 233 lines and the largest is
+// 23,664. The previous check counted files and asked an agent to re-slice; both
+// were wrong. Lines track what actually happened across three real scans:
+//
+//     47 slices ·    54,000 lines each · 297 findings
+//     24 slices ·   106,000 lines each · 194 findings
+//      1 slice  · 2,545,000 lines      ·   3 findings
+//
+// Splitting is DETERMINISTIC now — bin/gsd-t-slice-budget.cjs measures real
+// files and packs them under a ceiling. No agent re-slices, so nothing can be
+// lost, invented, or returned no finer than it was given.
+const budgetPlan = await runCli(
+  "slice-budget",
+  ["--project", projectDir, "--slices", JSON.stringify(rawSlices.map((sl) => ({
+    key: sl.key, paths: sl.paths, dimension: sl.dimension, why: sl.why,
+  })))],
+  "slice-budget"
+);
 
-      if (retrySlices.length > slices.length && retryLost.length === 0) {
-        log(`✓ re-slice retry succeeded — ${slices.length} → ${retrySlices.length} slices, every path preserved`);
-        slices = retrySlices;
-      } else {
-        // Mechanical split: divide each oversized slice's own paths into chunks.
-        // No agent, no judgement, no way to lose a path — every path lands in
-        // exactly one chunk because the chunks ARE the path list, cut up.
-        const split = [];
-        for (const sl of slices) {
-          const paths = sl.paths || [];
-          const share = Math.max(1, Math.round((paths.length / Math.max(pathsBefore.size, 1)) * totalFiles));
-          const parts = Math.ceil(share / MAX_FILES_PER_SLICE);
-          if (parts <= 1 || paths.length <= 1) { split.push(sl); continue; }
-          const per = Math.ceil(paths.length / parts);
-          for (let i = 0; i < paths.length; i += per) {
-            split.push({ ...sl, key: `${sl.key}-part${Math.floor(i / per) + 1}`, paths: paths.slice(i, i + per) });
-          }
-        }
-        log(`⚠ both re-slice attempts rejected — splitting mechanically instead: ${slices.length} → ${split.length} slices. Crude, but every path is still scanned and no slice is too large to read.`);
-        slices = split;
-      }
-    }
+if (budgetPlan && budgetPlan.ok && Array.isArray(budgetPlan.slices) && budgetPlan.slices.length) {
+  const a = budgetPlan.after || {};
+  if (budgetPlan.slices.length > rawSlices.length) {
+    log(`✂ slice budget: ${rawSlices.length} → ${budgetPlan.slices.length} slices (${(a.lines || 0).toLocaleString()} lines, ~${(a.meanLinesPerSlice || 0).toLocaleString()} per slice, ceiling ${(budgetPlan.budget || {}).max}). A reviewer must read every file it owns; a slice too large is read by sampling, and a sampled slice reports few findings while looking complete.`);
+  } else {
+    log(`slice budget: ${budgetPlan.slices.length} slice(s), ~${(a.meanLinesPerSlice || 0).toLocaleString()} lines each — all within the ${(budgetPlan.budget || {}).max}-line ceiling.`);
   }
+  for (const f of (budgetPlan.soloOversizedFiles || []).slice(0, 5)) {
+    log(`  · ${f.file} is ${f.lines.toLocaleString()} lines — larger than the whole ceiling, so it is its own slice. The budget cannot go below one file.`);
+  }
+  for (const prob of (budgetPlan.problems || []).slice(0, 5)) {
+    log(`  ⚠ slice budget could not measure ${prob}`);
+  }
+  slices = budgetPlan.slices;
+} else {
+  // Measuring failed. Continuing would hand reviewers slices of unknown size —
+  // exactly the state that produced a 2.5-million-line "slice" reporting three
+  // findings under a FULL coverage header.
+  log(`⚠ SLICE BUDGET FAILED [${(budgetPlan && budgetPlan.reason) || "no-result"}] — slice sizes are UNMEASURED. Running the probe's slices as given; if any is oversized its reviewer will sample rather than read.`);
 }
 
-log(`probe derived ${rawSlices.length} slice(s); running ${slices.length} deep-finder(s)${totalFiles ? `; ~${Math.round(totalFiles / Math.max(slices.length, 1))} files/slice` : ""}; structural estimate=${computedCap}; totals=${JSON.stringify(probe.totals)}`);
+const totalFiles = Number((budgetPlan && budgetPlan.after && budgetPlan.after.files) || (probe.totals || {}).files || 0);
+const totalLines = Number((budgetPlan && budgetPlan.after && budgetPlan.after.lines) || 0);
+log(`probe derived ${rawSlices.length} slice(s); running ${slices.length} deep-finder(s)${totalLines ? `; ${totalLines.toLocaleString()} lines, ~${Math.round(totalLines / Math.max(slices.length, 1)).toLocaleString()} per slice` : ""}${totalFiles ? `; ${totalFiles} files` : ""}; totals=${JSON.stringify(probe.totals)}`);
 
 // M94-D6: Graph-Wiring phase — ADDITIVE injection of the pre-computed structural slice.
 // Current scan architecture is KEPT FULLY INTACT (Destructive Action Guard).