@tekyzinc/gsd-t 3.12.14 → 3.13.10

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

@@ -9,6 +9,10 @@ This command is:
 
 ## Step 1: Verify Completion
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 1 --step-label "Verify Completion" 2>/dev/null || true
+```
+
 Read:
 1. `.gsd-t/progress.md` — confirm status is VERIFIED
 2. `.gsd-t/verify-report.md` — confirm all checks passed
@@ -20,6 +24,10 @@ If `--force` flag provided, proceed with warning in archive.
 
 ## Step 1.25: Graph-Enhanced Completion Check
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 1 --step-label ".25: Graph-Enhanced Completion Check" 2>/dev/null || true
+```
+
 If `.gsd-t/graph/meta.json` exists (graph index is available):
 1. Query `getEntitiesByDomain` to validate all planned entities were implemented — compare against domain task lists
 2. Query `findDeadCode` to flag unreachable implementations that may indicate incomplete wiring or orphaned code
@@ -29,6 +37,10 @@ If graph is not available, skip this step.
 
 ## Step 1.5: Smoke Test Artifact Gate (MANDATORY — Categories 2 and 7)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 1 --step-label ".5: Smoke Test Artifact Gate (MANDATORY — Categories 2 and 7)" 2>/dev/null || true
+```
+
 Before archiving, verify that high-risk features have testable artifacts. This gate catches what code review and unit tests cannot.
 
 **Scan this milestone's domains for any of the following:**
@@ -53,6 +65,10 @@ Do not proceed to archiving. Create the smoke test now, run it, confirm it passe
 
 ## Step 1.75: Goal-Backward Verification Gate (MANDATORY)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 1 --step-label ".75: Goal-Backward Verification Gate (MANDATORY)" 2>/dev/null || true
+```
+
 Before archiving, verify that milestone goals are actually achieved end-to-end — not just structurally present. This catches placeholder implementations that passed all quality gates.
 
 Refer to `.gsd-t/contracts/goal-backward-contract.md` for the full verification flow, placeholder patterns, and findings report format.
@@ -105,6 +121,10 @@ Refer to `.gsd-t/contracts/goal-backward-contract.md` for the full verification
 
 ## Step 2: Gap Analysis Gate
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 2 --step-label "Gap Analysis Gate" 2>/dev/null || true
+```
+
 After verification passes, run a gap analysis against `docs/requirements.md` scoped to this milestone's deliverables:
 
 1. Identify which requirements this milestone was supposed to satisfy (from domain scopes, tasks, and milestone definition)
@@ -121,6 +141,10 @@ This is a **mandatory gate** — the milestone cannot be archived with known gap
 
 ## Step 2.5: Distillation — Extract Milestone Patterns
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 2 --step-label ".5: Distillation — Extract Milestone Patterns" 2>/dev/null || true
+```
+
 Before archiving, extract learning from the event stream to improve future runs.
 
 1. Check if `.gsd-t/events/` exists and has any `.jsonl` files for this milestone period
@@ -142,6 +166,10 @@ Before archiving, extract learning from the event stream to improve future runs.
 
 ### Step 2.5b: Rule Engine Distillation
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 2 --step-label ".5b: Rule Engine Distillation" 2>/dev/null || true
+```
+
 After event-stream pattern detection, run rule-based distillation using the declarative rule engine and patch lifecycle:
 
 1. **Rule Evaluation**: Run via Bash:
@@ -166,6 +194,10 @@ After event-stream pattern detection, run rule-based distillation using the decl
 
 ### Step 2.5c: Global Rule Promotion
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 2 --step-label ".5c: Global Rule Promotion" 2>/dev/null || true
+```
+
 After local rule promotion completes, propagate newly promoted rules to global metrics:
 
 1. **Check for promoted rules**: Run via Bash:
@@ -247,6 +279,10 @@ After local rule promotion completes, propagate newly promoted rules to global m
 
 ### Step 2.5d: Component Impact Evaluation (if available)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 2 --step-label ".5d: Component Impact Evaluation (if available)" 2>/dev/null || true
