@tekyzinc/gsd-t 2.45.11 → 2.50.10

package/commands/gsd-t-debug.md

@@ -8,6 +8,22 @@ To give this debug session a fresh context window and prevent compaction, always
 
 **If you are the orchestrating agent** (you received the slash command directly):
 
+**Stack Rules Detection (before spawning subagent):**
+Run via Bash to detect project stack and collect matching rules:
+`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react-native"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react-native.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react-native.md")"$'\n\n'; grep -q '"react"' package.json 2>/dev/null && ! grep -q '"react-native"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; grep -q '"next"' package.json 2>/dev/null && [ -f "$STACKS_DIR/nextjs.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/nextjs.md")"$'\n\n'; grep -q '"vue"' package.json 2>/dev/null && [ -f "$STACKS_DIR/vue.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/vue.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; grep -q '"tailwindcss"' package.json 2>/dev/null && [ -f "$STACKS_DIR/tailwind.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/tailwind.md")"$'\n\n'; grep -q '"vite"' package.json 2>/dev/null && [ -f "$STACKS_DIR/vite.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/vite.md")"$'\n\n'; grep -q '"@supabase/supabase-js"' package.json 2>/dev/null && [ -f "$STACKS_DIR/supabase.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/supabase.md")"$'\n\n'; grep -q '"firebase"' package.json 2>/dev/null && [ -f "$STACKS_DIR/firebase.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/firebase.md")"$'\n\n'; grep -qE '"(graphql|@apollo/client|urql)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/graphql.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/graphql.md")"$'\n\n'; grep -q '"zustand"' package.json 2>/dev/null && [ -f "$STACKS_DIR/zustand.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/zustand.md")"$'\n\n'; grep -q '"@reduxjs/toolkit"' package.json 2>/dev/null && [ -f "$STACKS_DIR/redux.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/redux.md")"$'\n\n'; grep -q '"neo4j-driver"' package.json 2>/dev/null && [ -f "$STACKS_DIR/neo4j.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/neo4j.md")"$'\n\n'; grep -qE '"(pg|prisma|drizzle-orm|knex)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/postgresql.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/postgresql.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/rest-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rest-api.md")"$'\n\n'; fi; ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "Pipfile" ]) && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; ([ -f "requirements.txt" ] && grep -q "psycopg" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "psycopg" pyproject.toml 2>/dev/null) && [ -f "$STACKS_DIR/postgresql.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/postgresql.md")"$'\n\n'; ([ -f "requirements.txt" ] && grep -q "neo4j" requirements.txt 2>/dev/null) && [ -f "$STACKS_DIR/neo4j.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/neo4j.md")"$'\n\n'; [ -f "pubspec.yaml" ] && [ -f "$STACKS_DIR/flutter.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/flutter.md")"$'\n\n'; [ -f "Dockerfile" ] && [ -f "$STACKS_DIR/docker.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/docker.md")"$'\n\n'; [ -d ".github/workflows" ] && [ -f "$STACKS_DIR/github-actions.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/github-actions.md")"$'\n\n'; ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && [ -f "$STACKS_DIR/playwright.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/playwright.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; fi`
+
+If STACK_RULES is non-empty, append to the subagent prompt:
+```
+## Stack Rules (MANDATORY — violations fail this task)
+
+{STACK_RULES}
+
+These standards have the same enforcement weight as contract compliance.
+Violations are task failures, not warnings.
+```
+
+If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
+
 **OBSERVABILITY LOGGING (MANDATORY):**
 Before spawning — run via Bash:
 `T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M") && TOK_START=${CLAUDE_CONTEXT_TOKENS_USED:-0} && TOK_MAX=${CLAUDE_CONTEXT_TOKENS_MAX:-200000}`
@@ -215,7 +231,16 @@ When you encounter unexpected situations during the fix:
 3. **Blocker (missing file, wrong API response)** → Fix blocker and continue. Log if non-trivial.
 4. **Architectural change required to fix correctly** → STOP. Explain what exists, what needs to change, what breaks, and a migration path. Wait for user approval. Never self-approve.
 
