speckit Phase 3 -> Phase 4 advances without enforcing ! task spec:render

[MScottAdams]

Summary

In deft/strategies/speckit.md, Phase 3 ("Plan / HOW") declares a ! MUST step:

Post-Phase 3: Render for Review

• ! Run task spec:render to produce SPECIFICATION.md as a read-only rendered export
• ! SPECIFICATION.md is for human review only -- vbrief/specification.vbrief.json remains the source of truth

But nothing in the workflow contract prevents the agent from advancing directly to Phase 4 (Tasks) without invoking task spec:render. There is no transition criterion that gates Phase 3 -> Phase 4 on the render having occurred.

In auto-pilot / yolo mode this gap is invisible to the user: the agent silently writes vbrief/specification.vbrief.json, writes vbrief/plan.vbrief.json, and reports "documents complete" -- with no SPECIFICATION.md ever produced.

Reproduction

1. Greenfield project with vbrief/PROJECT-DEFINITION.vbrief.json declaring Strategy: speckit.
2. Run an agent through speckit Phases 1-4 in yolo mode.
3. Observe: vbrief/specification.vbrief.json and vbrief/plan.vbrief.json are written, but SPECIFICATION.md does not exist anywhere.
4. The agent reports completion with no warning.

Why #398 does not catch this

PR #400 / issue #398 added auto-render hooks (task check staleness warning, deft-directive-pre-pr quality-loop render). Both have explicit "skip silently if absent" semantics:

"Warn if present, ignore if absent." -- the files don't exist, the user hasn't opted into them, no nag.

