ec7e49a64c
* test(#3576): gate shipped reference citations on the canonical resolvable form Failing-first gate for #3576: a backticked bare references/<name>.md cite resolves from no install location (agents, workflows, and references all install where a bare relative references/ path is dead). The gate walks the runtime-loaded trees the issue prescribes, strips @~/ include tokens PER-TOKEN (a line-skip guard would miss a bare cite sharing a line with an include — the issue-named trap), pins the genuinely relative ../ href and canonical forms as non-offenders, and checks canonical cite targets exist. 43 offenders today across 19 files. * fix(#3576): repair all 43 dead references/ cites to the canonical resolvable form Every backticked bare references/<name>.md cite across the 19 shipped files rewritten to gsd-core/references/<name>.md — the form every required_reading block and @~/ include already uses, and the only form that resolves from any install location. All 20 cited targets verified to exist; the one genuinely relative href (plan-phase.md's ../references/mvp-concepts.md) is untouched (the repair is backtick-anchored). Growth acks: new fragment for the three first-time paths, #3206-pattern appends to the five fragments already naming the other grown files (two ack sources may never name the same path). execute-phase.md lands at 93,391/93,400 and gsd-executor.md at 49,150/49,152 — exactly the issue's projections; every repair fits. * fix(#3576): drop stale default.md growth ack (nested modes file is hash-attributed, not growth-ratcheted) Review finding: the emitted-attribution ratchet covers only top-level workflows/ + agents/ files; discuss-phase/modes/default.md's delta is source-attributed, so acknowledging its growth is a stale entry the differential lane fails on. * chore(#3576): add changeset fragment * chore(#3576): backfill changeset pr number --------- Co-authored-by: sim <sim@local>
82 lines
4.8 KiB
Markdown
82 lines
4.8 KiB
Markdown
# 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.
|