@tekyzinc/gsd-t 5.0.14 → 5.1.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-architect.md

@@ -85,6 +85,12 @@ The subagent works through the six stages IN ORDER. Each can kill or reshape the
    you can cite a confirmed reproducible case only a fallback catches. The straight-line process
    that produces the result is the goal; where it can fail, prefer a **HALT** (stop + demand
    fix), which is NOT a fallback. (See CLAUDE.md § No-Fallback-Ever Doctrine.)
+7. **SIMPLY-STATED** (clarity gate — the review is NOT done until this passes) — state every
+   finding and the verdict SIMPLY: precise and complete, but every word load-bearing, the logic
+   in a straight line, ZERO jargon standing in for a clear idea, no nested clauses hiding a
+   tangle. If a finding cannot be stated simply, the thinking on it is not finished — RE-THINK
+   the muddled part, do not re-word it. "Too sophisticated to simplify" is a BANNED escape hatch
+   (simplify the expression, never the idea). (See CLAUDE.md § Simply Stated Doctrine.)
 
 A stage the subagent cannot answer with evidence is a HALT — surface it as an open question for
 the user, do not paper over it with a guess.
@@ -100,6 +106,10 @@ a summary table, near-zero preamble. For each CURRENT block, say **why it does w
 successive fixes). Unless `--chat-only`, write it to `.gsd-t/pseudocode/PseudoCode-<Target>.md`.
 
 **B — Session summary** (always printed, even under `--build`):
+- **Simply Stated** (REQUIRED FIRST LINE — the clarity gate) — the verdict + the single most
+  important finding in ONE clean, jargon-free, straight-line statement a smart non-specialist
+  acts on without re-reading. If you cannot write this line cleanly, the review is NOT done —
+  re-think, don't re-word. Everything below is the depth for whoever wants it.
 - **Core objective** (one line)
 - **Is this a "complicated over time" issue?** (yes/no + the accretion history if yes)
 - **What's reusable** (process or a stored output already available)

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,11 @@ 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.
 
 ## Graph Structural Slice — who-imports + cluster (M94-D10)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.0.14",
+  "version": "5.1.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-architect-oversight-guard.js

@@ -45,7 +45,11 @@ const REMINDER =
   "(catch-and-continue, || default, silent degrade, try-X-else-Y) — STOP and ask the " +
   "user first, unless you can cite a confirmed reproducible case only a fallback catches. " +
   "A HALT (stop + demand fix) is NOT a fallback and is the preferred move. " +
-  "See ~/.claude/CLAUDE.md § Architect's Oversight + No-Fallback-Ever Doctrines.";
+  "SIMPLY-STATED: before presenting an architecture/plan/finding, state it SIMPLY — every " +
+  "word load-bearing, logic in a straight line, no jargon or nested clauses. If you can't " +
+  "state it cleanly the thinking isn't done (muddle in the words = muddle in the design) — " +
+  "RE-THINK, don't re-word. 'Too sophisticated to simplify' is a banned escape hatch. " +
+  "See ~/.claude/CLAUDE.md § Architect's Oversight + No-Fallback-Ever + Simply Stated Doctrines.";
 
 // File extensions that are PROSE/config, not code — skip the reminder for these.
 // (The doctrine's own artifacts are markdown; reminding while authoring them is noise.)

package/templates/CLAUDE-global.md

@@ -99,6 +99,26 @@ NEED TO UNDERSTAND SOMETHING?
   └── Not documented? → Research, then DOCUMENT IT
 ```
 
+### Environment Access — read-first, HALT-and-document (M102)
+
+**EXTENDS No-Re-Research; obeys No-Fallback-Ever.** Before reaching ANY non-local environment (staging/prod DB, remote server, hosted API, SSH host), the connection MAP is read from the committed `## Environments` table in `docs/infrastructure.md` — NEVER re-discovered.
+
+```
+NEED TO REACH A NON-LOCAL ENVIRONMENT?
+  ├── lookupEnvironment(scope, kind) FIRST  →  bin/gsd-t-env-registry.cjs lookup
+  ├── Row exists → use its connect command; the secret is pulled at runtime via
+  │                the recorded env-var NAME from its vault (never a value in the doc).
+  │                scope=prod + read-only=YES + a WRITE op → HALT, confirm with human.
+  └── Row MISSING → HALT the connect. Do NOT guess a connection string. Do NOT grep
+                    transcripts to rediscover. The brownfield path:
+                    detectEnvConfig → ask human to confirm/fill → recordEnvironment
+                    → addPermissionEntry → THEN proceed. First need = last rediscovery.
+```
+
+- The registry stores only the MAP + which vault holds the secret + the env-var NAME + the fetch/connect commands — **never a secret VALUE**.
+- **Zero fallback.** A missing row resolves by DOCUMENTING (detect → ask → record → proceed), never by a guessed connstring or a transcript re-grep. That HALT-then-document is NOT a fallback.
+- Greenfield: when GSD-T builds/provisions an env, it records the row in the SAME pass (`recordEnvironment`) — so staleness self-heals (a re-provision upserts by `(scope, kind)` and replaces the stale row).
+
 
 # Versioning
 
