@tekyzinc/gsd-t 5.1.13 → 5.2.11

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.2.11] - 2026-07-22
+
+### Changed — architect-overview cleanup (dead tool, shared reader, archived contracts)
+
+Applied the three safe findings from a `/gsd-t-architect` framework-overview pass, and recorded a correction to a wrong finding.
+
+- Deleted `bin/model-selector.js` + `test/model-selector.test.js` — the M35 model picker with zero live callers, superseded by M85's `bin/gsd-t-model-tier-policy.cjs`. Scrubbed 3 stale `selectModel()` doc references (`gsd-t-quick.md`, `gsd-t-test-sync.md`, `templates/CLAUDE-project.md`, `README.md`).
+- Extracted a shared marker-block *reader* (`extractMarkedDocBlock`) into `bin/gsd-t-doc-marker.cjs` and rewired `bin/gsd-t-env-registry.cjs::extractBlock` to it — finishing the M102 writer/reader extraction. The verify-gate's independent copy is left intact on purpose (defensive-independence invariant — a writer bug must not disable the gate).
+- Archived 13 stale `mXX-integration-points.md` contracts to `.gsd-t/milestones/_integration-points-archive/`. `m94-integration-points.md` was RESTORED — 3 live M94 tests read it by path (a live fixture, not archaeology).
+
+Recorded in `progress.md`: the overview's "graph subsystem is broken sprawl" finding was a **false negative** — it checked the pre-M99 path `.gsd-t/graph.db`; the real store moved to `.gsd-t/graphDB/graph.db` (M99 consolidation, already shipped, with a canonical resolver). The graph builds and works in every project. No code change — the correction is the deliverable.
+
+Suite: 3020/3020 pass, 13 skipped.
+
+## [5.2.10] - 2026-07-17
+
+### Added — Environment Registry (M102): the committed, secret-free connection map
+
+Every project now gets ONE `## Environments` table in `docs/infrastructure.md` recording each environment's connection MAP (host/port/db/auth/which-vault-holds-the-secret/env-var-NAME/connect-command) — so the AI stops re-discovering non-local DB/server URLs, credentials, and permissions from scratch. Two triggers on one mechanism: **record-at-create** (greenfield — record the map as GSD-T builds the env) and **capture-on-first-need** (brownfield — first access with no row HALTs → detect → ask → record → add broad-glob permission → proceed; never guesses a connection string, never greps transcripts).
+
+The hard invariant — **no secret VALUE ever in a committed cell** — took NINE Red Team cycles to converge. Value denylists (cycles 1-4) and a secret-flag-name denylist (5-6) both failed as open categories; a "safe value" slot regressed to an entropy floor (7). The converged design: a CLOSED **safe-label allowlist** (`-U`/`-d`/`-h`/`--port`/`--secret`) with **typed value shapes** (port=digits, host=host-shape, user/db=tight-db-name), a **strict command-hostname** (lowercase labels ≤24, alpha TLD — kills dotted-token laundering), and the entropy detector demoted to a dot-stripping backstop. A strong/random credential fails every typed shape → must be `$VAR`; a weak dictionary-word username passes (not a *recognizable* secret). Cycle 9 = GRUDGING-PASS (20k-command fuzz, zero writer/gate divergence).
+
+- `bin/gsd-t-env-registry.cjs`: writer — converged command grammar, upsert-by-(scope,kind), `detectEnvConfig`, `addPermissionEntry`, `ensureEnvGitignored`, per-project local-literal switch, `detectCommandLeak`/`proposeRemediation`.
+- `bin/gsd-t-env-registry-check.cjs`: independent verify gate — re-implements the same grammar so a writer bug can't disable it; overflow-column hard-fail; opted-in local-row exemption.
+- `bin/gsd-t-doc-marker.cjs`: shared marker-block doc writer (extracted from the M100 logging scaffolder — no third copy).
+- `bin/gsd-t-verify-gate.cjs`: env-registry FAIL-closed gate wired into the substrate track.
+- `bin/gsd-t.js`: env-registry bins added to `PROJECT_BIN_TOOLS`.
+- `commands/gsd-t-init.md`: record-at-create trigger + `ensure-gitignore`.
+- `commands/gsd-t-populate.md`: capture-on-first-need HALT + leak-remediation + local-literal switch.
+- `templates/infrastructure.md`: marker-delimited `## Environments` table (map-only columns).
+- `templates/CLAUDE-global.md`: "Environment Access — read-first, HALT-and-document" rule.
+- `.gsd-t/contracts/env-registry-contract.md` v1.1.0; `.gsd-t/pseudocode/PseudoCode-EnvironmentRegistry.md` §E (converged design).
+- `test/m102-env-registry.test.js`: 274 tests — the full 9-cycle Red Team leak corpus as regressions.
+
+A project may opt in to literal secrets in `scope=local` rows via `.gsd-t/env-registry-config.json` `{"allowLocalLiteral": true}` (staging/prod always strict). Repo suite 3077/0.
+
 ## [5.1.13] - 2026-07-15
 
 ### Changed — explicit "No Preambles" rule with banned openers

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.1.13** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.2.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.
@@ -18,7 +18,7 @@
 **Rigorous User-Journey Coverage + Anti-Drift Test Quality** — `bin/journey-coverage.cjs` regex listener detector + `gsd-t check-coverage` CLI + `scripts/hooks/pre-commit-journey-coverage` commit gate blocks viewer-source commits when uncovered listeners exist. Journey specs in `e2e/journeys/` use functional assertions (zero `toBeVisible`-only tests) per the E2E Test Quality Standard in CLAUDE.md.
 **Universal Playwright Bootstrap + Deterministic UI Enforcement (M50)** — three executable enforcement layers: (1) `bin/playwright-bootstrap.cjs` + `bin/ui-detection.cjs` - idempotent installer detects package manager, installs `@playwright/test` + chromium, scaffolds `e2e/`; (2) Workflow runtime runs `playwright-bootstrap.cjs::installPlaywright()` before any E2E stage when `hasUI && !hasPlaywright`; install failure halts with `blocked-needs-human`; (3) `scripts/hooks/pre-commit-playwright-gate` (opt-in via `gsd-t doctor --install-hooks`) blocks viewer-source commits when staged files are newer than `.gsd-t/.last-playwright-pass`. The `gsd-t setup-playwright [path]` subcommand handles manual install.
 **Visualizer (`/gsd-t-visualize`)** — launches a real-time browser dashboard with dual-pane view: top pane streams the main session, bottom pane streams whichever spawn the user clicks. Left rail shows Live Spawns and Completed (last 100 spawns, status-badged, collapsible). Right rail shows Spawn Plan / Parallelism / Tool Cost. Powered by `gsd-t-stream-feed-server.js` + `gsd-t-dashboard.html`.
