@tekyzinc/gsd-t 2.45.11 → 2.50.10

package/commands/gsd-t-quick.md

@@ -12,12 +12,29 @@ To give this task a fresh context window and prevent compaction during consecuti
 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}`
 
+**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.
+
 Spawn a fresh subagent using the Task tool:
 ```
 subagent_type: general-purpose
 prompt: "You are running gsd-t-quick for this request: {$ARGUMENTS}
 Working directory: {current project root}
-Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-quick starting at Step 1."
+Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-quick starting at Step 1.
+{STACK_RULES block — if non-empty, append the ## Stack Rules section defined above; omit if empty}"
 ```
 
 After subagent returns — run via Bash:
@@ -133,6 +150,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 +163,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
@@ -275,7 +296,11 @@ After each task completes:
 2. **If new code paths have zero test coverage: write tests NOW** — do not defer
 3. Run ALL affected unit/integration tests
 4. Run ALL affected Playwright E2E tests
-5. If failures: fix immediately (up to 2 attempts) before continuing
+5. If failures: fix immediately (up to 2 attempts) before continuing. If both attempts fail:
+   1. Write failure context to `.gsd-t/debug-state.jsonl` via `node -e "require('./bin/debug-ledger.js').appendEntry('.', {iteration:1,timestamp:new Date().toISOString(),test:'test-sync-failure',error:'2 in-context fix attempts exhausted',hypothesis:'see test-coverage.md',fix:'n/a',fixFiles:[],result:'STILL_FAILS',learning:'delegating to headless debug-loop',model:'sonnet',duration:0})"`
+   2. Log: "Delegating to headless debug-loop (2 in-context attempts exhausted)"
+   3. Run: `gsd-t headless --debug-loop --max-iterations 10`
+   4. Exit code 0 → tests pass, continue; 1/4 → log to `.gsd-t/deferred-items.md`, report failure; 3 → report error
 6. If E2E specs are missing for new features/modes/flows: **create them NOW**, not later
 7. If E2E specs need updating for changed behavior: update them before continuing
 8. **No task is complete until its tests exist and pass** — do not move to the next task with test gaps

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)
 ```
@@ -308,7 +309,12 @@ Update `.gsd-t/progress.md`:
 
 **All Levels**:
 - VERIFIED or CONDITIONAL PASS → **Auto-invoke complete-milestone** (see Step 8 below). Completing a verified milestone is mechanical — there is no judgment call that benefits from user review.
-- FAIL → **Level 3**: Auto-execute remediation tasks (up to 2 fix attempts). If still failing after 2 attempts, STOP and report to user. **Level 1–2**: Return to execute phase for remediation tasks.
+- FAIL → **Level 3**: Auto-execute remediation tasks (up to 2 fix attempts). If still failing after 2 attempts:
+  1. Write failure context to `.gsd-t/debug-state.jsonl` via `node -e "require('./bin/debug-ledger.js').appendEntry('.', {iteration:1,timestamp:new Date().toISOString(),test:'verify-remediation',error:'2 in-context fix attempts exhausted',hypothesis:'see verify-report.md',fix:'n/a',fixFiles:[],result:'STILL_FAILS',learning:'delegating to headless debug-loop',model:'sonnet',duration:0})"`
+  2. Log: "Delegating to headless debug-loop (2 in-context attempts exhausted)"
+  3. Run: `gsd-t headless --debug-loop --max-iterations 10`
+  4. Exit code 0 → re-run verification; 1/4 → log to `.gsd-t/deferred-items.md`, STOP and report to user; 3 → report error
+  **Level 1–2**: Return to execute phase for remediation tasks.
 
 ## Document Ripple
 

package/commands/gsd-t-wave.md

@@ -52,6 +52,22 @@ If `.gsd-t/graph/meta.json` exists, the code graph is available for all phases.
 
 For each phase, spawn the agent like this:
 
+**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.
+
 **OBSERVABILITY LOGGING (MANDATORY) — repeat for every phase 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}`
@@ -84,6 +100,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 +176,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:
@@ -234,6 +281,11 @@ If the user interrupts or a phase agent fails:
 - Report blocking issues to user
 
 **Level 3**: Spawn a remediation agent to fix blocking issues, then re-spawn impact agent. Max 2 attempts.
+If both attempts fail:
+1. Write failure context to `.gsd-t/debug-state.jsonl` via `node -e "require('./bin/debug-ledger.js').appendEntry('.', {iteration:1,timestamp:new Date().toISOString(),test:'impact-remediation',error:'2 in-context fix attempts exhausted',hypothesis:'see impact-report.md',fix:'n/a',fixFiles:[],result:'STILL_FAILS',learning:'delegating to headless debug-loop',model:'sonnet',duration:0})"`
+2. Log: "Delegating to headless debug-loop (2 in-context attempts exhausted)"
+3. Run: `gsd-t headless --debug-loop --max-iterations 10`
+4. Exit code 0 → continue; 1/4 → log to `.gsd-t/deferred-items.md`, report to user; 3 → report error
 **Level 1–2**: Ask user for direction.
 
 ### If tests fail during execute:
@@ -245,6 +297,11 @@ If the user interrupts or a phase agent fails:
 - Read verify report for failure details
 
 **Level 3**: Spawn remediation agent, then re-spawn verify agent. Max 2 attempts.
+If both attempts fail:
+1. Write failure context to `.gsd-t/debug-state.jsonl` via `node -e "require('./bin/debug-ledger.js').appendEntry('.', {iteration:1,timestamp:new Date().toISOString(),test:'verify-remediation',error:'2 in-context fix attempts exhausted',hypothesis:'see verify-report.md',fix:'n/a',fixFiles:[],result:'STILL_FAILS',learning:'delegating to headless debug-loop',model:'sonnet',duration:0})"`
+2. Log: "Delegating to headless debug-loop (2 in-context attempts exhausted)"
+3. Run: `gsd-t headless --debug-loop --max-iterations 10`
+4. Exit code 0 → re-spawn verify agent; 1/4 → log to `.gsd-t/deferred-items.md`, report to user; 3 → report error
 **Level 1–2**: Ask user for direction.
 
 ## Why Agent-Per-Phase

package/docs/GSD-T-README.md

@@ -100,9 +100,10 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-discuss` | Multi-perspective design exploration | In wave |
 | `/user:gsd-t-plan` | Create atomic task lists per domain (tasks auto-split to fit one context window) | In wave |
 | `/user:gsd-t-impact` | Analyze downstream effects | In wave |
