@tekyzinc/gsd-t 2.24.7 → 2.28.12

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 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
+- **CLAUDE.md update no longer overwrites user content**: Installer now uses marker-based merging (`<!-- GSD-T:START -->` / `<!-- GSD-T:END -->`). Updates only replace the GSD-T section between markers, preserving all user customizations. Existing installs without markers are auto-migrated. Backup still created for reference
+
 ## [2.24.7] - 2026-02-18
 
 ### Changed

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) {
@@ -483,47 +503,80 @@ function installCommands(isUpdate) {
   return { gsdtCommands, utilityCommands };
 }
 
+const GSDT_START = "<!-- GSD-T:START";
+const GSDT_END = "<!-- GSD-T:END";
+
 function installGlobalClaudeMd(isUpdate) {
   heading("Global CLAUDE.md");
   const globalSrc = path.join(PKG_TEMPLATES, "CLAUDE-global.md");
 
   if (!fs.existsSync(GLOBAL_CLAUDE_MD)) {
-    copyFile(globalSrc, GLOBAL_CLAUDE_MD, "CLAUDE.md installed → ~/.claude/CLAUDE.md");
+    copyFile(globalSrc, GLOBAL_CLAUDE_MD, "CLAUDE.md installed");
+    return;
+  }
+
+  if (isSymlink(GLOBAL_CLAUDE_MD)) {
+    warn("Skipping CLAUDE.md — target is a symlink");
     return;
   }
 
   const existing = fs.readFileSync(GLOBAL_CLAUDE_MD, "utf8");
-  if (existing.includes("GSD-T: Contract-Driven Development")) {
-    updateExistingGlobalClaudeMd(globalSrc, existing, isUpdate);
+  const template = fs.readFileSync(globalSrc, "utf8");
+
+  if (existing.includes(GSDT_START)) {
+    mergeGsdtSection(existing, template, isUpdate);
+  } else if (existing.includes("GSD-T: Contract-Driven Development")) {
+    migrateToMarkers(existing, template);
   } else {
-    appendGsdtToClaudeMd(globalSrc);
+    appendGsdtToClaudeMd(template);
   }
 }
 
-function updateExistingGlobalClaudeMd(globalSrc, existing, isUpdate) {
+function mergeGsdtSection(existing, template, isUpdate) {
   if (!isUpdate) {
-    info("CLAUDE.md already contains GSD-T config — skipping");
-    info("Run 'gsd-t update' to overwrite with latest version");
+    info("CLAUDE.md already contains GSD-T config");
     return;
   }
-  const template = fs.readFileSync(globalSrc, "utf8");
-  if (normalizeEol(existing) === normalizeEol(template)) {
-    copyFile(globalSrc, GLOBAL_CLAUDE_MD, "CLAUDE.md updated (no customizations detected)");
+  const startIdx = existing.indexOf(GSDT_START);
+  const endMarkerIdx = existing.indexOf(GSDT_END);
+  if (startIdx === -1 || endMarkerIdx === -1) {
+    warn("GSD-T markers incomplete — appending fresh copy");
+    appendGsdtToClaudeMd(template);
+    return;
+  }
+  const endLineEnd = existing.indexOf("\n", endMarkerIdx);
+  const endIdx = endLineEnd === -1 ? existing.length : endLineEnd + 1;
+  const before = existing.substring(0, startIdx);
+  const after = existing.substring(endIdx);
+  const merged = before + template.trimEnd() + "\n" + after;
+  if (normalizeEol(merged) === normalizeEol(existing)) {
+    info("CLAUDE.md GSD-T section already up to date");
     return;
   }
   const backupPath = GLOBAL_CLAUDE_MD + ".backup-" + Date.now();
-  if (!isSymlink(backupPath)) fs.copyFileSync(GLOBAL_CLAUDE_MD, backupPath);
-  else warn("Skipping backup — target is a symlink");
-  copyFile(globalSrc, GLOBAL_CLAUDE_MD, "CLAUDE.md updated");
-  warn(`Previous version backed up to ${path.basename(backupPath)}`);
-  info("Review the backup if you had custom additions to merge back in.");
-}
-
-function appendGsdtToClaudeMd(globalSrc) {
-  if (isSymlink(GLOBAL_CLAUDE_MD)) { warn("Skipping CLAUDE.md append — target is a symlink"); return; }
-  const gsdtContent = fs.readFileSync(globalSrc, "utf8");
-  const separator = "\n\n# ─── GSD-T Section (added by installer) ───\n\n";
-  fs.appendFileSync(GLOBAL_CLAUDE_MD, separator + gsdtContent);
+  fs.copyFileSync(GLOBAL_CLAUDE_MD, backupPath);
+  fs.writeFileSync(GLOBAL_CLAUDE_MD, merged);
+  success("CLAUDE.md GSD-T section updated (custom content preserved)");
+}
+
+function migrateToMarkers(existing, template) {
+  const backupPath = GLOBAL_CLAUDE_MD + ".backup-" + Date.now();
+  fs.copyFileSync(GLOBAL_CLAUDE_MD, backupPath);
+  const sepIdx = existing.indexOf("# ─── GSD-T Section");
+  if (sepIdx !== -1) {
+    const before = existing.substring(0, sepIdx);
+    const merged = before + template.trimEnd() + "\n";
+    fs.writeFileSync(GLOBAL_CLAUDE_MD, merged);
+  } else {
+    fs.writeFileSync(GLOBAL_CLAUDE_MD, template);
+  }
+  success("CLAUDE.md migrated to marker-based format");
+  info("Backup saved: " + path.basename(backupPath));
+}
+
+function appendGsdtToClaudeMd(template) {
+  const separator = "\n\n";
+  fs.appendFileSync(GLOBAL_CLAUDE_MD, separator + template.trimEnd() + "\n");
   success("GSD-T config appended to existing CLAUDE.md");
   info("Your existing content was preserved.");
 }
@@ -543,6 +596,9 @@ function doInstall(opts = {}) {
 
   heading("Update Check (Session Start)");
   installUpdateCheck();
+
+  heading("Utility Scripts");
+  installUtilityScripts();
   saveInstalledVersion();
 
   showInstallSummary(gsdtCommands.length, utilityCommands.length);
@@ -1317,7 +1373,8 @@ module.exports = {
   checkDoctorClaudeMd,
   checkDoctorSettings,
   checkDoctorEncoding,
-  updateExistingGlobalClaudeMd,
+  mergeGsdtSection,
+  migrateToMarkers,
   appendGsdtToClaudeMd,
   readSettingsJson,
   readUpdateCache,

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,55 @@ 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 `date +%s` via Bash → save as START
+After subagent returns: run `date +%s` → compute `DURATION=$((END-START))`
+Append to `.gsd-t/token-log.md` (create with header `| Date | Command | Step | Model | Duration(s) | Notes |` if missing):
+`| {YYYY-MM-DD HH:MM} | gsd-t-execute | Step 2 | haiku | {DURATION}s | task: {task-name}, {pass/fail} |`
+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):
+`| {YYYY-MM-DD HH:MM} | 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 +88,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 +118,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: