@tekyzinc/gsd-t 4.7.11 → 4.8.10

package/templates/PseudoCode-spec.md

@@ -0,0 +1,194 @@
+# {Title} — {one-line subject of this behavior map}
+
+**Pseudocode + intention for how {the subject} behaves, end to end.**
+Covers WHERE the system makes each decision, WHEN it refuses to, and how the
+result reaches every consumer. **{Scope line — what this is, and the one thing
+it deliberately does NOT do.}**
+
+> **⚠ {THE LOAD-BEARING DIRECTIVE} ({Author}, {date}).** {The single sentence a
+> reader must not miss — the WHY behind the whole map, stated as the user's
+> intention. Prose here is the USER's directive, never agent reasoning.}
+
+_Forward-looking behavior map for **{milestone / scope id}**. Not yet built —
+grounds itself in the EXISTING contracts it must respect:
+`{existing-contract-a}.md`, `{existing-contract-b}.md`, and the frozen
+`{Schema}` (`{field}` / `{field}` / `{field}`). Companion to
+`PseudoCode-{Other}.md`. See `{roadmap ref}` for the milestone scope._
+
+<!--
+  ─────────────────────────────────────────────────────────────────────────────
+  HOW TO USE THIS MOLD  (delete this comment block in the real instance)
+  ─────────────────────────────────────────────────────────────────────────────
+  • Name the instance PseudoCode-[Title].md where [Title] is the SUBJECT
+    (PseudoCode-PayPal.md), never a milestone id. Only THIS blank mold keeps the
+    `-spec` suffix.
+  • Author the TWO ALTITUDES in order:
+      1. HIGH-LEVEL APPROACH  — what / why / when, the actors, a one-breath
+         summary table. NO field-level detail. SIGN THIS OFF FIRST.
+      2. DETAILED             — the full numbered `##` section set below, at
+         exemplar granularity (one section per decision boundary).
+  • Every section carries the FIVE SECTION ELEMENTS (see the contract §1):
+      Intention prose · Mechanism pseudocode · one-breath summary ·
+      [RULE] guard map · ⚠ Divergence flags · Appendix.
+  • Each `> **Intention.**` prose block sits ABOVE its fenced pseudocode and is
+    dated + attributed; the prose is the USER's WHY, never agent reasoning.
+  • The Mechanism block grounds in EXISTING contracts/schema and DEFERS concrete
+    identifiers to plan-time-against-the-real-schema.
+  • Guard map: render EVERY invariant as a one-line `[RULE] <invariant>` (or the
+    tagged `<invariant> [RULE — <tag>]` form). One marker = one rule.
+  • Divergence: wherever a NEW intention supersedes shipped code, write an
+    explicit `⚠ Divergence:` flag. Keep = no flag.
+  • Cite each implementing plan task back with:
+        **PseudoCode-Section**: {Title}#<github-slug-of-the-## heading>
+  Grammars are owned by the contract:
+  `.gsd-t/contracts/pseudocode-source-of-truth-contract.md`
+  (§2 guard-map, §3 section-citation, §4 divergence). Do NOT re-derive them here.
+  ─────────────────────────────────────────────────────────────────────────────
+-->
+
+---
+
+<!-- ═══════════════ ALTITUDE 1 — HIGH-LEVEL APPROACH (sign off FIRST) ═══════════════ -->
+
+## The one {call / decision}, in one breath
+
+> **High-Level Approach ({Author}, {date}).** {What this does, why, and when —
+> the actors and the single decision, in plain language. No field-level detail.
+> This altitude is signed off BEFORE the Detailed sections below are written.}
+
+| {Call / decision} | Lives in | Decides | Runs only when… |
+|-------------------|----------|---------|-----------------|
+| **{The call}** | **{realm — Server / Extension / …}** | {what it turns the input into} | {the precondition that triggers it} |
+| **{The read / fallback}** | **{realm}** | {the question it answers} | {seller- / event-initiated trigger} |
+
+> **SCOPE ({Author}, {date}).** {The deliberate OUT-of-scope boundary — what this
+> map does NOT do. State the one status / call / surface it touches and the ones
+> it refuses to touch. This keeps the Detailed sections honest.}
+
+---
+
+<!-- ═══════════════ ALTITUDE 2 — DETAILED (exemplar granularity) ═══════════════ -->
+
+## 0. Where this picks up — {precondition / what exists before}
+
+> **Intention ({Author}, {date}).** {What state the system is in when this map
+> begins — the precondition. If this SUPERSEDES a shipped model, say so here and
+> add the ⚠ Divergence flag below.}
+
+```text
+PRECONDITION:
+  {The exact starting state — what is loaded / grouped / present, and what is
+   deliberately NOT persisted yet.}
+```
+
+> ⚠ **Divergence from shipped {what} (plan-time reconcile):** {what the shipped
+> code does today} vs. {what THIS intention does instead}. {What becomes dead
+> code / what is reused.} Flag for the {milestone} plan.
+> *(Keep = delete this flag. Supersede = keep it, per contract §4.)*
+
+---
+
+## 1. {First boundary} — {the trigger → the actor that owns it}
+
+> **Intention.** {WHY this step exists and what the user wants it to do — the
+> directive. One short paragraph, the user's voice.}
+
+```text
+{ACTOR}  on {trigger}:
+    {step}
+    {the call / the guard}
+    on {outcome}:  {what happens}
+    on {failure}:  {the safe fallback — never a crash}
+```
+
+---
+
+## 2. {Second boundary} — `{the operation}`  (★ {why this one is load-bearing})
+
+> **Intention.** {The WHY. Name the one invariant this section exists to protect
+> — e.g. "every guard makes a double-click HARMLESS".}
+
+```text
+{operationName}({inputs}):
+
+    # ── GATE 1 — {what it validates} (RULE) ────────────────────────────────
+    # Intention: {why this gate exists, in the user's voice}.
+    {load / lock}
+    if {precondition fails}:   → {status / error}   # {what it protects}
+
+    # ── GATE 2 — {backstop} (RULE, backstop) ───────────────────────────────
+    # Intention: {why — name it a backstop if upstream already blocks it}.
+    if {impossible condition}:   → {status}
+
+    # ── STEP 3 — {the side-effecting call} ─────────────────────  ★ {marker}
+    # Intention: {what crosses the boundary and what is deferred to real schema}.
+    {the call}                                   # defer concrete ids to plan-time
+
+    # ── STEP 4 — PERSIST + {atomic effect} (RULE, one tx) ──────────────────
+    # Intention: {the record is born / the state flips — atomically}.
+    in ONE tx:
+        {write}
+        {flip state}
+    return {success shape}
+
+    # ── FAILURE — never half-{do the thing} (RULE) ─────────────────────────
+    # Intention: a failed {op} persists NOTHING — safe retry.
+    on {failure} (any point):  nothing persisted ; → {status}
+```
+
+---
+
+## 3. {Further boundaries as needed} — {one `##` section per decision}
+
+> **Intention.** {Add as many numbered `##` sections as the subject has distinct
+> decision boundaries — match the exemplars' granularity, one section per real
+> decision, not one giant section.}
+
+```text
+{the mechanism for this boundary}
+```
+
+---
+
+## {N}. {Subject}-safety map — every guard, as a one-line [RULE]
+
+```text
+GATE: {condition} → {status}                     [RULE] {the invariant in one line}
+GATE: {lock / serialize}                          [RULE] {what it prevents}
+{deterministic guard}                             [RULE — {tag}] {invariant, tagged form}
+{never-do-this}                                   [RULE] {the prohibition}
+{born / set at this exact point}                  [RULE] {the lifecycle invariant}
+on {failure}: persist NOTHING                     [RULE] {the safe-failure invariant}
+```
+
+**{One paragraph restating the whole safety story in prose: the record is born
+WHEN, the lock means WHAT, the one thing that can never happen, and why every
+retry / double-action is harmless.}**
+
+---
+
+## {Optional} — {ONE STORE / shared-state / known-gaps notes}
+
+> {Optional sections the exemplars carry: a shared-store note, a "Known gaps /
+> status (as of {version})" list. Include only if the subject has them.}
+
+---
+
+## Appendix — Raw pseudocode (no intention comments)
+
+```text
+# ════════════════════════════════════════════════════════════════════════════
+# {REALM A} — {what it covers}
+# ════════════════════════════════════════════════════════════════════════════
+{the §1–§N mechanism, intention prose STRIPPED — the build's quick-reference}
+
+# ════════════════════════════════════════════════════════════════════════════
+# {REALM B} — {what it covers}
+# ════════════════════════════════════════════════════════════════════════════
+{operationName}({inputs}):
+    {guard}                                       # {one-line reason}
+    {the call}                                    # ★ {the load-bearing call}
+    tx: {write} ; {flip state}
+    return {success}
+    on fail: persist NOTHING ; → {status}         # safe retry
+```

package/templates/prompts/keep-or-supersede-subagent.md

@@ -0,0 +1,61 @@
+# Keep-or-Supersede Subagent Prompt — Inherited Shipped-Code Forcing Protocol
+
+<!-- M87 D3 — the forcing keep-or-supersede protocol. PROSE PROTOCOL: its reliability
+     is bounded by how FORCING this prompt is, NOT by a deterministic gate. The
+     deterministic parseDivergence()/formatDivergence() grammar round-trip is M88.
+     Contract: .gsd-t/contracts/pseudocode-source-of-truth-contract.md §4. -->
+
+You are the **keep-or-supersede** agent. Your sole job: for **every model inherited from shipped code** that the milestone is about to encode into its intention-first `PseudoCode-[Title].md`, FORCE an explicit **keep-or-supersede** decision from the user — and on every supersede, WRITE a `⚠ Divergence` flag into the doc. You write ZERO feature code.
+
+## Why this exists (the real failure this prevents)
+
+A real incident: a PayPal-first web app inherited a **stored-draft over-trust** model from shipped code — it assumed a draft already persisted on the PayPal server was still valid, and re-confirmed deletion against that stale draft instead of re-checking the live state. The shipped model was silently carried forward as if it were intention, and the bug shipped with it. The rescue was to STOP at each inherited model and ask the user, out loud: *"do we keep this behavior, or does a new intention supersede it?"* — and to RECORD every supersede so the divergence from shipped code is never silent.
+
+This protocol bakes that rescue into the methodology. Inherited code is a HYPOTHESIS about intent, never a proven intent. Encoding it without asking is the deadly pattern.
+
+## The Forcing Rule (non-negotiable)
+
+**Never encode an inherited shipped-code model without an explicit keep-or-supersede decision.** "It already works this way" is NOT a keep decision — it is the un-asked assumption this protocol exists to break. For each inherited model:
+
+1. **Surface it plainly.** State the inherited behavior in one jargon-free sentence: what the shipped code currently does, where it lives (the file/realm), and the model it embeds. Lead with a short concrete example of when that behavior bites, then map it to the code in one line — so the user can decide with understanding, not rubber-stamp.
+2. **ASK, do not assume.** Present exactly two choices and require a decision:
+   - **KEEP** — the shipped behavior IS the intended behavior. The doc encodes it as-is. **No flag is written.**
+   - **SUPERSEDE** — a new intention replaces the shipped behavior. The doc encodes the NEW intention, and a `⚠ Divergence` flag is WRITTEN (see below).
+3. **The doc prose is the USER'S intention, never your reasoning.** When you write the superseding intention, write what the USER decided and why, in their framing — not your justification for it.
+4. **Default is NOT silent keep.** If the user has not decided, you do NOT proceed by silently keeping. You ASK. An un-asked inherited model is an open question, never a default-on behavior (`feedback_no_silent_degradation`, `feedback_unproven_assumption_stop_and_research`).
+
+## On SUPERSEDE — write the Divergence flag (mandatory)
+
+Every **supersede** WRITES a `⚠ Divergence` flag into `PseudoCode-[Title].md`, using the §4 grammar shape exactly:
+
+```
+⚠ Divergence: <RULE-ID or section> — supersedes shipped <what>. Reason: <user intention>.
+```
+
+- `<RULE-ID or section>` — the guard-map RULE-ID or the doc section the divergence attaches to.
+- `<what>` — the shipped behavior being superseded, in one phrase.
+- `<user intention>` — WHY, in the user's framing (the new intention that replaces it).
+
+**KEEP writes no flag.** One supersede → exactly one flag. The flag is captured IN the doc so the divergence from shipped code is an explicit, visible artifact — never silent.
+
+> **M87/M88 split.** In M87 this flag is WRITTEN by this prose protocol (the ASK + the write). The DETERMINISTIC `parseDivergence()` / `formatDivergence()` round-trip — making the divergence COUNT a code-checkable, byte-stable artifact that can feed the guard-map rule set — is **M88** (backlog #35). The §4 grammar is the spec for both; only the round-trip IMPLEMENTATION is deferred. Here, your obligation is: ask, and on supersede, write a well-formed flag.
+
+## What to do (step by step)
+
+1. **Enumerate inherited models.** From the brief / requirements / the shipped code being carried forward, list every behavioral model the milestone would inherit. If `$BRIEF_PATH` is set, read it first (the ≤2,500-token snapshot) before re-walking the repo.
+2. **For each inherited model, run the Forcing Rule above** — surface it, ASK keep-or-supersede, get the decision.
+3. **On KEEP:** encode the behavior as-is in the doc. No flag.
+4. **On SUPERSEDE:** encode the NEW intention (in the user's framing) and WRITE the `⚠ Divergence` flag in §4 grammar.
+5. **Report** the full keep/supersede ledger: every inherited model, the decision, and for each supersede the exact flag written.
+
+## Report Format
+
+```
+Inherited models reviewed: N
+- <model>: KEEP — encoded as-is.
+- <model>: SUPERSEDE — flag written: "⚠ Divergence: <ref> — supersedes shipped <what>. Reason: <intention>."
+...
+Divergence flags written: M  (= number of supersedes)
+```
+
+If ANY inherited model was encoded WITHOUT an explicit keep-or-supersede decision, that is a protocol FAILURE — report it as such; do not mark the work complete.

package/templates/prompts/qa-subagent.md

@@ -8,6 +8,16 @@ You are the QA agent. Your sole job is test generation, execution, and gap repor
 <!-- M55-D5: brief-first rule -->
 **Brief first.** If you're about to grep, read, or run a test, check the brief first at `$BRIEF_PATH` (a ≤2,500-token JSON snapshot of CLAUDE.md + contracts + scope + constraints, generated by `bin/gsd-t-context-brief.cjs`). The brief replaces the 30–60k context re-read every parallel worker would otherwise perform — it's the dominant ITPM-relief lever in M55. If `$BRIEF_PATH` is unset or the file is missing, fall back to the legacy read-everything pattern, but log a note so the orchestrator can see the gap.
 
+<!-- guard-map-ingest -->
+**Guard-map rule ingest (A5 — contract-compliance frame).** When a guard-map is
+present, the surfaced RULE-ID set reaches you via
+`gsd-t rule-consume --map <guard-map.json> --json` → the `qa` array. INGEST that
+set: treat **every RULE-ID as a required compliance assertion**. For each id, the
+build/tests MUST demonstrate the rule's invariant holds — an unverified or
+unasserted rule is a contract-compliance FAILURE, not a pass. Do NOT drop, skip,
+or sample rules: every id in the `qa` frame is a mandatory check.
+<!-- /guard-map-ingest -->
+
 ## What to Do
 
 1. **Detect every configured test suite** in this project — vitest/jest/mocha config, `playwright.config.*`, `cypress.config.*`. Run EVERY suite that exists.

package/templates/prompts/red-team-subagent.md

@@ -8,6 +8,18 @@ You are a Red Team QA adversary. Your job is to BREAK the code that was just wri
 <!-- M55-D5: brief-first rule -->
 **Brief first.** If you're about to grep, read, or run a test, check the brief first at `$BRIEF_PATH` (a ≤2,500-token JSON snapshot of CLAUDE.md + contracts + scope + constraints + recent commits, generated by `bin/gsd-t-context-brief.cjs --kind red-team`). The brief identifies high-risk surfaces, recent diffs, and contract status — your starting attack surface. The brief replaces the 30–60k context re-read every parallel worker would otherwise perform. If `$BRIEF_PATH` is unset or the file is missing, fall back to the legacy read-everything pattern, but log a note so the orchestrator can see the gap.
 
+<!-- guard-map-ingest -->
+**Guard-map rule ingest (A5 — attack-surface frame).** When a guard-map is
+present, the surfaced RULE-ID set reaches you via
+`gsd-t rule-consume --map <guard-map.json> --json` → the `redTeam` array. INGEST
+that set: treat **every RULE-ID as an invariant to ATTACK**. For each id, mount a
+concrete attack that tries to make the rule's invariant FALSE (boundary inputs,
+race/double-submit, out-of-order state, error paths). A rule you cannot break
+after an exhaustive attempt is a defended invariant; a rule you DROP from your
+attack plan is a seam breach. Do NOT sample — every id in the `redTeam` frame
+must be attacked.
+<!-- /guard-map-ingest -->
+
 ## Hard Rules
 
 - **Bugs found = value.** A short attack list is failure.

package/templates/workflows/gsd-t-phase.workflow.js

@@ -555,9 +555,19 @@ const _PROBE_SCHEMA = {
     approaches: { type: "array", items: { type: "string" } },
   },
 };
-async function runSolutionSpaceProbe(projectDir, phaseName, { milestone, briefPath, userInput, phaseNameOpt } = {}) {
+async function runSolutionSpaceProbe(projectDir, phaseName, { milestone, briefPath, userInput, phaseNameOpt, altitude } = {}) {
+  // M87 altitude shift: when behavior is SPEC'D (the milestone is authored at the
+  // intention-first high-level-approach altitude), the milestone solution-space
+  // probe shifts UP — it competes over high-level APPROACHES (what/why/when, actors,
+  // one-breath thesis), NOT lower-altitude implementation detail. This changes WHAT
+  // the producers compete on, never WHO competes (producers stay opus, judge differs —
+  // M82 blindness invariant preserved) nor the probe's model (stays fable).
+  const atApproachAltitude = altitude === "high-level-approach";
   const prompt = [
     `You are the Solution-Space Probe for the ${phaseName} phase${milestone ? ` of ${milestone}` : ""}. Decide ONE thing: should this phase generate MULTIPLE competing candidates (then a judge picks the best), or is a single draft sufficient?`,
+    atApproachAltitude
+      ? `ALTITUDE: HIGH-LEVEL APPROACH (M87 — behavior is spec'd intention-first). Compete over distinct high-level APPROACHES — what/why/when, the actors, the one-breath thesis — NOT over field-level implementation detail. The competition is about WHICH approach best serves the intention, decided before the detailed PseudoCode-[Title].md is authored.`
+      : "",
     `**Brief:** ${briefPath || "(none — read the relevant .gsd-t docs/contracts/requirements directly)"}`,
     userInput ? `\nUser input:\n${userInput}\n` : "",
     `Compete WHEN there are ≥2 genuinely DIFFERENT, viable approaches whose trade-offs matter — different architectures, decomposition strategies, data models, sequencing, or design directions that a reasonable expert could disagree about. List them in "approaches".`,
@@ -690,9 +700,13 @@ if (_competitionEligible) {
     // Automatic decision — the workflow probes and decides. Opus probe (or the
     // partition-specific probe); biased toward competing.
     phase("Probe");
+    // M87: the milestone phase is authored intention-first — behavior is spec'd at the
+    // high-level-approach altitude, so its solution-space probe shifts UP to compete over
+    // high-level approaches (not implementation detail). Other phases keep their altitude.
+    const _probeAltitude = phaseName === "milestone" ? "high-level-approach" : undefined;
     const probe = phaseName === "partition"
       ? await runPartitionProbe(projectDir, { milestone, briefPath: brief.briefPath, userInput, phaseNameOpt: "Probe" })
-      : await runSolutionSpaceProbe(projectDir, phaseName, { milestone, briefPath: brief.briefPath, userInput, phaseNameOpt: "Probe" });
+      : await runSolutionSpaceProbe(projectDir, phaseName, { milestone, briefPath: brief.briefPath, userInput, phaseNameOpt: "Probe", altitude: _probeAltitude });
     competitionOn = !!probe.compete;
     competitionN = competitionOn ? AUTO_COMPETITION_N : 1;
     log(`competition: AUTO → ${competitionOn ? `COMPETE (${AUTO_COMPETITION_N} producers)` : "single draft"} — ${probe.reason}${probe.approaches && probe.approaches.length ? ` [approaches: ${probe.approaches.join("; ")}]` : ""}`);
@@ -720,6 +734,12 @@ ${STATED_CLAIMS_INSTRUCTION}`,
 ${STATED_CLAIMS_INSTRUCTION}`,
   milestone: `Define a new milestone — origin, goal, success criteria, falsifiable acceptance. Append to .gsd-t/progress.md. Defer partition/plan.
 
+TWO-ALTITUDE INTENTION-FIRST FLOW (M87, default-ON — contract pseudocode-source-of-truth-contract.md §1). Author the milestone at two altitudes, IN ORDER:
+  ALTITUDE 1 — HIGH-LEVEL APPROACH (signed off FIRST): emit the high-level approach pseudocode — what/why/when (the user's intention, never agent reasoning), the actors, and a one-breath summary ("one call in one breath"). PRESENT this approach to the user for SIGN-OFF. The detailed doc is authored ONLY AFTER the approach is approved — the sign-off is the checkpoint between the two altitudes. (This is a PROSE flow: describe the checkpoint; do NOT assert a machine-checkable DEFINED-state predicate — that is M88.)
+  ALTITUDE 2 — DETAILED doc: only after the approach is signed off, author .gsd-t/pseudocode/PseudoCode-[Title].md at exemplar granularity (the §1 section set: Intention, Mechanism, one-breath table, Guard map, Divergence flags, Appendix). [Title] = the SUBJECT (e.g. PseudoCode-PayPal.md), never a milestone id; a milestone may produce several.
+DEFAULT-ON; skip is a LOGGED decision in progress.md naming WHY — NEVER a silent default-off (feedback_no_silent_degradation).
+KEEP-OR-SUPERSEDE: before encoding any model inherited from shipped code, run the keep-or-supersede protocol (templates/prompts/keep-or-supersede-subagent.md) — per inherited model ASK keep or supersede; each supersede WRITES a ⚠ Divergence flag (§4 grammar) into the doc. Keep = no flag.
+
 ${STATED_CLAIMS_INSTRUCTION}`,
   prd: `Generate a product requirements doc at docs/prd.md. Functional + non-functional requirements traceable to acceptance criteria.`,
   "design-decompose": `Decompose a design reference (Figma URL / images) into hierarchical contracts: elements -> widgets -> pages, each at .gsd-t/contracts/design/.`,

package/templates/workflows/gsd-t-verify.workflow.js

@@ -39,6 +39,7 @@ export const meta = {
     { title: "Auto-Research Gate", detail: "M89 §7 ENFORCE: scan for status=uncited markers (A4 — no silent guess)" },
     { title: "CI-Parity",          detail: "M57 build-coverage + ci-parity (FAIL-blocking)" },
     { title: "Test-Data Purge",    detail: "M58 test-data --purge (FAIL-blocking)" },
+    { title: "Guard-Map Gate",     detail: "M87 [RULE] guard-map gate (FAIL-blocking, §7 discovery)" },
     { title: "Orthogonal Triad",   detail: "code-review ultra ∥ Red Team ∥ QA" },
     { title: "Synthesis",          detail: "merge without collapsing categories" },
   ],
@@ -517,7 +518,105 @@ if (!td.ok) {
   log(`M58 test-data purge FAIL exitCode=${td.exitCode} — halting (FAIL-blocking)`);
   return { status: "test-data-purge-failed", overallVerdict: "VERIFY-FAILED", testDataPurge: td.envelope };
 }
-log(`M58 test-data purge green — proceeding to orthogonal triad`);
+log(`M58 test-data purge green — proceeding to guard-map gate`);
+
+// ─── M87 D1 Guard-Map Gate (FAIL-blocking — A1 / SC1) ─────────────────────
+// Turns each PseudoCode-[Title].md prose `[RULE]` guard map into a
+// machine-checkable gate: a divergent (UNBACKED or CONTRADICTED) rule HALTS
+// verify BEFORE the triad, at contract-breach severity, naming the RULE-ID —
+// zero LLM judgment in the pass/fail decision (deterministic, like verify-gate /
+// CI-parity / test-data).
+//
+// Discovery per contract §7 (deterministic, path-as-path):
+//   1. glob `.gsd-t/pseudocode/PseudoCode-*.md` (multi-doc — a milestone may
+//      produce several subjects).
+//   2. each doc's map = same basename with `.md` → `.map.json`, co-located.
+//   3. pairing outcomes (each OBSERVABLE, never a silent pass):
+//        - doc + co-located map  → FIRE the gate on that pair.
+//        - doc with no map       → logged skip-with-reason `no-build-map`.
+//        - zero docs             → logged skip-with-reason `no-pseudocode-docs`.
+//   4. the fire path passes `--doc <doc> --map <map>` to gsd-t-guard-map.cjs; any
+//      FAIL-blocking non-zero HALTS verify before the triad.
+// M81: no fs — a haiku discovery agent globs + pairs and returns the set; each
+// fire-able pair is gated via the runCli helper (model: haiku, like the other gates).
+// Contract: pseudocode-source-of-truth-contract.md §2 + §7.
+phase("Guard-Map Gate");
+const GUARD_MAP_DISCOVERY_SCHEMA = {
+  type: "object",
+  required: ["docsFound", "firePairs", "skips"],
+  additionalProperties: true,
+  properties: {
+    docsFound: { type: "integer" },
+    firePairs: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["doc", "map"],
+        properties: { doc: { type: "string" }, map: { type: "string" } },
+      },
+    },
+    skips: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["reason"],
+        properties: { reason: { type: "string" }, doc: { type: "string" } },
+      },
+    },
+    notes: { type: "string" },
+  },
+};
+const guardMapDiscovery = await agent(
+  [
+    `You are the M87 guard-map discovery scanner for the project at "${projectDir}". Discover the PseudoCode doc + build-map pairs per contract §7 (deterministic, path-as-path) and return JSON. Do NOT gate anything — only enumerate.`,
+    ``,
+    `Steps:`,
+    `1. Glob the docs: \`ls ${projectDir}/.gsd-t/pseudocode/PseudoCode-*.md 2>/dev/null || true\`. These are the candidate docs (a milestone may produce SEVERAL — handle the multi-doc set).`,
+    `2. docsFound = the number of PseudoCode-*.md docs found.`,
+    `3. For EACH doc, the build-map is the SAME basename with \`.md\` replaced by \`.map.json\`, co-located in \`.gsd-t/pseudocode/\` (e.g. PseudoCode-Foo.md → PseudoCode-Foo.map.json). Check it exists: \`test -f <map> && echo EXISTS || echo ABSENT\`.`,
+    `   - doc + co-located map EXISTS → add { "doc": "<abs-or-project-rel doc path>", "map": "<map path>" } to firePairs.`,
+    `   - doc with map ABSENT → add { "reason": "no-build-map", "doc": "<doc path>" } to skips (a logged skip WITH A REASON, never a silent pass).`,
+    `4. If docsFound === 0 → firePairs is empty and skips = [ { "reason": "no-pseudocode-docs" } ] (the gate legitimately has nothing to gate, but the skip is SURFACED, not silent).`,
+    ``,
+    `Return JSON per the schema: { "docsFound": N, "firePairs": [ { "doc", "map" } ], "skips": [ { "reason", "doc"? } ], "notes": "..." }. Discovery is path-as-path (glob + basename derivation), never substring.`,
+  ].join("\n"),
+  { label: "guard-map-discovery", phase: "Guard-Map Gate", schema: GUARD_MAP_DISCOVERY_SCHEMA, model: "haiku" }
+).catch((e) => ({ docsFound: 0, firePairs: [], skips: [{ reason: "discovery-error" }], notes: `guard-map discovery agent error: ${e && e.message}` }));
+
+const guardMapResults = [];
+if (guardMapDiscovery.docsFound === 0 || (guardMapDiscovery.firePairs || []).length === 0) {
+  // No fire-able pair — surface the DISTINCT skip reason(s), never a silent pass.
+  const reasons = (guardMapDiscovery.skips || []).map((s) => s.reason).join(", ") || "no-pseudocode-docs";
+  log(`M87 guard-map gate: SKIP (no fire-able doc+map pair) — reason(s): ${reasons}`);
+} else {
+  for (const pair of guardMapDiscovery.firePairs) {
+    const gmr = await runCli(
+      projectDir,
+      "guard-map",
+      ["--doc", pair.doc, "--map", pair.map, "--json"],
+      "gsd-t-guard-map.cjs",
+      `m87:guard-map:${pair.doc.split("/").pop()}`,
+      true,
+      "Guard-Map Gate"
+    );
+    guardMapResults.push({ pair, envelope: gmr.envelope, ok: gmr.ok, exitCode: gmr.exitCode });
+    if (!gmr.ok) {
+      const env = gmr.envelope || {};
+      const named = (env.violations || []).map((v) => v.id).join(", ") || env.reason || "(rule id unavailable)";
+      log(`M87 guard-map gate FAIL exitCode=${gmr.exitCode} on ${pair.doc} — divergent RULE(s): ${named} — halting before triad`);
+      return {
+        status: "guard-map-gate-failed",
+        overallVerdict: "VERIFY-FAILED",
+        reason: `M87 guard-map divergence on ${pair.doc}: ${named} (unbacked or contradicted [RULE]) — back/cite the rule, then re-verify`,
+        guardMap: { discovery: guardMapDiscovery, results: guardMapResults },
+        verifyGate: vg.envelope,
+        autoResearchGate: arGate,
+      };
+    }
+    log(`M87 guard-map gate: PASS on ${pair.doc} — all ${(gmr.envelope && gmr.envelope.ruleCount) || "?"} [RULE]s backed, none contradicted`);
+  }
+  log(`M87 guard-map gate green (${guardMapResults.length} doc+map pair(s) fired) — proceeding to orthogonal triad`);
+}
 
 phase("Orthogonal Triad");
 
@@ -629,6 +728,7 @@ return {
   buildCoverage: bc.envelope,
   ciParity: cip.envelope,
   testDataPurge: td.envelope,
+  guardMap: { discovery: guardMapDiscovery, results: guardMapResults },
   triad: triadResults,
   verdict,
 };