@tekyzinc/gsd-t 2.22.0 → 2.24.6

package/docs/GSD-T-README.md

@@ -117,6 +117,18 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches | Manual |
 
+### Backlog Management
+
+| Command | Purpose | Auto |
+|---------|---------|------|
+| `/user:gsd-t-backlog-add` | Capture item, auto-categorize, append to backlog | Manual |
+| `/user:gsd-t-backlog-list` | Filtered, ordered view of backlog items | Manual |
+| `/user:gsd-t-backlog-move` | Reorder items by position (priority) | Manual |
+| `/user:gsd-t-backlog-edit` | Modify backlog entry fields | Manual |
+| `/user:gsd-t-backlog-remove` | Drop item with optional reason | Manual |
+| `/user:gsd-t-backlog-promote` | Refine, classify, launch GSD-T workflow | Manual |
+| `/user:gsd-t-backlog-settings` | Manage types, apps, categories, defaults | Manual |
+
 ---
 
 ## Workflow Phases

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18
+## Last Updated: 2026-02-18 (Post-M9)
 
 ## System Overview
 
@@ -8,36 +8,100 @@ GSD-T is an npm-distributed methodology framework for Claude Code. It provides s
 
 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.
 
+**Architecture Pattern**: Distributed Markdown Instruction System with CLI Lifecycle Manager. Command files are the "source code" interpreted by Claude Code. The CLI is a lifecycle manager (install/update/init/status/doctor/uninstall). State files persist across sessions as git-tracked Markdown.
+
 ## Components
 
 ### CLI Installer (bin/gsd-t.js)
 - **Purpose**: Install, update, diagnose, and manage GSD-T across projects
-- **Location**: `bin/gsd-t.js`
+- **Location**: `bin/gsd-t.js` (1,298 lines, 81 functions, 49 exports)
 - **Dependencies**: Node.js built-ins only (fs, path, os, child_process, https)
 - **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog
+- **Organization**: Configuration → Guard section → Helpers → Heartbeat → Commands → Install/Update → Init → Status → Uninstall → Update-All → Doctor → Register → Update Check → Help → Main dispatch
+- **All functions ≤ 30 lines** (M6 refactoring). Largest: `doRegister()` at 30 lines, `summarize()` at 30 lines.
 
 ### 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
+- **Count**: 43 (39 GSD-T workflow + 4 utility: gsd, branch, checkin, Claude-md)
+- **Format**: Pure markdown with step-numbered instructions, team mode blocks, document ripple sections, and $ARGUMENTS terminator
 
 ### 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
+- **Tokens**: `{Project Name}` and `{Date}` replaced during init via `applyTokens()`
 
-### 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
+### Hook Scripts (scripts/)
+- **gsd-t-heartbeat.js** (181 lines, 6 functions, 5 exports): Real-time event logging via Claude Code hooks. Captures 9 event types as structured JSONL. Input capped at 1MB. Session ID validated. Path traversal protection. Secret scrubbing via `scrubSecrets()`/`scrubUrl()` (M5). Notification message + title scrubbing (M8/M9). EVENT_HANDLERS map pattern (M6). Auto-cleanup after 7 days (SessionStart only, M6).
+- **npm-update-check.js** (43 lines): Background npm registry version checker. Spawned detached by CLI when update cache is stale. Path validation within `~/.claude/` (M5). Symlink check before write (M5). 1MB response limit (M5).
+- **gsd-t-fetch-version.js** (26 lines, NEW in M6): Synchronous npm registry fetch. Called by `fetchVersionSync()` via `execFileSync`. HTTPS-only, 5s timeout, 1MB limit. Silent failure on errors (caller validates).
 
 ### Examples (examples/)
 - **Purpose**: Reference project structure and settings
 - **Location**: `examples/`
 - **Contents**: settings.json, .gsd-t/ with sample contracts and domain structure
 