That was a deliberate design choice for solo-iteration ergonomics (#398 Recommendation), not an oversight. But it means the first render is always a manual step, and speckit.md puts that step on the agent, and nothing enforces the agent doing it.

Proposed fix (sketch)

Pick one or combine:

1. Phase 3 transition criterion (cheapest): add to speckit.md Phase 3 Transition Criteria a ! clause: "SPECIFICATION.md exists and its hash matches the current vbrief/specification.vbrief.json narratives". The deft-directive-build / Phase 4 entry would refuse to proceed otherwise.

2. Skill enforcement: have deft-directive-setup (or whatever skill drives speckit) call task spec:render itself at the Phase 3 -> Phase 4 boundary instead of asking the agent to remember.

3. Workflow doc clarification: change the "Post-Phase 3: Render for Review" section from agent-instruction prose into a numbered transition gate, mirroring how Phase 2's approval gate is structured.

Related

• Auto-render PRD.md and SPECIFICATION.md when specification.vbrief.json changes #398 / PR fix(scripts,skills): auto-render staleness warning + pre-pr auto-render step (#398) #400 -- design ancestor (auto-render hooks). This issue is a follow-up gap from Auto-render PRD.md and SPECIFICATION.md when specification.vbrief.json changes #398's deliberate "skip silently if absent" decision.
• docs(readme): Document Generation table missing task prd:render row #420 -- related README discoverability gap for task prd:render.

Severity

Workflow-correctness bug in the speckit strategy. Doesn't corrupt data (vBRIEF is source of truth) but defeats Phase 3's stated review intent. Reproducible 100% on greenfield + yolo.

Discovered

During greenfield walkthrough of speckit Phase 1-4 in agentic mode.

[MScottAdams]

Companion issue: #433 (Greenfield projects can complete speckit with no PRD/SPECIFICATION export and no prompt).

[MScottAdams]

Related: #434 (spec_render.py is item-centric and silently drops all speckit narratives) -- makes any fix here hollow until the renderer itself is fixed.

[MScottAdams]

Related: #435 (spec rendering does not aggregate scope vBRIEFs) and #436 (speckit Phase 4 collides with plan.vbrief.json definition).

[MScottAdams]

Tracked by #437 (v0.20 vBRIEF-centric rendering is half-shipped).

[MScottAdams]

Decision (2026-04-20): reject hash gate, widen scope to all spec-generating strategies

Per tracker #437 deep-think walkthrough. The originally-proposed hash-match transition gate (Option 1 from the issue body) is rejected — it solves the wrong problem. The failure mode is "render was never invoked," not "render is out of sync with narratives." A hash gate is still agent-facing prose and can be ignored the same way the current ! is ignored.

Adopted fix: skill-driven Exit Commands contract (all 5 spec-generating strategies)

Audit expands beyond speckit once we look at every spec-generating strategy:

• interview.md:358 — ✓ ! SPECIFICATION.md has been rendered via task spec:render lives inside Transition Criteria. Structurally correct.
• yolo.md — ✓ inherits interview.
• enterprise.md:38, 77 — ✓ ! markers plus formal approval gates (Gate 1 / Gate 3).
• rapid.md:51 — ⚠ ! Run task spec:render exists but sits in a flow step, not Transition Criteria.
• speckit.md:127-130 — ✗ ! Run task spec:render lives in a parallel "Post-Phase 3: Render for Review" subsection outside Transition Criteria. This is what speckit Phase 3 -> Phase 4 advances without enforcing ! task spec:render #432 originally flagged.

Two of five have the structural gap. Fix uniformly, not just in speckit.

Scope of change

1. Introduce strategy-level ## Exit Commands contract. Every strategy phase may declare a list of commands that the driving skill MUST execute before advancing to the next phase. Commands declared here are authoritative; prose requests in flow steps are informational only.
2. Patch speckit.md Phase 3 and rapid.md Step 3 to move task spec:render into their Transition Criteria (mirroring interview's structure) and also list it under ## Exit Commands.
3. Update skills/deft-directive-setup/SKILL.md to read the current strategy's ## Exit Commands for the current phase and run each command before declaring the phase complete. Refuse to advance if any command returns non-zero.
4. Doc consistency pass across all 5 spec-generating strategies so the render-enforcement shape is identical (Transition Criteria entry + Exit Commands listing).

Explicitly dropped from scope

• No hash gate.
• No new scripts/spec_render_check.py or similar.
• No canonicalization spec (json.dumps(sort_keys=True, ...) hashing, sidecar hash files, etc.).
• No "staleness between Phase 3 and Phase 4" guard — deft-directive-pre-pr Phase 3b already unconditionally re-renders at PR time, which is when staleness actually matters.

Why B.2 (strategy-local Exit Commands) over B.1 (hard-code in setup skill)

B.2 scales to every current and future strategy by keeping the render-responsibility in the strategy .md. The driving skill runs commands mechanically; it doesn't need to know which strategies render and which don't. B.1 would hard-code task spec:render into deft-directive-setup for specific phase transitions — brittle, strategy-coupled, and requires edits to the skill every time a new strategy adds a post-phase command.

Preparatory strategies are deliberately not affected

map / discuss / research / bdd / roadmap (type: preparatory) do not generate SPECIFICATION.md by design. They produce structured-context vBRIEFs in vbrief/proposed/ that flow into a spec-generating strategy via the chaining gate (interview.md:21-88). Their outputs are already captured as JSON; rendering them to markdown is a separate concern and is deferred to a post-GA follow-up issue.

GA status

Blocker for v0.20.0 GA. Lands alongside #433 (PRD-render explicitness audit), #434 (renderer narrative pass), #435 (lifecycle aggregator), and #436 (speckit Opt 1 + migrator).

[MScottAdams]

Risk-8b amendment (2026-04-20): spec-generating strategies gain completedStrategies append step

Per the #437 walkthrough. Small scope addition to this issue's strategy-wide audit.

What's added

All 5 spec-generating strategies gain an explicit "on completion, update completedStrategies in plan.vbrief.json" step, mirroring the pattern already documented for preparatory strategies.

Why

Preparatory strategies all declare this in their docs:

• strategies/bdd.md:77-79
• strategies/map.md:88-91
• strategies/research.md:87-91
• strategies/discuss.md:88-92

Example (research.md:87-91):

! On completion, register artifacts in ./vbrief/plan.vbrief.json:

• Update completedStrategies: increment runCount for "research", append artifact path
• Append the path to the flat artifacts array

Spec-generating strategies (interview, yolo, speckit, rapid, enterprise) don't have this step. The chaining gate at strategies/interview.md:60-61 reads completedStrategies for run-count annotations, but only preparatory-strategy runs are recorded. A user who runs map → research → speckit sees map (ran 1×), research (ran 1×) on re-entry to the chaining gate, but no record of speckit having run.

Asymmetric and invisible to the user.

Addition to each strategy doc

Each of the 5 spec-generating strategies gains a step of the shape:

! On completion, register artifacts in ./vbrief/plan.vbrief.json:

• Update completedStrategies: increment runCount for "<strategy-name>", append artifact paths (e.g. SPECIFICATION.md, PRD.md where applicable)
• Append each artifact path to the flat artifacts array

Placement:

• interview.md -- at the end of the Acceptance Gate section, before re-entry to chaining gate.
• yolo.md -- inherited from interview; add explicit note that Johnbot performs the update silently.
• speckit.md -- new section at the end of Phase 5 (Implement) OR explicitly at session completion, before re-entering the chaining gate.
• rapid.md -- at the end of Step 5 (Evaluate).
• enterprise.md -- at the end of Stage 4 (Build) / Gate 3 (Specification Approval).

Integration with the Exit Commands contract (this issue's main decision)

Each strategy's new "register completedStrategies" step becomes part of the Exit Commands contract -- it's a deterministic post-phase action that the driving skill (deft-directive-setup) mechanically runs, not agent-facing prose. Ideally a small task (e.g. task strategy:record <name>) or skill invocation performs the append; alternatively the agent performs it as an Exit Command.

Consistency guarantee

Once this lands, every strategy run (preparatory or spec-generating) appends to completedStrategies. The chaining gate's run-count annotations become complete and symmetric.

No separate follow-up issue

Folded into this issue's strategy-wide audit. Small prose addition per strategy plus one Exit-Commands wiring decision.

GA status

Part of #432. Lands in the same PR as the render-enforcement audit and Exit Commands contract.