@tekyzinc/gsd-t 5.17.13 → 5.17.14

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.17.14] - 2026-09-03
+
+### Fixed — two more gate defects surfaced by TimeTracking (TD-395 round 2), plus a silent library and a crashing finalizer
+
+- `bin/gsd-t-fallback-detect.cjs`: `--scan` now covers only what git treats as the project's
+  source (tracked + untracked-not-ignored). Git-ignored files — where GSD-T's propagated
+  `bin/*.cjs` tools live — are skipped and counted (`skippedIgnored`); outside a git repo
+  nothing is filtered and the envelope says so (`gitSourceFilter:false`). The gate had
+  flagged GSD-T's own freshly-synced checker as the project's fallbacks.
+- `bin/gsd-t-logging-envelope-check.cjs`: `.gsd-t/logging-manifest.json` lets a project
+  DECLARE a stream the candidate paths cannot see (`{ "audit": { "module":
+  "server/src/audit.ts", "store": { "kind": "postgres", "table": "tb_audit_log" },
+  "retention": "indefinite" } }`). The declaration is checked — a missing path or malformed
+  file FAILs (`logging-manifest-invalid`); an external store's rows are not inspected offline
+  and that is reported in `notes`, with the module surface as the enforced evidence.
+- `bin/gsd-t-migrate-logging.cjs`: a declared stream is skipped (reported under `declared`),
+  so declaring an existing audit never scaffolds a second audit module beside it.
+- `bin/gsd-t-file-disjointness.cjs`: run directly it produced no output and exit 0, which a
+  partition finalizer read as a clean check. It now exits 64 and names `gsd-t parallel --dry-run`.
+- Contract `logging-verify-gate-contract.md` §discovery (0), `CLAUDE-global.md`,
+  `commands/gsd-t-migrate-logging.md` rippled. 12 tests.
+- `/cpua` now verifies the global install advanced ON DISK and halts if not — the 5.17.13
+  release saw `npm install -g` report success while leaving the old version in place.
+
+Also: M115 PLANNED (25 atomic tasks, headline bound, two pre-mortem findings closed). Not built.
+
 ## [5.17.13] - 2026-09-03
 
 ### Fixed — the verify gate failed projects for GSD-T's own gaps (TD-395), and a lost finalizer crashed the phase workflow

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.17.13** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.17.14** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-fallback-detect.cjs

