@tekyzinc/gsd-t 4.7.11 → 4.9.11

package/bin/gsd-t-milestone-state.cjs

@@ -0,0 +1,236 @@
+"use strict";
+
+/**
+ * gsd-t-milestone-state — M88 G1 (m88-signoff-state)
+ *
+ * A machine-checkable milestone sign-off STATE + the `isDefined(milestone)`
+ * predicate. Today "DEFINED" is prose an LLM writes into `.gsd-t/progress.md` —
+ * NOT a code-readable marker. This module reads a CONCRETE, structured sign-off
+ * marker at the head of the detailed `PseudoCode-[Title].md` and decides, with
+ * ZERO LLM judgment, whether a milestone's pseudocode set is signed off.
+ *
+ * The marker is a STRUCTURED front-matter HTML comment at the doc head:
+ *
+ *     <!-- signed-off: <ISO-date> by <author> -->
+ *
+ * It is PARSED by its structural form (regex on the marker shape), never by a
+ * prose substring scan (`feedback_coverage_check_structural_not_substring`).
+ * An absent OR malformed marker is FAIL-CLOSED → `signed:false` (never a crash,
+ * never a vacuous pass). A skip is NEVER a silent default-off — `recordSkip`
+ * emits an ASSERTABLE, greppable logged decision (`feedback_no_silent_degradation`).
+ *
+ * Contract: .gsd-t/contracts/pseudocode-source-of-truth-contract.md §1
+ * (doc anatomy — the two altitudes; High-Level signed off FIRST, then Detailed).
+ *
+ * ── INTEGRATION NOTE (for a later doc-ripple pass — NOT done here) ──────────
+ * This domain ships the predicate ONLY. It does NOT edit `commands/gsd-t-milestone.md`
+ * (D3-owned). When that doc-ripple pass runs, the milestone command's "DEFINED"
+ * emission should call `isDefined(<the milestone's detailed PseudoCode doc paths>)`
+ * and refuse to flip a milestone to DEFINED until the predicate returns true —
+ * replacing the prose "DEFINED" an LLM writes into progress.md with this
+ * code-readable gate. A deliberate skip MUST route through `recordSkip` so the
+ * decision is logged + greppable, never a silent default-off.
+ *
+ * Hard engineering bar (mirror M87 D1 guard-map): zero deps (Node built-ins
+ * only), never throws (bad input → exitCode 64, never an uncaught throw),
+ * pure/read-only (writes nothing). Deterministic — ZERO LLM judgment.
+ *
+ * CLI:
+ *   --doc <path> [--json]                  → readSignoff over one detailed doc
+ *   --docs <comma-list> [--json]           → isDefined over a doc set
+ *   --skip <milestone> --reason <text>     → recordSkip (assertable decision)
+ *
+ * Exit: 0 signed / defined / skip-recorded · 4 unsigned / NOT-defined · 64 bad input.
+ */
+
+const fs = require("node:fs");
+
+// ─── sign-off marker grammar (structural, NOT prose substring) ─────────────
+//
+// `<!-- signed-off: <ISO-date> by <author> -->`
+//   <ISO-date> : YYYY-MM-DD, optionally with a time/zone tail (ISO 8601-ish).
+//   <author>   : a non-empty author token/phrase (everything up to the `-->`).
+//
+// Anchored to the marker FORM, not to a "signed-off" substring anywhere in
+// prose: the keyword must sit inside an `<!-- ... -->` HTML comment AND be
+// followed by a structurally-valid date + ` by ` + non-empty author. A bare
+// `<!-- signed-off: -->` (no date) does NOT match → fail-closed (unsigned).
+const SIGNOFF_RE =
+  /<!--\s*signed-off:\s*(\d{4}-\d{2}-\d{2}(?:[T ][0-9:.+\-Z]*)?)\s+by\s+(\S.*?)\s*-->/i;
+
+/**
+ * Parse the sign-off marker from a detailed doc's text. Structural-only.
+ * @param {string} md - the doc text (may be null/undefined → unsigned).
+ * @returns {{signed: boolean, date: (string|null), author: (string|null)}}
+ */
+function parseSignoff(md) {
+  const text = md == null ? "" : String(md);
+  const m = text.match(SIGNOFF_RE);
+  if (!m) return { signed: false, date: null, author: null };
+  const date = (m[1] || "").trim();
+  const author = (m[2] || "").trim();
+  // Defense in depth: both date AND a non-empty author are required. An empty
+  // author (regex can't capture one) means malformed → fail-closed.
+  if (!date || !author) return { signed: false, date: null, author: null };
+  return { signed: true, date, author };
+}
+
+/**
+ * Read the sign-off marker from a detailed PseudoCode doc on disk.
+ * Never throws — an unreadable/missing path is fail-closed (unsigned).
+ * @param {string} docPath
+ * @returns {{signed: boolean, date: (string|null), author: (string|null), doc: (string|null), error?: string}}
+ */
+function readSignoff(docPath) {
+  if (!docPath || typeof docPath !== "string") {
+    return { signed: false, date: null, author: null, doc: null, error: "no doc path" };
+  }
+  let md;
+  try {
+    md = fs.readFileSync(docPath, "utf8");
+  } catch (e) {
+    // Missing / unreadable doc = NOT signed (fail-closed), never a throw.
+    return { signed: false, date: null, author: null, doc: docPath, error: `cannot read doc: ${e && e.message}` };
+  }
+  const parsed = parseSignoff(md);
+  return { ...parsed, doc: docPath };
+}
+
+/**
+ * The `isDefined` predicate. A milestone's pseudocode is DEFINED IFF EVERY
+ * detailed doc in the set carries a valid sign-off marker. ANY unsigned (or
+ * absent/malformed) doc → NOT-DEFINED (false). An EMPTY set is NOT defined
+ * (there is nothing signed off to define it — fail-closed, never vacuous-true).
+ * @param {string[]} milestoneDocs - detailed PseudoCode doc paths.
+ * @returns {{defined: boolean, total: number, signed: number, docs: Array, unsigned: string[]}}
+ */
+function isDefined(milestoneDocs) {
+  const docs = Array.isArray(milestoneDocs) ? milestoneDocs : [];
+  const results = docs.map((d) => readSignoff(d));
+  const unsigned = results.filter((r) => !r.signed).map((r) => r.doc);
+  const signedCount = results.length - unsigned.length;
+  // Empty set → NOT defined (no signed docs ⇒ nothing defines the milestone).
+  const defined = results.length > 0 && unsigned.length === 0;
+  return {
+    defined,
+    total: results.length,
+    signed: signedCount,
+    docs: results.map((r) => ({ doc: r.doc, signed: r.signed, date: r.date, author: r.author })),
+    unsigned,
+  };
+}
+
+/**
+ * Record a deliberate skip of the sign-off gate as an ASSERTABLE, greppable
+ * logged decision — NEVER a silent default-off. Returns a structured object
+ * whose `decision` line is a single greppable string containing the milestone
+ * AND the reason (so a test / grep can prove the skip is observable).
+ * @param {string} milestone - the milestone id being skipped.
+ * @param {string} reason - the human-supplied justification (required).
+ * @returns {{ok: boolean, kind: "milestone-signoff-skip", milestone: (string|null), reason: (string|null), decision: string}}
+ */
+function recordSkip(milestone, reason) {
+  const ms = milestone == null ? "" : String(milestone).trim();
+  const rs = reason == null ? "" : String(reason).trim();
+  // A skip with no reason is itself fail-closed: still emitted + assertable, but
+  // flagged ok:false so the gate cannot treat a reasonless skip as a clean pass.
+  const ok = ms.length > 0 && rs.length > 0;
+  const decision = `[GSD-T SIGNOFF-SKIP] milestone=${ms || "<none>"} reason=${rs || "<none>"}`;
+  return { ok, kind: "milestone-signoff-skip", milestone: ms || null, reason: rs || null, decision };
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const o = { doc: null, docs: null, skip: null, reason: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") o.help = true;
+    else if (a === "--doc") o.doc = argv[++i];
+    else if (a === "--docs") o.docs = argv[++i];
+    else if (a === "--skip") o.skip = argv[++i];
+    else if (a === "--reason") o.reason = argv[++i];
+    else if (a === "--json") {/* default output is JSON */}
+  }
+  return o;
+}
+
+const HELP = `Usage:
+  gsd-t milestone-state --doc <PseudoCode-[Title].md> [--json]   read one doc's sign-off
+  gsd-t milestone-state --docs <p1,p2,...> [--json]             isDefined over a set
+  gsd-t milestone-state --skip <milestone> --reason <text>      record an assertable skip
+
+The M88 milestone sign-off state. A milestone is NOT DEFINED until every detailed
+PseudoCode-[Title].md carries a structured sign-off marker:
+
+  <!-- signed-off: <ISO-date> by <author> -->
+
+Parsing is structural (marker form), not a prose substring scan. An absent or
+malformed marker is fail-closed (unsigned). A skip is a LOGGED, greppable
+decision, never a silent default-off.
+
+Exit: 0 signed/defined/skip-recorded · 4 unsigned/NOT-defined · 64 bad input.`;
+
+/**
+ * Run the CLI for one parsed arg set. Never throws — bad input → exitCode 64.
+ * @param {object} o - parsed args.
+ * @returns {{ok: boolean, exitCode: number, ...}}
+ */
+function runCli(o) {
+  const opts = o && typeof o === "object" ? o : {};
+
+  // recordSkip mode
+  if (opts.skip != null) {
+    const res = recordSkip(opts.skip, opts.reason);
+    // A reasonless skip is bad input (64) — the decision is still emitted so it
+    // stays assertable, but the gate must not treat it as a clean exit.
+    return { ...res, exitCode: res.ok ? 0 : 64 };
+  }
+
+  // isDefined mode (a set of docs)
+  if (opts.docs != null) {
+    const list = String(opts.docs)
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    if (list.length === 0) {
+      return { ok: false, exitCode: 64, reason: "--docs given but resolved to an empty list" };
+    }
+    const res = isDefined(list);
+    return { ok: res.defined, exitCode: res.defined ? 0 : 4, ...res };
+  }
+
+  // readSignoff mode (one doc)
+  if (opts.doc != null) {
+    const res = readSignoff(opts.doc);
+    return { ok: res.signed, exitCode: res.signed ? 0 : 4, ...res };
+  }
+
+  return { ok: false, exitCode: 64, reason: "no mode: pass --doc, --docs, or --skip" };
+}
+
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) { process.stdout.write(HELP + "\n"); process.exit(0); }
+  let res;
+  try {
+    res = runCli(o);
+  } catch (e) {
+    // Defense in depth — runCli is written never to throw; the contract mandates
+    // the module never throws, so any unexpected error maps to 64.
+    res = { ok: false, exitCode: 64, reason: `state-error: ${e && e.message}` };
+  }
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  readSignoff,
+  parseSignoff,
+  isDefined,
+  recordSkip,
+  runCli,
+  _internal: { SIGNOFF_RE },
+};

