@tekyzinc/gsd-t 3.19.0 → 3.20.10

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.20.10] - 2026-05-03
+
+### Added — Live-clock dated banner + PreToolUse date guard
+
+Solves the multi-day-session date-drift problem. Long sessions span days; without a fresh time signal every turn, hand-written timestamps (decision log entries, `continue-here-{ts}.md` filenames, memory entries, banners) silently drift to the session-start date.
+
+**Hook — `scripts/gsd-t-auto-route.js` (UserPromptSubmit):**
+- Now emits `[GSD-T NOW] Day: Mon DD, YYYY HH:MM:SS TZ` at the start of every user turn (every project, regardless of GSD-T detection).
+- Existing `[GSD-T AUTO-ROUTE]` behavior preserved (still GSD-T-project-only, plain-text-prompts-only).
+- Exports `liveTimestamp()` for test reuse.
+
+**Hook — `scripts/gsd-t-date-guard.js` (PreToolUse on Write|Edit, NEW):**
+- Blocks Write/Edit calls whose content contains timestamps drifting more than ±5 minutes from the live system clock.
+- High-signal patterns validated: decision-log entries (`- YYYY-MM-DD HH:MM:`), `continue-here-YYYY-MM-DDTHHMMSS` filenames, banners (`Day: Mon DD, YYYY HH:MM`), labeled stamps (`Date:`, `Updated:`, `Created:`, etc.).
+- For Edit: timestamps appearing in BOTH `old_string` and `new_string` are pre-existing context — never flagged.
+- Allowlist: machine-written and historical-frozen paths (`.gsd-t/events/`, `.gsd-t/transcripts/`, `.gsd-t/metrics/`, `.gsd-t/.unattended/`, `.gsd-t/headless-*.log`, `.gsd-t/dashboard.log`, `.gsd-t/progress-archive/`, `.gsd-t/milestones/`, `.gsd-t/scan/`, `.git/`, `node_modules/`, `CHANGELOG.md`, `.gsd-t/token-log.md`, `.gsd-t/qa-issues.md`, existing `continue-here-*.md`).
+- Fails open on internal error — broken tool calls are worse than drift.
+- 10/10 smoke tests pass.
+
+**Banner change — `scripts/gsd-t-update-check.js`:**
+- CURRENT-state banner no longer ships the changelog URL — pure noise when there's no update to read about. Action-required banners (AUTO-UPDATE, UPDATE) keep the link.
+
+**Spec — `~/.claude/CLAUDE.md` + `templates/CLAUDE-global.md` (rewritten §Update Notices + new §Live Clock Rule):**
+- Dated banner mandated as the first line of EVERY response, sourced from `[GSD-T NOW]` only — never `currentDate` (frozen) or SessionStart (frozen).
+- Live Clock Rule: any timestamp written to disk MUST come from live system clock. Date guard mechanically enforces this.
+- Format tightened to `Day: Mon DD, YYYY HH:MM TZ` (HH:MM displayed; seconds emitted but trimmed).
+
+### Why
+
+Hand-written timestamps were being sourced from `currentDate` in Claude's context — a string injected once at session start. Multi-day sessions (the user reported they happen often) meant decision-log entries, archive filenames, and memory entries were silently dated wrong by N days.
+
+Red Team principle applied: directives in CLAUDE.md are not safety properties. The PreToolUse hook is the enforcement.
+
+### Settings install
+
+Add to `~/.claude/settings.json` (in the `hooks` block, before `PostToolUse`):
+
+```json
+"PreToolUse": [
+  { "matcher": "Write|Edit",
+    "hooks": [{ "type": "command",
+                "command": "node \"$HOME/.claude/scripts/gsd-t-date-guard.js\"" }] }
+]
+```
+
 ## [3.19.00] - 2026-04-23
 
 ### Added — M46 Milestone: Unattended Iter-Parallel + Worker Fan-Out Completion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.19.00",
+  "version": "3.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/scripts/gsd-t-auto-route.js

@@ -1,26 +1,47 @@
 #!/usr/bin/env node
 /**
- * GSD-T UserPromptSubmit hook — auto-routes plain text prompts through /gsd.
+ * GSD-T UserPromptSubmit hook — emits live timestamp + auto-routes plain text prompts.
  *
  * Receives JSON on stdin: { "prompt": "...", "cwd": "...", "session_id": "..." }
  * Outputs to stdout: injected as system context before Claude processes the prompt.
  *
- * Logic:
- *   - Not a GSD-T project (no .gsd-t/progress.md in cwd) → exit silently
- *   - Prompt starts with "/" → exit silently (user typed a command, pass through)
- *   - Prompt is plain text → emit [GSD-T AUTO-ROUTE] signal so Claude routes via /gsd
+ * Always emits (every turn, every project):
+ *   - [GSD-T NOW] {Day: Mon DD, YYYY HH:MM:SS TZ} — live system clock for the
+ *     dated banner at the top of Claude's response. Fresh per turn so multi-day
+ *     sessions and date-rollovers are reflected accurately.
+ *
+ * Conditionally emits (GSD-T projects only, plain text prompts only):
+ *   - [GSD-T AUTO-ROUTE] signal so Claude routes via /gsd
  */
 
 const fs = require("fs");
 const path = require("path");
 
