@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/references/context-budget.md

@@ -1,49 +1,85 @@
-# Context Budget Rules
-
-Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
-
-See also: `references/universal-anti-patterns.md` for the complete set of universal rules.
-
----
-
-## Universal Rules
-
-Every workflow that spawns agents or reads significant content must follow these rules:
-
-1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them
-2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead
-3. **Read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`:
-   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
-   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
-4. **Delegate** heavy work to subagents -- the orchestrator routes, it doesn't execute
-5. **Proactive warning**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
-
-## Read Depth by Context Window
-
-| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
-|---------------|------------------------|------------|-----------------|------------------------|
-| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
-| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
-
-**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
-
-## Context Degradation Tiers
-
-Monitor context usage and adjust behavior accordingly:
-
-| Tier | Usage | Behavior |
-|------|-------|----------|
-| PEAK | 0-30% | Full operations. Read bodies, spawn multiple agents, inline results. |
-| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. |
-| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. |
-| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. |
-
-## Context Degradation Warning Signs
-
-Quality degrades gradually before panic thresholds fire. Watch for these early signals:
-
-- **Silent partial completion** -- agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
-- **Increasing vagueness** -- agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
-- **Skipped steps** -- agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
-
-When delegating to agents, the orchestrator cannot verify semantic correctness of agent output -- only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+# Context Budget Rules
+
+Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
+
+See also: `references/universal-anti-patterns.md` for the complete set of universal rules.
+
+---
+
+## Universal Rules
+
+Every workflow that spawns agents or reads significant content must follow these rules:
+
+1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them
+2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead
+3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
+4. **Delegate** heavy work to subagents -- the orchestrator routes, it doesn't execute
+5. **Proactive warning**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window`. If the field is absent, treat as 200k (conservative default).
+
+## Context Degradation Tiers
+
+Monitor context usage and adjust behavior accordingly:
+
+| Tier | Usage | Behavior |
+|------|-------|----------|
+| PEAK | 0-30% | Full operations. Read bodies, spawn multiple agents, inline results. |
+| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. |
+| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. |
+| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. |
+
+## Context Degradation Warning Signs
+
+Quality degrades gradually before panic thresholds fire. Watch for these early signals:
+
+- **Silent partial completion** -- agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** -- agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** -- agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output -- only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
+## MCP Tool Schema Cost (Harness Concern)
+
+Every enabled MCP server injects its tool schema into **every turn**, regardless of whether you call any of its tools. Heavyweight servers can cost 20k+ tokens per turn each — often dwarfing whatever SDD itself can save through `model_profile` tuning. This is a Claude Code harness concern, not a SDD concern: SDD does **not** manage MCP enablement. The toggle lives in `.claude/settings.json` under `enabledMcpjsonServers` and `disabledMcpjsonServers`.
+
+### Why this is the biggest cost lever you don't own
+
+Tool schemas count against the same context budget as model context, prompts, and conversation history. If a project has 5 unused MCP servers averaging 5k tokens of schema each, every turn pays a 25k-token tax before the assistant reads a single project file. Trimming MCPs has a **multiplier effect** that compounds with whichever `model_profile` you've chosen — every-turn overhead drops regardless of which model is in use.
+
+### Pre-Phase MCP Audit
+
+Before starting a long phase (especially `/sdd:execute-phase`, `/sdd:plan-phase`, or anything that fans out across many subagents), run this audit:
+
+- [ ] **Browser / playwright tools enabled?** If this phase has no UI work, disable them. They're among the heaviest per-turn schemas.
+- [ ] **Platform-specific tools enabled?** Mac-tools / Windows-tools / OS-specific helpers should be disabled when not actively needed for the phase at hand.
+- [ ] **Cross-project / stale MCPs?** Servers added for a different project that are still enabled here. These are often forgotten and pay a per-turn tax for zero benefit.
+- [ ] **Duplicate or shadow servers?** Two MCPs offering similar tools (e.g. two different filesystem helpers). Keep one.
+
+Each item disabled removes its schema from every subsequent turn for the rest of the session.
+
+### How to toggle
+
+The keys live in `.claude/settings.json` (project) or `~/.claude/settings.json` (global) — **not** in `.planning/config.json`:
+
+```json
+{
+  "enabledMcpjsonServers": ["context7"],
+  "disabledMcpjsonServers": ["playwright", "mac-tools"]
+}
+```
+
+Either list works — `enabledMcpjsonServers` is an explicit allow-list, `disabledMcpjsonServers` is a block-list against the default. See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for the canonical reference; this section just flags it as a context-budget lever SDD users routinely overlook.
+
+### Composition with model_profile
+
+Trimming MCPs and tuning `model_profile` are independent levers that **compound**. Disabling a 25k-token MCP saves 25k per turn whether you're running `quality` (opus everywhere) or `budget` (sonnet/haiku); the savings are additive, not in lieu of model tuning. Don't pick one — do both, and audit MCPs first because the per-turn savings show up immediately and stack across every subagent the orchestrator spawns.

