@tekyzinc/gsd-t 2.24.7 → 2.28.12

package/commands/gsd-t-status.md

@@ -2,6 +2,23 @@
 
 You are checking the current state of the project across all domains.
 
+## Launch via Subagent
+
+To keep the main conversation context lean, run status via a Task subagent.
+
+**If you are the orchestrating agent** (you received the slash command directly):
+Spawn a fresh subagent using the Task tool:
+```
+subagent_type: general-purpose
+model: haiku
+prompt: "You are running gsd-t-status. Working directory: {current project root}
+Read .gsd-t/progress.md and execute the full status report workflow."
+```
+Wait for the subagent to complete. Relay its output to the user. **Do not read files yourself.**
+
+**If you are the spawned subagent** (your prompt says "running gsd-t-status"):
+Continue below.
+
 ## Read These Files
 
 1. `.gsd-t/progress.md`

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

@@ -21,18 +21,17 @@ Identify:
 - Naming conventions
 - Test run commands (from package.json scripts, Makefile, or CI config)
 
-## Step 2: Spawn QA Agent
+## Step 2: Contract Coverage Audit
 
-Spawn the QA teammate to assist with test coverage analysis:
+Perform inline contract testing and gap 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.
-```
+1. Read all contracts in `.gsd-t/contracts/` — identify the interface each one defines
+2. For each contract, check whether a test file exists that validates it
+3. Run the full test suite: `npm test` (or project equivalent)
+4. Identify gaps: contracts with no tests, stale tests referencing removed APIs, uncovered code paths
+5. Report: coverage gaps, stale tests, and recommended test tasks
 
-QA agent works alongside the test sync process. QA failure blocks test-sync completion.
+Test-sync cannot complete if critical contract gaps remain unaddressed.
 
 ## Step 3: Map Code to Tests
 

package/commands/gsd-t-verify.md

@@ -12,18 +12,17 @@ Read:
 5. `docs/requirements.md` — original requirements
 6. All source code
 
-## Step 2: Spawn QA Agent
+## Step 2: Full Test Audit (Inline)
 
-Spawn the QA teammate to run the full test audit:
+Run the full test audit directly:
 
-```
-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.
-```
+1. Run the full test suite: `npm test` (or project equivalent) — record pass/fail counts
+2. Read all contracts in `.gsd-t/contracts/` — verify each has at least one test validating it
+3. Check acceptance criteria from domain task lists — verify each is tested
+4. Run E2E suite if `playwright.config.*` exists
+5. Report: comprehensive test results with pass/fail counts and coverage gaps
 
-QA failure blocks verification completion.
+Verification cannot complete if any test fails or critical contract gaps remain.
 
 ## Step 3: Define Verification Dimensions
 
@@ -40,6 +39,12 @@ Standard dimensions (adjust based on project):
 5. **E2E Tests**: Run the FULL Playwright suite — all specs must pass. If new features lack specs, create them before proceeding.
 6. **Security**: Auth flows, input validation, data exposure, dependencies
 7. **Integration Integrity**: Do the seams between domains hold under stress?
+8. **Requirements Traceability Close-Out**: Mark verified requirements as complete and report orphans:
+   - Read `docs/requirements.md` traceability table (added by plan phase)
+   - For each REQ-ID that is fully implemented and tested: update Status to `complete` in the traceability table
+   - **Orphan report**: List any REQ-IDs with no task mapping (planning gap) and any tasks with no REQ-ID (potential scope creep)
+   - Orphaned requirements = WARN (not blocking unless critical)
+   - Update `docs/requirements.md` with the close-out results
 
 ## Step 4: Execute Verification
 
@@ -101,12 +106,7 @@ Teammate assignments:
   - Secret/credential handling
   Report: severity-ranked findings.
 
-- 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.
+Lead: After receiving teammate reports, spawn a Task subagent to run the full test suite and contract audit. Collect all reports, synthesize, create remediation plan.
 ```
 
 ## Step 5: Compile Verification Report

package/commands/gsd-t-wave.md

@@ -120,14 +120,18 @@ Spawn agent → `commands/gsd-t-complete-milestone.md`
 
 ### Between Each Phase
 
-After each agent completes:
-1. Read `.gsd-t/progress.md` to verify the phase updated status correctly
-2. Report brief status to user:
+After each agent completes, run this spot-check before proceeding:
+
+1. **Status check**: Read `.gsd-t/progress.md` — verify the phase updated status correctly (no FAILED markers, status matches expected phase completion state)
+2. **Git check**: Run `git log --oneline -5` — verify commits were made during this phase (if execute/integrate: at least one commit per task completed)
+3. **Filesystem check**: Verify key output files exist on disk — e.g., for partition: `.gsd-t/domains/*/scope.md` and `.gsd-t/contracts/` files; for execute: newly created source files; for verify: `.gsd-t/verify-report.md`. Do not trust agent-reported completions alone.
+4. Report to user:
    ```
    ✅ {Phase} complete — {agent's one-line summary}
+   📋 Spot-check: {N} commits | {N} output files verified | no FAILED markers
    ```
-3. If status was NOT updated correctly: report error and stop
-4. Proceed to next phase
+5. If spot-check fails: report the discrepancy, re-spawn the phase agent once to correct it, then re-verify. If still failing: stop and report to user.
+6. Proceed to next phase
 
 ## Step 4: Autonomy Behavior
 

package/docs/GSD-T-README.md

@@ -112,6 +112,8 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees | Manual |
 | `/user:gsd-t-debug` | Systematic debugging with state | Manual |
+| `/user:gsd-t-health` | Validate .gsd-t/ structure, optionally repair | Manual |
+| `/user:gsd-t-pause` | Save exact position for reliable resume | Manual |
 | `/user:gsd-t-log` | Sync progress Decision Log with recent git activity | Manual |
 | `/user:gsd-t-version-update` | Update GSD-T to latest version | Manual |
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |

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.7",
-  "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');