-**3-attempt limit**: If your fix doesn't work after 3 attempts within this session, treat it as a loop. Do NOT keep trying the same approach. Log the attempt to `.gsd-t/progress.md` Decision Log with a `[failure]` prefix, then return to Step 1.5 and run Deep Research Mode before any further attempts. Present findings and options to the user before proceeding.
+**3-attempt limit**: If your fix doesn't work after 3 attempts within this session, treat it as a loop. Do NOT keep trying the same approach. Before entering Deep Research Mode, first try the headless debug-loop:
+1. Write current failure context to `.gsd-t/debug-state.jsonl` via appendEntry
+2. Log: "Delegating to headless debug-loop (3 in-context attempts exhausted)"
+3. Run: `gsd-t headless --debug-loop --max-iterations 10`
+4. Check exit code:
+   - 0: Tests pass, continue
+   - 1/4: Log to `.gsd-t/deferred-items.md`, then enter Deep Research Mode
+   - 3: Report error, stop
+
+If the debug-loop also fails (exit 1/4), log the attempt to `.gsd-t/progress.md` Decision Log with a `[failure]` prefix, return to Step 1.5 and run Deep Research Mode before any further attempts. Present findings and options to the user before proceeding.
 
 ### Solo Mode
 1. Reproduce the issue — **reproduction script must exist before step 2** (see Step 2.5)
@@ -288,7 +313,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 +328,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

@@ -119,6 +119,22 @@ Run via Bash:
 If rules fire: inject up to 10 lines of rule warnings into each task subagent prompt (concise format: `RULE: {name} — {description}`). These inform the subagent of known patterns — non-blocking.
 If no rules fire: log "No active rules for {domain-name}" and continue.
 
+**Stack Rules Detection (before spawning subagent):**
+Run via Bash to detect project stack and collect matching rules:
+`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react-native"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react-native.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react-native.md")"$'\n\n'; grep -q '"react"' package.json 2>/dev/null && ! grep -q '"react-native"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; grep -q '"next"' package.json 2>/dev/null && [ -f "$STACKS_DIR/nextjs.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/nextjs.md")"$'\n\n'; grep -q '"vue"' package.json 2>/dev/null && [ -f "$STACKS_DIR/vue.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/vue.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/rest-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rest-api.md")"$'\n\n'; grep -q '"tailwindcss"' package.json 2>/dev/null && [ -f "$STACKS_DIR/tailwind.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/tailwind.md")"$'\n\n'; grep -q '"vite"' package.json 2>/dev/null && [ -f "$STACKS_DIR/vite.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/vite.md")"$'\n\n'; grep -q '"@supabase/supabase-js"' package.json 2>/dev/null && [ -f "$STACKS_DIR/supabase.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/supabase.md")"$'\n\n'; grep -q '"firebase"' package.json 2>/dev/null && [ -f "$STACKS_DIR/firebase.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/firebase.md")"$'\n\n'; grep -qE '"(graphql|@apollo/client|urql)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/graphql.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/graphql.md")"$'\n\n'; grep -q '"zustand"' package.json 2>/dev/null && [ -f "$STACKS_DIR/zustand.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/zustand.md")"$'\n\n'; grep -q '"@reduxjs/toolkit"' package.json 2>/dev/null && [ -f "$STACKS_DIR/redux.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/redux.md")"$'\n\n'; grep -q '"neo4j-driver"' package.json 2>/dev/null && [ -f "$STACKS_DIR/neo4j.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/neo4j.md")"$'\n\n'; grep -qE '"(pg|prisma|drizzle-orm|knex)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/postgresql.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/postgresql.md")"$'\n\n'; fi; ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "Pipfile" ]) && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; ([ -f "requirements.txt" ] && grep -q "psycopg" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "psycopg" pyproject.toml 2>/dev/null) && [ -f "$STACKS_DIR/postgresql.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/postgresql.md")"$'\n\n'; ([ -f "requirements.txt" ] && grep -q "neo4j" requirements.txt 2>/dev/null) && [ -f "$STACKS_DIR/neo4j.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/neo4j.md")"$'\n\n'; [ -f "pubspec.yaml" ] && [ -f "$STACKS_DIR/flutter.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/flutter.md")"$'\n\n'; [ -f "Dockerfile" ] && [ -f "$STACKS_DIR/docker.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/docker.md")"$'\n\n'; [ -d ".github/workflows" ] && [ -f "$STACKS_DIR/github-actions.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/github-actions.md")"$'\n\n'; ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && [ -f "$STACKS_DIR/playwright.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/playwright.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; fi`
+
+If STACK_RULES is non-empty, append to the subagent prompt:
+```
+## Stack Rules (MANDATORY — violations fail this task)
+
+{STACK_RULES}
+
+These standards have the same enforcement weight as contract compliance.
+Violations are task failures, not warnings.
+```
+
+If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
+
 **Domain task-dispatcher (lightweight — sequences tasks, passes summaries):**
 
 For each task in `.gsd-t/domains/{domain-name}/tasks.md` (in order, skip completed):