package/sdd/references/continuation-format.md

@@ -7,7 +7,7 @@ Standard format for presenting next steps after completing a command or workflow
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **{identifier}: {name}** — {one-line description}
 
@@ -24,6 +24,9 @@ Standard format for presenting next steps after completing a command or workflow
 ---
 ```
 
+> If `project_code` is not set in the init context, omit the project identity suffix:
+> `## ▶ Next Up` (no ` — [CODE] Title`).
+
 ## Format Rules
 
 1. **Always show what it is** — name + description, never just a command path
@@ -32,6 +35,7 @@ Standard format for presenting next steps after completing a command or workflow
 4. **`/clear` first** — always show `/clear` before the command so users run it in the correct order
 5. **"Also available" not "Other options"** — sounds more app-like
 6. **Visual separators** — `---` above and below to make it stand out
+7. **Project identity in heading** — include `[PROJECT_CODE] PROJECT_TITLE` from init context so handoffs are self-identifying across sessions. If `project_code` is not set, omit the suffix entirely (just `## ▶ Next Up`)
 
 ## Variants
 
@@ -40,13 +44,13 @@ Standard format for presenting next steps after completing a command or workflow
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 
 `/clear` then:
 
-`/sdd-execute-phase 2`
+`/sdd:execute-phase 2`
 
 ---
 
@@ -64,14 +68,14 @@ Add note that this is the last plan and what comes after:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 <sub>Final plan in Phase 2</sub>
 
 `/clear` then:
 
-`/sdd-execute-phase 2`
+`/sdd:execute-phase 2`
 
 ---
 
@@ -87,19 +91,19 @@ Add note that this is the last plan and what comes after:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase 2: Authentication** — JWT login flow with refresh tokens
 
 `/clear` then:
 
-`/sdd-plan-phase 2`
+`/sdd:plan-phase 2`
 
 ---
 
 **Also available:**
-- `/sdd-discuss-phase 2` — gather context first
-- `/sdd-research-phase 2` — investigate unknowns
+- `/sdd:discuss-phase 2` — gather context first
+- `/sdd:plan-phase --research-phase 2` — investigate unknowns
 - Review roadmap
 
 ---
@@ -116,19 +120,19 @@ Show completion status before next action:
 
 3/3 plans executed
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
 `/clear` then:
 
-`/sdd-plan-phase 3`
+`/sdd:plan-phase 3`
 
 ---
 
 **Also available:**
-- `/sdd-discuss-phase 3` — gather context first
-- `/sdd-research-phase 3` — investigate unknowns
+- `/sdd:discuss-phase 3` — gather context first
+- `/sdd:plan-phase --research-phase 3` — investigate unknowns
 - Review what Phase 2 built
 
 ---
@@ -141,17 +145,17 @@ When there's no clear primary action:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
 `/clear` then one of:
 
-**To plan directly:** `/sdd-plan-phase 3`
+**To plan directly:** `/sdd:plan-phase 3`
 
-**To discuss context first:** `/sdd-discuss-phase 3`
+**To discuss context first:** `/sdd:discuss-phase 3`
 
-**To research unknowns:** `/sdd-research-phase 3`
+**To research unknowns:** `/sdd:plan-phase --research-phase 3`
 
 ---
 ```
@@ -165,13 +169,13 @@ When there's no clear primary action:
 
 All 4 phases shipped
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Start v1.1** — questioning → research → requirements → roadmap
 
 `/clear` then:
 
-`/sdd-new-milestone`
+`/sdd:new-milestone`
 
 ---
 ```
