@tekyzinc/gsd-t 2.23.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

@@ -10,6 +10,17 @@ Read ONLY:
 
 Do NOT read contracts, domains, docs, or source code. You are the orchestrator — phase agents handle their own context loading.
 
+### Integrity Check
+
+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
+
+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.
+
 ## Step 2: Determine Resume Point
 
 From progress.md status, determine which phase to start from:
@@ -64,10 +75,13 @@ Spawn agent → `commands/gsd-t-partition.md`
 - If failed: Report error, stop
 
 #### 2. DISCUSS (conditional)
-- Check: Are there open architectural questions or multiple viable approaches?
-- If YES: Spawn agent → `commands/gsd-t-discuss.md`
+- **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 NO (path is clear): Skip to Plan
+- If all checks pass: Skip to Plan
 
 #### 3. PLAN
 Spawn agent → `commands/gsd-t-plan.md`
@@ -188,6 +202,34 @@ Each phase agent gets a **fresh context window** (~200K tokens). This means:
 
 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
+
+### Recommendations
+
+- 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
 
 ```

package/docs/GSD-T-README.md

@@ -117,6 +117,18 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches | Manual |
 
+### Backlog Management
+
+| Command | Purpose | Auto |
+|---------|---------|------|
+| `/user:gsd-t-backlog-add` | Capture item, auto-categorize, append to backlog | Manual |
+| `/user:gsd-t-backlog-list` | Filtered, ordered view of backlog items | Manual |
+| `/user:gsd-t-backlog-move` | Reorder items by position (priority) | Manual |
+| `/user:gsd-t-backlog-edit` | Modify backlog entry fields | Manual |
+| `/user:gsd-t-backlog-remove` | Drop item with optional reason | Manual |
+| `/user:gsd-t-backlog-promote` | Refine, classify, launch GSD-T workflow | Manual |
+| `/user:gsd-t-backlog-settings` | Manage types, apps, categories, defaults | Manual |
+
 ---
 
 ## Workflow Phases

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-02-18
+## Last Updated: 2026-02-18 (Post-M9)
 
 ## System Overview
 
@@ -8,36 +8,100 @@ GSD-T is an npm-distributed methodology framework for Claude Code. It provides s
 
 The framework has no runtime — it is consumed entirely by Claude Code's slash command system and the user's shell. The CLI handles installation, updates, and diagnostics. The command files define the workflow methodology that Claude Code follows.
 
+**Architecture Pattern**: Distributed Markdown Instruction System with CLI Lifecycle Manager. Command files are the "source code" interpreted by Claude Code. The CLI is a lifecycle manager (install/update/init/status/doctor/uninstall). State files persist across sessions as git-tracked Markdown.
+
 ## Components
 
 ### CLI Installer (bin/gsd-t.js)
 - **Purpose**: Install, update, diagnose, and manage GSD-T across projects
-- **Location**: `bin/gsd-t.js`
+- **Location**: `bin/gsd-t.js` (1,298 lines, 81 functions, 49 exports)
 - **Dependencies**: Node.js built-ins only (fs, path, os, child_process, https)
 - **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog
+- **Organization**: Configuration → Guard section → Helpers → Heartbeat → Commands → Install/Update → Init → Status → Uninstall → Update-All → Doctor → Register → Update Check → Help → Main dispatch
+- **All functions ≤ 30 lines** (M6 refactoring). Largest: `doRegister()` at 30 lines, `summarize()` at 30 lines.
 
 ### Slash Commands (commands/*.md)
 - **Purpose**: Define the GSD-T methodology as executable workflows for Claude Code
 - **Location**: `commands/`
-- **Count**: 41 (37 GSD-T workflow + 4 utility)
-- **Format**: Pure markdown with step-numbered instructions, team mode blocks, and document ripple sections
+- **Count**: 43 (39 GSD-T workflow + 4 utility: gsd, branch, checkin, Claude-md)
+- **Format**: Pure markdown with step-numbered instructions, team mode blocks, document ripple sections, and $ARGUMENTS terminator
 
 ### Templates (templates/*.md)
 - **Purpose**: Starter files for project initialization
 - **Location**: `templates/`
 - **Count**: 9 (CLAUDE-global, CLAUDE-project, requirements, architecture, workflows, infrastructure, progress, backlog, backlog-settings)
-- **Tokens**: `{Project Name}`, `{Date}`, `{app}` replaced during init
+- **Tokens**: `{Project Name}` and `{Date}` replaced during init via `applyTokens()`
 
-### Heartbeat System (scripts/gsd-t-heartbeat.js)
-- **Purpose**: Real-time event logging via Claude Code hooks
-- **Location**: `scripts/gsd-t-heartbeat.js`
-- **Output**: `.gsd-t/heartbeat-{session}.jsonl` files
+### Hook Scripts (scripts/)
+- **gsd-t-heartbeat.js** (181 lines, 6 functions, 5 exports): Real-time event logging via Claude Code hooks. Captures 9 event types as structured JSONL. Input capped at 1MB. Session ID validated. Path traversal protection. Secret scrubbing via `scrubSecrets()`/`scrubUrl()` (M5). Notification message + title scrubbing (M8/M9). EVENT_HANDLERS map pattern (M6). Auto-cleanup after 7 days (SessionStart only, M6).
+- **npm-update-check.js** (43 lines): Background npm registry version checker. Spawned detached by CLI when update cache is stale. Path validation within `~/.claude/` (M5). Symlink check before write (M5). 1MB response limit (M5).
+- **gsd-t-fetch-version.js** (26 lines, NEW in M6): Synchronous npm registry fetch. Called by `fetchVersionSync()` via `execFileSync`. HTTPS-only, 5s timeout, 1MB limit. Silent failure on errors (caller validates).
 
 ### Examples (examples/)
 - **Purpose**: Reference project structure and settings
 - **Location**: `examples/`
 - **Contents**: settings.json, .gsd-t/ with sample contracts and domain structure
 
+## Data Flow
+
+### Installation Flow
+```
+npm install @tekyzinc/gsd-t → bin/gsd-t.js install
+  ├── Copy commands/*.md → ~/.claude/commands/
+  ├── Copy/append templates/CLAUDE-global.md → ~/.claude/CLAUDE.md
+  ├── Copy scripts/gsd-t-heartbeat.js → ~/.claude/scripts/
+  ├── Configure 9 hooks in ~/.claude/settings.json
+  └── Write version to ~/.claude/.gsd-t-version
+```
+
+### Project Initialization Flow
+```
+gsd-t init [name] → templates/ → applyTokens()
+  ├── → {project}/CLAUDE.md
+  ├── → {project}/docs/{requirements,architecture,workflows,infrastructure}.md
+  ├── → {project}/.gsd-t/{progress,backlog,backlog-settings}.md
+  └── → {project}/.gsd-t/{contracts,domains}/.gitkeep
+```
+
+### Runtime Command Execution (within Claude Code)
+```
+User types /user:gsd-t-{command} [args]
+  → Claude Code loads ~/.claude/commands/gsd-t-{command}.md
+  → Claude interprets step-by-step instructions
+  → Reads state files → Executes workflow → Pre-Commit Gate → Updates progress.md
+```
+
+### Update Check Flow
+```
+CLI command → Read cache (~/.claude/.gsd-t-update-check)
+  ├── Fresh (<1h): Show notice if latest > installed
+  ├── No cache: Synchronous fetch → cache → show notice
+  └── Stale (>1h): Spawn background scripts/npm-update-check.js
+```
+
+## Configuration Model
+
+Three-tier configuration:
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| **Global** | `~/.claude/CLAUDE.md` | Framework defaults: autonomy rules, code standards, pre-commit gate |
+| **Project** | `{cwd}/CLAUDE.md` | Project-specific: tech stack, branch guard, conventions, overrides |
+| **State** | `{cwd}/.gsd-t/` | Live state: progress, contracts, domains, backlog, scan results |
+
+## State Files
+
+| File | Purpose | Read By | Written By |
+|------|---------|---------|------------|
+| `progress.md` | Master state, version, decision log | All commands | Most commands |
+| `contracts/*.md` | Domain interfaces | execute, integrate, verify | partition |
+| `domains/{name}/scope.md` | File ownership | execute, quick | partition |
+| `domains/{name}/tasks.md` | Task list | execute, status, resume | plan, execute |
+| `backlog.md` | Priority-ordered backlog | backlog-list, status | backlog-add/edit/move/remove |
+| `backlog-settings.md` | Types, apps, categories | backlog-add/edit/settings | backlog-settings, init |
+| `techdebt.md` | Prioritized tech debt | promote-debt, scan | scan |
+| `scan/*.md` | Codebase analysis | scan (synthesis), setup | scan (teammates) |
+
 ## Data Models
 
 ### Progress State (.gsd-t/progress.md)
@@ -45,14 +109,14 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 |-------|------|-------|
 | Project | string | Name from CLAUDE.md |
 | Version | semver | Major.Minor.Patch |
-| Status | enum | INITIALIZED, IN_PROGRESS, READY |
+| Status | enum | READY, INITIALIZED, PARTITIONED, DISCUSSED, PLANNED, IMPACT_ANALYZED, EXECUTING, EXECUTED, TESTS_SYNCED, INTEGRATED, VERIFIED, VERIFY_FAILED, COMPLETED |
 | Current Milestone | string | Active milestone name or "None" |
 | Decision Log | entries | Timestamped log of all changes |
 
 ### Backlog (.gsd-t/backlog.md)
 | Field | Type | Notes |
 |-------|------|-------|
-| ID | Bn | Sequential backlog item ID |
+| Position | integer | Sequential, 1 = highest priority |
 | Type | enum | bug, feature, improvement, ux, architecture |
 | App | string | Target application |
 | Category | string | Domain/module category |
@@ -61,14 +125,60 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 ### Contracts (.gsd-t/contracts/)
 | Contract | Purpose |
 |----------|---------|
-| command-interface-contract.md | Slash command file format and structure |
-| file-format-contract.md | File naming and organization rules |
+| backlog-command-interface.md | Backlog command interface and promote flow |
 | integration-points.md | How components connect |
-| backlog-file-formats.md | Backlog markdown structure |
+| backlog-file-formats.md | Backlog markdown structure (authoritative — duplicate file-format-contract.md deleted in M9) |
 | domain-structure.md | Domain directory layout |
 | pre-commit-gate.md | Commit checklist contract |
 | progress-file-format.md | Progress.md structure |
 | wave-phase-sequence.md | Phase ordering rules |
+| qa-agent-contract.md | QA agent spawn interface, output per phase, communication protocol |
+
+## Workflow Phase Architecture
+
+```
+PARTITION → DISCUSS → PLAN → IMPACT → EXECUTE → TEST-SYNC → INTEGRATE → VERIFY → COMPLETE
+```
+
+| Phase | Mode | QA Agent | Why |
+|-------|------|----------|-----|
+| Partition | Solo only | YES — test skeletons | Needs full cross-domain context |
+| Discuss | Solo only | No | Always pauses for user input (even Level 3) |
+| Plan | Solo only | YES — acceptance scenarios | Needs full cross-domain context |
+| Impact | Solo only | No | Cross-cutting analysis |
+| Execute | Solo or Team | YES — continuous testing | Tasks within domains are independent |
+| Test-Sync | Solo only | YES — coverage audit | Sequential verification |
+| Integrate | Solo only | YES — boundary tests | Needs to see all seams |
+| Verify | Solo or Team | YES — full audit | Dimensions are independent |
+| Complete | Solo only | YES — final gate | Archival and tagging |
+
+### Wave Orchestrator (Agent-Per-Phase Model)
+
+The wave command spawns an independent agent for each phase via the Task tool with `bypassPermissions`. Each phase agent gets a fresh ~200K token context window, eliminating context accumulation and mid-wave compaction. The orchestrator itself stays lightweight (~30KB), reading only `progress.md` and `CLAUDE.md`. State handoff between phases occurs through `.gsd-t/` files.
+
+### QA Agent Integration
+
+10 commands spawn a QA teammate (`commands/gsd-t-qa.md`) for test-driven contract enforcement. QA behavior is phase-dependent: test skeletons during partition, continuous testing during execute, full audit during verify. QA failure blocks phase completion (user override available). Communication protocol: `QA: {PASS|FAIL} — {summary}`.
+
+### Test Suite (test/)
+- **helpers.test.js** (27 tests): Pure helper functions — validateProjectName, applyTokens, isNewerVersion, normalizeEol, etc.
+- **filesystem.test.js** (37 tests): Filesystem helpers + CLI subcommand integration — ensureDir, isSymlink, writeTemplateFile, status/doctor/help outputs
+- **security.test.js** (30 tests): Security functions — scrubSecrets (18), scrubUrl (5), summarize integration (4), hasSymlinkInPath (3)
+- **cli-quality.test.js** (22 tests): M6 refactored functions — buildEvent (10), readProjectDeps (3), readPyContent (2), insertGuardSection (3), readUpdateCache (1), addHeartbeatHook (3)
+- **Runner**: Node.js built-in (`node --test`), zero test dependencies
+- **Total**: 116 tests, all passing
+
+## Security Model
+
+- **Zero dependencies**: No supply chain attack surface
+- **Symlink protection**: `isSymlink()` at 15+ write sites + `hasSymlinkInPath()` for parent directory validation (M5)
+- **Secret scrubbing**: `scrubSecrets()` masks passwords/tokens/API keys in heartbeat logs; `scrubUrl()` masks URL query params (M5)
+- **Input validation**: Project names, version strings, session IDs, project paths all validated
+- **Path traversal prevention**: Heartbeat validates session_id regex, resolves paths, verifies containment; npm-update-check validates cache path within `~/.claude/` (M5)
+- **Command injection mitigation**: `execFileSync` with array args (not `execSync`)
+- **Exclusive file creation**: Init uses `{ flag: "wx" }` for atomic create-or-fail
+- **Resource limits**: Heartbeat stdin capped at 1MB, HTTP responses capped at 1MB (M5), 5s/8s timeouts, 7-day file cleanup
+- **Wave security**: `bypassPermissions` mode documented with attack surface analysis and mitigations (M5)
 
 ## Design Decisions
 
@@ -80,3 +190,13 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 | 2026-02-12 | Heartbeat via Claude Code hooks | Non-invasive monitoring, no command file changes needed | Polling, WebSocket |
 | 2026-02-13 | Semantic router over keyword matching | Better intent detection, fewer misroutes | Regex patterns, ML classifier |
 | 2026-02-16 | Mandatory Playwright for all projects | Consistent E2E testing, no "we'll add tests later" | Optional testing, Jest-only |
+| 2026-02-16 | Team mode default for scan | Parallel scanning faster, better results | Solo sequential scan |
+| 2026-02-17 | QA Agent as cross-cutting concern | Mandatory test-driven contracts for all code phases | Optional testing, deferred testing |
+| 2026-02-17 | Agent-per-phase wave orchestration | Fresh context window per phase, eliminates compaction | Inline execution (original approach) |
+
+## Known Architecture Concerns
+
+1. **CLI single-file size**: bin/gsd-t.js at 1,298 lines exceeds the 200-line convention, but splitting adds complexity for questionable benefit given zero-dependency constraint. Accepted deviation.
+2. **Four-file synchronization**: Any command change requires updating README, GSD-T-README, CLAUDE-global template, and gsd-t-help. Manual process — no automated validation.
+3. **Pre-Commit Gate unenforced**: Mental checklist in CLAUDE.md, not a git hook or CI check.
+4. **Progress.md Decision Log growth**: Unbounded append-only log. May need periodic archival strategy for long-lived projects.