@tekyzinc/gsd-t 2.24.8 → 2.28.12

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18 (Post-M9)
+## Last Updated: 2026-02-18 (Post-M13, Scan #6)
 
 ## System Overview
 
@@ -14,7 +14,7 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 
 ### CLI Installer (bin/gsd-t.js)
 - **Purpose**: Install, update, diagnose, and manage GSD-T across projects
-- **Location**: `bin/gsd-t.js` (1,298 lines, 81 functions, 49 exports)
+- **Location**: `bin/gsd-t.js` (1,438 lines, 81+ functions, all ≤ 30 lines)
 - **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
@@ -23,7 +23,7 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 ### Slash Commands (commands/*.md)
 - **Purpose**: Define the GSD-T methodology as executable workflows for Claude Code
 - **Location**: `commands/`
-- **Count**: 43 (39 GSD-T workflow + 4 utility: gsd, branch, checkin, Claude-md)
+- **Count**: 45 (41 GSD-T workflow + 4 utility: gsd, branch, checkin, Claude-md) — includes gsd-t-health and gsd-t-pause added in M13
 - **Format**: Pure markdown with step-numbered instructions, team mode blocks, document ripple sections, and $ARGUMENTS terminator
 
 ### Templates (templates/*.md)
@@ -36,6 +36,8 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 - **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).
+- **gsd-t-tools.js** (163 lines, NEW in M13): State utility CLI returning compact JSON. Subcommands: state get/set (progress.md), validate (required file presence), parse progress --section, list domains/contracts, git pre-commit-check, template scope/tasks. Zero external dependencies. NOTE: No module.exports — untestable as module (TD-066).
+- **gsd-t-statusline.js** (94 lines, NEW in M13): Context usage bar + project state for Claude Code `statusLine` setting. Reads CLAUDE_CONTEXT_TOKENS_USED/MAX env vars for usage percentage. Color-coded bar (green <50%, yellow <70%, orange <85%, red ≥85%). NOTE: No module.exports — untestable as module (TD-066).
 
 ### Examples (examples/)
 - **Purpose**: Reference project structure and settings
@@ -51,6 +53,8 @@ npm install @tekyzinc/gsd-t → bin/gsd-t.js install
   ├── Copy/append templates/CLAUDE-global.md → ~/.claude/CLAUDE.md
   ├── Copy scripts/gsd-t-heartbeat.js → ~/.claude/scripts/
   ├── Configure 9 hooks in ~/.claude/settings.json
+  ├── Copy scripts/gsd-t-tools.js → ~/.claude/scripts/    (installUtilityScripts, M13)
+  ├── Copy scripts/gsd-t-statusline.js → ~/.claude/scripts/ (installUtilityScripts, M13)
   └── Write version to ~/.claude/.gsd-t-version
 ```
 
@@ -101,6 +105,9 @@ Three-tier configuration:
 | `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) |
+| `CONTEXT.md` | Discuss phase output — Locked Decisions, Deferred Ideas | plan (reads + enforces) | discuss |
+| `continue-here-{ts}.md` | Pause/resume checkpoint — exact position | resume (reads + deletes) | pause |
+| `deferred-items.md` | Log of unresolved issues from execute/quick/debug | (manual review) | execute, quick, debug |
 
 ## Data Models
 
@@ -142,23 +149,51 @@ PARTITION → DISCUSS → PLAN → IMPACT → EXECUTE → TEST-SYNC → INTEGRAT
 
 | Phase | Mode | QA Agent | Why |
 |-------|------|----------|-----|
-| Partition | Solo only | YES — test skeletons | Needs full cross-domain context |
+| Partition | Solo only | NO (removed M10) | Was unnecessary overhead |
 | Discuss | Solo only | No | Always pauses for user input (even Level 3) |
-| Plan | Solo only | YES — acceptance scenarios | Needs full cross-domain context |
+| Plan | Solo only | NO (removed M10) | Was unnecessary overhead |
 | 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 |
+| Execute | Solo or Team | Task subagent (M10) | Each task gets QA after completion |
+| Test-Sync | Solo only | Inline (M10) | Sequential contract coverage audit |
+| Integrate | Solo only | Task subagent (M10) | Cross-domain integration tests |
+| Verify | Solo or Team | Inline (M10) | Full audit runs directly |
+| Complete | Solo only | Inline (M10) | Final gate runs directly |
 
 ### 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
