@tekyzinc/gsd-t 4.7.11 → 4.9.11

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 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
+
+A `PseudoCode-[Title].md` authored BEFORE the build (a two-altitude behavior map: high-level approach → detailed per-step intention+mechanism) is now the milestone source-of-truth, enforced by deterministic gates. Eight file-disjoint domains across three waves, single-session build; full suite 2131 / 2127 pass / 0 fail / 4 skip.
+
+**M87 core (Waves 1–2):**
+- **Guard-map verify gate** (`bin/gsd-t-guard-map.cjs`) — parses the `[RULE …]` guard map (3 grammar forms, side-agnostic, derives `R-<SLUG>-<NN>` ids), gates a build→rule map (exit 0 / 4-names-the-rule / 64); wired FAIL-blocking into `gsd-t-verify.workflow.js` before the triad, with §7 doc+map discovery and distinct logged skips (`no-build-map` / `no-pseudocode-docs`).
+- **Section-citation traceability** (`bin/gsd-t-traceability-gate.cjs` extended) — tasks cite `**PseudoCode-Section**: <Title>#<anchor>`; a section with no citing task is a structural coverage gap; slug-as-slug resolution, never substring. Plus a milestone→domains scoping fix (`--domains`; zero-prefix-match no longer falls back to all — exit 64 `milestone-scope-unresolved`) and a path-containment guard (`domain-path-escape`).
+- **Two-altitude milestone flow** (`commands/gsd-t-milestone.md` + `gsd-t-phase.workflow.js`) — high-level approach sign-off precedes the detailed doc; competition solution-space probe shifts up to the approach altitude. Keep-or-supersede prompt protocol writes a `⚠ Divergence` flag on supersede.
+- **Template + doc-ripple** — `templates/PseudoCode-spec.md` mold; `PseudoCode-[Title].md` joins the Living Documents ripple set (region-scoped A4 drift lint).
+
+**M88 deterministic gates (Wave 3):**
+- **Sign-off state** (`bin/gsd-t-milestone-state.cjs`) — `<!-- signed-off: … -->` marker + `isDefined(docs)` predicate; unsigned ≠ DEFINED; skip is a logged decision, never silent.
+- **Build→map derivation** (`bin/gsd-t-guard-map-derive.cjs`) — mechanical evidence→map seam (imports the guard-map parser), end-to-end derive→gate test.
+- **Triad-consumption seam** (`bin/gsd-t-rule-consume.cjs` + ingest directives in qa/red-team prompts) — deterministic seam-check, no live triad.
+- **Divergence grammar** (`bin/gsd-t-divergence-grammar.cjs`) — `parseDivergence`/`formatDivergence` byte-stable round-trip + `countDivergences`.
+
+Every gate meets the deterministic-gate bar: deterministic code, zero LLM judgment, structural-not-substring, killing test vs byte-verbatim fixtures, fail-closed. Verify: QA PASS (mutation-tested), Red Team GRUDGING-PASS (one path-traversal MEDIUM fixed in-verify; fence-awareness MEDIUM/LOW deferred to backlog #45, all fail-closed). Contract: `pseudocode-source-of-truth-contract.md` v1.1.5 STABLE.
+
 ## [4.7.11] - 2026-06-22 (backlog #40 — deterministic domain archive+sweep — patch)
 
 ### Fixed — complete-milestone now deterministically archives + sweeps a milestone's domains

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.7.11** - 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-divergence-grammar.cjs

@@ -0,0 +1,213 @@
+"use strict";
+
+/**
+ * gsd-t-divergence-grammar — M88 G4 (M91 Wave 3)
+ *
+ * The deterministic round-trip over the `⚠ Divergence` flag grammar.
+ *
+ * Contract: .gsd-t/contracts/pseudocode-source-of-truth-contract.md §4 — the
+ * SINGLE source of truth for the grammar. This module IMPLEMENTS that spec; it
+ * does NOT redefine it. The canonical §4 form is, EXACTLY:
+ *
+ *   ⚠ Divergence: <RULE-ID or section> — supersedes shipped <what>. Reason: <user intention>.
+ *
+ * ORIGIN: M87's D3 (`keep-or-supersede-subagent.md`) ships the keep-or-supersede
+ * ASK and the prose WRITING of a `⚠ Divergence` flag on every supersede. That
+ * makes the flag a string IN the doc — but not yet a code-checkable artifact.
+ * This module closes that gap: a `⚠ Divergence` line round-trips
+ * format→parse→format BYTE-STABLE, a malformed flag FAILS (named, no throw), and
+ * the divergence COUNT over a doc is emitted as a checkable JSON integer that can
+ * feed D1's guard-map rule set.
+ *
+ * Hard rules (contract §4 + domain constraints):
+ *   - Zero external runtime deps.
+ *   - Never throws. A parse failure is a RETURNED, NAMED error, not an exception
+ *     (fail-closed).
+ *   - Pure. parseDivergence / formatDivergence / countDivergences have no I/O and
+ *     no side effects (the CLI wrapper at the bottom is the only I/O).
+ *   - Round-trip is byte-stable: formatDivergence(parseDivergence(line).value)
+ *     === line for every valid flag.
+ *   - Structural marker parse, never a prose substring scan
+ *     (feedback_coverage_check_structural_not_substring): countDivergences only
+ *     counts lines that PARSE as a well-formed §4 flag, not lines that merely
+ *     CONTAIN the substring "⚠ Divergence".
+ *
+ * CLI:
+ *   --parse "<line>" --json     → { ok, value|error }
+ *   --count <docPath> --json    → { ok, count }   (count is the checkable artifact)
+ *
+ * Exit: 0 ok · 4 parse failure / count error · 64 bad input.
+ */
+
+// --- §4 grammar literals (the EXACT canonical form — single source is the contract) ---
+const PREFIX = "⚠ Divergence: ";          // "⚠ Divergence: "
+const SEP_SUPERSEDES = " — supersedes shipped "; // " — supersedes shipped " (em-dash U+2014)
+const SEP_REASON = ". Reason: ";
+const SUFFIX = ".";
+
+/**
+ * Parse a single line as a §4 `⚠ Divergence` flag.
+ *
+ * Structural, anchored parse — NOT a substring scan. The line MUST be EXACTLY
+ * `⚠ Divergence: <ref> — supersedes shipped <what>. Reason: <reason>.` with no
+ * leading/trailing slop. Each field MUST be non-empty.
+ *
+ * @param {string} line
+ * @returns {{ok: true, value: {ref: string, supersedes: string, reason: string}}
+ *          | {ok: false, error: string}}  never throws.
+ */
+function parseDivergence(line) {
+  if (typeof line !== "string") {
+    return { ok: false, error: "not-a-string" };
+  }
+  // Anchored: must START with the prefix (no leading slop — structural, not substring).
+  if (!line.startsWith(PREFIX)) {
+    return { ok: false, error: "missing-prefix" };
+  }
+  // Must END with the trailing period.
+  if (!line.endsWith(SUFFIX)) {
+    return { ok: false, error: "missing-trailing-period" };
+  }
+
+  // ref ... " — supersedes shipped " ... <what>
+  const afterPrefix = line.slice(PREFIX.length);
+  const supIdx = afterPrefix.indexOf(SEP_SUPERSEDES);
+  if (supIdx === -1) {
+    return { ok: false, error: "missing-supersedes-clause" };
+  }
+  const ref = afterPrefix.slice(0, supIdx);
+  const afterSup = afterPrefix.slice(supIdx + SEP_SUPERSEDES.length);
+
+  // <what> ". Reason: " <reason> "."
+  // Use the LAST ". Reason: " as the boundary so a <what> that itself contains
+  // ". Reason: " can never steal the reason field (round-trip stays exact).
+  const reasonIdx = afterSup.lastIndexOf(SEP_REASON);
+  if (reasonIdx === -1) {
+    return { ok: false, error: "missing-reason-clause" };
+  }
+  const supersedes = afterSup.slice(0, reasonIdx);
+  // reason is everything between ". Reason: " and the final ".", which we have
+  // already confirmed via endsWith(SUFFIX).
+  const reasonWithDot = afterSup.slice(reasonIdx + SEP_REASON.length);
+  const reason = reasonWithDot.slice(0, reasonWithDot.length - SUFFIX.length);
+
+  // Every field MUST be non-empty (an empty field is a malformed flag).
+  if (ref.length === 0) return { ok: false, error: "empty-ref" };
+  if (supersedes.length === 0) return { ok: false, error: "empty-supersedes" };
+  if (reason.length === 0) return { ok: false, error: "empty-reason" };
+
+  return { ok: true, value: { ref, supersedes, reason } };
+}
+
+/**
+ * Format a {ref, supersedes, reason} triple back into the canonical §4 line.
+ *
+ * @param {{ref: string, supersedes: string, reason: string}} obj
+ * @returns {{ok: true, value: string} | {ok: false, error: string}}  never throws.
+ */
+function formatDivergence(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return { ok: false, error: "not-an-object" };
+  }
+  const { ref, supersedes, reason } = obj;
+  if (typeof ref !== "string" || ref.length === 0) {
+    return { ok: false, error: "empty-ref" };
+  }
+  if (typeof supersedes !== "string" || supersedes.length === 0) {
+    return { ok: false, error: "empty-supersedes" };
+  }
+  if (typeof reason !== "string" || reason.length === 0) {
+    return { ok: false, error: "empty-reason" };
+  }
+  const value = PREFIX + ref + SEP_SUPERSEDES + supersedes + SEP_REASON + reason + SUFFIX;
+  return { ok: true, value };
+}
+
+/**
+ * Count the VALID `⚠ Divergence` flags in a document.
+ *
+ * Structural: a line is counted ONLY if it PARSES as a well-formed §4 flag — a
+ * line that merely contains the substring "⚠ Divergence" but is malformed is NOT
+ * counted (feedback_coverage_check_structural_not_substring). The returned count
+ * is a deterministic integer (the checkable artifact that can feed D1's rule map).
+ *
+ * @param {string} docText
+ * @returns {number} count of valid flags (0 on non-string input — never throws).
+ */
+function countDivergences(docText) {
+  if (typeof docText !== "string") return 0;
+  // Split on any newline style; trailing/leading whitespace on a line is slop,
+  // so a flag line with surrounding whitespace will fail the anchored parse and
+  // not be counted (matches the byte-stable round-trip invariant).
+  const lines = docText.split(/\r\n|\r|\n/);
+  let count = 0;
+  for (const line of lines) {
+    if (parseDivergence(line).ok) count++;
+  }
+  return count;
+}
+
+// --------------------------------------------------------------------------
+// CLI wrapper (the only I/O; the three functions above are pure).
+// --------------------------------------------------------------------------
+
+const HELP = [
+  "gsd-t-divergence-grammar — §4 ⚠ Divergence flag round-trip + count",
+  "",
+  "Usage:",
+  '  gsd-t-divergence-grammar --parse "<line>" --json',
+  "  gsd-t-divergence-grammar --count <docPath> --json",
+  "",
+  "Exit: 0 ok · 4 parse failure / count error · 64 bad input.",
+].join("\n");
+
+function parseArgs(argv) {
+  const o = { json: false, help: false, parse: null, count: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") o.help = true;
+    else if (a === "--json") o.json = true;
+    else if (a === "--parse") o.parse = argv[++i];
+    else if (a === "--count") o.count = argv[++i];
+  }
+  return o;
+}
+
+function main() {
+  // Lazy require of fs ONLY inside the CLI path — the module export surface
+  // stays pure/dep-free.
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) {
+    process.stdout.write(HELP + "\n");
+    process.exit(0);
+  }
+
+  if (o.parse != null) {
+    const res = parseDivergence(o.parse);
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+    process.exit(res.ok ? 0 : 4);
+  }
+
+  if (o.count != null) {
+    let text;
+    try {
+      text = require("fs").readFileSync(o.count, "utf8");
+    } catch (e) {
+      process.stdout.write(
+        JSON.stringify({ ok: false, error: "read-failed", path: o.count }, null, 2) + "\n"
+      );
+      process.exit(4);
+    }
+    const count = countDivergences(text);
+    // The count is a CHECKABLE JSON integer artifact, not prose.
+    process.stdout.write(JSON.stringify({ ok: true, count }, null, 2) + "\n");
+    process.exit(0);
+  }
+
+  process.stdout.write(JSON.stringify({ ok: false, error: "no-mode" }, null, 2) + "\n");
+  process.exit(64);
+}
+
+if (require.main === module) main();
+
+module.exports = { parseDivergence, formatDivergence, countDivergences };