+```
+
 Record impact data for each active component:
 
 1. **Record component impact** — for each domain that completed tasks, run via Bash:
@@ -256,6 +292,10 @@ Record impact data for each active component:
 
 ## Step 3: Gather Milestone Artifacts
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 3 --step-label "Gather Milestone Artifacts" 2>/dev/null || true
+```
+
 Collect all files related to this milestone:
 - `.gsd-t/progress.md` (current state)
 - `.gsd-t/verify-report.md`
@@ -266,6 +306,10 @@ Collect all files related to this milestone:
 
 ## Step 4: Create Archive
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 4 --step-label "Create Archive" 2>/dev/null || true
+```
+
 Create milestone archive directory:
 
 ```
@@ -283,6 +327,10 @@ Create milestone archive directory:
 
 ## Step 5: Generate Summary
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 5 --step-label "Generate Summary" 2>/dev/null || true
+```
+
 Create `summary.md`:
 
 ```markdown
@@ -323,6 +371,10 @@ Create `summary.md`:
 
 ## Step 6: Bump Version
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 6 --step-label "Bump Version" 2>/dev/null || true
+```
+
 GSD-T tracks project version in `.gsd-t/progress.md` using semantic versioning: `Major.Minor.Patch`
 
 - **Major** (X.0.0): Breaking changes, major rework, v1 launch
@@ -343,6 +395,10 @@ Determine the version bump based on the milestone:
 
 ## Step 7: Clean Working State
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 7 --step-label "Clean Working State" 2>/dev/null || true
+```
+
 Reset `.gsd-t/` for next milestone:
 
 1. Archive current domains → `.gsd-t/milestones/{name}/domains/`
@@ -351,6 +407,14 @@ Reset `.gsd-t/` for next milestone:
 4. Clear `.gsd-t/impact-report.md`, `.gsd-t/test-coverage.md`
 5. Update `.gsd-t/progress.md`:
 
