@tekyzinc/gsd-t 2.24.8 → 2.28.13

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.28.10] - 2026-02-18
+
+### Added
+- **Milestone 13: Tooling & UX** — Infrastructure and UX improvements:
+  - **`scripts/gsd-t-tools.js`**: New zero-dependency Node.js CLI utility returning compact JSON. Subcommands: `state get/set` (read/write progress.md keys), `validate` (check required files), `parse progress --section` (extract named sections), `list domains|contracts`, `git pre-commit-check` (branch/status/last-commit), `template scope|tasks <domain>`
+  - **`scripts/gsd-t-statusline.js`**: New statusline script for Claude Code. Reads GSD-T project state and optionally reads `CLAUDE_CONTEXT_TOKENS_USED`/`CLAUDE_CONTEXT_TOKENS_MAX` env vars to show a color-coded context usage bar (green→yellow→orange→red). Configure via `"statusLine": "node ~/.claude/scripts/gsd-t-statusline.js"` in `settings.json`
+  - **`gsd-t-health`**: New slash command validating `.gsd-t/` project structure. Checks all required files, directories, version consistency, status validity, contract integrity, and domain integrity. `--repair` creates any missing files from templates. Reports HEALTHY / DEGRADED / BROKEN
+  - **`gsd-t-pause`**: New slash command saving exact position to `.gsd-t/continue-here-{timestamp}.md` with milestone, phase, domain, task, last completed action, next action, and open items
+  - Both scripts automatically installed to `~/.claude/scripts/` during `npx @tekyzinc/gsd-t install/update`
+
+### Changed
+- **`gsd-t-resume`**: Now reads the most recent `.gsd-t/continue-here-*.md` file (if present) as the primary resume point before falling back to `progress.md`. Deletes the continue-here file after consuming it
+- **`gsd-t-plan`**: Wave Execution Groups added to `integration-points.md` format — groups tasks into parallel-safe waves with checkpoints between them. Wave rules: same-wave tasks share no files and have no dependencies; different-wave tasks depend on each other's output or modify shared files
+- **`gsd-t-execute`**: Reads Wave Execution Groups from `integration-points.md` and executes wave-by-wave. Tasks within a wave are parallel-safe; checkpoints between waves verify contract compliance before proceeding. Team mode now spawns teammates only within the same wave
+- **`gsd-t-health`** and **`gsd-t-pause`** added to all reference files (help, README, GSD-T-README, CLAUDE-global template, user CLAUDE.md)
+- Total command count: 43 → **45** (41 GSD-T workflow + 4 utility)
+
+## [2.27.10] - 2026-02-18
+
+### Changed
+- **Milestone 12: Planning Intelligence** — Three improvements to correctness across milestones:
+  - **CONTEXT.md from discuss**: `gsd-t-discuss` now creates `.gsd-t/CONTEXT.md` with three sections — Locked Decisions (plan must implement exactly), Deferred Ideas (plan must NOT implement), and Claude's Discretion (free to decide). New Step 5 added to discuss; steps renumbered
+  - **Plan fidelity enforcement**: `gsd-t-plan` reads CONTEXT.md and maps every Locked Decision to at least one task. Also produces a REQ-ID → domain/task traceability table in `docs/requirements.md`
+  - **Plan validation checker**: A Task subagent validates the plan after creation — checks REQ coverage, Locked Decision mapping, task completeness, cross-domain dependencies, and contract existence. Max 3 fix iterations before stopping
+  - **Requirements close-out in verify**: `gsd-t-verify` marks matched requirements as `complete` in the traceability table and reports orphaned requirements and unanchored tasks
+
+## [2.26.10] - 2026-02-18
+
+### Changed
+- **Milestone 11: Execution Quality** — Three improvements to execution reliability:
+  - **Deviation Rules**: `execute`, `quick`, and `debug` now include a 4-rule deviation protocol — auto-fix bugs (3-attempt limit), add minimum missing dependencies, fix blockers, and STOP for architectural changes. Failed attempts log to `.gsd-t/deferred-items.md`
+  - **Atomic per-task commits**: `execute` now commits after each task using `feat({domain}/task-{N}): {description}` format instead of batching at phase end. Team mode instructions updated with the same requirement
+  - **Wave spot-check**: Between-phase verification in `wave` now checks git log (commits present), filesystem (output files exist), and FAILED markers in progress.md — not just agent-reported status
+
+## [2.25.10] - 2026-02-18
+
+### Changed
+- **Milestone 10: Token Efficiency** — QA overhead significantly reduced across all phases:
+  - `partition` and `plan`: QA spawn removed (no code produced in these phases)
+  - `test-sync`, `verify`, `complete-milestone`: contract testing and gap analysis performed inline (no QA teammate)
+  - `execute`, `integrate`: QA now spawned via lightweight Task subagent instead of TeamCreate teammate
+  - `quick`, `debug`: QA spawn removed; tests run inline in the existing Test & Verify step; both commands now self-spawn as Task subagents (Step 0) for fresh context windows
+  - `scan`, `status`: wrap themselves as Task subagents for fresh context on each invocation
+  - Global CLAUDE.md QA Mandatory section updated to reflect the new per-command QA method
+
+## [2.24.10] - 2026-02-18
+
+### Changed
+- **Versioning scheme: patch numbers are always 2 digits**: Patch segment now starts at 10 (not 0) after any minor or major reset. Incrementing continues normally (10→11→12…). Semver validity is preserved — no leading zeros. `checkin.md` and `gsd-t-complete-milestone.md` updated with the new convention. `gsd-t-init` will initialize new projects at `0.1.10`
+
+## [2.24.9] - 2026-02-18
+
+### Changed
+- **Default model**: Example settings.json updated from `claude-opus-4-6` to `claude-sonnet-4-6` (faster, lower token usage)
+
 ## [2.24.8] - 2026-02-18
 
 ### Fixed

