@tekyzinc/gsd-t 4.8.10 → 4.9.11

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.9.11] - 2026-06-23 (M93 — Brevity Guard: enforce concise, answer-first output — patch)
+
+### Added — conciseness is now enforced, not just requested
+
+The user has asked for concise, jargon-free replies for weeks; prose instructions kept getting ignored (a "no process narration" rule even existed and was violated). The fix is a deterministic gate, because that is the only mechanism GSD-T reliably obeys. 3 file-disjoint domains; full suite 2230 / 2226 pass / 0 fail / 4 skip.
+
+- **Brevity-guard Stop hook** (`scripts/gsd-t-brevity-guard.js`) — runs when a reply finishes. For a **question** (a pure-text answer), it blocks egregious preamble: 2+ stacked process-narration sentences ("let me find X before I answer…") before the actual answer, or an unglossed jargon code (`S2-M7`, `HC-003`). For an **action** (the turn changed code), intent-first is allowed — you still get to short-circuit a wrong direction. **Fail-open by design**: any error, malformed input, or uncertainty → allow, so it can never gag legitimate work.
+- **Reader Contract** in `templates/CLAUDE-global.md` + the QA / Red Team / pre-mortem / blind-adversary subagent prompts — sets the concise, answer-first, gloss-jargon default at the source, so the gate rarely needs to fire.
+- **Jargon lint** (`bin/gsd-t-jargon-lint.cjs`) — flags an unglossed jargon code in a written document (the file surface the Stop hook can't reach), so decision docs stay readable.
+
+The dated banner at the top of each reply is unchanged (kept by request).
+
+## [4.9.10] - 2026-06-23 (M92 — Understand-Before-Build, the paradigm half / backlog #44a — minor)
+
+### Changed — GSD-T now prefers the SMALLEST change that hits the crux
+
+The root cause of the BinVoice over-scoping saga: GSD-T was a purely ADDITIVE gate pipeline — when a plan started too high, every gate made it bigger, and the verdict schema couldn't even SAY "we made it smaller." M92 is the cheap, no-graph paradigm half of the fix (the graph half, #44b, is a separate later milestone gated on this one). Three file-disjoint moves, one wave; full suite 2183 / 2179 pass / 0 fail / 4 skip.
+
+- **Cheaper-first response ladder (move 1).** M90's §2 architectural trigger (R-ARCH-2 — fires when a task touches an existing file) now resolves a **look → smallest → spike → defer** ladder: `look` (grep/read what exists before scoping) is the new DEFAULT, `spike` is DEMOTED to a later rung. The cheap "look" rung resolves most over-scoping without ever needing a spike. R-ARCH-4/5/6 and the backward-compat envelope are preserved; the live spike-feasibility decider remains backlog #42 (explicitly out of scope). Doctrine contract `unproven-assumption-doctrine-contract.md` §2.2 updated.
+- **The verdict can say "smaller" (move 2, the keystone).** New `bin/gsd-t-shrink-metric.cjs` measures a change's leanness deterministically from `git diff --numstat` (`netLoc`, `leaner`) — MEASURED, not LLM-attested. Verify's `VERDICT_SCHEMA` gains an ADDITIVE `shrink` dimension (the correctness enum is untouched), so a net-negative diff is rewarded as a success instead of being invisible.
+- **The default is inverted (move 3).** The milestone/quick framing now leads with the smallest-altitude change; ceremony (plan→execute, partition, competition) is opt-in, justified by the crux — instead of being the implied "Recommended" default.
+
+### Security
+
+- **`bin/gsd-t-shrink-metric.cjs` git-argument injection (M92 verify Red Team, HIGH, fixed in-verify).** The `--range` value was passed to `git diff --numstat <range>` without dash-leading validation — `execFileSync` blocks shell injection but not git-OPTION injection, so a range like `--output=<path>` made git overwrite an arbitrary file (and the range is LLM-derived upstream). Fixed by refusing non-string/empty/dash-leading ranges before the git call (+ `--` end-of-options as defense-in-depth), with 3 security regression tests.
+
 ## [4.8.10] - 2026-06-22 (M91 — PseudoCode Source-of-Truth, merged M87+M88 — minor)
 
 ### Added — the intention-first PseudoCode behavior map becomes the milestone source-of-truth

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.8.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.9.11** - 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-architectural-trigger.cjs

@@ -231,12 +231,52 @@ function emitInstrumentationRecord(record) {
 /**
  * Resolve the response mode flags given the spike feasibility / spike result inputs.
  *
+ * M92 — CHEAPER-FIRST RESPONSE LADDER (look → smallest → spike → defer).
+ * --------------------------------------------------------------------------
+ * The BinVoice evidence proves the response should default to the CHEAPEST rung
+ * (look/grep what already exists) and only climb to a spike when look+smallest
+ * leave real uncertainty. Spike is DEMOTED from the default to a later rung.
+ *
+ * Rung order (deterministic state function of the inputs — ZERO LLM):
+ *   1. look      (DEFAULT, no inputs)          — grep/read the touched files first.
+ *   2. smallest  ({looked:true})               — propose the smallest-altitude change.
+ *   3. spike     ({looked, smallestProposed})  — uncertainty REMAINS → prove via spike.
+ *   4. defer     ({wartDiscovered:true})       — a wart found mid-change → capture, never clean inline.
+ *
+ * PRESERVED EXACTLY (these still fire on their explicit inputs, ahead of the ladder):
+ *   R-ARCH-5: spikeFeasible===false → adversary-only + adversaryMandatory + logged skip.
+ *   R-ARCH-4: spikePassed===false   → STOP (stopDirective:true); agent cannot proceed.
+ *   spikePassed===true              → mode:spike, adversary recommended-not-mandatory.
+ *
+ * Backward-compat envelope: EVERY return shape carries `mode` (string),
+ * `stopDirective` (boolean), `adversaryMandatory`, `provenByAdversaryOnly` — the keys
+ * execute/quick/verify read. A dropped/renamed key fails-OPEN those gates.
+ *
+ * NOTE (scope boundary): this resolver does NOT decide whether a spike is feasible
+ * (that is backlog #42's EXPERIMENTAL spike-feasibility decider). It only routes
+ * across the rungs from the inputs it is given; absent a spike result it defaults to
+ * the cheap LOOK rung instead of spike-preferred.
+ *
  * @param {object} opts
- * @param {boolean} [opts.spikeFeasible=true]  - Can an executable spike be run?
- * @param {boolean} [opts.spikePassed]         - Did the spike pass? (ignored if spikeFeasible=false)
+ * @param {boolean} [opts.spikeFeasible=true]   - Can an executable spike be run?
+ * @param {boolean} [opts.spikePassed]          - Did the spike pass? (ignored if spikeFeasible=false)
+ * @param {boolean} [opts.looked]               - Has the agent grep/read the touched files yet?
+ * @param {boolean} [opts.smallestProposed]     - Has the smallest-altitude change been proposed?
+ * @param {boolean} [opts.wartDiscovered]       - Was an out-of-scope wart discovered mid-change?
  * @returns {object} Response mode envelope fragment.
  */
-function resolveResponseMode({ spikeFeasible = true, spikePassed } = {}) {
+function resolveResponseMode(opts = {}) {
+  // Never throw on garbage: coalesce null/non-object inputs to an empty options bag
+  // (the `= {}` default only fires on `undefined`, not on `null` or primitives).
+  const o = opts && typeof opts === "object" ? opts : {};
+  const {
+    spikeFeasible = true,
+    spikePassed,
+    looked,
+    smallestProposed,
+    wartDiscovered,
+  } = o;
+
   if (!spikeFeasible) {
     // R-ARCH-5: spike infeasible → adversary-only + adversaryMandatory + logged skip
     return {
@@ -269,9 +309,44 @@ function resolveResponseMode({ spikeFeasible = true, spikePassed } = {}) {
     };
   }
 
-  // Default: spike PREFERRED (no spike result provided yet)
+  // ----- M92 cheaper-first ladder (no spike result provided yet) -----
+
+  if (wartDiscovered === true) {
+    // DEFER (terminal): a wart discovered mid-change is captured for later, never cleaned inline.
+    return {
+      mode: "defer",
+      deferDirective: "a wart discovered mid-change is captured for later, never cleaned inline",
+      adversaryMandatory: false,
+      provenByAdversaryOnly: false,
+      stopDirective: false,
+    };
+  }
+
+  if (looked === true && smallestProposed === true) {
+    // SPIKE (DEMOTED here): look + smallest left REAL uncertainty and a spike is feasible.
+    return {
+      mode: "spike",
+      adversaryMandatory: false,
+      provenByAdversaryOnly: false,
+      stopDirective: false,
+    };
+  }
+
+  if (looked === true) {
+    // SMALLEST: looked at what exists → propose the smallest-altitude change that hits the crux.
+    return {
+      mode: "smallest",
+      smallestDirective: "propose the smallest-altitude change that hits the crux; edit inward at the source, not outward at consumers",
+      adversaryMandatory: false,
+      provenByAdversaryOnly: false,
+      stopDirective: false,
+    };
+  }
+
+  // DEFAULT (no inputs): LOOK — the cheapest rung. Spike is NO LONGER the default.
   return {
-    mode: "spike",
+    mode: "look",
+    lookDirective: "grep/read the touched existing files; confirm what already exists before choosing scope",
     adversaryMandatory: false,
     provenByAdversaryOnly: false,
     stopDirective: false,

package/bin/gsd-t-jargon-lint.cjs

@@ -0,0 +1,363 @@
+"use strict";
+
+/**
+ * gsd-t-jargon-lint — M93 D3 (the file-surface gate)
+ *
+ * A deterministic lint for WRITTEN docs — the surface the D1 Stop hook can't reach.
+ * Documents (briefs, progress entries, contracts) fill with unglossed high-signal
+ * jargon — `S2-M7`, `HC-003`, bare ALL-CAPS acronyms — and the real decision gets
+ * buried. This lint FLAGS an unglossed first-occurrence jargon token (with its line)
+ * so the author glosses it before commit. It NEVER auto-fixes (auto-glossing is LLM
+ * judgment, out of scope) and it NEVER nags: only the FIRST occurrence of each
+ * distinct token is checked, so a glossed-then-reused-bare token PASSES.
+ *
+ * Detection (high-signal tokens):
+ *   - /\bS2-M\d+\b/          milestone-family code (e.g. S2-M7)
+ *   - /\bHC-\d+\b/           contract / hard-constraint id (e.g. HC-003)
+ *   - /\bM\d+(-D\d+(-T\d+)?)?\b/   GSD-T milestone/domain/task code (M93, M93-D3, M93-D3-T1)
+ *   - /\b[A-Z]{3,}\b/        ALL-CAPS acronym (≥3) NOT in the allowlist
+ *
+ * A "gloss" for a token's first occurrence is any of:
+ *   - an adjacent parenthetical `(...)` right after the token
+ *   - an em-dash clause `— ...` after the token (same sentence)
+ *   - any parenthetical / em-dash clause elsewhere in the SAME sentence
+ *   - the acronym's expansion (the N capitalized words whose initials spell it)
+ *
+ * Conservative by design ([[feedback_coverage_check_structural_not_substring]]):
+ *   - Skips fenced code blocks (```), and inline-code spans (`...`) — a token in
+ *     code is a reference, not prose jargon.
+ *   - Allowlist of common acronyms + an exempt-PATH list (mirrors the date-guard's
+ *     ALLOWLIST_PATTERNS) so machine-written / archived files are never flagged.
+ *
+ * Hard engineering bar (mirror gsd-t-shrink-metric.cjs / gsd-t-guard-map.cjs):
+ *   zero external deps (Node built-ins only), never throws (bad input → exitCode 64,
+ *   never an uncaught throw), pure detection — ZERO LLM judgment.
+ *
+ * Exit: 0 clean · 4 unglossed token(s) found (named with line in --json) · 64 bad input.
+ */
+
+const fs = require("node:fs");
+
+// ─── allowlist: exempt acronyms (never flagged) ────────────────────────────
+// Conservative — common protocol/format/timezone/English caps so legitimate prose
+// is never false-flagged. Extend only with truly universal acronyms.
+const ACRONYM_ALLOWLIST = new Set([
+  "GSD-T", "QA", "CLI", "API", "URL", "DB", "JSON", "JSONL", "NDJSON", "HTML",
+  "CSS", "HTTP", "HTTPS", "DTO", "SQL", "PDT", "EST", "UTC", "PST", "AND", "OR",
+  "NOT", "TODO", "FIXME", "README", "ID", "OK", "NPM", "CPUA",
+  // M93 Red Team MEDIUM: common cloud / hardware / infra acronyms are ordinary
+  // prose, not GSD-T jargon — exempt so the lint doesn't false-flag legit docs.
+  "AWS", "GCP", "CPU", "GPU", "RAM", "ETL", "SDK", "IDE", "OS", "UI", "UX",
+  "CI", "CD", "DNS", "TLS", "SSL", "SSH", "VM", "S3", "EC2", "RDS", "IAM",
+  "REST", "RPC", "GRPC", "MCP", "LLM", "PR", "MR", "TTL", "EOL", "EOF", "ASCII",
+  "UTF", "YAML", "TOML", "XML", "CSV", "PNG", "JPG", "SVG", "PDF", "DOM", "ENV",
+]);
+
+// ─── exempt PATHS (skip entirely — mirror gsd-t-date-guard ALLOWLIST_PATTERNS) ──
+// Machine-written / archived / historically-frozen surfaces are not user-facing
+// decision docs, so they are never linted.
+const EXEMPT_PATH_PATTERNS = [
+  /\.gsd-t\/milestones\//,
+  /\.gsd-t\/events\//,
+  /\.gsd-t\/transcripts\//,
+  /node_modules\//,
+  /\.git\//,
+  /CHANGELOG\.md$/,
+  /\.gsd-t\/token-log\.md$/,
+];
+
+function isExemptPath(p) {
+  if (typeof p !== "string" || p === "") return false;
+  return EXEMPT_PATH_PATTERNS.some((re) => re.test(p));
+}
+
+// ─── token detection ────────────────────────────────────────────────────────
+// Order matters for classification only (we report the raw matched token regardless).
+const TOKEN_PATTERNS = [
+  { kind: "S2-M", regex: /\bS2-M\d+\b/g },
+  { kind: "HC", regex: /\bHC-\d+\b/g },
+  // M93 Red Team MEDIUM: require a GSD-T milestone shape, not a bare `M1`/`M4`
+  // (motorway, chip, screw size — ordinary prose). A real milestone code is either
+  // 2+ digits (M82+) OR carries a -D/-T domain/task suffix. Bare single-digit M\d
+  // is NOT flagged.
+  { kind: "M-code", regex: /\bM(?:\d{2,}|\d+-D\d+(?:-T\d+)?)\b/g },
+  // Acronym ≥3 caps, optionally with hyphenated all-caps/digit segments so a
+  // hyphenated form (GSD-T) matches WHOLE and is allowlist-checked as a unit — a
+  // bare `\b[A-Z]{3,}\b` would catch only "GSD" inside "GSD-T" and false-flag it.
+  { kind: "acronym", regex: /\b[A-Z]{3,}(?:-[A-Z0-9]+)*\b/g },
+];
+
+/**
+ * Strip inline-code spans (`...`) from a single line so tokens inside them are
+ * invisible to detection. Replaces the span (incl. backticks) with spaces of the
+ * SAME length to preserve column/line geometry. Pure.
+ * @param {string} line
+ * @returns {string}
+ */
+function stripInlineCode(line) {
+  // Match the shortest backtick-delimited span. Double-backtick spans (`` ` ``) too.
+  return line.replace(/(`+)(?:.*?)\1/g, (m) => " ".repeat(m.length));
+}
+
+/**
+ * Find all high-signal token matches on a (code-stripped) line.
+ * @param {string} line
+ * @returns {Array<{ token:string, index:number, kind:string }>}
+ */
+function findTokens(line) {
+  const found = [];
+  for (const { kind, regex } of TOKEN_PATTERNS) {
+    regex.lastIndex = 0;
+    let m;
+    while ((m = regex.exec(line)) !== null) {
+      const token = m[0];
+      if (kind === "acronym" && ACRONYM_ALLOWLIST.has(token)) continue;
+      // An acronym match that is part of an allowlisted hyphenated form (GSD-T) is
+      // handled by the allowlist holding the full form; a bare "GSD" (≥3) would be
+      // flagged, which is intended (bare GSD is unglossed jargon).
+      found.push({ token, index: m.index, kind });
+    }
+  }
+  return found;
+}
+
+// ─── gloss proximity ──────────────────────────────────────────────────────
+
+/**
+ * Extract the sentence containing a given character index from a line. We treat a
+ * line as the gloss scope's outer bound and split on sentence terminators. Pure.
+ * @param {string} line
+ * @param {number} index
+ * @returns {{ sentence:string, relIndex:number }}
+ */
+function sentenceAround(line, index) {
+  // Split points: . ! ? followed by whitespace/end. Keep it simple + deterministic.
+  let start = 0;
+  let end = line.length;
+  const term = /[.!?](?=\s|$)/g;
+  let m;
+  while ((m = term.exec(line)) !== null) {
+    const pos = m.index + 1; // char after the terminator
+    if (pos <= index) start = pos;
+    else { end = pos; break; }
+  }
+  const sentence = line.slice(start, end);
+  return { sentence, relIndex: index - start };
+}
+
+/**
+ * Does the acronym's expansion appear adjacent to the token? An expansion is N
+ * Capitalized words whose initials spell the acronym, appearing immediately before
+ * the token inside a parenthetical OR immediately before/after the bare token.
+ * Heuristic but conservative. Pure.
+ * @param {string} sentence
+ * @param {string} token  the acronym (already known to be ALL-CAPS)
+ * @returns {boolean}
+ */
+function hasExpansion(sentence, token) {
+  if (!/^[A-Z]+$/.test(token)) return false; // expansion check only for plain acronyms
+  const letters = token.split("");
+  // Build a regex of N Capitalized words: \bWord\s+Word\s+...\b matching the initials.
+  // We scan all runs of >=N capitalized words and check any window spells the acronym.
+  const wordRe = /\b([A-Z][a-z]+)\b/g;
+  const words = [];
+  let m;
+  while ((m = wordRe.exec(sentence)) !== null) words.push(m[1]);
+  if (words.length < letters.length) return false;
+  for (let i = 0; i + letters.length <= words.length; i++) {
+    let ok = true;
+    for (let j = 0; j < letters.length; j++) {
+      if (words[i + j][0] !== letters[j]) { ok = false; break; }
+    }
+    if (ok) return true;
+  }
+  return false;
+}
+
+/**
+ * Is the token's first occurrence glossed? A gloss is:
+ *   - a parenthetical `(...)` adjacent (immediately following, allowing whitespace/quote)
+ *   - an em-dash clause after the token in the same sentence
+ *   - any parenthetical anywhere in the same sentence
+ *   - the acronym's expansion present in the sentence
+ * Pure.
+ * @param {string} line   the code-stripped line containing the token
+ * @param {number} index  char index of the token on the line
+ * @param {string} token
+ * @param {string} kind
+ * @returns {boolean}
+ */
+function isGlossed(line, index, token, kind) {
+  const { sentence, relIndex } = sentenceAround(line, index);
+  const after = sentence.slice(relIndex + token.length);
+
+  // 1. Adjacent parenthetical immediately after the token (optionally past quotes/space).
+  if (/^\s*["'“”]?\s*\([^)]*\)/.test(after)) return true;
+
+  // 2. Em-dash clause after the token (—, --, or - surrounded by spaces).
+  if (/^\s*(—|--|\s-\s)/.test(after)) return true;
+
+  // 3. Any parenthetical anywhere in the same sentence (glosses the term in context).
+  if (/\([^)]*\)/.test(sentence)) return true;
+
+  // 4. Acronym expansion present in the sentence.
+  if (kind === "acronym" && hasExpansion(sentence, token)) return true;
+
+  return false;
+}
+
+// ─── line scanning with fence awareness ────────────────────────────────────
+
+/**
+ * Lint a document's text. Returns the list of unglossed first-occurrence tokens.
+ * Pure; never throws.
+ * @param {string} text
+ * @returns {{ unglossed: Array<{ token:string, line:number, kind:string }>, tokensSeen:number }}
+ */
+function lintText(text) {
+  const src = String(text == null ? "" : text);
+  const lines = src.split(/\r?\n/);
+
+  const seen = new Set();       // distinct tokens whose first occurrence we've judged
+  const unglossed = [];
+  let inFence = false;
+  let tokensSeen = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i].replace(/\r$/, "");
+
+    // Fenced code block toggle: a line whose first non-space chars are ``` or ~~~.
+    if (/^\s*(```|~~~)/.test(raw)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    const codeStripped = stripInlineCode(raw);
+    const tokens = findTokens(codeStripped);
+
+    for (const t of tokens) {
+      tokensSeen++;
+      if (seen.has(t.token)) continue; // only the FIRST occurrence is judged — no nag
+      seen.add(t.token);
+      if (!isGlossed(codeStripped, t.index, t.token, t.kind)) {
+        unglossed.push({ token: t.token, line: i + 1, kind: t.kind });
+      }
+    }
+  }
+
+  return { unglossed, tokensSeen };
+}
+
+// ─── driver ─────────────────────────────────────────────────────────────────
+
+/**
+ * Run the lint over options. Never throws — bad input → exitCode 64.
+ * @param {{ file?:string, stdin?:boolean }} o
+ * @returns {{ ok, exitCode, ... }}
+ */
+function runLint(o) {
+  const opt = (o && typeof o === "object") ? o : {};
+  const hasFile = typeof opt.file === "string" && opt.file.length > 0;
+  const hasStdin = opt.stdin === true;
+
+  if (!hasFile && !hasStdin) {
+    return { ok: false, exitCode: 64, reason: "need --file <path> OR --stdin" };
+  }
+  if (hasFile && hasStdin) {
+    return { ok: false, exitCode: 64, reason: "give EITHER --file OR --stdin, not both" };
+  }
+
+  // Exempt path → skip entirely (clean).
+  if (hasFile && isExemptPath(opt.file)) {
+    return { ok: true, exitCode: 0, skipped: true, reason: `exempt path: ${opt.file}`, source: `file:${opt.file}`, unglossed: [], count: 0 };
+  }
+
+  let text;
+  let source;
+  if (hasFile) {
+    source = `file:${opt.file}`;
+    try {
+      text = fs.readFileSync(opt.file, "utf8");
+    } catch (e) {
+      return { ok: false, exitCode: 64, reason: `cannot read --file input: ${(e && e.message) || "unknown"}`, source };
+    }
+  } else {
+    source = "stdin";
+    try {
+      text = fs.readFileSync(0, "utf8");
+    } catch (e) {
+      return { ok: false, exitCode: 64, reason: `cannot read stdin: ${(e && e.message) || "unknown"}`, source };
+    }
+  }
+
+  const { unglossed, tokensSeen } = lintText(text);
+  return {
+    ok: unglossed.length === 0,
+    exitCode: unglossed.length === 0 ? 0 : 4,
+    source,
+    unglossed,
+    count: unglossed.length,
+    tokensSeen,
+  };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const o = { file: null, stdin: false, 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 === "--file") o.file = argv[++i];
+    else if (a === "--stdin") o.stdin = true;
+    else if (a === "--json") {/* default output is JSON */}
+  }
+  return o;
+}
+
+const HELP = `Usage:
+  gsd-t jargon-lint --file <path>   [--json]
+  gsd-t jargon-lint --stdin         [--json]
+
+The M93 jargon-gloss lint (D3). Flags an unglossed FIRST-occurrence high-signal
+jargon token in a written doc so it gets glossed before commit. Detects S2-M<n>,
+HC-<n>, M<n>(-D<n>(-T<n>)) codes, and ALL-CAPS acronyms (>=3) not in the allowlist.
+A token is "glossed" if its first occurrence has an adjacent parenthetical, an
+em-dash clause, a same-sentence parenthetical, or the acronym's spelled-out
+expansion. Skips code fences/inline-code spans. FLAGS, never auto-fixes. Conservative
+allowlist + exempt-path list (mirrors the date-guard). Zero LLM judgment.
+
+  --file PATH   lint a markdown/text file.
+  --stdin       lint text on stdin.
+  --json        emit the JSON envelope (default output is always JSON).
+
+Exit: 0 clean · 4 unglossed token(s) (named with line in JSON) · 64 bad input.`;
+
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) { process.stdout.write(HELP + "\n"); process.exit(0); }
+  let res;
+  try {
+    res = runLint(o);
+  } catch (e) {
+    // Defense in depth — runLint is written never to throw; any escape maps to 64.
+    res = { ok: false, exitCode: 64, reason: `lint-error: ${e && e.message}` };
+  }
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  runLint,
+  lintText,
+  findTokens,
+  isGlossed,
+  stripInlineCode,
+  hasExpansion,
+  isExemptPath,
+  ACRONYM_ALLOWLIST,
+  EXEMPT_PATH_PATTERNS,
+};