msd-core/docs/how-to/verify-and-ship.md

How to verify and ship a phase

Goal: Walk executed work through user acceptance testing, diagnose and fix any failures, then open a pull request with an auto-generated body.

Prerequisites: The phase has been executed and has SUMMARY.md files. If execution is not yet done, see Execute a phase.

---

Run user acceptance testing

/msd-verify-work 1

MSD reads the phase's SUMMARY.md files, extracts user-observable deliverables, and walks you through them one at a time. For each checkpoint it presents what should happen and asks whether reality matches.

• yes / y / empty → pass, move to next test
• Anything else → recorded as an issue, severity inferred from your description

You never need to categorise severity — MSD infers it from your words ("crashes" → blocker, "doesn't work" → major, "looks off" → cosmetic).

Progress is written to .planning/phases/01-<name>/01-UAT.md and survives a /clear. If a session is interrupted, re-run /msd-verify-work 1 and MSD offers to resume from the last checkpoint.

---

When failures are found: auto-diagnose and fix planning

If any tests report issues, MSD proceeds automatically:

1. Diagnoses root causes — spawns parallel debug agents, one per issue, and updates UAT.md with root causes.
2. Plans gap closure — spawns a msd-planner in gap-closure mode, which reads UAT.md (with diagnoses) and writes new PLAN.md files.
3. Verifies the fix plans — spawns a msd-plan-checker to ensure the plans are executable. If issues are found, the planner and checker iterate up to three times.
4. Presents next step — when plans pass the checker:

Plans verified and ready for execution.

`/clear` then `/msd-execute-phase 1 --gaps-only`

Run the suggested command to apply fixes, then re-run /msd-verify-work 1 to confirm everything passes.

---

When all tests pass: ship the phase

Once all UAT tests pass (or if this is your first run and no issues are found), the phase is marked complete in ROADMAP.md and STATE.md automatically.

/msd-ship 1

MSD runs preflight checks (verification status, clean working tree, branch, remote, gh CLI authentication), pushes the branch, and creates a PR:

/msd-ship 1          # Ready-for-review PR
/msd-ship 1 --draft  # Draft PR — useful when more phases will follow

The PR body is assembled from planning artefacts automatically:

• Phase goal from ROADMAP.md
• Per-plan summaries from SUMMARY.md files and their key files
• Requirements addressed (REQ-IDs)
• Verification status from VERIFICATION.md
• Key decisions from STATE.md

No manual body writing required.

---

Optional: code review before or after shipping

/msd-ship does not run a code review automatically, but you can slot one in at any point:

Before verification (catches issues before UAT):

/msd-code-review 1          # Standard review
/msd-code-review 1 --fix    # Review then auto-fix Critical + Warning findings

After the PR is open (to gate on quality before merge):

/msd-code-review 1 --depth=deep  # Cross-file analysis including import graphs

See Set up cross-AI review to configure Antigravity, Codex, or other reviewers for plan review earlier in the cycle.

---

Optional: create a clean PR branch

If your branch contains .planning/ commits that you do not want reviewers to see:

/msd-pr-branch          # Filter against main
/msd-pr-branch develop  # Filter against develop

/msd-pr-branch creates a new branch with only code changes — planning artefact commits are excluded. Run this before /msd-ship if your team's review policy excludes planning noise.

---

Why a passing verification can turn stale

A *-VERIFICATION.md reporting status: passed is re-checked, not cached, every time a completion gate reads it. Two ways it can flip to status: stale:

• Content fingerprint (default for new reports). The verifier records a digest of every input its verdict covers — the phase's PLAN.md/SUMMARY.md files, mapped requirements, and implementation files in the change set. If any of those files changes, disappears, or becomes unreadable after verification, the gate recomputes the digest, finds a mismatch, and reports stale. This catches drift even when nothing touches SUMMARY.md itself — an implementation file edited after verification is enough.
• Legacy SUMMARY-mtime check. A *-VERIFICATION.md written before this fingerprint existed has no digest to check, so it keeps the older rule: stale when a SUMMARY.md is newer than the verification report.

Either way, stale routes the same as any other incomplete state: re-run /msd-verify-work 1 before shipping.

The content fingerprint hashes covered files exactly as they sit on disk, including line endings. A checkout without a .gitattributes eol=lf rule pinning text files to LF (a Windows checkout with core.autocrlf=true, for example) can report stale on unchanged content — fix with a .gitattributes eol=lf rule, not by treating it as drift.

---

Closing a milestone

If this was the last phase in the milestone, run the milestone audit and archive it:

/msd-audit-milestone      # Verify all requirements shipped
/msd-complete-milestone   # Archive, create git tag

/msd-complete-milestone is the natural next step after the PR merges. See the The phase loop for how verification and shipping fit into the full project lifecycle.

---

Related

• Execute a phase
• Set up cross-AI review
• The phase loop
• Commands