+### QA Agent Integration (Updated M10)
 
-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}`.
+QA runs inline or as Task subagent depending on phase (M10 refactor). Removed from partition and plan (were unnecessary). execute and integrate spawn QA as Task subagent after each domain checkpoint. test-sync, verify, and complete-milestone run QA inline. QA failure blocks phase completion (user override available).
+
+### Execution Quality (M11)
+
+**Deviation Rules**: 4-rule protocol added to execute, quick, debug: (1) Bug → fix up to 3 attempts, then defer; (2) Missing dependency → add minimum; (3) Blocker → fix and log; (4) Architectural change → STOP, apply Destructive Action Guard.
+
+**Per-Task Commits**: execute enforces `feat({domain}/task-{N})` commit format after each task. Wave spot-check verifies commits were made.
+
+**Between-Phase Spot-Check (Wave)**: After each phase agent completes, wave reads progress.md (status), runs git log (commits), and verifies filesystem output. Re-spawns phase agent once on failure. Stops and reports to user if still failing.
+
+### Planning Intelligence (M12)
+
+**CONTEXT.md**: discuss phase creates `.gsd-t/CONTEXT.md` with three sections: Locked Decisions (plan MUST implement), Deferred Ideas (plan must NOT implement), Claude's Discretion (implementation details left to executor). Plan reads CONTEXT.md and fails validation if any Locked Decision has no task mapping.
+
+**Plan Validation**: After creating task lists, plan spawns a Task subagent to validate REQ coverage, Locked Decision mapping, task completeness, contract existence. Max 3 fix iterations before stopping and reporting to user.
+
+**REQ Traceability**: Plan writes a traceability table to docs/requirements.md mapping REQ-IDs to domain/task/status. Verify marks matched requirements complete.
+
+### Tooling & UX (M13)
+
+**gsd-t-tools.js**: State utility CLI for Claude Code agents. Reduces token-heavy markdown parsing with compact JSON responses. Installed to `~/.claude/scripts/`. See Hook Scripts section.
+
+**gsd-t-statusline.js**: Visual context usage bar for Claude Code `statusLine` setting. Shows milestone, status, version, and context percentage. Installed to `~/.claude/scripts/`.
+
+**gsd-t-health**: New command — validates .gsd-t/ structure against 12 required items. `--repair` creates missing files from templates. Step 0 subagent pattern.
+
+**gsd-t-pause**: New command — creates `.gsd-t/continue-here-{timestamp}.md` with exact position snapshot. More precise than progress.md alone.
+
+**gsd-t-resume** (updated): Reads continue-here files first (most recent by timestamp), falls back to progress.md. Deletes continue-here file after reading.
 
 ### Test Suite (test/)
 - **helpers.test.js** (27 tests): Pure helper functions — validateProjectName, applyTokens, isNewerVersion, normalizeEol, etc.
@@ -166,7 +201,7 @@ The wave command spawns an independent agent for each phase via the Task tool wi
 - **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
+- **Total**: 125 tests, all passing (post-M9)
 
 ## Security Model
 
@@ -193,10 +228,15 @@ The wave command spawns an independent agent for each phase via the Task tool wi
 | 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) |
+| 2026-02-18 | QA refactor — remove from partition/plan, Task subagent for execute/integrate | QA on partition/plan added overhead with little value; Task subagent gives QA fresh context | Teammate QA (original), no QA |
+| 2026-02-18 | Deviation Rules + 3-attempt limit | Prevents infinite loops; auto-fixes bugs without blocking; escalates architectural changes | Manual escalation only, no auto-fix |
+| 2026-02-18 | CONTEXT.md from discuss phase | Structured handoff between discuss and plan; fidelity enforcement on Locked Decisions | Free-form decisions in progress.md |
+| 2026-02-18 | gsd-t-tools.js as state utility CLI | Reduces token-heavy markdown parsing; compact JSON responses save ~50K tokens/wave | Parsing progress.md inline (original) |
+| 2026-02-18 | continue-here files for pause/resume | More precise than progress.md; captures exact task+next-action, not just phase | progress.md alone (less precise) |
 
 ## 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.
+1. **CLI single-file size**: bin/gsd-t.js at 1,438 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 (Scan #5)
+## Last Updated: 2026-02-18 (Post-M13, Scan #6)
 
 ## Quick Reference
 
@@ -30,7 +30,7 @@ node bin/gsd-t.js status
 
 ### Testing
 ```bash
