@tekyzinc/gsd-t 5.5.10 → 5.6.10

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.6.10] - 2026-08-02
+
+### Changed — the Environment Registry now fires (M103)
+
+The registry shipped in M102 was never filled in — empty in 31 of 33 projects — so every session re-asked the human how to reach production. Four independent breaks, each verified:
+
+1. **Record-at-create was prose, not code.** `recordEnvironment` had zero production callers; the instruction to record a row lived only in a markdown command file. Provisioning also often has no discrete moment to fire on — one project's production database came up via a hosting-platform integration during a deploy.
+2. **Nothing backfilled** projects that predate M102.
+3. **The empty state was certified as fine.** The gate looked for the env-access rule in the *project's* `CLAUDE.md`, but that rule ships in the *global* one — so every project took the "has not adopted the registry" no-op PASS branch.
+4. **The nine-cycle secret grammar rejected TRUE values** (`n/a`, `cli-session`, lowercase `yes`, plain-English notes). The observed consequence was writing something *false* to get past it — a staging row recorded as production.
+
+Changes:
+
+- `bin/gsd-t-env-registry-check.cjs`: accept true values in columns that structurally cannot carry a secret (`n/a` in port / db-name / env-var-NAME; unenumerated sign-in methods in label shape; `yes`/`no` in any capitalisation; word-by-word prose in `access gotchas`). Password-carrying columns — host, db name, both commands — are untouched. A project with a remote environment and no prod/staging row now FAILS; a local-only project PASSES and is named `localOnly:true`. The M102 rule-vs-table condition is removed: once the rule is read from the global file it fired in every project (21 of 28, all correct local-only states) and added no signal the remote-environment check does not already carry.
+- `bin/gsd-t-env-registry.cjs`: new `source` column. A vendor resource id is shape-identical to a token, so the row names where the value came from (`neonctl projects list`, `.vercel/project.json`) and the source vouches for it. Its presence is the flag — there is no per-vendor "source required" list to maintain, and therefore none to forget. A source never vouches past the backstop.
+- `templates/infrastructure.md`, `templates/CLAUDE-global.md`: the 15-column schema, the relaxed column rules, and a write-the-row-before-you-use-the-answer rule.
+- `.gsd-t/contracts/env-registry-contract.md`: v1.1.0 DRAFT → **v1.2.0 STABLE**, plus four `[RULE]`s — truth-accepted, source-vouches, empty-is-not-pass, local-only-named.
+- `test/m102-env-registry.test.js`: 274 → 305 tests. Includes the leak found *during* this work — once `source` took the 15th slot the overflow-corruption guard no longer covered it, and a bare word passed an early "looks like a path" rule.
+
+Two things were built and then reverted, both killed by evidence: a "recorded command must run as written" gate check (not a secret question, it failed provably-safe rows, and its rule only holds for a multi-project account — three existing tests caught it), and a rule that guessed resource ids by their spelling (replaced by the source column).
+
+Measured across the project registry: **22 PASS / 6 FAIL, all six true findings** — five genuinely unmapped remote projects and one malformed row.
+
+Suite 3083/0/13-skip.
+
+## [5.5.11] - 2026-07-29
+
+### Fixed — the new style gate would have failed 27 untouched documents in three projects
+
+Caught by running the gate live in a downstream project immediately after propagation rather than trusting the "copied 1 bin tool(s)" report. v5.5.10 shipped the gate to all 33 registered projects, but the grandfather list that exempts pre-v1.2.0 documents existed only in the GSD-T repo. binvoice (19 documents), NiceNote (6) and IssueRecorder (2) had none — so the next `gsd-t-verify` run in those projects would have failed on documents nobody touched, written to a then-valid standard.
+
+The gate now establishes its own starting line: on the `--dir` path, when the list file is absent and the directory already holds documents, it writes the list once from the existing set and reports `seeded: { reason: "seeded-pre-existing", count, docs }`.
+
+This is **not a fallback** — it masks no failure and continues past none; it defines where the gate begins. Three properties keep it honest: written **once** (a self-re-seeding list would silently absolve every newly-drifted document, which is the banned behavior), keyed on the file being absent, and always surfaced naming every document covered. A document created after the seed is gated normally; a single `--doc` call never seeds; an un-writable directory returns exit 64 with the reason rather than a silent mass-pass or mass-fail.
+
+- `bin/gsd-t-pseudocode-style.cjs`: `seedGrandfatherList()` + envelope `seeded` field.
+- `test/pseudocode-style-gate.test.js`: 4 new tests (15 → 19) — seed happens, seed never re-runs, `--doc` never seeds, un-writable directory exits 64.
+- `.gsd-t/contracts/pseudocode-source-of-truth-contract.md`: §1.1.5 documents the seed and why it is not a fallback.
+
+Verified live: binvoice's 19 documents now report `exitCode 0`, 19 seeded, 0 violations. Suite 3052/0/13-skip.
+
 ## [5.5.10] - 2026-07-29
 
 ### Added — PseudoCode style is governed: the flow IS the document

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.5.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.6.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-env-registry-check.cjs

