@tekyzinc/gsd-t 2.23.0 → 2.24.6

package/docs/infrastructure.md

@@ -1,6 +1,6 @@
 # Infrastructure — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18
+## Last Updated: 2026-02-18 (Scan #5)
 
 ## Quick Reference
 
@@ -12,7 +12,8 @@
 | 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` |
+| Register project | `npx @tekyzinc/gsd-t register` |
+| Publish to npm | `npm publish` (runs `npm test` automatically via prepublishOnly) |
 
 ## Local Development
 
@@ -29,44 +30,65 @@ node bin/gsd-t.js status
 
 ### Testing
 ```bash
-# Test CLI subcommands
+# Run automated test suite (116 tests, zero dependencies)
+npm test
+
+# Test CLI subcommands manually
 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 commands/*.md | wc -l  # Should be 43
 ls templates/*.md | wc -l  # Should be 9
 ```
 
+### Scripts
+| Script | Purpose |
+|--------|---------|
+| `scripts/gsd-t-heartbeat.js` | Claude Code hook event logger (JSONL output, secret scrubbing) |
+| `scripts/npm-update-check.js` | Background npm registry version checker (path-validated) |
+| `scripts/gsd-t-fetch-version.js` | Synchronous npm registry fetch (5s timeout, 1MB limit) |
+
 ## 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`
+- **Files shipped**: `bin/`, `commands/`, `scripts/`, `templates/`, `examples/`, `docs/`, `CHANGELOG.md`
 
 ### Installed Locations
 | What | Where |
 |------|-------|
-| Slash commands | `~/.claude/commands/` |
+| Slash commands (43 files) | `~/.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` |
+| Heartbeat script | `~/.claude/scripts/gsd-t-heartbeat.js` |
+| Hook configuration | `~/.claude/settings.json` (hooks section) |
+| Version file | `~/.claude/.gsd-t-version` |
+| Update cache | `~/.claude/.gsd-t-update-check` |
 | Project registry | `~/.claude/.gsd-t-projects` |
 
 ## Repository Structure
 
 ```
 get-stuff-done-teams/
-├── bin/gsd-t.js        — CLI (zero dependencies)
-├── commands/           — 41 slash command files
+├── bin/gsd-t.js        — CLI installer (~1,300 lines, zero dependencies)
+├── commands/           — 43 slash command files (39 GSD-T + 4 utility)
+├── scripts/            — 3 hook/utility scripts
 ├── 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
 ```
+
+## Security Notes
+
+- Zero npm dependencies — no supply chain risk
+- All file writes check for symlinks first
+- Input validation on project names, versions, session IDs, paths
+- Heartbeat stdin capped at 1MB
+- HTTP requests use HTTPS with timeouts
+- Init operations use exclusive file creation (`{ flag: "wx" }`)

package/docs/requirements.md

@@ -1,21 +1,24 @@
 # Requirements — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18
+## Last Updated: 2026-02-18 (Scan #5)
 
 ## 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-002 | 39 GSD-T workflow slash commands for Claude Code (incl. QA agent) | P1 | complete | validated by use |
+| REQ-003 | 4 utility commands (gsd smart router, branch, checkin, Claude-md) | 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-006 | Wave orchestration (full cycle: partition → discuss → plan → impact → execute → test-sync → integrate → verify → complete) | P1 | complete | validated by use |
+| REQ-007 | Heartbeat system via Claude Code hooks (9 events, JSONL output, 7-day cleanup) | P2 | complete | hook scripts installed |
+| REQ-008 | Automatic update check against npm registry (1h cache, background refresh) | P2 | complete | CLI + slash command |
+| REQ-009 | Document templates for living docs (9 templates with token replacement) | P1 | complete | used by gsd-t-init |
 | REQ-010 | Smart router — natural language intent → command routing | P2 | complete | validated by use |
+| REQ-011 | Triage and merge — auto-review, score, merge safe GitHub branches | P2 | complete | validated by use |
+| REQ-012 | QA Agent — test-driven contract enforcement spawned in 10 phases | P1 | complete | validated by use |
+| REQ-013 | Wave orchestrator — agent-per-phase execution with fresh context windows | P1 | complete | validated by use |
 
 ## Technical Requirements
 
@@ -25,19 +28,46 @@
 | 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 |
+| TECH-005 | Pre-Commit Gate enforced on every commit | P1 | complete (manual, not automated) |
+| TECH-006 | Symlink protection on all file write operations | P1 | complete |
+| TECH-007 | Input validation on project names, versions, paths, session IDs | P1 | complete |
+| TECH-008 | prepublishOnly gate — `npm test` runs before `npm publish` | P1 | complete (M8) |
 
 ## Non-Functional Requirements
 
 | ID | Requirement | Metric | Status |
 |----|-------------|--------|--------|
-| NFR-001 | CLI install completes in < 5 seconds | < 5s | complete |
+| NFR-001 | CLI install completes quickly | < 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 |
+| NFR-004 | Heartbeat auto-cleanup prevents unbounded growth | 7-day TTL | complete |
+| NFR-005 | Update check is non-blocking after first run | background process | 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 |
+| REQ-001 | test/helpers.test.js, test/filesystem.test.js | CLI subcommand + helper tests | passing (64 tests) |
+| REQ-006 | test/cli-quality.test.js | Wave-related function tests (buildEvent, etc.) | passing (22 tests) |
+| REQ-007 | test/security.test.js | Heartbeat security (scrubSecrets, scrubUrl) | passing (30 tests) |
+| REQ-002–005, 008–013 | manual | Workflow validation by use | passing |
+
+**Total automated tests**: 116 across 4 test files (M4, M5, M6). Runner: `node --test` (zero dependencies).
+
+## Gaps Identified
+
+### Open (Scan #5 — 2026-02-18)
+- 10 new LOW items: TD-056 through TD-065 (cosmetic code quality, documentation fixes, contract alignment)
+- See `.gsd-t/techdebt.md` for full list (all LOW severity, no functional issues)
+
+### Resolved (Milestones 3-8, 2026-02-18/19)
+- ~~All scan #4 items (TD-044-TD-055)~~ — RESOLVED (M8)
+- ~~No automated test suite (TD-003)~~ — RESOLVED (116 tests, M4)
+- ~~Command count 42→43 not updated (TD-022)~~ — RESOLVED (M3)
+- ~~QA agent contract missing test-sync (TD-042)~~ — RESOLVED (M3)
+- ~~Wave bypassPermissions not documented (TD-035)~~ — RESOLVED (M5)
+- ~~All 15 scan #3 functions >30 lines (TD-021)~~ — RESOLVED (M6, all 81 functions ≤30 lines)
+- ~~34 fractional step numbers (TD-031)~~ — RESOLVED (M7, all renumbered)
+- ~~Backlog file format drift (TD-014)~~ — RESOLVED
+- ~~Progress.md format drift (TD-015)~~ — RESOLVED
+- ~~7 backlog commands missing from GSD-T-README (TD-016)~~ — RESOLVED

package/docs/workflows.md

@@ -1,67 +1,120 @@
 # Workflows — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18
+## Last Updated: 2026-02-18 (Scan #5)
 
 ## 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
+2. CLI copies 43 commands to `~/.claude/commands/`
+3. CLI sets up global CLAUDE.md if missing (appends with separator if exists)
+4. CLI installs heartbeat script to `~/.claude/scripts/`
+5. CLI configures 9 hooks in `~/.claude/settings.json`
+6. CLI saves version to `~/.claude/.gsd-t-version`
+7. User starts Claude Code in their project
 
 **Entry point**: `npx @tekyzinc/gsd-t install`
-**Success**: 41 commands available in Claude Code
+**Success**: 43 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
+1. User runs `/gsd-t-init [name]` in Claude Code (or `gsd-t init [name]` CLI)
+2. Init creates `.gsd-t/` directory with progress.md, backlog.md, backlog-settings.md, contracts/, domains/
+3. Init creates or updates CLAUDE.md (project-level) using template with token replacement
+4. Init creates `docs/` living documents (requirements, architecture, workflows, infrastructure) if missing
+5. Init auto-registers project in `~/.claude/.gsd-t-projects`
+6. All file creation uses `{ flag: "wx" }` — never overwrites existing files
 
-**Entry point**: `/gsd-t-init` slash command
+**Entry point**: `/gsd-t-init` slash command or `gsd-t init` CLI
 **Success**: Project ready for milestone definition
-**Failure**: Reports what couldn't be created
+**Failure**: Reports what couldn't be created (existing files preserved)
 
 ### 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
+2. **Partition**: Decompose into domains + contracts (file ownership, interfaces)
+3. **Discuss**: Explore design decisions (always pauses, even Level 3) — SKIPPABLE via structured 3-condition check: single domain, no open questions in Decision Log, all cross-domain contracts exist (M7)
+4. **Plan**: Create atomic task lists per domain with dependencies
+5. **Impact**: Analyze downstream effects (PROCEED / CAUTION / BLOCK verdicts)
+6. **Execute**: Implement tasks (solo or team mode based on domain count)
+7. **Test-Sync**: Align tests with code changes, verify coverage
+8. **Integrate**: Wire domains at boundaries, verify contracts honored
+9. **Verify**: Run 7 quality gate dimensions (functional, contracts, quality, tests, E2E, security, integration)
+10. **Complete**: Archive to `.gsd-t/milestones/`, bump version, git tag
+
+**Entry point**: `/gsd-t-wave` (auto-advances) or manual phase-by-phase
 **Success**: Milestone completed, version bumped, git tagged
-**Failure**: Wave pauses at failing phase, user can fix and resume
+**Failure**: Wave pauses at failing phase; user can fix and resume
+
+### Autonomy Levels
+| Level | Behavior |
+|-------|----------|
+| Level 1 (Supervised) | Pause at each phase for confirmation |
+| Level 2 (Standard) | Pause only at milestones |
+| Level 3 (Full Auto) | Auto-advance; only stop for Destructive Guard, Impact BLOCK, errors after 2 attempts, Discuss |
+
+### Error Recovery (2-Attempt Rule)
+| Failure | Recovery | After 2 Failures |
+|---------|----------|-------------------|
+| Impact BLOCK | Add remediation tasks, re-run | STOP and report |
+| Test failures | Fix and re-run | STOP and report |
+| Verify failure | Remediate and re-verify | STOP and report |
+| Gap analysis gaps | Auto-fix and re-analyze | STOP and report |
 
 ## 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
+1. CLI reads cached version from `~/.claude/.gsd-t-update-check` (JSON: `{ latest, timestamp }`)
+2. If cache is fresh (<1 hour): show notice if cached latest > installed
+3. If no cache: synchronous fetch to npm registry (8s timeout), cache result
+4. If cache stale (>1 hour): spawn detached background `scripts/npm-update-check.js`
+5. Compare versions using `isNewerVersion()` semver comparison
 
-**Trigger**: Every CLI invocation and `/gsd-t-status`
-**Frequency**: Cached, actual fetch at most once per hour
+**Trigger**: Every CLI invocation (except install/update/update-all)
+**Also**: `/gsd-t-status` slash command checks independently
 
 ### 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
+1. Claude Code hook fires (9 events: SessionStart, PostToolUse, SubagentStart, SubagentStop, TaskCompleted, TeammateIdle, Notification, Stop, SessionEnd)
+2. `settings.json` hook calls `node ~/.claude/scripts/gsd-t-heartbeat.js`
+3. Script reads JSON from stdin (capped at 1MB)
+4. Validates session_id (alphanumeric regex), validates path is absolute and within `.gsd-t/`
+5. Builds structured event with timestamp, type-specific data (tool summaries, file paths)
+6. Appends JSONL to `.gsd-t/heartbeat-{session_id}.jsonl`
+7. Runs cleanup: removes heartbeat files older than 7 days
 
 **Trigger**: Claude Code hooks (9 event types)
 **Frequency**: On every hooked event during a session
 
+### Version Bump Rules
+| Context | Change Type | Bump |
+|---------|-------------|------|
+| Complete-milestone | Breaking changes, major rework | Major |
+| Complete-milestone | New features, feature milestones | Minor |
+| Complete-milestone | Bug fixes, cleanup | Patch |
+| Checkin | New features, new commands | Minor |
+| Checkin | Bug fixes, docs, refactors | Patch (default) |
+| Checkin | Breaking changes | Major |
+
+Updated in: package.json, .gsd-t/progress.md, CHANGELOG.md, git tag
+
+### Pre-Commit Gate
+Every commit must pass applicable checks:
+1. Branch guard (correct branch?)
+2. Contract updates (API, schema, component)
+3. Scope updates (new files → domain scope.md)
+4. Documentation updates (requirements, architecture)
+5. Decision Log entry (timestamped in progress.md)
+6. Tech debt tracking (discovered/fixed?)
+7. Test execution (affected tests pass?)
+
 ## Integration Workflows
 
 ### npm Publish
 - **Trigger**: Manual `npm publish` after milestone completion
-- **Flow**: Version bumped → CHANGELOG updated → git tagged → npm publish
+- **Pre-publish gate**: `prepublishOnly: "npm test"` runs 116 tests before publish (M8)
+- **Flow**: Version bumped → CHANGELOG updated → git tagged → `npm publish` → tests run automatically → published
 - **Verification**: `npx @tekyzinc/gsd-t status` on fresh install
+
+### Update All Projects
+- **Trigger**: `gsd-t update-all` CLI command
+- **Flow**: Global update → iterate registered projects → inject Destructive Action Guard → create CHANGELOG → health check (Playwright, Swagger)
+- **Registry**: `~/.claude/.gsd-t-projects` (newline-separated absolute paths)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.23.0",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 42 slash commands with backlog management, impact analysis, test sync, and milestone archival",
+  "version": "2.24.6",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 43 slash commands with backlog management, impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,8 @@
     "gsd-t": "bin/gsd-t.js"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepublishOnly": "npm test"
   },
   "files": [
     "bin/",

package/scripts/gsd-t-fetch-version.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Fetch Version — Synchronous npm registry version check
+ *
+ * Fetches the latest version of @tekyzinc/gsd-t from the npm registry
+ * and writes it to stdout. Used by checkForUpdates() in bin/gsd-t.js.
+ *
+ * Bounded to 1MB response to prevent OOM.
+ */
+
+const https = require("https");
+
+const MAX_BODY = 1048576; // 1MB
+
+https.get("https://registry.npmjs.org/@tekyzinc/gsd-t/latest", { timeout: 5000 }, (res) => {
+  let data = "";
+  res.on("data", (chunk) => {
+    data += chunk;
+    if (data.length > MAX_BODY) { res.destroy(); return; }
+  });
+  res.on("end", () => {
+    try { process.stdout.write(JSON.parse(data).version); } catch { /* ignore */ }
+  });
+}).on("error", () => { /* silent */ });