@@ -150,6 +166,9 @@ Task subagent (general-purpose, model: sonnet, mode: bypassPermissions):
 ## Prior Task Summaries (most recent first, max 5)
 {contents of task-{N}-summary.md files — 10-20 lines each}
 
+## Stack Rules
+{STACK_RULES if non-empty — omit entire section if empty}
+
 ## Instructions
 
 Execute the task above:
@@ -168,6 +187,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 +226,15 @@ 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) | Stack rules: compliant/N violations"
+     f. Validate compliance with Stack Rules (if injected in the work subagent's prompt).
+        Stack rule violations have the same severity as contract violations — report as failures, not warnings.'
+    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
@@ -198,8 +244,15 @@ Execute the task above:
     - **Notes**: {10-20 lines max — key decisions, patterns, warnings}
 
 Deviation rules:
-- Bug blocking progress → fix, max 3 attempts; if still blocked, log to
-  .gsd-t/deferred-items.md and stop (report FAIL in summary)
+- Bug blocking progress → fix, max 3 attempts; after fix attempt 2 fails:
+  1. Write current failure context to .gsd-t/debug-state.jsonl via appendEntry
+  2. Log: "Delegating to headless debug-loop (2 in-context attempts exhausted)"
+  3. Run: `gsd-t headless --debug-loop --max-iterations 15`
+  4. Check exit code:
+     - 0: Tests pass, continue with task
+     - 1/4: Log to .gsd-t/deferred-items.md and stop (report FAIL in summary)
+     - 3: Report error, stop
+  If still blocked after debug-loop, log to .gsd-t/deferred-items.md and stop (report FAIL in summary)
 - Missing dependency → add minimum needed, document in commit message
 - Non-trivial blocker → log to .gsd-t/deferred-items.md
 - Architectural change required → write NEEDS-APPROVAL to .gsd-t/deferred-items.md,
@@ -275,10 +328,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 +453,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 +528,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)
@@ -64,6 +65,12 @@ UTILITIES                                                              Manual
   triage-and-merge    Auto-review, merge, and publish GitHub branches
   global-change       Apply file changes across all registered GSD-T projects
 
+HEADLESS (CI/CD)                                                       CLI
+───────────────────────────────────────────────────────────────────────────────
+  headless exec       Run any GSD-T command non-interactively via claude -p
+  headless query      Read project state without LLM (<100ms)
+  headless --debug-loop  Compaction-proof test-fix-retest loop (fresh sessions)
+
 BACKLOG                                                                Manual
 ───────────────────────────────────────────────────────────────────────────────
   backlog-add         Capture item, auto-categorize, append to backlog