@@ -36,6 +36,7 @@
 // by construction) would still trip these.
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 
 const {
@@ -81,6 +82,22 @@ const GATE_VAULTS = new Set([
   "hashicorp-vault", "vault", "azure-key-vault", "infisical",
 ]);
 const GATE_GOTCHA_ENUM = new Set(["vpn", "ip-allowlist", "ssh-tunnel", "bastion", "none"]);
+// M103 — "this column does not apply to this kind of environment" is a TRUE
+// answer, not a hidden value. Accepted ONLY in columns that cannot carry a
+// secret anyway (port, secret env-var NAME).
+const GATE_NOT_APPLICABLE = new Set(["n/a", "na", "none", "—", "-"]);
+// M103 — an auth METHOD the enum has not heard of (`cli-session`,
+// `device-code`, `browser-session`). Accepted only in LABEL shape: 1-3 short
+// lowercase alphabetic words joined by hyphens, ≤24 chars, NO digits. A
+// credential fails this: tokens/keys/passwords carry digits, mixed case, or
+// punctuation, and random lowercase-only strings exceed the per-word length.
+const GATE_AUTH_LABEL = /^[a-z]{2,12}(?:-[a-z]{2,12}){0,2}$/;
+function gateIsAuthLabelShape(s) {
+  if (typeof s !== "string") return false;
+  const v = s.trim();
+  if (v.length > 24) return false;
+  return GATE_AUTH_LABEL.test(v);
+}
 const GATE_CLI_WORDS = new Set([
   "psql", "mysql", "mysqldump", "mongo", "mongosh", "redis-cli", "sqlite3",
   "pg_dump", "pg_restore", "pg_dumpall", "cqlsh", "clickhouse-client",
@@ -91,6 +108,10 @@ const GATE_CLI_WORDS = new Set([
   "env", "pull", "push", "list", "get", "set", "secrets", "versions",
   "access", "version", "exec", "run", "connect", "login", "logout",
   "connection-string", "db-url", "database-url", "redis-url",
+  // M103 — resource-listing subcommands, the shape of a `source` value
+  // ("neonctl projects list"). Ordinary CLI nouns, same class as list/get/show.
+  "projects", "project", "branches", "branch", "orgs", "org", "databases",
+  "roles", "endpoints", "instances", "buckets", "services", "apps",
   "admin", "default", "latest", "read", "write", "describe", "show",
   "from", "cat", "source", "printenv", "dotenv",
 ]);
@@ -234,6 +255,46 @@ function gateCommandOk(cell) {
   }
   return true;
 }
+// M103 — the access-gotchas column is the ONE cell that must carry human
+// judgment in plain English ("live seller data — never mutate without an OK").
+// That warning is the most valuable thing in the row: it is what stops a
+// destructive mistake, and no vendor CLI can ever return it. The M102 enum
+// rejected all prose, so the column was written as `none` and the judgment was
+// lost.
+//
+// Prose is allowed here, but NOT as a hole in the guard. A word is accepted
+// only if it is PROSE-SHAPED — and a secret is not prose-shaped. The test is
+// per-WORD and structural (never a denylist of secret values, which the M102
+// cycles proved unwinnable): a word must be ordinary letters, or ordinary
+// punctuation, or one of the shapes already proven safe elsewhere in the row.
+//
+// What a prose word may be:
+//   - a letters-only word, with optional internal apostrophe/hyphen, ≤24 chars
+//     (`Marla's`, `never`, `read-only`, `VPN`) — no digits, so a random
+//     credential cannot pass as a word
+//   - a pure number / ordinary punctuation (`6h`, `17`, `—`, `.`, `(main)`)
+//   - a shape already whitelisted for other columns (host, $VAR, .env dotfile,
+//     curated CLI word, the gotcha enum)
+// Everything else — any mixed letters+digits token that is not a plain unit
+// like `6h`, anything with credential punctuation — FAILS. That is the shape
+// a real secret has, and it still fails here exactly as before.
+const GATE_PROSE_WORD = /^[A-Za-z]+(?:['’-][A-Za-z]+)*$/;
+// A plain magnitude: 17, 6h, 30d, 5432. Digits with an optional short unit.
+const GATE_PROSE_NUMBER = /^\d+[a-z]{0,2}$/i;
+// Ordinary sentence punctuation carrying no value.
+const GATE_PROSE_PUNCT = /^[.,;:!?()[\]{}"'’“”—–\-/&+%]+$/;
+
+function gateIsProseWord(raw) {
+  // Strip surrounding punctuation so `(main),` tests as `main`.
+  const w = raw.replace(/^[.,;:!?()[\]{}"'’“”—–]+/, "").replace(/[.,;:!?()[\]{}"'’“”—–]+$/, "");
+  if (w === "") return true;
+  if (w.length > 24) return false;
+  if (GATE_PROSE_WORD.test(w)) return true;
+  if (GATE_PROSE_NUMBER.test(w)) return true;
+  if (GATE_PROSE_PUNCT.test(w)) return true;
+  return false;
+}
+
 function gateGotchasOk(cell) {
   const tokens = cell.split(/[,\s]+/).filter(Boolean);
   for (let i = 0; i < tokens.length; i++) {
@@ -246,11 +307,77 @@ function gateGotchasOk(cell) {
       continue;
     }
     if (gateIsHostShape(tokens[i])) continue;
+    // M103 — plain-English judgment is allowed, word by word.
+    if (gateIsSafeNonSecretToken(tokens[i].replace(/^["']/, "").replace(/["']$/, ""))) continue;
+    if (gateIsProseWord(tokens[i])) continue;
     return false;
   }
   return true;
 }
 
+// ─── M103 — the `source` column: where an unprovable value came from ─────────
+//
+// A vendor's resource id (`winter-frog-54927244`, `prj_3OQ3gUB1zkm5uraf…`) is
+// indistinguishable from a token BY SHAPE — that is a fact about the values,
+// not a gap in the grammar, so no amount of pattern-tightening resolves it.
+// The M102 answer was to reject them, which forced a worse outcome: rows were
+// written with FALSE values to get past the checker (a `staging` environment
+// recorded as `prod`, a real command replaced by an unrelated one that
+// happened to pass). A checker that makes the truth unwritable buys nothing.
+//
+// So a value the shape-grammar cannot vouch for is accepted when the row NAMES
+// WHERE IT CAME FROM. The source's PRESENCE is the flag — there is no
+// per-vendor "source required" list to add to, and therefore none to forget.
+//
+// What this does and does not defend against: it stops an ACCIDENT (a secret
+// pasted into the wrong cell, a connection string carrying its password) —
+// which is the whole M102 threat model. It does not stop someone deliberately
+// writing a secret and inventing a source for it; nothing mechanical does, and
+// that was never in scope.
+//
+// The source must itself be checkable — a command from the curated CLI words
+// or a path to a file in the project. Free prose here would re-open the hole.
+// A project-relative file path. It must LOOK like a path — carry a separator or
+// a file extension. A bare word (`hunter2`) is NOT a path: allowing one would
+// turn this column into the free-text cell the 15-column schema used to catch
+// as overflow corruption (a real leak, found by the CYCLE5 overflow tests when
+// the `source` column took over the 15th slot).
+const GATE_SOURCE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+const GATE_SOURCE_PATH_EVIDENCE = /[/]|^\.[A-Za-z]|\.[A-Za-z0-9]{1,8}$/;
+
+function gateIsSourceShape(s) {
+  if (typeof s !== "string") return false;
+  const v = s.trim();
+  if (v === "" || v === "—") return true;
+  if (v.length > 120) return false;
+  // A command: every token must clear the same grammar the command columns use.
+  if (gateCommandOk(v)) return true;
+  // A file path in the project (.vercel/project.json, fly.toml, .env.example).
+  // Rejected if absolute, if it climbs out of the project, or if it is a bare
+  // word carrying no evidence of being a path at all.
+  if (
+    GATE_SOURCE_PATH.test(v) &&
+    !v.startsWith("/") &&
+    !v.includes("..") &&
+    GATE_SOURCE_PATH_EVIDENCE.test(v)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+// Does this row name a source? If so, cells the shape-grammar cannot prove are
+// accepted — EXCEPT cells that hit the backstop, which stays absolute (see
+// cellLeaks). A source vouches for an unrecognised value; it never vouches for
+// something that positively looks like a credential.
+function rowNamesASource(cells) {
+  const idx = ENV_COLUMNS.indexOf("source");
+  if (idx === -1) return false;
+  const v = (cells[idx] || "").trim();
+  if (v === "" || v === "—") return false;
+  return gateIsSourceShape(v);
+}
+
 // 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) {
@@ -278,24 +405,42 @@ function cellMatchesColumnShape(col, cell) {
     case "host":
       return gateIsHostShape(s.replace(/:\d+$/, ""));
     case "port":
-      return /^\d+$/.test(s);
+      // M103: "not applicable" is a TRUE answer for a kind with no port (a
+      // web-console / CLI-session environment). Digits or n/a — nothing else.
+      return /^\d+$/.test(s) || GATE_NOT_APPLICABLE.has(s.toLowerCase());
     case "db/name":
-      return gateIsDbNameShape(s);
+      // M103: an environment that is not a database (a hosting account, a web
+      // console) has no db name. `n/a` is true, not hidden.
+      return gateIsDbNameShape(s) || GATE_NOT_APPLICABLE.has(s.toLowerCase());
     case "auth method":
-      return GATE_AUTH_METHODS.has(s.toLowerCase());
+      // M103: the enum can never be complete (every vendor names sign-in its
+      // own way — `cli-session`, `device-code`). An unenumerated method is
+      // accepted ONLY in LABEL shape: short lowercase hyphenated words. A
+      // credential is not that shape (see gateIsAuthLabelShape).
+      return GATE_AUTH_METHODS.has(s.toLowerCase()) || gateIsAuthLabelShape(s);
     case "secret vault":
       return GATE_VAULTS.has(s.toLowerCase());
     case "secret env-var NAME":
-      return GATE_UPPER_SNAKE.test(s);
+      // M103: an environment reached by an interactive CLI session carries no
+      // env var. `n/a` is the true answer; it is not a secret in any shape.
+      return GATE_UPPER_SNAKE.test(s) || GATE_NOT_APPLICABLE.has(s.toLowerCase());
     case "fetch command":
     case "connect command":
       return gateCommandOk(s);
     case "access gotchas":
       return gateGotchasOk(s);
     case "read-only default":
-      return s === "YES" || s === "NO";
+      // M103: a boolean is a boolean whatever its capitalisation. Rejecting
+      // `yes` taught humans to retype until the checker relented.
+      return /^(yes|no)$/i.test(s);
     case "recorded":
       return GATE_ISO_TS.test(s);
+    case "source":
+      // M103 — where an otherwise-unprovable value came from. It must itself be
+      // checkable: a command built from the curated CLI words, or a path to a
+      // file in the project. Free prose here would re-open the hole the column
+      // exists to close.
+      return gateIsSourceShape(s);
     default:
       // Unknown column — fall back to refusing anything the backstop flags.
       return !cellHitsBackstop(s);
@@ -305,10 +450,20 @@ function cellMatchesColumnShape(col, cell) {
 // 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) {
+function cellLeaks(col, cell, hasSource) {
   if (typeof cell !== "string" || !cell) return false;
-  if (!cellMatchesColumnShape(col, cell)) return true; // primary: wrong shape
-  if (cellHitsBackstop(cell)) return true; // backstop: extra layer
+  // BACKSTOP FIRST, and it is absolute: a value that positively looks like a
+  // credential (known prefix / JWT / base64 / hex / embedded cred) fails no
+  // matter what the row claims about where it came from. A source vouches for
+  // the UNRECOGNISED, never for the recognisably-secret.
+  if (cellHitsBackstop(cell)) return true;
+  if (!cellMatchesColumnShape(col, cell)) {
+    // M103 — the shape grammar cannot recognise this value. If the row names
+    // where it came from, that is the vouching the shape cannot provide.
+    // The `source` column itself is never vouched for by its own presence.
+    if (hasSource && col !== "source") return false;
+    return true;
+  }
   return false;
 }
 
@@ -354,6 +509,98 @@ function readAllowLocalLiteral(projectDir) {
   }
 }
 
+// ─── M103 — does this project reach anything that is NOT on this machine? ────
+//
+// The M102 gate treated "no table and no rule" as "hasn't adopted the registry
+// yet" and PASSED. That certified the exact emptiness the registry exists to
+// prevent: 31 of 33 projects sat in that state, so every session re-asked the
+// human for connection details.
+//
+// A project only NEEDS a map if it reaches a remote environment. So the gate
+// now looks for evidence of one. The signals are re-derived HERE rather than
+// imported from the writer's detectEnvConfig — the gate must stay independently
+// implemented (a writer bug must never disable it), same invariant M102 set for
+// the shape grammar.
+//
+// This is a HALT, not a fallback: a project with a remote environment and no
+// map FAILS and says which marker it found. A genuinely local-only project
+// PASSES and is NAMED as local-only, so "passed" never silently means
+// "unchecked" (no-silent-degradation).
+const REMOTE_MARKER_FILES = [
+  ["vercel.json", "Vercel"],
+  [".vercel", "Vercel"],
+  ["cloudbuild.yaml", "Google Cloud"],
+  ["cloudbuild.yml", "Google Cloud"],
+  [".gcloudignore", "Google Cloud"],
+  ["fly.toml", "Fly.io"],
+  ["render.yaml", "Render"],
+  ["railway.json", "Railway"],
+  ["app.yaml", "Google App Engine"],
+  ["netlify.toml", "Netlify"],
+  ["wrangler.toml", "Cloudflare"],
+  ["captain-definition", "CapRover"],
+  [".neon", "Neon"],
+];
+// A dependency whose presence means a hosted service is being talked to.
+const REMOTE_DEP_HINTS = [
+  ["@neondatabase/serverless", "Neon"],
+  ["@vercel/postgres", "Vercel Postgres"],
+  ["@supabase/supabase-js", "Supabase"],
+  ["@planetscale/database", "PlanetScale"],
+  ["@aws-sdk/client-s3", "AWS"],
+  ["@google-cloud/storage", "Google Cloud"],
+  ["mongodb", "MongoDB"],
+];
+
+// M103 — "a recorded command must run as written" was TRIED as a gate check
+// here and REMOVED. Two reasons, both found by the existing tests:
+//   1. It is not a secret question. Bolting a usefulness check onto the leak
+//      gate made it fail rows that are perfectly safe — three pre-existing
+//      tests assert bare `neonctl connection-string` is legitimate, correctly.
+//   2. The rule was not universally true. `neonctl connection-string` resolves
+//      fine in a single-project account; it only opens a picker when the
+//      account holds several (as David's does). Generalising one environment's
+//      behaviour into a universal requirement is the guess this codebase's
+//      No-Fallback/evidence rules exist to stop.
+// The requirement survives as guidance in the CLAUDE.md env-access rule, where
+// the human recording the row can judge their own account shape.
+
+function detectRemoteEnvironment(projectDir) {
+  const found = [];
+  for (const [file, label] of REMOTE_MARKER_FILES) {
+    try {
+      if (fs.existsSync(path.join(projectDir, file))) found.push(`${label} (${file})`);
+    } catch (_) { /* unreadable path is not evidence */ }
+  }
+  try {
+    const pkgRaw = fs.readFileSync(path.join(projectDir, "package.json"), "utf8");
+    const pkg = JSON.parse(pkgRaw);
+    const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+    for (const [dep, label] of REMOTE_DEP_HINTS) {
+      if (Object.prototype.hasOwnProperty.call(deps, dep)) found.push(`${label} (${dep})`);
+    }
+  } catch (_) { /* no/unparseable package.json is not evidence */ }
+  return found;
+}
+
+// Does the table hold at least one row describing a NON-local environment?
+// A map listing only `scope=local` rows does not answer "how do I reach prod".
+function hasNonLocalRow(infra) {
+  const start = infra.indexOf(ENV_MARKER_START);
+  const end = infra.indexOf(ENV_MARKER_END);
+  if (start === -1 || end === -1) return false;
+  const lines = infra.slice(start, end).split("\n");
+  for (const line of lines) {
+    if (!line.trim().startsWith("|")) continue;
+    const cells = splitRow(line);
+    if (cells[0] === "id") continue;
+    if (cells.every((c) => /^-{1,}$/.test(c) || c === "")) continue;
+    const scope = (cells[1] || "").trim().toLowerCase();
+    if (scope === "prod" || scope === "staging") return true;
+  }
+  return false;
+}
+
 function check(projectDir) {
   const infraPath = path.join(projectDir, "docs", "infrastructure.md");
   const claudePath = path.join(projectDir, "CLAUDE.md");
@@ -364,14 +611,42 @@ function check(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);
+  //
+  // M103 — the rule ships in the GLOBAL ~/.claude/CLAUDE.md (via
+  // templates/CLAUDE-global.md), NOT in a project CLAUDE.md. M102 looked only
+  // at the project file, so hasRule was false in EVERY project, which sent
+  // every project down the "hasn't adopted it" no-op-PASS branch. Check both:
+  // the project file first (a project may restate it), then the global.
+  const RULE_PHRASE = /Environment Access — read-first, HALT-and-document/;
+  const globalClaude = readSafe(path.join(os.homedir(), ".claude", "CLAUDE.md")) || "";
+  const hasRule = RULE_PHRASE.test(claude) || RULE_PHRASE.test(globalClaude);
 
   const failures = [];
 
-  // (b) rule present but table markers absent.
-  if (hasRule && !hasMarkers) {
+  // (b) M102 asked "the rule promises a map — is there a table?". That made
+  // sense while the rule was believed to be per-project. It is not: the rule
+  // ships in the GLOBAL CLAUDE.md, so once M103 reads the global file the
+  // condition is true in EVERY project and fires on local-only projects that
+  // have nothing remote to map (measured: 21 of 28 projects failed on this
+  // alone). A gate that fails a project for a correct state gets switched off.
+  //
+  // Condition (c) below asks the question (b) was reaching for, and asks it
+  // against evidence from the project itself rather than a globally-true
+  // premise: does this project REACH something remote, and is it mapped?
+  // (b) is therefore removed, not merely relaxed — it added no signal (c)
+  // does not already carry.
+
+  // (c) M103 — a project that reaches a REMOTE environment must map it. An
+  // empty (or local-only) map in a project with a deploy marker is the state
+  // that made every session re-ask the human for connection details.
+  const remoteMarkers = detectRemoteEnvironment(projectDir);
+  const mapsARemoteEnv = hasMarkers && hasNonLocalRow(infra);
+  const isLocalOnly = remoteMarkers.length === 0;
+  if (!isLocalOnly && !mapsARemoteEnv) {
     failures.push(
-      "env-access rule is present in CLAUDE.md but the `## Environments` table markers are absent from docs/infrastructure.md"
+      `project reaches a remote environment (${remoteMarkers.join(", ")}) but the ` +
+        "`## Environments` table has no prod/staging row — record it with " +
+        "`gsd-t env-registry record`, so the connection is not rediscovered every session"
     );
   }
 
@@ -391,7 +666,11 @@ function check(projectDir) {
       // 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
+      // M103 — does this row say where its values came from? A named source
+      // vouches for a value the shape-grammar cannot recognise (a vendor
+      // resource id). It never vouches past the backstop.
+      const hasSource = rowNamesASource(cells);
+      // An OVERFLOW cell (index ≥ the fixed 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
@@ -409,9 +688,11 @@ function check(projectDir) {
         }
         if (exemptSecrets) continue; // opted-in local row — skip secret-leak check
         const col = ENV_COLUMNS[i];
-        if (cellLeaks(col, cells[i])) {
+        if (cellLeaks(col, cells[i], hasSource)) {
           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`
+            hasSource
+              ? `Environments row cell (${col}) contains a secret-shaped literal value: "${cells[i]}" — naming a source does not permit a value that looks like a credential; record the env-var NAME and a $VAR reference`
+              : `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, OR name where the value came from in the \`source\` column if it is a vendor resource id`
           );
         }
       }
@@ -423,10 +704,16 @@ function check(projectDir) {
     check: "env-registry",
     hasMarkers,
     hasRule,
+    // M103 — the reason for a PASS is always NAMED. "local-only" is a real
+    // verdict about this project; it never silently means "not checked".
+    localOnly: isLocalOnly,
+    remoteMarkers,
     failures,
+    // Only describe a PASS when it IS one — a note saying "PASS" beside
+    // ok:false is exactly the kind of mixed signal this gate exists to remove.
     note:
-      !hasMarkers && !hasRule
-        ? "no-op PASS: project has not adopted the M102 Environments registry (no table, no rule)"
+      isLocalOnly && failures.length === 0
+        ? "PASS: local-only — no deploy marker or hosted-service dependency found, so there is no remote environment to map"
         : undefined,
   };
 }

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

@@ -50,6 +50,12 @@ const ENV_COLUMNS = [
   "access gotchas",
   "read-only default",
   "recorded",
+  // M103 — WHERE a value came from. Filled ONLY when a cell holds something the
+  // checker cannot prove safe by its shape (a vendor's project id looks exactly
+  // like a token). Naming the source is what makes such a value acceptable; its
+  // PRESENCE is the flag, so there is no per-vendor list to keep up to date.
+  // Empty for rows whose every cell stands on its own — most rows.
+  "source",
 ];
 
 // ─── Secret-value BACKSTOP detector (known-prefix / JWT / embedded-cred) ─────

package/bin/gsd-t-pseudocode-style.cjs

@@ -252,10 +252,56 @@ function loadGrandfathered(dir) {
       const t = l.trim();
       if (t && !t.startsWith("#")) out.add(t);
     }
-  } catch { /* absent list = nothing grandfathered */ }
+  } catch { /* absent list = nothing grandfathered (see seedGrandfatherList) */ }
   return out;
 }
 
+/**
+ * First-run seed for a project that already had PseudoCode docs before this gate
+ * existed.
+ *
+ * WHY THIS IS NOT A FALLBACK (No-Fallback-Ever doctrine):
+ * this does not continue past a failure or mask one. It establishes the gate's
+ * STARTING LINE. The gate governs docs authored under contract §1.1; docs that
+ * predate it were written to a different (then-valid) standard, and retroactively
+ * failing them would make an unrelated verify run fail in a downstream project for
+ * work nobody touched. That is a false failure, not a caught defect.
+ *
+ * The seed is: WRITTEN ONCE (never rewritten — a list that re-seeded itself would
+ * silently absolve every newly-drifted doc, which IS the banned behavior), keyed on
+ * the list file being ABSENT, and always SURFACED with reason "seeded-pre-existing"
+ * naming every doc it covers. A doc created AFTER the seed is gated normally.
+ *
+ * @returns {{ seeded: boolean, names: string[], error?: string }}
+ */
+function seedGrandfatherList(dir, docBasenames) {
+  const listPath = path.join(dir, GRANDFATHER_FILE);
+  if (fs.existsSync(listPath)) return { seeded: false, names: [] };
+  if (docBasenames.length === 0) return { seeded: false, names: [] };
+
+  const body = [
+    "# Docs that predate the §1.1 flow-line style gate (contract v1.2.0).",
+    "# Seeded automatically on this gate's FIRST run in this project, so pre-existing",
+    "# docs are not retroactively failed. Each is reported as a logged skip WITH A",
+    "# REASON — never a silent pass.",
+    "#",
+    "# This file is written ONCE and never re-seeded: a doc created after this point",
+    "# is gated normally. Removing a name here is how a doc opts INTO the gate —",
+    "# convert it to the §1.1 flow style in the same change.",
+    ...docBasenames,
+    "",
+  ].join("\n");
+
+  try {
+    fs.writeFileSync(listPath, body, "utf8");
+  } catch (e) {
+    // Cannot write (read-only checkout, permissions) — surface it, do NOT
+    // silently fail 20 docs and do NOT silently pass them either.
+    return { seeded: false, names: [], error: `cannot seed ${GRANDFATHER_FILE}: ${e && e.message}` };
+  }
+  return { seeded: true, names: docBasenames.slice() };
+}
+
 /**
  * Run the gate over one doc or a whole directory (§7 discovery glob).
  * Never throws.
@@ -283,6 +329,17 @@ function run({ doc, dir }) {
     }
   }
 
+  // First-run seed: a project whose docs predate this gate gets its starting line
+  // established once, surfaced with a reason. Only on the --dir path (the whole-set
+  // view); a single --doc call never seeds.
+  let seedInfo = null;
+  if (dir) {
+    seedInfo = seedGrandfatherList(dir, docs.map((d) => path.basename(d)).sort());
+    if (seedInfo.error) {
+      return { ok: false, exitCode: 64, reason: seedInfo.error, violations: [] };
+    }
+  }
+
   const results = [];
   const violations = [];
   const skips = [];
@@ -295,7 +352,7 @@ function run({ doc, dir }) {
     if (r.exitCode > worstExit) worstExit = r.exitCode;
   }
 
-  return {
+  const envelope = {
     ok: worstExit === 0,
     exitCode: worstExit,
     docsChecked: docs.length,
@@ -303,6 +360,11 @@ function run({ doc, dir }) {
     skips,
     violations,
   };
+  if (seedInfo && seedInfo.seeded) {
+    // Surfaced, never silent: name the migration and every doc it covers.
+    envelope.seeded = { reason: "seeded-pre-existing", count: seedInfo.names.length, docs: seedInfo.names };
+  }
+  return envelope;
 }
 
 function parseArgs(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.5.10",
+  "version": "5.6.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -106,6 +106,8 @@ NEED TO UNDERSTAND SOMETHING?
 
 - **On a HIT** — use the recorded connect command; the secret is pulled from its vault at runtime via the env-var NAME.
 - **On a MISS (no row) — HALT and document. NEVER guess a connection string, NEVER grep transcripts to rediscover it** (No-Fallback-Ever). Then: `detect` the env → ask the human to confirm/fill → `record` the map row → `add-permission` (broad-glob) → proceed. The registry self-heals staleness because a re-provision upserts by `(scope, kind)`.
+- **WRITE THE ROW BEFORE YOU USE THE ANSWER (M103).** The moment the human answers is the ONLY moment both a human and a real answer are in the same place. `record` FIRST, then continue the work that needed it. Using the answer and recording it "after this task" is how the map stayed empty in 31 of 33 projects and why the same question got asked again next session. This is not a fallback: the HALT already fired and was answered — writing it down is what COMPLETES the halt.
+- **A recorded command must RUN AS WRITTEN (M103).** Record the command you actually verified, including every identifier it needs (project id, branch, org). `neonctl connection-string` with no `--project-id` drops into an interactive picker and answers nothing unattended; `neonctl connection-string --project-id winter-frog-54927244 --database-name neondb` works. A command that needs a fact it does not carry is an incomplete row — it looks recorded and still forces the next session to ask.
 - **Record-at-create (greenfield):** whenever GSD-T BUILDS/PROVISIONS an environment, record its map row in the SAME pass (it has the URL + creds right then).
 - **Never write a secret VALUE into the registry** — only the vault name + env-var NAME + a `$VAR`-referencing command. A literal secret is rejected by `recordEnvironment` and by the `gsd-t-verify` env-registry gate. If a secret is found in a URL/command, the capture flow OFFERS to move it into the vault (rotate-or-move, user's choice) and replace it with a `$VAR`.
 - **Local-literal switch:** a project may opt in via `.gsd-t/env-registry-config.json` `{"allowLocalLiteral": true}` to allow a literal secret in `scope=local` rows only; `staging`/`prod` stay strict.

package/templates/infrastructure.md

@@ -79,8 +79,8 @@ cp .env.example .env
 > document (detect → ask → record → proceed); never guess a connection string,
 > never grep transcripts to rediscover.
 
-| id | scope | kind | host | port | db/name | auth method | secret vault | secret env-var NAME | fetch command | connect command | access gotchas | read-only default | recorded |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| id | scope | kind | host | port | db/name | auth method | secret vault | secret env-var NAME | fetch command | connect command | access gotchas | read-only default | recorded | source |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 <!-- gsd-t-env-registry:end -->
 
 <!--
@@ -92,17 +92,35 @@ cp .env.example .env
     host              = POSITIVE shape: localhost | IPv4 | dotted DNS hostname |
                         short lowercase service name (letters+hyphen, no digits, e.g. db, postgres)
     db/name           = short lowercase snake identifier (<=16, e.g. binvoice_prod, analytics)
-    auth method       = ENUMERATED — password | iam | oauth | oauth2 | service-account |
-                        ssh-key | api-key | none | scram-sha-256 | md5 | trust | token | key | ...
+    auth method       = password | iam | oauth | oauth2 | service-account | ssh-key |
+                        api-key | none | scram-sha-256 | md5 | trust | token | key | ...
+                        A method the list has not heard of (cli-session, device-code) is
+                        accepted in LABEL shape: short lowercase hyphenated words, no digits.
     fetch command     = how to pull the secret from its vault (e.g. `vercel env pull`)
                         POSITIVE allowlist: a token is accepted ONLY if it IS a $VAR/${VAR} ref,
                         a flag, a hostname/IP, a .env dotfile, or a curated CLI/db word.
                         Any OTHER bare literal is REJECTED (move it to an env var, reference as $VAR).
     connect command   = references the env-var by name: `psql "$DATABASE_URL_PROD"` (same allowlist)
-    access gotchas    = ENUMERATED — vpn | ip-allowlist | ssh-tunnel | bastion | none,
-                        optionally `via <hostname>` (e.g. `ssh-tunnel via bastion.example.com`).
-                        Free prose is FORBIDDEN (nowhere for a secret to hide).
-    read-only default = YES for scope=prod unless a human explicitly recorded write-ok
+    access gotchas    = vpn | ip-allowlist | ssh-tunnel | bastion | none, optionally
+                        `via <hostname>` (e.g. `ssh-tunnel via bastion.example.com`).
+                        PLAIN-ENGLISH judgment is also allowed here and is the most
+                        valuable cell in the row ("live customer data — never mutate
+                        without an explicit OK"): no vendor CLI can ever return it.
+                        Checked word-by-word — ordinary words and numbers pass; a
+                        credential-shaped token does not.
+    read-only default = yes | no (any capitalisation). YES for scope=prod unless a
+                        human explicitly recorded write-ok.
+    port / db/name / secret env-var NAME
+                      = `n/a` is a valid TRUE answer where the column does not apply
+                        (a web console has no port; a hosting account is not a database).
+    source            = WHERE an unprovable value came from — a command
+                        (`neonctl projects list`) or a project file (`.vercel/project.json`).
+                        Fill it ONLY when a cell holds something the checker cannot
+                        recognise by shape: a vendor resource id (winter-frog-54927244)
+                        is indistinguishable from a token, so naming its source is what
+                        makes it acceptable. Its PRESENCE is the flag — there is no
+                        per-vendor list to maintain. It never excuses a value that
+                        positively looks like a credential.
   There is deliberately NO secret-value column — a row is structurally incapable
   of holding a secret. Populated by `gsd-t-env-registry` (record-at-create +
   capture-on-first-need).