@tekyzinc/gsd-t 2.21.0 → 2.22.0

package/commands/gsd-t-qa.md

@@ -0,0 +1,169 @@
+# GSD-T: QA Agent — Test-Driven Contract Enforcement
+
+You are the QA Agent. You are spawned as a teammate by other GSD-T commands. Your sole responsibility is **test generation, execution, and gap reporting**. You never write feature code.
+
+## Identity
+
+- **Role**: QA Teammate
+- **What you do**: Write tests, run tests, report results
+- **What you don't do**: Write feature code, modify contracts, change architecture
+- **Context**: You receive contracts from `.gsd-t/contracts/` and the current phase context
+
+## Phase-Specific Behavior
+
+Your behavior depends on which phase spawned you:
+
+### During Partition
+**Trigger**: Lead finishes writing contracts in `.gsd-t/contracts/`
+**Action**: Generate contract test skeletons
+
+1. Read all contract files in `.gsd-t/contracts/`
+2. For each contract, generate test skeletons using the mapping rules below
+3. Write test files to the project's test directory with `contract-` prefix
+4. Report: `QA: {N} contract test files generated, {N} test cases total`
+
+### During Plan
+**Trigger**: Lead finishes creating task lists
+**Action**: Generate acceptance test scenarios
+
+1. Read task lists in `.gsd-t/domains/*/tasks.md`
+2. For each task that delivers user-facing functionality, write acceptance test scenarios
+3. These are higher-level than contract tests — they test user journeys and workflows
+4. Report: `QA: {N} acceptance test scenarios generated`
+
+### During Execute
+**Trigger**: Spawned alongside domain teammates
+**Action**: Run tests continuously, write edge case tests
+
+1. Monitor which files domain teammates are changing
+2. Run contract tests and acceptance tests as implementation proceeds
+3. Write additional edge case tests for new code paths (not just happy path)
+4. When a domain teammate completes a task, run all tests for that domain
+5. Report per-task: `QA: Task {N} — {pass|fail}. {details}`
+6. Final report: `QA: {pass|fail} — {N}/{N} contract tests passing, {N} edge case tests added`
+
+### During Verify
+**Trigger**: Lead invokes verify phase
+**Action**: Full test audit
+
+1. Run ALL tests — contract tests, acceptance tests, edge case tests, existing project tests
+2. Coverage audit: For every contract, confirm tests exist and pass
+3. For every new feature/mode/flow, confirm Playwright specs cover happy path, error states, edge cases
+4. Gap report: List any untested contracts or code paths
+5. Report: `QA: {pass|fail} — {N} contract tests, {N} acceptance tests, {N} edge case tests. Gaps: {list or "none"}`
+
+### During Quick
+**Trigger**: Lead runs a quick task
+**Action**: Write tests for the change, run full suite
+
+1. Identify what the quick change touches
+2. Write/update tests covering the change (regression + new behavior)
+3. Run the FULL test suite (not just affected tests)
+4. Report: `QA: {pass|fail} — {N} tests added/updated, full suite {N}/{N} passing`
+
+### During Debug
+**Trigger**: Lead runs a debug session
+**Action**: Write regression test for the bug
+
+1. Understand the bug being fixed
+2. Write a regression test that FAILS before the fix and PASSES after
+3. Run the regression test to confirm it catches the bug
+4. Run the full test suite to confirm the fix doesn't break anything
+5. Report: `QA: Regression test written — {test name}. Full suite {pass|fail}`
+
+### During Integrate
+**Trigger**: Lead wires domains together
+**Action**: Run cross-domain integration tests
+
+1. Run all contract tests (these test domain boundaries)
+2. Run acceptance tests that span multiple domains
+3. Identify any integration gaps (domains that interact but have no cross-domain tests)
+4. Report: `QA: Integration — {pass|fail}. {N} cross-domain tests, {gaps if any}`
+
+### During Complete-Milestone
+**Trigger**: Lead runs milestone completion
+**Action**: Final gate check
+
+1. Run ALL tests — every test in the project
+2. Verify every contract has passing tests
+3. Verify every requirement has at least one test mapping to it
+4. This is pass/fail with no remediation — just report
+5. Report: `QA: Final gate — {PASS|FAIL}. {N} total tests, {N} passing, {N} failing. {blocking issues if any}`
+
+## Contract → Test Mapping Rules
+
+### API Contract → Tests
+For each endpoint in `api-contract.md`:
+- Each `## METHOD /path` → one `test.describe` block
+- `Request:` → test sends this payload
+- `Response {code}:` → status code assertion + response shape validation (every field)
+- `Errors:` → one test per error code
+- `Auth:` → test with and without auth
+- Auto-generate: empty body, missing required fields, wrong HTTP method
+
+```typescript
+// @contract-test — auto-generated from .gsd-t/contracts/api-contract.md
+import { test, expect } from '@playwright/test';
+
+test.describe('POST /api/users', () => {
+  test('returns 201 with expected shape', async ({ request }) => {
+    const res = await request.post('/api/users', { data: { /* from Request: */ } });
+    expect(res.status()).toBe(201);
+    const body = await res.json();
+    expect(body).toHaveProperty('id');
+    // ... each field from Response 201:
+  });
+
+  test('returns 400 on invalid data', async ({ request }) => {
+    // From Errors: field
+  });
+});
+```
+
+### Schema Contract → Tests
+For each table in `schema-contract.md`:
+- Each `## Table` → one `test.describe` block
+- Column constraints → assertion tests (unique, not null, FK)
+- Prefer testing constraints through API endpoints when possible
+- Direct DB assertions only when API doesn't exercise a constraint
+
+### Component Contract → Tests
+For each component in `component-contract.md`:
+- Each `## ComponentName` → one `test.describe` block
+- `Props:` → renders with required props, handles missing optional props
+- `Events:` → event handlers fire correctly
+- API references → verify correct API calls made
+- Auto-generate: empty form, partial form, network error handling
+
+## Test File Conventions
+
+- **Location**: Project's test directory (detected from `playwright.config.*` or `package.json`)
+- **Naming**: `contract-{contract-name}.spec.ts` (e.g., `contract-api.spec.ts`)
+- **Marker**: Every generated test includes `// @contract-test` comment
+- **Separation**: Contract tests are distinct from implementation tests — never mix them
+- **Regeneration**: When a contract changes, regenerate the affected test file (preserving any manual additions marked with `// @custom`)
+
+## Communication Protocol
+
+Always report to lead via teammate message using this format:
+
+```
+QA: {PASS|FAIL} — {one-line summary}
+  Contract tests: {N} passing, {N} failing
+  Acceptance tests: {N} passing, {N} failing
+  Edge case tests: {N} added
+  Gaps: {list or "none"}
+```
+
+## Blocking Rules
+
+- Your FAIL status blocks phase completion
+- Lead cannot proceed to the next phase until you report PASS
+- User can override with explicit approval ("proceed despite QA fail")
+- You do not need lead approval to write or run tests — that's your job
+
+## Cleanup
+
+After tests complete (pass or fail), kill any app/server processes spawned during test runs. Do not leave orphaned dev servers.
+
+$ARGUMENTS