+## Data Flow
+
+### Installation Flow
+```
+npm install @tekyzinc/gsd-t → bin/gsd-t.js install
+  ├── Copy commands/*.md → ~/.claude/commands/
+  ├── Copy/append templates/CLAUDE-global.md → ~/.claude/CLAUDE.md
+  ├── Copy scripts/gsd-t-heartbeat.js → ~/.claude/scripts/
+  ├── Configure 9 hooks in ~/.claude/settings.json
+  └── Write version to ~/.claude/.gsd-t-version
+```
+
+### Project Initialization Flow
+```
+gsd-t init [name] → templates/ → applyTokens()
+  ├── → {project}/CLAUDE.md
+  ├── → {project}/docs/{requirements,architecture,workflows,infrastructure}.md
+  ├── → {project}/.gsd-t/{progress,backlog,backlog-settings}.md
+  └── → {project}/.gsd-t/{contracts,domains}/.gitkeep
+```
+
+### Runtime Command Execution (within Claude Code)
+```
+User types /user:gsd-t-{command} [args]
+  → Claude Code loads ~/.claude/commands/gsd-t-{command}.md
+  → Claude interprets step-by-step instructions
+  → Reads state files → Executes workflow → Pre-Commit Gate → Updates progress.md
+```
+
+### Update Check Flow
+```
+CLI command → Read cache (~/.claude/.gsd-t-update-check)
+  ├── Fresh (<1h): Show notice if latest > installed
+  ├── No cache: Synchronous fetch → cache → show notice
+  └── Stale (>1h): Spawn background scripts/npm-update-check.js
+```
+
+## Configuration Model
+
+Three-tier configuration:
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| **Global** | `~/.claude/CLAUDE.md` | Framework defaults: autonomy rules, code standards, pre-commit gate |
+| **Project** | `{cwd}/CLAUDE.md` | Project-specific: tech stack, branch guard, conventions, overrides |
+| **State** | `{cwd}/.gsd-t/` | Live state: progress, contracts, domains, backlog, scan results |
+
+## State Files
+
+| File | Purpose | Read By | Written By |
+|------|---------|---------|------------|
+| `progress.md` | Master state, version, decision log | All commands | Most commands |
+| `contracts/*.md` | Domain interfaces | execute, integrate, verify | partition |
+| `domains/{name}/scope.md` | File ownership | execute, quick | partition |
+| `domains/{name}/tasks.md` | Task list | execute, status, resume | plan, execute |
+| `backlog.md` | Priority-ordered backlog | backlog-list, status | backlog-add/edit/move/remove |
+| `backlog-settings.md` | Types, apps, categories | backlog-add/edit/settings | backlog-settings, init |
+| `techdebt.md` | Prioritized tech debt | promote-debt, scan | scan |
+| `scan/*.md` | Codebase analysis | scan (synthesis), setup | scan (teammates) |
+
 ## Data Models
 
 ### Progress State (.gsd-t/progress.md)
@@ -45,14 +109,14 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 |-------|------|-------|
 | Project | string | Name from CLAUDE.md |
 | Version | semver | Major.Minor.Patch |
-| Status | enum | INITIALIZED, IN_PROGRESS, READY |
+| Status | enum | READY, INITIALIZED, PARTITIONED, DISCUSSED, PLANNED, IMPACT_ANALYZED, EXECUTING, EXECUTED, TESTS_SYNCED, INTEGRATED, VERIFIED, VERIFY_FAILED, COMPLETED |
 | 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 |
+| Position | integer | Sequential, 1 = highest priority |
 | Type | enum | bug, feature, improvement, ux, architecture |
 | App | string | Target application |
 | Category | string | Domain/module category |
@@ -61,14 +125,60 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 ### 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 |
+| backlog-command-interface.md | Backlog command interface and promote flow |
 | integration-points.md | How components connect |
-| backlog-file-formats.md | Backlog markdown structure |
+| backlog-file-formats.md | Backlog markdown structure (authoritative — duplicate file-format-contract.md deleted in M9) |
 | 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 |