-| `/user:gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning | In wave |
+| `/user:gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning, stack rules injection | 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 |
@@ -223,6 +224,88 @@ your-project/
 
 ---
 
+## Stack Rules Engine
+
+GSD-T auto-detects your project's tech stack and injects mandatory best-practice rules into subagent prompts at execute-time. This ensures stack conventions are enforced at the same weight as contract compliance — violations are task failures, not warnings.
+
+### How It Works
+
+1. At subagent spawn time, GSD-T reads project manifest files to detect the active stack(s).
+2. Universal rules (`templates/stacks/_security.md`) are **always** injected.
+3. Stack-specific rules are injected when the corresponding stack is detected.
+4. Rules are appended to the subagent prompt as a `## Stack Rules (MANDATORY)` section.
+
+### Stack Detection
+
+| Project File | Detected Stack |
+|---|---|
+| `package.json` with `"react"` | React |
+| `package.json` with `"typescript"` or `tsconfig.json` | TypeScript |
+| `package.json` with `"express"`, `"fastify"`, `"hono"`, or `"koa"` | Node API |
+| `requirements.txt` or `pyproject.toml` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+
+### Commands That Inject Stack Rules
+
+`gsd-t-execute`, `gsd-t-quick`, `gsd-t-integrate`, `gsd-t-wave`, `gsd-t-debug`
+
+### Extending
+
+Drop a `.md` file into `templates/stacks/` to add a new stack. Files prefixed with `_` are universal (always injected). Files without a prefix are stack-specific (injected only when detected). If the `stacks/` directory is missing, detection skips silently — no error.
+
+---
+
+## Headless Mode
+
+Run GSD-T non-interactively in CI/CD pipelines or automated workflows.
+
+### headless exec
+
+```bash
+gsd-t headless verify --json --timeout=1200  # Run verify non-interactively
+gsd-t headless execute --json                # Execute tasks without interactive prompts
+```
+
+### headless query
+
+```bash
+gsd-t headless query status   # Project state — no LLM, <100ms
+gsd-t headless query domains  # Domain list with status
+```
+
+### headless debug-loop
+
+Compaction-proof automated test-fix-retest cycles. Each iteration runs as a separate `claude -p` session with fresh context. A cumulative debug ledger (`.gsd-t/debug-state.jsonl`) preserves all hypothesis/fix/learning history across sessions. An anti-repetition preamble is injected into each session to prevent retrying failed approaches.
+
+```bash
+gsd-t headless --debug-loop [--max-iterations=N] [--test-cmd=CMD] [--fix-scope=PATTERN] [--json] [--log]
+```
+
+**Flags:**
+
+| Flag               | Default | Description |
+|--------------------|---------|-------------|
+| `--max-iterations` | 20      | Hard ceiling on iterations |
+| `--test-cmd`       | (auto)  | Override test command (auto-detected from project) |
+| `--fix-scope`      | (all)   | Limit fix scope to specific files or patterns |
+| `--json`           | false   | Structured JSON output after each iteration |
+| `--log`            | false   | Write per-iteration logs to `.gsd-t/` |
+
+**Escalation tiers:**
+
+| Iterations | Model  | Behavior |
+|------------|--------|----------|
+| 1–5        | sonnet | Standard debug — one fix per session |
+| 6–15       | opus   | Deeper reasoning — reads full ledger, may attempt multi-file fixes |
+| 16–20      | STOP   | Write full diagnostic summary, present to user, exit code 4 |
+
+**Exit codes:** `0` all tests pass · `1` max iterations reached · `2` compaction error · `3` process error · `4` needs human decision
+
+**Auto-escalation from commands:** `gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-debug`, and `gsd-t-wave` delegate to `--debug-loop` automatically after 2 failed in-context fix attempts.
+
+---
+
 ## Key Principles
 
 1. **Contracts are the source of truth.** Code implements contracts, not the other way around. If code and contract disagree, fix one or the other — never leave them inconsistent.

