@tekyzinc/gsd-t 5.1.12 → 5.2.10

package/bin/gsd-t-logging-scaffolder.cjs

@@ -21,6 +21,9 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
+// M102 — the marker-block idempotent doc-writer was extracted here into the ONE
+// shared module both this scaffolder and bin/gsd-t-env-registry.cjs call.
+const { upsertMarkedDocBlock } = require("./gsd-t-doc-marker.cjs");
 
 const VALID_BACKENDS = ["db-table", "local-sqlite", "local-jsonl"];
 
@@ -182,24 +185,9 @@ function writeChoiceToProjectDocs(projectDir, envelope) {
   const targetPath = candidates.find((p) => fs.existsSync(p)) || candidates[0];
 
   const block = docBlock(envelope);
-  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(DOC_MARKER_START) && content.includes(DOC_MARKER_END)) {
-    const startIdx = content.indexOf(DOC_MARKER_START);
-    const endIdx = content.indexOf(DOC_MARKER_END) + DOC_MARKER_END.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;
+  // M102 — delegate to the ONE shared marker-block writer (byte-identical logic
+  // to the former inline replace/append; extracted so env-registry reuses it).
+  return upsertMarkedDocBlock(targetPath, DOC_MARKER_START, DOC_MARKER_END, block);
 }
 
 // ─── Seam envelope builder ──────────────────────────────────────────────────

package/bin/gsd-t-verify-gate.cjs

