@tekyzinc/gsd-t 2.31.18 → 2.33.12

package/README.md

@@ -7,6 +7,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Maintains test coverage** — automatically keeps tests aligned with code changes.
 **Catches downstream effects** — analyzes impact before changes break things.
 **Protects existing work** — destructive action guard prevents schema drops, architecture replacements, and data loss without explicit approval.
+**Visualizes execution in real time** — live browser dashboard renders agent hierarchy, tool activity, and phase progression from the event stream.
 
 ---
 
@@ -18,7 +19,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 42 GSD-T commands + 4 utility commands (46 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 44 GSD-T commands + 4 utility commands (48 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -144,6 +145,8 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-status` | Cross-domain progress view | Manual |
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees | Manual |
+| `/user:gsd-t-reflect` | Generate retrospective from event stream, propose memory updates | Manual |
+| `/user:gsd-t-visualize` | Launch browser dashboard — SSE server + React Flow agent visualization | 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 |
@@ -230,6 +233,8 @@ your-project/
 │   │       ├── scope.md
 │   │       ├── tasks.md
 │   │       └── constraints.md
+│   ├── events/                        # Execution event stream (JSONL, daily-rotated)
+│   ├── retrospectives/                # Retrospective reports from gsd-t-reflect
 │   ├── milestones/                    # Archived completed milestones
 │   │   └── {milestone-name}-{date}/
 │   └── scan/                          # Codebase analysis outputs
@@ -247,6 +252,7 @@ your-project/
 5. **State survives sessions.** Everything is in `.gsd-t/`.
 6. **Plan is single-brain, execute is multi-brain.** Planning and integration always solo; execution and verification can parallelize.
 7. **Every decision is logged.** The Decision Log captures why, not just what.
+8. **Agents learn from experience.** Every command invocation, phase transition, and subagent spawn is captured as a structured event. Past failures surface before each task (Reflexion pattern). Distillation converts repeated patterns into lasting CLAUDE.md rules.
 
 ---
 
@@ -298,8 +304,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 46 slash commands
-│   ├── gsd-t-*.md                     # 42 GSD-T workflow commands
+├── commands/                          # 48 slash commands
+│   ├── gsd-t-*.md                     # 44 GSD-T workflow commands
 │   ├── gsd.md                         # GSD-T smart router
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper
@@ -314,6 +320,12 @@ get-stuff-done-teams/
 │   ├── progress.md
 │   ├── backlog.md
 │   └── backlog-settings.md
+├── scripts/                           # Runtime utility scripts (installed to ~/.claude/scripts/)
+│   ├── gsd-t-tools.js                 # State CLI (get/set/validate/list)
+│   ├── gsd-t-statusline.js            # Context usage bar
+│   ├── gsd-t-event-writer.js          # Structured JSONL event writer
+│   ├── gsd-t-dashboard-server.js      # Zero-dep SSE server for dashboard
+│   └── gsd-t-dashboard.html           # React Flow + Dagre real-time dashboard
 ├── examples/
 │   ├── settings.json
 │   └── .gsd-t/

package/bin/gsd-t.js

@@ -518,7 +518,7 @@ function configureAutoRouteHook(scriptPath) {
 
 // ─── Utility Scripts ─────────────────────────────────────────────────────────
 
-const UTILITY_SCRIPTS = ["gsd-t-tools.js", "gsd-t-statusline.js"];
+const UTILITY_SCRIPTS = ["gsd-t-tools.js", "gsd-t-statusline.js", "gsd-t-event-writer.js", "gsd-t-dashboard-server.js", "gsd-t-dashboard.html"];
 
 function installUtilityScripts() {
   ensureDir(SCRIPTS_DIR);

package/commands/gsd-t-brainstorm.md

@@ -84,26 +84,42 @@ If mode is unclear, ask: "What kind of thinking would be most useful right now
 4. When energy shifts to a new idea, follow it
 5. Periodically collect the best ideas into a running list
 
-### Team Mode (if enabled and user requests):
+### Deep Research Phase (MANDATORY — always runs before Step 5):
+
+Before drawing any conclusions or presenting final insights, spawn a team of parallel research agents. **This is not optional.** No brainstorm session may land (Step 5) until this research phase is complete. The purpose is to ensure conclusions are grounded in evidence — not just intuition — so the brainstorm surfaces the genuinely best path forward and avoids going down the wrong path.
 
 **OBSERVABILITY LOGGING (MANDATORY):**
 Before spawning the team — 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}`
 
 ```
-Create an agent team for brainstorming:
-
-- Teammate "visionary": Push boundaries. What's the most ambitious
-  version? What would make this remarkable? Think in terms of
-  possibilities, not constraints.
-
-- Teammate "pragmatist": Keep it real. What can we actually build?
-  What's the shortest path to value? Where are the hidden costs?
-
-- Teammate "devil's advocate": Challenge everything. Why might this
-  fail? What are we not seeing? Which assumptions are weakest?
-
-Lead: Synthesize the best insights from all three perspectives.
+Spawn a deep research team (run all three in parallel):
+
+- Teammate "researcher-landscape": Search external sources, docs, and
+  prior art. What solutions already exist for this problem or idea?
+  What have others tried? What are the known pitfalls? What does the
+  current state of the art look like? Produce a research brief with
+  concrete findings and citations.
+
+- Teammate "researcher-alternatives": Enumerate 3–5 fundamentally
+  different technical or architectural approaches to this problem.
+  For each: what are the trade-offs, risks, costs, and prerequisites?
+  Which is most promising and why? Consider approaches that might
+  require a completely different direction from the current thinking.
+
+- Teammate "researcher-analogies": Look outside the immediate domain.
+  How have adjacent industries, other products, or different technical
+  domains solved similar problems? Find non-obvious analogies and
+  extract transferable insights that the team may not have considered.
+
+Lead: Wait for all three researchers to report before proceeding.
+Then synthesize:
+1. What did we learn that changes or validates the initial thinking?
+2. Which ideas from the brainstorm are supported by research findings?
+3. Which ideas should be reconsidered or ruled out based on evidence?
+4. What is the most promising path forward, and what is the evidence for it?
+
+Do NOT proceed to Step 5 until this synthesis is complete.
 ```
 
 After team completes — run via Bash:
@@ -112,7 +128,7 @@ 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-brainstorm | Step 3 | sonnet | {DURATION}s | team brainstorm: {topic summary} | {TOKENS} | {COMPACTED} |`
+`| {DT_START} | {DT_END} | gsd-t-brainstorm | Step 3 | sonnet | {DURATION}s | deep research: {topic summary} | {TOKENS} | {COMPACTED} |`
 
 ## Step 4: Capture the Sparks
 

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

@@ -57,6 +57,27 @@ After verification passes, run a gap analysis against `docs/requirements.md` sco
 
 This is a **mandatory gate** — the milestone cannot be archived with known gaps against its requirements.
 
+## Step 2.5: Distillation — Extract Milestone Patterns
+
+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
+   - If no events files found: skip distillation (log "No events recorded — distillation skipped"), continue to Step 3
+   - If event-writer not installed (`node ~/.claude/scripts/gsd-t-event-writer.js 2>/dev/null || true`): skip gracefully
+
+2. Parse events: scan `.gsd-t/events/*.jsonl` for events with `"outcome":"failure"` or `"outcome":"learning"`
+
+3. Group by `reasoning` field value — count occurrences of each distinct reasoning string
+
+4. For each group with ≥ 3 occurrences:
+   - Formulate a concrete rule (e.g., "Always read X before modifying Y — failed 4 times without this")
+   - Present to user: "Pattern found {N} times: {reasoning}. Proposed rule: '{rule}'. Add to CLAUDE.md? [y/n]"
+   - **Wait for user confirmation before writing** (Destructive Action Guard — CLAUDE.md changes require approval)
+   - If approved: append the rule to CLAUDE.md under the relevant section
+   - Write event: `node ~/.claude/scripts/gsd-t-event-writer.js --type distillation --command gsd-t-complete-milestone --reasoning "{rule}" --outcome success || true`
+
+5. If no patterns found (fewer than 3 occurrences): log "Distillation complete — no repeating patterns found", continue to Step 3
+
 ## Step 3: Gather Milestone Artifacts
 
 Collect all files related to this milestone:
@@ -168,7 +189,8 @@ None — ready for next milestone
 | {previous} | {version} | {date} | v{version} |
 
 ## Decision Log
-{Keep the decision log — it's valuable context}
+- {date}: [success] Milestone "{name}" completed — {summary of what was built}. v{version}
+{Keep all prior decision log entries — they are valuable context}
 ```
 
 ## Step 8: Update README.md

package/commands/gsd-t-debug.md

@@ -41,6 +41,107 @@ Read:
 3. `.gsd-t/contracts/` — all contracts
 4. `.gsd-t/domains/*/scope.md` — domain boundaries
 
+## Step 1.5: Debug Loop Detection (MANDATORY)
+
+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:**
+1. Scan `.gsd-t/progress.md` Decision Log for `[debug]` entries related to this issue (match by keyword, error name, or component)
+2. Count distinct debug sessions that attempted to fix this issue
+3. Check `.gsd-t/deferred-items.md` for any entries matching this issue
+
+**If 3 or more prior sessions found → Enter Deep Research Mode (below). Do NOT attempt another fix with the same approach.**
+
+**If fewer than 3 sessions → Proceed to Step 2 normally.**
+
+---
+
+### Deep Research Mode (triggered when debug loop detected)
+
+The current approach has failed 3+ times. This means the root cause is not yet understood. A different strategy — possibly a fundamentally different technical approach — is required.
+
+**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}`
+
+```
+Spawn a deep research team (run all three in parallel):
+
+- Teammate "researcher-root-cause": Take the broadest possible look at
+  the problem. Ignore prior fix attempts. Read the full component,
+  its dependencies, contracts, and all error traces from scratch.
+  What is the actual root cause — not the symptom? Consider that the
+  real issue may be architectural, not in the code being patched.
+
+- Teammate "researcher-alternatives": Enumerate 3–5 fundamentally
+  different ways to solve this problem. Include approaches that would
+  require refactoring or changing the technical direction entirely.
+  For each: what are the trade-offs, effort, and risk?
+
+- Teammate "researcher-prior-art": Search external sources, docs,
+  GitHub issues, and known patterns for this class of bug. Has this
+  problem been documented elsewhere? What did others find? Are there
+  framework-specific pitfalls or known workarounds?
+
+Lead: Wait for all three researchers to complete. Then synthesize:
+1. What is the true root cause based on full investigation?
+2. What are the viable solution paths (ranked by confidence)?
+3. Does any path require a different technical approach than what has been tried?
+4. What is the recommended path and why?
+```
+
+After team completes — 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`:
+`| {DT_START} | {DT_END} | gsd-t-debug | Step 1.5 | sonnet | {DURATION}s | deep research loop break: {issue summary} | {TOKENS} | {COMPACTED} |`
+
+**STOP. Present findings to the user before making any changes:**
+
+```
+## Debug Loop Break — Research Findings
+
+**Issue**: {issue summary}
+**Prior sessions**: {count} failed attempts
+
+**Root Cause (revised)**: {finding from researcher-root-cause}
+
+**Solution Options**:
+| # | Approach | Effort | Risk | Notes |
+|---|----------|--------|------|-------|
+| 1 | {option} | {effort} | {risk}  | {notes} |
+| 2 | {option} | {effort} | {risk}  | {notes} |
+| 3 | {option} | {effort} | {risk}  | {notes} |
+
+**Recommendation**: {recommended option and rationale}
+
+**Does this require a different technical direction?** {Yes/No — explain}
+
+Please select an option (or provide your own direction) before I proceed.
+```
+
+**Wait for explicit user selection/approval.** Do NOT proceed with any fix until the user confirms the chosen approach. If the recommendation requires refactoring or changing technical direction, the Destructive Action Guard applies — present the full migration path and wait for approval.
+
+---
+
+## Step 1.7: Experience Retrieval
+
+Before proceeding to classification and fix, retrieve relevant past failures from the Decision Log.
+
+Run via Bash:
+`grep -i "\[failure\]\|\[learning\]" .gsd-t/progress.md | tail -10`
+
+If results found:
+- Display a `## ⚠️ Relevant Past Failures` block showing matching entries (max 5 lines)
+- Pass this block as context to any debug subagent spawned in Step 3
+- Write event via Bash: `node ~/.claude/scripts/gsd-t-event-writer.js --type experience_retrieval --command gsd-t-debug --reasoning "{N entries found}" --outcome null || true`
+
+If no results found: proceed normally to Step 2.
+
+---
+
 ## Step 2: Classify the Bug
 
 Based on the user's description ($ARGUMENTS), determine:
@@ -102,7 +203,7 @@ When you encounter unexpected situations during the fix:
 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.
 
-**3-attempt limit**: If your fix doesn't work after 3 attempts, log to `.gsd-t/deferred-items.md` and stop trying.
+**3-attempt limit**: If your fix doesn't work after 3 attempts within this session, treat it as a loop. Do NOT keep trying the same approach. Log the attempt to `.gsd-t/progress.md` Decision Log with a `[failure]` prefix, then return to Step 1.5 and run Deep Research Mode before any further attempts. Present findings and options to the user before proceeding.
 
 ### Solo Mode
 1. Reproduce the issue — **reproduction script must exist before step 2** (see Step 2.5)
@@ -132,7 +233,11 @@ First to find root cause: message the lead with findings.
 After fixing, assess what documentation was affected by the change and update ALL relevant files:
 
 ### Always check:
-1. **`.gsd-t/progress.md`** — Add to Decision Log: what broke, why, and the fix
+1. **`.gsd-t/progress.md`** — Add to Decision Log: what broke, why, and the fix. Prefix the entry with an outcome tag:
+   - Debug session start → prefix `[debug]`
+   - Fix succeeded → prefix `[success]`
+   - Fix failed → prefix `[failure]`
+   - Issue deferred → prefix `[deferred]`
 2. **`.gsd-t/contracts/`** — Update any contract if the fix changed an interface, schema, or API shape
 3. **Domain `constraints.md`** — Add a "must not" rule if the bug was caused by a pattern that should be avoided
 

package/commands/gsd-t-execute.md

@@ -70,6 +70,16 @@ Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime
 
 **For each domain (in wave order), spawn:**
 
+**Pre-task experience retrieval (before spawning each domain subagent):**
+Run via Bash:
+`grep -i "\[failure\]\|\[learning\]" .gsd-t/progress.md | grep -i "{domain-name}" | tail -5`
+
+If results found:
+- Prepend a `## ⚠️ Past Failures (retrieve before acting)` block to the subagent prompt (max 5 lines from results)
+- Write event via Bash: `node ~/.claude/scripts/gsd-t-event-writer.js --type experience_retrieval --command gsd-t-execute --reasoning "{N past failures found for {domain-name}}" --outcome null || true`
+
+If no results found: proceed normally (no warning block, no event write).
+
 ```
 Task subagent (general-purpose, model: sonnet, mode: bypassPermissions):
 "You are executing all tasks for the {domain-name} domain.
@@ -98,7 +108,11 @@ Execute each incomplete task in order:
 7. Run ALL tests — unit, integration, Playwright. Fix failures (up to 2 attempts)
 8. Run Pre-Commit Gate checklist from CLAUDE.md — update all affected docs BEFORE committing
 9. Commit immediately: feat({domain-name}/task-{N}): {description}
-10. Update .gsd-t/progress.md — mark task complete
+10. Update .gsd-t/progress.md — mark task complete; prefix the Decision Log entry with an outcome tag based on how the task completed:
+    - Task completed successfully on first attempt → prefix `[success]`
+    - Task completed after a fix (required debugging or correction) → prefix `[learning]`
+    - Task deferred to .gsd-t/deferred-items.md → prefix `[deferred]`
+    - Task failed after 3 attempts → prefix `[failure]`
 11. Spawn QA subagent (model: haiku) after each task:
     'Run the full test suite. Read .gsd-t/contracts/ for definitions.
      Report: pass/fail counts and coverage gaps.'

package/commands/gsd-t-help.md

@@ -51,6 +51,8 @@ UTILITIES                                                              Manual
   status              Cross-domain progress view
   resume              Restore context after break
   quick               Fast task with GSD-T guarantees
+  reflect             Generate retrospective from event stream, propose memory updates
+  visualize           Launch browser dashboard (SSE server + React Flow)
   debug               Systematic debugging with state
   health              Validate .gsd-t/ structure, optionally repair missing files
   pause               Save exact position for reliable resume later
@@ -299,6 +301,20 @@ Use these when user asks for help on a specific command:
 - **Creates**: Quick task record
 - **Use when**: Small tasks that don't need full planning
 
+### reflect
+- **Summary**: Generate a structured retrospective from the event stream for the current milestone, then propose CLAUDE.md/constraints.md rule additions based on recurring patterns
+- **Auto-invoked**: No
+- **Reads**: `.gsd-t/events/*.jsonl`, `.gsd-t/progress.md`, `CLAUDE.md`
+- **Creates**: `.gsd-t/retrospectives/YYYY-MM-DD-{milestone}.md`
+- **Use when**: After completing a milestone or mid-milestone to surface what's working, what's failing, and what patterns should become permanent rules
+
+### visualize
+- **Summary**: Launch the real-time agent dashboard — starts the SSE server (if not running) and opens the React Flow visualization in a browser
+- **Auto-invoked**: No
+- **Reads**: `.gsd-t/dashboard.pid`, `.gsd-t/events/*.jsonl` (via server)
+- **Creates**: `.gsd-t/dashboard.pid` (when starting server)
+- **Use when**: Monitoring live agent activity during execute/wave phases; run `gsd-t-visualize stop` to stop the server
+
 ### debug
 - **Summary**: Systematic debugging with persistent state
 - **Auto-invoked**: No

package/commands/gsd-t-init.md

@@ -54,6 +54,7 @@ Skip the copy (step 2) silently if the target already exists.
 │   └── .gitkeep
 ├── domains/
 │   └── .gitkeep
+├── events/
 ├── backlog.md
 ├── backlog-settings.md
 ├── progress.md
@@ -61,6 +62,8 @@ Skip the copy (step 2) silently if the target already exists.
 └── qa-issues.md
 ```
 
+Create `.gsd-t/events/` directory (empty — populated at runtime by heartbeat and event writer).
+
 Create `token-log.md` with header row:
 ```
 | Date | Command | Step | Model | Duration(s) | Notes |

package/commands/gsd-t-reflect.md

@@ -0,0 +1,134 @@
+# GSD-T: Reflect — Generate Retrospective from Event Stream
+
+You are generating a structured retrospective for the current (or specified) milestone by reading the JSONL event stream and proposing memory updates.
+
+## Step 0: Launch via Subagent
+
+When invoked directly by the user, spawn yourself as a Task subagent for a fresh context window.
+
+**OBSERVABILITY LOGGING — 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}`
+
+```
+Task subagent (general-purpose, model: sonnet):
+"Run the GSD-T reflect command. Read commands/gsd-t-reflect.md for your full instructions.
+Arguments: {$ARGUMENTS}
+Skip Step 0 — you are already the subagent."
+```
+
+**OBSERVABILITY LOGGING — 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:
+- 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-reflect | Step 0 | sonnet | {DURATION}s | retrospective generated | {TOKENS} | {COMPACTED} |`
+
+Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
+
+## Step 1: Load State
+
+Read:
+1. `CLAUDE.md` — project context
+2. `.gsd-t/progress.md` — current milestone name and start date
+3. `.gsd-t/contracts/event-schema-contract.md` — event fields available for reading
+
+Identify the current milestone name and its start date from the `## Current Milestone` table in `progress.md`.
+
+If `$ARGUMENTS` is provided, treat it as a milestone name filter — search for a past milestone matching that name in the `## Completed Milestones` table and use its completion date as the date boundary instead.
+
+## Step 2: Find Events
+
+Look for `.gsd-t/events/*.jsonl` files.
+
+If no `.gsd-t/events/` directory or no `.jsonl` files exist:
+```
+No events recorded for this milestone yet.
+Events are written during execute/wave/debug phases once the event-writer is installed.
+```
+Stop and exit.
+
+Filter events by milestone period: include only JSONL lines with `"ts"` values on or after the milestone start date (from Step 1). Read all matching `.jsonl` files and collect the event objects.
+
+## Step 3: Generate Retrospective
+
+Parse the collected events and categorize:
+
+**By outcome:**
+- `success` events — commands/phases that completed successfully
+- `failure` events — commands/phases that failed (capture `reasoning` field)
+- `learning` events — insights captured during execution (capture `reasoning`)
+- `deferred` events — items postponed (capture `reasoning`)
+
+**Command patterns:**
+- Which `command` values appear most in failure events
+- Which `phase` values appear most in failure events
+
+**Repeating patterns (threshold ≥ 2):**
+- Group events by `reasoning` field value (exact string match)
+- Identify any `reasoning` string that appears in 2 or more events
+
+**Summary:**
+- What worked: `command`/`phase` values that have only `success` outcomes
+- What failed: failure events with their `reasoning` and `command`
+- What was learned: `learning` outcome events and their `reasoning`
+
+## Step 4: Write Retrospective File
+
+Create `.gsd-t/retrospectives/` directory if it does not exist.
+
+Determine the output filename:
+- Current milestone: `{YYYY-MM-DD}-{milestone-name-kebab-case}.md` (today's date)
+- Past milestone (from $ARGUMENTS): use that milestone's completion date
+
+Write the retrospective file:
+
+```markdown
+# Retrospective: {Milestone Name}
+**Generated**: {YYYY-MM-DD}
+**Milestone period**: {start date} → {end date}
+**Events analyzed**: {N}
+
+## What Worked
+{List each command/phase that had only success outcomes — one per line}
+{If none: _No commands with exclusively success outcomes recorded._}
+
+## What Failed
+{For each failure event: `- [{command}] {reasoning}`}
+{If none: _No failure events recorded._}
+
+## Patterns Found
+{For each reasoning string with ≥ 2 occurrences: `- ({N}×) {reasoning}`}
+{If none: _No repeating patterns found (threshold: 2 occurrences)._}
+
+## Proposed Memory Updates
+{For each pattern found: suggest a concrete rule}
+{Format: `- Pattern ({N}×): "{reasoning}" → Rule: "Always/Never {concrete action}"`}
+{If none: _No patterns met the threshold for a proposed rule._}
+```
+
+## Step 5: Present Proposed Memory Updates
+
+For each item in the **Proposed Memory Updates** section:
+
+1. Present to user: `"Proposed rule (seen {N} times): '{rule}'. Add to CLAUDE.md? [y/n]"`
+2. **Wait for user confirmation before writing** (Destructive Action Guard — CLAUDE.md changes require explicit approval)
+3. If approved: append the rule to `CLAUDE.md` under the relevant section
+4. If none to propose: report "No repeating patterns found — no memory updates proposed."
+
+## Document Ripple
+
+Update `.gsd-t/progress.md` Decision Log:
+- Add entry: `- {YYYY-MM-DD HH:MM}: [learning] gsd-t-reflect run — retrospective written to .gsd-t/retrospectives/{filename}.md; {N} events analyzed, {N} patterns found, {N} rules proposed`
+
+$ARGUMENTS
+
+## Auto-Clear
+
+All work is committed to project files. Execute `/clear` to free the context window for the next command.

package/commands/gsd-t-visualize.md

@@ -0,0 +1,104 @@
+# GSD-T: Visualize — Launch Real-Time Agent Dashboard
+
+You are launching the GSD-T real-time agent dashboard — an SSE-backed browser visualization of agent activity.
+
+## Step 0: Launch via Subagent
+
+When invoked directly by the user, spawn yourself as a Task subagent for a fresh context window.
+
+**OBSERVABILITY LOGGING — 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}`
+
+```
+Task subagent (general-purpose, model: sonnet):
+"Run the GSD-T visualize command. Read commands/gsd-t-visualize.md for your full instructions.
+Arguments: {$ARGUMENTS}
+Skip Step 0 — you are already the subagent."
+```
+
+**OBSERVABILITY LOGGING — 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:
+- 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-visualize | Step 0 | sonnet | {DURATION}s | dashboard launched | {TOKENS} | {COMPACTED} |`
+
+Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
+
+## Step 1: Write command_invoked Event
+
+Run via Bash:
+```bash
+node ~/.claude/scripts/gsd-t-event-writer.js --type command_invoked --command gsd-t-visualize --reasoning "Launching dashboard" || true
+```
+
+## Step 2: Check $ARGUMENTS for "stop"
+
+If `$ARGUMENTS` contains "stop", skip to **Step 5**. Otherwise continue to Step 3.
+
+## Step 3: Check if Server is Already Running
+
+Run via Bash:
+```bash
+if [ -f .gsd-t/dashboard.pid ]; then
+  PID=$(cat .gsd-t/dashboard.pid)
+  curl -sf http://localhost:7433/ping 2>/dev/null | grep -q '"ok"' && echo "SERVER_RUNNING=true" || echo "SERVER_RUNNING=false"
+else
+  echo "SERVER_RUNNING=false"
+fi
+```
+
+If output is `SERVER_RUNNING=true`, skip Step 3a and go directly to Step 4.
+
+### Step 3a: Start Server if Not Running
+
+Run via Bash:
+```bash
+node ~/.claude/scripts/gsd-t-dashboard-server.js --detach || true
+for i in 1 2 3 4 5; do
+  curl -sf http://localhost:7433/ping 2>/dev/null | grep -q '"ok"' && break
+  sleep 1
+done
+```
+
+## Step 4: Open Browser
+
+Run via Bash:
+```bash
+node -e "const {execFileSync}=require('child_process'); const url='http://localhost:7433'; try { if(process.platform==='win32'){execFileSync('cmd',['/c','start','',url],{stdio:'ignore'})}else{execFileSync(process.platform==='darwin'?'open':'xdg-open',[url],{stdio:'ignore'})} } catch(e) { console.error('Could not open browser:', e.message); }" || true
+```
+
+Report to the user: "Dashboard is running at http://localhost:7433 — browser opened."
+
+## Step 5: Stop Handler
+
+Run only when `$ARGUMENTS` contains "stop".
+
+Run via Bash:
+```bash
+if [ -f .gsd-t/dashboard.pid ]; then
+  PID=$(cat .gsd-t/dashboard.pid)
+  curl -sf http://localhost:7433/stop 2>/dev/null || kill $PID 2>/dev/null || true
+  rm -f .gsd-t/dashboard.pid
+  echo "Dashboard server stopped"
+else
+  echo "No dashboard server running (no .gsd-t/dashboard.pid found)"
+fi
+```
+
+## Document Ripple
+
+Note: All 4 reference files (README.md, docs/GSD-T-README.md, templates/CLAUDE-global.md, commands/gsd-t-help.md) are updated in Task 3 of Milestone 15, not here.
+
+$ARGUMENTS
+
+## Auto-Clear
+
+All work is committed to project files. Execute `/clear` to free the context window for the next command.

package/commands/gsd-t-wave.md

@@ -142,7 +142,27 @@ After each agent completes, run this spot-check before proceeding:
    ✅ {Phase} complete — {agent's one-line summary}
    📋 Spot-check: {N} commits | {N} output files verified | no FAILED markers
    ```
-5. If spot-check fails: report the discrepancy, re-spawn the phase agent once to correct it, then re-verify. If still failing: stop and report to user.
+5. If spot-check fails: write failure event via Bash, then report the discrepancy, re-spawn the phase agent once to correct it, then re-verify. If still failing: stop and report to user.
+   ```bash
+   node ~/.claude/scripts/gsd-t-event-writer.js \
+     --type phase_transition \
+     --command gsd-t-wave \
+     --phase {COMPLETED_PHASE} \
+     --reasoning "Spot-check failed: {one-line discrepancy summary}" \
+     --outcome failure \
+     --agent-id "${CLAUDE_SESSION_ID:-unknown}" || true
+   ```
+5a. After spot-check passes, write success event via Bash:
+   ```bash
+   node ~/.claude/scripts/gsd-t-event-writer.js \
+     --type phase_transition \
+     --command gsd-t-wave \
+     --phase {COMPLETED_PHASE} \
+     --reasoning "Phase complete: {one-line spot-check summary}" \
+     --outcome success \
+     --agent-id "${CLAUDE_SESSION_ID:-unknown}" || true
+   ```
+   The `|| true` ensures event write failure never blocks wave execution.
 6. Proceed to next phase
 
 ## Step 4: Autonomy Behavior