package/docs/architecture.md

@@ -16,7 +16,7 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 - **Purpose**: Install, update, diagnose, and manage GSD-T across projects
 - **Location**: `bin/gsd-t.js` (1,798 lines, 90+ functions, all ≤ 30 lines)
 - **Dependencies**: Node.js built-ins only (fs, path, os, child_process, https, crypto)
-- **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog, graph (index/status/query), headless (exec/query)
+- **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog, graph (index/status/query), headless (exec/query/--debug-loop)
 - **Organization**: Configuration → Guard section → Helpers → Heartbeat → Commands → Install/Update → Init → Status → Uninstall → Update-All → Doctor → Register → Update Check → Help → Main dispatch
 - **All functions ≤ 30 lines** (M6 refactoring). Largest: `doRegister()` at 30 lines, `summarize()` at 30 lines.
 
@@ -78,6 +78,14 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 - **Exit codes**: 0=success, 1=verify-fail, 2=context-budget-exceeded, 3=error, 4=blocked-needs-human
 - **CI/CD examples**: `docs/ci-examples/github-actions.yml` (GitHub Actions), `docs/ci-examples/gitlab-ci.yml` (GitLab CI)
 
+### Compaction-Proof Debug Loop (M29 — complete)
+- **bin/debug-ledger.js** (193 lines): JSONL-based debug persistence layer. 6 exported functions: `readLedger`, `appendEntry`, `compactLedger`, `generateAntiRepetitionPreamble`, `getLedgerStats`, `clearLedger`. Ledger file: `.gsd-t/debug-state.jsonl` (11-field schema per entry). Compaction triggers at 50KB — haiku session condenses history, last 5 raw entries preserved. Anti-repetition preamble lists all STILL_FAILS hypotheses, current narrowing direction, and tests still failing. Zero external deps.
+- **doHeadlessDebugLoop(flags)**: External iteration manager in `bin/gsd-t.js`. Runs test-fix-retest as separate `claude -p` sessions — each session starts with zero accumulated context. Escalation tiers: sonnet (iterations 1-5), opus (6-15), STOP with full diagnostic output (16-20). `--max-iterations N` flag (default 20) enforced by external process.
+- **parseDebugLoopFlags(args)**: Extracts `--max-iterations`, `--test-cmd`, `--fix-scope`, `--json`, `--log` from args. Defaults: maxIterations=20.
+- **getEscalationModel(iteration)**: Returns "sonnet" for 1-5, "opus" for 6-15, null for 16-20 (STOP tier).
+- **Command integration**: execute, wave, test-sync, verify, debug all delegate fix-retest loops to `gsd-t headless --debug-loop` after 2 in-context fix attempts.
+- **Exit codes (debug-loop specific)**: 0=all tests pass (ledger cleared), 1=max iterations reached, 3=process error, 4=escalation stop (needs human)
+
 ### Graph Engine (M20 — complete)
 - **`bin/graph-store.js`** (147 lines): File-based graph storage in `.gsd-t/graph/`. 8 JSON files (index, calls, imports, contracts, requirements, tests, surfaces, meta). Read/write operations, MD5 file hashing for incremental indexing, staleness detection. Zero external deps. Note: no symlink protection (TD-099).
 - **`bin/graph-parsers.js`** (327 lines): Language-specific entity parsers. JS/TS: function declarations, arrow functions, classes, methods, imports (ES/CJS), exports. Python: def/class/import. Regex-based (no Tree-sitter). Returns `{ entities, imports, calls }`.

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,16 @@
 | 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 |