-# Run automated test suite (116 tests, zero dependencies)
+# Run automated test suite (125 tests, zero dependencies)
 npm test
 
 # Test CLI subcommands manually
@@ -40,8 +40,12 @@ 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 43
+ls commands/*.md | wc -l  # Should be 45
 ls templates/*.md | wc -l  # Should be 9
+
+# Test new utility scripts
+node scripts/gsd-t-tools.js validate
+node scripts/gsd-t-tools.js git pre-commit-check
 ```
 
 ### Scripts
@@ -50,6 +54,8 @@ ls templates/*.md | wc -l  # Should be 9
 | `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) |
+| `scripts/gsd-t-tools.js` | State utility CLI — state get/set, validate, list, git check, template read (NEW M13) |
+| `scripts/gsd-t-statusline.js` | Context usage bar + project state for Claude Code statusLine setting (NEW M13) |
 
 ## Distribution
 
@@ -62,9 +68,11 @@ ls templates/*.md | wc -l  # Should be 9
 ### Installed Locations
 | What | Where |
 |------|-------|
-| Slash commands (43 files) | `~/.claude/commands/` |
+| Slash commands (45 files) | `~/.claude/commands/` |
 | Global config | `~/.claude/CLAUDE.md` |
 | Heartbeat script | `~/.claude/scripts/gsd-t-heartbeat.js` |
+| State utility CLI | `~/.claude/scripts/gsd-t-tools.js` |
+| Statusline script | `~/.claude/scripts/gsd-t-statusline.js` |
 | Hook configuration | `~/.claude/settings.json` (hooks section) |
 | Version file | `~/.claude/.gsd-t-version` |
 | Update cache | `~/.claude/.gsd-t-update-check` |
@@ -74,9 +82,9 @@ ls templates/*.md | wc -l  # Should be 9
 
 ```
 get-stuff-done-teams/
-├── 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
+├── bin/gsd-t.js        — CLI installer (~1,438 lines, zero dependencies)
+├── commands/           — 45 slash command files (41 GSD-T + 4 utility)
+├── scripts/            — 5 hook/utility scripts (added gsd-t-tools.js, gsd-t-statusline.js in M13)
 ├── templates/          — 9 document templates
 ├── examples/           — Reference project structure
 ├── docs/               — Methodology + living docs

package/docs/requirements.md

@@ -1,13 +1,13 @@
 # Requirements — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18 (Scan #5)
+## Last Updated: 2026-02-18 (Post-M13, Scan #6)
 
 ## 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 | 39 GSD-T workflow slash commands for Claude Code (incl. QA agent) | P1 | complete | validated by use |
+| REQ-002 | 41 GSD-T workflow slash commands for Claude Code (incl. QA agent, health, pause) | 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 |
@@ -19,6 +19,10 @@
 | 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 |
+| REQ-014 | Token Efficiency — QA refactored (removed from partition/plan, Task subagent for execute/integrate, inline for test-sync/verify) | P2 | complete (M10) | validated by use |
+| REQ-015 | Execution Quality — Deviation Rules (4-rule, 3-attempt), per-task commits, wave spot-check | P2 | complete (M11) | validated by use |
+| REQ-016 | Planning Intelligence — CONTEXT.md from discuss, plan fidelity enforcement, plan validation subagent, REQ traceability | P2 | complete (M12) | validated by use |
+| REQ-017 | Tooling & UX — gsd-t-tools.js state CLI, gsd-t-statusline.js context bar, gsd-t-health command, gsd-t-pause command | P2 | complete (M13) | validated by use |
 
 ## Technical Requirements
 
@@ -52,13 +56,20 @@
 | 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).
+**Total automated tests**: 125 across 4 test files (M4: 64, M5: 30, M6: 22, M9: 9). 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)
+### Open (Scan #6 — 2026-02-18, Post-M10-M13)
+- 14 new items: TD-066 through TD-079 (1 high: untestable new scripts; 5 medium: contract drift + doc staleness + stateSet injection; 7 low: cleanup)
+- See `.gsd-t/techdebt.md` for full list
+
+### Resolved (Milestone 9 + Milestones 10-13, 2026-02-18)
+- ~~Scan #5 items (TD-056-TD-065)~~ — RESOLVED (M9, Cleanup Sprint)
+- ~~Token efficiency gaps~~ — RESOLVED (M10)
+- ~~Execution quality gaps (no deviation rules, no per-task commits)~~ — RESOLVED (M11)
+- ~~Planning intelligence gaps (no CONTEXT.md, no plan validation)~~ — RESOLVED (M12)
+- ~~Tooling gaps (no state CLI, no statusline, no health command, no pause)~~ — RESOLVED (M13)
 
 ### Resolved (Milestones 3-8, 2026-02-18/19)
 - ~~All scan #4 items (TD-044-TD-055)~~ — RESOLVED (M8)

package/docs/workflows.md

@@ -1,12 +1,12 @@
 # Workflows — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18 (Scan #5)
+## Last Updated: 2026-02-18 (Post-M13, Scan #6)
 
 ## User Workflows
 
 ### Install GSD-T
 1. Run `npx @tekyzinc/gsd-t install`
-2. CLI copies 43 commands to `~/.claude/commands/`
+2. CLI copies 45 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`
@@ -14,7 +14,8 @@
 7. User starts Claude Code in their project
 
 **Entry point**: `npx @tekyzinc/gsd-t install`
-**Success**: 43 commands available in Claude Code
+5b. CLI installs gsd-t-tools.js and gsd-t-statusline.js to `~/.claude/scripts/` (M13)
+**Success**: 45 commands available in Claude Code
 **Failure**: CLI reports missing Node.js or permission errors
 
 ### Initialize a Project
@@ -41,9 +42,14 @@
 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
 
+Additional wave behaviors (M10-M12):
+- **M10**: QA removed from partition/plan; execute/integrate spawn QA as Task subagent; test-sync/verify/complete run QA inline
+- **M11**: Per-task commits (`feat({domain}/task-{N})`) enforced; between-phase spot-check (status + git + filesystem); Deviation Rules in execute (4-rule protocol, 3-attempt limit)
+- **M12**: discuss creates CONTEXT.md (Locked Decisions); plan reads CONTEXT.md + runs plan validation subagent (max 3 iterations); REQ traceability table in requirements.md; verify marks requirements complete
+
 **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; spot-check re-spawns phase agent once before stopping
 
 ### Autonomy Levels
 | Level | Behavior |
@@ -106,11 +112,45 @@ Every commit must pass applicable checks:
 6. Tech debt tracking (discovered/fixed?)
 7. Test execution (affected tests pass?)
 
+### Pause and Resume (M13)
+
+**Pause workflow** (`/gsd-t-pause`):
+1. Command reads progress.md + domains/*/tasks.md to identify exact position
+2. Creates `.gsd-t/continue-here-{YYYYMMDDTHHMMSS}.md` with: milestone, phase, version, last completed action, next action, open items, user note
+3. File persists until consumed by resume
+4. Multiple pauses create multiple files; resume reads most recent by timestamp
+
+**Resume workflow** (`/gsd-t-resume`):
+1. Same-session: skip file reads, use conversation context
+2. Cross-session: glob `.gsd-t/continue-here-*.md`, read most recent
+3. Resume from "Next Action" field in continue-here file (more precise than progress.md alone)
+4. Delete continue-here file after reading
+
+### CONTEXT.md Workflow (M12)
+
+1. `discuss` phase completes design decisions
+2. Writes `.gsd-t/CONTEXT.md`:
+   - **Locked Decisions**: specific decisions the plan MUST implement
+   - **Deferred Ideas**: good ideas NOT in scope (plan must NOT implement)
+   - **Claude's Discretion**: implementation details left open
+3. `plan` reads CONTEXT.md; every Locked Decision must map to at least one task
+4. Plan validation subagent (Task tool) verifies mapping before finalizing plan
+5. CONTEXT.md persists after plan phase; deleted manually if desired
+6. If discuss is skipped (structured skip), CONTEXT.md is not created; plan handles gracefully
+
+### Project Health Check (M13)
+
+1. User invokes `/gsd-t-health [--repair]`
+2. Health spawns as Task subagent (fresh context)
+3. Checks 12 items: 5 root files, 3 directories, 4 docs, active milestone domains, version consistency, status validity, Decision Log, contract integrity
+4. Reports status as HEALTHY (0 issues), DEGRADED (1-3), or BROKEN (4+ or critical missing)
+5. With `--repair`: creates missing files from templates (MISSING items only; INVALID items flagged for user)
+
 ## Integration Workflows
 
 ### npm Publish
 - **Trigger**: Manual `npm publish` after milestone completion