@@ -251,6 +258,7 @@ Use these when user asks for help on a specific command:
 - **Use when**: Ready to implement
 - **Note (M22)**: Task-level fresh dispatch (one subagent per task, ~10-20% context each). Team mode uses worktree isolation (`isolation: "worktree"`) — zero file conflicts. Adaptive replanning between domain completions.
 - **Note (M26)**: Active rule injection — evaluates declarative rules from rules.jsonl before dispatching each domain's tasks. Fires matching rules as warnings in subagent prompts.
+- **Note (M29)**: Stack Rules Engine — auto-detects project tech stack from manifest files and injects mandatory best-practice rules into each task subagent prompt. Universal rules (`_security.md`) always apply; stack-specific rules layer on top. Violations are task failures (same weight as contract violations).
 
 ### test-sync
 - **Summary**: Keep tests aligned with code changes
@@ -264,6 +272,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)
@@ -332,11 +346,20 @@ Use these when user asks for help on a specific command:
 - **Use when**: Reviewing process health, first-pass rates, ELO trends, anomaly flags, or comparing signal distributions across projects
 
 ### debug
-- **Summary**: Systematic debugging with persistent state
+- **Summary**: Systematic debugging with persistent state; delegates to `gsd-t headless --debug-loop` after 2 failed in-context fix attempts
 - **Auto-invoked**: No
-- **Creates**: Debug session state
+- **Creates**: Debug session state, `.gsd-t/debug-state.jsonl` (when delegating to headless loop)
 - **Use when**: Tracking down a bug methodically
 
+### headless --debug-loop
+- **Summary**: Compaction-proof automated test-fix-retest loop — each iteration is a fresh `claude -p` session; a cumulative ledger (`.gsd-t/debug-state.jsonl`) preserves all hypothesis/fix/learning history; anti-repetition preamble prevents retrying failed approaches
+- **Auto-invoked**: Yes — by `execute`, `test-sync`, `verify`, `debug`, and `wave` after 2 failed in-context fix attempts
+- **Flags**: `--max-iterations=N` (default 20), `--test-cmd=CMD`, `--fix-scope=PATTERN`, `--json`, `--log`
+- **Escalation**: sonnet (iterations 1–5) → opus (6–15) → STOP with diagnostic summary (16–20)
+- **Exit codes**: `0` pass · `1` max iterations · `2` compaction error · `3` process error · `4` needs human
+- **Creates**: `.gsd-t/debug-state.jsonl`, optional `.gsd-t/headless-{ts}.log`
+- **Use when**: Running automated fix loops in CI, or delegated from in-context commands that exhausted fix attempts
+
 ### promote-debt
 - **Summary**: Convert techdebt.md items into milestones
 - **Auto-invoked**: No

package/commands/gsd-t-integrate.md

@@ -62,6 +62,22 @@ If rolled-back domains exist, report them to the user (or if Level 3: log to `.g
 
 ## Step 3: Wire Integration Points
 
+**Stack Rules Detection (before spawning subagent):**
+Run via Bash to detect project stack and collect matching rules:
+`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; fi`
+
+If STACK_RULES is non-empty, append to the subagent prompt:
+```
+## Stack Rules (MANDATORY — violations fail this task)
+
+{STACK_RULES}
+
+These standards have the same enforcement weight as contract compliance.
+Violations are task failures, not warnings.
+```
+
+If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
+
 Work through each integration point in `integration-points.md`. If integration work spans multiple domains with independent tasks, use the **task-level dispatch pattern** (per fresh-dispatch-contract.md): spawn one Task subagent per integration task, passing only the relevant contracts, the specific integration point to wire, and summaries from prior integration tasks (max 5, 10-20 lines each). This prevents context accumulation across integration tasks.
 
 **Multi-domain integration merging**: If integration work itself requires merging domain outputs that weren't merged during execute (e.g., domains executed in separate waves and integration needs to combine them), use the Sequential Merge Protocol from `.gsd-t/contracts/worktree-isolation-contract.md`:
@@ -126,7 +142,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 +195,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`)