@tekyzinc/gsd-t 2.22.0 → 2.24.6

package/commands/gsd-t-qa.md

@@ -9,6 +9,23 @@ You are the QA Agent. You are spawned as a teammate by other GSD-T commands. You
 - **What you don't do**: Write feature code, modify contracts, change architecture
 - **Context**: You receive contracts from `.gsd-t/contracts/` and the current phase context
 
+## File-Path Boundaries
+
+### You CAN modify:
+- Project test directories (e.g., `test/`, `tests/`, `__tests__/`, `e2e/`, `spec/`)
+- Test configuration files (e.g., `playwright.config.*`, `jest.config.*`, `vitest.config.*`)
+- `.gsd-t/test-coverage.md` — coverage reports
+
+### You MUST NOT modify:
+- Source code files (e.g., `src/`, `lib/`, `bin/`, `scripts/`)
+- Contract files (`.gsd-t/contracts/`)
+- Documentation files (`docs/`, `README.md`, `CLAUDE.md`)
+- Command files (`commands/`)
+- Template files (`templates/`)
+- Configuration files outside test config (`.gsd-t/progress.md`, `package.json`, etc.)
+
+If a test requires a source code change (e.g., adding an export for testability), message the lead — do not make the change yourself.
+
 ## Phase-Specific Behavior
 
 Your behavior depends on which phase spawned you:
@@ -42,6 +59,17 @@ Your behavior depends on which phase spawned you:
 5. Report per-task: `QA: Task {N} — {pass|fail}. {details}`
 6. Final report: `QA: {pass|fail} — {N}/{N} contract tests passing, {N} edge case tests added`
 
+### During Test-Sync
+**Trigger**: Lead runs test-sync phase
+**Action**: Validate test-to-contract alignment and fill gaps
+
+1. Read all contracts in `.gsd-t/contracts/`
+2. Compare contract definitions against existing test files — identify any contracts without tests
+3. For each contract change since last test-sync, verify tests match the updated contract shape
+4. Write missing contract tests for any gaps found
+5. Run all contract tests to verify they pass against current implementation
+6. Report: `QA: Test-sync — {pass|fail}. {N} contract tests aligned, {N} gaps filled, {N} stale tests updated`
+
 ### During Verify
 **Trigger**: Lead invokes verify phase
 **Action**: Full test audit
@@ -90,6 +118,27 @@ Your behavior depends on which phase spawned you:
 4. This is pass/fail with no remediation — just report
 5. Report: `QA: Final gate — {PASS|FAIL}. {N} total tests, {N} passing, {N} failing. {blocking issues if any}`
 
+## Framework Detection
+
+Before generating any tests, detect the project's test framework:
+
+1. **Check for existing test config**: `playwright.config.*`, `jest.config.*`, `vitest.config.*`, `mocha` in package.json, `pytest.ini`, `pyproject.toml`
+2. **Check package.json dependencies**: `@playwright/test`, `jest`, `vitest`, `mocha`, `node:test`
+3. **Check existing test files**: What import style do they use?
+4. **Check for Python**: `requirements.txt`, `pyproject.toml` with `pytest`
+
+### Framework-Specific Test Generation
+
+| Framework | Import Style | Test Block | Assertion |
+|-----------|-------------|------------|-----------|
+| **Playwright** | `import { test, expect } from '@playwright/test'` | `test.describe` / `test` | `expect(x).toBe(y)` |
+| **Jest** | `const { describe, it, expect } = require(...)` or ES import | `describe` / `it` | `expect(x).toBe(y)` |
+| **Vitest** | `import { describe, it, expect } from 'vitest'` | `describe` / `it` | `expect(x).toBe(y)` |
+| **Node.js built-in** | `const { describe, it } = require('node:test')` | `describe` / `it` | `assert.equal(x, y)` |
+| **Pytest** | `import pytest` | `def test_` / `class Test` | `assert x == y` |
+
+**Always match the project's existing test framework.** Do not introduce a new framework unless the project has none. If no framework exists, default to the project's language ecosystem standard (Node.js: `node:test`, Python: `pytest`).
+
 ## Contract → Test Mapping Rules
 
 ### API Contract → Tests
@@ -166,4 +215,18 @@ QA: {PASS|FAIL} — {one-line summary}
 
 After tests complete (pass or fail), kill any app/server processes spawned during test runs. Do not leave orphaned dev servers.
 
+## Document Ripple
+
+After generating or updating tests, check if documentation needs updating:
+
+### Always update:
+1. **`.gsd-t/test-coverage.md`** — Update coverage status for any contracts or code paths you tested
+
+### Check if affected:
+2. **`docs/requirements.md`** — If new test files were created for a requirement, add the test file path to the requirement's test mapping
+3. **Domain `scope.md`** — If new test files were created, verify the test directory is listed in the domain's owned files
+4. **`.gsd-t/techdebt.md`** — If test generation revealed untestable code or missing exports, add as debt items
+
+### Skip what's not affected.
+
 $ARGUMENTS

package/commands/gsd-t-quick.md

@@ -24,7 +24,7 @@ Should I proceed with quick mode or use the full execute workflow?"
 ### If it's within a single domain or pre-partition:
 Proceed.
 
-## Step 2.5: Spawn QA Agent
+## Step 3: Spawn QA Agent
 
 Spawn the QA teammate to handle testing for this quick task:
 
@@ -37,7 +37,7 @@ Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
 
 QA failure blocks the commit.
 
-## Step 3: Execute
+## Step 4: Execute
 
 1. Identify exactly which files need to change
 2. **Destructive Action Guard**: Check if this task involves destructive or structural changes (DROP TABLE, removing columns, deleting data, replacing architecture patterns, removing working modules, changing schema in ways that conflict with existing data). If YES → STOP and present the change to the user with what exists today, what will change, what will break, and a safe migration path. Wait for explicit approval.
@@ -46,7 +46,7 @@ QA failure blocks the commit.
 5. Verify it works
 6. Commit: `[quick] {description}`
 
-## Step 4: Document Ripple (if GSD-T is active)
+## Step 5: Document Ripple (if GSD-T is active)
 
 If `.gsd-t/progress.md` exists, assess what documentation was affected and update ALL relevant files:
 
@@ -65,7 +65,7 @@ If `.gsd-t/progress.md` exists, assess what documentation was affected and updat
 
 ### Skip what's not affected — most quick tasks will only touch 1-2 of these.
 
-## Step 5: Test & Verify (MANDATORY)
+## Step 6: Test & Verify (MANDATORY)
 
 Quick does not mean skip testing. Before committing:
 

package/commands/gsd-t-scan.md

@@ -365,7 +365,7 @@ If `README.md` exists, merge — update tech stack and setup sections but preser
 - If the file doesn't exist, **create** it
 - Replace `{Project Name}` and `{Date}` tokens with actual values
 
-## Step 5.5: Test Verification
+## Step 6: Test Verification
 
 After updating living documents, verify nothing was broken:
 
@@ -373,7 +373,7 @@ After updating living documents, verify nothing was broken:
 2. **Verify passing**: If any tests fail that were passing before the scan began, investigate and fix
 3. **Log test baseline**: Record the current test state in `.gsd-t/scan/test-baseline.md` — this gives future milestones a starting point
 
-## Step 6: Update Project State
+## Step 7: Update Project State
 
 If `.gsd-t/progress.md` exists:
 - Log scan in Decision Log
@@ -386,7 +386,7 @@ If `.gsd-t/roadmap.md` exists:
 If `CLAUDE.md` exists:
 - Suggest updates for any patterns or conventions discovered during scan
 
-## Step 7: Report to User
+## Step 8: Report to User
 
 Present a summary:
 1. Architecture overview (brief)

package/commands/gsd-t-test-sync.md

@@ -21,7 +21,7 @@ Identify:
 - Naming conventions
 - Test run commands (from package.json scripts, Makefile, or CI config)
 
-## Step 1.5: Spawn QA Agent
+## Step 2: Spawn QA Agent
 
 Spawn the QA teammate to assist with test coverage analysis:
 
@@ -32,9 +32,9 @@ Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
   Report: coverage gaps, stale tests, and recommended test tasks.
 ```
 
-QA agent works alongside the test sync process. QA failure flags are included in the coverage report.
+QA agent works alongside the test sync process. QA failure blocks test-sync completion.
 
-## Step 2: Map Code to Tests
+## Step 3: Map Code to Tests
 
 For each file changed in recent tasks:
 
@@ -56,7 +56,7 @@ find . -name "*.spec.*" | xargs grep -l "{class_name}"
 | src/api/users.py | tests/test_users.py | PARTIAL |
 ```
 
-## Step 3: Detect Test Issues
+## Step 4: Detect Test Issues
 
 ### A) Stale Tests
 Tests that reference old behavior:
@@ -90,7 +90,7 @@ Tests that sometimes fail:
 - Check recent CI runs
 - Note any intermittent failures
 
-## Step 4: Run Affected Tests
+## Step 5: Run Affected Tests
 
 ### A) Unit/Integration Tests
 Execute tests that cover changed code:
@@ -149,7 +149,7 @@ For all test types:
 - FAIL: Test needs update or code has bug
 - ERROR: Test broken (import error, etc.)
 
-## Step 5: Produce Test Coverage Report
+## Step 6: Produce Test Coverage Report
 
 Create/update `.gsd-t/test-coverage.md`:
 
@@ -236,7 +236,7 @@ Create/update `.gsd-t/test-coverage.md`:
 {Based on findings, what should be prioritized}
 ```
 
-## Step 6: Generate Test Tasks
+## Step 7: Generate Test Tasks
 
 If issues found, add to current domain's tasks:
 
@@ -259,7 +259,7 @@ If issues found, add to current domain's tasks:
   - Action: Update all user fixtures
 ```
 
-## Step 7: Integration with Workflow
+## Step 8: Integration with Workflow
 
 ### During Execute Phase (auto-invoked):
 After each task completes:
@@ -289,7 +289,7 @@ Full sync:
 3. Generate all test tasks
 4. Do not auto-add to domains — present for review
 
-## Step 8: Report to User
+## Step 9: Report to User
 
 ### Quick Mode (during execute):
 ```

package/commands/gsd-t-verify.md

@@ -12,7 +12,7 @@ Read:
 5. `docs/requirements.md` — original requirements
 6. All source code
 
-## Step 1.5: Spawn QA Agent
+## Step 2: Spawn QA Agent
 
 Spawn the QA teammate to run the full test audit:
 
@@ -25,7 +25,7 @@ Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
 
 QA failure blocks verification completion.
 
-## Step 2: Define Verification Dimensions
+## Step 3: Define Verification Dimensions
 
 Standard dimensions (adjust based on project):
 
@@ -41,7 +41,7 @@ Standard dimensions (adjust based on project):
 6. **Security**: Auth flows, input validation, data exposure, dependencies
 7. **Integration Integrity**: Do the seams between domains hold under stress?
 
-## Step 3: Execute Verification
+## Step 4: Execute Verification
 
 ### Solo Mode (default)
 Work through each dimension sequentially. For each:
@@ -109,7 +109,7 @@ Teammate assignments:
 Lead: Collect all reports (including QA), synthesize, create remediation plan.
 ```
 
-## Step 4: Compile Verification Report
+## Step 5: Compile Verification Report
 
 Create or update `.gsd-t/verify-report.md`:
 
@@ -147,7 +147,7 @@ Create or update `.gsd-t/verify-report.md`:
 | 2 | ui | Add loading states for async calls | WARN |
 ```
 
-## Step 5: Handle Remediation
+## Step 6: Handle Remediation
 
 If there are CRITICAL findings:
 1. Create remediation tasks in the affected domain's `tasks.md`
@@ -155,7 +155,7 @@ If there are CRITICAL findings:
 3. Re-verify the specific findings
 4. Update the verification report
 
-## Step 6: Update State
+## Step 7: Update State
 
 Update `.gsd-t/progress.md`:
 - If all PASS: Set status to `VERIFIED`

package/commands/gsd-t-wave.md

@@ -1,125 +1,145 @@
-# GSD-T: Wave — Full Cycle Orchestration
+# GSD-T: Wave — Full Cycle Orchestration (Agent-Per-Phase)
 
-You are running a complete GSD-T cycle through all phases for the current milestone. This is the "just go" command — it runs partition → discuss → plan → impact → execute → test-sync → integrate → verify → complete-milestone in sequence, using teams where beneficial.
+You are the wave orchestrator. You do NOT execute phases yourself. Instead, you spawn an **independent agent for each phase**, giving each a fresh context window. This eliminates context accumulation across phases and prevents mid-wave compaction.
 
-## Step 1: Load State
+## Step 1: Load State (Lightweight)
 
-Read:
-1. `CLAUDE.md`
-2. `.gsd-t/progress.md`
-3. All `.gsd-t/` files
+Read ONLY:
+1. `.gsd-t/progress.md` — current status, milestone name, phase state
+2. `CLAUDE.md` — autonomy level only (scan for Level 1/2/3)
 
-Determine current status and resume from wherever the milestone left off.
+Do NOT read contracts, domains, docs, or source code. You are the orchestrator — phase agents handle their own context loading.
 
-## Step 1.5: QA Agent Spawning
+### Integrity Check
 
-Every phase that produces or validates code will automatically spawn a QA teammate. The QA agent is spawned per-phase (not once for the entire wave) because each phase has different QA responsibilities. Each phase's command file contains its own QA spawn instructions — follow them when executing that phase.
+After reading progress.md, verify it contains the required fields before proceeding:
+- **Status field**: A `Status:` line with a recognized value (DEFINED, PARTITIONED, PLANNED, etc.)
+- **Milestone name**: A `Milestone` heading or table entry identifying the current milestone
+- **Domains table**: A `| Domain |` table with at least one row
 
-## Step 2: Execute Remaining Phases
+If ANY of these are missing or malformed, STOP and report:
+"Wave cannot proceed — progress.md is missing required fields: {list}. Run `/user:gsd-t-status` to inspect, or `/user:gsd-t-init` to repair."
+Do NOT attempt to fix progress.md yourself — that risks data loss.
 
-Work through each phase that hasn't been completed:
+## Step 2: Determine Resume Point
 
-### INITIALIZED or DEFINED → Run Partition
-- Decompose into domains with contracts
-- Set status to PARTITIONED
+From progress.md status, determine which phase to start from:
 
-### PARTITIONED → Run Discuss (if needed)
-- If there are open architectural questions or multiple viable approaches: discuss
-- If the path is clear (simple milestone, clear requirements): skip to plan
-- Set status to DISCUSSED
+| Status | Next Phase |
+|--------|------------|
+| READY | Need milestone first — prompt user or run milestone |
+| INITIALIZED / DEFINED | Partition |
+| PARTITIONED | Discuss (or skip to Plan if path is clear) |
+| DISCUSSED | Plan |
+| PLANNED | Impact |
+| IMPACT_ANALYZED | Execute |
+| EXECUTED | Test-Sync |
+| TESTS_SYNCED | Integrate |
+| INTEGRATED | Verify |
+| VERIFIED | Complete |
+| VERIFY_FAILED | Remediate → re-Verify |
 
-### DISCUSSED → Run Plan
-- Create atomic task lists per domain
-- Map dependencies and checkpoints
-- Set status to PLANNED
+## Step 3: Phase Orchestration Loop
 
-### PLANNED → Run Impact Analysis
-- Analyze downstream effects of all planned changes
-- Check for contract violations
-- Trace dependencies and consumers
-- Produce `.gsd-t/impact-report.md`
+For each remaining phase, spawn an **independent agent** using the Task tool. Each agent gets a fresh context window, loads its own state from files, and reports back.
 
-**Decision Gate:**
-- If PROCEED: continue to execute
-- If PROCEED WITH CAUTION: report items, continue if no user intervention
-- If BLOCK: stop, add remediation tasks, require user decision
+### Phase Agent Spawn Pattern
 
-- Set status to IMPACT_ANALYZED
+For each phase, spawn the agent like this:
 
-### IMPACT_ANALYZED → Run Execute
-- **Auto-select mode**:
-  - Count total independent starting tasks across domains
-  - If 3+ domains with independent work AND teams are enabled: use team mode
-  - Otherwise: solo mode
-
-- **Destructive Action Guard**: Before each task, check if it involves destructive or structural changes (DROP TABLE, schema changes that lose data, removing existing modules, replacing architecture patterns). If YES → STOP and present the change to the user. Wait for explicit approval. This applies at ALL autonomy levels.
-
-- **After each task:**
-  - Run quick test-sync (affected tests only)
-  - If test failures: pause and report
-  - If all pass: continue
-
-- Run through all tasks, respecting checkpoints
-- Set status to EXECUTED
-
-### EXECUTED → Run Full Test Sync
-- Complete test coverage analysis
-- Run all tests
-- Generate/update test tasks if gaps found
-- If critical test failures: add fix tasks, re-execute
-- Set status to TESTS_SYNCED
-
-### TESTS_SYNCED → Run Integrate
-- Wire domains together
-- Verify contract compliance at boundaries
-- Run integration tests
-- Set status to INTEGRATED
-
-### INTEGRATED → Run Verify
-- **Auto-select mode**:
-  - If teams enabled and milestone is complex (3+ domains): team verify
-  - Otherwise: solo verify
-- Run quality gates across all dimensions
-- Handle remediation if needed
-- Set status to VERIFIED
-
-### VERIFIED → Run Complete Milestone
-- Archive milestone documentation to `.gsd-t/milestones/{name}/`
-- Generate summary.md
-- Clean working state for next milestone
-- Create git tag
-- Set status to COMPLETED
+```
+Task agent (subagent_type: "general-purpose", mode: "bypassPermissions"):
+  "Execute the {PHASE} phase of the current GSD-T milestone.
 
-## Step 3: Phase Transitions
+   Read and follow the full instructions in commands/gsd-t-{phase}.md
+   Read .gsd-t/progress.md for current milestone and state.
+   Read CLAUDE.md for project conventions.
+   Read .gsd-t/contracts/ for domain interfaces.
 
-Between each phase:
-1. Update `.gsd-t/progress.md`
-2. Report brief status to user
+   Complete the phase fully:
+   - Follow every step in the command file
+   - Update .gsd-t/progress.md status when done
+   - Run document ripple as specified
+   - Commit your work
 
-### Autonomy Behavior
+   Report back: one-line status summary."
+```
 
-**Level 3 (Full Auto)**: Auto-advance to the next phase after logging status. Only STOP for:
-- Destructive Action Guard violations (always)
-- Impact analysis BLOCK verdict (always)
+### Phase Sequence
+
+Execute phases in this order, spawning one agent per phase:
+
+#### 1. PARTITION
+Spawn agent → `commands/gsd-t-partition.md`
+- After: Read `progress.md`, verify status = PARTITIONED
+- If failed: Report error, stop
+
+#### 2. DISCUSS (conditional)
+- **Structured skip check** — skip discuss and go directly to Plan if ALL of these are true:
+  - (a) Single domain milestone (only one entry in Domains table)
+  - (b) No items containing "OPEN QUESTION" in the Decision Log
+  - (c) For multi-domain milestones: all cross-domain contracts exist in `.gsd-t/contracts/`
+- If ANY check fails: Spawn agent → `commands/gsd-t-discuss.md`
+  - **Note**: Discuss always pauses for user input, even at Level 3. The discuss agent will interact with the user directly.
+- If all checks pass: Skip to Plan
+
+#### 3. PLAN
+Spawn agent → `commands/gsd-t-plan.md`
+- After: Read `progress.md`, verify status = PLANNED
+
+#### 4. IMPACT
+Spawn agent → `commands/gsd-t-impact.md`
+- After: Read `progress.md` and `.gsd-t/impact-report.md`
+- **Decision Gate**:
+  - PROCEED → continue to Execute
+  - PROCEED WITH CAUTION → log items, continue
+  - BLOCK → stop, report to user, wait for decision
+
+#### 5. EXECUTE
+Spawn agent → `commands/gsd-t-execute.md`
+- This is the heaviest phase. The execute agent will handle its own domain agent spawning and QA agent internally.
+- After: Read `progress.md`, verify status = EXECUTED
+
+#### 6. TEST-SYNC
+Spawn agent → `commands/gsd-t-test-sync.md`
+- After: Read `progress.md`, verify status = TESTS_SYNCED
+
+#### 7. INTEGRATE
+Spawn agent → `commands/gsd-t-integrate.md`
+- After: Read `progress.md`, verify status = INTEGRATED
+
+#### 8. VERIFY
+Spawn agent → `commands/gsd-t-verify.md`
+- After: Read `progress.md`, check status:
+  - VERIFIED → proceed to Complete
+  - VERIFY_FAILED → handle remediation (see Error Recovery)
+
+#### 9. COMPLETE
+Spawn agent → `commands/gsd-t-complete-milestone.md`
+- After: Read `progress.md`, verify status = COMPLETED
+
+### Between Each Phase
+
+After each agent completes:
+1. Read `.gsd-t/progress.md` to verify the phase updated status correctly
+2. Report brief status to user:
+   ```
+   ✅ {Phase} complete — {agent's one-line summary}
+   ```
+3. If status was NOT updated correctly: report error and stop
+4. Proceed to next phase
+
+## Step 4: Autonomy Behavior
+
+**Level 3 (Full Auto)**: Auto-advance to next phase after each agent completes. Only STOP for:
+- Destructive Action Guard violations (reported by phase agent)
+- Impact analysis BLOCK verdict
 - Unrecoverable errors after 2 fix attempts
-- The Discuss phase (always pauses for user input, even at Level 3)
+- Discuss phase (always pauses for user input)
 
-**Level 1–2**: If any phase produces findings that need user input, STOP and ask. If all clear, continue to next phase.
-
-Status messages:
-```
-✅ Partition complete — 3 domains defined, 4 contracts written
-✅ Discuss complete — 2 design decisions logged
-✅ Plan complete — 12 tasks across 3 domains
-⚠️ Impact analysis found 2 items requiring attention — proceeding
-✅ Execute complete — 12/12 tasks done
-✅ Test sync — 8 tests affected, all passing, 1 gap noted
-✅ Integrate complete — all domain boundaries wired
-✅ Verify complete — all quality gates passed
-✅ Milestone archived and tagged
-```
+**Level 1–2**: Pause between phases, show status, ask to continue.
 
-## Step 4: Completion
+## Step 5: Completion
 
 When all phases are done:
 ```
@@ -147,59 +167,95 @@ Next steps:
 
 ## Interruption Handling
 
-If the user interrupts or the session needs to end:
-1. Finish the current atomic task
-2. Save all state to `.gsd-t/progress.md`
-3. Note exactly where to resume: "{phase} — {domain} — Task {N}"
-4. Report: "Paused at {location}. Run `/user:gsd-t-resume` to continue."
+If the user interrupts or a phase agent fails:
+1. The current phase agent saves its own state to `.gsd-t/progress.md`
+2. Report: "Paused at {phase}. Run `/user:gsd-t-resume` to continue."
+3. Resume will pick up from the last completed phase
 
 ## Error Recovery
 
 ### If impact analysis blocks:
-- Report blocking issues
-- Generate remediation tasks
-- Add to appropriate domain
+- Read the impact report from the agent's output
+- Report blocking issues to user
 
-**Level 3 (Full Auto)**: Auto-execute remediation tasks, then re-run impact analysis. Only STOP if remediation fails after 2 attempts.
-
-**Level 1–2**: Ask: "Address blockers now, or pause?" If address: execute remediation tasks, re-run impact. If pause: save state, exit.
+**Level 3**: Spawn a remediation agent to fix blocking issues, then re-spawn impact agent. Max 2 attempts.
+**Level 1–2**: Ask user for direction.
 
 ### If tests fail during execute:
-- Pause execution
-- Report failing tests
-- Generate fix tasks
+- The execute agent handles test failures internally (up to 2 fix attempts)
+- If still failing after 2 attempts, the execute agent reports failure
+- Orchestrator stops and reports to user
 
-**Level 3 (Full Auto)**: Auto-execute fix tasks and re-run tests (up to 2 fix attempts). If still failing, STOP and report to user.
+### If verify fails:
+- Read verify report for failure details
 
-**Level 1–2**: Ask: "Fix now or continue?" If fix: execute fix tasks, re-run tests. If continue: note failures, proceed (will catch in verify).
+**Level 3**: Spawn remediation agent, then re-spawn verify agent. Max 2 attempts.
+**Level 1–2**: Ask user for direction.
 
-### If verify fails:
-- Report failures
-- Generate remediation tasks
-- Do NOT run complete-milestone
+## Why Agent-Per-Phase
+
+Each phase agent gets a **fresh context window** (~200K tokens). This means:
+- Phase 7 doesn't carry the context baggage from phases 1-6
+- Mid-phase compaction is eliminated for standard-sized phases
+- Each agent loads only what it needs from state files
+- The orchestrator stays lightweight (~30KB total)
+
+State handoff happens through `.gsd-t/` files — exactly what they were designed for.
+
+## Security Considerations
+
+### bypassPermissions Mode
+
+Wave spawns each phase agent with `mode: "bypassPermissions"`. This means agents execute bash commands, write files, and perform git operations **without per-action user approval**. This is by design — wave phases would be impractical with manual approval at every step.
+
+### Attack Surface
+
+If command files in `~/.claude/commands/` are tampered with, wave agents will execute the modified instructions with full permissions. The attack requires:
+1. Write access to the user's `~/.claude/commands/` directory
+2. Knowledge of the GSD-T command file format
+3. The user to run `/gsd-t-wave` after tampering
+
+### Current Mitigations
+
+- **npm-installed files**: Command files are installed from the npm registry, providing a known-good source
+- **Content comparison on update**: `gsd-t update` compares file contents and reports changes
+- **User-owned directory**: `~/.claude/commands/` inherits the user's filesystem permissions
+- **Destructive Action Guard**: CLAUDE.md instructions provide soft protection against destructive operations (DROP TABLE, schema changes, etc.), though agents could theoretically ignore these
+- **Autonomy levels**: Level 1 and Level 2 pause between phases, giving users visibility into agent activity
 
-**Level 3 (Full Auto)**: Auto-execute remediation tasks and re-run verify (up to 2 attempts). If still failing, STOP and report to user.
+### Recommendations
 
-**Level 1–2**: Ask: "Address issues now?" If yes: execute remediation, re-run verify. If no: save state with VERIFY_FAILED status.
+- For sensitive projects, use **Level 1 or Level 2 autonomy** instead of Level 3 to review each phase's output
+- Periodically verify command file integrity: `gsd-t doctor` checks installation health
+- If security is a concern, audit `~/.claude/commands/gsd-t-*.md` files for unexpected modifications
+- Keep GSD-T updated (`gsd-t update`) to receive the latest command files from npm
 
 ## Workflow Visualization
 
 ```
-┌─────────┐   ┌─────────┐   ┌──────┐   ┌────────┐   ┌─────────┐
-│PARTITION│ → │ DISCUSS │ → │ PLAN │ → │ IMPACT │ → │ EXECUTE │
-└─────────┘   └─────────┘   └──────┘   └────────┘   └────┬────┘
-                                            │            │
-                                         BLOCK?      test-sync
-                                            ↓         after each
-                                        remediate        task
-                                            │            │
-┌──────────┐   ┌────────┐   ┌───────────┐   │   ┌────────┴────────┐
-│ COMPLETE │ ← │ VERIFY │ ← │ INTEGRATE │ ← └── │ FULL TEST-SYNC  │
-└──────────┘   └────────┘   └───────────┘       └─────────────────┘
-     │
-     ↓
-  archive
-  git tag
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                     Wave Orchestrator (lightweight)                          │
+│                                                                              │
+│  ┌─────────┐   ┌─────────┐   ┌──────┐   ┌────────┐   ┌─────────┐          │
+│  │PARTITION│ → │ DISCUSS │ → │ PLAN │ → │ IMPACT │ → │ EXECUTE │          │
+│  │ agent 1 │   │ agent 2 │   │agent 3│   │agent 4 │   │ agent 5 │          │
+│  └────┬────┘   └────┬────┘   └───┬──┘   └───┬────┘   └────┬────┘          │
+│       ↓              ↓            ↓           ↓             ↓               │
+│    status          status      status      status        status             │
+│    check           check       check       check +       check              │
+│                                           gate                              │
+│                                                                              │
+│  ┌──────────┐   ┌────────┐   ┌───────────┐       ┌─────────────────┐       │
+│  │ COMPLETE │ ← │ VERIFY │ ← │ INTEGRATE │ ←──── │ FULL TEST-SYNC  │       │
+│  │ agent 9  │   │agent 8 │   │  agent 7  │       │    agent 6      │       │
+│  └────┬────┘   └────┬────┘   └─────┬─────┘       └────────┬────────┘       │
+│       ↓              ↓              ↓                      ↓               │
+│    archive        status +       status                 status              │
+│    git tag        gate check     check                  check               │
+│                                                                              │
+│  Each agent: fresh context window, reads state from files, dies when done   │
+│  Orchestrator: ~30KB total, never compacts                                  │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 $ARGUMENTS