-- **Pre-publish gate**: `prepublishOnly: "npm test"` runs 116 tests before publish (M8)
+- **Pre-publish gate**: `prepublishOnly: "npm test"` runs 125 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
 

package/examples/settings.json

@@ -1,6 +1,6 @@
 {
   "env": {
-    "ANTHROPIC_MODEL": "claude-opus-4-6",
+    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
   },
   "permissions": {
@@ -13,5 +13,6 @@
     ],
     "defaultMode": "dontAsk"
   },
-  "alwaysThinkingEnabled": true
+  "alwaysThinkingEnabled": true,
+  "statusLine": "node ~/.claude/scripts/gsd-t-statusline.js"
 }

package/package.json

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

package/scripts/gsd-t-heartbeat.js

@@ -92,9 +92,9 @@ function cleanupOldHeartbeats(gsdtDir) {
 
 const EVENT_HANDLERS = {
   SessionStart: (h) => ({ evt: "session_start", data: { source: h.source, model: h.model } }),
-  PostToolUse: (h) => ({ evt: "tool", tool: h.tool_name, data: summarize(h.tool_name, h.tool_input) }),
-  SubagentStart: (h) => ({ evt: "agent_spawn", data: { agent_id: h.agent_id, agent_type: h.agent_type } }),
-  SubagentStop: (h) => ({ evt: "agent_stop", data: { agent_id: h.agent_id, agent_type: h.agent_type } }),
+  PostToolUse: (h) => ({ evt: "tool", tool: h.tool_name, agent_id: h.agent_id || null, data: summarize(h.tool_name, h.tool_input) }),
+  SubagentStart: (h) => ({ evt: "agent_spawn", data: { agent_id: h.agent_id, agent_type: h.agent_type, parent_id: h.parent_agent_id || h.session_id } }),
+  SubagentStop: (h) => ({ evt: "agent_stop", data: { agent_id: h.agent_id, agent_type: h.agent_type, parent_id: h.parent_agent_id || h.session_id } }),
   TaskCompleted: (h) => ({ evt: "task_done", data: { task: h.task_subject, agent: h.teammate_name } }),
   TeammateIdle: (h) => ({ evt: "agent_idle", data: { agent: h.teammate_name, team: h.team_name } }),
   Notification: (h) => ({ evt: "notification", data: { message: scrubSecrets(h.message), title: scrubSecrets(h.title) } }),

package/scripts/gsd-t-statusline.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+'use strict';
+// gsd-t-statusline.js — GSD-T status line for Claude Code
+// Outputs compact project status for display in Claude Code's statusLine setting.
+//
+// Configure in ~/.claude/settings.json:
+//   "statusLine": "node ~/.claude/scripts/gsd-t-statusline.js"
+//
+// Context usage is read from CLAUDE_CONTEXT_TOKENS_USED and
+// CLAUDE_CONTEXT_TOKENS_MAX environment variables if available.
+// Falls back to GSD-T project state only.
+//
+// Zero external dependencies.
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── ANSI colors ─────────────────────────────────────────────────────────────
+const GREEN  = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED    = '\x1b[31m';
+const RESET  = '\x1b[0m';
+const DIM    = '\x1b[2m';
+const BOLD   = '\x1b[1m';
+const ORANGE = '\x1b[38;5;208m'; // 256-color orange
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.gsd-t'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function readProgress(root) {
+  const p = path.join(root, '.gsd-t', 'progress.md');
+  if (!fs.existsSync(p)) return null;
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function extract(content, key) {
+  const m = content.match(new RegExp(`^## ${key}:\\s*(.+)`, 'm'));
+  return m ? m[1].trim() : null;
+}
+
+function contextBar(pct) {
+  // pct: 0-100
+  const barLen = 10;
+  const filled = Math.round((pct / 100) * barLen);
+  const empty  = barLen - filled;
+  let color;
+  if (pct < 50)      color = GREEN;
+  else if (pct < 70) color = YELLOW;
+  else if (pct < 85) color = ORANGE;
+  else               color = RED;
+  return `${color}${'█'.repeat(filled)}${DIM}${'░'.repeat(empty)}${RESET} ${color}${pct}%${RESET}`;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+const root = findProjectRoot();
+
+// Context usage from env vars (provided by Claude Code if available)
+const tokensUsed = parseInt(process.env.CLAUDE_CONTEXT_TOKENS_USED || '0', 10);
+const tokensMax  = parseInt(process.env.CLAUDE_CONTEXT_TOKENS_MAX  || '0', 10);
+const hasContext = tokensMax > 0;
+const ctxPct     = hasContext ? Math.min(100, Math.round((tokensUsed / tokensMax) * 100)) : null;
+
+// GSD-T project state
+let projectPart = '';
+if (root) {
+  const content = readProgress(root);
+  if (content) {
+    const milestone = extract(content, 'Milestone') || extract(content, 'Current Milestone') || '—';
+    const status    = extract(content, 'Status') || '—';
+    const version   = extract(content, 'Version') || '';
+    const vStr      = version ? ` ${DIM}v${version}${RESET}` : '';
+    projectPart = `${BOLD}${milestone}${RESET} ${DIM}${status}${RESET}${vStr}`;
+  }
+} else {
+  projectPart = `${DIM}(no gsd-t project)${RESET}`;
+}
+
+// Context bar
+let contextPart = '';
+if (ctxPct !== null) {
+  contextPart = ` │ ctx ${contextBar(ctxPct)}`;
+}
+
+const line = `gsd-t │ ${projectPart}${contextPart}`;
+process.stdout.write(line + '\n');

package/scripts/gsd-t-tools.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+'use strict';
+// gsd-t-tools.js — GSD-T state utility CLI. Zero external dependencies.
+// Returns compact JSON. Subcommands: state, validate, parse, list, git, template
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Find nearest .gsd-t/ directory walking up from cwd
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.gsd-t'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+const root = findProjectRoot();
+const gsdDir = path.join(root, '.gsd-t');
+
+function readProgress() {
+  const p = path.join(gsdDir, 'progress.md');
+  if (!fs.existsSync(p)) return null;
+  return fs.readFileSync(p, 'utf8');
+}
+
+function stateGet(key) {
+  const content = readProgress();
+  if (!content) return { error: 'progress.md not found' };
+  const re = new RegExp(`^## ${escapeRe(key)}:\\s*(.+)`, 'm');
+  const m = content.match(re);
+  if (!m) return { error: `key not found: ${key}` };
+  return { key, value: m[1].trim() };
+}
+
+function stateSet(key, value) {
+  const p = path.join(gsdDir, 'progress.md');
+  if (!fs.existsSync(p)) return { error: 'progress.md not found' };
+  const content = fs.readFileSync(p, 'utf8');
+  const re = new RegExp(`(^## ${escapeRe(key)}:\\s*)(.+)`, 'm');
+  if (!re.test(content)) return { error: `key not found: ${key}` };
+  fs.writeFileSync(p, content.replace(re, `$1${value}`));
+  return { ok: true, key, value };
+}
+
+function validate() {
+  const required = [
+    '.gsd-t/progress.md',
+    '.gsd-t/contracts',
+    '.gsd-t/domains',
+    'CLAUDE.md',
+  ];
+  const results = {};
+  const missing = [];
+  for (const f of required) {
+    const exists = fs.existsSync(path.join(root, f));
+    results[f] = exists ? 'ok' : 'missing';
+    if (!exists) missing.push(f);
+  }
+  return { valid: missing.length === 0, results, missing };
+}
+
+function parseSection(sectionName) {
+  const content = readProgress();
+  if (!content) return { error: 'progress.md not found' };
+  const re = new RegExp(`## ${escapeRe(sectionName)}\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const m = content.match(re);
+  if (!m) return { error: `section not found: ${sectionName}` };
+  return { section: sectionName, content: m[1].trim() };
+}
+
+function listDomains() {
+  const dir = path.join(gsdDir, 'domains');
+  if (!fs.existsSync(dir)) return { domains: [] };
+  const domains = fs.readdirSync(dir).filter(f => {
+    try { return fs.statSync(path.join(dir, f)).isDirectory(); } catch { return false; }
+  });
+  return { domains };
+}
+
+function listContracts() {
+  const dir = path.join(gsdDir, 'contracts');
+  if (!fs.existsSync(dir)) return { contracts: [] };
+  const contracts = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+  return { contracts };
+}
+
+function preCommitCheck() {
+  const result = {};
+  try {
+    result.branch = execSync('git branch --show-current', { cwd: root, encoding: 'utf8' }).trim();
+  } catch {
+    result.branch = 'error';
+  }
+  try {
+    const status = execSync('git status --porcelain', { cwd: root, encoding: 'utf8' }).trim();
+    result.clean = status.length === 0;
+    result.changes = status ? status.split('\n').filter(Boolean) : [];
+  } catch {
+    result.clean = 'error';
+  }
+  try {
+    result.lastCommit = execSync('git log -1 --format="%h %s"', { cwd: root, encoding: 'utf8' }).trim();
+  } catch {
+    result.lastCommit = 'error';
+  }
+  return result;
+}
+
+function templateScope(domain) {
+  const p = path.join(gsdDir, 'domains', domain, 'scope.md');
+  if (!fs.existsSync(p)) return { error: `scope.md not found for domain: ${domain}` };
+  return { domain, scope: fs.readFileSync(p, 'utf8') };
+}
+
+function templateTasks(domain) {
+  const p = path.join(gsdDir, 'domains', domain, 'tasks.md');
+  if (!fs.existsSync(p)) return { error: `tasks.md not found for domain: ${domain}` };
+  return { domain, tasks: fs.readFileSync(p, 'utf8') };
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Parse args
+const args = process.argv.slice(2);
+const [cmd, subcmd, ...rest] = args;
+
+let result;
+if (cmd === 'state') {
+  if (subcmd === 'get' && rest[0]) {
+    result = stateGet(rest[0]);
+  } else if (subcmd === 'set' && rest[0] && rest[1]) {
+    result = stateSet(rest[0], rest[1]);
+  } else {
+    result = { error: 'Usage: state get <key> | state set <key> <value>' };
+  }
+} else if (cmd === 'validate') {
+  result = validate();
+} else if (cmd === 'parse' && subcmd === 'progress') {
+  const si = args.indexOf('--section');
+  const section = si !== -1 ? args[si + 1] : null;
+  result = section ? parseSection(section) : { error: 'Usage: parse progress --section <name>' };
+} else if (cmd === 'list') {
+  if (subcmd === 'domains') result = listDomains();
+  else if (subcmd === 'contracts') result = listContracts();
+  else result = { error: 'Usage: list domains | list contracts' };
+} else if (cmd === 'git' && subcmd === 'pre-commit-check') {
+  result = preCommitCheck();
+} else if (cmd === 'template') {
+  if (subcmd === 'scope' && rest[0]) result = templateScope(rest[0]);
+  else if (subcmd === 'tasks' && rest[0]) result = templateTasks(rest[0]);
+  else result = { error: 'Usage: template scope <domain> | template tasks <domain>' };
+} else {
+  result = {
+    error: cmd ? `Unknown command: ${cmd}` : 'No command specified',
+    usage: 'state get|set  validate  parse progress --section <name>  list domains|contracts  git pre-commit-check  template scope|tasks <domain>',
+  };
+}
+
+process.stdout.write(JSON.stringify(result, null, 2) + '\n');