@@ -307,6 +307,8 @@ function _detectDefaultTrack2(projectDir, notes) {
 
   plan.push({ id: 'logging-envelope', cmd: 'node', args: [path.join(__dirname, 'gsd-t-logging-envelope-check.cjs'), '--project', projectDir], timeoutMs: 30000 }); // M100 D3: structural trace+audit envelope gate, FAIL-CLOSED
 
+  plan.push({ id: 'env-registry', cmd: 'node', args: [path.join(__dirname, 'gsd-t-env-registry-check.cjs'), '--project', projectDir], timeoutMs: 30000 }); // M102 D3: no-secret-in-registry + rule-without-table gate, FAIL-CLOSED
+
   // secrets — gitleaks (PATH detection deferred to runtime)
   if (_hasOnPath('gitleaks')) {
     plan.push({

package/bin/gsd-t.js

@@ -2999,6 +2999,16 @@ const PROJECT_BIN_TOOLS = [
   // ship to every project or the consumers can't classify. Same propagation class as
   // gsd-t-graph-store-resolver.cjs above. [[project_global_bin_propagation_gap]]
   "gsd-t-graph-availability.cjs",
+  // M102 — Environment Registry. The shared marker-block doc-writer + the
+  // registry helper (record/lookup/detect/add-permission/ensure-gitignore).
+  // Sandboxed workflows (init/populate + provisioning execute/quick tasks) call
+  // the registry via project-local Bash, and the registry `require`s the shared
+  // writer at load — BOTH must ship or the registry throws / the writer is a
+  // second copy. Same propagation class as the graph tools above.
+  // [[project_global_bin_propagation_gap]]
+  // Plus the verify-gate lint (gsd-t-verify-gate.cjs invokes it via __dirname,
+  // so it must sit alongside the gate in the project's bin/).
+  "gsd-t-doc-marker.cjs", "gsd-t-env-registry.cjs", "gsd-t-env-registry-check.cjs",
 ];
 
 // Files that older versions of this installer copied into project bin/ but

package/commands/gsd-t-init.md

@@ -296,6 +296,12 @@ docs/
 
 These are the living documents that persist across milestones and keep institutional knowledge alive. The `infrastructure.md` is especially important — it captures the exact commands for provisioning cloud resources, setting up databases, managing secrets, and deploying, so this knowledge doesn't get lost between sessions.
 
+The `infrastructure.md` template ships with a marker-delimited `## Environments` table (`<!-- gsd-t-env-registry:start -->` / `:end`) — the committed, **secret-free** connection registry (M102). It is created empty by init and populated by the two triggers:
+- **Greenfield (record-at-create):** whenever this project later BUILDS/PROVISIONS/CONFIGURES an environment (a local test DB, a remote server, credentials, or hands the user setup instructions), record the map row in the SAME pass:
+  `node bin/gsd-t-env-registry.cjs record '{"projectDir":".","scope":"local","kind":"postgres","host":"localhost","port":"5432","name":"appdb","authMethod":"password","secretVault":"local (.env)","secretEnvVarName":"DATABASE_URL","fetchCommand":"read $DATABASE_URL from .env","connectCommand":"psql \"$DATABASE_URL\""}'`
+  Records only the MAP + vault pointer + env-var NAME + fetch/connect commands — **never a secret VALUE** (a literal password/token in a command is REJECTED). `scope=prod` defaults `read-only=YES`.
+- Also run `node bin/gsd-t-env-registry.cjs ensure-gitignore .` so `.env` is gitignored (auto-add + report; secret-leak precheck).
+
 ## Step 8: Ensure README.md Exists
 
 If no `README.md` exists, create one with:

package/commands/gsd-t-populate.md

@@ -29,6 +29,13 @@ Scan this codebase and populate the GSD-T documentation. Analyze the actual code
 - List Credentials and Secrets from .env.example (local) and any secret manager configs
 - Document Deployment from CI/CD configs, Dockerfiles, cloud configs
 - Document Logging and Monitoring from any logging setup or dashboard configs
+- **Back-fill the `## Environments` registry (M102 — brownfield capture).** For an existing project whose non-local environments are undocumented, back-fill the map-only Environments table WITHOUT ever reading or writing a secret VALUE:
+  1. `node bin/gsd-t-env-registry.cjs detect .` → proposes the vault + fetch command from `.env.example` var NAMES, connection-string SHAPES, and `vercel.json`/`.vercel` (Vercel) · `cloudbuild.yaml`/`.gcloudignore` (Google Secret Manager) · neon dep (Neon) · plain `.env` (local). Map only — never a value.
+  2. Confirm/fill gaps with the human, then `node bin/gsd-t-env-registry.cjs record '<json>'` per environment (upsert by `(scope, kind)` — a re-provision replaces the stale row).
+  3. `node bin/gsd-t-env-registry.cjs ensure-gitignore .` — auto-add `.env` to `.gitignore` if missing + report.
+  - **No-Fallback-Ever:** a genuinely undocumented environment reached for the first time HALTs → detect → ask → record → `add-permission` → proceed. NEVER guess a connection string, NEVER grep transcripts to rediscover.
+  - **Leak remediation (secret found in a URL/command):** before recording, run `node bin/gsd-t-env-registry.cjs propose-remediation . '<command>'`. If it reports `needed:true`, STOP and tell the user *what* leaked (`detectedSecret`), then ASK **rotate or move** (`choices.rotate` / `choices.move`) — each time, do not assume. On their answer: store the (rotated or existing) secret into the detected `vault` (directly where possible — e.g. `vercel env add`, write to `.env`; else instruct the user to create/rotate it), then record the row with the `rewrittenCommand` ($VAR form). NEVER commit the literal secret.
+  - **Local-literal switch (per project):** by default every row uses `$VAR` (strict). A project may opt in via `.gsd-t/env-registry-config.json` → `{"allowLocalLiteral": true}` to allow a LITERAL secret in `scope=local` rows only (testing convenience). `staging`/`prod` are ALWAYS strict. A relaxed local write returns a one-time "committed file → git history" warning — surface it.
 
 ## Graph Structural Slice — who-imports + cluster (M94-D10)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.1.12",
+  "version": "5.2.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/scripts/gsd-t-auto-route.js

@@ -32,6 +32,7 @@ const path = require("path");
 const READER_CONTRACT = [
   "[GSD-T READER CONTRACT] Before sending ANY reply, assume your first draft is too wordy and rewrite it tight. Rules:",
   "• Answer FIRST. No preamble, no restating the question, no narrating what you're about to do (\"let me check…\"). Do the work silently, then give the result.",
+  "• NO PREAMBLES — start with the answer, never a framing phrase. BANNED openers (and anything like them): \"One thing I owe you honestly:\", \"To be honest\", \"Here's the thing\", \"The honest truth is\", \"I'll be straight with you\", \"Let me level with you\", \"Full transparency:\", \"Real talk\", \"What's worth noting here\", \"The key insight is\", \"Here's what's happening\". Delete the opener and lead with the actual point — if a sentence only announces that a point is coming, cut it.",
   "• Exception — when you're about to CHANGE code/files: state intent in one line first, so the user can stop a wrong direction.",
   "• Gloss every code/jargon term in plain words on first use. No bare IDs or acronyms the reader must decode.",
   "• Bullets/tables over paragraphs. Cut hedging and meta-commentary. Expand only if asked.",

package/templates/CLAUDE-global.md

@@ -96,9 +96,22 @@ NEED TO UNDERSTAND SOMETHING?
   ├── Is it about what to build? → Read docs/requirements.md
   ├── Is it about how to deploy/operate? → Read docs/infrastructure.md
   ├── Is it about domain interfaces? → Read .gsd-t/contracts/
+  ├── Is it about reaching a non-local environment (DB/server URL, creds, perms)? → Read the `## Environments` registry in docs/infrastructure.md
   └── Not documented? → Research, then DOCUMENT IT
 ```
 
+## Environment Access — read-first, HALT-and-document (M102)
+
+**Before reaching ANY non-local environment (a staging/prod DB, a remote server, an external service), READ the `## Environments` registry in `docs/infrastructure.md` FIRST.** It is the committed, **secret-free** map of every environment — host, port, db, auth method, which vault holds the secret, the env-var NAME, and the connect command (secrets referenced as `$VAR`, never as a literal value).
+
+- **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)`.
+- **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.
+
+Details: `.gsd-t/contracts/env-registry-contract.md`.
+
 
 
 # Versioning
@@ -484,7 +497,7 @@ See memory pointer: `feedback_auto_research_external_gaps`.
 
 **The HALT (the teeth):** a deliverable whose simply-stated lead cannot be written cleanly is NOT done — stop, surface it, re-think the muddled part. Do not ship the verbose version with an apology; the verbose version is evidence the design has a gap.
 
-**§Applies to conversational narration too, not just formal deliverables.** The doctrine governs REPLIES and mid-work talk-to-the-user, not only architectures/plans/findings. Two extra rules there: **NO PREAMBLE** (no throat-clearing, no "let me…", no narrating-the-explanation like "it matters that I say why…" — give the point, not a description of the point), and **load-bearing point FIRST** (never buried after justification clauses). No clever phrase that obscures where a plain one is clearer.
+**§Applies to conversational narration too, not just formal deliverables.** The doctrine governs REPLIES and mid-work talk-to-the-user, not only architectures/plans/findings. Two extra rules there: **NO PREAMBLES** (no throat-clearing, no "let me…", no narrating-the-explanation like "it matters that I say why…" — give the point, not a description of the point; BANNED openers and anything like them: "One thing I owe you honestly:", "To be honest", "Here's the thing", "The honest truth is", "I'll be straight with you", "Full transparency:", "What's worth noting", "The key insight is" — delete the opener, lead with the point), and **load-bearing point FIRST** (never buried after justification clauses). No clever phrase that obscures where a plain one is clearer.
 
 **§Enforcement (four layers):** (1) this doctrine = the definition; (2) the **Architect's Oversight Write/Edit trigger** carries a Simply-Stated line; (3) the **plan/milestone Six-Stage Pass + `/gsd-t-architect` gain a Simply-Stated gate** — the pass does not complete until its finding/plan has a clean simply-stated lead, and the validation protocols flag a deliverable that lacks one (a REQUIRED ARTIFACT like the pseudocode file, not advice); (4) the **every-turn Reader Contract** (injected by the UserPromptSubmit hook `scripts/gsd-t-auto-route.js`) carries the Simply-Stated rule + a before/after example, so it governs conversational output each reply — the channel that reaches mid-work narration, which layers 2-3 do not.
 

package/templates/infrastructure.md

@@ -68,6 +68,46 @@ cp .env.example .env
 {command}
 ```
 
+<!-- gsd-t-env-registry:start -->
+## Environments
+
+> **Map, not secrets.** This table records only WHERE an environment lives and
+> HOW to reach it — host/port/name/auth-method/which-vault-holds-the-secret/the
+> env-var NAME/the fetch + connect commands. It NEVER stores a secret VALUE.
+> The value lives in the vault (`.env` / Vercel / Neon / Google Secret Manager)
+> and is pulled at runtime via the env-var NAME. A missing row → HALT and
+> 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 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+<!-- gsd-t-env-registry:end -->
+
+<!--
+  Column notes:
+    scope             = local | staging | prod
+    kind              = postgres | mysql | redis | http-api | ssh-host | ...
+    secret vault      = local (.env) | Vercel | Neon | Google Secret Manager | ...
+    secret env-var NAME = e.g. DATABASE_URL_PROD  — the NAME only, NEVER the value
+    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 | ...
+    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
+  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).
+-->
+
 ## Credentials & Secrets
 
 ### Local (.env)