package/bin/gsd-t-guard-map-derive.cjs

@@ -0,0 +1,210 @@
+"use strict";
+
+/**
+ * gsd-t-guard-map-derive — M88 G2 (map-derivation-seam)
+ *
+ * The mechanical build→rule-map DERIVATION seam. Where M87 D1
+ * (`bin/gsd-t-guard-map.cjs`) GATES a build→rule map, this module DERIVES that
+ * map from two inputs — instead of hand-authoring it:
+ *
+ *   1. a PseudoCode doc  → the doc's derived RULE-ID set (via D1's parser,
+ *      IMPORTED, never re-implemented — single source of truth for the grammar).
+ *   2. a build-evidence manifest → which test assertions / files back (or
+ *      contradict) which RULE-ID(s).
+ *
+ * Output: `{ rules: { <id>: { backedBy:[<refs>], contradicted:bool } } }`
+ * keyed EXACTLY to the doc's derived RULE-ID set — EVERY doc rule present.
+ * A rule with no evidence → `backedBy:[]` (PRESENT, unbacked) — NOT an omitted
+ * key. Omitting it would re-open the map-side vacuous pass D1's gate closed
+ * (the gate iterates the DOC's id set; an absent key is treated as unbacked, but
+ * a faithful derivation must still emit every doc rule so the map is a complete,
+ * gate-ready artifact).
+ *
+ * Evidence manifest shape (the convention this seam defines):
+ *   {
+ *     "evidence": [
+ *       { "ref": "test/foo.test.js:42", "backs": ["R-PAYPAL-03", "R-PAYPAL-05"] },
+ *       { "ref": "test/bar.test.js:7",  "contradicts": ["R-PAYPAL-07"] }
+ *     ]
+ *   }
+ * - `ref` (string, required): a stable evidence reference (file:line, file::name, …).
+ * - `backs` (string[], optional): RULE-IDs this evidence BACKS.
+ * - `contradicts` (string[], optional): RULE-IDs this evidence CONTRADICTS
+ *   (build/test asserts the negation of the invariant). Any contradiction on a
+ *   rule sets its `contradicted:true` in the derived map.
+ * An evidence entry that references a RULE-ID NOT in the doc's derived set is
+ * IGNORED (the doc is the source of truth; phantom refs never invent map keys).
+ *
+ * Hard engineering bar (mirror D1 + M83): zero deps (Node built-ins only), never
+ * throws (bad input → exitCode 64, never an uncaught throw), pure/read-only
+ * (writes nothing). Deterministic — same doc bytes + same manifest → same map.
+ *
+ * Input:  --doc <PseudoCode-[Title].md> --evidence <manifest.json> [--json]
+ * Output: the derived map JSON ({ rules: {...} }) on stdout.
+ * Exit:   0 derivation succeeded · 64 bad input (unreadable doc, bad manifest,
+ *         doc parse failure).
+ */
+
+const fs = require("node:fs");
+
+// IMPORT D1's parser + RULE-ID derivation — the single source of truth for the
+// `[RULE]` grammar. We consume `parseRules(md, docPath)`; we do NOT re-implement
+// the grammar (a re-impl would drift from the gate that reads our output).
+const { parseRules } = require("./gsd-t-guard-map.cjs");
+
+// ─── derivation (pure) ─────────────────────────────────────────────────────
+
+/**
+ * Derive the build→rule map from a doc's derived RULE-ID set + an evidence
+ * manifest. Doc-keyed: EVERY doc rule is emitted; an unbacked rule is
+ * `backedBy:[]` present. Phantom evidence refs (RULE-IDs not in the doc) are
+ * ignored. Pure — no I/O, never throws.
+ *
+ * @param {Array<{id:string}>} rules - parseRules().rules (doc-derived id set)
+ * @param {{evidence?: Array<{ref?:string, backs?:string[], contradicts?:string[]}>}} manifest
+ * @returns {{ rules: Object<string, {backedBy:string[], contradicted:boolean}> }}
+ */
+function deriveMap(rules, manifest) {
+  // Seed every doc-derived id with an empty, unbacked, not-contradicted entry.
+  // Iterating the DOC's id set (not the manifest) is what preserves doc-keyed
+  // non-vacuity: a rule with zero evidence is PRESENT as backedBy:[].
+  const out = { rules: {} };
+  const docIds = new Set();
+  for (const r of Array.isArray(rules) ? rules : []) {
+    if (r && typeof r.id === "string") {
+      docIds.add(r.id);
+      if (!out.rules[r.id]) out.rules[r.id] = { backedBy: [], contradicted: false };
+    }
+  }
+
+  const evidence = (manifest && Array.isArray(manifest.evidence)) ? manifest.evidence : [];
+  for (const item of evidence) {
+    if (!item || typeof item !== "object") continue;
+    const ref = typeof item.ref === "string" ? item.ref : null;
+    const backs = Array.isArray(item.backs) ? item.backs : [];
+    const contradicts = Array.isArray(item.contradicts) ? item.contradicts : [];
+
+    for (const id of backs) {
+      // Only attach to a DOC-derived id (doc is the source of truth; phantom
+      // ids never invent a key). A backing without a `ref` is meaningless — skip.
+      if (typeof id === "string" && docIds.has(id) && ref) {
+        const entry = out.rules[id];
+        if (!entry.backedBy.includes(ref)) entry.backedBy.push(ref);
+      }
+    }
+    for (const id of contradicts) {
+      if (typeof id === "string" && docIds.has(id)) {
+        out.rules[id].contradicted = true;
+      }
+    }
+  }
+
+  return out;
+}
+
+// ─── driver ────────────────────────────────────────────────────────────────
+
+/**
+ * Run the derivation over a doc + evidence manifest. Never throws — bad input
+ * returns an envelope with exitCode 64. On success, `map` is the derived
+ * build→rule map (gate-ready, consumable by gsd-t-guard-map.cjs unchanged).
+ *
+ * @param {{doc?:string, evidence?:string}} o
+ * @returns {{ ok:boolean, exitCode:number, map?:object, derivedIds?:string[], ... }}
+ */
+function runDerive(o) {
+  const { doc, evidence } = (o && typeof o === "object") ? o : {};
+  if (!doc || !evidence || typeof doc !== "string" || typeof evidence !== "string") {
+    return { ok: false, exitCode: 64, reason: "missing --doc and/or --evidence", doc: doc || null, evidence: evidence || null };
+  }
+
+  let md;
+  try {
+    md = fs.readFileSync(doc, "utf8");
+  } catch (e) {
+    return { ok: false, exitCode: 64, reason: `cannot read doc: ${e && e.message}`, doc };
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(evidence, "utf8"));
+  } catch (e) {
+    return { ok: false, exitCode: 64, reason: `cannot read/parse evidence JSON: ${e && e.message}`, evidence };
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return { ok: false, exitCode: 64, reason: "evidence JSON must be an object with an `evidence` array", evidence };
+  }
+
+  const { rules, parseErrors } = parseRules(md, doc);
+
+  // A doc parse failure (empty-invariant rule) is bad input — the same severity
+  // D1's gate assigns it. We cannot derive a faithful map from a malformed doc.
+  if (parseErrors.length > 0) {
+    return {
+      ok: false,
+      exitCode: 64,
+      reason: `doc parse failure: ${parseErrors.length} rule line(s) yielded an empty invariant`,
+      parseErrors,
+      doc,
+    };
+  }
+
+  const map = deriveMap(rules, manifest);
+  const derivedIds = rules.map((r) => r.id);
+
+  return { ok: true, exitCode: 0, doc, evidence, derivedIds, ruleCount: derivedIds.length, map };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const o = { doc: null, evidence: 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 === "--evidence") o.evidence = argv[++i];
+    else if (a === "--json") {/* default output is JSON */}
+  }
+  return o;
+}
+
+const HELP = `Usage: gsd-t guard-map-derive --doc <PseudoCode-[Title].md> --evidence <manifest.json> [--json]
+
+The M88 build→rule-map DERIVATION seam. Parses every [RULE] from a PseudoCode
+doc (via the M87 guard-map parser — single source of truth), then DERIVES the
+build→rule map gsd-t-guard-map.cjs gates, attaching each evidence ref to the
+RULE-ID(s) it backs/contradicts. The map is keyed EXACTLY to the doc's derived
+id set — every doc rule present; an unbacked rule is backedBy:[] (never omitted).
+The derived map prints to stdout and is valid --map input to the gate unchanged.
+
+  --doc      PATH  the PseudoCode-[Title].md guard-map doc.
+  --evidence PATH  the build-evidence manifest:
+                   { "evidence": [ { "ref": "test/x.test.js:42",
+                                     "backs": ["R-FOO-01"],
+                                     "contradicts": ["R-FOO-02"] } ] }
+
+Exit: 0 derivation succeeded (map on stdout) · 64 bad input (unreadable doc,
+bad manifest, or doc parse failure).`;
+
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) { process.stdout.write(HELP + "\n"); process.exit(0); }
+  let res;
+  try {
+    res = runDerive(o);
+  } catch (e) {
+    // Defense in depth — runDerive is written never to throw, but the contract
+    // mandates the module never throws, so bad input maps to 64 even here.
+    res = { ok: false, exitCode: 64, reason: `derive-error: ${e && e.message}` };
+  }
+  // On success print the derived MAP (the artifact); on failure print the
+  // diagnostic envelope. Either way, valid JSON to stdout.
+  const payload = res.ok ? res.map : res;
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { runDerive, deriveMap };