a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
138 lines
5.7 KiB
Markdown
138 lines
5.7 KiB
Markdown
# 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](execute-a-phase.md).
|
|
|
|
---
|
|
|
|
## Run user acceptance testing
|
|
|
|
```bash
|
|
/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.
|
|
|
|
```bash
|
|
/msd-ship 1
|
|
```
|
|
|
|
MSD runs preflight checks (verification status, clean working tree, branch, remote, `gh` CLI authentication), pushes the branch, and creates a PR:
|
|
|
|
```bash
|
|
/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):
|
|
|
|
```bash
|
|
/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):
|
|
|
|
```bash
|
|
/msd-code-review 1 --depth=deep # Cross-file analysis including import graphs
|
|
```
|
|
|
|
See [Set up cross-AI review](set-up-cross-ai-review.md) 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:
|
|
|
|
```bash
|
|
/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:
|
|
|
|
```bash
|
|
/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](../explanation/the-phase-loop.md) for how verification and shipping fit into the full project lifecycle.
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [Execute a phase](execute-a-phase.md)
|
|
- [Set up cross-AI review](set-up-cross-ai-review.md)
|
|
- [The phase loop](../explanation/the-phase-loop.md)
|
|
- [Commands](../COMMANDS.md)
|