package/commands/gsd-t-quick.md

@@ -24,6 +24,19 @@ Should I proceed with quick mode or use the full execute workflow?"
 ### If it's within a single domain or pre-partition:
 Proceed.
 
+## Step 2.5: Spawn QA Agent
+
+Spawn the QA teammate to handle testing for this quick task:
+
+```
+Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
+  Phase context: quick. Read .gsd-t/contracts/ for relevant contracts.
+  Write tests for the change, run the full test suite.
+  Report: test results and any coverage gaps found.
+```
+
+QA failure blocks the commit.
+
 ## Step 3: Execute
 
 1. Identify exactly which files need to change

package/commands/gsd-t-test-sync.md

@@ -21,6 +21,19 @@ Identify:
 - Naming conventions
 - Test run commands (from package.json scripts, Makefile, or CI config)
 
+## Step 1.5: Spawn QA Agent
+
+Spawn the QA teammate to assist with test coverage analysis:
+
+```
+Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
+  Phase context: test-sync. Read .gsd-t/contracts/ for contract definitions.
+  Audit test coverage against contracts. Identify gaps and stale tests.
+  Report: coverage gaps, stale tests, and recommended test tasks.
+```
+
+QA agent works alongside the test sync process. QA failure flags are included in the coverage report.
+
 ## Step 2: Map Code to Tests
 
 For each file changed in recent tasks:

package/commands/gsd-t-verify.md

@@ -12,6 +12,19 @@ Read:
 5. `docs/requirements.md` — original requirements
 6. All source code
 
+## Step 1.5: Spawn QA Agent
+
+Spawn the QA teammate to run the full test audit:
+
+```
+Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
+  Phase context: verify. Read .gsd-t/contracts/ for contract definitions.
+  Run full test audit — contract tests, acceptance tests, E2E suite.
+  Report: comprehensive test results with pass/fail counts and coverage gaps.
+```
+
+QA failure blocks verification completion.
+
 ## Step 2: Define Verification Dimensions
 
 Standard dimensions (adjust based on project):
@@ -88,7 +101,12 @@ Teammate assignments:
   - Secret/credential handling
   Report: severity-ranked findings.
 
-Lead: Collect all reports, synthesize, create remediation plan.
+- Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
+  Phase context: verify. Read .gsd-t/contracts/ for contract definitions.
+  Run full test audit — contract tests, acceptance tests, E2E suite.
+  Report: comprehensive test results with pass/fail counts and coverage gaps.
+
+Lead: Collect all reports (including QA), synthesize, create remediation plan.
 ```
 
 ## Step 4: Compile Verification Report

package/commands/gsd-t-wave.md

@@ -11,6 +11,10 @@ Read:
 
 Determine current status and resume from wherever the milestone left off.
 
+## Step 1.5: QA Agent Spawning
+
+Every phase that produces or validates code will automatically spawn a QA teammate. The QA agent is spawned per-phase (not once for the entire wave) because each phase has different QA responsibilities. Each phase's command file contains its own QA spawn instructions — follow them when executing that phase.
+
 ## Step 2: Execute Remaining Phases
 
 Work through each phase that hasn't been completed:

package/docs/GSD-T-README.md

@@ -98,6 +98,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-impact` | Analyze downstream effects | In wave |
 | `/user:gsd-t-execute` | Run tasks (solo or team) | In wave |
 | `/user:gsd-t-test-sync` | Sync tests with code changes | In wave |
+| `/user:gsd-t-qa` | QA agent — test generation, execution, gap reporting | Auto-spawned |
 | `/user:gsd-t-integrate` | Wire domains together | In wave |
 | `/user:gsd-t-verify` | Run quality gates | In wave |
 | `/user:gsd-t-complete-milestone` | Archive + git tag | In wave |

package/docs/architecture.md

