@tekyzinc/gsd-t 4.19.14 → 4.20.11

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

@@ -0,0 +1,281 @@
+"use strict";
+
+// bin/gsd-t-logging-scaffolder.cjs
+//
+// M100-D1 — the stack-adaptive storage SCAFFOLDER that STOPS for human
+// approval and NEVER silently picks a logging backend. Owns the sole
+// init-scaffold seam consumed by d2 (trace machinery), d4 (audit machinery),
+// and d5 (migrate-logging / defaults pilot).
+//
+// Contract: .gsd-t/contracts/logging-scaffold-seam-contract.md (1.0.0)
+//
+// scaffoldLogging({ projectDir, stack, approve }) -> envelope
+//   Without `approve`:
+//     { status: "PAUSED", alternatives: [...], resumeToken }
+//     — NEVER writes a backend, NEVER returns a `backend` value.
+//   With `approve` (first-time) or a valid recorded choice already on disk:
+//     { backend, traceSink, auditSink, recordedAt, resumeToken }
+//
+// Zero external npm runtime deps — fs/path/crypto only.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const VALID_BACKENDS = ["db-table", "local-sqlite", "local-jsonl"];
+
+const CHOICE_DIR = ".gsd-t";
+const CHOICE_FILE = "logging-scaffold-choice.json";
+
+// ─── Stack detection ─────────────────────────────────────────────────────────
+//
+// has-DB (package.json deps signal a DB client, or a DB config file/env is
+// present) -> table-backed alternative is offered.
+// no-server/desktop -> local store alternatives (sqlite | flat-file jsonl),
+// with sqlite flagged as the recommended default for audit queryability.
+
+const DB_DEP_SIGNATURES = [
+  "pg", "postgres", "postgresql", "mysql", "mysql2", "mongodb", "mongoose",
+  "sequelize", "prisma", "typeorm", "knex", "drizzle-orm", "better-sqlite3",
+  "sqlite3", "@supabase/supabase-js", "planetscale",
+];
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function detectStack(projectDir) {
+  const pkgPath = path.join(projectDir, "package.json");
+  const pkg = readJsonSafe(pkgPath) || {};
+  const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+  const depNames = Object.keys(deps).map((d) => d.toLowerCase());
+
+  const hasDb = DB_DEP_SIGNATURES.some((sig) =>
+    depNames.some((d) => d === sig || d.includes(sig))
+  );
+
+  // Server signal: a "start"/"dev" script implies a running server process
+  // that could own a DB connection; a "bin" field implies a CLI/desktop tool.
+  const scripts = pkg.scripts || {};
+  const hasServerScript = !!(scripts.start || scripts.dev || scripts.serve);
+  const isCliOrDesktop = !!pkg.bin || !hasServerScript;
+
+  return {
+    hasDb,
+    isCliOrDesktop,
+    detectedFrom: pkgPath,
+  };
+}
+
+// ─── Alternatives ────────────────────────────────────────────────────────────
+//
+// MUST present REAL alternatives — never silently pick. SQLite is flagged
+// over flat-file (jsonl) for audit queryability per contract §Detect.
+
+function buildAlternatives(stack) {
+  const alternatives = [];
+
+  if (stack.hasDb) {
+    alternatives.push({
+      backend: "db-table",
+      label: "Database table (uses the project's existing DB connection)",
+      recommended: true,
+      reason: "Project already has a database dependency — reuse it for queryable trace/audit rows.",
+    });
+  }
+
+  alternatives.push({
+    backend: "local-sqlite",
+    label: "Local SQLite file (.gsd-t/logging.db)",
+    recommended: !stack.hasDb,
+    reason: "Queryable via SQL — required for the audit admin query surface. Recommended over flat-file when no server DB is present.",
+  });
+
+  alternatives.push({
+    backend: "local-jsonl",
+    label: "Local flat-file JSONL (.gsd-t/logging.jsonl)",
+    recommended: false,
+    reason: "Simplest option, but NOT queryable — flagged below SQLite for audit use cases that need query support.",
+  });
+
+  return alternatives;
+}
+
+// ─── Recorded-choice persistence ────────────────────────────────────────────
+
+function choiceFilePath(projectDir) {
+  return path.join(projectDir, CHOICE_DIR, CHOICE_FILE);
+}
+
+function isValidRecordedChoice(record) {
+  if (!record || typeof record !== "object") return false;
+  if (typeof record.backend !== "string") return false;
+  if (!VALID_BACKENDS.includes(record.backend)) return false;
+  if (typeof record.recordedAt !== "string" || !record.recordedAt) return false;
+  if (typeof record.resumeToken !== "string" || !record.resumeToken) return false;
+  return true;
+}
+
+// Reads + validates the recorded choice. A corrupt/partial/truncated file,
+// or a record whose `backend` is out of the fixed enum, is treated as
+// "no recorded choice" — never crashes, never silently proceeds with a bad
+// value. See M100 pre-mortem FINDING 7.
+function readRecordedChoice(projectDir) {
+  const filePath = choiceFilePath(projectDir);
+  if (!fs.existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch (_) {
+    return null;
+  }
+  let record;
+  try {
+    record = JSON.parse(raw);
+  } catch (_) {
+    // Corrupt/truncated JSON — treated as unrecorded, never crashes.
+    return null;
+  }
+  if (!isValidRecordedChoice(record)) return null;
+  return record;
+}
+
+function writeRecordedChoice(projectDir, record) {
+  const dir = path.join(projectDir, CHOICE_DIR);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const filePath = choiceFilePath(projectDir);
+  fs.writeFileSync(filePath, JSON.stringify(record, null, 2) + "\n", "utf8");
+}
+
+// ─── Doc-record writer ──────────────────────────────────────────────────────
+//
+// Records the chosen backend into the project's CLAUDE.md (preferred) or
+// docs/infrastructure.md (fallback) so the choice is human-visible without
+// re-reading the raw JSON record.
+
+const DOC_MARKER_START = "<!-- gsd-t-logging-scaffold:start -->";
+const DOC_MARKER_END = "<!-- gsd-t-logging-scaffold:end -->";
+
+function docBlock(envelope) {
+  return [
+    DOC_MARKER_START,
+    "## Logging Backend (M100)",
+    "",
+    `**Backend:** \`${envelope.backend}\``,
+    `**Recorded:** ${envelope.recordedAt}`,
+    `**Trace sink:** ${envelope.traceSink.kind} (${envelope.traceSink.path || envelope.traceSink.table})`,
+    `**Audit sink:** ${envelope.auditSink.kind} (${envelope.auditSink.path || envelope.auditSink.table}) — queryable: ${envelope.auditSink.kind !== "flat-file"}`,
+    "",
+    DOC_MARKER_END,
+  ].join("\n");
+}
+
+function writeChoiceToProjectDocs(projectDir, envelope) {
+  const candidates = [
+    path.join(projectDir, "CLAUDE.md"),
+    path.join(projectDir, "docs", "infrastructure.md"),
+  ];
+  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;
+}
+
+// ─── Seam envelope builder ──────────────────────────────────────────────────
+
+function sinkFor(backend, kind) {
+  // kind: "trace" | "audit"
+  if (backend === "db-table") {
+    return { kind: "db-table", table: kind === "trace" ? "gsdt_trace_log" : "gsdt_audit_log" };
+  }
+  if (backend === "local-sqlite") {
+    return { kind: "sqlite", path: `.gsd-t/${kind}.db` };
+  }
+  // local-jsonl
+  return { kind: "flat-file", path: `.gsd-t/${kind}.jsonl` };
+}
+
+function buildEnvelope(backend, recordedAt, resumeToken) {
+  return {
+    backend,
+    traceSink: sinkFor(backend, "trace"),
+    auditSink: sinkFor(backend, "audit"),
+    recordedAt,
+    resumeToken,
+  };
+}
+
+function makeResumeToken(projectDir) {
+  return crypto.createHash("sha256").update(path.resolve(projectDir)).digest("hex").slice(0, 16);
+}
+
+// ─── The seam entry point ───────────────────────────────────────────────────
+
+function scaffoldLogging({ projectDir, stack, approve, resumeToken } = {}) {
+  if (!projectDir) throw new Error("scaffoldLogging: projectDir is required");
+
+  const detectedStack = stack || detectStack(projectDir);
+  const token = resumeToken || makeResumeToken(projectDir);
+
+  // Deterministic resume: if a VALID recorded choice already exists for this
+  // token, short-circuit — never re-prompt. Corrupt/partial/unmatched/
+  // out-of-enum records all fall through to PAUSE (M100 pre-mortem FINDING 7).
+  const recorded = readRecordedChoice(projectDir);
+  if (recorded && recorded.resumeToken === token) {
+    return buildEnvelope(recorded.backend, recorded.recordedAt, recorded.resumeToken);
+  }
+
+  if (!approve) {
+    // NEVER silently pick. STOP for human approval — the ONE sanctioned pause.
+    return {
+      status: "PAUSED",
+      alternatives: buildAlternatives(detectedStack),
+      resumeToken: token,
+    };
+  }
+
+  if (!VALID_BACKENDS.includes(approve)) {
+    throw new Error(
+      `scaffoldLogging: approve must be one of ${VALID_BACKENDS.join(", ")}, got "${approve}"`
+    );
+  }
+
+  const recordedAt = new Date().toISOString();
+  const record = { backend: approve, recordedAt, resumeToken: token };
+  writeRecordedChoice(projectDir, record);
+
+  const envelope = buildEnvelope(approve, recordedAt, token);
+  writeChoiceToProjectDocs(projectDir, envelope);
+
+  return envelope;
+}
+
+module.exports = {
+  scaffoldLogging,
+  detectStack,
+  buildAlternatives,
+  readRecordedChoice,
+  isValidRecordedChoice,
+  VALID_BACKENDS,
+};

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

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GSD-T Brownfield Logging Migration (M100-D5-T2).
+ *
+ * Scaffolds the two framework-default logging streams (trace + audit) into
+ * an EXISTING project, ADDITIVELY — every pre-existing project file is left
+ * byte-for-byte unchanged; only NEW logging files are added.
+ *
+ * Dispatch seam: invoked via `bin/gsd-t.js` `case "migrate-logging"`, wired
+ * by d1 (the sole editor of that file) on d5's behalf. See
+ * .gsd-t/contracts/logging-scaffold-seam-contract.md §Ownership boundary.
+ *
+ * Consumes:
+ *   - bin/gsd-t-logging-scaffolder.cjs  (d1) — scaffoldLogging() storage seam
+ *   - templates/logging/trace-module.template.ts   (d2)
+ *   - templates/logging/audit-module.template.ts   (d4)
+ *   - bin/gsd-t-trace-distill.cjs   (d2) — distillTraceCategories()
+ *   - bin/gsd-t-audit-distill.cjs   (d4) — distillAuditActions()
+ * Publishes: .gsd-t/contracts/logging-schema-distillation-contract.md
+ *
+ * Hard rule (Destructive Action Guard / M100 pre-mortem): this module MUST
+ * NEVER overwrite, modify, or delete a file that already exists in the
+ * target project. It only creates files that are ABSENT. Every write is
+ * guarded by an existence check first.
+ *
+ * Exports:
+ *   migrateLogging(projectDir, opts) -> {
+ *     ok: boolean,
+ *     created: string[],       // relative paths of NEW files written
+ *     skipped: string[],       // relative paths that already existed (untouched)
+ *     dispatchedVia: "bin/gsd-t.js case \"migrate-logging\"" (informational),
+ *     scaffold: <seam envelope | PAUSED envelope>,
+ *   }
+ *   run(argv) -> Promise<void>   // CLI entry, used by the bin/gsd-t.js dispatch case
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { scaffoldLogging } = require('./gsd-t-logging-scaffolder.cjs');
+const { distillTraceCategories } = require('./gsd-t-trace-distill.cjs');
+const { distillAuditActions } = require('./gsd-t-audit-distill.cjs');
+
+const TRACE_TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'logging', 'trace-module.template.ts');
+const AUDIT_TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'logging', 'audit-module.template.ts');
+
+const TRACE_DEST_REL = path.join('src', 'logging', 'trace.ts');
+const AUDIT_DEST_REL = path.join('src', 'logging', 'audit.ts');
+const SCHEMA_DEST_REL = path.join('.gsd-t', 'logging-schema.json');
+
+/**
+ * Copies `srcPath` to `<projectDir>/<destRel>` ONLY IF the destination does
+ * NOT already exist. Never overwrites. Returns 'created' | 'skipped'.
+ */
+function copyIfAbsent(projectDir, destRel, srcPath) {
+  const destAbs = path.join(projectDir, destRel);
+  if (fs.existsSync(destAbs)) {
+    return 'skipped';
+  }
+  const destDir = path.dirname(destAbs);
+  fs.mkdirSync(destDir, { recursive: true });
+  const content = fs.readFileSync(srcPath, 'utf8');
+  fs.writeFileSync(destAbs, content, 'utf8');
+  return 'created';
+}
+
+/**
+ * Writes the distilled per-project schema (trace categories + audit actions)
+ * to `.gsd-t/logging-schema.json`, ONLY IF that file does not already exist.
+ * Distills from `planPath` when provided and present; an absent/omitted plan
+ * yields empty category/action lists (never confabulated) rather than an error.
+ */
+function writeDistilledSchemaIfAbsent(projectDir, planPath) {
+  const destAbs = path.join(projectDir, SCHEMA_DEST_REL);
+  if (fs.existsSync(destAbs)) {
+    return { status: 'skipped', categories: [], actions: [] };
+  }
+
+  let categories = [];
+  let actions = [];
+  if (planPath && fs.existsSync(planPath)) {
+    categories = distillTraceCategories(planPath).categories;
+    actions = distillAuditActions(planPath).actions;
+  }
+
+  const dir = path.dirname(destAbs);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    destAbs,
+    JSON.stringify({ categories, actions, distilledFrom: planPath || null }, null, 2) + '\n',
+    'utf8'
+  );
+  return { status: 'created', categories, actions };
+}
+
+/**
+ * migrateLogging(projectDir, opts) -> result
+ *
+ * opts:
+ *   planPath  - optional path to the project's own plan, used to distill the
+ *               per-project trace category / audit action schema. Absent ⇒
+ *               empty schema (a question, never a confabulated guess).
+ *   approve   - forwarded to scaffoldLogging(); when omitted the storage
+ *               seam PAUSES for human approval (never silently picks) unless
+ *               a valid choice is already recorded for this project.
+ *
+ * ADDITIVE / NON-DESTRUCTIVE: every write is preceded by an existence check;
+ * a file that already exists in the target project is left byte-for-byte
+ * untouched (recorded in `skipped`, never in `created`).
+ */
+function migrateLogging(projectDir, opts) {
+  opts = opts || {};
+  if (!projectDir || typeof projectDir !== 'string') {
+    throw new Error('migrateLogging: projectDir is required');
+  }
+  if (!fs.existsSync(projectDir)) {
+    throw new Error(`migrateLogging: projectDir does not exist: ${projectDir}`);
+  }
+
+  const created = [];
+  const skipped = [];
+
+  const traceResult = copyIfAbsent(projectDir, TRACE_DEST_REL, TRACE_TEMPLATE_PATH);
+  (traceResult === 'created' ? created : skipped).push(TRACE_DEST_REL);
+
+  const auditResult = copyIfAbsent(projectDir, AUDIT_DEST_REL, AUDIT_TEMPLATE_PATH);
+  (auditResult === 'created' ? created : skipped).push(AUDIT_DEST_REL);
+
+  const schemaResult = writeDistilledSchemaIfAbsent(projectDir, opts.planPath);
+  (schemaResult.status === 'created' ? created : skipped).push(SCHEMA_DEST_REL);
+
+  // Storage seam — d1's scaffolder. Deterministic-resume + human-pause
+  // semantics are entirely owned by scaffoldLogging(); this module never
+  // second-guesses or silently forces a backend.
+  const scaffold = scaffoldLogging({ projectDir, approve: opts.approve });
+
+  return {
+    ok: true,
+    created,
+    skipped,
+    dispatchedVia: 'bin/gsd-t.js case "migrate-logging" (wired by d1 — see logging-scaffold-seam-contract.md)',
+    scaffold,
+  };
+}
+
+module.exports = {
+  migrateLogging,
+  run,
+  // Test surface:
+  copyIfAbsent,
+  writeDistilledSchemaIfAbsent,
+  TRACE_DEST_REL,
+  AUDIT_DEST_REL,
+  SCHEMA_DEST_REL,
+};
+
+// ── CLI ──────────────────────────────────────────────────────────────────
+//
+// Usage: gsd-t migrate-logging <projectDir> [--plan <path>] [--approve <backend>]
+//
+// Invoked by bin/gsd-t.js's `case "migrate-logging"` dispatch as
+// `run(args.slice(1))` — argv here EXCLUDES the leading "migrate-logging"
+// subcommand token.
+
+function _parseArgv(argv) {
+  const out = { projectDir: null, planPath: null, approve: undefined };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--plan') out.planPath = argv[++i] || null;
+    else if (a === '--approve') out.approve = argv[++i];
+    else positional.push(a);
+  }
+  out.projectDir = positional[0] || null;
+  return out;
+}
+
+async function run(argv) {
+  const args = _parseArgv(argv || []);
+  if (!args.projectDir) {
+    process.stderr.write(
+      'usage: gsd-t migrate-logging <projectDir> [--plan <path-to-plan.md>] [--approve <db-table|local-sqlite|local-jsonl>]\n'
+    );
+    process.exitCode = 64;
+    return;
+  }
+
+  const result = migrateLogging(args.projectDir, { planPath: args.planPath, approve: args.approve });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  if (result.scaffold && result.scaffold.status === 'PAUSED') {
+    // Storage choice not yet approved — informational exit, not a failure.
+    process.exitCode = 0;
+  }
+}
+
+if (require.main === module) {
+  run(process.argv.slice(2)).catch((e) => {
+    process.stderr.write(String((e && e.message) || e) + '\n');
+    process.exit(1);
+  });
+}

