@tekyzinc/gsd-t 2.16.5 → 2.18.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.18.0] - 2026-02-16
+
+### Added
+- Heartbeat system — real-time event streaming from Claude Code sessions via async hooks
+- `scripts/gsd-t-heartbeat.js` — hook handler that writes JSONL events to `.gsd-t/heartbeat-{session_id}.jsonl`
+- 9 Claude Code hooks: SessionStart, PostToolUse, SubagentStart, SubagentStop, TaskCompleted, TeammateIdle, Notification, Stop, SessionEnd
+- Installer auto-configures heartbeat hooks in settings.json (all async, zero performance impact)
+- Event types: session lifecycle, tool calls with file/command summaries, agent spawn/stop/idle, task completions
+
+## [2.17.0] - 2026-02-16
+
+### Added
+- `/user:gsd-t-log` command — sync progress.md Decision Log with recent git activity by scanning commits since last logged entry
+- Incremental updates (only new commits) and first-time full reconstruction from git history
+- Total commands: 38 GSD-T + 3 utility = 41
+
 ## [2.16.5] - 2026-02-16
 
 ### Added

package/README.md

@@ -18,7 +18,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 37 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 38 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -142,6 +142,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees | Manual |
 | `/user:gsd-t-debug` | Systematic debugging with state | Manual |
+| `/user:gsd-t-log` | Sync progress Decision Log with recent git activity | Manual |
 | `/user:gsd-t-version-update` | Update GSD-T to latest version | Manual |
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
 
@@ -280,8 +281,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 40 slash commands
-│   ├── gsd-t-*.md                     # 37 GSD-T workflow commands
+├── commands/                          # 41 slash commands
+│   ├── gsd-t-*.md                     # 38 GSD-T workflow commands
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper
 │   └── Claude-md.md                   # Reload CLAUDE.md directives

package/bin/gsd-t.js

@@ -24,6 +24,7 @@ const { execSync } = require("child_process");
 
 const CLAUDE_DIR = path.join(os.homedir(), ".claude");
 const COMMANDS_DIR = path.join(CLAUDE_DIR, "commands");
+const SCRIPTS_DIR = path.join(CLAUDE_DIR, "scripts");
 const GLOBAL_CLAUDE_MD = path.join(CLAUDE_DIR, "CLAUDE.md");
 const SETTINGS_JSON = path.join(CLAUDE_DIR, "settings.json");
 const VERSION_FILE = path.join(CLAUDE_DIR, ".gsd-t-version");
@@ -33,6 +34,7 @@ const UPDATE_CHECK_FILE = path.join(CLAUDE_DIR, ".gsd-t-update-check");
 // Where our package files live (relative to this script)
 const PKG_ROOT = path.resolve(__dirname, "..");
 const PKG_COMMANDS = path.join(PKG_ROOT, "commands");
+const PKG_SCRIPTS = path.join(PKG_ROOT, "scripts");
 const PKG_TEMPLATES = path.join(PKG_ROOT, "templates");
 const PKG_EXAMPLES = path.join(PKG_ROOT, "examples");
 
@@ -144,6 +146,84 @@ function getInstalledCommands() {
   }
 }
 