@@ -214,7 +218,7 @@ Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with slidi
 ## To Continue
 
 Run `/clear`, then paste:
-/sdd-execute-phase 2
+/sdd:execute-phase 2
 ```
 
 User has no idea what 02-03 is about.
@@ -222,7 +226,7 @@ User has no idea what 02-03 is about.
 ### Don't: Missing /clear explanation
 
 ```
-`/sdd-plan-phase 3`
+`/sdd:plan-phase 3`
 
 Run /clear first.
 ```
@@ -242,7 +246,7 @@ Sounds like an afterthought. Use "Also available:" instead.
 
 ```
 ```
-/sdd-plan-phase 3
+/sdd:plan-phase 3
 ```
 ```
 

package/sdd/references/debugger-philosophy.md

@@ -0,0 +1,76 @@
+# Debugger Philosophy
+
+Evergreen debugging disciplines — applies across every bug, every language, every system. Loaded by `sdd-debugger` via `@file` include.
+
+## User = Reporter, Claude = Investigator
+
+The user knows:
+- What they expected to happen
+- What actually happened
+- Error messages they saw
+- When it started / if it ever worked
+
+The user does NOT know (don't ask):
+- What's causing the bug
+- Which file has the problem
+- What the fix should be
+
+Ask about experience. Investigate the cause yourself.
+
+## Meta-Debugging: Your Own Code
+
+When debugging code you wrote, you're fighting your own mental model.
+
+**Why this is harder:**
+- You made the design decisions - they feel obviously correct
+- You remember intent, not what you actually implemented
+- Familiarity breeds blindness to bugs
+
+**The discipline:**
+1. **Treat your code as foreign** - Read it as if someone else wrote it
+2. **Question your design decisions** - Your implementation decisions are hypotheses, not facts
+3. **Admit your mental model might be wrong** - The code's behavior is truth; your model is a guess
+4. **Prioritize code you touched** - If you modified 100 lines and something breaks, those are prime suspects
+
+**The hardest admission:** "I implemented this wrong." Not "requirements were unclear" - YOU made an error.
+
+## Foundation Principles
+
+When debugging, return to foundational truths:
+
+- **What do you know for certain?** Observable facts, not assumptions
+- **What are you assuming?** "This library should work this way" - have you verified?
+- **Strip away everything you think you know.** Build understanding from observable facts.
+
+## Cognitive Biases to Avoid
+
+| Bias | Trap | Antidote |
+|------|------|----------|
+| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What would prove me wrong?" |
+| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating any |
+| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise |
+| **Sunk Cost** | Spent 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" |
+
+## Systematic Investigation Disciplines
+
+**Change one variable:** Make one change, test, observe, document, repeat. Multiple changes = no idea what mattered.
+
+**Complete reading:** Read entire functions, not just "relevant" lines. Read imports, config, tests. Skimming misses crucial details.
+
+**Embrace not knowing:** "I don't know why this fails" = good (now you can investigate). "It must be X" = dangerous (you've stopped thinking).
+
+## When to Restart
+
+Consider starting over when:
+1. **2+ hours with no progress** - You're likely tunnel-visioned
+2. **3+ "fixes" that didn't work** - Your mental model is wrong
+3. **You can't explain the current behavior** - Don't add changes on top of confusion
+4. **You're debugging the debugger** - Something fundamental is wrong
+5. **The fix works but you don't know why** - This isn't fixed, this is luck
+
+**Restart protocol:**
+1. Close all files and terminals
+2. Write down what you know for certain
+3. Write down what you've ruled out
+4. List new hypotheses (different from before)
+5. Begin again from Phase 1: Evidence Gathering

package/sdd/references/decimal-phase-calculation.md

@@ -6,7 +6,7 @@ Calculate the next decimal phase number for urgent insertions.
 
 ```bash
 # Get next decimal phase after phase 6
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase next-decimal 6
+sdd-sdk query phase.next-decimal 6
 ```
 
 Output:
@@ -32,13 +32,13 @@ With existing decimals:
 ## Extract Values
 
 ```bash
