@tekyzinc/gsd-t 2.31.17 → 2.33.11

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.33.11] - 2026-03-05
+
+### Added
+- `.gitignore` excludes `.claude/worktrees/` (Claude Code internal) and `nul` (Windows artifact)
+- `ai-evals-analysis.md`, `gsd-t-command-doc-matrix.csv` — development reference documents
+- `scripts/gsd-t-dashboard-mockup.html` — interactive mockup from M15 brainstorm (historical reference)
+- `.gsd-t/brainstorm-2026-02-18.md` — brainstorm notes from Feb 18 ideation session
+
+## [2.33.10] - 2026-03-04
+
+### Added
+- **Milestone 15: Real-Time Agent Dashboard** — Zero-dependency live browser dashboard for GSD-T execution:
+  - **`scripts/gsd-t-dashboard-server.js`** (141 lines): Node.js HTTP+SSE server (zero external deps). Watches `.gsd-t/events/*.jsonl`, streams up to 500 existing events on connect, tails for new events, keepalive every 15s. Runs detached with PID file. All functions exported for testability (23 unit tests in `test/dashboard-server.test.js`).
+  - **`scripts/gsd-t-dashboard.html`** (194 lines): Browser dashboard using React 17 + React Flow v11.11.4 + Dagre via CDN (no build step, no npm deps). Dark theme. Renders agent hierarchy as directed graph from `parent_agent_id` relationships. Live event feed (max 200 events, outcome color-coded: green=success, red=failure, yellow=learning). Auto-reconnects on disconnect.
+  - **`commands/gsd-t-visualize`**: 48th GSD-T command. Starts server via `--detach`, polls `/ping` up to 5s, opens browser cross-platform (win32/darwin/linux). Accepts `stop` argument. Includes Step 0 self-spawn with OBSERVABILITY LOGGING.
+  - Both `gsd-t-dashboard-server.js` and `gsd-t-dashboard.html` automatically installed to `~/.claude/scripts/` during `npx @tekyzinc/gsd-t install/update`
+  - 23 new tests in `test/dashboard-server.test.js` — total: 176/176 passing
+
+### Changed
+- Total command count: 47 → **48** (44 GSD-T workflow + 4 utility)
+
+## [2.32.10] - 2026-03-04
+
+### Added
+- **Milestone 14: Execution Intelligence Layer** — Structured observability, learning, and reflection:
+  - **`scripts/gsd-t-event-writer.js`**: New zero-dependency CLI + module.exports. Writes structured JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl`. Validates 8 event_type values and 5 outcome values. Symlink-safe. Resolves events dir from `GSD_T_PROJECT_DIR` or cwd. 26 new tests.
+  - **Heartbeat enrichment**: `scripts/gsd-t-heartbeat.js` maps `SubagentStart`/`SubagentStop`/`PostToolUse` hook events to the events/ schema, appending them to daily JSONL files alongside existing heartbeat writes.
+  - **Outcome-tagged Decision Log**: `execute`, `debug`, and `wave` now prefix all new Decision Log entries with `[success]`, `[failure]`, `[learning]`, or `[deferred]`.
+  - **Pre-task experience retrieval (Reflexion pattern)**: `execute` and `debug` grep the Decision Log for `[failure]`/`[learning]` entries matching the current domain before spawning subagents. Relevant past failures prepended as `⚠️ Past Failures` block in subagent prompt.
+  - **Phase transition events**: `wave` writes `phase_transition` event with outcome:success/failure at each phase boundary.
+  - **Distillation step** (Step 2.5 in `complete-milestone`): Scans event stream for patterns seen ≥3 times, proposes CLAUDE.md / constraints.md rule additions, requires user confirmation before any write.
+  - **`commands/gsd-t-reflect`** (134 lines, 47th command): On-demand retrospective from event stream. Generates `.gsd-t/retrospectives/YYYY-MM-DD-{milestone}.md` with What Worked / What Failed / Patterns Found / Proposed Memory Updates. Includes Step 0 self-spawn with OBSERVABILITY LOGGING.
+  - `gsd-t-event-writer.js` installed to `~/.claude/scripts/` during install/update
+
+### Changed
+- Total command count: 46 → **47** (43 GSD-T workflow + 4 utility)
+
 ## [2.28.10] - 2026-02-18
 
 ### Added

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

@@ -17,6 +17,30 @@ If status is not VERIFIED:
 
 If `--force` flag provided, proceed with warning in archive.
 
+## Step 1.5: Smoke Test Artifact Gate (MANDATORY — Categories 2 and 7)
+
+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:**
+- Audio capture/playback, speech recognition/synthesis
+- GPU/WebGPU/WebGL compute or rendering
+- ML inference, model loading, quantized model execution
+- Background workers, service workers, IPC channels
+- Native APIs (camera, bluetooth, filesystem, microphone)
+- WebAssembly modules
+- Any feature whose only prior "test" was manual user interaction
+
+**For each high-risk feature found:**
+
+1. Check that a smoke test script exists (in `scripts/`, `tests/`, or `.gsd-t/smoke-tests/`)
+2. Check that the script was run and passed (evidence in token-log.md, CI output, or a `.gsd-t/smoke-tests/{feature}.md` file with run results)
+3. If manual steps remain unavoidable: `.gsd-t/smoke-tests/{feature}.md` must exist documenting exact steps and confirming they passed
+
+**If any high-risk feature lacks a smoke test artifact → BLOCK completion.**
+Do not proceed to archiving. Create the smoke test now, run it, confirm it passes, then continue.
+
+> This gate exists because complete-milestone is the last opportunity to catch "shipped blind" features before they become user-facing bugs requiring 15 debug sessions to resolve.
+
 ## Step 2: Gap Analysis Gate
 
 After verification passes, run a gap analysis against `docs/requirements.md` scoped to this milestone's deliverables:
@@ -33,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:
@@ -144,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:
@@ -71,6 +172,27 @@ The contract didn't specify something it should have. Symptoms:
 
 → Update the contract, then fix implementations on both sides.
 
+## Step 2.5: Reproduce First (MANDATORY — Category 5)
+
+**A fix attempt without a reproduction script is a guess, not a fix.**
+
+Before touching any code:
+
+1. **Write a reproduction script** that demonstrates the bug. Automate as much as possible:
+   - Unit/integration bug → write a failing test that proves the bug exists
+   - UI/audio/GPU/worker bug (not fully automatable) → write the closest possible script: a headless probe, a log-based trigger, a mock that replicates the failure path. Document the manual remainder explicitly.
+   - If you cannot write any form of reproduction → you do not yet understand the bug. Keep investigating until you can.
+
+2. **Run the reproduction** and confirm it fails before attempting any fix.
+
+3. **Never close a debug session with "ready for testing."** A session closes only when the reproduction script passes. If manual steps remain, document them explicitly and confirm they passed.
+
+4. **Log the reproduction script path** in `.gsd-t/progress.md` Decision Log: what it tests, how to run it, what passing looks like.
+
+> This rule exists because code review cannot detect silent runtime failures (GPU compute shaders, audio context state, worker message drops). Only execution proves correctness.
+
+---
+
 ## Step 3: Debug (Solo or Team)
 
 ### Deviation Rules
@@ -81,16 +203,17 @@ 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
+1. Reproduce the issue — **reproduction script must exist before step 2** (see Step 2.5)
 2. Trace through the relevant domain(s)
 3. Check contract compliance at each boundary
 4. Identify root cause
 5. **Destructive Action Guard**: If the fix requires destructive or structural changes (dropping tables, removing columns, changing schema, replacing architecture patterns, removing working modules) → STOP and present the change to the user with what exists, what will change, what will break, and a safe migration path. Wait for explicit approval.
 6. Fix and test — **adapt the fix to existing structures**, not the other way around
 7. Update contracts if needed
+8. **Category 6 — Bug Isolation Check**: After applying the fix, run the FULL test suite and all smoke tests — not just the reproduction script. Do not assume the bug was isolated. A fix that resolves one failure frequently uncovers adjacent failures. Every test must pass before the session closes.
 
 ### Team Mode (for complex cross-domain bugs)
 ```
