@tekyzinc/gsd-t 2.46.11 → 2.50.11

package/commands/gsd-t-execute.md

@@ -119,6 +119,70 @@ 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. Local overrides in `.gsd-t/stacks/` take precedence over global templates — if a project has `.gsd-t/stacks/react.md`, it replaces the global `react.md` for that project.
+
+```bash
+GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t
+STACKS_DIR="$GSD_T_DIR/templates/stacks"
+LOCAL_STACKS=".gsd-t/stacks"
+STACK_RULES=""
+
+# Helper: read local override if exists, else global
+_sf() { local n=$(basename "$1"); [ -f "$LOCAL_STACKS/$n" ] && cat "$LOCAL_STACKS/$n" || cat "$1"; }
+
+# Helper: append a stack file to STACK_RULES
+_add() { [ -f "$STACKS_DIR/$1" ] && STACK_RULES="${STACK_RULES}$(_sf "$STACKS_DIR/$1")"$'\n\n'; }
+
+if [ -d "$STACKS_DIR" ]; then
+  # Universal rules (_ prefix — always injected)
+  for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(_sf "$f")"$'\n\n'; done
+
+  # Package.json-based detection
+  if [ -f "package.json" ]; then
+    grep -q '"react-native"' package.json 2>/dev/null && _add react-native.md
+    grep -q '"react"' package.json 2>/dev/null && ! grep -q '"react-native"' package.json 2>/dev/null && _add react.md
+    grep -q '"next"' package.json 2>/dev/null && _add nextjs.md
+    grep -q '"vue"' package.json 2>/dev/null && _add vue.md
+    (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && _add typescript.md
+    grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && _add node-api.md && _add rest-api.md
+    grep -q '"tailwindcss"' package.json 2>/dev/null && _add tailwind.md
+    grep -q '"vite"' package.json 2>/dev/null && _add vite.md
+    grep -q '"@supabase/supabase-js"' package.json 2>/dev/null && _add supabase.md
+    grep -q '"firebase"' package.json 2>/dev/null && _add firebase.md
+    grep -qE '"(graphql|@apollo/client|urql)"' package.json 2>/dev/null && _add graphql.md
+    grep -q '"zustand"' package.json 2>/dev/null && _add zustand.md
+    grep -q '"@reduxjs/toolkit"' package.json 2>/dev/null && _add redux.md
+    grep -q '"neo4j-driver"' package.json 2>/dev/null && _add neo4j.md
+    grep -qE '"(pg|prisma|drizzle-orm|knex)"' package.json 2>/dev/null && _add postgresql.md
+  fi
+
+  # File-based detection (no package.json needed)
+  ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "Pipfile" ]) && _add python.md
+  ([ -f "requirements.txt" ] && grep -q "psycopg" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "psycopg" pyproject.toml 2>/dev/null) && _add postgresql.md
+  ([ -f "requirements.txt" ] && grep -q "neo4j" requirements.txt 2>/dev/null) && _add neo4j.md
+  [ -f "pubspec.yaml" ] && _add flutter.md
+  [ -f "Dockerfile" ] && _add docker.md
+  [ -d ".github/workflows" ] && _add github-actions.md
+  ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
+  [ -f "go.mod" ] && _add go.md
+  [ -f "Cargo.toml" ] && _add rust.md
+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 +214,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:
@@ -212,7 +279,9 @@ Execute the task above:
         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)"'
+     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}
@@ -223,8 +292,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,

package/commands/gsd-t-help.md

@@ -65,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
@@ -252,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
@@ -339,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-init.md

@@ -54,6 +54,8 @@ Skip the copy (step 2) silently if the target already exists.
 │   └── .gitkeep
 ├── domains/
 │   └── .gitkeep
+├── stacks/
+│   └── README.md
 ├── events/
 ├── backlog.md
 ├── backlog-settings.md
@@ -62,6 +64,11 @@ Skip the copy (step 2) silently if the target already exists.
 └── qa-issues.md
 ```
 
