msd-core/gsd-core/references/execute-mvp-tdd.md

Execute-Phase — MVP+TDD Gate (Runtime Enforcement)

Loaded by execute-phase workflow and gsd-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 gsd-core/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 /gsd 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 /gsd execute-phase, or override with /gsd 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 gsd-core/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 gsd-core/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.