+function liveTimestamp(now = new Date()) {
+  const day  = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][now.getDay()];
+  const mon  = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+                "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][now.getMonth()];
+  const pad  = (n) => String(n).padStart(2, "0");
+  const date = `${day}: ${mon} ${now.getDate()}, ${now.getFullYear()}`;
+  const time = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+  // Pull the local timezone abbreviation (e.g. "PDT", "EST") from toString().
+  const tzMatch = now.toString().match(/\(([^)]+)\)$/);
+  const tzShort = tzMatch
+    ? tzMatch[1].split(" ").map((w) => w[0]).join("") // "Pacific Daylight Time" → "PDT"
+    : "";
+  return `${date} ${time}${tzShort ? " " + tzShort : ""}`;
+}
+
 let input = "";
 process.stdin.setEncoding("utf8");
 process.stdin.on("data", (chunk) => { input += chunk; });
 process.stdin.on("end", () => {
+  // Always emit live timestamp first — every turn, every project.
+  process.stdout.write(`[GSD-T NOW] ${liveTimestamp()}\n`);
+
   try {
     const data = JSON.parse(input);
-    // Guard: only activate in GSD-T projects
+    // Auto-route is GSD-T-project-only.
     const cwd = typeof data.cwd === "string" ? data.cwd : process.cwd();
     if (!fs.existsSync(path.join(cwd, ".gsd-t", "progress.md"))) process.exit(0);
     const prompt = (typeof data.prompt === "string" ? data.prompt : "").trimStart();
@@ -37,3 +58,5 @@ process.stdin.on("end", () => {
   }
   process.exit(0);
 });
+
+module.exports = { liveTimestamp };

package/scripts/gsd-t-date-guard.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * GSD-T PreToolUse hook — blocks Write/Edit calls that contain stale or invented timestamps.
+ *
+ * Receives JSON on stdin from Claude Code:
+ *   {
+ *     "tool_name": "Write" | "Edit",
+ *     "tool_input": { "file_path": "...", "content"|"new_string"|"old_string": "..." },
+ *     "cwd": "...",
+ *     "session_id": "..."
+ *   }
+ *
+ * Behavior:
+ *   - Pulls system clock at hook execution time (independent of Claude's context).
+ *   - Scans the content being written for date-like patterns (decision-log entries,
+ *     filename timestamps, ISO date strings, "Day: Mon DD, YYYY" banners).
+ *   - For Edit: only validates timestamps in `new_string` that are NOT also in `old_string`
+ *     (so unchanged surrounding context never trips the guard).
+ *   - For Write: validates timestamps that match high-signal "freshly stamped" patterns;
+ *     ignores generic ISO matches in prose.
+ *   - If any flagged timestamp is outside ±DRIFT_MINUTES of system clock, exit 2 with a
+ *     structured error that surfaces back to Claude as a tool error.
+ *
+ * Exit codes:
+ *   0 — content passes (no suspicious timestamps, or all within window)
+ *   2 — block: stale/invented timestamp detected
+ *
+ * Allowlisted paths bypass entirely (machine-written files, transcripts, git internals).
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const DRIFT_MINUTES = 5;
+const DRIFT_MS = DRIFT_MINUTES * 60 * 1000;
+
+// Paths where dates are machine-written or historically frozen — never validate.
+const ALLOWLIST_PATTERNS = [
+  /\/\.git\//,
+  /\/node_modules\//,
+  /\.gsd-t\/events\/[\d-]+\.jsonl$/,
+  /\.gsd-t\/transcripts\//,
+  /\.gsd-t\/metrics\//,
+  /\.gsd-t\/\.unattended\//,
+  /\.gsd-t\/headless-\d+\.log$/,
+  /\.gsd-t\/dashboard\.log$/,
+  /\.gsd-t\/progress-archive\//,
+  /\.gsd-t\/milestones\//,
+  /\.gsd-t\/scan\//,
+  /CHANGELOG\.md$/,
+  /\.gsd-t\/token-log\.md$/,
+  /\.gsd-t\/qa-issues\.md$/,
+  /\.gsd-t\/continue-here-[\d-]+T[\d]+\.md$/, // Existing files; new ones validated by filename rule
+];
+
+// High-signal patterns — these are timestamps Claude is producing right now,
+// not historical references inside prose.
+const FRESH_STAMP_PATTERNS = [
+  // Decision log entries: "- 2026-05-03 12:35: did the thing"
+  {
+    name: "decision-log",
+    regex: /^- (\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):/gm,
+    extract: (m) => new Date(
+      Number(m[1]), Number(m[2]) - 1, Number(m[3]),
+      Number(m[4]), Number(m[5]), 0
+    ),
+  },
+  // continue-here filenames: "continue-here-2026-05-03T123500.md"
+  {
+    name: "continue-here-filename",
+    regex: /continue-here-(\d{4})-(\d{2})-(\d{2})T(\d{2})(\d{2})(\d{2})/g,
+    extract: (m) => new Date(
+      Number(m[1]), Number(m[2]) - 1, Number(m[3]),
+      Number(m[4]), Number(m[5]), Number(m[6])
+    ),
+  },
+  // Session-banner format: "Sun: May 3, 2026 12:35 PDT"
+  {
+    name: "banner",
+    regex: /(Sun|Mon|Tue|Wed|Thu|Fri|Sat): (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{1,2}), (\d{4}) (\d{2}):(\d{2})/g,
+    extract: (m) => {
+      const monIdx = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+                      "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"].indexOf(m[2]);
+      return new Date(Number(m[4]), monIdx, Number(m[3]), Number(m[5]), Number(m[6]), 0);
+    },
+  },
+];
+
+// Generic ISO date — only validated when surrounded by strong "freshly stamping now"
+// context (e.g., right after labels like "Date:", "Today:", "Stamped:", etc.).
+// Two arms: (a) date+time (validated against full ±DRIFT_MINUTES window),
+//          (b) date-only (validated as same-calendar-day-as-now, time-of-day ignored).
+const STAMPED_ISO_PATTERN = {
+  name: "stamped-iso",
+  regex: /\b(?:Date|Today|Stamped|Updated|Created|Generated|Now|Timestamp|At)\s*[:=]\s*(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?/gi,
+  extract: (m) => {
+    const hasTime = m[4] !== undefined;
+    return {
+      stamped: new Date(
+        Number(m[1]), Number(m[2]) - 1, Number(m[3]),
+        hasTime ? Number(m[4]) : 12, // Date-only → noon, neutralizes timezone-edge false positives
+        hasTime ? Number(m[5]) : 0,
+        0
+      ),
+      dateOnly: !hasTime,
+    };
+  },
+};
+
+function isAllowlisted(filePath) {
+  if (!filePath) return false;
+  return ALLOWLIST_PATTERNS.some((re) => re.test(filePath));
+}
+
+function findStaleTimestamps(content, now, oldContent) {
+  if (!content || typeof content !== "string") return [];
+  const findings = [];
+  const oldText = typeof oldContent === "string" ? oldContent : "";
+
+  const allPatterns = [...FRESH_STAMP_PATTERNS, STAMPED_ISO_PATTERN];
+
+  for (const pattern of allPatterns) {
+    const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const fullMatch = match[0];
+      // For Edit: skip matches that also appear in old_string (pre-existing).
+      if (oldText && oldText.includes(fullMatch)) continue;
+
+      let extracted;
+      try { extracted = pattern.extract(match); } catch { continue; }
+      if (!extracted) continue;
+
+      // Normalize: extract may return a Date directly, or {stamped, dateOnly}.
+      const stamped = extracted instanceof Date ? extracted : extracted.stamped;
+      const dateOnly = !!(extracted && extracted.dateOnly);
+      if (!stamped || isNaN(stamped.getTime())) continue;
+
+      // Date-only stamps: validate same-calendar-day-as-now (drift in days, not minutes).
+      if (dateOnly) {
+        const sameDay = stamped.getFullYear() === now.getFullYear() &&
+                        stamped.getMonth() === now.getMonth() &&
+                        stamped.getDate() === now.getDate();
+        if (!sameDay) {
+          const dayDiff = Math.round((stamped.getTime() - now.getTime()) / 86400000);
+          findings.push({
+            pattern: pattern.name,
+            matched: fullMatch,
+            stamped: `${stamped.getFullYear()}-${String(stamped.getMonth()+1).padStart(2,'0')}-${String(stamped.getDate()).padStart(2,'0')}`,
+            driftMinutes: Math.abs(dayDiff) * 1440,
+            direction: dayDiff > 0 ? "future" : "past",
+            note: `date-only stamp; ${Math.abs(dayDiff)} day(s) ${dayDiff > 0 ? "ahead of" : "behind"} today`,
+          });
+        }
+        continue;
+      }
+
+      const driftMs = Math.abs(stamped.getTime() - now.getTime());
+      if (driftMs > DRIFT_MS) {
+        const driftMin = Math.round(driftMs / 60000);
+        findings.push({
+          pattern: pattern.name,
+          matched: fullMatch,
+          stamped: stamped.toISOString(),
+          driftMinutes: driftMin,
+          direction: stamped.getTime() > now.getTime() ? "future" : "past",
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+function nowBanner(now) {
+  const day = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][now.getDay()];
+  const mon = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+               "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][now.getMonth()];
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${day}: ${mon} ${now.getDate()}, ${now.getFullYear()} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+}
+
+function formatBlock(findings, now) {
+  const lines = [
+    "[GSD-T DATE GUARD] Blocked — content contains timestamps that don't match the live system clock.",
+    `Live system clock: ${now.toISOString()}  (${nowBanner(now)})`,
+    `Tolerance: ±${DRIFT_MINUTES} minutes.`,
+    "",
+    "Stale or invented timestamps detected:",
+  ];
+  for (const f of findings) {
+    lines.push(`  - [${f.pattern}] "${f.matched}" — stamped ${f.stamped} (${f.driftMinutes} min ${f.direction} of now)`);
+  }
+  lines.push("");
+  lines.push("Fix: re-emit the write using the live system clock from `[GSD-T NOW]` in your context,");
+  lines.push("or `node -e \"console.log(new Date().toISOString())\"` if the signal is unavailable.");
+  lines.push("Never source timestamps from `currentDate` (frozen at session start) or memory.");
+  return lines.join("\n");
+}
+
+function processInput(rawJson) {
+  let payload;
+  try { payload = JSON.parse(rawJson); } catch { return { ok: true }; }
+
+  const tool = payload.tool_name;
+  if (tool !== "Write" && tool !== "Edit") return { ok: true };
+
+  const input = payload.tool_input || {};
+  const filePath = input.file_path || "";
+
+  // Allowlist check — bypass entirely for machine-written / historical-frozen paths.
+  if (isAllowlisted(filePath)) return { ok: true };
+
+  // Pull live system clock — independent of any signal in Claude's context.
+  const now = new Date();
+
+  let content, oldContent;
+  if (tool === "Write") {
+    content = input.content || "";
+    oldContent = ""; // Write replaces — no diff context.
+  } else { // Edit
+    content = input.new_string || "";
+    oldContent = input.old_string || "";
+  }
+
+  const findings = findStaleTimestamps(content, now, oldContent);
+  if (findings.length === 0) return { ok: true };
+
+  return { ok: false, message: formatBlock(findings, now) };
+}
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => { input += chunk; });
+process.stdin.on("end", () => {
+  try {
+    const result = processInput(input);
+    if (result.ok) process.exit(0);
+    process.stderr.write(result.message + "\n");
+    process.exit(2);
+  } catch (e) {
+    // Never block on guard error — fail open. Drift is bad; broken tool calls are worse.
+    process.stderr.write(`[GSD-T DATE GUARD] internal error (failing open): ${e.message}\n`);
+    process.exit(0);
+  }
+});
+
+module.exports = { findStaleTimestamps, isAllowlisted, processInput, DRIFT_MINUTES };

package/scripts/gsd-t-update-check.js

@@ -95,7 +95,7 @@ function run() {
   if (cached && cached.latest && isNewer(cached.latest, installed)) {
     doAutoUpdate(cached.latest, installed);
   } else {
-    console.log(`${dateStamp()}[GSD-T] v${installed} — CURRENT. Changelog: ${CHANGELOG}`);
+    console.log(`${dateStamp()}[GSD-T] v${installed} — CURRENT.`);
   }
 }
 

package/templates/CLAUDE-global.md

@@ -120,27 +120,59 @@ Even in development, the user may have:
 
 ## Update Notices
 
-On session start, a version check hook auto-updates GSD-T and outputs a status message. Show the result to the user at the **beginning** of your first response:
+The hook output at session start is NOT visible to the user — only your response text is. So you MUST emit a dated status banner as the **very first line of every response** (every turn, not just the first), above any routing header or other content.
 
-- If `[GSD-T AUTO-UPDATE]` appears → GSD-T was just auto-updated. Show:
+**Date source — MANDATORY**: use the timestamp from the most recent `[GSD-T NOW]` signal in your context. The UserPromptSubmit hook (`scripts/gsd-t-auto-route.js`) emits `[GSD-T NOW] Day: Mon DD, YYYY HH:MM:SS TZ` at the start of every turn — this is live system clock. Do NOT use:
+- The SessionStart banner (frozen at session start — wrong on day 2 of a long session)
+- The `currentDate` field in your context (frozen at session start — same problem)
+- Your training-cutoff intuition (always wrong)
+
+If `[GSD-T NOW]` is absent for any reason, fall back to `currentDate` and flag the gap.
+
+**Format** — one line, no changelog noise in steady state:
+
+- Steady state (`[GSD-T]` token seen at session start, or no version-check token — default):
   ```
-  ✅ GSD-T auto-updated: v{old} → v{new}
-     Changelog: https://github.com/Tekyz-Inc/get-stuff-done-teams/blob/main/CHANGELOG.md
+  Day: Mon DD, YYYY HH:MM TZ — GSD-T v{version} — CURRENT
   ```
+  Example: `Sun: May 3, 2026 12:21 PDT — GSD-T v3.19.00 — CURRENT`
 
-- If `[GSD-T UPDATE]` appears → update available but auto-update failed. Show:
+- Auto-updated this session (`[GSD-T AUTO-UPDATE]` token seen at session start):
   ```
-  ⬆️  GSD-T update available: v{installed} → v{latest} (auto-update failed)
-     Run: /gsd-t-version-update-all
-     Changelog: https://github.com/Tekyz-Inc/get-stuff-done-teams/blob/main/CHANGELOG.md
+  Day: Mon DD, YYYY HH:MM TZ — GSD-T v{old} → v{new} ✅ AUTO-UPDATED
+  Changelog: https://github.com/Tekyz-Inc/get-stuff-done-teams/blob/main/CHANGELOG.md
   ```
-  Also repeat at the **end** of your first response.
+  (The changelog link earns its place here — there's new code to read about.)
 
-- If `[GSD-T]` appears → up to date. Show:
+- Update available, auto-update failed (`[GSD-T UPDATE]` token seen at session start):
   ```
-  GSD-T v{version} — up to date
+  Day: Mon DD, YYYY HH:MM TZ — GSD-T v{installed} → v{latest} ⬆️ UPDATE AVAILABLE (auto-update failed)
+  Run: /gsd-t-version-update-all
   Changelog: https://github.com/Tekyz-Inc/get-stuff-done-teams/blob/main/CHANGELOG.md
   ```
+  Also repeat at the **end** of your first response.
+
+(Drop seconds from the displayed banner — keep it to `HH:MM TZ` for readability. The hook emits seconds; you trim.)
+
+**Why every response, not just the first**: long sessions span multiple days. A dated header on every turn means the user can scroll back and immediately see when any exchange happened, without inferring from context.
+
+**Order**: dated status banner FIRST. Then routing header (if any). Then your response body.
+
+## Live Clock Rule (MANDATORY)
+
+Whenever you write a date or timestamp to any file — decision log entries in `progress.md`, `continue-here-{ts}.md` filenames, memory entries, banners, "Updated:" / "Date:" frontmatter, archive headings, anything visible — source it from **the live system clock**. Never from `currentDate` (frozen at session start), the SessionStart banner (frozen), or your intuition (unreliable).
+
+**How to obtain the live clock**:
+1. Read the most recent `[GSD-T NOW]` signal from your context (UserPromptSubmit hook emits it every turn).
+2. If absent, run `node -e "console.log(new Date().toISOString())"` via Bash before writing.
+
+**Enforcement**: a PreToolUse hook (`scripts/gsd-t-date-guard.js`) blocks Write/Edit calls whose content contains timestamps drifting more than ±5 minutes from the live system clock. The guard:
+- Validates decision-log entries (`- YYYY-MM-DD HH:MM:`), filename timestamps (`continue-here-YYYY-MM-DDTHHMMSS`), banners (`Day: Mon DD, YYYY HH:MM`), and labeled stamps (`Date:`, `Updated:`, `Created:`, etc.).
+- For Edit, ignores timestamps that appear in BOTH `old_string` and `new_string` (pre-existing context, not new writes).
+- Allowlists machine-written paths (`.gsd-t/events/`, `.gsd-t/transcripts/`, `.gsd-t/metrics/`, `.git/`, `node_modules/`, archives, log files).
+- Fails open on internal error — broken tool calls would be worse than drift.
+
+If the guard blocks your write, do NOT bypass it. Re-read `[GSD-T NOW]`, regenerate the timestamp, retry.
 
 ## Conversation vs. Work