package/bin/gsd-t-rule-consume.cjs

@@ -0,0 +1,141 @@
+"use strict";
+
+/**
+ * gsd-t-rule-consume — M88 G3 (triad-consumption seam)
+ *
+ * The DETERMINISTIC half of the A5 reframe. A5 once read "the `[RULE]` set is
+ * consumed by verify's QA + Red Team frames" — a non-deterministic LIVE-triad
+ * observation. This module reframes the CONSUMER side as a pure, deterministic
+ * seam: given the guard-map JSON (`{rules:{<id>:...}}` from gsd-t-guard-map.cjs),
+ * it surfaces the RULE-ID set that each verify frame must ingest.
+ *
+ * The seam invariant (A5): EVERY rule id in the map surfaces in BOTH frames —
+ *   - `qa`      → the QA contract-compliance frame (each rule = a compliance assertion)
+ *   - `redTeam` → the Red Team attack-surface frame (each rule = an invariant to attack)
+ * A rule that reaches the map but is DROPPED from either frame breaks the seam
+ * (the rule set failed to reach the whole triad). The killing test asserts this.
+ *
+ * Hard engineering bar (mirror gsd-t-guard-map.cjs): zero deps (Node built-ins
+ * only), NEVER throws, pure/read-only (writes nothing). Fail-closed: an
+ * empty/malformed map yields EMPTY frame sets (`{qa:[], redTeam:[]}`), never a
+ * throw and never a phantom id.
+ *
+ * Input:  --map <path> [--json]
+ * Output: JSON envelope { ok, exitCode, qa, redTeam, ... }.
+ * Exit:   0 ok (sets surfaced, possibly empty) · 64 bad input (cannot read map).
+ */
+
+const fs = require("node:fs");
+
+/**
+ * Extract the ordered, de-duplicated RULE-ID set from a guard-map object.
+ * Pure. Never throws. A non-object, a missing/non-object `rules`, or a
+ * malformed shape → empty array (fail-closed — no phantom ids).
+ * @param {*} map - parsed guard-map object ({ rules: { <id>: {...} } })
+ * @returns {string[]} the rule ids in stable insertion order, de-duplicated
+ */
+function ruleIds(map) {
+  if (!map || typeof map !== "object") return [];
+  const rules = map.rules;
+  if (!rules || typeof rules !== "object") return [];
+  const seen = new Set();
+  const ids = [];
+  for (const key of Object.keys(rules)) {
+    const id = String(key);
+    if (id.length === 0 || seen.has(id)) continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Surface the rule-id set into BOTH verify frames. Pure. The seam: every id
+ * appears in `qa` AND `redTeam` — same set, two frame views. A dropped id in
+ * either frame is the failure the seam-check catches.
+ * @param {*} map - parsed guard-map object
+ * @returns {{ qa: string[], redTeam: string[] }}
+ */
+function consume(map) {
+  const ids = ruleIds(map);
+  // Independent copies so a mutation of one frame can never silently alias the other.
+  return { qa: ids.slice(), redTeam: ids.slice() };
+}
+
+// ─── driver ────────────────────────────────────────────────────────────────
+
+/**
+ * Run the consumer over a map path. Never throws — bad input → exitCode 64
+ * with EMPTY frame sets (fail-closed).
+ * @param {{ map: string|null }} o
+ * @returns {{ ok, exitCode, qa, redTeam, ... }}
+ */
+function runConsume(o) {
+  const { map } = (o && typeof o === "object") ? o : {};
+  if (!map || typeof map !== "string") {
+    return { ok: false, exitCode: 64, reason: "missing --map", qa: [], redTeam: [], map: map || null };
+  }
+
+  let mapObj;
+  try {
+    mapObj = JSON.parse(fs.readFileSync(map, "utf8"));
+  } catch (e) {
+    // Fail-closed: unreadable / unparseable map → empty sets, no throw.
+    return { ok: false, exitCode: 64, reason: `cannot read/parse map JSON: ${e && e.message}`, qa: [], redTeam: [], map };
+  }
+
+  const frames = consume(mapObj);
+  return {
+    ok: true,
+    exitCode: 0,
+    map,
+    ruleCount: frames.qa.length,
+    qa: frames.qa,
+    redTeam: frames.redTeam,
+  };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const o = { map: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") o.help = true;
+    else if (a === "--map") o.map = argv[++i];
+    else if (a === "--json") {/* default output is JSON */}
+  }
+  return o;
+}
+
+const HELP = `Usage: gsd-t rule-consume --map <guard-map.json> [--json]
+
+The M88 G3 triad-consumption seam (A5). Reads the guard-map JSON and surfaces
+the RULE-ID set into both verify frames — every id appears in BOTH the QA
+contract-compliance frame and the Red Team attack-surface frame. A dropped id
+breaks the seam (caught by test/m88-triad-consumption-seam.test.js).
+Deterministic, zero LLM judgment, fail-closed (empty/malformed map → empty sets).
+
+  --map PATH   the guard-map JSON ({ "rules": { "<id>": {...} } }).
+
+Output: { "ok", "exitCode", "qa": [...ids], "redTeam": [...ids] }.
+Exit: 0 ok (sets surfaced) · 64 bad input (map unreadable → empty sets).`;
+
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) { process.stdout.write(HELP + "\n"); process.exit(0); }
+  let res;
+  try {
+    res = runConsume(o);
+  } catch (e) {
+    // Defense in depth — runConsume never throws, but the contract mandates the
+    // module never throws, so any escape maps to 64 with empty sets.
+    res = { ok: false, exitCode: 64, reason: `consume-error: ${e && e.message}`, qa: [], redTeam: [] };
+  }
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { runConsume, consume, ruleIds };

package/bin/gsd-t-shrink-metric.cjs

@@ -0,0 +1,255 @@
+"use strict";
+
+/**
+ * gsd-t-shrink-metric — M92 D2 (shrink-verdict, the keystone move)
+ *
+ * A deterministic leanness readout for a change. Today verify's `overallVerdict`
+ * is a pure AND of additive gates — the schema literally CANNOT say "we made it
+ * smaller." This module measures the change's net size from a `git diff --numstat`
+ * envelope so a NET-NEGATIVE (leaner) change becomes a first-class, ORTHOGONAL
+ * success dimension surfaced ALONGSIDE the pass/fail enum (never folded into it).
+ *
+ * MEASURED, not attested ([[feedback_measure_dont_claim]]): leanness comes from
+ * `git diff --numstat`, never an LLM judgment.
+ *
+ * Output: { filesAdded, filesRemoved, filesModified, insertions, deletions, netLoc, leaner }
+ *   netLoc = insertions - deletions
+ *   leaner = netLoc <= 0   (removed at least as much as it added)
+ *
+ * Input — EITHER:
+ *   --numstat <path|->   parse a PRE-CAPTURED `git diff --numstat` string (testable
+ *                        with no repo; `-` reads stdin).
+ *   --range <base>..<head> --project-dir <p>   compute LIVE (runs git itself).
+ *
+ * numstat grammar (porcelain `git diff --numstat`): one line per path,
+ *   <insertions>\t<deletions>\t<path>
+ * where a BINARY file emits `-\t-\t<path>` (no textual LOC — counted as a modified
+ * file with 0 loc contribution). File add/remove/modify is inferred from the
+ * `--numstat` line alone WITHOUT a name-status pass:
+ *   - deletions>0 AND insertions==0  → a file with only removals  → filesRemoved
+ *   - insertions>0 AND deletions==0  → a file with only additions → filesAdded
+ *   - both>0, OR a binary line       → filesModified
+ * (This is a heuristic over numstat: a wholly-new file shows insertions/0, a wholly-
+ * deleted file shows 0/deletions. It is deterministic and sufficient for the leanness
+ * readout; netLoc/leaner — the load-bearing signal — are EXACT regardless of the
+ * add/remove/modify split.)
+ *
+ * Hard engineering bar (mirror gsd-t-guard-map.cjs): zero deps (Node built-ins
+ * only), never throws (bad input → exitCode 64, never an uncaught throw),
+ * pure parsing. Deterministic — ZERO LLM judgment.
+ *
+ * Exit: 0 metric computed · 64 bad input.
+ */
+
+const fs = require("node:fs");
+const { execFileSync } = require("node:child_process");
+
+// ─── numstat parsing (pure) ────────────────────────────────────────────────
+
+/**
+ * Parse a `git diff --numstat` string into the shrink metric. Pure; never throws.
+ * @param {string} numstat - raw numstat text
+ * @returns {{ filesAdded, filesRemoved, filesModified, insertions, deletions, netLoc, leaner, files }}
+ */
+function parseNumstat(numstat) {
+  const text = String(numstat == null ? "" : numstat);
+  const lines = text.split(/\r?\n/);
+
+  let filesAdded = 0;
+  let filesRemoved = 0;
+  let filesModified = 0;
+  let insertions = 0;
+  let deletions = 0;
+  let files = 0;
+
+  for (const raw of lines) {
+    const line = raw.replace(/\r$/, "");
+    if (line.trim() === "") continue;
+    // numstat columns are TAB-separated: <ins>\t<del>\t<path>. Be tolerant of
+    // runs of whitespace (git uses a single tab, but stay robust).
+    const m = line.match(/^\s*(-|\d+)\s+(-|\d+)\s+(.+)$/);
+    if (!m) {
+      // A non-empty line that is not a numstat row → malformed input.
+      return { _malformed: true, badLine: line.slice(0, 200) };
+    }
+    files += 1;
+    const insTok = m[1];
+    const delTok = m[2];
+    const binary = insTok === "-" || delTok === "-";
+
+    if (binary) {
+      // A binary change: counted as a modified file, 0 textual loc contribution.
+      filesModified += 1;
+      continue;
+    }
+
+    const ins = Number(insTok);
+    const del = Number(delTok);
+    // Number() of a \d+ token is always a finite non-negative integer here.
+    insertions += ins;
+    deletions += del;
+
+    if (del > 0 && ins === 0) filesRemoved += 1;
+    else if (ins > 0 && del === 0) filesAdded += 1;
+    else filesModified += 1; // both>0, or 0/0 (an empty/mode-only change)
+  }
+
+  const netLoc = insertions - deletions;
+  return {
+    filesAdded,
+    filesRemoved,
+    filesModified,
+    insertions,
+    deletions,
+    netLoc,
+    leaner: netLoc <= 0,
+    files,
+  };
+}
+
+// ─── live git (only on the --range path) ───────────────────────────────────
+
+/**
+ * Capture `git diff --numstat <range>` for a project. Returns { ok, numstat } or
+ * { ok:false, reason }. Never throws.
+ * @param {string} range - e.g. "<base>..HEAD"
+ * @param {string} projectDir
+ */
+function captureNumstat(range, projectDir) {
+  // SECURITY (M92 Red Team BUG-1, [[feedback_defense_in_depth_at_adapters]]):
+  // `execFileSync` blocks SHELL injection but NOT git-ARGUMENT injection — a range
+  // beginning with `-` is parsed by git as an OPTION (e.g. `--output=<path>` makes
+  // git OVERWRITE an arbitrary file). The range is LLM-derived upstream (verify
+  // computes the base via a haiku agent), so it is untrusted. Reject any
+  // dash-leading / non-string / empty range BEFORE the git call. The trailing `--`
+  // is defense-in-depth (NOT sufficient alone — `--output` is honored before `--`).
+  if (typeof range !== "string" || range === "" || range.startsWith("-")) {
+    return { ok: false, reason: `invalid range (refused: must be a non-empty, non-option string): ${JSON.stringify(range)}` };
+  }
+  try {
+    const out = execFileSync("git", ["diff", "--numstat", range, "--"], {
+      cwd: projectDir || ".",
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true, numstat: out };
+  } catch (e) {
+    return { ok: false, reason: `git diff failed: ${(e && e.message) || "unknown"}` };
+  }
+}
+
+function readNumstatFile(p) {
+  // `-` → stdin (fd 0). Otherwise a path.
+  if (p === "-") return fs.readFileSync(0, "utf8");
+  return fs.readFileSync(p, "utf8");
+}
+
+// ─── driver ─────────────────────────────────────────────────────────────────
+
+/**
+ * Compute the shrink metric from options. Never throws — bad input → exitCode 64.
+ * @param {{ numstat?:string, range?:string, projectDir?:string }} o
+ * @returns {{ ok, exitCode, ... }}
+ */
+function runMetric(o) {
+  const opt = (o && typeof o === "object") ? o : {};
+  const hasNumstat = typeof opt.numstat === "string" && opt.numstat.length > 0;
+  const hasRange = typeof opt.range === "string" && opt.range.length > 0;
+
+  if (!hasNumstat && !hasRange) {
+    return { ok: false, exitCode: 64, reason: "need --numstat <path|-> OR --range <base>..<head>" };
+  }
+  if (hasNumstat && hasRange) {
+    return { ok: false, exitCode: 64, reason: "give EITHER --numstat OR --range, not both" };
+  }
+
+  let numstatText;
+  let source;
+  if (hasNumstat) {
+    source = `numstat:${opt.numstat}`;
+    try {
+      numstatText = readNumstatFile(opt.numstat);
+    } catch (e) {
+      return { ok: false, exitCode: 64, reason: `cannot read --numstat input: ${(e && e.message) || "unknown"}`, source };
+    }
+  } else {
+    source = `range:${opt.range}`;
+    const cap = captureNumstat(opt.range, opt.projectDir);
+    if (!cap.ok) {
+      // A git failure on the live path is BAD INPUT (unresolvable range / not a repo)
+      // → exit 64. The verify workflow turns this into a logged skip-with-reason,
+      // never a fabricated metric.
+      return { ok: false, exitCode: 64, reason: cap.reason, source };
+    }
+    numstatText = cap.numstat;
+  }
+
+  const parsed = parseNumstat(numstatText);
+  if (parsed._malformed) {
+    return { ok: false, exitCode: 64, reason: `malformed numstat line: "${parsed.badLine}"`, source };
+  }
+
+  return {
+    ok: true,
+    exitCode: 0,
+    source,
+    filesAdded: parsed.filesAdded,
+    filesRemoved: parsed.filesRemoved,
+    filesModified: parsed.filesModified,
+    insertions: parsed.insertions,
+    deletions: parsed.deletions,
+    netLoc: parsed.netLoc,
+    leaner: parsed.leaner,
+    files: parsed.files,
+  };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const o = { numstat: null, range: null, projectDir: ".", help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") o.help = true;
+    else if (a === "--numstat") o.numstat = argv[++i];
+    else if (a === "--range") o.range = argv[++i];
+    else if (a === "--project-dir" || a === "--projectDir") o.projectDir = argv[++i];
+    else if (a === "--json") {/* default output is JSON */}
+  }
+  return o;
+}
+
+const HELP = `Usage:
+  gsd-t shrink-metric --numstat <path|->            [--json]
+  gsd-t shrink-metric --range <base>..<head> --project-dir <p> [--json]
+
+The M92 shrink-metric (D2). Computes a deterministic leanness readout from a
+\`git diff --numstat\` envelope: { filesAdded, filesRemoved, filesModified,
+insertions, deletions, netLoc, leaner } where netLoc = insertions - deletions and
+leaner = netLoc <= 0. MEASURED, zero LLM judgment.
+
+  --numstat PATH   parse a pre-captured \`git diff --numstat\` string (\`-\` = stdin).
+  --range R        compute live: runs \`git diff --numstat <R>\` in --project-dir.
+  --project-dir P  cwd for the live --range git call (default ".").
+
+Exit: 0 metric computed · 64 bad input (no source, both sources, unreadable, or
+malformed numstat / unresolvable range).`;
+
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) { process.stdout.write(HELP + "\n"); process.exit(0); }
+  let res;
+  try {
+    res = runMetric(o);
+  } catch (e) {
+    // Defense in depth — runMetric is written never to throw, but the contract
+    // mandates the module never throws, so any escape maps to 64.
+    res = { ok: false, exitCode: 64, reason: `metric-error: ${e && e.message}` };
+  }
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { runMetric, parseNumstat, captureNumstat };