@tekyzinc/gsd-t 4.19.14 → 4.20.11

package/bin/gsd-t.js

@@ -203,6 +203,24 @@ const {
 } = require("./playwright-bootstrap.cjs");
 const { hasUI } = require("./ui-detection.cjs");
 
+// M100 D1: stack-adaptive storage scaffolder — the sole init-scaffold seam.
+// Presents real alternatives and PAUSES for human approval; never silently
+// picks a logging backend. See .gsd-t/contracts/logging-scaffold-seam-contract.md.
+const { scaffoldLogging } = require("./gsd-t-logging-scaffolder.cjs");
+
+// runLoggingScaffoldStep(projectDir, opts): the init-dispatch integration
+// point. Calls the scaffolder and explicitly checks the envelope's `status`
+// field: on "PAUSED" it halts BEFORE any sink/template write and surfaces
+// alternatives[] to the caller; it only proceeds (halted:false) once a
+// resolved `backend` comes back (fresh approval or a valid recorded choice).
+function runLoggingScaffoldStep(projectDir, opts) {
+  const envelope = scaffoldLogging(Object.assign({ projectDir }, opts || {}));
+  if (envelope.status === "PAUSED") {
+    return { halted: true, alternatives: envelope.alternatives, resumeToken: envelope.resumeToken };
+  }
+  return { halted: false, backend: envelope.backend, envelope };
+}
+
 function readProjectDeps(projectDir) {
   const pkgPath = path.join(projectDir, "package.json");
   if (!fs.existsSync(pkgPath)) return [];
@@ -2130,6 +2148,26 @@ async function doInit(projectName) {
   // M52 D1: auto-install the journey-coverage gate. Idempotent — no-op if marker present.
   if (hasUI(projectDir)) installJourneyCoverageHook(projectDir);
 
+  // M100 D1: storage scaffolder step. Presents real backend alternatives and
+  // PAUSES for human approval — the ONE sanctioned pause against Level-3
+  // full-auto. On PAUSED, halts here and surfaces alternatives; never writes
+  // a trace/audit sink or picks a backend silently. See
+  // .gsd-t/contracts/logging-scaffold-seam-contract.md.
+  try {
+    const loggingOutcome = runLoggingScaffoldStep(projectDir);
+    if (loggingOutcome.halted) {
+      warn("Logging backend not yet chosen — scaffolder is PAUSED for human approval:");
+      for (const alt of loggingOutcome.alternatives) {
+        info(`  - ${alt.backend}${alt.recommended ? " (recommended)" : ""}: ${alt.label} — ${alt.reason}`);
+      }
+      info(`Re-run init with an approved backend to resume (resumeToken: ${loggingOutcome.resumeToken}).`);
+    } else {
+      success(`Logging backend: ${loggingOutcome.backend}`);
+    }
+  } catch (e) {
+    warn(`Logging scaffold step errored: ${e.message || e}`);
+  }
+
   showInitTree(projectDir);
 }
 
@@ -3736,13 +3774,17 @@ function refreshVersionAsync() {
 }
 
 function showUpdateNotice(latest) {
-  log("");
-  log(`  ${YELLOW}╭──────────────────────────────────────────────╮${RESET}`);
-  log(`  ${YELLOW}│${RESET}  Update available: ${DIM}${PKG_VERSION}${RESET} → ${GREEN}${latest}${RESET}            ${YELLOW}│${RESET}`);
-  log(`  ${YELLOW}│${RESET}  Run: ${CYAN}npm update -g @tekyzinc/gsd-t${RESET}         ${YELLOW}│${RESET}`);
-  log(`  ${YELLOW}│${RESET}  Then: ${CYAN}gsd-t update-all${RESET}                     ${YELLOW}│${RESET}`);
-  log(`  ${YELLOW}│${RESET}  Changelog: ${CYAN}gsd-t changelog${RESET}                  ${YELLOW}│${RESET}`);
-  log(`  ${YELLOW}╰──────────────────────────────────────────────╯${RESET}`);
+  // Human-facing banner MUST go to stderr — writing it to stdout corrupts the JSON
+  // output of machine commands (e.g. `graph body`, `graph --output json`), breaking
+  // any JSON.parse consumer. stderr keeps the banner visible without polluting stdout.
+  const e = (msg) => console.error(msg);
+  e("");
+  e(`  ${YELLOW}╭──────────────────────────────────────────────╮${RESET}`);
+  e(`  ${YELLOW}│${RESET}  Update available: ${DIM}${PKG_VERSION}${RESET} → ${GREEN}${latest}${RESET}            ${YELLOW}│${RESET}`);
+  e(`  ${YELLOW}│${RESET}  Run: ${CYAN}npm update -g @tekyzinc/gsd-t${RESET}         ${YELLOW}│${RESET}`);
+  e(`  ${YELLOW}│${RESET}  Then: ${CYAN}gsd-t update-all${RESET}                     ${YELLOW}│${RESET}`);
+  e(`  ${YELLOW}│${RESET}  Changelog: ${CYAN}gsd-t changelog${RESET}                  ${YELLOW}│${RESET}`);
+  e(`  ${YELLOW}╰──────────────────────────────────────────────╯${RESET}`);
 }
 
 function doChangelog() {
@@ -4871,6 +4913,8 @@ module.exports = {
   promptForApiKeyIfMissing,
   resolveApiKeyEnvVar,
   runTaskCounterRetirementMigration,
+  // M100: storage scaffolder seam
+  runLoggingScaffoldStep,
 };
 
 // ─── Main ────────────────────────────────────────────────────────────────────
@@ -4972,6 +5016,22 @@ if (require.main === module) {
     case "graph":
       doGraph(args.slice(1));
       break;
+    case "migrate-logging": {
+      // M100 D1 wiring on d5's behalf — d1 is the SOLE editor of bin/gsd-t.js;
+      // d5 owns bin/gsd-t-migrate-logging.cjs (the module) and
+      // commands/gsd-t-migrate-logging.md (the command). See
+      // .gsd-t/contracts/logging-scaffold-seam-contract.md §Ownership boundary.
+      let migrateLogging;
+      try {
+        migrateLogging = require("./gsd-t-migrate-logging.cjs");
+      } catch (e) {
+        error(`migrate-logging module not found: ${e.message || e}`);
+        process.exit(1);
+      }
+      Promise.resolve(migrateLogging.run ? migrateLogging.run(args.slice(1)) : migrateLogging(args.slice(1)))
+        .catch((e) => { error(e.message || String(e)); process.exit(1); });
+      break;
+    }
     case "headless":
       doHeadless(args.slice(1));
       break;

package/commands/gsd-t-help.md

@@ -76,6 +76,7 @@ HEADLESS (CI/CD)                                                       CLI
   research-gate       Classify a guessed claim: internal (grep) / external (web) / ambiguous (LLM judge) [M89]
   architectural-trigger  Fire the architectural-assumption trigger (divergence-sampling or extend-existing-code) [M90]
   loop-ledger         Record a debug cycle, read exit state, detect non-convergence (premise-re-examination) [M90]
+  migrate-logging     Brownfield: scaffold trace + audit logging into an existing project, additively [M100]
 
 BACKLOG                                                                Manual
 ───────────────────────────────────────────────────────────────────────────────
@@ -553,6 +554,13 @@ Use these when user asks for help on a specific command:
 - **CLI**: `gsd-t loop-ledger append-cycle --assertion "<symptom>" --surface "<file>" --fileClass unit --projectDir <dir>`. `gsd-t loop-ledger read-exit-state --projectDir <dir>`. Exit 0 on success.
 - **Contract**: `.gsd-t/contracts/unproven-assumption-doctrine-contract.md` §3 v1.0.0 STABLE.
 
+### migrate-logging (M100)
+- **Summary**: Brownfield migration — scaffolds the two framework-default logging streams (trace + audit) into an EXISTING project, ADDITIVELY. Trace is a default for every project except explicit opt-out recorded at `.gsd-t/trace-optout.json` (see `trace-logging-contract.md` §opt-out-record — a stateless CLI/library with no runtime data-flow may opt out); audit is a default except an explicit opt-out recorded at `.gsd-t/audit-optout.json` (see `audit-logging-contract.md` §opt-out-record) — the migration honors an existing opt-out for either stream rather than forcing a store on it. Every pre-existing project file is left byte-for-byte unchanged; only new logging files are added. Dispatch is wired into `bin/gsd-t.js` `case "migrate-logging"` by d1 (the sole editor of that file) on d5's behalf — the module (`bin/gsd-t-migrate-logging.cjs`) and this command are owned by d5 via the scaffold-seam contract.
+- **Files**: `bin/gsd-t-migrate-logging.cjs`. Contracts: `.gsd-t/contracts/logging-scaffold-seam-contract.md`, `.gsd-t/contracts/logging-schema-distillation-contract.md`, `trace-logging-contract.md`, `audit-logging-contract.md`.
+- **Use when**: An existing (brownfield) project needs the trace/audit defaults retrofitted without touching its current code or tests.
+- **CLI**: `gsd-t migrate-logging <projectDir> [--plan <path-to-plan.md>]`. Exit 0 on success · 1 on migration error.
+- **Proven**: `test/m100-d5-migration-fixture.test.js` — runs the migration against a throwaway fixture repo and asserts additive/non-destructive behavior (pre-existing files unchanged) before/after snapshot comparison.
+
 ## Unknown Command
 
 If user asks for help on unrecognized command:

package/commands/gsd-t-init.md

@@ -350,6 +350,17 @@ Operator overrides: `gsd-t setup-playwright [path]` (explicit single-project ins
 
 The spawn-time gate in `bin/headless-auto-spawn.cjs` re-runs the install on first need if the project skipped this step (e.g., older project that pre-dates M50).
 
+## Step 11.5: Logging Backend Scaffold (M100)
+
+The `bin/gsd-t.js init` flow calls `runLoggingScaffoldStep(projectDir)` (from `bin/gsd-t-logging-scaffolder.cjs`) automatically, right before the init tree summary. This is the sole init-scaffold seam for M100's trace/audit logging.
+
+- It detects the stack (has-DB → `db-table` alternative; no-server/desktop → `local-sqlite` | `local-jsonl`, with SQLite flagged over flat-file for audit queryability).
+- It **presents real alternatives and PAUSES for human approval** — this is the ONE sanctioned pause against the Level-3 full-auto default (see `.gsd-t/contracts/logging-scaffold-seam-contract.md`). It never silently picks a backend.
+- On re-run with a previously-approved choice, it resumes deterministically (no re-prompt) and records the backend into the project's `CLAUDE.md`.
+- If it halts with `status:"PAUSED"`, report the presented alternatives to the user and wait for them to choose before re-running init with an approved backend — do NOT guess or auto-select on their behalf.
+
+See `.gsd-t/contracts/logging-scaffold-seam-contract.md` for the full seam envelope shape consumed by d2 (trace), d4 (audit), and d5 (migrate-logging).
+
 ## Step 12: Test Verification
 
 After initialization:

package/commands/gsd-t-migrate-logging.md

@@ -0,0 +1,46 @@
+# GSD-T: Migrate Logging — Brownfield Trace + Audit Retrofit
+
+Scaffolds the two framework-default logging streams — **trace** (transient debug signal, no opt-out) and **audit** (durable accountability record, default except explicit opt-out) — into an EXISTING project, additively. See `~/.claude/CLAUDE.md` § Logging Defaults for the two hard rules this command implements.
+
+## What this does
+
+- Copies the trace module template (`templates/logging/trace-module.template.ts`) to `src/logging/trace.ts` — **only if that file does not already exist**.
+- Copies the audit module template (`templates/logging/audit-module.template.ts`) to `src/logging/audit.ts` — **only if that file does not already exist**.
+- Distills the per-project trace category / audit action schema from the project's own plan (when `--plan` is given) into `.gsd-t/logging-schema.json` — never confabulated; an unstated category/action is a gap, not a guess.
+- Runs d1's stack-adaptive storage scaffolder (`scaffoldLogging()`), which detects the stack and **pauses for human approval** before recording a storage backend — never silently picks one.
+
+## Non-destructive guarantee (MANDATORY)
+
+This command is **purely additive**. Every write is preceded by an existence check; a file that already exists in the target project is left byte-for-byte untouched. It is proven non-destructive on a throwaway fixture in `test/m100-d5-migration-fixture.test.js` — a run that modifies or deletes any pre-existing fixture file is a test FAILURE.
+
+## Usage
+
+```
+gsd-t migrate-logging <projectDir> [--plan <path-to-plan.md>] [--approve <db-table|local-sqlite|local-jsonl>]
+```
+
+- `<projectDir>` — required. The existing project to retrofit.
+- `--plan <path>` — optional. Distills the concrete trace category / audit action set from this plan file. Omit to get an empty (never invented) schema.
+- `--approve <backend>` — optional. Approves a storage backend up front (`db-table` / `local-sqlite` / `local-jsonl`). Omit to let the scaffolder pause and present alternatives first.
+
+## Step 1: Run the migration
+
+Invoke the module via the CLI dispatch (owned by d1 — `bin/gsd-t.js` `case "migrate-logging"`; the module itself is owned by this domain, see `.gsd-t/contracts/logging-scaffold-seam-contract.md`):
+
+```bash
+gsd-t migrate-logging "$ARGUMENTS"
+```
+
+## Step 2: Report
+
+Show the created/skipped file lists and the storage scaffold result (approved backend, or the PAUSED alternatives list awaiting human approval) exactly as returned by the module — do not summarize away a PAUSED state as if it were complete.
+
+## Step 3: If storage is PAUSED
+
+Present the alternatives to the user and wait for an explicit backend choice (the ONE sanctioned pause against the Level-3 full-auto default — see `.gsd-t/contracts/logging-scaffold-seam-contract.md`). Re-run with `--approve <backend>` once chosen.
+
+$ARGUMENTS
+
+## Auto-Clear
+
+All work is committed to project files. Execute `/clear` to free the context window for the next command.

package/commands/gsd-t-verify.md

@@ -20,9 +20,10 @@ preflight → brief → verify-gate (deterministic Track 1+2)
 Per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE, the three triad stages are orthogonal objective functions — no collapse, no substitution, no transitive trust. Synthesis preserves category labels.
 
 **Hard-failing gates** (each halts before triad):
-- `verify-gate` — deterministic Track 1 (preflight envelope) + Track 2 (tsc/biome/npm-test/knip/gitleaks/scc fan-out)
+- `verify-gate` — deterministic Track 1 (preflight envelope) + Track 2 (tsc/biome/npm-test/knip/gitleaks/scc/logging-envelope fan-out)
 - M57 `build-coverage` + `ci-parity` — origin TimeTracking v1.10.12 Dockerfile incident
 - M58 `test-data --purge` — origin GSD-T-Board v0.1.10 2442 E2E orphans incident
+- M100 `logging-envelope` — structural predicate (`bin/gsd-t-logging-envelope-check.cjs`) enforcing BOTH the trace envelope (`ts`/`category`/`decision`/`detail`) and the audit envelope (`ts`/`actor`/`action`/`target`/`before`/`after`/`context`) over per-project-varying schemas — never a hardcoded category/action value. Also enforces the trace PII bar (recursing into nested `data`), the no-collapse boundary (a record MUST NOT carry top-level markers from both streams), append-only/immutability, retention-configurability, and audit-default-except-opt-out (`.gsd-t/audit-optout.json`). FAIL-CLOSED — never warn-and-proceed. Contract: `.gsd-t/contracts/logging-verify-gate-contract.md`.
 
 ## Step 1: Read the current milestone state
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.19.14",
+  "version": "4.20.11",
   "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

@@ -222,6 +222,16 @@ The hard rules (non-negotiable, all projects):
 - **Functional, not layout.** Every assertion must prove state changed / data flowed / content loaded / widget responded — not mere existence (`isVisible`/`toBeAttached`). If a test would pass on empty HTML with the right IDs and no JS, rewrite it.
 - **Test-data cleanup.** Tests that insert data MUST register it via the `withTestData()` fixture so verify Step 4.5 (`gsd-t test-data --purge`) can remove it; an adapter throw/refusal FAILs the gate. Adapters refuse to delete ids lacking the ledger `taggedPrefix`. See [[feedback_test_data_cleanup_convention]] + `.gsd-t/contracts/test-data-ledger-contract.md`.
 
+## Logging Defaults — Trace + Audit (M100 — MANDATORY)
+
+Every GSD-T project gets TWO logging streams scaffolded by default at `gsd-t-init` — never opt-in, and never silently skipped (an opt-out must be an explicit, reasoned, recorded decision, not a silent absence). Contracts: `.gsd-t/contracts/trace-logging-contract.md`, `.gsd-t/contracts/audit-logging-contract.md`, `.gsd-t/contracts/logging-schema-distillation-contract.md`, `.gsd-t/contracts/logging-scaffold-seam-contract.md`.
+
+- **Rule 1 — Trace is a default for EVERY project EXCEPT explicit opt-out.** Trace = a transient, PII-barred, toggleable DEBUGGING SIGNAL STREAM (`ts`/`category`/`decision`/`detail` envelope). Scaffolded into every project regardless of stack; `gsd-t-verify` FAILs a project with no discoverable trace module/store AND no valid opt-out record. A stateless CLI/library with no runtime data-flow (no requests/jobs/integrations/user sessions) may opt out by writing the canonical opt-out record to `.gsd-t/trace-optout.json` (`{"traceOptOut": true, "reason": "<why>"}` — see `trace-logging-contract.md` §opt-out-record); a running application must NOT opt out.
+- **Rule 2 — Audit is a default for EVERY project EXCEPT explicit opt-out declared in the project's own CLAUDE.md.** Audit = a durable, admin-queryable, append-only ACCOUNTABILITY record (`ts`/`actor`/`action`/`target`/`before`/`after`/`context` envelope). A project that genuinely has no admin-facing accountability surface (e.g. a pure local trace-only tool) may opt out by writing the canonical opt-out record to `.gsd-t/audit-optout.json` (`{"auditOptOut": true, "reason": "<why>"}` — see `audit-logging-contract.md` §opt-out-record). `gsd-t-verify` FAILs any project with neither a discoverable audit store NOR a valid opt-out record; a valid opt-out is honored and does NOT fail the project for missing audit.
+- **Storage is stack-adaptive and human-approval-gated** — `bin/gsd-t-logging-scaffolder.cjs` detects the stack, presents real alternatives, and STOPS for approval; it never silently picks a backend (the one sanctioned pause against the Level-3 full-auto default).
+- **Trace and audit NEVER collapse into one stream.** A trace envelope carrying audit markers (`before`/`after`/`actor`/`action`) or vice-versa is a contract violation and a `gsd-t-verify` FAIL — see each contract's §no-collapse boundary.
+- **Brownfield migration**: `gsd-t migrate-logging <projectDir>` scaffolds both streams into an EXISTING project additively — it never modifies or deletes a pre-existing file. See `commands/gsd-t-migrate-logging.md`.
+
 ## Orthogonal Validation Triad (Mandatory)
 
 Every code-producing phase ends with `gsd-t-verify.workflow.js`, which runs three orthogonal validators as `parallel()` `agent()` stages with schema-validated output. Per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE, they are declared orthogonal objective functions — no collapse, no substitution, no transitive trust.
@@ -419,6 +429,33 @@ asserting. If you lack a fresh source, say so explicitly: *"I believe X, but I d
 source — please verify."* Do NOT state an external/time-varying fact as known when it is a guess.
 See memory pointer: `feedback_auto_research_external_gaps`.
 
+### Architect's Oversight Doctrine (M101 — governed, enforced)
+
+**Contract:** `.gsd-t/contracts/architects-oversight-contract.md` v1.0.0 STABLE
+
+**Never build before the design has passed the architect's interrogation.** GSD-T staffs verifiers (Red Team, QA, code-review, pre-mortem) — all asking "is this correct?" — but no seat asked "is this the *smartest, simplest* design given what we already have?" The result: the wrong thing built correctly, then thoroughly tested, then shipped (the Binvoice completeness-scan waste — a whole-page scan re-deriving a count already stored locally). This doctrine fills the empty architect seat. Sibling to the Unproven-Assumption Doctrine: that one bars unproven *facts*; this one bars unproven *necessity*.
+
+**The Six-Stage Pass — run IN ORDER before proposing or building any solution. Each stage can KILL the plan. Every "am I sure?" is answered with EVIDENCE (a grep, a Read, a graph query), never conviction — self-confidence is what produced the waste.**
+
+1. **Objective** — What is the core objective? Why is it the core objective? *(Kills: building the wrong thing.)*
+2. **Conflict** — Does it support or conflict with other core objectives? Must we re-examine/re-plan an already-built objective? *(Kills: a local win that breaks the system; frozen past decisions.)*
+3. **Reuse** — Have I already accomplished any piece of this? Can I reuse the **process**, or the **output** of that process? *(Query the graph — not memory. This stage kills redundant work like the completeness scan. Split is load-bearing: reuse the answer already produced, not just the code.)*
+4. **Simplicity** — Is this the simplest, most efficient plan? Am I sure? *(Evidence, not conviction. Kills bloat.)*
+5. **Reuse forecast & duplication** — see §Reuse Logic below. *(Kills both over-engineering and rogue-twin sprawl.)*
+6. **Risk** — Security risks? Stability/scalability risks? Am I sure? *(Kills fast-but-fragile.)*
+   → **Then build.**
+
+**§Reuse Logic (Stage 5 — how to avoid both sprawl and stability-breakage):**
+- **Forecast reuse likelihood** against long-term project scope (read requirements/architecture — don't guess): **HIGH** (core domain entity / recurs in roadmap / pure transformation) or **LOW** (one-off UI/debug/glue / single caller). HIGH → build clean + extractable now (NOT config-knobbed — that's the YAGNI trap), register in the graph as reuse-likely. LOW → simplest inline thing, no abstraction.
+- **When a similar-but-not-reusable thing already exists:** (a) same WHAT (job) or same HOW (surface)? Same WHAT → generalize; merely similar → build new. (b) If generalize: **extract a shared core, do NOT mutate** the working original (old callers keep identical behavior). (c) If blast-radius/stability forbids touching it → build new, **but register a "reuse-candidate" link in the graph** pointing at the twin, so the duplication is visible and re-decided on next touch. **Never build a silent rogue twin** — sprawl disables Stage 3's reuse-check for everyone after you.
+- **A wrong forecast self-corrects:** the graph's similarity check surfaces a LOW-forecast function that got reused anyway at the next Stage 3. So the forecast need only be directionally right — the graph rescues the misses. That is what removes the paralysis.
+
+**§Plain-English proof (the artifact you can always review, never must):** the Six-Stage answers are written into the milestone's **PseudoCode document** in plain, jargon-free language (style: `.gsd-t/pseudocode/` — title + one-line purpose, `CURRENT`/`PROPOSED` blocks, `# plain comment` inline, a summary table; near-zero preamble). Jargon is where unexamined complexity hides — a layman-legible sentence has nowhere for a pointless operation to survive. The pseudocode IS the audit, and it lets the user approve *direction before code* as the senior reviewer, not a rubber-stamp.
+
+**§Jargonless output (co-equal with brevity, NOT a trade-off):** short and clear are different axes; jargon is short, so brevity rules alone reward it. Every reply, plan, options-prompt, and mid-work narration glosses jargon in plain words on first use. The crux: individual shorthand may be decodable, but **several mashed into one sentence become unintelligible** — never force the reader toward an "I don't understand" escape hatch; if that option would help, the sentence already failed. Enforced by the Reader Contract (injected every turn).
+
+**§Enforcement (three layers — same shape as Unproven-Assumption):** (1) this doctrine = the *definition* (reference, always available); (2) a **PreToolUse hook on Write/Edit** = the *trigger* — injects a one-line reminder pointing here at the build moment, so it can't be missed under load; (3) the **plan/milestone workflow gate** = the *execution* — the Six-Stage Pass runs as blocking `agent()` steps with graph/doc evidence, and pseudocode-completeness is a verify check. Injecting the doctrine ≠ executing it; the workflow does the doing.
+
 ### Phase Flow
 - Upon completing a phase, automatically proceed to the next phase
 - ONLY run Discussion phase if truly required (clear path → skip to Plan)