@tekyzinc/gsd-t 2.20.7 → 2.22.0

package/docs/workflows.md

@@ -0,0 +1,67 @@
+# Workflows — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## User Workflows
+
+### Install GSD-T
+1. Run `npx @tekyzinc/gsd-t install`
+2. CLI copies commands to `~/.claude/commands/`
+3. CLI sets up global CLAUDE.md if missing
+4. CLI installs heartbeat hooks
+5. User starts Claude Code in their project
+
+**Entry point**: `npx @tekyzinc/gsd-t install`
+**Success**: 41 commands available in Claude Code
+**Failure**: CLI reports missing Node.js or permission errors
+
+### Initialize a Project
+1. User runs `/gsd-t-init` in Claude Code
+2. Init creates `.gsd-t/` directory structure
+3. Init creates or updates CLAUDE.md
+4. Init creates `docs/` living documents if missing
+5. Init scans existing codebase if code exists
+
+**Entry point**: `/gsd-t-init` slash command
+**Success**: Project ready for milestone definition
+**Failure**: Reports what couldn't be created
+
+### Full Wave Cycle
+1. User defines milestone via `/gsd-t-milestone`
+2. Partition decomposes into domains + contracts
+3. Plan creates task lists per domain
+4. Execute implements tasks (solo or team)
+5. Test-sync aligns tests with code changes
+6. Integrate wires domains together
+7. Verify runs quality gates
+8. Complete-milestone archives and tags
+
+**Entry point**: `/gsd-t-wave` or manual phase-by-phase
+**Success**: Milestone completed, version bumped, git tagged
+**Failure**: Wave pauses at failing phase, user can fix and resume
+
+## Technical Workflows
+
+### CLI Update Check
+1. CLI reads cached version from `~/.claude/.gsd-t-update-cache`
+2. If cache is older than 1 hour, query npm registry
+3. Compare installed vs. latest using semver
+4. Display update notice if newer version available
+
+**Trigger**: Every CLI invocation and `/gsd-t-status`
+**Frequency**: Cached, actual fetch at most once per hour
+
+### Heartbeat Event Logging
+1. Claude Code hook fires on tool call or notification
+2. `gsd-t-heartbeat.js` appends JSONL event to `.gsd-t/heartbeat-{session}.jsonl`
+3. Events include timestamp, type, and context
+
+**Trigger**: Claude Code hooks (9 event types)
+**Frequency**: On every hooked event during a session
+
+## Integration Workflows
+
+### npm Publish
+- **Trigger**: Manual `npm publish` after milestone completion
+- **Flow**: Version bumped → CHANGELOG updated → git tagged → npm publish
+- **Verification**: `npx @tekyzinc/gsd-t status` on fresh install

package/examples/.gsd-t/domains/example-domain/scope.md

@@ -1,15 +1,13 @@
-# Domain: auth — Example
-
-## Responsibility
-Handles all authentication and authorization: user registration, login, JWT token generation and verification, password hashing, and auth middleware for protecting routes.
-
-## Files Owned
-- `src/auth/` — all auth service code
-- `src/middleware/auth.py` — auth middleware
-- `tests/auth/` — auth tests
-
-## Inputs (from other domains)
-- schema-contract.md: Users table structure for lookups
-
-## Outputs (to other domains)
-- api-contract.md: POST /api/auth/login, POST /api/auth/register, GET /api/users/me
+# Domain: auth — Example
+
+## Responsibility
+Handles all authentication and authorization: user registration, login, JWT token generation and verification, password hashing, and auth middleware for protecting routes.
+
+## Owned Files/Directories
+- `src/auth/` — all auth service code
+- `src/middleware/auth.py` — auth middleware
+- `tests/auth/` — auth tests
+
+## NOT Owned (do not modify)
+- `src/db/` — owned by data-layer domain
+- `src/api/` — owned by api domain (except auth endpoints)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.20.7",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 41 slash commands with backlog management, impact analysis, test sync, and milestone archival",
+  "version": "2.22.0",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 42 slash commands with backlog management, impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {

package/scripts/gsd-t-heartbeat.js

@@ -55,6 +55,8 @@ process.stdin.on("end", () => {
     const event = buildEvent(hook);
     if (event) {
       cleanupOldHeartbeats(gsdtDir);
+      // Symlink check — prevent redirection of event data to arbitrary files
+      try { if (fs.lstatSync(file).isSymbolicLink()) return; } catch { /* file doesn't exist yet — safe */ }
       fs.appendFileSync(file, JSON.stringify(event) + "\n");
     }
   } catch (e) {
@@ -69,7 +71,8 @@ function cleanupOldHeartbeats(gsdtDir) {
     for (const f of files) {
       if (!f.startsWith("heartbeat-") || !f.endsWith(".jsonl")) continue;
       const fp = path.join(gsdtDir, f);
-      const stat = fs.statSync(fp);
+      const stat = fs.lstatSync(fp);
+      if (stat.isSymbolicLink()) continue; // Don't follow symlinks
       if (now - stat.mtimeMs > MAX_AGE_MS) {
         fs.unlinkSync(fp);
       }

package/scripts/npm-update-check.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/**
+ * Background update check — spawned detached by the CLI to refresh the version cache.
+ * Usage: node npm-update-check.js <cache-file-path>
+ */
+
+const https = require("https");
+const fs = require("fs");
+
+const cacheFile = process.argv[2];
+if (!cacheFile) process.exit(1);
+
+https.get("https://registry.npmjs.org/@tekyzinc/gsd-t/latest",
+  { timeout: 5000 }, (res) => {
+  let d = "";
+  res.on("data", (c) => d += c);
+  res.on("end", () => {
+    try {
+      const v = JSON.parse(d).version;
+      if (v && /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/.test(v)) {
+        fs.writeFileSync(cacheFile,
+          JSON.stringify({ latest: v, timestamp: Date.now() }));
+      }
+    } catch { /* malformed response — skip */ }
+  });
+}).on("error", () => {});