-**Surgical model selection** — `bin/model-selector.js` assigns haiku/sonnet/opus/fable per phase via a declarative rules table; `/advisor` escalation path with convention-based fallback. **M85 single-source tier policy:** `bin/gsd-t-model-tier-policy.cjs` is the SINGLE source of truth for model-tier assignments; the 5 highest-leverage stages (solution-space probe, partition probe, competition judge, pre-mortem, Red Team) run on `fable` (Claude Fable 5, tier above Opus); competition producers stay `opus` (M82 blindness); debug escalates cycle-1→opus, cycle-2→fable. Drift is mechanically enforced by the M71-family lint (`test/m85-workflow-tier-policy-lint.test.js`). **M86 model profiles:** `bin/gsd-t-model-profile.cjs` adds a per-project SECOND dimension — three named profiles (`standard` / `pro` / `premium`) that control which stages run on Fable vs. Opus/Sonnet (see [Model Profiles](#model-profiles) below).
+**Surgical model selection** — models are assigned haiku/sonnet/opus/fable per phase. **M85 single-source tier policy:** `bin/gsd-t-model-tier-policy.cjs` is the SINGLE source of truth for model-tier assignments; the 5 highest-leverage stages (solution-space probe, partition probe, competition judge, pre-mortem, Red Team) run on `fable` (Claude Fable 5, tier above Opus); competition producers stay `opus` (M82 blindness); debug escalates cycle-1→opus, cycle-2→fable. Drift is mechanically enforced by the M71-family lint (`test/m85-workflow-tier-policy-lint.test.js`). **M86 model profiles:** `bin/gsd-t-model-profile.cjs` adds a per-project SECOND dimension — three named profiles (`standard` / `pro` / `premium`) that control which stages run on Fable vs. Opus/Sonnet (see [Model Profiles](#model-profiles) below).
 **Token Telemetry** — `gsd-t-calibration-hook.js` records token usage per spawn to `.gsd-t/token-metrics.jsonl` (18-field rows). `gsd-t-token-aggregator.js` aggregates across tasks for the `/gsd-t-metrics` view. Use the native Claude Code `/context` command for live in-session context percentage.
 **Quality North Star** — projects define a `## Quality North Star` section in CLAUDE.md (1–3 sentences, e.g., "This is a published npm library. Every public API must be intuitive and backward-compatible."). `gsd-t-init` auto-detects preset (library/web-app/cli) from package.json signals; `gsd-t-setup` configures it for existing projects. Subagents read it as a quality lens; absent = silent skip (backward compatible).
 **Design Brief Artifact** — during partition, UI/frontend projects (React, Vue, Svelte, Flutter, Tailwind) automatically get `.gsd-t/contracts/design-brief.md` with color palette, typography, spacing system, component patterns, and tone/voice. Non-UI projects skip silently. User-customized briefs are preserved. Referenced in plan phase for visual consistency.
@@ -466,7 +466,6 @@ get-stuff-done-teams/
 │   ├── graph-*.js                     # Code graph engine (CGC/Neo4j integration)
 │   ├── journey-coverage.cjs           # Listener detector + coverage gap reporting
 │   ├── playwright-bootstrap.cjs       # Idempotent Playwright installer
-│   ├── model-selector.js              # Phase-to-model assignment (haiku/sonnet/opus/fable)
 │   ├── gsd-t-model-tier-policy.cjs    # M85: single-source tier policy (haiku/sonnet/opus/fable), resolver CLI
 │   ├── rule-engine.js                 # Declarative failure-pattern rules
 │   ├── patch-lifecycle.js             # 5-stage patch candidate→graduated lifecycle

package/bin/gsd-t-doc-marker.cjs

@@ -0,0 +1,83 @@
+"use strict";
+
+// bin/gsd-t-doc-marker.cjs
+//
+// M102 — the ONE shared marker-block idempotent doc-writer. Extracted from the
+// M100 logging scaffolder's private `writeChoiceToProjectDocs` (so there is a
+// single writer, not two copies): both bin/gsd-t-logging-scaffolder.cjs and
+// bin/gsd-t-env-registry.cjs call this.
+//
+// upsertMarkedDocBlock(targetPath, startMarker, endMarker, block):
+//   - If targetPath contains BOTH markers, the region between them (inclusive)
+//     is REPLACED with `block` (idempotent re-write).
+//   - Otherwise `block` is appended to the end of the file (creating the file
+//     and any missing parent dirs).
+//   - `block` MUST already begin with startMarker and end with endMarker — the
+//     caller composes the full block (same contract the M100 writer used).
+//
+// Zero external npm runtime deps — fs/path only. Symlink-guarded: refuses to
+// write through a symlinked target (defense-in-depth, matches the installer's
+// settings-writer scaffold).
+
+const fs = require("fs");
+const path = require("path");
+
+function isSymlink(filePath) {
+  try {
+    return fs.lstatSync(filePath).isSymbolicLink();
+  } catch (_) {
+    return false;
+  }
+}
+
+// Replace the [startMarker … endMarker] region with `block`, or append it.
+// Returns the written targetPath. Idempotent: a second call with the same
+// block leaves the file byte-identical.
+function upsertMarkedDocBlock(targetPath, startMarker, endMarker, block) {
+  if (!targetPath) throw new Error("upsertMarkedDocBlock: targetPath is required");
+  if (!startMarker || !endMarker) throw new Error("upsertMarkedDocBlock: start/end markers are required");
+  if (typeof block !== "string") throw new Error("upsertMarkedDocBlock: block must be a string");
+
+  if (isSymlink(targetPath)) {
+    throw new Error(`upsertMarkedDocBlock: refusing to write through symlinked target: ${targetPath}`);
+  }
+
+  let content = "";
+  if (fs.existsSync(targetPath)) {
+    content = fs.readFileSync(targetPath, "utf8");
+  } else {
+    const dir = path.dirname(targetPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+
+  if (content.includes(startMarker) && content.includes(endMarker)) {
+    const startIdx = content.indexOf(startMarker);
+    const endIdx = content.indexOf(endMarker) + endMarker.length;
+    content = content.slice(0, startIdx) + block + content.slice(endIdx);
+  } else {
+    content = content.replace(/\s*$/, "") + "\n\n" + block + "\n";
+  }
+
+  fs.writeFileSync(targetPath, content, "utf8");
+  return targetPath;
+}
+
+// Read the marked block back OUT of `content`. Returns the slice from the START
+// marker up to (but NOT including) the END marker — i.e. the block body a parser
+// walks line-by-line — or null if either marker is absent. The complement of
+// upsertMarkedDocBlock's write. (Shared so a reader isn't re-implemented per
+// caller — the env-registry writer/reader used to copy this inline.)
+//
+// NOTE: the verify GATE (gsd-t-env-registry-check.cjs) deliberately does NOT use
+// this — it re-implements the extract independently so a bug here cannot disable
+// the gate (M102 defensive-independence invariant). That duplication is
+// load-bearing; do not "consolidate" it.
+function extractMarkedDocBlock(content, startMarker, endMarker) {
+  if (typeof content !== "string" || !startMarker || !endMarker) return null;
+  if (!content.includes(startMarker) || !content.includes(endMarker)) return null;
+  const start = content.indexOf(startMarker);
+  const end = content.indexOf(endMarker);
+  return content.slice(start, end);
+}
+
+module.exports = { upsertMarkedDocBlock, extractMarkedDocBlock };

package/bin/gsd-t-env-registry-check.cjs

@@ -0,0 +1,449 @@
+"use strict";
+
+// bin/gsd-t-env-registry-check.cjs
+//
+// M102 D3 — the deterministic verify-gate lint for the Environment Registry.
+// FAIL-CLOSED. Two failure conditions (spec D3):
+//   (a) any Environments row cell is NOT the POSITIVE shape its column is
+//       supposed to hold (a value that is not a real hostname / not the enum /
+//       not a $VAR / not a curated command token = a probable inline secret);
+//   (b) the env-access DOC RULE is present in the project's CLAUDE.md but the
+//       `## Environments` table MARKERS are absent from docs/infrastructure.md
+//       (rule promises a registry the doc doesn't provide).
+//
+// A project that has neither the table nor the rule is a NO-OP PASS (it simply
+// hasn't adopted M102 yet) — distinguishable from a wired-but-broken FAIL.
+//
+// Zero external npm runtime deps — fs/path only.
+//
+// PRIMARY GUARD = POSITIVE PER-COLUMN SHAPE (re-derived here, NOT a call into
+// the writer). The gate RE-IMPLEMENTS the positive shapes so a writer bug can
+// never silently disable it. It maps each cell to its column and requires the
+// cell to BE the shape that column holds:
+//   - host        → localhost / IPv4 / dotted-DNS / short lowercase service label
+//   - db/name     → short lowercase snake identifier (≤16, no digit→letter)
+//   - auth method → enumerated auth-method name
+//   - fetch/connect command → every token is $VAR / flag / hostname / curated word
+//   - access gotchas → enumerated (vpn|ip-allowlist|ssh-tunnel|bastion|none) + via host
+//   - secret vault → enumerated vault name
+//   - secret env-var NAME → UPPER_SNAKE
+// A cell that is NOT its column's positive shape → FAIL.
+//
+// BACKSTOP (extra layer, applied to EVERY cell regardless of column): the
+// imported known-prefix/JWT/base64/hex `looksLikeSecretValue` + the gate's OWN
+// embedded-credential regex. These are NOT the primary guard — the positive
+// per-column shape is. A secret that somehow matched a positive shape (it can't
+// by construction) would still trip these.
+
+const fs = require("fs");
+const path = require("path");
+
+const {
+  ENV_MARKER_START,
+  ENV_MARKER_END,
+  ENV_COLUMNS,
+  looksLikeSecretValue,
+} = require("./gsd-t-env-registry.cjs");
+
+// The gate ALSO carries its own inline embedded-credential detector so it is
+// not solely dependent on the imported symbol — a proto://user:pw@ literal in
+// ANY cell fails independently of the writer's classification.
+const GATE_EMBEDDED_CRED = /[a-z][a-z0-9+.\-]*:\/\/[^\s:/@]+:(?!\$)[^\s:/@]+@/i;
+
+// ─── Gate's OWN re-implemented POSITIVE shapes (independent of the writer) ────
+//
+// Deliberately re-declared here (not imported) so the gate is a genuinely
+// independent implementation — a bug in the writer's shapes cannot disable the
+// gate's.
+
+const GATE_DOTTED_HOSTNAME =
+  /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
+// STRICT command hostname (cycle-8 mirror): lowercase labels ≤24, alpha TLD —
+// so a dotted high-entropy token cannot launder through the command grammar.
+const GATE_STRICT_CMD_HOSTNAME =
+  /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,22}[a-z0-9])?\.)+[a-z]{2,}$/;
+const GATE_IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const GATE_BARE_HOST_LABEL = /^[a-z][a-z-]{0,15}$/;
+const GATE_VAR_REF = /^["']?\$\{?[A-Za-z_][A-Za-z0-9_]*\}?["']?$/;
+const GATE_UPPER_SNAKE = /^[A-Z][A-Z0-9_]*$/;
+// An ISO-8601 timestamp (the `recorded` column) is structural, not a secret.
+const GATE_ISO_TS = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+const GATE_AUTH_METHODS = new Set([
+  "password", "iam", "oauth", "oauth2", "service-account", "ssh-key",
+  "api-key", "none", "scram-sha-256", "md5", "trust", "token", "key",
+  "cert", "mtls", "kerberos", "ldap",
+]);
+const GATE_VAULTS = new Set([
+  "local", "local (.env)", ".env", "env",
+  "vercel", "neon", "gcp-secret-manager", "google secret manager",
+  "aws-secrets-manager", "aws secrets manager", "doppler", "1password",
+  "hashicorp-vault", "vault", "azure-key-vault", "infisical",
+]);
+const GATE_GOTCHA_ENUM = new Set(["vpn", "ip-allowlist", "ssh-tunnel", "bastion", "none"]);
+const GATE_CLI_WORDS = new Set([
+  "psql", "mysql", "mysqldump", "mongo", "mongosh", "redis-cli", "sqlite3",
+  "pg_dump", "pg_restore", "pg_dumpall", "cqlsh", "clickhouse-client",
+  "neonctl", "vercel", "gcloud", "aws", "az", "doppler", "supabase",
+  "flyctl", "fly", "heroku", "railway", "wrangler", "turso", "op", "infisical",
+  "kubectl", "helm", "terraform", "vault",
+  "ssh", "scp", "sftp", "curl", "wget", "ldapsearch", "nc", "openssl", "rsync",
+  "env", "pull", "push", "list", "get", "set", "secrets", "versions",
+  "access", "version", "exec", "run", "connect", "login", "logout",
+  "connection-string", "db-url", "database-url", "redis-url",
+  "admin", "default", "latest", "read", "write", "describe", "show",
+  "from", "cat", "source", "printenv", "dotenv",
+]);
+const GATE_DOTFILE_TOKEN = /^\.[a-z][a-z0-9]*(?:\.[a-z][a-z0-9-]*)*$/;
+
+function gateIsDbNameShape(s) {
+  if (typeof s !== "string" || s.length === 0 || s.length > 16) return false;
+  if (!/^[a-z][a-z0-9_]*$/.test(s)) return false;
+  if (/[0-9][a-z]/.test(s)) return false;
+  return true;
+}
+function gateIsHostShape(s) {
+  if (s === "localhost") return true;
+  if (GATE_IPV4.test(s)) return true;
+  if (GATE_DOTTED_HOSTNAME.test(s)) return true;
+  if (GATE_BARE_HOST_LABEL.test(s)) return true;
+  return false;
+}
+function gateIsVarRef(tok) {
+  const bare = tok.replace(/^["']/, "").replace(/["']$/, "");
+  return GATE_VAR_REF.test(tok) || /^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/.test(bare);
+}
+function gateIsBareVarRef(value) {
+  return GATE_VAR_REF.test(value) || /^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/.test(value);
+}
+
+// ─── CONVERGED command grammar — SAFE-LABEL ALLOWLIST (mirror of the writer) ──
+//
+// Independently re-declared here (a writer bug must not disable the gate). The
+// primitive: a bare identifier value is safe ONLY right after an allowlisted
+// value-flag (--user/--dbname/--host/--port/--secret). After ANY other flag —
+// and for any standalone bare arg — the value must be a $VAR or a provably-safe
+// shape (dotted host / IPv4 / localhost / .env dotfile / curated CLI word). This
+// closes the whole `--password swordfish` / `-pS3cret` / `--pw=x` leak family:
+// those flags are NOT on the safe list, so their value must be a $VAR.
+
+// Each value-flag maps to a TYPED shape (mirror of the writer). A bare value is
+// allowed ONLY if it matches that flag's tight shape — NOT a wide identifier
+// (cycle-7 leak). A strong/random credential fails and must be a $VAR.
+const GATE_VALUE_FLAG_SHAPE = {
+  u: "dbname", user: "dbname", username: "dbname",
+  d: "dbname", dbname: "dbname", db: "dbname", database: "dbname",
+  h: "host", host: "host", hostname: "host",
+  port: "port",
+  secret: "dbname",
+};
+function gateFlagBareName(tok) {
+  return tok.replace(/^--?/, "").toLowerCase();
+}
+function gateFlagValueMatchesTypedShape(name, bareVal) {
+  const shape = GATE_VALUE_FLAG_SHAPE[name];
+  if (shape === "port") return /^\d+$/.test(bareVal);
+  if (shape === "host") {
+    return bareVal === "localhost" || GATE_IPV4.test(bareVal) ||
+      GATE_STRICT_CMD_HOSTNAME.test(bareVal) || GATE_BARE_HOST_LABEL.test(bareVal);
+  }
+  if (shape === "dbname") return gateIsDbNameShape(bareVal);
+  return false;
+}
+// A bare flag NAME with no attached value: --long, or a single-letter -X. A
+// multi-char single-dash token (`-pMyPass`) is a GLUED flag+value, NOT a bare
+// flag — it must be classified as flag+value, never as a value-less flag name.
+function gateIsBareFlag(bare) {
+  if (/^--[A-Za-z][A-Za-z0-9-]*$/.test(bare)) return true;
+  if (/^-[A-Za-z]$/.test(bare)) return true;
+  return false;
+}
+// SAFE non-$VAR shapes ANY token may take: dotted-DNS / IPv4 / localhost / .env
+// dotfile / curated CLI word. NO bare host-label, NO db-name-shape.
+const GATE_SAFE_URL =
+  /^[a-z][a-z0-9+.\-]*:\/\/(?:localhost|\d{1,3}(?:\.\d{1,3}){3}|(?:[a-z0-9](?:[a-z0-9-]{0,22}[a-z0-9])?\.)+[a-z]{2,})(?::\d+)?(?:[/?#]\S*)?$/;
+function gateIsSafeNonSecretToken(bare) {
+  if (bare === "localhost") return true;
+  if (GATE_IPV4.test(bare)) return true;
+  if (GATE_STRICT_CMD_HOSTNAME.test(bare)) return true; // strict, not loose
+  if (GATE_SAFE_URL.test(bare)) return true;
+  if (GATE_DOTFILE_TOKEN.test(bare)) return true;
+  if (GATE_CLI_WORDS.has(bare.toLowerCase())) return true;
+  return false;
+}
+// A flag's VALUE (attached, glued, or next-token). An allowlisted value-flag may
+// carry a bare identifier; every other flag's value must be $VAR or a safe shape.
+function gateFlagValueOk(name, value) {
+  const bareVal = value.replace(/^["']/, "").replace(/["']$/, "");
+  if (gateIsBareVarRef(value)) return true;
+  if (gateIsSafeNonSecretToken(bareVal)) return true;
+  if (Object.prototype.hasOwnProperty.call(GATE_VALUE_FLAG_SHAPE, name) &&
+      gateFlagValueMatchesTypedShape(name, bareVal)) return true;
+  return false;
+}
+// A single command token WITHOUT adjacency (attached flag values + standalone).
+function gateCommandTokenOk(tok) {
+  const bare = tok.replace(/^["']/, "").replace(/["']$/, "");
+  if (bare === "") return true;
+  if (gateIsVarRef(tok)) return true;
+  // --flag=value
+  const eqMatch = bare.match(/^(--?[A-Za-z][A-Za-z0-9-]*)=(.*)$/);
+  if (eqMatch) {
+    const name = gateFlagBareName(eqMatch[1]);
+    const value = eqMatch[2];
+    if (value === "") return true;
+    return gateFlagValueOk(name, value);
+  }
+  // glued short flag -pVALUE
+  const gluedMatch = bare.match(/^(-[A-Za-z])(.+)$/);
+  if (gluedMatch) {
+    return gateFlagValueOk(gateFlagBareName(gluedMatch[1]), gluedMatch[2]);
+  }
+  if (gateIsBareFlag(bare)) return true;
+  if (gateIsSafeNonSecretToken(bare)) return true;
+  return false;
+}
+function gateTokenizeCommand(s) {
+  const tokens = [];
+  const re = /"[^"]*"|'[^']*'|\S+/g;
+  let m;
+  while ((m = re.exec(s)) !== null) tokens.push(m[0]);
+  return tokens;
+}
+// Adjacency-aware: a bare flag NAME followed by a non-flag value forces that
+// value through gateFlagValueOk with the flag's name (so `-U binvoice` passes,
+// `--password swordfish` fails).
+function gateCommandOk(cell) {
+  const tokens = gateTokenizeCommand(cell);
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    const bare = tok.replace(/^["']/, "").replace(/["']$/, "");
+    if (gateIsBareFlag(bare) && !gateIsVarRef(tok)) {
+      const next = tokens[i + 1];
+      if (next !== undefined) {
+        const nextBare = next.replace(/^["']/, "").replace(/["']$/, "");
+        if (!/^-/.test(nextBare)) {
+          if (!gateFlagValueOk(gateFlagBareName(bare), next)) return false;
+          i++;
+          continue;
+        }
+      }
+      continue;
+    }
+    if (!gateCommandTokenOk(tok)) return false;
+  }
+  return true;
+}
+function gateGotchasOk(cell) {
+  const tokens = cell.split(/[,\s]+/).filter(Boolean);
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i].toLowerCase();
+    if (GATE_GOTCHA_ENUM.has(t)) continue;
+    if (t === "via") {
+      const next = tokens[i + 1];
+      if (!next || !gateIsHostShape(next)) return false;
+      i++;
+      continue;
+    }
+    if (gateIsHostShape(tokens[i])) continue;
+    return false;
+  }
+  return true;
+}
+
+// The BACKSTOP leak test — the known-prefix/JWT/base64/hex detector + the
+// embedded-cred regex. Applied to EVERY cell as an extra layer.
+function cellHitsBackstop(cell) {
+  if (typeof cell !== "string" || !cell) return false;
+  if (looksLikeSecretValue(cell)) return true;
+  if (GATE_EMBEDDED_CRED.test(cell)) return true;
+  return false;
+}
+
+// PRIMARY GUARD: is this cell the POSITIVE shape its column is supposed to hold?
+// Returns true if the cell is VALID for its column. An empty cell / placeholder
+// (`—`) is always valid. `col` is the column NAME.
+function cellMatchesColumnShape(col, cell) {
+  if (typeof cell !== "string") return true;
+  const s = cell.trim();
+  if (s === "" || s === "—") return true;
+  switch (col) {
+    case "id":
+      // <scope>-<kind> — lowercase identifier with a hyphen.
+      return /^[a-z0-9][a-z0-9-]*$/.test(s);
+    case "scope":
+      return s === "local" || s === "staging" || s === "prod";
+    case "kind":
+      return /^[a-z0-9][a-z0-9-]*$/.test(s);
+    case "host":
+      return gateIsHostShape(s.replace(/:\d+$/, ""));
+    case "port":
+      return /^\d+$/.test(s);
+    case "db/name":
+      return gateIsDbNameShape(s);
+    case "auth method":
+      return GATE_AUTH_METHODS.has(s.toLowerCase());
+    case "secret vault":
+      return GATE_VAULTS.has(s.toLowerCase());
+    case "secret env-var NAME":
+      return GATE_UPPER_SNAKE.test(s);
+    case "fetch command":
+    case "connect command":
+      return gateCommandOk(s);
+    case "access gotchas":
+      return gateGotchasOk(s);
+    case "read-only default":
+      return s === "YES" || s === "NO";
+    case "recorded":
+      return GATE_ISO_TS.test(s);
+    default:
+      // Unknown column — fall back to refusing anything the backstop flags.
+      return !cellHitsBackstop(s);
+  }
+}
+
+// The gate's leak test for a cell in a KNOWN column: FAIL if it is NOT the
+// column's positive shape OR (backstop) it hits the known-prefix/embedded-cred
+// detector. The positive shape is the PRIMARY guard.
+function cellLeaks(col, cell) {
+  if (typeof cell !== "string" || !cell) return false;
+  if (!cellMatchesColumnShape(col, cell)) return true; // primary: wrong shape
+  if (cellHitsBackstop(cell)) return true; // backstop: extra layer
+  return false;
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch (_) {
+    return null;
+  }
+}
+
+function splitRow(line) {
+  const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  const cells = [];
+  let cur = "";
+  for (let i = 0; i < trimmed.length; i++) {
+    const ch = trimmed[i];
+    if (ch === "\\" && trimmed[i + 1] === "|") {
+      cur += "|";
+      i++;
+    } else if (ch === "|") {
+      cells.push(cur.trim());
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  cells.push(cur.trim());
+  return cells;
+}
+
+// Per-project local-literal switch (mirror of the writer). When a project opts
+// in, a `scope=local` row is EXEMPT from the secret-leak check (the user's
+// testing convenience). staging/prod are ALWAYS checked. The OVERFLOW-column
+// (corrupt-schema) check is NEVER exempted — a malformed table fails regardless.
+function readAllowLocalLiteral(projectDir) {
+  const p = path.join(projectDir, ".gsd-t", "env-registry-config.json");
+  try {
+    const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+    return !!(cfg && cfg.allowLocalLiteral === true);
+  } catch (_) {
+    return false; // absent / invalid → strict (no silent relax)
+  }
+}
+
+function check(projectDir) {
+  const infraPath = path.join(projectDir, "docs", "infrastructure.md");
+  const claudePath = path.join(projectDir, "CLAUDE.md");
+
+  const infra = readSafe(infraPath) || "";
+  const claude = readSafe(claudePath) || "";
+  const allowLocalLiteral = readAllowLocalLiteral(projectDir);
+
+  const hasMarkers = infra.includes(ENV_MARKER_START) && infra.includes(ENV_MARKER_END);
+  // The env-access rule is identified by its stable marker phrase.
+  const hasRule = /Environment Access — read-first, HALT-and-document/.test(claude);
+
+  const failures = [];
+
+  // (b) rule present but table markers absent.
+  if (hasRule && !hasMarkers) {
+    failures.push(
+      "env-access rule is present in CLAUDE.md but the `## Environments` table markers are absent from docs/infrastructure.md"
+    );
+  }
+
+  // (a) secret-shaped value in any row cell.
+  if (hasMarkers) {
+    const start = infra.indexOf(ENV_MARKER_START);
+    const end = infra.indexOf(ENV_MARKER_END);
+    const block = infra.slice(start, end);
+    const lines = block.split("\n");
+    for (const line of lines) {
+      if (!line.trim().startsWith("|")) continue;
+      const cells = splitRow(line);
+      if (cells[0] === "id") continue; // header
+      if (cells.every((c) => /^-{1,}$/.test(c) || c === "")) continue; // separator
+      // Local-literal exemption: a scope=local row (cells[1]) in an opted-in
+      // project skips the SECRET-leak check (but NOT the overflow/corruption
+      // check below — a malformed schema always fails).
+      const rowScope = (cells[1] || "").trim();
+      const exemptSecrets = allowLocalLiteral && rowScope === "local";
+      // An OVERFLOW cell (index ≥ the fixed 14-column schema) is itself a
+      // corruption signal — a hand-edit/merge/tool that appended a 15th column
+      // could hide a plaintext secret in a column the shape-map doesn't cover.
+      // The old `col${i}` default branch fell back to the WEAK backstop only
+      // (leak #3). A cell beyond the schema is now a HARD FAIL, no exceptions.
+      for (let i = 0; i < cells.length; i++) {
+        if (i >= ENV_COLUMNS.length) {
+          if (cells[i] !== "" && cells[i] !== "—") {
+            failures.push(
+              `Environments row has an extra cell beyond the fixed ${ENV_COLUMNS.length}-column schema ` +
+                `(index ${i}): "${cells[i]}" — the table shape is corrupt; a secret could hide in an ` +
+                `unmapped column. Restore the exact ${ENV_COLUMNS.length}-column schema.`
+            );
+          }
+          continue;
+        }
+        if (exemptSecrets) continue; // opted-in local row — skip secret-leak check
+        const col = ENV_COLUMNS[i];
+        if (cellLeaks(col, cells[i])) {
+          failures.push(
+            `Environments row cell (${col}) contains a secret-shaped literal value: "${cells[i]}" — record the env-var NAME and a $VAR reference, never a literal secret`
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    check: "env-registry",
+    hasMarkers,
+    hasRule,
+    failures,
+    note:
+      !hasMarkers && !hasRule
+        ? "no-op PASS: project has not adopted the M102 Environments registry (no table, no rule)"
+        : undefined,
+  };
+}
+
+function parseArgs(argv) {
+  const out = { projectDir: "." };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--project") out.projectDir = argv[++i] || ".";
+  }
+  return out;
+}
+
+module.exports = { check };
+
+if (require.main === module) {
+  const { projectDir } = parseArgs(process.argv.slice(2));
+  const result = check(projectDir);
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exit(result.ok ? 0 : 1);
+}