-DECIMAL_PHASE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick next)
-BASE_PHASE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick base_phase)
+DECIMAL_PHASE=$(sdd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(sdd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
 ```
 
 Or with --raw flag:
 ```bash
-DECIMAL_PHASE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
+DECIMAL_PHASE=$(sdd-sdk query phase.next-decimal "${AFTER_PHASE}" --raw)
 # Returns just: 06.1
 ```
 
@@ -56,7 +56,7 @@ DECIMAL_PHASE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase next-decimal "$
 Decimal phase directories use the full decimal number:
 
 ```bash
-SLUG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
+SLUG=$(sdd-sdk query generate-slug "$DESCRIPTION" --raw)
 PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
 mkdir -p "$PHASE_DIR"
 ```

package/sdd/references/doc-conflict-engine.md

@@ -0,0 +1,91 @@
+# Doc Conflict Engine
+
+Shared conflict-detection contract for workflows that ingest external content into `.planning/` (e.g., `/sdd:import`, `/sdd:ingest-docs`). Defines the report format, severity semantics, and safety-gate behavior. The specific checks that populate each severity bucket are workflow-specific and defined by the calling workflow.
+
+---
+
+## Severity Semantics
+
+- **[BLOCKER]** — Unsafe to proceed. The workflow MUST exit without writing any destination files. Used for contradictions of locked decisions, missing prerequisites, and impossible targets.
+- **[WARNING]** — Ambiguous or partially overlapping. The workflow MUST surface the warning and obtain explicit user approval before writing. Never auto-approve.
+- **[INFO]** — Informational only. No gate; no user prompt required. Included in the report for transparency.
+
+---
+
+## Report Format
+
+Plain-text, never markdown tables (no `|---|`). The report is rendered to the user verbatim.
+
+```
+## Conflict Detection Report
+
+### BLOCKERS ({N})
+
+[BLOCKER] {Short title}
+  Found: {what the incoming content says}
+  Expected: {what existing project context requires}
+  → {Specific action to resolve}
+
+### WARNINGS ({N})
+
+[WARNING] {Short title}
+  Found: {what was detected}
+  Impact: {what could go wrong}
+  → {Suggested action}
+
+### INFO ({N})
+
+[INFO] {Short title}
+  Note: {relevant information}
+```
+
+Every entry requires `Found:` plus one of `Expected:`/`Impact:`/`Note:` plus (for BLOCKER/WARNING) a `→` remediation line.
+
+---
+
+## Safety Gate
+
+**If any [BLOCKER] exists:**
+
+Display:
+```
+SDD > BLOCKED: {N} blockers must be resolved before {operation} can proceed.
+```
+
+Exit WITHOUT writing any destination files. The gate must hold regardless of WARNING/INFO counts.
+
+**If only WARNINGS and/or INFO (no blockers):**
+
+Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
+
+**If the report is empty (no entries in any bucket):**
+
+Proceed silently or display `SDD > No conflicts detected.` Either is acceptable; workflows choose based on verbosity context.
+
+---
+
+## Workflow Responsibilities
+
+Each workflow that consumes this contract must define:
+
+1. **Its own check list per bucket** — which conditions are BLOCKER vs WARNING vs INFO. These are domain-specific (plan ingestion checks are not doc ingestion checks).
+2. **The loaded context** — what it reads (ROADMAP.md, PROJECT.md, REQUIREMENTS.md, CONTEXT.md, intel files) before running checks.
+3. **The operation noun** — substituted into the BLOCKED banner (`import`, `ingest`, etc.).
+
+The workflow MUST NOT:
+
+- Introduce new severity levels beyond BLOCKER/WARNING/INFO
+- Render the report as a markdown table
+- Write any destination file when BLOCKERs exist
+- Auto-approve past WARNINGs without user input
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+
+- Use markdown tables (`|---|`) in the conflict report — use plain-text labels as shown above
+- Bypass the safety gate when BLOCKERs exist — no exceptions for "minor" blockers
+- Fold WARNINGs into INFO to skip the approval prompt — if user input is needed, it is a WARNING
+- Re-invent severity labels per workflow — the three-level taxonomy is fixed

package/sdd/references/domain-probes.md

@@ -1,6 +1,6 @@
 # Domain-Aware Probing Patterns
 
-Shared reference for `/sdd-begin`, `/sdd-discuss-phase`, and domain exploration workflows.
+Shared reference for `/sdd-begin`, `/sdd:discuss-phase`, and domain exploration workflows.
 
 When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist -- pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
 

package/sdd/references/execute-mvp-tdd.md

@@ -0,0 +1,81 @@
+# Execute-Phase — MVP+TDD Gate (Runtime Enforcement)
+
+> Loaded by `execute-phase` workflow and `sdd-executor` agent only when **both** `MVP_MODE=true` AND `TDD_MODE=true` for the phase. Defines the runtime gate that blocks behavior-adding tasks until a failing-test commit exists.
+
+## When this gate fires
+
+- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `references/planner-mvp-mode.md`).
+- `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config).
+- The current task being executed has `tdd="true"` in its `<task>` frontmatter (set by the planner per Phase 1).
+- The task's `<behavior>` block lists at least one expected behavior.
+
+If any of these is false, the gate is inactive — execution proceeds normally.
+
+## What the gate checks
+
+For each task gated by MVP+TDD, the executor MUST verify (before running the implementation step):
+
+1. **A failing-test commit exists.** Search git log on the current branch for a commit matching `test({phase}-{plan})` whose subject mentions the same plan as the current task. The commit must touch a test file (`*.test.*`, `*.spec.*`, `tests/**`).
+2. **The test was actually red.** The commit message body or the executor's recent shell history must show the test failed when first run. Acceptable evidence:
+   - Commit message contains `RED:` prefix or `(RED)` tag
+   - Recent terminal output shows `FAIL` or non-zero exit on the new test before any implementation commit
+3. **No implementation commit yet.** No `feat({phase}-{plan})` commit may exist for the same plan ID before the failing-test commit.
+
+If any check fails, the gate trips.
+
+## What "behavior-adding task" means
+
+A task is behavior-adding when:
+- Its frontmatter has `tdd="true"` AND
+- Its `<behavior>` block names at least one user-visible outcome (not a config-only or doc-only task) AND
+- Its `<files>` list includes at least one source file (not exclusively docs/tests/config files such as `*.md`, `*.json`, `*.test.*`, `*.spec.*`, `*.yml`, `*.yaml`, `*.toml`, `*.ini`, `.env*`)
+
+Pure documentation, configuration, or test-only tasks are skipped by this gate even when both modes are active.
+
+## What happens when the gate trips
+
+The executor MUST:
+
+1. Halt before running the task's implementation step.
+2. Emit a structured halt report:
+
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    MVP+TDD GATE TRIPPED — Plan {plan_id}, Task {task_id}
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Reason: {missing_red_commit | red_commit_not_failing | feat_before_test}
+
+   Behavior expected to be tested:
+   - {first behavior bullet}
+
+   Required next step:
+   1. Write a failing test for the behavior above.
+   2. Commit it as: test({phase}-{plan}): {short description}
+   3. Re-run /sdd execute-phase
+   ```
+
+3. Exit the current execution wave cleanly. Do NOT roll back any prior commits in the same wave.
+4. Update `STATE.md` with `last_gate_trip: {plan_id}/{task_id}` so the user can resume after writing the test.
+
+## Escalation: end-of-phase TDD review under MVP+TDD
+
+The existing end-of-phase TDD review (in `workflows/execute-phase.md`'s `tdd_review_checkpoint` step) is normally **advisory** — it surfaces gate violations but does not block phase completion.
+
+Under MVP+TDD, escalate this to **blocking**:
+- If any TDD plan is missing a RED or GREEN commit, the executor MUST refuse to mark the phase complete.
+- The user is shown the same review table, but the verdict line reads:
+  > "Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under MVP+TDD. Resolve and re-run /sdd execute-phase, or override with `/sdd execute-phase {phase} --force-mvp-gate` to ship anyway."
+
+The `--force-mvp-gate` flag is documented but not introduced by this plan — it is the escape hatch the spec mentions; if the user later builds it, the workflow already references the contract.
+
+## What this gate does NOT do
+
+- It does not enforce REFACTOR commits. REFACTOR remains optional (per `references/tdd.md`).
+- It does not check test quality (the test could be trivially passing). That's the planner's job.
+- It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
+- It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
+
+## Compatibility with existing TDD discipline
+
+This gate is additive to `references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.