+| qa-agent-contract.md | QA agent spawn interface, output per phase, communication protocol |
+
+## Workflow Phase Architecture
+
+```
+PARTITION → DISCUSS → PLAN → IMPACT → EXECUTE → TEST-SYNC → INTEGRATE → VERIFY → COMPLETE
+```
+
+| Phase | Mode | QA Agent | Why |
+|-------|------|----------|-----|
+| Partition | Solo only | YES — test skeletons | Needs full cross-domain context |
+| Discuss | Solo only | No | Always pauses for user input (even Level 3) |
+| Plan | Solo only | YES — acceptance scenarios | Needs full cross-domain context |
+| Impact | Solo only | No | Cross-cutting analysis |
+| Execute | Solo or Team | YES — continuous testing | Tasks within domains are independent |
+| Test-Sync | Solo only | YES — coverage audit | Sequential verification |
+| Integrate | Solo only | YES — boundary tests | Needs to see all seams |
+| Verify | Solo or Team | YES — full audit | Dimensions are independent |
+| Complete | Solo only | YES — final gate | Archival and tagging |
+
+### Wave Orchestrator (Agent-Per-Phase Model)
+
+The wave command spawns an independent agent for each phase via the Task tool with `bypassPermissions`. Each phase agent gets a fresh ~200K token context window, eliminating context accumulation and mid-wave compaction. The orchestrator itself stays lightweight (~30KB), reading only `progress.md` and `CLAUDE.md`. State handoff between phases occurs through `.gsd-t/` files.
+
+### QA Agent Integration
+
+10 commands spawn a QA teammate (`commands/gsd-t-qa.md`) for test-driven contract enforcement. QA behavior is phase-dependent: test skeletons during partition, continuous testing during execute, full audit during verify. QA failure blocks phase completion (user override available). Communication protocol: `QA: {PASS|FAIL} — {summary}`.
+
+### Test Suite (test/)
+- **helpers.test.js** (27 tests): Pure helper functions — validateProjectName, applyTokens, isNewerVersion, normalizeEol, etc.
+- **filesystem.test.js** (37 tests): Filesystem helpers + CLI subcommand integration — ensureDir, isSymlink, writeTemplateFile, status/doctor/help outputs
+- **security.test.js** (30 tests): Security functions — scrubSecrets (18), scrubUrl (5), summarize integration (4), hasSymlinkInPath (3)
+- **cli-quality.test.js** (22 tests): M6 refactored functions — buildEvent (10), readProjectDeps (3), readPyContent (2), insertGuardSection (3), readUpdateCache (1), addHeartbeatHook (3)
+- **Runner**: Node.js built-in (`node --test`), zero test dependencies
+- **Total**: 116 tests, all passing
+
+## Security Model
+
+- **Zero dependencies**: No supply chain attack surface
+- **Symlink protection**: `isSymlink()` at 15+ write sites + `hasSymlinkInPath()` for parent directory validation (M5)
+- **Secret scrubbing**: `scrubSecrets()` masks passwords/tokens/API keys in heartbeat logs; `scrubUrl()` masks URL query params (M5)
+- **Input validation**: Project names, version strings, session IDs, project paths all validated
+- **Path traversal prevention**: Heartbeat validates session_id regex, resolves paths, verifies containment; npm-update-check validates cache path within `~/.claude/` (M5)
+- **Command injection mitigation**: `execFileSync` with array args (not `execSync`)
+- **Exclusive file creation**: Init uses `{ flag: "wx" }` for atomic create-or-fail
+- **Resource limits**: Heartbeat stdin capped at 1MB, HTTP responses capped at 1MB (M5), 5s/8s timeouts, 7-day file cleanup
+- **Wave security**: `bypassPermissions` mode documented with attack surface analysis and mitigations (M5)
 
 ## Design Decisions
 
@@ -80,3 +190,13 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 | 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 |
+| 2026-02-16 | Team mode default for scan | Parallel scanning faster, better results | Solo sequential scan |
+| 2026-02-17 | QA Agent as cross-cutting concern | Mandatory test-driven contracts for all code phases | Optional testing, deferred testing |
+| 2026-02-17 | Agent-per-phase wave orchestration | Fresh context window per phase, eliminates compaction | Inline execution (original approach) |
+
+## Known Architecture Concerns
+
+1. **CLI single-file size**: bin/gsd-t.js at 1,298 lines exceeds the 200-line convention, but splitting adds complexity for questionable benefit given zero-dependency constraint. Accepted deviation.
+2. **Four-file synchronization**: Any command change requires updating README, GSD-T-README, CLAUDE-global template, and gsd-t-help. Manual process — no automated validation.
+3. **Pre-Commit Gate unenforced**: Mental checklist in CLAUDE.md, not a git hook or CI check.
+4. **Progress.md Decision Log growth**: Unbounded append-only log. May need periodic archival strategy for long-lived projects.

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.22.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 */ });