@tekyzinc/gsd-t 4.19.13 → 4.20.10

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-stories.md

@@ -32,12 +32,18 @@ For EACH story, author in EXACTLY this order (per the format reference):
 3. **Story:** `*As a <role>, I want <capability>, so that <benefit>.*` (strict template, one sentence.)
 4. **Workflow:** numbered concrete interaction steps (user action → system response), present tense.
 5. **Acceptance Criteria:** bulleted, **grouped by sub-area** with a bold sub-heading per group; include error/edge/recovery groups. Each bullet one testable assertion.
-6. **Flow Diagram:** a per-story Mermaid flowchart of THIS story's workflow → rendered PNG → embedded (Step 4).
-7. **Mapped Test Cases:** table `TC ID | Type | Test Title | Expected Result`. `TC-NNN` sequential across the whole doc; `Type` ∈ {Positive, Negative, Edge}; cover happy-path + failure + boundary; every acceptance-criteria group represented by ≥1 test case.
+6. **Flow Diagram** (the LAST-but-one section; the diagram carries its OWN title banner INSIDE the image — see Step 4d — so there is NO external `Flow Diagram:` markdown label and NO footer label): a per-story Mermaid flowchart of THIS story's workflow → rendered PNG (with in-image title) → embedded (Step 4).
+7. **Mapped Test Cases** (the LAST section of every story — each story ENDS here): a colored table `TC ID | Type | Test Title | Expected Result` (styling in Step 4e). `TC-NNN` sequential across the whole doc; `Type` ∈ {Positive, Negative, Edge}; cover happy-path + failure + boundary; every acceptance-criteria group represented by ≥1 test case.
+
+**Pagination (MANDATORY — hard rule, exactly as stated):**
+- **Each Epic (`EP-NN`) starts a NEW PAGE** (page-break BEFORE the epic heading).
+- **The FIRST story of that epic flows on the SAME page** as the epic heading (no break between them).
+- **Each SUBSEQUENT story in the same epic starts a NEW PAGE** (page-break BEFORE that story's `PREFIX-NNN` heading).
+- Because every story ENDS with its Mapped Test Cases table, a page thus contains exactly one story (or epic-heading + first story). Enforce in `.docx` via page-break-before on epic headings and on every non-first story heading.
 
 **Heading placement + no orphans (MANDATORY layout rules):**
-- **Each section label sits ABOVE the content it introduces — never below it.** The `Flow Diagram:` label immediately PRECEDES its image; `Mapped Test Cases:` immediately PRECEDES its table; `Workflow:` precedes its steps. A label rendered after/below its block is a defect. In markdown, ensure the label line comes on the line(s) directly before the block with no intervening content.
-- **Headings must NOT be orphaned across a page break.** A section label (`Flow Diagram:`, `Mapped Test Cases:`, a story `PREFIX-NNN` title, an epic `EP-NN`) must stay on the same page as at least the first line of its content (keep-with-next). To enforce this in the `.docx` conversion, apply pandoc's page-break control: use a paragraph style / raw-openxml `keepNext` on heading paragraphs, OR insert an explicit page break BEFORE a heading that would otherwise strand at a page bottom, so the heading travels with its content. Never leave a heading alone at the foot of a page with its table/diagram/steps starting on the next.
+- **Each section label sits ABOVE the content it introduces — never below it.** `Mapped Test Cases:` immediately PRECEDES its table; `Workflow:` precedes its steps; `Acceptance Criteria:` precedes its bullets. A label rendered after/below its block is a defect. (The Flow Diagram is the EXCEPTION — it has NO external label; its title is baked into the image, Step 4d.)
+- **Headings must NOT be orphaned across a page break.** A section label (`Mapped Test Cases:`, a story `PREFIX-NNN` title, an epic `EP-NN`) must stay on the same page as at least the first line of its content (keep-with-next). Enforce with `keepNext` on heading paragraphs in the `.docx` conversion. With the pagination rule above (one story per page), orphaning is largely prevented structurally, but keep-with-next remains the backstop.
 
 **No confabulation** (`feedback_no_confabulated_examples`): every story, workflow step, and test case must trace to something in the actual input source. If the source is silent on a needed detail, mark it a `[TODO: confirm with client]` — never invent product specifics.
 
@@ -71,18 +77,16 @@ classDef newfeat   fill:#e2f0fb,stroke:#5b9bd5,color:#1f4e79,stroke-dasharray:4
 
 The whole diagram MUST fit inside the page's visible area. **Compare aspect ratios first, then clamp ONLY the constraining dimension** — this is the standard "contain" fit; it guarantees no clipping and no distortion. Do NOT eyeball it or rely on layout luck.
 
-**Page dimensions** (the visible printable area) default to **US Letter portrait content box ≈ 6.5in × 9in** (W×H, i.e. 8.5×11 minus 1in margins) unless the deliverable specifies otherwise.
-
-**⚠️ RESERVE LABEL SPACE — critical.** Every diagram has a heading label ABOVE it (`Flow Diagram:`) that must sit on the SAME page (4b keep-with-next). If the image is set to the FULL page height, there is no room for the label → keep-with-next pushes the whole image to the next page (the Newman failure). So the height the image may occupy is **`avail_height = page_height − label_reserve`**, where `label_reserve ≈ 0.5in` (heading line + gap). Use `avail_height` — NOT the full `page_height` — as the height constraint. Width is unaffected (`avail_width = page_width`). `page_AR = avail_width / avail_height`.
+**Page dimensions** (the visible printable area) default to **US Letter portrait content box ≈ 6.5in × 9in** (W×H, i.e. 8.5×11 minus 1in margins) unless the deliverable specifies otherwise. Because the diagram carries its OWN title banner INSIDE the image (Step 4d) — there is NO external label above it — the image may use the FULL page box: `avail_width = page_width`, `avail_height = page_height`. `page_AR = avail_width / avail_height`. (The one-story-per-page pagination rule means the diagram owns its page.)
 
 **Algorithm — run per rendered diagram:**
 1. **Render** the Mermaid to PNG (Step 4c), then **measure its actual pixel dimensions** `img_w × img_h` (e.g. via `sips -g pixelWidth -g pixelHeight <png>` on macOS, or `mmdc` output metadata). `img_AR = img_w / img_h`.
-2. **Compute both aspect ratios** against the **label-reserved** page box — compare SHAPES, not sizes yet.
+2. **Compute both aspect ratios** — compare SHAPES, not sizes yet.
 3. **Clamp the constraining dimension:**
-   - **If `img_AR > page_AR`** (image is *wider* than the available box) → **width is the constraint → set embedded `width = avail_width` (= page_width)** (height scales proportionally, lands ≤ avail_height). *Example: a 5-wide × 4-tall image → set width = page width.*
-   - **If `img_AR < page_AR`** (image is *taller* than the available box) → **height is the constraint → set embedded `height = avail_height` (= page_height − label_reserve, NOT full page height)** (width scales proportionally). This is what leaves room for the label above. *Example: a 2-wide × 4-tall image → set height = page_height − 0.5in.*
+   - **If `img_AR > page_AR`** (image is *wider* than the page box) → **width is the constraint → set embedded `width = avail_width` (= page_width)** (height scales proportionally, lands ≤ avail_height). *Example: a 5-wide × 4-tall image → set width = page width.*
+   - **If `img_AR < page_AR`** (image is *taller* than the page box) → **height is the constraint → set embedded `height = avail_height` (= page_height)** (width scales proportionally). *Example: a 2-wide × 4-tall image → set height = page height.*
    - **If equal** → either works; set width = avail_width.
-4. **Embed at that ONE clamped dimension** so the renderer scales the other proportionally. In markdown, use an HTML `<img>` with only the clamped side set (e.g. `<img src="media/<name>.png" width="…" />` or `height="…"`) — never set both (that distorts). For `.docx`, pandoc honors the single dimension. The label + image together now fit on one page.
+4. **Embed at that ONE clamped dimension** so the renderer scales the other proportionally. In markdown, use an HTML `<img>` with only the clamped side set (e.g. `<img src="media/<name>.png" width="…" />` or `height="…"`) — never set both (that distorts). For `.docx`, pandoc honors the single dimension.
 
 **Layout still matters as an INPUT to the ratio** (not a substitute for it): choose `flowchart LR` for long linear flows and `TD` for short ones so the rendered `img_AR` is closer to the page shape *before* clamping — this maximizes the final on-page size. But the aspect-ratio clamp above is what GUARANTEES the fit; the direction choice only optimizes how much of the page it fills.
 
@@ -94,9 +98,20 @@ Never ship a diagram wider or taller than the page (`feedback_no_silent_degradat
 2. Render each to PNG: `mmdc -i <src>.mmd -o share/media/<name>.png --width 1600 --backgroundColor white --scale 2 --padding 20` (Mermaid CLI `@mermaid-js/mermaid-cli`; fall back to `npx @mermaid-js/mermaid-cli …`).
 3. **If `mmdc` is unavailable → HALT** and tell the user to install it (`npm i -g @mermaid-js/mermaid-cli`). Do NOT silently ship raw Mermaid where an embedded image is expected (`feedback_no_silent_degradation`).
 4. **Measure + clamp per the 4b aspect-ratio algorithm:** read the rendered PNG's pixel `img_w × img_h` (`sips -g pixelWidth -g pixelHeight share/media/<name>.png`), compute `img_AR` vs `page_AR`, and pick the ONE clamped dimension (width=page_width if wider, else height=page_height).
-5. Embed each rendered PNG at that clamped dimension using an HTML `<img>` with only the constraining side set — e.g. `<img src="media/<name>.png" width="6.5in" />` OR `<img src="media/<name>.png" height="9in" />` (never both). Place it at the `Flow Diagram:` / §1 position.
+5. Embed each rendered PNG at that clamped dimension using an HTML `<img>` with only the constraining side set — e.g. `<img src="media/<name>.png" width="6.5in" />` OR `<img src="media/<name>.png" height="9in" />` (never both). Place it directly where the story's diagram belongs — with NO external `Flow Diagram:` label and NO footer label (the title is in the image, Step 4d).
 6. Keep the `.mmd` source (editable, version-controllable) alongside the PNG.
 
+### 4d. In-image title banner (MANDATORY — replaces the external Flow Diagram label)
+
+Each per-story diagram carries its OWN title INSIDE the rendered image — a filled banner at the TOP showing the story id + title (matching the sample: `NWMN-003` bold on line 1, the story title on line 2, on a light-purple fill). This lets the doc DROP the external `Flow Diagram:` markdown label AND any footer label. Implement as the first node(s) of the flowchart, styled as the banner (a full-width `screen`-class node with the two lines), OR via a mermaid `title`/subgraph header styled to match. Font: bold id line + regular title line, dark-purple text (`#2d2160`) on light-purple fill (`#ece9fb`) — the `screen` classDef. The app-flow chart (§1) gets a matching banner with the product name.
+
+### 4e. Mapped Test Cases table coloring (MANDATORY)
+
+The test-case table is COLORED, not plain (matching the sample):
+- **Header row:** white bold text on a **purple gradient / solid purple fill** (`#7c5cfc`-ish), all four columns.
+- **`Type` cell tinted by value:** **Positive → green** (`#e6f4ea` fill, green text) · **Negative → peach/orange** (`#fdecd8` fill, amber text) · **Edge → blue** (`#e2eefb` fill, blue text). Only the Type cell is tinted; other cells stay white with normal text.
+- Markdown tables can't carry cell fills, so for the `.docx` this coloring is applied at conversion (a pandoc pipeline / post-process on the table), OR the table is authored as raw HTML with inline styles that pandoc converts to Word table shading. Keep the plain-markdown table as the editable source; apply the color styling in the rendered/delivered output.
+
 ## Step 5: Assemble + Deliver
 
 1. Assemble front matter (product, "Prepared by Tekyz Inc.", version, source-of-truth note; SAMPLE disclaimer only if illustrative) + §1 + §2 + §3.

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.13",
+  "version": "4.20.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

@@ -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.