@tekyzinc/gsd-t 4.7.11 → 4.8.10

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

@@ -0,0 +1,279 @@
+"use strict";
+
+/**
+ * gsd-t-guard-map — M87 D1 (guard-bridge-spike)
+ *
+ * The A1 kill-criterion gate. Turns a prose `[RULE]` guard map in a
+ * `PseudoCode-[Title].md` doc into a machine-checkable verify gate where a
+ * divergence (an UNBACKED or CONTRADICTED rule) is a DETERMINISTIC,
+ * non-vacuous FAILURE — zero LLM judgment in the pass/fail decision.
+ *
+ * Contract: .gsd-t/contracts/pseudocode-source-of-truth-contract.md §2 (the
+ * `[RULE]` guard-map grammar + RULE-ID derivation) + §7 (discovery convention).
+ *
+ * Grammar (§2, reconciled to the real binvoice corpus):
+ *   A rule = any line CONTAINING the `[RULE …]` marker (matched ANYWHERE on the
+ *   line, NOT `^`-anchored — the corpus places guard prose LEFT of the marker).
+ *   Three accepted marker forms:
+ *     ... [RULE] <RULE-ID>: <invariant>    # explicit id, invariant RIGHT
+ *     GATE: ... → 409  [RULE] <invariant>  # loose, invariant RIGHT (PayPal style)
+ *     <invariant prose> ... [RULE — <tag>] # tagged, invariant LEFT (Extension style)
+ *   Invariant capture is SIDE-AGNOSTIC (§2 v1.1.3): RIGHT-of-`]` if non-empty,
+ *   ELSE the LEFT-of-marker prose. An EMPTY resolved invariant = parse FAILURE.
+ *   Rule id: explicit `<RULE-ID>:` if present, else DERIVE `R-<DOC-SLUG>-<NN>`
+ *   by 1-based appearance order (pure — same doc bytes → same ids).
+ *
+ * Gate (DOC-keyed, §2 "Non-vacuity on the MAP side"): iterate the DOC's derived
+ * RULE-ID set as the source of truth. For each doc rule:
+ *   - map entry present + backedBy non-empty + !contradicted → backed (passes)
+ *   - map entry unbacked (backedBy []) OR contradicted          → FAIL (exit 4)
+ *   - map key ABSENT entirely                                   → UNBACKED → FAIL (exit 4)
+ * An incomplete map that simply omits a doc rule can NEVER pass vacuously.
+ *
+ * Hard engineering bar (mirror M83 traceability-gate): zero deps (Node built-ins
+ * only), never throws (bad input → exitCode 64, never an uncaught throw),
+ * pure/read-only (writes nothing). Deterministic pass/fail — ZERO LLM judgment.
+ *
+ * Input:  --doc <path> --map <path> [--json]
+ * Output: JSON envelope { ok, exitCode, ... }.
+ * Exit:   0 every rule backed, none contradicted · 4 ≥1 unbacked/contradicted
+ *         (names the RULE-ID) · 64 bad input.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// ─── RULE marker grammar (§2) ─────────────────────────────────────────────
+
+// The marker is `[RULE]` or `[RULE — <tag>]`. Matched ANYWHERE on the line
+// (not `^`-anchored). Path-as-marker, never a bare "RULE" substring.
+const MARKER_RE = /\[RULE(\s*—\s*[^\]]*)?\]/;
+
+// An explicit id form: directly after `]`, `<RULE-ID>: <invariant>` where the
+// id is an R-prefixed token (e.g. `R-PAYPAL-01`). Captured for id resolution.
+const EXPLICIT_ID_RE = /^\s*(R-[A-Z0-9][A-Z0-9-]*)\s*:\s*(.*)$/i;
+
+/**
+ * Derive the DOC-SLUG from a doc filename: `PseudoCode-[Title].md` → uppercased
+ * `[Title]` with non-alphanumerics collapsed (PAYPAL, EXTENSION). Pure.
+ * @param {string} docPath
+ * @returns {string}
+ */
+function docSlug(docPath) {
+  const base = path.basename(String(docPath || ""), ".md");
+  // Strip a leading "PseudoCode-" (case-insensitive) if present, else use whole base.
+  let title = base.replace(/^pseudocode-/i, "");
+  // Strip a trailing harness-variant suffix (e.g. `-doctored`) so a doctored COPY of a
+  // subject derives the SAME DOC-SLUG as the faithful subject — the derived RULE-IDs must
+  // stay STABLE between faithful and doctored runs (§2; the divergence lives only in the
+  // map, never the doc text or its ids). `-doctored` is a test-harness variant of the same
+  // subject (PayPal), not a distinct subject Title.
+  title = title.replace(/-doctored$/i, "");
+  return title.replace(/[^a-z0-9]+/gi, "").toUpperCase() || "DOC";
+}
+
+/**
+ * Parse every `[RULE]` from a doc's text per §2.
+ * Side-agnostic invariant capture, deterministic id resolution.
+ * @param {string} md - the doc text
+ * @param {string} docPath - used to derive the DOC-SLUG
+ * @returns {{ rules: Array<{id, invariant, tag, explicit, line}>, parseErrors: Array<{line, raw}> }}
+ */
+function parseRules(md, docPath) {
+  const slug = docSlug(docPath);
+  const lines = String(md == null ? "" : md).split(/\r?\n/);
+  const rules = [];
+  const parseErrors = [];
+  let n = 0; // 1-based appearance order, only incremented for real markers
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = line.match(MARKER_RE);
+    if (!m) continue;
+
+    n += 1;
+    const markerStart = m.index;
+    const markerEnd = m.index + m[0].length;
+    const tag = m[1] ? m[1].replace(/^\s*—\s*/, "").trim() : null;
+
+    const leftText = line.slice(0, markerStart).trim();
+    const rightRaw = line.slice(markerEnd).trim();
+
+    // Explicit id form: the RIGHT side begins `<RULE-ID>: <invariant>`.
+    let id = `R-${slug}-${String(n).padStart(2, "0")}`;
+    let explicit = false;
+    let rightInvariant = rightRaw;
+    const idm = rightRaw.match(EXPLICIT_ID_RE);
+    if (idm) {
+      id = idm[1].toUpperCase();
+      explicit = true;
+      rightInvariant = idm[2].trim();
+    }
+
+    // Side-agnostic capture: RIGHT-of-`]` if non-empty, else LEFT-of-marker prose.
+    const invariant = (rightInvariant && rightInvariant.length > 0) ? rightInvariant : leftText;
+
+    if (!invariant || invariant.length === 0) {
+      // A rule whose resolved invariant is empty is a PARSE FAILURE (§2).
+      parseErrors.push({ line: i + 1, raw: line.trim() });
+      continue;
+    }
+
+    rules.push({ id, invariant, tag, explicit, line: i + 1 });
+  }
+
+  return { rules, parseErrors };
+}
+
+// ─── gate (DOC-keyed; §2 non-vacuity on the map side) ──────────────────────
+
+/**
+ * Gate a parsed doc against a build→rule map. Iterates the DOC's derived
+ * RULE-ID set (NOT the map's keyset). A doc-derived id absent from the map is
+ * treated as UNBACKED.
+ * @param {Array} rules - parseRules().rules
+ * @param {object} map - { rules: { <id>: { backedBy:[...], contradicted:bool } } }
+ * @returns {{ violations: Array<{id, kind, detail}>, checked: number }}
+ */
+function gateRules(rules, map) {
+  const mapRules = (map && map.rules && typeof map.rules === "object") ? map.rules : {};
+  const violations = [];
+  for (const r of rules) {
+    const entry = mapRules[r.id];
+    if (entry === undefined || entry === null) {
+      // Key absent entirely → UNBACKED (doc-keyed iteration; no map-side vacuous pass).
+      violations.push({
+        id: r.id,
+        kind: "unbacked",
+        detail: `RULE ${r.id} ("${r.invariant}") has NO entry in the build→rule map — UNBACKED (a doc-derived rule absent from the map is unbacked, never a vacuous pass).`,
+      });
+      continue;
+    }
+    const backedBy = Array.isArray(entry.backedBy) ? entry.backedBy : [];
+    const contradicted = entry.contradicted === true;
+    if (contradicted) {
+      violations.push({
+        id: r.id,
+        kind: "contradicted",
+        detail: `RULE ${r.id} ("${r.invariant}") is CONTRADICTED — build/test evidence asserts the negation of the invariant (contract-breach divergence).`,
+      });
+    } else if (backedBy.length === 0) {
+      violations.push({
+        id: r.id,
+        kind: "unbacked",
+        detail: `RULE ${r.id} ("${r.invariant}") is UNBACKED — no test assertion references it (backedBy is empty).`,
+      });
+    }
+  }
+  return { violations, checked: rules.length };
+}
+
+// ─── driver ────────────────────────────────────────────────────────────────
+
+function readJson(p) {
+  const txt = fs.readFileSync(p, "utf8");
+  return JSON.parse(txt);
+}
+
+/**
+ * Run the gate over a doc + map. Never throws — bad input returns exitCode 64.
+ * @param {{ doc, map }} o
+ * @returns {{ ok, exitCode, ... }}
+ */
+function runGate(o) {
+  const { doc, map } = (o && typeof o === "object") ? o : {};
+  if (!doc || !map || typeof doc !== "string" || typeof map !== "string") {
+    return { ok: false, exitCode: 64, reason: "missing --doc and/or --map", doc: doc || null, map: map || 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 mapObj;
+  try {
+    mapObj = readJson(map);
+  } catch (e) {
+    return { ok: false, exitCode: 64, reason: `cannot read/parse map JSON: ${e && e.message}`, map };
+  }
+  if (!mapObj || typeof mapObj !== "object" || mapObj.rules === undefined || typeof mapObj.rules !== "object" || mapObj.rules === null) {
+    return { ok: false, exitCode: 64, reason: "map JSON has no `rules` object", map };
+  }
+
+  const { rules, parseErrors } = parseRules(md, doc);
+
+  // A parse failure (empty-invariant rule) is bad input (the doc violates the grammar).
+  if (parseErrors.length > 0) {
+    return {
+      ok: false,
+      exitCode: 64,
+      reason: `parse failure: ${parseErrors.length} rule line(s) yielded an empty invariant`,
+      parseErrors,
+      doc,
+    };
+  }
+
+  const derivedIds = rules.map((r) => r.id);
+  const { violations, checked } = gateRules(rules, mapObj);
+
+  const ok = violations.length === 0;
+  return {
+    ok,
+    exitCode: ok ? 0 : 4,
+    doc,
+    map,
+    ruleCount: checked,
+    derivedIds,
+    rules: rules.map((r) => ({ id: r.id, invariant: r.invariant, tag: r.tag, explicit: r.explicit, line: r.line })),
+    violations,
+    ...(ok ? {} : { reason: `${violations.length} unbacked/contradicted rule(s): ${violations.map((v) => v.id).join(", ")}` }),
+  };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const o = { doc: null, 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 === "--doc") o.doc = argv[++i];
+    else if (a === "--map") o.map = argv[++i];
+    else if (a === "--json") {/* default output is JSON */}
+  }
+  return o;
+}
+
+const HELP = `Usage: gsd-t guard-map --doc <PseudoCode-[Title].md> --map <build-map.json> [--json]
+
+The M87 guard-map gate (A1). Enumerates every [RULE] from a PseudoCode doc per
+the source-of-truth contract §2, then gates a build→rule map: exit non-zero when
+a doc-derived RULE-ID is UNBACKED (backedBy empty, or key absent from the map) or
+CONTRADICTED, naming the violated RULE-ID. Deterministic, zero LLM judgment.
+
+  --doc PATH   the PseudoCode-[Title].md guard-map doc.
+  --map PATH   the build→rule map JSON ({ "rules": { "<id>": { backedBy, contradicted } } }).
+
+Exit: 0 all backed/none contradicted · 4 ≥1 unbacked/contradicted · 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 = runGate(o);
+  } catch (e) {
+    // Defense in depth — runGate 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: `gate-error: ${e && e.message}` };
+  }
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { runGate, parseRules, gateRules, docSlug, _internal: { MARKER_RE, EXPLICIT_ID_RE } };

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