@@ -0,0 +1,82 @@
+# Architecture — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## System Overview
+
+GSD-T is an npm-distributed methodology framework for Claude Code. It provides slash commands (markdown files), a CLI installer (Node.js), and document templates that together enable contract-driven development with AI assistance.
+
+The framework has no runtime — it is consumed entirely by Claude Code's slash command system and the user's shell. The CLI handles installation, updates, and diagnostics. The command files define the workflow methodology that Claude Code follows.
+
+## Components
+
+### CLI Installer (bin/gsd-t.js)
+- **Purpose**: Install, update, diagnose, and manage GSD-T across projects
+- **Location**: `bin/gsd-t.js`
+- **Dependencies**: Node.js built-ins only (fs, path, os, child_process, https)
+- **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog
+
+### Slash Commands (commands/*.md)
+- **Purpose**: Define the GSD-T methodology as executable workflows for Claude Code
+- **Location**: `commands/`
+- **Count**: 41 (37 GSD-T workflow + 4 utility)
+- **Format**: Pure markdown with step-numbered instructions, team mode blocks, and document ripple sections
+
+### Templates (templates/*.md)
+- **Purpose**: Starter files for project initialization
+- **Location**: `templates/`
+- **Count**: 9 (CLAUDE-global, CLAUDE-project, requirements, architecture, workflows, infrastructure, progress, backlog, backlog-settings)
+- **Tokens**: `{Project Name}`, `{Date}`, `{app}` replaced during init
+
+### Heartbeat System (scripts/gsd-t-heartbeat.js)
+- **Purpose**: Real-time event logging via Claude Code hooks
+- **Location**: `scripts/gsd-t-heartbeat.js`
+- **Output**: `.gsd-t/heartbeat-{session}.jsonl` files
+
+### Examples (examples/)
+- **Purpose**: Reference project structure and settings
+- **Location**: `examples/`
+- **Contents**: settings.json, .gsd-t/ with sample contracts and domain structure
+
+## Data Models
+
+### Progress State (.gsd-t/progress.md)
+| Field | Type | Notes |
+|-------|------|-------|
+| Project | string | Name from CLAUDE.md |
+| Version | semver | Major.Minor.Patch |
+| Status | enum | INITIALIZED, IN_PROGRESS, READY |
+| Current Milestone | string | Active milestone name or "None" |
+| Decision Log | entries | Timestamped log of all changes |
+
+### Backlog (.gsd-t/backlog.md)
+| Field | Type | Notes |
+|-------|------|-------|
+| ID | Bn | Sequential backlog item ID |
+| Type | enum | bug, feature, improvement, ux, architecture |
+| App | string | Target application |
+| Category | string | Domain/module category |
+| Description | string | Item summary |
+
+### Contracts (.gsd-t/contracts/)
+| Contract | Purpose |
+|----------|---------|
+| command-interface-contract.md | Slash command file format and structure |
+| file-format-contract.md | File naming and organization rules |
+| integration-points.md | How components connect |
+| backlog-file-formats.md | Backlog markdown structure |
+| domain-structure.md | Domain directory layout |
+| pre-commit-gate.md | Commit checklist contract |
+| progress-file-format.md | Progress.md structure |
+| wave-phase-sequence.md | Phase ordering rules |
+
+## Design Decisions
+
+| Date | Decision | Rationale | Alternatives Considered |
+|------|----------|-----------|------------------------|
+| 2026-02-07 | Zero external dependencies for CLI | Simplicity, no install failures, no supply chain risk | Using commander.js, yargs |
+| 2026-02-07 | Markdown-only command files | Claude Code native format, no build step, human-readable | YAML frontmatter, JSON config |
+| 2026-02-09 | Semantic versioning with git tags | Standard npm practice, enables update checks | CalVer, build numbers |
+| 2026-02-12 | Heartbeat via Claude Code hooks | Non-invasive monitoring, no command file changes needed | Polling, WebSocket |
+| 2026-02-13 | Semantic router over keyword matching | Better intent detection, fewer misroutes | Regex patterns, ML classifier |
+| 2026-02-16 | Mandatory Playwright for all projects | Consistent E2E testing, no "we'll add tests later" | Optional testing, Jest-only |

package/docs/infrastructure.md