+Create `.gsd-t/stacks/` directory with a `README.md` explaining the override mechanism:
+- This folder holds project-specific overrides of global stack rule files
+- If a file with the same name as a global stack file exists here, it replaces the global version
+- Folder stays empty until the developer explicitly adds overrides
+
 Create `.gsd-t/events/` directory (empty — populated at runtime by heartbeat and event writer).
 
 Create `token-log.md` with header row:

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`:

package/commands/gsd-t-quick.md

@@ -12,12 +12,67 @@ 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. Local overrides in `.gsd-t/stacks/` take precedence over global templates.
+
+```bash
+GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t
+STACKS_DIR="$GSD_T_DIR/templates/stacks"
+LOCAL_STACKS=".gsd-t/stacks"
+STACK_RULES=""
+_sf() { local n=$(basename "$1"); [ -f "$LOCAL_STACKS/$n" ] && cat "$LOCAL_STACKS/$n" || cat "$1"; }
+_add() { [ -f "$STACKS_DIR/$1" ] && STACK_RULES="${STACK_RULES}$(_sf "$STACKS_DIR/$1")"$'\n\n'; }
+if [ -d "$STACKS_DIR" ]; then
+  for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(_sf "$f")"$'\n\n'; done
+  if [ -f "package.json" ]; then
+    grep -q '"react-native"' package.json 2>/dev/null && _add react-native.md
+    grep -q '"react"' package.json 2>/dev/null && ! grep -q '"react-native"' package.json 2>/dev/null && _add react.md
+    grep -q '"next"' package.json 2>/dev/null && _add nextjs.md
+    grep -q '"vue"' package.json 2>/dev/null && _add vue.md
+    (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && _add typescript.md
+    grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && _add node-api.md && _add rest-api.md
+    grep -q '"tailwindcss"' package.json 2>/dev/null && _add tailwind.md
+    grep -q '"vite"' package.json 2>/dev/null && _add vite.md
+    grep -q '"@supabase/supabase-js"' package.json 2>/dev/null && _add supabase.md
+    grep -q '"firebase"' package.json 2>/dev/null && _add firebase.md
+    grep -qE '"(graphql|@apollo/client|urql)"' package.json 2>/dev/null && _add graphql.md
+    grep -q '"zustand"' package.json 2>/dev/null && _add zustand.md
+    grep -q '"@reduxjs/toolkit"' package.json 2>/dev/null && _add redux.md
+    grep -q '"neo4j-driver"' package.json 2>/dev/null && _add neo4j.md
+    grep -qE '"(pg|prisma|drizzle-orm|knex)"' package.json 2>/dev/null && _add postgresql.md
+  fi
+  ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "Pipfile" ]) && _add python.md
+  ([ -f "requirements.txt" ] && grep -q "psycopg" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "psycopg" pyproject.toml 2>/dev/null) && _add postgresql.md
+  ([ -f "requirements.txt" ] && grep -q "neo4j" requirements.txt 2>/dev/null) && _add neo4j.md
+  [ -f "pubspec.yaml" ] && _add flutter.md
+  [ -f "Dockerfile" ] && _add docker.md
+  [ -d ".github/workflows" ] && _add github-actions.md
+  ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
+  [ -f "go.mod" ] && _add go.md
+  [ -f "Cargo.toml" ] && _add rust.md
+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:

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

@@ -296,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

@@ -309,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}`
@@ -265,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:
@@ -276,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,7 +100,7 @@ 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 |
@@ -224,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/requirements.md

@@ -61,6 +61,13 @@
 | 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
 
@@ -166,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.46.11",
+  "version": "2.50.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",

package/templates/CLAUDE-global.md

@@ -339,7 +339,7 @@ This applies during: `gsd-t-execute`, `gsd-t-quick`, `gsd-t-integrate`, `gsd-t-w
 
 ## Prime Rule
 KEEP GOING. Only stop for:
-1. Unrecoverable errors after 2 fix attempts
+1. Unrecoverable errors after 2 fix attempts (delegate to `gsd-t headless --debug-loop` first — only stop if exit code 4)
 2. Ambiguity that fundamentally changes project direction
 3. Milestone completion (checkpoint for user review)
 4. Destructive actions (see Destructive Action Guard above — ALWAYS stop)
@@ -431,7 +431,7 @@ BEFORE reporting "done" or presenting a summary:
 - NEVER pause to show verification steps — execute them.
 - NEVER ask "should I continue?" — just continue.
 - NEVER summarize what you're "about to do" — just do it.
-- IF a test fails, fix it immediately (up to 2 attempts) before reporting.
+- IF a test fails, fix it immediately (up to 2 attempts) before reporting. If both attempts fail, delegate to `gsd-t headless --debug-loop` before stopping.
 
 ## Autonomy Levels
 
@@ -583,6 +583,23 @@ Also pad all cell values in a column to the width of the widest value:
 ```
 
 
+## Stack Rules Engine
+
+GSD-T auto-detects project tech stack at subagent spawn time and injects mandatory best-practice rules into the subagent prompt.
+
+**Detection sources**: `package.json` (React, TypeScript, Node API), `requirements.txt`/`pyproject.toml` (Python), `go.mod` (Go), `Cargo.toml` (Rust).
+
+**Universal rules**: Templates prefixed with `_` (e.g., `_security.md`) are **always** injected, regardless of stack.
+
+**Stack-specific rules**: Injected only when the matching stack is detected (e.g., `react.md` when `"react"` is in `package.json`).
+
+**Enforcement**: Stack rule violations have the same weight as contract violations — they are task failures, not warnings.
+
+**Extensible**: Drop a `.md` file into `templates/stacks/` in the GSD-T package to add rules for a new stack. If the directory is missing, detection skips silently.
+
+**Commands that inject stack rules**: `gsd-t-execute`, `gsd-t-quick`, `gsd-t-integrate`, `gsd-t-wave`, `gsd-t-debug`.
+
+
 # Recovery After Interruption
 
 When resuming work (new session or after /clear):