+| REQ-053 | Debug Ledger Protocol — structured JSONL ledger (.gsd-t/debug-state.jsonl) persists hypothesis/fix/learning entries across debug sessions. Supports read, append, compact (at 50KB), anti-repetition preamble generation, and clear. | P1 | complete | M29: bin/debug-ledger.js, test/debug-ledger.test.js (46 tests) |
+| REQ-054 | Headless Debug-Loop — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions with fresh context each. External loop controller (pure Node.js, zero AI context). Escalation tiers: sonnet 1-5, opus 6-15, STOP 16-20. --max-iterations enforced externally. | P1 | complete | M29: bin/gsd-t.js headless extension, test/headless-debug-loop.test.js (37 tests) |
+| REQ-055 | Anti-Repetition Preamble — each debug-loop iteration injects a preamble listing all failed hypotheses, current narrowing direction, and tests still failing. Prevents repeat of eliminated approaches. | P1 | complete | M29: bin/debug-ledger.js generateAntiRepetitionPreamble, test/debug-ledger.test.js |
+| REQ-056 | Debug-Loop Command Integration — execute, wave, test-sync, verify, and debug commands delegate to headless debug-loop after 2 in-context fix attempts fail. Preserves existing try-twice behavior for quick fixes. | P1 | complete | M29: 5 command files (execute, debug, wave, test-sync, verify) |
+| REQ-057 | Stack Rule Templates — best practice rule files in `templates/stacks/` for React, TypeScript, and Node.js API. Each file follows a standard structure (mandatory framing, numbered sections, GOOD/BAD examples, verification checklist) and stays under 200 lines. Universal templates (`_` prefix) always injected; stack-specific templates injected when detected. | P1 | complete | M30: templates/stacks/ (4 files: _security.md, react.md, typescript.md, node-api.md) |
+| REQ-058 | Stack Detection Engine — auto-detect project tech stack from manifest files (package.json, requirements.txt, go.mod, Cargo.toml) at subagent spawn time. Match detected stacks against available templates. Inject matched rules into subagent prompts with mandatory enforcement framing. Resilient: skip silently if no templates exist or no matches found. | P1 | complete | M30: 5 command files (execute, quick, integrate, wave, debug) |
+| REQ-059 | Stack Rule QA Enforcement — QA subagent prompts include stack rule compliance validation. Stack rule violations have the same severity as contract violations — they fail the task, not warn. Report format includes "Stack rules: compliant/N violations". | P1 | complete | M30: execute QA prompt + all 5 commands |
 
 ## Technical Requirements
 
@@ -163,6 +173,29 @@
 **Orphaned requirements**: None — all M27 REQs mapped to tasks.
 **Unanchored tasks**: global-metrics Task 4 (tests) and cross-project-sync Task 3 (tests) are QA infrastructure supporting REQ-043 through REQ-045. command-extensions Task 4 (reference docs) supports Pre-Commit Gate compliance.
 
+## Requirements Traceability (updated by plan phase — M29)
+
+| REQ-ID  | Requirement Summary                                          | Domain               | Task(s)        | Status  |
+|---------|--------------------------------------------------------------|----------------------|----------------|---------|
+| REQ-053 | Debug Ledger Protocol — JSONL ledger with read/write/compact | debug-state-protocol | Task 1, 2, 3   | complete |
+| REQ-054 | Headless Debug-Loop — external loop controller               | headless-loop        | Task 1, 2, 3   | complete |
+| REQ-055 | Anti-Repetition Preamble — failed hypothesis injection       | debug-state-protocol, headless-loop | dsp Task 2, hl Task 2 | complete |
+| REQ-056 | Debug-Loop Command Integration — delegate after 2 failures   | command-integration  | Task 1, 2      | complete |
+
+**Orphaned requirements**: None — all M29 REQs mapped to tasks.
+**Unanchored tasks**: debug-state-protocol Task 3 (tests) and headless-loop Task 3 (tests) are QA infrastructure supporting REQ-053 through REQ-055. command-integration Task 3 (reference docs) supports Pre-Commit Gate compliance.
+
+## Requirements Traceability (updated by plan phase — M30)
+
+| REQ-ID  | Requirement Summary                                          | Domain               | Task(s)        | Status  |
+|---------|--------------------------------------------------------------|----------------------|----------------|---------|
+| REQ-057 | Stack Rule Templates — react.md, typescript.md, node-api.md  | stack-templates      | Task 1, 2, 3   | complete |
+| REQ-058 | Stack Detection Engine — auto-detect + prompt injection      | command-integration  | Task 1, 2      | complete |
+| REQ-059 | Stack Rule QA Enforcement — QA validates compliance          | command-integration  | Task 1, 2      | complete |
+
+**Orphaned requirements**: None — all M30 REQs mapped to tasks.
+**Unanchored tasks**: command-integration Task 3 (tests) is QA infrastructure supporting REQ-057 through REQ-059. command-integration Task 4 (reference docs) supports Pre-Commit Gate compliance.
+
 ---
 
 ## M17: Scan Visual Output — Feature Specification

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.50.10",
+  "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": {