@@ -473,6 +493,18 @@ See memory pointer: `feedback_auto_research_external_gaps`.
 
 **§Enforcement (three layers):** (1) this doctrine = the definition; (2) the **Architect's Oversight Write/Edit trigger is extended** to challenge every fallback at the build moment ("is this a fallback? name the proven case or ask"); (3) mechanical guards where they already exist — the graph consumers' `try→catch→grep` fallback is caught by `bin/gsd-t-graph-anti-grep-lint.cjs` (reused, not duplicated); a general static "detect every fallback" lint is deliberately NOT built (it can't judge *proven-necessary* — that is the human/architect ask, which is layer 2).
 
+### Simply Stated Doctrine (governed, enforced — clarity as a defect gate, not a writing-style reminder)
+
+**Before GSD-T presents an architecture, plan, finding, review, or milestone definition, it must first state it *simply* — precise and complete, every word earning its place, the logic in a straight line, with no jargon standing in for a clear idea and no nested clauses hiding a tangle. If it cannot be stated simply, the thinking is NOT finished: the muddle in the words IS a muddle in the design. It goes back to be RE-THOUGHT, not re-worded.** The simply-stated version leads the deliverable; the technical depth sits below it for whoever wants it.
+
+**This is a DIFFERENT mechanism from the Reader Contract / jargon lint.** Those treat verbosity as an OUTPUT-polish problem — trim the prose after the thinking is done — and repeatedly fail because a reminder loses to "but this case needs the detail" under load. Simply Stated treats verbosity as what it is: **a symptom of unclear thinking, and the same unclear thinking ships the bugs.** If you cannot express it cleanly, you do not yet understand it — and not-understanding is where defects come from. The inability to state it simply is a DEFECT SIGNAL, gated like the No-Fallback HALT, not a soft nudge.
+
+**"Simply" is NOT "dumbed down."** The content stays as sophisticated as the problem demands — sophisticated IN its simplicity and conciseness (simplify the *expression*, never the *idea*). The test is NOT "could a novice understand the topic." The test is: **is every word load-bearing, and is the logic a straight line?** "This topic is too sophisticated to state simply" is the banned escape hatch.
+
+**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.
+
+**§Enforcement (three 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. The simply-stated lead is a REQUIRED ARTIFACT (like the pseudocode file), not advice.
+
 ### Phase Flow
 - Upon completing a phase, automatically proceed to the next phase
 - ONLY run Discussion phase if truly required (clear path → skip to Plan)

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)

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

@@ -934,6 +934,13 @@ const _architectPassLine = _ARCHITECT_PHASES.has(phaseName)
       `     it in — UNLESS you can cite a confirmed reproducible case only a fallback catches. The`,
       `     straight-line process that produces the result is the goal; where it can fail, prefer a`,
       `     HALT (stop + demand fix), which is NOT a fallback. Fallbacks are rare and ask-first.`,
+      `  7. SIMPLY-STATED (clarity gate — the plan is NOT done until this passes) — write the ${phaseName}`,
+      `     as a SIMPLY-STATED lead FIRST: precise and complete, but every word load-bearing, the logic`,
+      `     in a straight line, ZERO jargon standing in for a clear idea, no nested clauses hiding a`,
+      `     tangle. If you CANNOT state it simply, the thinking is not finished — the muddle in the`,
+      `     words is a muddle in the design; RE-THINK the muddled part, do not re-word it. "Too`,
+      `     sophisticated to simplify" is a BANNED escape hatch (simplify the expression, never the`,
+      `     idea). This simply-stated lead heads the deliverable; the depth sits below it.`,
       `A stage you cannot answer with evidence HALTS the plan (needs-human) — do not proceed on a hunch.`,
     ].join("\n")
   : "";