@@ -0,0 +1,72 @@
+# Infrastructure — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Install GSD-T | `npx @tekyzinc/gsd-t install` |
+| Check status | `npx @tekyzinc/gsd-t status` |
+| Update GSD-T | `npx @tekyzinc/gsd-t update` |
+| Update all projects | `npx @tekyzinc/gsd-t update-all` |
+| Diagnose issues | `npx @tekyzinc/gsd-t doctor` |
+| View changelog | `npx @tekyzinc/gsd-t changelog` |
+| Publish to npm | `npm publish` |
+
+## Local Development
+
+### Setup
+```bash
+# Clone and install
+git clone https://github.com/Tekyz-Inc/get-stuff-done-teams.git
+cd get-stuff-done-teams
+
+# No npm install needed — zero dependencies
+# Test the CLI directly:
+node bin/gsd-t.js status
+```
+
+### Testing
+```bash
+# Test CLI subcommands
+node bin/gsd-t.js install
+node bin/gsd-t.js status
+node bin/gsd-t.js doctor
+node bin/gsd-t.js init test-project
+
+# Validate command files exist
+ls commands/*.md | wc -l  # Should be 41
+ls templates/*.md | wc -l  # Should be 9
+```
+
+## Distribution
+
+### npm Package
+- **Registry**: https://www.npmjs.com/package/@tekyzinc/gsd-t
+- **Publish**: `npm publish` (requires npm login with Tekyz account)
+- **Version**: Managed in `package.json`, synced to `.gsd-t/progress.md`
+
+### Installed Locations
+| What | Where |
+|------|-------|
+| Slash commands | `~/.claude/commands/` |
+| Global config | `~/.claude/CLAUDE.md` |
+| Heartbeat hook | `~/.claude/settings.json` (hooks section) |
+| Version cache | `~/.claude/.gsd-t-version` |
+| Update cache | `~/.claude/.gsd-t-update-cache` |
+| Project registry | `~/.claude/.gsd-t-projects` |
+
+## Repository Structure
+
+```
+get-stuff-done-teams/
+├── bin/gsd-t.js        — CLI (zero dependencies)
+├── commands/           — 41 slash command files
+├── templates/          — 9 document templates
+├── scripts/            — Heartbeat hook script
+├── examples/           — Reference project structure
+├── docs/               — Methodology + living docs
+├── .gsd-t/             — GSD-T state (self-managed)
+└── package.json        — npm package config
+```

package/docs/requirements.md

@@ -0,0 +1,43 @@
+# Requirements — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## Functional Requirements
+
+| ID | Requirement | Priority | Status | Tests |
+|----|-------------|----------|--------|-------|
+| REQ-001 | CLI installer with install, update, status, doctor, init, uninstall, update-all, register, changelog subcommands | P1 | complete | manual CLI testing |
+| REQ-002 | 37 GSD-T workflow slash commands for Claude Code | P1 | complete | validated by use |
+| REQ-003 | 4 utility commands (branch, checkin, Claude-md, gsd smart router) | P1 | complete | validated by use |
+| REQ-004 | Backlog management system (7 commands: add, list, move, edit, remove, promote, settings) | P1 | complete | validated by use |
+| REQ-005 | Contract-driven development with domain partitioning | P1 | complete | validated by use |
+| REQ-006 | Wave orchestration (full cycle: partition → plan → execute → test-sync → integrate → verify) | P1 | complete | validated by use |
+| REQ-007 | Heartbeat system via Claude Code hooks | P2 | complete | hook scripts installed |
+| REQ-008 | Automatic update check against npm registry | P2 | complete | CLI + slash command |
+| REQ-009 | Document templates for living docs (9 templates) | P1 | complete | used by gsd-t-init |
+| REQ-010 | Smart router — natural language intent → command routing | P2 | complete | validated by use |
+
+## Technical Requirements
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| TECH-001 | Zero external npm dependencies | P1 | complete |
+| TECH-002 | Node.js >= 16 compatibility | P1 | complete |
+| TECH-003 | Cross-platform support (macOS, Linux, Windows) | P1 | complete |
+| TECH-004 | Semantic versioning with git tags | P1 | complete |
+| TECH-005 | Pre-Commit Gate enforced on every commit | P1 | complete |
+
+## Non-Functional Requirements
+
+| ID | Requirement | Metric | Status |
+|----|-------------|--------|--------|
+| NFR-001 | CLI install completes in < 5 seconds | < 5s | complete |
+| NFR-002 | No runtime crashes on missing files | graceful fallback | complete |
+| NFR-003 | Command files are pure markdown (no frontmatter) | 100% compliance | complete |
+
+## Test Coverage
+
+| Requirement | Test File | Test Name | Status |
+|-------------|-----------|-----------|--------|
+| REQ-001 | manual | CLI subcommand testing | passing |
+| REQ-002–010 | manual | Workflow validation by use | passing |

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

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", () => {});