@tekyzinc/gsd-t 2.17.0 → 2.18.2

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.18.2] - 2026-02-16
+
+### Added
+- Gap Analysis Gate in `gsd-t-complete-milestone` — mandatory requirements verification before archiving
+- Self-correction loop: auto-fixes gaps, re-verifies, re-analyzes (up to 2 cycles), stops if unresolvable
+- Explicit Playwright E2E test execution in milestone test verification step
+
+## [2.18.1] - 2026-02-16
+
+### Added
+- Auto-Init Guard — GSD-T workflow commands automatically run `gsd-t-init` if any init files are missing, then continue with the original command
+- `gsd-t-init` copies `~/.claude/settings.local` → `.claude/settings.local.json` during project initialization
+- Exempt commands that skip auto-init: `gsd-t-init`, `gsd-t-init-scan-setup`, `gsd-t-help`, `gsd-t-version-update`, `gsd-t-version-update-all`, `gsd-t-prompt`, `gsd-t-brainstorm`
+
+## [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

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-complete-milestone.md

@@ -17,6 +17,22 @@ If status is not VERIFIED:
 
 If `--force` flag provided, proceed with warning in archive.
 
+## Step 1.5: Gap Analysis Gate
+
+After verification passes, run a gap analysis against `docs/requirements.md` scoped to this milestone's deliverables:
+
+1. Identify which requirements this milestone was supposed to satisfy (from domain scopes, tasks, and milestone definition)
+2. Run `gsd-t-gap-analysis` against those requirements, comparing spec to actual code
+3. If **all gaps resolved** (100% Implemented) → proceed to Step 2
+4. If **gaps found** (Partial, Incorrect, or Not Implemented):
+   a. Auto-fix: execute remediation for each gap (prioritize Critical → High → Medium)
+   b. Run affected tests (unit + integration + Playwright E2E if configured)
+   c. Re-run `gsd-t-verify` to confirm fixes don't break anything
+   d. Re-run gap analysis to confirm gaps are resolved
+   e. If gaps remain after **2 fix cycles** → STOP and report unresolved gaps to user
+
+This is a **mandatory gate** — the milestone cannot be archived with known gaps against its requirements.
+
 ## Step 2: Gather Milestone Artifacts
 
 Collect all files related to this milestone:
@@ -163,10 +179,11 @@ Before creating the git tag, verify all documentation is up to date:
 
 Before creating the git tag, verify the milestone is truly complete:
 
-1. **Run the full test suite**: Execute ALL tests — unit, integration, and E2E if available
-2. **Verify all pass**: Every test must pass. If any fail, fix before tagging (up to 2 attempts)
-3. **Compare to baseline**: If a test baseline was recorded at milestone start, verify coverage has improved or at minimum not regressed
-4. **Log test results**: Include test pass/fail counts in the milestone summary (Step 4)
+1. **Run the full test suite**: Execute ALL tests — unit, integration, and E2E
+2. **Run Playwright E2E** (if configured): Detect `playwright.config.*` or Playwright in dependencies. If present, run the full Playwright suite. If specs are missing or stale, invoke `gsd-t-test-sync` first.
+3. **Verify all pass**: Every test must pass. If any fail, fix before tagging (up to 2 attempts)
+4. **Compare to baseline**: If a test baseline was recorded at milestone start, verify coverage has improved or at minimum not regressed
+5. **Log test results**: Include test pass/fail counts in the milestone summary (Step 4)
 
 ## Step 8: Create Git Tag
 

package/commands/gsd-t-init.md

@@ -18,6 +18,14 @@ Report current state and ask if user wants to reset or continue.
 Offer to migrate: "Found legacy GSD structure. Want me to migrate to GSD-T?"
 If yes, read `.gsd/` state and create equivalent `.gsd-t/` structure.
 
+## Step 1.5: Copy Local Settings
+
+If `~/.claude/settings.local` exists and `.claude/settings.local.json` does not exist in the project:
+1. Create the `.claude/` directory in the project root if it doesn't exist
+2. Copy `~/.claude/settings.local` → `.claude/settings.local.json`
+
+Skip silently if the source file doesn't exist or the target already exists.
+
 ## Step 2: Create Directory Structure
 
 ```

package/package.json

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

@@ -176,6 +176,21 @@ On session start, a version check hook outputs one of two messages. Show the res
 
 Only execute GSD-T workflow behavior when a `/gsd-t-*` command is invoked or when actively mid-phase (resumed via `/gsd-t-resume`). **Plain text messages — especially questions — should be answered conversationally.** Do not launch into workflow execution, file reading, or phase advancement from a question or comment. If the user wants work done, they will invoke a command.
 
+## Auto-Init Guard
+
+Before executing any GSD-T workflow command, check if **any** of these files are missing in the current project:
+- `.gsd-t/progress.md`, `.gsd-t/backlog.md`, `.gsd-t/backlog-settings.md`
+- `.gsd-t/contracts/`, `.gsd-t/domains/`
+- `.claude/settings.local.json` (if `~/.claude/settings.local` exists)
+- `CLAUDE.md`, `README.md`
+- `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`
+
+If any are missing:
+1. Run `gsd-t-init` automatically (it skips files that already exist)
+2. Then continue with the originally requested command
+
+**Exempt commands** (do not trigger auto-init): `gsd-t-init`, `gsd-t-init-scan-setup`, `gsd-t-help`, `gsd-t-version-update`, `gsd-t-version-update-all`, `gsd-t-prompt`, `gsd-t-brainstorm`.
+
 ## Prime Rule
 KEEP GOING. Only stop for:
 1. Unrecoverable errors after 2 fix attempts