+**CRITICAL — Decision Log Trim**: This trim happens AFTER Step 4's archive copy of `.gsd-t/progress.md` is written. The archive snapshot at `.gsd-t/milestones/{name}-{date}/progress.md` is the source-of-truth for full history. The live Decision Log is reset to the just-completed milestone's entries only — everything dated before the milestone's start date is deleted from the live file (it remains in the archive). This prevents the live progress.md from growing without bound.
+
+Steps to apply the trim:
+- Identify the just-completed milestone's start date (typically the `[milestone-defined]` entry for this milestone)
+- Delete all Decision Log entries dated BEFORE that start date from the live `.gsd-t/progress.md`
+- Keep entries from the start date onward (they cover the milestone arc + the completion entry you're about to add)
+- Prepend the pointer line shown below
+
 ```markdown
 # GSD-T Progress
 
@@ -365,12 +429,19 @@ None — ready for next milestone
 | {previous} | {version} | {date} | v{version} |
 
 ## Decision Log
+
+> Prior decision log entries preserved in `.gsd-t/milestones/*/progress.md` — see archive snapshots for pre-{next-milestone-name} history.
+
 - {date}: [success] Milestone "{name}" completed — {summary of what was built}. v{version}
-{Keep all prior decision log entries — they are valuable context}
+{Trim: delete all decision-log entries older than the just-completed milestone's start date. Those entries are preserved in the milestone archive created in Step 4. Keep only the completion entry above plus any entries logged on or after the cutoff — typically the live log is near-empty when the next milestone begins.}
 ```
 
 ## Step 8: Update README.md
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 8 --step-label "Update README.md" 2>/dev/null || true
+```
+
 If `README.md` exists, update it to reflect the completed milestone:
 - Add or update a **Features** / **What's Included** section with capabilities delivered
 - Update version number if displayed in README
@@ -382,6 +453,10 @@ If `README.md` doesn't exist, create one with project name, description, version
 
 ## Step 8.5: Scan Doc Milestone Checkpoint
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 8 --step-label ".5: Scan Doc Milestone Checkpoint" 2>/dev/null || true
+```
+
 Before tagging, ensure scan docs reflect the final state of the codebase after all milestone work. This is the full-refresh counterpart to the micro-updates done during execute/quick/debug.
 
 If `.gsd-t/scan/` exists (a prior scan has been run):
@@ -402,6 +477,10 @@ If `.gsd-t/scan/` doesn't exist → skip (no scan data to maintain).
 
 ## Step 8.7: Generate Metrics Rollup
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 8 --step-label ".7: Generate Metrics Rollup" 2>/dev/null || true
+```
+
 Generate milestone-level metrics aggregation and ELO score:
 
 1. Run via Bash:
@@ -428,6 +507,10 @@ Include ELO score in the milestone summary (Step 5) and git tag message (Step 11
 
 ## Step 9: Document Ripple
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 9 --step-label "Document Ripple" 2>/dev/null || true
+```
+
 Before creating the git tag, verify all documentation is up to date:
 
 ### Always update:
@@ -446,6 +529,10 @@ Before creating the git tag, verify all documentation is up to date:
 
 ## Step 10: Test Verification
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 10 --step-label "Test Verification" 2>/dev/null || true
+```
+
 Verify the milestone is truly complete:
 
 1. **Run ALL configured test suites** — detect and run every one:
@@ -460,6 +547,10 @@ Verify the milestone is truly complete:
 
 ## Step 11: Create Git Tag
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 11 --step-label "Create Git Tag" 2>/dev/null || true
+```
+
 ```bash
 # Stage any remaining .gsd-t changes
 git add .gsd-t/
@@ -478,6 +569,10 @@ Verified: {date}"
 
 ## Step 12: Report Completion
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 12 --step-label "Report Completion" 2>/dev/null || true
+```
+
 ```
 ✅ Milestone "{name}" completed — v{version}
 
@@ -499,6 +594,10 @@ Next steps:
 
 ## Step 13: Update Roadmap (if exists)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-complete-milestone --step 13 --step-label "Update Roadmap (if exists)" 2>/dev/null || true
+```
+
 If `.gsd-t/roadmap.md` exists:
 - Mark this milestone as complete
 - Update any dependent milestones

package/commands/gsd-t-debug.md

@@ -26,6 +26,10 @@ Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
 
 ## Step 0.1: Launch via Subagent
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 0 --step-label ".1: Launch via Subagent" 2>/dev/null || true
+```
+
 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):
@@ -117,6 +121,10 @@ Continue to Step 1 below.
 
 ## Step 1: Load Context
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 1 --step-label "Load Context" 2>/dev/null || true
+```
+
 Read:
 1. `CLAUDE.md`
 2. `.gsd-t/progress.md`
@@ -125,6 +133,10 @@ Read:
 
 ## Step 1.5: Debug Loop Detection (MANDATORY)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 1 --step-label ".5: Debug Loop Detection (MANDATORY)" 2>/dev/null || true
+```
+
 Before attempting any fix, check whether this issue has been through multiple failed debug sessions. This prevents the 10–20 attempt death spiral that happens when the same approach is retried repeatedly.
 
 **Detection:**
@@ -207,6 +219,10 @@ Please select an option (or provide your own direction) before I proceed.
 
 ## Step 1.7: Experience Retrieval
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 1 --step-label ".7: Experience Retrieval" 2>/dev/null || true
+```
+
 Before proceeding to classification and fix, retrieve relevant past failures from the Decision Log.
 
 Run via Bash:
@@ -223,6 +239,10 @@ If no results found: proceed normally to Step 2.
 
 ## Step 1.7: Graph-Enhanced Root Cause Tracing (if available)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 1 --step-label ".7: Graph-Enhanced Root Cause Tracing (if available)" 2>/dev/null || true
+```
+
 If `.gsd-t/graph/meta.json` exists, use the graph to accelerate root cause identification:
 
 1. **Call chain from error**: `query('getCallers', { entity: '{error_function}' })` → trace backward from the error location
@@ -235,6 +255,10 @@ Graph results replace the manual "classify the bug" analysis in Step 2 — the c
 
 ## Step 2: Classify the Bug
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 2 --step-label "Classify the Bug" 2>/dev/null || true
+```
+
 Based on the user's description ($ARGUMENTS) and graph analysis (if available), determine:
 
 ### A) Within-Domain Bug
@@ -265,6 +289,10 @@ The contract didn't specify something it should have. Symptoms:
 
 ## Step 2.5: Reproduce First (MANDATORY — Category 5)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 2 --step-label ".5: Reproduce First (MANDATORY — Category 5)" 2>/dev/null || true
+```
+
 **A fix attempt without a reproduction script is a guess, not a fix.**
 
 Before touching any code:
@@ -286,6 +314,10 @@ Before touching any code:
 
 ## Step 3: Debug (Solo or Team)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 3 --step-label "Debug (Solo or Team)" 2>/dev/null || true
+```
+
 ### Deviation Rules
 
 When you encounter unexpected situations during the fix:
@@ -330,6 +362,10 @@ First to find root cause: message the lead with findings.
 
 ## Step 4: Document Ripple
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 4 --step-label "Document Ripple" 2>/dev/null || true
+```
+
 After fixing, assess what documentation was affected by the change and update ALL relevant files:
 
 ### Always check:
@@ -366,6 +402,10 @@ Skip scan docs not affected by this fix. Skip analytical sections — those requ
 
 ## Step 5: Test Verification (run tests confirming fix)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 5 --step-label "Test Verification (run tests confirming fix)" 2>/dev/null || true
+```
+
 Before committing, ensure the fix is solid:
 
 1. **Update tests**: If the bug reveals a missing test case, add one that would have caught it
@@ -395,6 +435,10 @@ Commit: `[debug] Fix {description} — root cause: {explanation}`
 
 ## Step 5.3: Red Team — Adversarial QA (MANDATORY)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 5 --step-label ".3: Red Team — Adversarial QA (MANDATORY)" 2>/dev/null || true
+```
+
 After the fix passes all tests, spawn an adversarial Red Team agent to BREAK the fix and find regressions.
 
 ⚙ [opus] Red Team → adversarial validation of debug fix
@@ -422,6 +466,10 @@ Append to `.gsd-t/token-log.md`:
 
 ## Step 5.5: Emit Task Metrics
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 5 --step-label ".5: Emit Task Metrics" 2>/dev/null || true
+```
+
 After committing, emit a task-metrics record for this debug session — run via Bash:
 `node bin/metrics-collector.js --milestone {current-milestone-or-none} --domain {domain-or-debug} --task debug-{timestamp} --command debug --duration_s {elapsed} --tokens_used {estimated} --context_pct ${CTX_PCT:-0} --pass {true|false} --fix_cycles {attempts} --signal_type debug-invoked --notes "[debug] {description}" 2>/dev/null || true`
 
@@ -432,6 +480,10 @@ Emit task_complete event — run via Bash:
 
 ## Step 6: Doc-Ripple (Automated)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-debug --step 6 --step-label "Doc-Ripple (Automated)" 2>/dev/null || true
+```
+
 After all work is committed but before reporting completion:
 
 1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions

package/commands/gsd-t-execute.md

@@ -56,6 +56,10 @@ Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0. Selection is determin
 
 ## Step 0.1: Verify Context Gate Readiness (MANDATORY — first thing in a fresh session)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 0 --step-label ".1: Verify Context Gate Readiness (MANDATORY — first thing in a fresh session)" 2>/dev/null || true
+```
+
 Run via Bash:
 
 ```bash
@@ -70,6 +74,10 @@ Why: every `/gsd-t-execute` invocation is a fresh orchestrator session and needs
 
 ## Step 1: Load State
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 1 --step-label "Load State" 2>/dev/null || true
+```
+
 Read:
 1. `CLAUDE.md` — check for **Branch Guard** (`Expected branch` field)
 2. `.gsd-t/progress.md`
@@ -87,6 +95,10 @@ Identify:
 
 ## Step 1.5: Graph-Enhanced Domain Isolation Check (if available)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 1 --step-label ".5: Graph-Enhanced Domain Isolation Check (if available)" 2>/dev/null || true
+```
+
 If `.gsd-t/graph/meta.json` exists, run graph queries before execution begins:
 
 1. **Reindex** (if stale): `query('reindex', { force: false })` — ensure graph reflects current code
@@ -98,6 +110,10 @@ After each domain completes, re-run `getDomainBoundaryViolations` and diff again
 
 ## Step 2: QA Subagent
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 2 --step-label "QA Subagent" 2>/dev/null || true
+```
+
 In solo mode, QA runs inside each domain subagent (see Step 3). In team mode, the lead spawns QA subagents at each domain checkpoint using the pattern below.
 
 **QA subagent prompt** — `spawnType: 'validation'` (always headless, `--watch` ignored per headless-default-contract §2):
@@ -114,6 +130,10 @@ If QA found issues, append each to `.gsd-t/qa-issues.md` (create with header `|
 
 ## Step 3: Choose Execution Mode
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 3 --step-label "Choose Execution Mode" 2>/dev/null || true
+```
+
 ### 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).
@@ -651,6 +671,10 @@ Cleanup is not optional — orphaned worktrees waste disk space and can confuse
 
 ## Step 3.5: Orchestrator Context Gate (MANDATORY)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 3 --step-label ".5: Orchestrator Context Gate (MANDATORY)" 2>/dev/null || true
+```
+
 Single-band context gate per `.gsd-t/contracts/context-meter-contract.md` v1.3.0. The orchestrator checks `getSessionStatus()` BEFORE every task subagent spawn. `bin/token-budget.cjs` reads `.gsd-t/.context-meter-state.json` — the token estimate produced by the Context Meter PostToolUse hook.
 
 **Before each task spawn — gate check:**
@@ -670,6 +694,10 @@ The threshold percentage (default `75`) lives in `.gsd-t/context-meter-config.js
 
 ## Step 4: Checkpoint Handling
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 4 --step-label "Checkpoint Handling" 2>/dev/null || true
+```
+
 When a checkpoint is reached (solo or team):
 
 1. **Stop** execution of blocked tasks
@@ -685,6 +713,10 @@ When a checkpoint is reached (solo or team):
 
 ## Step 5: Error Handling
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 5 --step-label "Error Handling" 2>/dev/null || true
+```
+
 ### Contract Violation
 A teammate implements something that doesn't match a contract:
 1. Stop the teammate
@@ -709,6 +741,10 @@ A teammate finishes independent tasks and is waiting on a checkpoint:
 
 ## Step 5.25: Design Verification Agent (per-domain, MANDATORY when design contract exists)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 5 --step-label ".25: Design Verification Agent (per-domain, MANDATORY when design contract exists)" 2>/dev/null || true
+```
+
 **IMPORTANT — frequency change in v2.74.12**: Design Verification was previously run once at the end of every execute run, regardless of how many domains existed. It is now run ONCE PER COMPLETED DOMAIN — call this step from the "After all tasks in a domain complete" block (Step 3.5 area), not from a global post-execute hook. This keeps verification co-located with the changes that introduced visual deviation, but stops the agent from re-materializing on every task spawn (which is what commit `b68353e` accidentally caused).
 
 After all tasks in the CURRENT DOMAIN complete and per-task QA has passed, check if `.gsd-t/contracts/design-contract.md` exists. If it does NOT exist, skip this step entirely.
@@ -763,6 +799,10 @@ After the Design Verification Agent returns, check `.gsd-t/contracts/design-cont
 
 ## Step 5.5: Red Team — Adversarial QA (per-domain, MANDATORY)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 5 --step-label ".5: Red Team — Adversarial QA (per-domain, MANDATORY)" 2>/dev/null || true
+```
+
 **IMPORTANT — frequency change in v2.74.12**: Red Team was promoted to per-task by commit `da6d3ae` on the assumption that the orchestrator would catch context drain via an environment-variable-based self-check. That env-var path was never populated by Claude Code, so the check was inert and the per-task spawning of ~10k-token Red Team subagents was the largest single contributor to the v2.74.x context-burn regression. Red Team is now run ONCE PER COMPLETED DOMAIN — call this step from the "After all tasks in a domain complete" block, not from a per-task hook.
 
 After all tasks in the CURRENT DOMAIN pass their tests, spawn an adversarial Red Team agent. Its sole purpose is to BREAK the domain that was just built.
@@ -808,6 +848,10 @@ Append to `.gsd-t/token-log.md`:
 
 ## Step 6: Completion
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 6 --step-label "Completion" 2>/dev/null || true
+```
+
 When all tasks in all domains are complete:
 1. Update `.gsd-t/progress.md` — all tasks marked complete
 2. Set status to `EXECUTED`
@@ -821,6 +865,10 @@ When all tasks in all domains are complete:
 
 ## Step 7: Doc-Ripple (Automated)
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-execute --step 7 --step-label "Doc-Ripple (Automated)" 2>/dev/null || true
+```
+
 After all work is committed but before reporting completion:
 
 1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions

package/commands/gsd-t-feature.md

@@ -4,6 +4,10 @@ You are the lead agent planning a significant new feature for an existing codeba
 
 ## Step 0.5: Scan Freshness Auto-Refresh
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 0 --step-label ".5: Scan Freshness Auto-Refresh" 2>/dev/null || true
+```
+
 Before reading scan data for impact analysis, check if scan docs are stale and auto-refresh if needed. This ensures feature planning is based on current code — no warnings, no user involvement.
 
 If `.gsd-t/scan/.cache.json` exists:
@@ -22,6 +26,10 @@ If `.gsd-t/scan/` doesn't exist at all → skip (no scan data to refresh).
 
 ## Step 1: Understand What Exists
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 1 --step-label "Understand What Exists" 2>/dev/null || true
+```
+
 Read everything:
 1. `CLAUDE.md` — project conventions, stack, patterns
 2. `.gsd-t/progress.md` — completed milestones, decision history
@@ -50,6 +58,10 @@ Note what you find — this informs Step 3's Multi-Consumer Check and Step 4's m
 
 ## Step 1.5: Graph-Enhanced Blast Radius Analysis
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 1 --step-label ".5: Graph-Enhanced Blast Radius Analysis" 2>/dev/null || true
+```
+
 If `.gsd-t/graph/meta.json` exists (graph index is available):
 1. Query `getSurfaceConsumers` and `getCallers` on functions likely affected by the feature to calculate blast radius across all consumer surfaces
 2. Query `getTransitiveCallers` for deep impact chains that may not be obvious from architecture docs alone
@@ -59,6 +71,10 @@ If graph is not available, skip this step.
 
 ## Step 2: Understand the Feature
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 2 --step-label "Understand the Feature" 2>/dev/null || true
+```
+
 From $ARGUMENTS and conversation:
 - What does this feature do?
 - Who uses it?
@@ -74,6 +90,10 @@ If context is thin, ask targeted questions:
 
 ## Step 3: Impact Analysis
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 3 --step-label "Impact Analysis" 2>/dev/null || true
+```
+
 Before planning milestones, analyze how this feature touches the existing system.
 
 ### Team Mode (recommended for large codebases)
@@ -149,6 +169,10 @@ Produce a combined analysis:
 
 ## Step 4: Decompose into Milestones
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 4 --step-label "Decompose into Milestones" 2>/dev/null || true
+```
+
 The feature may be a single milestone or multiple, depending on scope:
 
 ### Single Milestone (if feature is focused):
@@ -216,6 +240,10 @@ Append to `.gsd-t/roadmap.md` (or create if doesn't exist):
 
 ## Step 5: Reconcile with Existing State
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 5 --step-label "Reconcile with Existing State" 2>/dev/null || true
+```
+
 Critical step — make sure the new milestones fit with what's already built:
 
 1. **Check for conflicts**: Do new milestones conflict with in-progress work?
@@ -228,6 +256,10 @@ If conflicts exist, present them to the user with options:
 
 ## Step 6: Update Project State
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 6 --step-label "Update Project State" 2>/dev/null || true
+```
+
 Update `.gsd-t/progress.md`:
 - Add new milestones to the table
 - Log the feature addition in Decision Log
@@ -235,6 +267,10 @@ Update `.gsd-t/progress.md`:
 
 ## Step 7: Document Ripple
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 7 --step-label "Document Ripple" 2>/dev/null || true
+```
+
 After creating the feature roadmap and milestones, update all affected documentation:
 
 ### Always update:
@@ -252,6 +288,10 @@ After creating the feature roadmap and milestones, update all affected documenta
 
 ## Step 8: Test Verification
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 8 --step-label "Test Verification" 2>/dev/null || true
+```
+
 Before finalizing the feature plan:
 
 1. **Run existing tests**: Execute the full test suite to confirm the codebase is in a clean state before feature work begins
@@ -260,6 +300,10 @@ Before finalizing the feature plan:
 
 ## Step 9: Report to User
 
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-feature --step 9 --step-label "Report to User" 2>/dev/null || true
+```
+
 Present:
 1. Impact analysis summary (what's new vs. what's modified)
 2. Milestone breakdown for the feature