package/bin/gsd-t-trace-distill.cjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GSD-T Trace-Half Category Distiller (M100 D2).
+ *
+ * Distills the concrete trace CATEGORY set from a project's own PLAN —
+ * NEVER confabulates a category absent from the plan (feedback_no_confabulated_examples).
+ * Emits categories as DATA, never baked into the envelope gate (d3 stays
+ * value-blind — the gate checks presence+type of `category`, never a value).
+ *
+ * Contract: .gsd-t/contracts/logging-schema-distillation-contract.md v1.0.0
+ * Consumed contract: .gsd-t/contracts/trace-logging-contract.md
+ *
+ * Shares NO file with the audit-half distiller (bin/gsd-t-audit-distill.cjs,
+ * owned by d4) — mechanizes no-collapse by construction.
+ *
+ * Exports:
+ *   distillTraceCategories(planPath) -> { categories: [{ category, source }] }
+ */
+
+const fs = require('fs');
+
+// ── Integration-point signatures ────────────────────────────────────────────
+//
+// A trace-worthy operation is a concrete REST/JSON/external-call integration
+// point named in the project's plan (per logging-schema-distillation-contract
+// §UMI pilot grounding: Grain / Airtable / Anthropic / Apify for UMI).
+//
+// This is a STRUCTURAL extraction, not a closed list: a hardcoded allowlist
+// would silently yield ZERO categories for a plan naming services outside the
+// list (e.g. Plaid/Shopify/QuickBooks), violating the project doctrine against
+// hardcoding a finite list for an open category. So the primary path greps
+// the plan text for integration-point CUES — REST/API/webhook/fetch/axios/
+// HTTP-client mentions, `*.com`-shaped service hostnames, and
+// `process.env.*_API_KEY`-shaped env vars — and grounds the emitted category
+// in the nearest proper-noun token on the matched line (mirroring the audit
+// distiller's grounded-extraction approach: never invent, always cite a
+// source line). KNOWN_INTEGRATION_SIGNATURES is kept only as a recognizer
+// HINT (checked first, since a known name is unambiguous) — never as the
+// sole gate for what counts as trace-worthy.
+
+const KNOWN_INTEGRATION_SIGNATURES = [
+  'Grain',
+  'Airtable',
+  'Anthropic',
+  'Apify',
+  'Slack',
+  'Stripe',
+  'Twilio',
+  'SendGrid',
+  'Softr',
+];
+
+// Structural cues marking a plan line as naming a concrete external
+// integration point — never a business-domain word list, purely syntactic.
+// Each cue is captured so the service token can be extracted RELATIVE to the
+// cue's own position, not just "first capitalized word on the line" (which
+// over-matches sentence-leading words like "We"/"Our"/"The").
+const INTEGRATION_CUE_RE =
+  /\b(?:REST|API|webhook|fetch|axios|HTTP client|Messages API|Files API)\b|[A-Za-z0-9-]+\.com\b|process\.env\.[A-Z0-9_]*_API_KEY\b/;
+
+const STOPWORDS = new Set([
+  'API', 'REST', 'HTTP', 'HTTPS', 'JSON', 'URL', 'ID', 'MCP', 'CLI', 'SOP',
+  'We', 'Our', 'The', 'This', 'That', 'A', 'An', 'It', 'They',
+]);
+
+/**
+ * Best-effort proper-noun token identifying the service named on a line that
+ * already matched INTEGRATION_CUE_RE — purely structural: looks at the
+ * capitalized word immediately BEFORE the cue match first (e.g. "Plaid API",
+ * "Shopify webhook"), falling back to immediately after (e.g. "REST client
+ * syncs QuickBooks"), then to the nearest non-stopword capitalized token
+ * anywhere on the line. Never a sentence-leading word like "We"/"The".
+ */
+function _extractServiceToken(line, cueMatch) {
+  const before = line.slice(0, cueMatch.index);
+  const after = line.slice(cueMatch.index + cueMatch[0].length);
+
+  const beforeTokens = before.match(/\b[A-Z][a-zA-Z0-9]*\b/g) || [];
+  for (let i = beforeTokens.length - 1; i >= 0; i--) {
+    if (!STOPWORDS.has(beforeTokens[i])) return beforeTokens[i];
+  }
+
+  const afterTokens = after.match(/\b[A-Z][a-zA-Z0-9]*\b/g) || [];
+  for (const t of afterTokens) {
+    if (!STOPWORDS.has(t)) return t;
+  }
+
+  const allTokens = line.match(/\b[A-Z][a-zA-Z0-9]*\b/g) || [];
+  for (const t of allTokens) {
+    if (!STOPWORDS.has(t)) return t;
+  }
+  return null;
+}
+
+/**
+ * Finds the first line in `lines` containing `needle` as a whole-word match,
+ * returning { lineNumber, text } or null if absent. Whole-word match avoids
+ * a substring false-positive (e.g. "Grainger" would not match "Grain").
+ */
+function findFirstMatchingLine(lines, needle) {
+  const re = new RegExp('\\b' + needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b');
+  for (let i = 0; i < lines.length; i++) {
+    if (re.test(lines[i])) {
+      return { lineNumber: i + 1, text: lines[i].trim() };
+    }
+  }
+  return null;
+}
+
+/**
+ * Distills the concrete trace CATEGORY set from a project plan file.
+ *
+ * @param {string} planPath - absolute or relative path to the project's plan
+ *   (e.g. docs/plan.md).
+ * @returns {{ categories: Array<{ category: string, source: string }> }}
+ *   `categories` is empty (never an error, never a confabulated placeholder)
+ *   when the plan has no trace-worthy operations. Each entry's `source` is
+ *   the grep-traceable plan line the category was distilled from.
+ */
+function distillTraceCategories(planPath) {
+  if (!planPath || typeof planPath !== 'string') {
+    throw new Error('distillTraceCategories: planPath is required');
+  }
+  if (!fs.existsSync(planPath)) {
+    throw new Error(`distillTraceCategories: plan not found at ${planPath}`);
+  }
+
+  const text = fs.readFileSync(planPath, 'utf8');
+  const lines = text.split(/\r?\n/);
+
+  const categories = [];
+  const seen = new Set();
+
+  // Pass 1 — known-service recognizer hint (unambiguous, checked first).
+  for (const signature of KNOWN_INTEGRATION_SIGNATURES) {
+    const match = findFirstMatchingLine(lines, signature);
+    if (match) {
+      categories.push({
+        category: signature,
+        source: `${planPath}:${match.lineNumber}: ${match.text}`,
+      });
+      seen.add(signature);
+    }
+  }
+
+  // Pass 2 — structural extraction over lines carrying an integration cue,
+  // for any named service NOT already covered by the known-list hint.
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const cueMatch = INTEGRATION_CUE_RE.exec(line);
+    if (!cueMatch) continue;
+    const token = _extractServiceToken(line, cueMatch);
+    if (!token || seen.has(token)) continue;
+    seen.add(token);
+    categories.push({
+      category: token,
+      source: `${planPath}:${i + 1}: ${line.trim()}`,
+    });
+  }
+
+  return { categories };
+}
+
+module.exports = {
+  distillTraceCategories,
+  KNOWN_INTEGRATION_SIGNATURES,
+};
+
+// ── CLI ──────────────────────────────────────────────────────────────────
+
+function _parseArgv(argv) {
+  const out = { planPath: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--plan') out.planPath = argv[++i] || null;
+  }
+  return out;
+}
+
+if (require.main === module) {
+  const args = _parseArgv(process.argv.slice(2));
+  if (!args.planPath) {
+    process.stderr.write('usage: gsd-t-trace-distill.cjs --plan <path-to-plan.md>\n');
+    process.exit(2);
+  }
+  try {
+    const result = distillTraceCategories(args.planPath);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(JSON.stringify({ error: String((err && err.message) || err) }, null, 2) + '\n');
+    process.exit(1);
+  }
+}

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

@@ -305,6 +305,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
+
   // secrets — gitleaks (PATH detection deferred to runtime)
   if (_hasOnPath('gitleaks')) {
     plan.push({