@@ -110,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-partition.md

@@ -17,6 +17,63 @@ If `.gsd-t/` doesn't exist, create the full directory structure:
 └── progress.md
 ```
 
+## Step 1.5: Assumption Audit (MANDATORY — complete before domain work begins)
+
+Before partitioning, surface and lock down all assumptions baked into the requirements. Unexamined assumptions become architectural decisions no one approved.
+
+Work through each category below. For every match found, write the explicit disposition into the affected domain's `constraints.md` and into the Decision Log in `.gsd-t/progress.md`.
+
+---
+
+### Category 1: External Reference Assumptions
+
+Scan requirements for any external project, file, component, library, or URL mentioned by name or path. For each one found, explicitly confirm which disposition applies — and lock it in the contract before any domain touches it:
+
+| Disposition | Meaning |
+|-------------|---------|
+| `USE`       |  Import and depend on it — treat as a dependency |
+| `INSPECT`   |  Read source for patterns only — do not import or copy code |
+| `BUILD`     |  Build equivalent functionality from scratch — do not read or use it |
+
+**No external reference survives partition without a locked disposition.**
+
+Trigger phrases to watch for: "reference X", "like X", "similar to Y", "see W for how it handles Z", any file path or project name, any URL.
+
+> If Level 3 (Full Auto): state the inferred disposition and reason; lock it unless it's ambiguous.
+> If ambiguous (e.g., "reference X" could mean USE or INSPECT): pause and ask the user before proceeding.
+
+---
+
+### Category 3: Black Box Assumptions
+
+Any component, module, or library **not written in this milestone** that a domain will call, import, or depend on → the agent that executes that domain must read its source before treating it as correct. This includes internal project modules written in a previous milestone.
+
+For each such component identified:
+1. Name it explicitly in the domain's `constraints.md` under a `## Must Read Before Using` section
+2. List the specific functions or behaviors the domain depends on
+3. The execute agent is prohibited from treating it as a black box — it must read the listed items before implementing
+
+---
+
+### Category 4: User Intent Assumptions
+
+Scan requirements for ambiguous language. Flag every instance where intent could be interpreted more than one way. Common patterns:
+
+- "like X" / "similar to Y" — does this mean the same UX, the same architecture, or just the same concept?
+- "the way X handles it" — inspiration, direct port, or behavioral equivalent?
+- "reference Z" — does this mean read it, use it, or replicate it?
+- "build something that does W" — from scratch, or using an existing library?
+- Any requirement where a reasonable developer could make two different implementation choices
+
+For each ambiguous item:
+1. State the two (or more) possible interpretations explicitly
+2. State which interpretation you are locking in and why
+3. If genuinely unclear: pause and ask the user — do not infer and proceed
+
+> **Rule**: Ambiguous intent that reaches execute unresolved becomes a wrong assumption. Resolve it here or pay for it in debug sessions.
+
+---
+
 ## Step 2: Identify Domains
 
 Decompose the milestone into 2-5 independent domains. Each domain should: