@tekyzinc/gsd-t 2.45.11 → 2.46.11

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.46.11] - 2026-03-24
+
+### Added
+- **M28: Doc-Ripple Subagent** — automated document ripple enforcement agent. Threshold check (7 FIRE/3 SKIP conditions), blast radius analysis, manifest generation, parallel document updates. New command: `gsd-t-doc-ripple`. 43 new tests. Wired into execute, integrate, quick, debug, wave.
+- **Orchestrator context self-check** — execute and wave orchestrators now check their own context utilization after every domain/phase. If >= 70%, saves progress and stops to prevent session breaks.
+- **Functional E2E test quality standard (REQ-050)** — Playwright specs must verify functional behavior, not just element existence. Shallow test audit added to qa, test-sync, verify, complete-milestone commands.
+- **Document Ripple Completion Gate (REQ-051)** — structural rule preventing "done" reports until all downstream documents are updated.
+
+### Changed
+- Command count: 50 → 51 (added `gsd-t-doc-ripple`)
+- Package description updated to include doc-ripple enforcement
+
 ## [2.39.12] - 2026-03-19
 
 ### Added

package/README.md

@@ -22,7 +22,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 45 GSD-T commands + 5 utility commands (50 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 46 GSD-T commands + 5 utility commands (51 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -141,6 +141,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning | In wave |
 | `/user:gsd-t-test-sync` | Sync tests with code changes | In wave |
 | `/user:gsd-t-qa` | QA agent — test generation, execution, gap reporting | Auto-spawned |
+| `/user:gsd-t-doc-ripple` | Automated document ripple — update downstream docs after code changes | Auto-spawned |
 | `/user:gsd-t-integrate` | Wire domains together | In wave |
 | `/user:gsd-t-verify` | Run quality gates + goal-backward behavior verification | In wave |
 | `/user:gsd-t-complete-milestone` | Archive + git tag (goal-backward gate required) | In wave |
@@ -314,8 +315,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 50 slash commands
-│   ├── gsd-t-*.md                     # 44 GSD-T workflow commands
+├── commands/                          # 51 slash commands
+│   ├── gsd-t-*.md                     # 45 GSD-T workflow commands
 │   ├── gsd.md                         # GSD-T smart router
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper

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

@@ -445,8 +445,9 @@ Verify the milestone is truly complete:
    c. If specs are missing or stale, invoke `gsd-t-test-sync` first.
    d. Report: "Unit: X/Y pass | E2E: X/Y pass"
 2. **Verify all pass**: Every test must pass. If any fail, fix before tagging (up to 2 attempts)
+3. **Functional test quality gate**: Read every Playwright spec. Verify assertions check **functional behavior** (state changed after action, data loaded, content updated, widget responded to input) — NOT just element existence (`isVisible`, `toBeAttached`, `toBeEnabled`). Shallow tests that would pass on an empty HTML page with the right element IDs are a milestone completion FAIL. Flag and rewrite before proceeding.
 4. **Compare to baseline**: If a test baseline was recorded at milestone start, verify coverage has improved or at minimum not regressed
-5. **Log test results**: Include test pass/fail counts in the milestone summary (Step 4)
+5. **Log test results**: Include test pass/fail counts and shallow test audit results in the milestone summary (Step 4)
 
 ## Step 11: Create Git Tag
 

package/commands/gsd-t-debug.md

@@ -288,7 +288,8 @@ Before committing, ensure the fix is solid:
    d. Report ALL results: "Unit: X/Y pass | E2E: X/Y pass"
 3. **Verify passing**: All tests must pass. If any fail, fix before proceeding (up to 2 attempts)
 4. **If the project has a UI but no E2E specs cover the fixed area**: WRITE THEM.
-5. **Regression check**: Confirm the fix doesn't break any adjacent functionality
+5. **Functional test quality**: Every E2E assertion must verify an action produced the correct outcome (state changed, data loaded, content updated) — not just that elements exist. Tests that only check `isVisible`/`toBeEnabled` are shallow layout tests and don't catch real bugs. If a test would pass on an empty HTML page with the right IDs, rewrite it.
+6. **Regression check**: Confirm the fix doesn't break any adjacent functionality
 
 Commit: `[debug] Fix {description} — root cause: {explanation}`
 
@@ -302,6 +303,26 @@ Signal type is always `debug-invoked` for debug sessions.
 Emit task_complete event — run via Bash:
 `node ~/.claude/scripts/gsd-t-event-writer.js --type task_complete --command gsd-t-debug --reasoning "signal_type=debug-invoked, domain={domain}" --outcome {success|failure} || true`
 
+## Step 6: Doc-Ripple (Automated)
+
+After all work is committed but before reporting completion:
+
+1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
+2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
+3. If FIRE: spawn doc-ripple agent:
+
+⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
+
+Task subagent (general-purpose, model: sonnet):
+"Execute the doc-ripple workflow per commands/gsd-t-doc-ripple.md.
+Git diff context: {files changed list}
+Command that triggered: debug
+Produce manifest at .gsd-t/doc-ripple-manifest.md.
+Update all affected documents.
+Report: 'Doc-ripple: {N} checked, {N} updated, {N} skipped'"
+
+4. After doc-ripple returns, verify manifest exists and report summary inline
+
 $ARGUMENTS
 
 ## Auto-Clear

package/commands/gsd-t-doc-ripple.md

@@ -0,0 +1,148 @@
+# GSD-T: Doc-Ripple — Automated Document Ripple Enforcement
+
+You are the doc-ripple agent. You identify and update all downstream documents after code changes. You are spawned by execute, integrate, quick, debug, and wave after primary work is committed.
+
+## Step 1: Load Context
+
+Read:
+1. `CLAUDE.md` — project conventions and Pre-Commit Gate (project-specific extensions)
+2. `.gsd-t/contracts/doc-ripple-contract.md` — trigger conditions, manifest format, update protocol
+3. `.gsd-t/contracts/pre-commit-gate.md` — the gate checklist you cross-reference
+
+Run via Bash:
+`git diff --name-only HEAD~1 2>/dev/null || git diff --cached --name-only`
+
+Store the changed file list for Steps 2–3.
+
+## Step 2: Threshold Check
+
+Evaluate the changed file list against trigger conditions from `doc-ripple-contract.md`.
+
+Output exactly:
+```
+DOC-RIPPLE THRESHOLD: {FIRE|SKIP}
+  Files changed: {N} across {N} directories
+  Cross-cutting signals: {list or "none"}
+  Reason: {brief explanation}
+```
+
+**If SKIP**: log the decision, output `Doc-ripple: SKIP — {reason}`, and stop. No manifest. No updates.
+
+**If FIRE**: proceed to Step 3.
+
+## Step 3: Blast Radius Analysis
+
+For each changed file, classify its type: source, test, contract, template, command, doc, config.
+
+Cross-reference `.gsd-t/contracts/pre-commit-gate.md` gate checklist:
+- API endpoint/shape changed → api-contract.md, Swagger spec, CLAUDE.md, README.md
+- Database schema changed → schema-contract.md, docs/schema.md
+- UI component interface changed → component-contract.md
+- New files or directories added → owning domain scope.md
+- Requirement implemented or changed → docs/requirements.md
+- Component or data flow changed → docs/architecture.md
+- Any file modified → .gsd-t/progress.md (Decision Log entry)
+- Architectural decision made → .gsd-t/progress.md (with rationale)
+- Tech debt discovered or fixed → .gsd-t/techdebt.md
+- New convention established → CLAUDE.md or domain constraints.md
+- Command file added/changed → GSD-T-README.md, README.md, templates/CLAUDE-global.md, commands/gsd-t-help.md
+- Command added/removed → all 4 above + package.json version + bin/gsd-t.js count
+- Wave flow changed → gsd-t-wave.md, GSD-T-README.md, README.md
+- Template changed → verify gsd-t-init output
+
+Build the final list: `{ document, status (UPDATED|SKIPPED), action, reason }`.
+
+## Step 4: Generate Manifest
+
+Write `.gsd-t/doc-ripple-manifest.md` (overwrite):
+
+```markdown
+# Doc-Ripple Manifest — {date}
+
+## Trigger
+- Command: {triggering command}
+- Files changed: {N}
+- Threshold: FIRE — {reason}
+
+## Blast Radius
+
+| Document | Status | Action | Reason |
+|----------|--------|--------|--------|
+| {path} | {UPDATED|SKIPPED} | {action} | {reason} |
+
+## Summary
+- Documents checked: {N}
+- Documents updated: {N}
+- Documents skipped (already current): {N}
+```
+
+## Step 5: Update Documents
+
+Count documents marked UPDATED.
+
+**Fewer than 3 updates — inline:**
+For each document: read current content → determine minimal edit → apply via Edit tool (not Write) → verify after edit.
+
+**3 or more updates — parallel subagents:**
+
+For each document or logical group:
+
+⚙ [haiku] gsd-t-doc-ripple → update {document}
+(Use sonnet for docs/architecture.md and docs/requirements.md — these need reasoning.)
+
+**OBSERVABILITY LOGGING (MANDATORY) — for each subagent spawn:**
+
+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}`
+
+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
+
+Compute context utilization:
+`if [ "${CLAUDE_CONTEXT_TOKENS_MAX:-0}" -gt 0 ]; then CTX_PCT=$(echo "scale=1; ${CLAUDE_CONTEXT_TOKENS_USED:-0} * 100 / ${CLAUDE_CONTEXT_TOKENS_MAX}" | bc); else CTX_PCT="N/A"; fi`
+
+Alert thresholds:
+- CTX_PCT >= 85: `echo "🔴 CRITICAL: Context at ${CTX_PCT}% — compaction likely. Task MUST be split."`
+- CTX_PCT >= 70: `echo "⚠️ WARNING: Context at ${CTX_PCT}% — approaching compaction threshold. Consider splitting."`
+
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-doc-ripple | Step 5 | {model} | {DURATION}s | update:{document} | {TOKENS} | {COMPACTED} | doc-ripple | — | {CTX_PCT} |`
+
+**Each document-update subagent prompt:**
+```
+Task subagent (general-purpose, model: {haiku|sonnet}):
+"Update a single document as part of doc-ripple enforcement.
+
+Document to update: {path}
+Action: {action from manifest}
+Reason: {reason from manifest}
+Git diff context (changed files): {file list}
+
+Instructions:
+1. Read the current document
+2. Apply the minimal edit — add/update only the affected section
+3. Use the Edit tool (not Write) — preserve all existing content
+4. Re-read after edit to confirm correctness
+5. Report: 'Updated {document} — {one-line summary of change}'"
+```
+
+## Step 6: Report Summary
+
+Output:
+```
+Doc-ripple: {N} checked, {N} updated, {N} skipped
+```
+
+List each updated document with a one-line summary of what changed.
+
+If any update failed, list it under `Failures:` and flag for manual review.
+
+$ARGUMENTS
+
+## Auto-Clear
+
+All work is written to project files. Execute `/clear` to free the context window for the next command.

package/commands/gsd-t-execute.md

@@ -168,6 +168,26 @@ Execute the task above:
    - If the project has a UI but no Playwright E2E specs exist for the features being
      touched: WRITE THEM. A placeholder spec is not sufficient — write real E2E tests
      that exercise the actual UI functionality being built or changed.
+   - **FUNCTIONAL E2E TESTS — NOT LAYOUT TESTS (MANDATORY)**:
+     E2E tests that only check element existence (isVisible, isEnabled, toBeAttached)
+     are LAYOUT tests, not functional tests. Layout tests pass even when every feature
+     is broken. Every Playwright spec MUST verify functional behavior:
+     a. **State changes**: After an action (click, type, submit), assert the app STATE
+        changed — not just that the button was clickable. Example: clicking a tab must
+        load different content; verify the content changed, not just that the tab exists.
+     b. **Data flow**: Form submissions must verify data arrived (API call made, response
+        rendered, list updated). Don't just assert the form rendered.
+     c. **Navigation/routing**: Tab/page switches must verify the NEW content loaded.
+        Assert on content unique to the destination, not the navigation element itself.
+     d. **Interactive widgets**: Terminals must accept input and produce output. Editors
+        must save changes. Panels must load their functional content after opening.
+     e. **Network integration**: If a feature requires WebSocket/API connection, verify
+        the connection status changes (e.g., "Disconnected" → "Connected") and that
+        messages flow through the connection.
+     f. **Error recovery**: Don't just check error messages render — verify the app
+        recovers (retry button works, form can be resubmitted, etc.).
+     A test that would pass on an empty HTML page with the right element IDs is useless.
+     Every assertion must prove the FEATURE WORKS, not that the ELEMENT EXISTS.
 7. Run ALL test suites — this is NOT optional, not conditional, not "if applicable":
    a. Detect configured test runners: check for vitest/jest config, playwright.config.*, cypress.config.*
    b. Run EVERY detected suite. Unit tests alone are NEVER sufficient when E2E exists.
@@ -187,8 +207,13 @@ Execute the task above:
      b. E2E tests: check for playwright.config.* or cypress.config.* — if found, run the FULL E2E suite
      c. NEVER skip E2E when a config file exists. Running only unit tests is a QA FAILURE.
      d. Read .gsd-t/contracts/ for contract definitions. Check contract compliance.
-     Report format: "Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Contract: compliant/violations"'
-    If QA fails, fix before proceeding. Append issues to .gsd-t/qa-issues.md.
+     e. AUDIT E2E test quality: Review each Playwright spec — if any test only checks
+        element existence (isVisible, toBeAttached, toBeEnabled) without verifying functional
+        behavior (state changes, data loaded, content updated after actions), flag it as
+        "SHALLOW TEST — needs functional assertions" in the gap report. A test suite where
+        every spec passes but no feature actually works is a QA FAILURE.
+     Report format: "Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Contract: compliant/violations | Shallow tests: N (list)"'
+    If QA fails OR shallow tests are found, fix before proceeding. Append issues to .gsd-t/qa-issues.md.
 12. Write task summary to .gsd-t/domains/{domain-name}/task-{task-id}-summary.md:
     ## Task {task-id} Summary — {domain-name}
     - **Status**: PASS | FAIL
@@ -275,10 +300,11 @@ RULES FOR ALL TEAMMATES:
 - **Destructive Action Guard**: NEVER drop tables, remove columns, delete data, replace architecture patterns, or remove working modules without messaging the lead first. The lead must get user approval before any destructive action proceeds.
 - Only modify files listed in your domain's scope.md
 - Implement interfaces EXACTLY as specified in contracts
-- **Write comprehensive tests with every task** — no feature code without test code:
+- **Write comprehensive FUNCTIONAL tests with every task** — no feature code without test code:
   - Unit/integration tests: happy path + edge cases + error cases for every new/changed function
   - Playwright E2E specs (if UI/routes/flows/modes changed): new specs for new features, cover all modes/flags, form validation, empty/loading/error states, common edge cases
   - Tests are part of the deliverable, not a follow-up
+  - **E2E tests MUST be functional, not layout tests**: Every assertion must verify an action produced the correct outcome (state changed, data loaded, content updated) — NOT just that an element is visible/clickable. A test that passes on an empty HTML shell with correct IDs is worthless. See the Functional E2E Test Requirements in the solo mode instructions above.
 - If a task is marked BLOCKED, message the lead and wait
 - Run the Pre-Commit Gate checklist from CLAUDE.md BEFORE every commit — update all affected docs
 - **Commit immediately after each task**: `feat({domain}/task-{N}): {description}` — do NOT batch commits
@@ -399,6 +425,29 @@ After all merges complete (whether all passed, some rolled back, or errors occur
 Cleanup is not optional — orphaned worktrees waste disk space and can confuse subsequent executions. Always run cleanup, even if earlier steps failed.
 ```
 
+## Step 3.5: Orchestrator Context Self-Check (MANDATORY)
+
+After EVERY domain completes (and after every checkpoint), the orchestrator MUST check its own context utilization:
+
+Run via Bash:
+`if [ "${CLAUDE_CONTEXT_TOKENS_MAX:-0}" -gt 0 ]; then CTX_PCT=$(echo "scale=1; ${CLAUDE_CONTEXT_TOKENS_USED:-0} * 100 / ${CLAUDE_CONTEXT_TOKENS_MAX}" | bc); else CTX_PCT="N/A"; fi && echo "Orchestrator context: ${CTX_PCT}%"`
+
+**If CTX_PCT >= 70:**
+1. **Save checkpoint to disk** — update `.gsd-t/progress.md` with:
+   - Which domains are complete, which remain
+   - Current wave, next domain to execute
+   - Any checkpoint results
+2. **Instruct user**: Output exactly:
+   ```
+   ⚠️ Orchestrator context at {CTX_PCT}% — approaching limit.
+   Progress saved. Run `/clear` then `/user:gsd-t-execute` to continue from the next domain.
+   ```
+3. **STOP execution.** Do NOT spawn another domain subagent. The next session will resume from saved state.
+
+**If CTX_PCT < 70:** Continue normally to the next domain/wave.
+
+This prevents the orchestrator from running out of context mid-milestone, which causes session breaks and summary-based recovery.
+
 ## Step 4: Checkpoint Handling
 
 When a checkpoint is reached (solo or team):
@@ -451,6 +500,26 @@ When all tasks in all domains are complete:
 
 **Level 1–2**: Report completion summary and recommend proceeding to integrate phase. Wait for confirmation.
 
+## Step 7: Doc-Ripple (Automated)
+
+After all work is committed but before reporting completion:
+
+1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
+2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
+3. If FIRE: spawn doc-ripple agent:
+
+⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
+
+Task subagent (general-purpose, model: sonnet):
+"Execute the doc-ripple workflow per commands/gsd-t-doc-ripple.md.
+Git diff context: {files changed list}
+Command that triggered: execute
+Produce manifest at .gsd-t/doc-ripple-manifest.md.
+Update all affected documents.
+Report: 'Doc-ripple: {N} checked, {N} updated, {N} skipped'"
+
+4. After doc-ripple returns, verify manifest exists and report summary inline
+
 ## Document Ripple
 
 Execute modifies source code, so the Pre-Commit Gate (referenced in Step 9) covers document updates. For clarity, the key documents affected by execution:

package/commands/gsd-t-help.md

@@ -38,6 +38,7 @@ MILESTONE WORKFLOW                                          [auto] = in wave
   execute      [auto] Run tasks (solo or team mode)
   test-sync    [auto] Sync tests with code changes
   qa           [auto] QA agent — test generation, execution, gap reporting
+  doc-ripple   [auto] Automated document ripple — update docs after code changes
   integrate    [auto] Wire domains together at boundaries
   verify       [auto] Run quality gates → auto-invokes complete-milestone
   complete-milestone [auto] Archive milestone + git tag (auto-invoked by verify)
@@ -264,6 +265,12 @@ Use these when user asks for help on a specific command:
 - **Creates**: Contract test skeletons, acceptance tests, edge case tests, test audit reports
 - **Use when**: Automatically spawned — never needs manual invocation. Standalone use for ad-hoc test audits.
 
+### doc-ripple
+- **Summary**: Automated document ripple — identifies and updates all downstream docs after code changes
+- **Auto-invoked**: Yes (after primary work in execute, integrate, quick, debug, wave)
+- **Creates**: `.gsd-t/doc-ripple-manifest.md`
+- **Use when**: Automatically spawned — never needs manual invocation. Standalone use for ad-hoc doc sync audits.
+
 ### integrate
 - **Summary**: Wire domains together at their boundaries
 - **Auto-invoked**: Yes (in wave, after execute)

package/commands/gsd-t-integrate.md

@@ -126,7 +126,10 @@ Run ALL configured test suites — detect and run every one:
 a. Unit tests (vitest/jest/mocha): run the full suite
 b. E2E tests: check for playwright.config.* or cypress.config.* — if found, run the FULL E2E suite
 c. NEVER skip E2E when a config file exists. Running only unit tests is a QA FAILURE.
-Report: 'Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Boundary: pass/fail by contract'"
+d. AUDIT E2E test quality: Review each Playwright spec — if any test only checks element existence
+   (isVisible, toBeAttached, toBeEnabled) without verifying functional behavior (state changes,
+   data loaded, content updated after actions), flag it as 'SHALLOW TEST — needs functional assertions'.
+Report: 'Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Boundary: pass/fail by contract | Shallow tests: N'"
 ```
 
 **OBSERVABILITY LOGGING (MANDATORY):**
@@ -176,8 +179,29 @@ After integration and doc ripple, verify everything works together:
    c. Unit tests alone are NEVER sufficient when E2E exists
    d. Report: "Unit: X/Y pass | E2E: X/Y pass"
 3. **Verify passing**: All tests must pass. If any fail, fix before proceeding (up to 2 attempts)
+4. **Functional test quality**: Spot-check E2E specs — every assertion must verify functional behavior (state changed, data loaded, content updated after action), not just element existence. Shallow tests that would pass on an empty HTML page are not acceptable.
 5. **Smoke test results**: Ensure the Step 4 smoke test results are still valid after any fixes
 
+## Step 7.5: Doc-Ripple (Automated)
+
+After all integration work is committed but before reporting completion:
+
+1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
+2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
+3. If FIRE: spawn doc-ripple agent:
+
+⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
+
+Task subagent (general-purpose, model: sonnet):
+"Execute the doc-ripple workflow per commands/gsd-t-doc-ripple.md.
+Git diff context: {files changed list}
+Command that triggered: integrate
+Produce manifest at .gsd-t/doc-ripple-manifest.md.
+Update all affected documents.
+Report: 'Doc-ripple: {N} checked, {N} updated, {N} skipped'"
+
+4. After doc-ripple returns, verify manifest exists and report summary inline
+
 ## Step 8: Handle Integration Issues
 
 For each issue found:

package/commands/gsd-t-qa.md

@@ -81,13 +81,16 @@ Your behavior depends on which phase spawned you:
 
 ### During Verify
 **Trigger**: Lead invokes verify phase
-**Action**: Full test audit
+**Action**: Full test audit + shallow test detection
 
 1. Run ALL tests — contract tests, acceptance tests, edge case tests, existing project tests
 2. Coverage audit: For every contract, confirm tests exist and pass
 3. For every new feature/mode/flow, confirm Playwright specs cover happy path, error states, edge cases
-4. Gap report: List any untested contracts or code paths
-5. Report: `QA: {pass|fail} — {N} contract tests, {N} acceptance tests, {N} edge case tests. Gaps: {list or "none"}`
+4. **Shallow test audit**: Read every Playwright spec file. For each `test()` block, check whether the assertions verify functional behavior (state changes, data flow, content updates after actions) or only check element existence (isVisible, toBeAttached, toBeEnabled). Flag any test that would pass on an empty HTML shell as `SHALLOW — needs functional assertions`.
+5. Gap report: List any untested contracts, code paths, AND shallow tests
+6. Report: `QA: {pass|fail} — {N} contract tests, {N} acceptance tests, {N} edge case tests. Gaps: {list or "none"}. Shallow E2E tests: {N} (list or "none")`
+
+**Shallow tests block verification.** A passing E2E suite where tests don't actually verify feature behavior is equivalent to a failing suite.
 
 ### During Quick
 **Trigger**: Lead runs a quick task
@@ -189,10 +192,28 @@ For each table in `schema-contract.md`:
 For each component in `component-contract.md`:
 - Each `## ComponentName` → one `test.describe` block
 - `Props:` → renders with required props, handles missing optional props
-- `Events:` → event handlers fire correctly
-- API references → verify correct API calls made
+- `Events:` → event handlers fire correctly AND produce the expected state change
+- API references → verify correct API calls made AND responses rendered correctly
 - Auto-generate: empty form, partial form, network error handling
 
+### Functional E2E Test Standard (MANDATORY for all Playwright specs)
+
+**E2E tests that only verify element existence are LAYOUT tests, not functional tests. Layout tests pass even when every feature is broken. This is a QA failure.**
+
+Every Playwright spec MUST verify functional behavior — that actions produce the correct outcome:
+
+| Test Pattern | WRONG (layout test) | RIGHT (functional test) |
+|---|---|---|
+| Tab switching | `expect(tab).toBeVisible()` | Click tab → assert NEW content loaded (text, data unique to that tab) |
+| Form submit | `expect(submitBtn).toBeEnabled()` | Fill form → submit → assert success message AND data persisted (API call, list updated) |
+| Terminal/editor | `expect(terminal).toBeAttached()` | Open terminal → type command → assert output appears |
+| WebSocket | `expect(statusBadge).toBeVisible()` | Wait for connection → assert status text changes to "Connected" → send message → assert response |
+| Navigation | `expect(link).toHaveAttribute('href')` | Click link → assert URL changed AND destination content rendered |
+| Toggle/mode | `expect(toggle).toBeVisible()` | Click toggle → assert the EFFECT (dark mode CSS applied, panel expanded with content, feature enabled) |
+| Error state | `expect(errorDiv).toBeVisible()` | Trigger error → assert message content → assert recovery action works |
+
+**Rule: If a test would pass on an empty HTML shell with the right element IDs, it is not a functional test. Every assertion must prove the feature works, not that the element exists.**
+
 ## Test File Conventions
 
 - **Location**: Project's test directory (detected from `playwright.config.*` or `package.json`)

package/commands/gsd-t-quick.md

@@ -133,6 +133,7 @@ Quick does not mean skip testing. Before committing:
    - Playwright E2E specs (if UI/routes/flows/modes changed): create new specs for new functionality, update existing specs for changed behavior
    - Cover all modes/flags affected by this change
    - "No feature code without test code" applies to quick tasks too
+   - **Functional tests only** — every E2E assertion must verify an action produced the correct outcome (state changed, data loaded, content updated). Tests that only check element existence (`isVisible`, `toBeEnabled`) are shallow/layout tests and are not acceptable. If a test would pass on an empty HTML page with the right IDs, rewrite it.
 2. **Run ALL configured test suites** — not just affected tests, not just one suite:
    a. Detect all runners: check for vitest/jest config, playwright.config.*, cypress.config.*
    b. Run EVERY detected suite. Unit tests alone are NEVER sufficient when E2E exists.
@@ -145,6 +146,26 @@ Quick does not mean skip testing. Before committing:
    - If a contract exists for the interface touched, does the code still match?
 4. **No test framework?**: Set one up, or at minimum manually verify and document how in the commit message
 
+## Step 6: Doc-Ripple (Automated)
+
+After all work is committed but before reporting completion:
+
+1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
+2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed to completion
+3. If FIRE: spawn doc-ripple agent:
+
+⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
+
+Task subagent (general-purpose, model: sonnet):
+"Execute the doc-ripple workflow per commands/gsd-t-doc-ripple.md.
+Git diff context: {files changed list}
+Command that triggered: quick
+Produce manifest at .gsd-t/doc-ripple-manifest.md.
+Update all affected documents.
+Report: 'Doc-ripple: {N} checked, {N} updated, {N} skipped'"
+
+4. After doc-ripple returns, verify manifest exists and report summary inline
+
 $ARGUMENTS
 
 ## Auto-Clear

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

@@ -151,6 +151,27 @@ If Playwright is configured (`playwright.config.*` or Playwright in dependencies
 
 **This is NOT optional.** Every new code path that a user can reach must have a Playwright spec. "We'll add tests later" is never acceptable.
 
+**FUNCTIONAL TESTS — NOT LAYOUT TESTS (MANDATORY):**
+E2E specs that only check element existence (`isVisible`, `toBeAttached`, `toBeEnabled`) are
+layout tests. Layout tests pass even when every feature is broken — they are worthless for QA.
+
+Every Playwright assertion MUST verify **functional behavior** — that an action produced the
+correct outcome:
+- **Tab/navigation**: Click → assert the NEW content loaded (unique text, data, or elements
+  that only appear on the destination view). Never just assert the tab element exists.
+- **Forms**: Fill → submit → assert success feedback AND data persisted (API call observed
+  via `page.waitForResponse`, or list/table updated with new entry).
+- **Interactive widgets** (terminals, editors, code panels): Open → interact → assert the
+  widget responded (keystroke produced output, content was saved, command executed).
+- **Connections** (WebSocket, SSE, polling): Assert status transitions ("Connecting" →
+  "Connected") and verify data flows through the connection.
+- **State toggles** (dark mode, expand/collapse, enable/disable): Assert the EFFECT of the
+  toggle, not just that the toggle control exists.
+- **Error handling**: Trigger error → assert error content → assert recovery path works.
+
+**Rule: If a test would pass on an empty HTML page with the correct element IDs and no
+JavaScript, it is not a functional test. Rewrite it.**
+
 ### D) Capture Results
 For all test types:
 - PASS: Test still valid

package/commands/gsd-t-verify.md

@@ -104,7 +104,8 @@ Work through each dimension sequentially. For each:
    - Confirm specs cover: happy path, error states, edge cases, all modes/flags
    - If specs are missing or incomplete → invoke `gsd-t-test-sync` to create them, then re-run
    - **Missing E2E coverage on new functionality = verification FAIL**
-5. Tests are NOT optional — verification cannot pass without running them and confirming comprehensive coverage
+5. **Functional test quality audit**: Read every Playwright spec. For each `test()` block, verify assertions check **functional behavior** (state changed after action, data loaded, content updated, widget responded) — NOT just element existence (`isVisible`, `toBeAttached`, `toBeEnabled`). A test that would pass on an empty HTML page with the right element IDs is a **shallow test** and counts as a verification FAIL. Flag shallow tests and rewrite them before proceeding.
+6. Tests are NOT optional — verification cannot pass without running them and confirming comprehensive, functional coverage
 
 ### Team Mode (when agent teams are enabled)
 ```

package/commands/gsd-t-wave.md

@@ -84,6 +84,17 @@ Compute context utilization — run via Bash:
 Alert on context thresholds (display to user inline):
 - If CTX_PCT >= 85: `echo "🔴 CRITICAL: Context at ${CTX_PCT}% — compaction likely. Task MUST be split."`
 - If CTX_PCT >= 70: `echo "⚠️ WARNING: Context at ${CTX_PCT}% — approaching compaction threshold. Consider splitting in plan."`
+
+**Orchestrator Context Self-Check (MANDATORY):**
+After EVERY phase agent returns, check the wave orchestrator's own context:
+- **If CTX_PCT >= 70:**
+  1. Save checkpoint to `.gsd-t/progress.md` — record which phases are complete, which remain
+  2. Output: `⚠️ Wave orchestrator context at {CTX_PCT}% — approaching limit. Progress saved. Run /clear then /user:gsd-t-wave to continue from the next phase.`
+  3. **STOP the wave loop.** Do NOT spawn the next phase agent. The next session resumes from saved state.
+- **If CTX_PCT < 70:** Continue to next phase.
+
+This prevents the wave orchestrator from running out of context mid-wave.
+
 Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted | Domain | Task | Ctx% |` if missing):
 `| {DT_START} | {DT_END} | gsd-t-wave | {PHASE} | sonnet | {DURATION}s | phase: {PHASE} | {TOKENS} | {COMPACTED} | | | {CTX_PCT} |`
 
@@ -149,6 +160,26 @@ Spawn agent → `commands/gsd-t-verify.md`
   📋 Phase 8 (VERIFY+COMPLETE): {N} gates passed | Goal-Backward: {PASS/WARN/FAIL} — {N} requirements checked, {N} findings
   ```
 
+#### 9. DOC-RIPPLE (Automated — after verify+complete)
+
+After the final phase completes but before wave reports done:
+
+1. Run threshold check — read `git diff --name-only HEAD~1` and evaluate against doc-ripple-contract.md trigger conditions
+2. If SKIP: log "Doc-ripple: SKIP — {reason}" and proceed
+3. If FIRE: spawn doc-ripple agent:
+
+⚙ [{model}] gsd-t-doc-ripple → blast radius analysis + parallel updates
+
+Task subagent (general-purpose, model: sonnet):
+"Execute the doc-ripple workflow per commands/gsd-t-doc-ripple.md.
+Git diff context: {files changed list}
+Command that triggered: wave
+Produce manifest at .gsd-t/doc-ripple-manifest.md.
+Update all affected documents.
+Report: 'Doc-ripple: {N} checked, {N} updated, {N} skipped'"
+
+4. After doc-ripple returns, verify manifest exists and report summary inline
+
 ### Between Each Phase
 
 After each agent completes, run this spot-check before proceeding:

package/docs/GSD-T-README.md

@@ -103,6 +103,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning | In wave |
 | `/user:gsd-t-test-sync` | Sync tests with code changes | In wave |
 | `/user:gsd-t-qa` | QA agent — test generation, execution, gap reporting | Auto-spawned |
+| `/user:gsd-t-doc-ripple` | Automated document ripple — update downstream docs after code changes | Auto-spawned |
 | `/user:gsd-t-integrate` | Wire domains together | In wave |
 | `/user:gsd-t-verify` | Run quality gates + goal-backward verification → auto-invokes complete-milestone | In wave |
 | `/user:gsd-t-complete-milestone` | Archive + git tag (auto-invoked by verify, also standalone) | In wave |

package/docs/framework-comparison-scorecard.md

@@ -0,0 +1,160 @@
+# Framework Comparison Scorecard
+
+**Purpose**: Unbiased comparison of development frameworks.
+**Instructions**: Score each framework 1-5 per dimension. Use the rubric at the bottom. Equal weights — no dimension gaming.
+
+---
+
+## Frameworks Being Compared
+
+| Slot | Framework | Version/Variant | Evaluator | Date |
+|------|-----------|-----------------|-----------|------|
+| F1   |           |                 |           |      |
+| F2   |           |                 |           |      |
+| F3   |           |                 |           |      |
+| F4   |           |                 |           |      |
+
+---
+
+## A. Onboarding & Adoption (Dimensions 1-3)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 1 | Time to first productive output | How quickly can someone go from choosing the framework to shipping real work? |    |    |    |    |
+| 2 | Team adoption friction | How willing is a typical team to adopt it after initial exposure? |    |    |    |    |
+| 3 | Works without specific tooling | Can it be used with any IDE, editor, or AI assistant? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## B. Execution & Delivery (Dimensions 4-7)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 4 | Defect prevention | How effectively does the framework prevent bugs from reaching production? |    |    |    |    |
+| 5 | Throughput | How many features can be shipped per unit time? |    |    |    |    |
+| 6 | Rework prevention | How well does the framework prevent completed work from needing redo? |    |    |    |    |
+| 7 | Idea-to-deploy cycle time | How quickly can a concept move from idea to production? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## C. Sustainability & Maintenance (Dimensions 8-11)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 8  | New member ramp-up | How quickly can a new team member contribute independently? |    |    |    |    |
+| 9  | Context recovery | How easily can work resume after an interruption of days or weeks? |    |    |    |    |
+| 10 | Tech debt management | How well does the framework track and control technical debt? |    |    |    |    |
+| 11 | Documentation freshness | How well does the framework keep documentation accurate and current? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## D. Flexibility & Universality (Dimensions 12-15)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 12 | Minimum viable process | Can you use a small portion of it and still get value? |    |    |    |    |
+| 13 | Project type coverage | Does it work across web, mobile, data, infra, and non-code projects? |    |    |    |    |
+| 14 | Team size range | Is it effective from 1-person teams to 50-person teams? |    |    |    |    |
+| 15 | Overhead proportionality | Does ceremony scale with project size rather than being fixed? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## E. Automation & AI-Agent Capabilities (Dimensions 16-19)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 16 | Agentic workflow support | Does the framework enable AI agents to execute work autonomously (task dispatch, parallel execution, adaptive replanning)? |    |    |    |    |
+| 17 | QA automation | Does the framework automate test generation, execution, and gap detection — not just run existing tests? |    |    |    |    |
+| 18 | QA coverage enforcement | Does the framework enforce minimum coverage and block progress when tests are missing or failing? |    |    |    |    |
+| 19 | Contract enforcement | Does the framework define and validate interfaces between components automatically (API shapes, schemas, props)? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## F. Observability & Decision Quality (Dimensions 20-22)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 20 | Decision traceability | Can you find why a choice was made 6 months later? |    |    |    |    |
+| 21 | Progress accuracy | Does reported progress match actual state? |    |    |    |    |
+| 22 | Risk visibility | Do problems surface early or only at integration? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+---
+
+## Summary
+
+| Category                                    | F1 | F2 | F3 | F4 |
+|---------------------------------------------|----|----|----|----|
+| A. Onboarding & Adoption (1-3)              |    |    |    |    |
+| B. Execution & Delivery (4-7)               |    |    |    |    |
+| C. Sustainability & Maintenance (8-11)      |    |    |    |    |
+| D. Flexibility & Universality (12-15)       |    |    |    |    |
+| E. Automation & AI-Agent Capabilities (16-19) |    |    |    |    |
+| F. Observability & Decisions (20-22)        |    |    |    |    |
+| **Overall Average (1-5)**                   | **—** | **—** | **—** | **—** |
+| **Normalized Score (/100)**                 | **—** | **—** | **—** | **—** |
+
+### Calculation
+
+```
+Category Average = sum of dimension scores in category / number of dimensions in category
+Overall Average  = sum of all 22 dimension scores / 22
+Normalized /100  = Overall Average × 20
+```
+
+---
+
+## Radar Chart Data
+
+For visual comparison, plot each framework on a 6-axis radar chart using the category averages:
+
+```
+Axis 1: Onboarding & Adoption
+Axis 2: Execution & Delivery
+Axis 3: Sustainability & Maintenance
+Axis 4: Flexibility & Universality
+Axis 5: Automation & AI-Agent Capabilities
+Axis 6: Observability & Decisions
+```
+
+---
+
+## Scoring Rubric
+
+Use this rubric consistently across all frameworks and dimensions:
+
+| Score | Label         | Definition                                                                   |
+|-------|---------------|------------------------------------------------------------------------------|
+| 1     | Absent        | Not addressed by the framework. User must solve this entirely on their own.  |
+| 2     | Minimal       | Acknowledged but not enforced. Ad-hoc or optional guidance only.             |
+| 3     | Supported     | Present with some structure, but inconsistently applied or easy to skip.     |
+| 4     | Systematic    | Well-integrated, mostly enforced, clear process with known exceptions.       |
+| 5     | Core strength | Foundational to the framework. Systematically enforced, hard to bypass.      |
+
+### Scoring guidelines
+
+- **Score what the framework provides**, not what a disciplined team could achieve without it
+- **Score the default experience**, not the best-case customized setup
+- **Score independently** — don't let a high score in one dimension inflate adjacent ones
+- **Use 3 as the anchor** — most frameworks land at 3 for most dimensions. Reserve 1 and 5 for clear extremes
+- **When uncertain**, score conservatively (lower)
+
+---
+
+## Bias Checks
+
+Before finalizing scores, verify:
+
+- [ ] No single framework scores 5 on more than 9 of 22 dimensions
+- [ ] No single framework scores below 2 on more than 9 of 22 dimensions
+- [ ] Every framework has at least one category where it leads
+- [ ] The evaluator did not design or build any of the frameworks being compared (if they did, note the conflict and consider a second evaluator)
+- [ ] Dimensions were not added or removed after seeing preliminary scores
+
+---
+
+## Notes & Justifications
+
+Use this section to record reasoning for any score that might be controversial:
+
+| Dimension | Framework | Score | Justification |
+|-----------|-----------|-------|---------------|
+|           |           |       |               |
+|           |           |       |               |
+|           |           |       |               |
+|           |           |       |               |

package/docs/requirements.md

@@ -58,6 +58,9 @@
 | REQ-047 | Global ELO & Rankings — gsd-t-status displays global ELO score and cross-project rank when global metrics exist | P2 | planned | validated by use |
 | REQ-048 | Global Rule Promotion on Milestone Completion — gsd-t-complete-milestone copies promoted rules to global-rules.jsonl and updates global rollup after local promotion | P1 | planned | validated by use |
 | REQ-049 | E2E Enforcement Rule — when playwright.config.* or cypress.config.* exists, ALL test-running commands (execute, quick, debug, test-sync, integrate, verify, complete-milestone) MUST run the full E2E suite. Unit-only results are NEVER sufficient. QA subagent prompts explicitly mandate E2E detection and execution. | P1 | complete | enforced in 7 command files + CLAUDE.md + pre-commit-gate contract |
+| REQ-050 | Functional E2E Test Quality Standard — Playwright specs MUST verify functional behavior (state changes, data flow, content updates after actions), NOT just element existence (isVisible, toBeEnabled). Shallow layout tests that would pass on an empty HTML page are flagged and block verification. QA subagent audits for shallow tests. | P1 | complete | enforced in execute, qa, test-sync, verify, quick, debug, integrate, complete-milestone + global CLAUDE.md + CLAUDE-global template |
+| REQ-051 | Document Ripple Completion Gate — when a change affects multiple files, identify the full blast radius BEFORE starting, complete ALL updates in one pass, and only report completion after every downstream document is updated. Partial delivery is never acceptable. The user should never need to ask "did you update everything?" | P1 | complete | enforced in global CLAUDE.md + CLAUDE-global template + project CLAUDE.md |
+| REQ-052 | Doc-Ripple Subagent — dedicated agent auto-spawned after code-modifying commands (execute, integrate, quick, debug, wave) that analyzes git diff, identifies full blast radius of affected documents, and spawns parallel subagents to update them. Produces manifest audit trail. Threshold logic skips trivial changes. | P1 | complete | M28: contract ACTIVE, command file, 43 tests, wired into execute/integrate/quick/debug/wave |
 
 ## Technical Requirements
 

package/examples/rules/desktop.ini

@@ -0,0 +1,2 @@
+[.ShellClassInfo]
+IconResource=C:\Program Files\Google\Drive File Stream\122.0.1.0\GoogleDriveFS.exe,27

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.45.11",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 50 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
+  "version": "2.46.11",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 51 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {

package/templates/CLAUDE-global.md

@@ -49,6 +49,7 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning, active rule injection |
 | `/user:gsd-t-test-sync` | Keep tests aligned with code changes |
 | `/user:gsd-t-qa` | QA agent — test generation, execution, gap reporting |
+| `/user:gsd-t-doc-ripple` | Automated document ripple — update downstream docs after code changes |
 | `/user:gsd-t-integrate` | Wire domains together |
 | `/user:gsd-t-verify` | Run quality gates + goal-backward behavior verification |
 | `/user:gsd-t-complete-milestone` | Archive milestone + git tag (goal-backward gate, rule engine distillation) |
@@ -250,6 +251,32 @@ BEFORE reporting "tests pass" for ANY task:
 
 The conditional "if UI/routes/flows changed" in command files applies to **writing new E2E specs**, not to **running existing ones**. You always run existing E2E specs. Always.
 
+### E2E Test Quality Standard (MANDATORY)
+
+**E2E tests must be FUNCTIONAL tests, not LAYOUT tests.** This is non-negotiable.
+
+A layout test checks that elements exist (`isVisible`, `toBeAttached`, `toBeEnabled`, `toHaveCount`). A functional test checks that features work — actions produce correct outcomes.
+
+```
+LAYOUT TEST (WRONG — passes even if every feature is broken):
+  await expect(page.locator('#tab-sessions')).toBeVisible();
+  await page.click('#tab-sessions');
+  // ← No assertion that the tab's content actually loaded
+
+FUNCTIONAL TEST (RIGHT — fails if the feature is broken):
+  await page.click('#tab-sessions');
+  await expect(page.locator('.session-list')).toContainText('Session 1');
+  // ← Proves clicking the tab loaded the session data
+```
+
+Every Playwright assertion must verify one of:
+- **State changed**: After click/type/submit, the app state is different (new content, updated data, changed status)
+- **Data flowed**: User input → API call → response rendered (use `page.waitForResponse` or assert on rendered data)
+- **Content loaded**: Navigation/tab switch → destination content appeared (assert on text/data unique to destination)
+- **Widget responded**: Terminal accepted keystrokes and produced output, editor saved changes, form submitted and data persisted
+
+**If a test would pass on an empty HTML page with the correct element IDs and no JavaScript, it is not a functional test.** Rewrite it.
+
 ## QA Agent (Mandatory)
 
 Any GSD-T phase that produces or validates code **MUST run QA**. The QA agent's sole job is test generation, execution, and gap reporting. It never writes feature code.
@@ -269,10 +296,15 @@ a. Unit tests (vitest/jest/mocha): run the full suite
 b. E2E tests: check for playwright.config.* or cypress.config.* — if found, run the FULL E2E suite
 c. NEVER skip E2E when a config file exists. Running only unit tests is a QA FAILURE.
 d. Read .gsd-t/contracts/ for contract definitions. Check contract compliance.
-Report format: 'Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Contract: compliant/violations'"
+e. AUDIT E2E test quality: Review each Playwright spec — if any test only checks element
+   existence (isVisible, toBeAttached, toBeEnabled) without verifying functional behavior
+   (state changes, data loaded, content updated after user actions), flag it as
+   'SHALLOW TEST — needs functional assertions'. A passing test suite that doesn't catch
+   broken features is a QA FAILURE.
+Report format: 'Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Contract: compliant/violations | Shallow tests: N'"
 ```
 
-**QA failure blocks phase completion.** Lead cannot proceed until QA reports PASS or user explicitly overrides.
+**QA failure OR shallow tests found blocks phase completion.** Lead cannot proceed until QA reports PASS with zero shallow tests, or user explicitly overrides.
 
 ## Model Display (MANDATORY)
 
@@ -361,6 +393,35 @@ BEFORE EVERY COMMIT:
 
 If ANY answer is YES and the doc is NOT updated, update it BEFORE committing. No exceptions.
 
+## Document Ripple Completion Gate (MANDATORY)
+
+**NEVER report a task as "done" or present a summary until ALL downstream documents are updated.** This is not optional.
+
+When a change affects multiple files (e.g., a new standard that applies across command files, a renamed API, a new convention), you MUST:
+
+1. **Identify the full blast radius BEFORE starting**: List every file that needs the change
+2. **Complete ALL updates in one pass**: Do not update 3 of 8 files and then present a summary
+3. **Run the Pre-Commit Gate on the COMPLETE changeset**: Not on a partial subset
+4. **Only THEN report completion**
+
+```
+BEFORE reporting "done" or presenting a summary:
+  ├── Did this change establish a new standard, rule, or convention?
+  │     YES → Grep for every file that should enforce it. Update ALL of them.
+  ├── Did this change modify a pattern used in multiple command files?
+  │     YES → Find and update EVERY command file that uses that pattern.
+  ├── Did this change affect a template (CLAUDE-global, CLAUDE-project, etc.)?
+  │     YES → The template AND the live equivalent (~/.claude/CLAUDE.md) must match.
+  ├── Did this change add a new requirement?
+  │     YES → Add to docs/requirements.md in the same pass.
+  ├── Have I checked EVERY file in the blast radius?
+  │     NO → Keep going. Do not present partial work.
+  └── Am I about to say "want me to also update X?" or "should I check Y?"
+        YES → STOP. Just update X and check Y. Then report done.
+```
+
+**The test for this gate**: If the user asks "did you update all the documents?" and the answer would be "no, I missed some" — you failed this gate. The user should never need to ask.
+
 ## Execution Behavior
 - ALWAYS check docs/architecture.md before adding or modifying components.
 - ALWAYS check docs/workflows.md before changing any multi-step process.