+// ─── Heartbeat ──────────────────────────────────────────────────────────────
+
+const HEARTBEAT_SCRIPT = "gsd-t-heartbeat.js";
+const HEARTBEAT_HOOKS = [
+  "SessionStart", "PostToolUse", "SubagentStart", "SubagentStop",
+  "TaskCompleted", "TeammateIdle", "Notification", "Stop", "SessionEnd"
+];
+
+function installHeartbeat() {
+  ensureDir(SCRIPTS_DIR);
+
+  // Copy heartbeat script
+  const src = path.join(PKG_SCRIPTS, HEARTBEAT_SCRIPT);
+  const dest = path.join(SCRIPTS_DIR, HEARTBEAT_SCRIPT);
+
+  if (!fs.existsSync(src)) {
+    warn("Heartbeat script not found in package — skipping");
+    return;
+  }
+
+  const srcContent = fs.readFileSync(src, "utf8");
+  const destContent = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
+
+  if (srcContent !== destContent) {
+    copyFile(src, dest, HEARTBEAT_SCRIPT);
+  } else {
+    info("Heartbeat script unchanged");
+  }
+
+  // Configure hooks in settings.json
+  const hooksAdded = configureHeartbeatHooks(dest);
+  if (hooksAdded > 0) {
+    success(`${hooksAdded} heartbeat hooks configured in settings.json`);
+  } else {
+    info("Heartbeat hooks already configured");
+  }
+}
+
+function configureHeartbeatHooks(scriptPath) {
+  let settings = {};
+  if (fs.existsSync(SETTINGS_JSON)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_JSON, "utf8"));
+    } catch {
+      warn("settings.json has invalid JSON — cannot configure hooks");
+      return 0;
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const cmd = `node "${scriptPath.replace(/\\/g, "\\\\")}"`;
+  let added = 0;
+
+  for (const event of HEARTBEAT_HOOKS) {
+    if (!settings.hooks[event]) settings.hooks[event] = [];
+
+    // Check if heartbeat hook already exists for this event
+    const hasHeartbeat = settings.hooks[event].some((entry) =>
+      entry.hooks && entry.hooks.some((h) => h.command && h.command.includes(HEARTBEAT_SCRIPT))
+    );
+
+    if (!hasHeartbeat) {
+      settings.hooks[event].push({
+        matcher: "",
+        hooks: [{ type: "command", command: cmd, async: true }],
+      });
+      added++;
+    }
+  }
+
+  if (added > 0) {
+    fs.writeFileSync(SETTINGS_JSON, JSON.stringify(settings, null, 2));
+  }
+
+  return added;
+}
+
 // ─── Commands ────────────────────────────────────────────────────────────────
 
 function doInstall(opts = {}) {
@@ -226,10 +306,14 @@ function doInstall(opts = {}) {
     copyFile(globalSrc, GLOBAL_CLAUDE_MD, "CLAUDE.md installed → ~/.claude/CLAUDE.md");
   }
 
-  // 4. Save version
+  // 4. Install heartbeat script + hooks
+  heading("Heartbeat (Real-time Events)");
+  installHeartbeat();
+
+  // 5. Save version
   saveInstalledVersion();
 
-  // 5. Summary
+  // 6. Summary
   heading("Installation Complete!");
   log("");
   log(`  Commands: ${gsdtCommands.length} GSD-T + ${utilityCommands.length} utility commands in ~/.claude/commands/`);

package/commands/gsd-t-help.md

@@ -52,6 +52,7 @@ UTILITIES                                                              Manual
   debug               Systematic debugging with state
   promote-debt        Convert techdebt items to milestones
   populate            Auto-populate docs from existing codebase
+  log                 Sync progress Decision Log with recent git activity
   version-update      Update GSD-T package to latest version
   version-update-all  Update GSD-T package + all registered projects
 
@@ -295,6 +296,13 @@ Use these when user asks for help on a specific command:
 - **Updates**: `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`, `.gsd-t/progress.md`
 - **Use when**: You have an existing codebase and want to fill docs with real findings instead of placeholders
 
+### log
+- **Summary**: Sync progress.md Decision Log with recent git activity
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/progress.md`, git history
+- **Use when**: Progress.md Decision Log is behind — catches up by scanning git commits since the last logged entry
+- **Features**: Incremental updates, first-time full reconstruction from git history, groups same-day changes
+
 ### backlog-add
 - **Summary**: Capture a new backlog item with auto-categorization
 - **Auto-invoked**: No

package/commands/gsd-t-log.md

@@ -0,0 +1,87 @@
+# GSD-T: Log — Sync Progress Decision Log with Recent Activity
+
+Update `.gsd-t/progress.md` Decision Log by scanning git history for commits not yet recorded. Works on any GSD-T project.
+
+## Step 1: Load State
+
+Read:
+1. `.gsd-t/progress.md` — current Decision Log entries
+2. Note the **last entry's timestamp** — this is the cutoff; only commits after this time need processing
+
+If `.gsd-t/progress.md` doesn't exist, inform user: "No GSD-T state found. Run `/user:gsd-t-init` first."
+
+## Step 2: Get Recent Commits
+
+Run: `git log --reverse --format="%ai|%s" --after="{last entry date}"`
+
+If no cutoff exists (empty Decision Log), get the full history:
+`git log --reverse --format="%ai|%s"`
+
+## Step 3: Filter and Format
+
+For each commit since the last logged entry:
+
+1. **Skip** merge commits, whitespace-only changes, and commits already in the Decision Log
+2. **Group** multiple commits on the same day that cover the same logical change into one entry
+3. **Format** each entry:
+   ```
+   - YYYY-MM-DD HH:MM: {commit summary} — {brief context}
+   ```
+4. If the commit message includes a version tag like `(vX.Y.Z)`, append it to the entry
+
+### What to include:
+- Feature additions, bug fixes, refactors
+- Config/dependency changes
+- Documentation updates
+- Version bumps and releases
+- Any commit that modified documents, scripts, or code
+
+### What to exclude:
+- Pure merge commits with no additional context
+- Commits that only change whitespace or formatting
+- Entries already in the Decision Log (check by date+content match)
+
+## Step 4: Append to Decision Log
+
+Append the new entries chronologically at the end of the existing Decision Log section in `.gsd-t/progress.md`.
+
+Do NOT modify or rewrite existing entries — only add new ones.
+
+## Step 5: Report
+
+Show a summary:
+
+```
+Progress Log Updated
+
+  Commits scanned:  {N}
+  New entries added: {M}
+  Last entry:        {date and summary of most recent entry}
+
+Decision Log now has {total} entries covering {first date} to {last date}.
+```
+
+If no new commits were found:
+```
+Progress Log — already up to date
+
+  Last entry: {date and summary}
+  No new commits since last log entry.
+```
+
+## Step 6: First-Time Reconstruction
+
+If the Decision Log is empty or has fewer than 3 entries and git history has 5+ commits, offer full reconstruction:
+
+```
+The Decision Log appears sparse but this project has {N} commits.
+Reconstructing full history from git...
+```
+
+Then run the full reconstruction (same as the populate command's git history reconstruction):
+1. Parse all commits
+2. Generate timestamped entries
+3. Group by logical change
+4. Mark reconstructed entries: `(Entries before {date} reconstructed from git history)`
+
+$ARGUMENTS

package/docs/GSD-T-README.md

@@ -111,6 +111,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees | Manual |
 | `/user:gsd-t-debug` | Systematic debugging with state | Manual |
+| `/user:gsd-t-log` | Sync progress Decision Log with recent git activity | Manual |
 | `/user:gsd-t-version-update` | Update GSD-T to latest version | Manual |
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.16.5",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 40 slash commands with backlog management, impact analysis, test sync, and milestone archival",
+  "version": "2.18.0",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 41 slash commands with backlog management, impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
   "files": [
     "bin/",
     "commands/",
+    "scripts/",
     "templates/",
     "examples/",
     "docs/",

package/scripts/gsd-t-heartbeat.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Heartbeat — Claude Code Hook Event Writer
+ *
+ * Writes structured events to .gsd-t/heartbeat-{session_id}.jsonl
+ * Installed as an async hook for multiple Claude Code events.
+ *
+ * Events captured:
+ *   SessionStart, PostToolUse, SubagentStart, SubagentStop,
+ *   TaskCompleted, TeammateIdle, Notification, Stop, SessionEnd
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (d) => (input += d));
+process.stdin.on("end", () => {
+  try {
+    const hook = JSON.parse(input);
+    const dir = hook.cwd || process.cwd();
+    const gsdtDir = path.join(dir, ".gsd-t");
+
+    if (!fs.existsSync(gsdtDir)) return;
+
+    const sid = hook.session_id || "unknown";
+    const file = path.join(gsdtDir, `heartbeat-${sid}.jsonl`);
+
+    const event = buildEvent(hook);
+    if (event) {
+      fs.appendFileSync(file, JSON.stringify(event) + "\n");
+    }
+  } catch (e) {
+    // Silent failure — never interfere with Claude Code
+  }
+});
+
+function buildEvent(hook) {
+  const base = {
+    ts: new Date().toISOString(),
+    sid: hook.session_id,
+  };
+
+  switch (hook.hook_event_name) {
+    case "SessionStart":
+      return {
+        ...base,
+        evt: "session_start",
+        data: { source: hook.source, model: hook.model },
+      };
+
+    case "PostToolUse":
+      return {
+        ...base,
+        evt: "tool",
+        tool: hook.tool_name,
+        data: summarize(hook.tool_name, hook.tool_input),
+      };
+
+    case "SubagentStart":
+      return {
+        ...base,
+        evt: "agent_spawn",
+        data: { agent_id: hook.agent_id, agent_type: hook.agent_type },
+      };
+
+    case "SubagentStop":
+      return {
+        ...base,
+        evt: "agent_stop",
+        data: { agent_id: hook.agent_id, agent_type: hook.agent_type },
+      };
+
+    case "TaskCompleted":
+      return {
+        ...base,
+        evt: "task_done",
+        data: { task: hook.task_subject, agent: hook.teammate_name },
+      };
+
+    case "TeammateIdle":
+      return {
+        ...base,
+        evt: "agent_idle",
+        data: { agent: hook.teammate_name, team: hook.team_name },
+      };
+
+    case "Notification":
+      return {
+        ...base,
+        evt: "notification",
+        data: { message: hook.message, title: hook.title },
+      };
+
+    case "Stop":
+      return { ...base, evt: "session_stop" };
+
+    case "SessionEnd":
+      return {
+        ...base,
+        evt: "session_end",
+        data: { reason: hook.reason },
+      };
+
+    default:
+      return null;
+  }
+}
+
+function summarize(tool, input) {
+  if (!tool || !input) return {};
+  switch (tool) {
+    case "Read":
+      return { file: shortPath(input.file_path) };
+    case "Edit":
+      return { file: shortPath(input.file_path) };
+    case "Write":
+      return { file: shortPath(input.file_path) };
+    case "Bash":
+      return {
+        cmd: (input.command || "").slice(0, 150),
+        desc: input.description,
+      };
+    case "Grep":
+      return { pattern: input.pattern, path: shortPath(input.path) };
+    case "Glob":
+      return { pattern: input.pattern };
+    case "Task":
+      return { desc: input.description, type: input.subagent_type };
+    case "WebSearch":
+      return { query: input.query };
+    case "WebFetch":
+      return { url: input.url };
+    case "NotebookEdit":
+      return { file: shortPath(input.notebook_path) };
+    default:
+      return {};
+  }
+}
+
+function shortPath(p) {
+  if (!p) return null;
+  // Convert absolute paths to relative for readability
+  const cwd = process.cwd();
+  if (p.startsWith(cwd)) {
+    return p.slice(cwd.length + 1).replace(/\\/g, "/");
+  }
+  // For home-dir paths, abbreviate
+  const home = require("os").homedir();
+  if (p.startsWith(home)) {
+    return "~" + p.slice(home.length).replace(/\\/g, "/");
+  }
+  return p.replace(/\\/g, "/");
+}

package/templates/CLAUDE-global.md

@@ -54,6 +54,7 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-debug` | Systematic debugging |
 | `/user:gsd-t-quick` | Fast task, respects contracts |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase |
+| `/user:gsd-t-log` | Sync progress Decision Log with recent git activity |
 | `/user:gsd-t-resume` | Restore context, continue |
 | `/user:gsd-t-version-update` | Update GSD-T to latest version |
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects |