@tekyzinc/gsd-t 4.7.10 → 4.8.10

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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
+
+`complete-milestone` Step 7 was prose-only ("archive domains → clear `.gsd-t/domains/`") with no enforcement, so a Level-3 autonomous agent skipped or partial-did it for ~30 milestones — accumulating 77 stale domain dirs that polluted the file-disjointness oracle (surfaced + manually pruned during M90). Root-cause fix:
+
+- **`bin/gsd-t-archive-domains.cjs`** (new) + `gsd-t archive-domains` dispatch: copies an EXPLICIT set of the completing milestone's domain dirs → `<archive>/domains/<name>/`, then removes them from `.gsd-t/domains/`. Idempotent (re-running is a no-op), containment-guarded (refuses any name with path separators / dot-segments or resolving outside `.gsd-t/domains/` — [[feedback_destructive_path_ops_containment]]), fail-closed (a bad name aborts the whole batch, no partial sweep). Domains of other still-active milestones are left untouched (not a blanket wipe).
+- `commands/gsd-t-complete-milestone.md` Step 7: prose → the deterministic helper call.
+- Propagated via PROJECT_BIN_TOOLS + GLOBAL_BIN_TOOLS. 5 tests (sweep-exactly / idempotent / dry-run / containment / bad-input). Suite 2003 / 1999 pass / 0 fail.
+
 ## [4.7.10] - 2026-06-22 (M90 — The Unproven-Assumption Doctrine — minor)
 
 ### Added — a self-governing doctrine that stops the system building on unproven assumptions

package/README.md

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

@@ -0,0 +1,136 @@
+/**
+ * gsd-t-archive-domains.cjs
+ *
+ * Backlog #40 — Deterministic archive+sweep of a completed milestone's domain dirs.
+ *
+ * complete-milestone Step 7 was prose-only ("archive domains → clear .gsd-t/domains/") with no
+ * enforcement, so a Level-3 agent skipped/partial-did the clear for ~30 milestones and 77 stale
+ * domain dirs accumulated, polluting the file-disjointness oracle. This helper makes the sweep a
+ * deterministic, idempotent, containment-guarded operation.
+ *
+ * Behavior — for an EXPLICIT set of the completing milestone's domains (NOT a blanket wipe; a
+ * later still-active milestone may legitimately have live domains, e.g. M90 completing while
+ * M87/M88 are queued):
+ *   1. Copy each domain dir → <archiveDir>/domains/<name>/  (skip if already archived — idempotent)
+ *   2. Remove it from .gsd-t/domains/                        (skip if already gone — idempotent)
+ * Domains NOT in the set are left untouched.
+ *
+ * Containment guard ([[feedback_destructive_path_ops_containment]]): every removed path MUST resolve
+ * INSIDE .gsd-t/domains/ AND NOT equal it. Predicate: resolved.startsWith(domainsRoot + sep) &&
+ * resolved !== domainsRoot. Any violation aborts the whole run (fail-closed, no partial sweep).
+ *
+ * House style: { ok:true, ... } | { ok:false, error }; bad input → non-zero CLI exit; Node
+ * built-ins only; sync APIs; zero deps.
+ *
+ * Usage:
+ *   gsd-t archive-domains --domains d-a,d-b,d-c --archive .gsd-t/milestones/mNN-name-DATE [--projectDir .] [--dry-run] [--json]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DOMAINS_SUBPATH = path.join('.gsd-t', 'domains');
+
+/**
+ * Archive + sweep the named domains.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.domains   — explicit domain dir names (the completing milestone's set)
+ * @param {string}   opts.archiveDir — milestone archive dir (domains land under <archiveDir>/domains/)
+ * @param {string}   [opts.projectDir] — project root (default cwd)
+ * @param {boolean}  [opts.dryRun]   — compute the plan, write nothing
+ * @returns {{ok:true, archived:string[], removed:string[], skipped:string[], dryRun:boolean}
+ *          | {ok:false, error:string}}
+ */
+function archiveDomains({ domains, archiveDir, projectDir, dryRun = false } = {}) {
+  if (!Array.isArray(domains) || domains.length === 0) {
+    return { ok: false, error: 'archive-domains requires a non-empty --domains list (the completing milestone\'s domain set)' };
+  }
+  if (!archiveDir || typeof archiveDir !== 'string' || !archiveDir.trim()) {
+    return { ok: false, error: 'archive-domains requires --archive <milestone archive dir>' };
+  }
+
+  const root = path.resolve(projectDir || process.cwd());
+  const domainsRoot = path.resolve(root, DOMAINS_SUBPATH);
+  const archiveRootAbs = path.isAbsolute(archiveDir) ? archiveDir : path.resolve(root, archiveDir);
+  const archiveDomainsDir = path.join(archiveRootAbs, 'domains');
+
+  // Validate every target up front (fail-closed: no partial sweep on a bad name).
+  const plan = [];
+  for (const name of domains) {
+    if (!name || typeof name !== 'string' || name.includes('/') || name.includes('\\') || name === '.' || name === '..') {
+      return { ok: false, error: `invalid domain name (no path separators / dot-segments allowed): ${JSON.stringify(name)}` };
+    }
+    const srcAbs = path.resolve(domainsRoot, name);
+    // CONTAINMENT GUARD: must resolve strictly INSIDE .gsd-t/domains/ (not outside, not equal).
+    if (!(srcAbs.startsWith(domainsRoot + path.sep) && srcAbs !== domainsRoot)) {
+      return { ok: false, error: `containment violation: ${name} resolves to ${srcAbs}, outside or equal to ${domainsRoot} — refusing` };
+    }
+    plan.push({ name, srcAbs, destAbs: path.join(archiveDomainsDir, name) });
+  }
+
+  const archived = [];
+  const removed = [];
+  const skipped = [];
+
+  for (const { name, srcAbs, destAbs } of plan) {
+    const srcExists = fs.existsSync(srcAbs);
+    const destExists = fs.existsSync(destAbs);
+
+    // IDEMPOTENT: nothing live and already archived → skip silently.
+    if (!srcExists && destExists) { skipped.push(name); continue; }
+    // Nothing live and not archived → the domain doesn't exist at all → skip (not an error;
+    // re-running after a manual prune is valid).
+    if (!srcExists && !destExists) { skipped.push(name); continue; }
+
+    if (dryRun) {
+      if (!destExists) archived.push(name);
+      removed.push(name);
+      continue;
+    }
+
+    // 1. Archive (copy) unless already archived.
+    if (!destExists) {
+      fs.mkdirSync(archiveDomainsDir, { recursive: true });
+      fs.cpSync(srcAbs, destAbs, { recursive: true });
+      archived.push(name);
+    }
+    // 2. Remove from live domains (containment re-checked at delete time).
+    if (!(srcAbs.startsWith(domainsRoot + path.sep) && srcAbs !== domainsRoot)) {
+      return { ok: false, error: `containment re-check failed at delete: ${srcAbs}` };
+    }
+    fs.rmSync(srcAbs, { recursive: true, force: true });
+    removed.push(name);
+  }
+
+  return { ok: true, archived, removed, skipped, dryRun };
+}
+
+module.exports = { archiveDomains };
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--json') flags.json = true;
+    else if (a.startsWith('--') && i + 1 < argv.length) flags[a.slice(2)] = argv[++i];
+  }
+
+  const domains = (flags.domains || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const result = archiveDomains({
+    domains,
+    archiveDir: flags.archive,
+    projectDir: flags.projectDir || process.cwd(),
+    dryRun: !!flags.dryRun,
+  });
+
+  process.stdout.write(JSON.stringify(result) + '\n');
+  process.exit(result.ok ? 0 : 1);
+}

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 };