@@ -461,6 +461,21 @@ function scanPlan(text, file) {
 
 // ─── Directory walk ─────────────────────────────────────────────────────────
 
+// The set of repo-relative paths git treats as the project's source: tracked
+// plus untracked-not-ignored. Returns null when this is not a git repo or git
+// is unavailable — the caller then scans everything and REPORTS the absence.
+function gitSourceSet(projectDir) {
+  try {
+    const { execFileSync } = require("child_process");
+    const out = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+      cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024,
+    });
+    return new Set(out.split("\0").filter(Boolean));
+  } catch (_) {
+    return null;
+  }
+}
+
 function walk(dir, out, root) {
   let entries;
   try {
@@ -512,6 +527,8 @@ function main() {
 
   let findings = [];
   let scanned = 0;
+  let gitSourceFilter = false;
+  let skippedIgnored = 0;
 
   try {
     if (args.plan) {
@@ -521,7 +538,18 @@ function main() {
     } else if (args.scan) {
       const files = [];
       walk(projectDir, files, projectDir);
-      for (const f of files) {
+      // Only the project's OWN source is the project's to answer for. In a git
+      // repo that is: tracked files plus untracked files git does not ignore.
+      // Git-ignored files are not the project's code — GSD-T's propagated
+      // bin/*.cjs tools live there (TimeTracking, 2026-09-03: the gate flagged
+      // the freshly-synced logging checker, GSD-T's own code, as the project's
+      // fallbacks). Outside a git repo nothing is filtered, and the envelope
+      // says so (`gitSourceFilter:false`) rather than pretending.
+      const gitSource = gitSourceSet(projectDir);
+      gitSourceFilter = gitSource !== null;
+      const inScope = gitSource ? files.filter((f) => gitSource.has(path.relative(projectDir, f).replace(/\\/g, "/"))) : files;
+      skippedIgnored = files.length - inScope.length;
+      for (const f of inScope) {
         try {
           findings.push(...scanText(fs.readFileSync(f, "utf8"), path.relative(projectDir, f)));
           scanned++;
@@ -599,6 +627,8 @@ function main() {
     ok: unapproved.length === 0,
     exitCode: unapproved.length === 0 ? EXIT_CLEAN : EXIT_FOUND,
     filesScanned: scanned,
+    gitSourceFilter,
+    skippedIgnored,
     found: findings.length,
     preExisting,
     approved,

package/bin/gsd-t-file-disjointness.cjs

@@ -612,3 +612,14 @@ module.exports = {
   _resolveTouches: resolveTouches,
   _gitHistoryTouches: gitHistoryTouches,
 };
+
+// This file is a LIBRARY. Invoked directly it used to exit 0 with no output at all,
+// and a partition finalizer (M115, 2026-09-03) read that silence as "no collisions".
+// Silence is not a pass. The CLI surface is `gsd-t parallel --dry-run` (parallel-cli.cjs).
+if (require.main === module) {
+  process.stderr.write(
+    "gsd-t-file-disjointness.cjs is a library, not a command — it checks nothing when run directly.\n" +
+    "Use: gsd-t parallel --dry-run   (bin/parallel-cli.cjs) to validate file-disjointness.\n"
+  );
+  process.exit(64);
+}

package/bin/gsd-t-logging-envelope-check.cjs

@@ -416,17 +416,95 @@ function _readModuleSurface(absModulePath) {
   };
 }
 
+// ── §declaration — .gsd-t/logging-manifest.json ──────────────────────────────
+//
+// A project whose streams live somewhere the candidate lists do not guess
+// (TimeTracking, 2026-09-03: audit = server/src/audit.ts → Postgres tb_audit_log)
+// DECLARES them here. A declaration beats guessing, and it is checked, never
+// trusted: a declared module path that does not exist is a FAIL, not a skip.
+//
+//   { "trace": { "module": "server/src/trace.ts", "store": "…" },
+//     "audit": { "module": "server/src/audit.ts",
+//                "store": { "kind": "postgres", "table": "tb_audit_log" },
+//                "retention": "indefinite" } }
+//
+// `store` is either a repo-relative path (JSON array or SQLite, inspected like a
+// discovered one) or an object naming an EXTERNAL store (kind + table). An
+// external store cannot be opened offline, so its rows are not inspected — that
+// is reported in `notes`, never hidden — and the enforceable evidence becomes the
+// module surface (append-only declared, no update/delete path, retention).
+// `retention: "indefinite"` declares a never-purged audit log; it satisfies the
+// retention rule by policy and is noted.
+function _readManifest(projectDir) {
+  const p = path.join(projectDir, '.gsd-t', 'logging-manifest.json');
+  if (!fs.existsSync(p)) return { present: false, manifest: null, error: null };
+  try {
+    const m = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!m || typeof m !== 'object' || Array.isArray(m)) return { present: true, manifest: null, error: 'manifest is not a JSON object' };
+    return { present: true, manifest: m, error: null };
+  } catch (err) {
+    return { present: true, manifest: null, error: 'manifest is not valid JSON: ' + (err && err.message ? err.message : String(err)) };
+  }
+}
+
+function _declaredStream(projectDir, manifest, stream, failures, notes) {
+  const out = { modulePath: null, storePath: null, externalStore: null, retentionIndefinite: false };
+  const d = manifest && manifest[stream];
+  if (!d) return out;
+  if (typeof d !== 'object' || Array.isArray(d)) {
+    failures.push({ rule: 'logging-manifest-invalid', stream, detail: 'manifest.' + stream + ' must be an object' });
+    return out;
+  }
+  if (d.module !== undefined) {
+    const abs = typeof d.module === 'string' && d.module ? path.join(projectDir, d.module) : null;
+    if (!abs || !fs.existsSync(abs)) {
+      failures.push({ rule: 'logging-manifest-invalid', stream, detail: 'declared ' + stream + ' module not found: ' + String(d.module) });
+    } else {
+      out.modulePath = abs;
+    }
+  }
+  if (d.store !== undefined) {
+    if (typeof d.store === 'string' && d.store) {
+      const abs = path.join(projectDir, d.store);
+      if (!fs.existsSync(abs)) failures.push({ rule: 'logging-manifest-invalid', stream, detail: 'declared ' + stream + ' store not found: ' + d.store });
+      else out.storePath = abs;
+    } else if (d.store && typeof d.store === 'object' && typeof d.store.kind === 'string' && d.store.kind) {
+      out.externalStore = d.store;
+      notes.push(stream + ' store declared as external (' + d.store.kind + (d.store.table ? ':' + d.store.table : '') + ') — live rows are not inspected offline; the module surface is the enforced evidence');
+    } else {
+      failures.push({ rule: 'logging-manifest-invalid', stream, detail: 'declared ' + stream + ' store must be a repo-relative path or {kind, table}' });
+    }
+  }
+  if (d.retention !== undefined) {
+    if (d.retention === 'indefinite') {
+      out.retentionIndefinite = true;
+      notes.push(stream + ' retention declared indefinite (never purged) — retention rule satisfied by policy');
+    } else {
+      failures.push({ rule: 'logging-manifest-invalid', stream, detail: 'retention may only be declared "indefinite"; anything else is read from the module surface' });
+    }
+  }
+  return out;
+}
+
 function checkLoggingEnvelopes(opts) {
   opts = opts || {};
   const projectDir = opts.projectDir || '.';
   const failures = [];
+  const notes = [];
+
+  // (0) Declaration file — checked before any path guessing.
+  const mf = _readManifest(projectDir);
+  if (mf.error) failures.push({ rule: 'logging-manifest-invalid', stream: 'both', detail: mf.error });
+  const declTrace = _declaredStream(projectDir, mf.manifest, 'trace', failures, notes);
+  const declAudit = _declaredStream(projectDir, mf.manifest, 'audit', failures, notes);
 
   // (i) Trace discovery — default for every project EXCEPT explicit opt-out
   // (M100 correction: stateless CLI/library class has no runtime data-flow to trace,
   // so a symmetric .gsd-t/trace-optout.json opt-out exists, mirroring audit's).
-  const traceModulePath = _firstExisting(projectDir, TRACE_MODULE_CANDIDATES);
-  const traceStorePath = _firstExisting(projectDir, TRACE_STORE_CANDIDATES);
-  const traceDbPath = _firstExisting(projectDir, TRACE_DB_CANDIDATES);
+  const traceModulePath = declTrace.modulePath || _firstExisting(projectDir, TRACE_MODULE_CANDIDATES);
+  const _declTraceIsDb = declTrace.storePath && /\.(db|sqlite)$/i.test(declTrace.storePath);
+  const traceStorePath = (declTrace.storePath && !_declTraceIsDb) ? declTrace.storePath : _firstExisting(projectDir, TRACE_STORE_CANDIDATES);
+  const traceDbPath = _declTraceIsDb ? declTrace.storePath : _firstExisting(projectDir, TRACE_DB_CANDIDATES);
   const traceRecords = traceStorePath ? _readJsonArrayIfExists(traceStorePath) : null;
   let traceOptOutRecord = null;
   const traceOptOutPath = path.join(projectDir, '.gsd-t', 'trace-optout.json');
@@ -434,7 +512,7 @@ function checkLoggingEnvelopes(opts) {
     if (fs.existsSync(traceOptOutPath)) traceOptOutRecord = JSON.parse(fs.readFileSync(traceOptOutPath, 'utf8'));
   } catch (_e) { traceOptOutRecord = null; }
 
-  if (!traceModulePath && !traceStorePath && !traceDbPath) {
+  if (!traceModulePath && !traceStorePath && !traceDbPath && !declTrace.externalStore) {
     if (!_isValidTraceOptOut(traceOptOutRecord)) {
       failures.push({ rule: 'trace-default-except-optout', stream: 'trace', detail: 'no trace module or store discoverable and no valid trace opt-out record' });
     }
@@ -467,11 +545,12 @@ function checkLoggingEnvelopes(opts) {
   // legitimately nothing to validate yet.
 
   // (ii) Audit discovery.
-  const auditModulePath = _firstExisting(projectDir, AUDIT_MODULE_CANDIDATES);
-  const auditStorePath = _firstExisting(projectDir, AUDIT_STORE_CANDIDATES);
-  const auditDbPath = _firstExisting(projectDir, AUDIT_DB_CANDIDATES);
+  const auditModulePath = declAudit.modulePath || _firstExisting(projectDir, AUDIT_MODULE_CANDIDATES);
+  const _declAuditIsDb = declAudit.storePath && /\.(db|sqlite)$/i.test(declAudit.storePath);
+  const auditStorePath = (declAudit.storePath && !_declAuditIsDb) ? declAudit.storePath : _firstExisting(projectDir, AUDIT_STORE_CANDIDATES);
+  const auditDbPath = _declAuditIsDb ? declAudit.storePath : _firstExisting(projectDir, AUDIT_DB_CANDIDATES);
   const auditRecords = auditStorePath ? _readJsonArrayIfExists(auditStorePath) : null;
-  const hasAuditStore = !!(auditModulePath || auditStorePath || auditDbPath);
+  const hasAuditStore = !!(auditModulePath || auditStorePath || auditDbPath || declAudit.externalStore);
 
   // (iii) Opt-out file.
   let optOutRecord = null;
@@ -517,10 +596,12 @@ function checkLoggingEnvelopes(opts) {
         exportsDelete: surface ? surface.exportsDelete : false,
         declaresAppendOnly: surface ? surface.declaresAppendOnly : false,
       }));
-      failures.push(..._checkRetentionConfigurable({
-        hardcoded: surface ? surface.retentionHardcoded : true,
-        configurable: surface ? surface.retentionConfigurable : false,
-      }));
+      if (!declAudit.retentionIndefinite) {
+        failures.push(..._checkRetentionConfigurable({
+          hardcoded: surface ? surface.retentionHardcoded : true,
+          configurable: surface ? surface.retentionConfigurable : false,
+        }));
+      }
     } else {
       // Audit store present but no module surface to inspect declared durability rules.
       failures.push({ rule: 'audit-append-only-immutable', stream: 'audit', detail: 'no audit module surface discoverable to verify append-only declaration' });
@@ -528,12 +609,14 @@ function checkLoggingEnvelopes(opts) {
     }
   }
 
-  return { ok: failures.length === 0, failures };
+  return { ok: failures.length === 0, failures, notes };
 }
 
 module.exports = {
   checkEnvelope,
   checkLoggingEnvelopes,
+  _readManifest,
+  _declaredStream,
   // Test surface (not part of the public contract):
   _hasKey,
   _typeOk,

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

@@ -110,6 +110,21 @@ function writeDistilledSchemaIfAbsent(projectDir, planPath) {
  * a file that already exists in the target project is left byte-for-byte
  * untouched (recorded in `skipped`, never in `created`).
  */
+// .gsd-t/logging-manifest.json — same reader the envelope checker uses (kept in
+// step with bin/gsd-t-logging-envelope-check.cjs _readManifest; a stream is
+// "declared" when its `module` is named).
+function readManifest(projectDir) {
+  const p = path.join(projectDir, '.gsd-t', 'logging-manifest.json');
+  if (!fs.existsSync(p)) return { present: false, manifest: null, error: null };
+  try {
+    const m = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!m || typeof m !== 'object' || Array.isArray(m)) return { present: true, manifest: null, error: '.gsd-t/logging-manifest.json is not a JSON object' };
+    return { present: true, manifest: m, error: null };
+  } catch (err) {
+    return { present: true, manifest: null, error: '.gsd-t/logging-manifest.json is not valid JSON: ' + (err && err.message ? err.message : String(err)) };
+  }
+}
+
 function migrateLogging(projectDir, opts) {
   opts = opts || {};
   if (!projectDir || typeof projectDir !== 'string') {
@@ -121,12 +136,32 @@ function migrateLogging(projectDir, opts) {
 
   const created = [];
   const skipped = [];
+  const declared = [];
+
+  // A stream the project DECLARES in .gsd-t/logging-manifest.json already exists
+  // somewhere the template path is not (TimeTracking, 2026-09-03: audit lives at
+  // server/src/audit.ts → Postgres). Scaffolding src/logging/audit.ts beside it
+  // would create a second audit module — a silent twin. A declared stream is
+  // skipped and reported as such; a manifest that cannot be read is an ERROR,
+  // not "no manifest" (scaffolding over an unreadable declaration is the twin
+  // risk with the evidence hidden).
+  const manifest = readManifest(projectDir);
+  if (manifest.error) throw new Error('migrateLogging: ' + manifest.error);
+  const declares = (stream) => !!(manifest.manifest && manifest.manifest[stream] && typeof manifest.manifest[stream] === 'object' && manifest.manifest[stream].module);
+
+  if (declares('trace')) {
+    declared.push('trace: ' + manifest.manifest.trace.module);
+  } else {
+    const traceResult = copyIfAbsent(projectDir, TRACE_DEST_REL, TRACE_TEMPLATE_PATH);
+    (traceResult === 'created' ? created : skipped).push(TRACE_DEST_REL);
+  }
 
-  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);
+  if (declares('audit')) {
+    declared.push('audit: ' + manifest.manifest.audit.module);
+  } else {
+    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);
@@ -140,12 +175,14 @@ function migrateLogging(projectDir, opts) {
     ok: true,
     created,
     skipped,
+    declared,
     dispatchedVia: 'bin/gsd-t.js case "migrate-logging" (wired by d1 — see logging-scaffold-seam-contract.md)',
     scaffold,
   };
 }
 
 module.exports = {
+  readManifest,
   migrateLogging,
   run,
   // Test surface:

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

@@ -4,6 +4,7 @@ Scaffolds the two framework-default logging streams — **trace** (transient deb
 
 ## What this does
 
+- **Declared streams are skipped.** If `.gsd-t/logging-manifest.json` names a stream's `module` (e.g. `{ "audit": { "module": "server/src/audit.ts", "store": { "kind": "postgres", "table": "tb_audit_log" }, "retention": "indefinite" } }`), that stream already exists and is NOT scaffolded — reported under `declared`. This is how a project with a real audit table at a path the checker does not guess adds only the missing trace stream, with no second audit module written beside the first. An unreadable manifest is an error, not "no manifest".
 - 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.

package/package.json

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

@@ -256,6 +256,7 @@ Every GSD-T project gets TWO logging streams scaffolded by default at `gsd-t-ini
 - **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`.
+- **Streams that already exist somewhere the checker does not guess** (an audit table behind `server/src/audit.ts`, say) are DECLARED in `.gsd-t/logging-manifest.json` — `{ "audit": { "module": "server/src/audit.ts", "store": { "kind": "postgres", "table": "tb_audit_log" }, "retention": "indefinite" } }`. The declaration is checked (a path that does not exist FAILs), an external store's rows are not inspected offline (reported in `notes`, the module surface is the enforced evidence), and `migrate-logging` skips a declared stream so it never scaffolds a twin.
 
 ## Orthogonal Validation Triad (Mandatory)