package/README.md

@@ -18,7 +18,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 39 GSD-T commands + 4 utility commands (43 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 41 GSD-T commands + 4 utility commands (45 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -143,6 +143,8 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/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 |
@@ -294,8 +296,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 43 slash commands
-│   ├── gsd-t-*.md                     # 39 GSD-T workflow commands
+├── commands/                          # 45 slash commands
+│   ├── gsd-t-*.md                     # 41 GSD-T workflow commands
 │   ├── gsd.md                         # GSD-T smart router
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper

package/bin/gsd-t.js

@@ -456,6 +456,26 @@ function configureUpdateCheckHook(scriptPath) {
   }
 }
 
+// ─── Utility Scripts ─────────────────────────────────────────────────────────
+
+const UTILITY_SCRIPTS = ["gsd-t-tools.js", "gsd-t-statusline.js"];
+
+function installUtilityScripts() {
+  ensureDir(SCRIPTS_DIR);
+  for (const script of UTILITY_SCRIPTS) {
+    const src = path.join(PKG_SCRIPTS, script);
+    const dest = path.join(SCRIPTS_DIR, script);
+    if (!fs.existsSync(src)) continue;
+    const srcContent = fs.readFileSync(src, "utf8");
+    const destContent = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
+    if (normalizeEol(srcContent) !== normalizeEol(destContent)) {
+      copyFile(src, dest, script);
+    } else {
+      info(`${script} unchanged`);
+    }
+  }
+}
+
 // ─── Commands ────────────────────────────────────────────────────────────────
 
 function installCommands(isUpdate) {
@@ -576,6 +596,9 @@ function doInstall(opts = {}) {
 
   heading("Update Check (Session Start)");
   installUpdateCheck();
+
+  heading("Utility Scripts");
+  installUtilityScripts();
   saveInstalledVersion();
 
   showInstallSummary(gsdtCommands.length, utilityCommands.length);

package/commands/checkin.md

@@ -16,7 +16,11 @@ Automatically stage, commit, and push all updated files to GitHub with automatic
    - **minor**: New features, new commands, new capabilities
    - **major**: Breaking changes, major rework, incompatible API changes
 6. Read the current version from `package.json`
-7. Bump the version according to the determined type (e.g., `2.3.0` → `2.3.1` for patch)
+7. Bump the version according to the determined type:
+   - **patch**: increment patch by 1 (e.g., `2.24.10` → `2.24.11`)
+   - **minor**: increment minor, reset patch to **10** (e.g., `2.24.11` → `2.25.10`)
+   - **major**: increment major, reset minor to 0, reset patch to **10** (e.g., `2.24.11` → `3.0.10`)
+   - **Patch numbers are always 2 digits (≥10).** After any minor/major reset, start at 10, never 0 or 1.
 8. Update the version in `package.json`
 9. If `.gsd-t/progress.md` exists, check for a `## Version` line and update it (or add one after the `## Date` line)
 

package/commands/gsd-t-complete-milestone.md

@@ -111,9 +111,10 @@ GSD-T tracks project version in `.gsd-t/progress.md` using semantic versioning:
 Determine the version bump based on the milestone:
 1. Read current version from `.gsd-t/progress.md`
 2. Assess milestone scope:
-   - Was this a major/breaking milestone? → bump **major**, reset minor and patch to 0
-   - Was this a feature milestone? → bump **minor**, reset patch to 0
-   - Was this a bugfix/cleanup/debt milestone? → bump **patch**
+   - Was this a major/breaking milestone? → bump **major**, reset minor to 0, reset patch to **10**
+   - Was this a feature milestone? → bump **minor**, reset patch to **10**
+   - Was this a bugfix/cleanup/debt milestone? → bump **patch** (increment by 1)
+   - **Patch numbers are always 2 digits (≥10).** After any minor/major reset, start at 10, never 0 or 1.
 3. Update version in `.gsd-t/progress.md`
 4. If a package manifest exists (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.), update its version to match
 5. Update `README.md` version badge or version reference if present
@@ -175,20 +176,9 @@ Before creating the git tag, verify all documentation is up to date:
 
 ### This is the LAST GATE before tagging — nothing should be undocumented.
 
-## Step 10: Spawn QA Agent and Test Verification
+## Step 10: Test Verification
 
-Before creating the git tag, spawn the QA teammate for a final test audit:
-
-```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: complete-milestone. Read .gsd-t/contracts/ for contract definitions.
-  Run final test audit before milestone archive. Verify all contract tests pass.
-  Report: final test pass/fail counts and any unresolved gaps.
-```
-
-Wait for QA agent to complete. QA failure blocks milestone completion.
-
-Then verify the milestone is truly complete:
+Verify the milestone is truly complete:
 
 1. **Run the full test suite**: Execute ALL tests — unit, integration, and E2E
 2. **Run Playwright E2E** (if configured): Detect `playwright.config.*` or Playwright in dependencies. If present, run the full Playwright suite. If specs are missing or stale, invoke `gsd-t-test-sync` first.

package/commands/gsd-t-debug.md

@@ -2,6 +2,23 @@
 
 You are debugging an issue in a contract-driven project. Your approach should identify whether the bug is within a domain or at a contract boundary.
 
+## Step 0: Launch via Subagent
+
+To give this debug session a fresh context window and prevent compaction, always execute 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
+prompt: "You are running gsd-t-debug for this issue: {$ARGUMENTS}
+Working directory: {current project root}
+Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-debug starting at Step 1."
+```
+Wait for the subagent to complete. Relay its summary to the user. **Do not execute Steps 1–5 yourself.**
+
+**If you are the spawned subagent** (your prompt says "starting at Step 1"):
+Continue to Step 1 below.
+
 ## Step 1: Load Context
 
 Read:
@@ -40,20 +57,17 @@ The contract didn't specify something it should have. Symptoms:
 
 → Update the contract, then fix implementations on both sides.
 
-## Step 3: Spawn QA Agent
-
-Spawn the QA teammate to handle regression testing:
+## Step 3: Debug (Solo or Team)
 
-```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: debug. Read .gsd-t/contracts/ for relevant contracts.
-  Write a regression test for the bug once root cause is identified.
-  Report: regression test status and related test coverage.
-```
+### Deviation Rules
 
-QA failure blocks the commit.
+When you encounter unexpected situations during the fix:
+1. **Related bug found while tracing** → Fix it immediately (up to 3 attempts). Log to `.gsd-t/deferred-items.md` if it recurs.
+2. **Missing functionality required for the fix** → Add minimum needed. Note in commit message.
+3. **Blocker (missing file, wrong API response)** → Fix blocker and continue. Log if non-trivial.
+4. **Architectural change required to fix correctly** → STOP. Explain what exists, what needs to change, what breaks, and a migration path. Wait for user approval. Never self-approve.
 
-## Step 4: Debug (Solo or Team)
+**3-attempt limit**: If your fix doesn't work after 3 attempts, log to `.gsd-t/deferred-items.md` and stop trying.
 
 ### Solo Mode
 1. Reproduce the issue
@@ -77,7 +91,7 @@ Create an agent team to debug:
 First to find root cause: message the lead with findings.
 ```
 
-## Step 5: Document Ripple
+## Step 4: Document Ripple
 
 After fixing, assess what documentation was affected by the change and update ALL relevant files:
 
@@ -97,7 +111,7 @@ After fixing, assess what documentation was affected by the change and update AL
 
 ### Skip what's not affected — don't update docs for the sake of updating them.
 
-## Step 6: Test Verification
+## Step 5: Test Verification (run tests confirming fix)
 
 Before committing, ensure the fix is solid:
 

package/commands/gsd-t-discuss.md

@@ -81,7 +81,31 @@ For each decision:
 2. Update domain `scope.md` and `constraints.md` if the decision affects boundaries
 3. Add to `.gsd-t/progress.md` Decision Log with date and rationale
 
-## Step 5: Document Ripple
+## Step 5: Create CONTEXT.md
+
+After finalizing decisions, create or update `.gsd-t/CONTEXT.md`:
+
+```markdown
+# Discuss CONTEXT — {Milestone Name}
+Generated: {date}
+
+## Locked Decisions
+Decisions made in this session. The plan phase MUST implement each of these exactly.
+- {Decision 1 — specific and implementable}
+- {Decision 2}
+
+## Deferred Ideas
+Good ideas surfaced but NOT in scope for this milestone. Plan must NOT implement these.
+- {Idea 1 — brief description of what was deferred and why}
+
+## Claude's Discretion
+Implementation details not specified — Claude can choose freely when executing.
+- {Detail 1 — e.g., "Use either X or Y approach for the logging layer"}
+```
+
+The plan phase planner must read this file and map every Locked Decision to at least one task. If a Locked Decision has no corresponding task, the plan is incomplete.
+
+## Step 6: Document Ripple
 
 Decisions don't just affect contracts — they can change the broader documentation:
 
@@ -97,7 +121,7 @@ Decisions don't just affect contracts — they can change the broader documentat
 
 ### Skip what's not affected.
 
-## Step 6: Test Verification
+## Step 7: Test Verification
 
 If decisions resulted in contract or code changes:
 
@@ -105,7 +129,7 @@ If decisions resulted in contract or code changes:
 2. **Verify passing**: All tests must pass. If any fail from contract changes, fix before proceeding (up to 2 attempts)
 3. **Flag test gaps**: If decisions created new requirements with no test coverage, note them for the plan phase
 
-## Step 7: Validate Contracts
+## Step 8: Validate Contracts
 
 After all updates:
 - [ ] All contracts are internally consistent (no conflicting types/shapes)
@@ -113,7 +137,7 @@ After all updates:
 - [ ] Every domain's constraints reflect the decisions made
 - [ ] Integration points are updated with any new dependencies
 
-## Step 8: Report and Stop
+## Step 9: Report and Stop
 
 Present to the user:
 1. Decisions made (with brief rationale)

package/commands/gsd-t-execute.md

@@ -19,23 +19,60 @@ Identify:
 - Which tasks are unblocked (no pending dependencies)
 - Which tasks are blocked (waiting on checkpoints)
 
-## Step 2: Spawn QA Agent
+## Step 2: QA Setup
 
-Spawn the QA teammate to handle testing alongside execution:
+After completing each task, spawn a QA subagent via the Task tool to run tests:
 
 ```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: execute. Read .gsd-t/contracts/ for contract definitions.
-  Run tests continuously as tasks complete. Write edge case tests for new code paths.
-  Report: test pass/fail status after each task completion.
+Task subagent (general-purpose, model: haiku):
+"Run the full test suite for this project and report pass/fail counts.
+Read .gsd-t/contracts/ for contract definitions.
+Write edge case tests for any new code paths in this task: {task description}.
+Report: test pass/fail status and any coverage gaps found."
 ```
 
-The QA agent runs in parallel — it writes and executes tests while you implement tasks. QA failure on any task blocks proceeding to the next task.
+**OBSERVABILITY LOGGING (MANDATORY):**
+Before spawning — run via Bash:
+`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M") && TOK_START=${CLAUDE_CONTEXT_TOKENS_USED:-0} && TOK_MAX=${CLAUDE_CONTEXT_TOKENS_MAX:-200000}`
+After subagent returns — run via Bash:
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && TOK_END=${CLAUDE_CONTEXT_TOKENS_USED:-0} && DURATION=$((T_END-T_START))`
+Compute tokens and compaction:
+- No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
+- Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-execute | Step 2 | haiku | {DURATION}s | task: {task-name}, {pass/fail} | {TOKENS} | {COMPACTED} |`
+If QA found issues, append each to `.gsd-t/qa-issues.md` (create with header `| Date | Command | Step | Model | Duration(s) | Severity | Finding |` if missing):
+`| {DT_START} | gsd-t-execute | Step 2 | haiku | {DURATION}s | {severity} | {finding} |`
+
+QA failure on any task blocks proceeding to the next task.
 
 ## Step 3: Choose Execution Mode
 
+### Wave Scheduling (read first)
+
+Before choosing solo or team mode, read the `## Wave Execution Groups` section in `.gsd-t/contracts/integration-points.md` (added by the plan phase).
+
+**If wave groups are present**:
+- Execute wave-by-wave: complete all tasks in Wave 1 before starting Wave 2
+- Within each wave, tasks marked as parallel-safe can run concurrently (team mode) or be interleaved (solo mode)
+- At each wave boundary: run the CHECKPOINT — verify contract compliance — before proceeding
+- File conflict detection: if two tasks in the same wave list the same file in their `scope.md` ownership, move one to the next wave
+
+**If no wave groups are defined** (older plans): fall back to the `Execution Order` list.
+
 ### Solo Mode (default)
-Execute tasks yourself following the execution order in `integration-points.md`.
+Execute tasks yourself following the wave groups (or execution order) in `integration-points.md`.
+
+### Deviation Rules (MANDATORY for every task)
+
+When you encounter unexpected situations during a task:
+
+1. **Bug in existing code blocking progress** → Fix it immediately, up to 3 attempts. If still blocked after 3 attempts, add to `.gsd-t/deferred-items.md` and move to the next task.
+2. **Missing functionality that the task clearly requires** → Add the minimum required code to unblock the task. Do not gold-plate. Document in commit message.
+3. **Blocker (missing file, wrong API, broken dependency)** → Fix the blocker and continue. Add a note to `.gsd-t/deferred-items.md` if the fix was more than trivial.
+4. **Architectural change required** → STOP immediately. Do NOT proceed. Apply the Destructive Action Guard: explain what exists, what needs to change, what breaks, and a migration path. Wait for explicit user approval.
+
+**3-attempt limit**: If any fix attempt fails 3 times, move on — don't loop. Log to `.gsd-t/deferred-items.md`.
 
 For each task:
 1. Read the task description, files list, and contract refs
@@ -56,12 +93,12 @@ For each task:
    d. **"No feature code without test code"** — implementation and tests are ONE deliverable, not two separate steps
 8. **Run ALL tests** — unit, integration, and full Playwright suite. Fix any failures before proceeding (up to 2 attempts)
 9. Run the Pre-Commit Gate checklist from CLAUDE.md — update ALL affected docs BEFORE committing
-10. Commit with a descriptive message: `[{domain}] Task {N}: {description}`
+10. **Commit immediately** after each task: `feat({domain}/task-{N}): {description}` — do NOT batch commits at phase end
 11. Update `.gsd-t/progress.md` — mark task complete
 12. If you've reached a CHECKPOINT in integration-points.md, pause and verify the contract before continuing
 
 ### Team Mode (when agent teams are enabled)
-Spawn teammates for independent domains:
+Spawn teammates for domains within the same wave. Only domains in the same wave can run in parallel — do not spawn teammates for domains in different waves simultaneously:
 
 ```
 Create an agent team for execution:
@@ -86,18 +123,14 @@ RULES FOR ALL TEAMMATES:
 - After completing each task, message the lead with:
   "DONE: {domain} Task {N} - {summary of what was created/modified}"
 - If you need to deviate from a contract, STOP and message the lead
-- Commit after each task: [{domain}] Task {N}: {description}
+- **Commit immediately after each task**: `feat({domain}/task-{N}): {description}` — do NOT batch commits
+- **Deviation Rules**: (1) Bug blocking progress → fix, 3 attempts max; (2) Missing dependency → add minimum needed; (3) Blocker → fix and log to deferred-items.md; (4) Architectural change → STOP, message lead, never self-approve
 
 Teammate assignments:
 - Teammate "{domain-1}": Execute .gsd-t/domains/{domain-1}/tasks.md
 - Teammate "{domain-2}": Execute .gsd-t/domains/{domain-2}/tasks.md
 - Teammate "{domain-3}": Execute .gsd-t/domains/{domain-3}/tasks.md
-- Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: execute. Read .gsd-t/contracts/ for contract definitions.
-  Run tests continuously as tasks complete. Write edge case tests.
-  Report: test pass/fail status after each task completion.
-
-Lead responsibilities:
+Lead responsibilities (QA is handled via Task subagent — spawn one after each domain checkpoint):
 - Use delegate mode (Shift+Tab)
 - Track completions from teammate messages
 - When a CHECKPOINT is reached:

package/commands/gsd-t-health.md

@@ -0,0 +1,138 @@
+# GSD-T: Health — Validate Project Structure
+
+You are diagnosing the health of a GSD-T project. Check every required file and directory, report findings, and optionally repair missing pieces.
+
+## Step 0: Launch via Subagent (default)
+
+When invoked directly by the user, spawn yourself as a Task subagent for a fresh context window:
+
+```
+Task subagent (general-purpose, model: haiku):
+"Run the GSD-T health check. Read commands/gsd-t-health.md for your full instructions.
+Arguments: {$ARGUMENTS}
+Skip Step 0 — you are already the subagent."
+```
+
+Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
+
+## Step 1: Determine Mode
+
+If `--repair` appears in $ARGUMENTS, set `REPAIR=true`. Otherwise `REPAIR=false`.
+
+## Step 2: Check Required Structure
+
+Check each item below. Record status as `OK`, `MISSING`, or `INVALID`.
+
+### Root files
+| File | Check |
+|------|-------|
+| `CLAUDE.md` | Exists and non-empty |
+| `README.md` | Exists and non-empty |
+| `.gsd-t/progress.md` | Exists, has `## Status:` and `## Version:` sections |
+| `.gsd-t/backlog.md` | Exists |
+| `.gsd-t/backlog-settings.md` | Exists |
+
+### Required directories
+| Directory | Check |
+|-----------|-------|
+| `.gsd-t/contracts/` | Exists |
+| `.gsd-t/domains/` | Exists |
+| `docs/` | Exists |
+
+### Docs
+| File | Check |
+|------|-------|
+| `docs/requirements.md` | Exists |
+| `docs/architecture.md` | Exists |
+| `docs/workflows.md` | Exists |
+| `docs/infrastructure.md` | Exists |
+
+### Active milestone (if any)
+Read `.gsd-t/progress.md` to find active milestone. For each domain listed as active:
+- `.gsd-t/domains/{domain}/scope.md` — exists?
+- `.gsd-t/domains/{domain}/tasks.md` — exists?
+- `.gsd-t/contracts/` — at least one `.md` contract file present?
+
+## Step 3: Additional Checks
+
+1. **Version consistency**: Read `## Version:` from `.gsd-t/progress.md`. If `package.json` exists, compare — they should match.
+2. **Status validity**: Read `## Status:` value. Confirm it's one of: `DEFINED`, `PARTITIONED`, `DISCUSSED`, `PLANNED`, `EXECUTED`, `SYNCED`, `INTEGRATED`, `VERIFIED`, `VERIFIED-WITH-WARNINGS`, `VERIFY-FAILED`, `COMPLETED`.
+3. **Decision Log**: Confirm `## Decision Log` section exists and has at least one entry.
+4. **Contract integrity**: For each `.md` file in `.gsd-t/contracts/`, confirm it's non-empty.
+5. **Domain integrity**: For each directory in `.gsd-t/domains/`, confirm at least `scope.md` exists.
+
+## Step 4: Report Findings
+
+Output a health report in this format:
+
+```
+GSD-T Health Report
+═══════════════════════════════════════════════════════════
+
+Core Files
+  ✓ CLAUDE.md
+  ✓ README.md
+  ✗ .gsd-t/progress.md — MISSING
+  ✓ .gsd-t/backlog.md
+
+Directories
+  ✓ .gsd-t/contracts/
+  ✗ docs/ — MISSING
+
+Docs
+  ✓ docs/requirements.md
+  ✗ docs/architecture.md — MISSING
+
+Active Milestone: {name | none}
+  ✓ .gsd-t/domains/{domain}/scope.md
+  ✗ .gsd-t/domains/{domain}/tasks.md — MISSING
+
+Additional Checks
+  ✓ Version: 2.27.10 (consistent with package.json)
+  ✓ Status: PLANNED (valid)
+  ✓ Decision Log: present
+  ✗ contracts/api-contract.md — EMPTY
+
+═══════════════════════════════════════════════════════════
+Summary: {N} OK  |  {N} missing  |  {N} invalid
+Overall: {HEALTHY | DEGRADED | BROKEN}
+```
+
+Status thresholds:
+- **HEALTHY**: 0 missing, 0 invalid
+- **DEGRADED**: 1-3 missing/invalid (non-critical)
+- **BROKEN**: 4+ missing/invalid OR progress.md missing OR contracts/ missing
+
+## Step 5: Repair (if --repair)
+
+If `REPAIR=true` and any items are MISSING (not INVALID), create them now:
+
+| Missing item | Repair action |
+|--------------|---------------|
+| `CLAUDE.md` | Create from `templates/CLAUDE-project.md` (with `{Project Name}` = directory name) |
+| `README.md` | Create minimal `# {Project Name}\n\n_No description yet._\n` |
+| `.gsd-t/progress.md` | Create from `templates/progress.md` |
+| `.gsd-t/backlog.md` | Create from `templates/backlog.md` |
+| `.gsd-t/backlog-settings.md` | Create from `templates/backlog-settings.md` |
+| `.gsd-t/contracts/` | Create empty directory |
+| `.gsd-t/domains/` | Create empty directory |
+| `docs/` | Create directory |
+| `docs/requirements.md` | Create from `templates/requirements.md` |
+| `docs/architecture.md` | Create from `templates/architecture.md` |
+| `docs/workflows.md` | Create from `templates/workflows.md` |
+| `docs/infrastructure.md` | Create from `templates/infrastructure.md` |
+| Domain `scope.md` | Create minimal scope with domain name as heading |
+| Domain `tasks.md` | Create minimal task list with `## Tasks\n_No tasks defined yet._` |
+
+After repair, re-run the checks and report the final state.
+
+**Do NOT repair INVALID items** (e.g., empty contracts, bad status values) — flag them for user action.
+
+## Step 6: Next Steps
+
+If HEALTHY → "✅ GSD-T structure is healthy — all required files present."
+If DEGRADED with --repair done → "✅ Repaired {N} missing files. Run /user:gsd-t-health again to confirm."
+If DEGRADED without --repair → "⚠ Run /user:gsd-t-health --repair to create {N} missing files."
+If BROKEN → "🔴 Project structure is broken. Run /user:gsd-t-health --repair or /user:gsd-t-init to rebuild."
+
+$ARGUMENTS

package/commands/gsd-t-help.md

@@ -51,6 +51,8 @@ UTILITIES                                                              Manual
   resume              Restore context after break
   quick               Fast task with GSD-T guarantees
   debug               Systematic debugging with state
+  health              Validate .gsd-t/ structure, optionally repair missing files
+  pause               Save exact position for reliable resume later
   promote-debt        Convert techdebt items to milestones
   populate            Auto-populate docs from existing codebase
   log                 Sync progress Decision Log with recent git activity

package/commands/gsd-t-init-scan-setup.md

@@ -39,15 +39,38 @@ All subsequent steps run from inside the project directory.
 
 Execute the full init workflow (same as `/user:gsd-t-init`):
 
-1. Create `.gsd-t/` directory structure (contracts/, domains/, progress.md, backlog.md, backlog-settings.md)
+1. Create `.gsd-t/` directory structure (contracts/, domains/, progress.md, backlog.md, backlog-settings.md, token-log.md, qa-issues.md)
 2. Ensure `CLAUDE.md` exists (create starter if missing, append GSD-T section if present without it)
 3. Create `docs/` with all 4 living document templates (skip existing files)
 4. Ensure `README.md` exists
-5. Map existing codebase if code exists
-6. Initialize backlog with auto-derived categories
-7. Register project in `~/.claude/.gsd-t-projects`
-
-**If `.gsd-t/` already exists**: Skip init — it's already done. Log and continue to scan.
+5. **Copy project settings**:
+   - First, ensure `~/.claude/settings.local` exists. If it does NOT, create it with these defaults:
+     ```json
+     {
+       "permissions": {
+         "allow": [
+           "Edit",
+           "Write",
+           "Bash",
+           "Read",
+           "WebSearch",
+           "WebFetch",
+           "Skill"
+         ]
+       },
+       "outputStyle": "default"
+     }
+     ```
+     Log: "Created ~/.claude/settings.local with default permissions — update the allow list to match your security preferences."
+   - Then, if `.claude/settings.local.json` does NOT already exist in the project root:
+     - Create `.claude/` directory in the project root if needed
+     - Copy `~/.claude/settings.local` → `.claude/settings.local.json`
+   - Skip the copy silently if the target already exists
+6. Map existing codebase if code exists
+7. Initialize backlog with auto-derived categories
+8. Register project in `~/.claude/.gsd-t-projects`
+
+**If `.gsd-t/` already exists**: Skip init — it's already done. Log and continue to scan. Still check and copy settings.local (step 5) even if init is skipped.
 
 ## Step 4: Deep Codebase Scan (gsd-t-scan)