0fbe1d899e
* chore(#191): migrate gsd-sdk query call sites to gsd-tools query Retiring the gsd-sdk shim. gsd-tools.cjs already accepts `query` as a meta-prefix (gsd-tools query <command>), so this is a behavior-preserving 1:1 swap across the runtime reference prompts, the graphify hook's commit-detection gate, and two bin/lib comment/message references. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(#191): remove vestigial gsd-sdk shim code from installer + projection The gsd-sdk shim was already not wired up (no gsd-sdk bin in package.json; buildWindowsShimTriple had zero call sites). Remove the dead code: - shell-command-projection.cjs: buildWindowsShimTriple + formatSdkPathDiagnostic (+ their now-unused PACKAGE_NAME import) and exports - install.js: the re-export wrappers + imports, the #3406 stale-standalone-sdk detection (detectStaleStandaloneSdk/formatStaleStandaloneSdkWarning + its global-install call site), and the exports Preserved (retained, not gsd-sdk): buildCodexHookWindowsShimIR (#3426) — only its comments referenced the gsd-sdk pattern; reworded. Also kept the homePathCoveredByRc 'reopen your shell' branch in maybeSuggestPathExport — its logic is bin-dir-agnostic, only the message mentioned gsd-sdk; reworded to use the actual bin dir. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(#191): update tests for retired gsd-sdk shim - bug-3441/bug-3442: drop the formatSdkPathDiagnostic / buildWindowsShimTriple assertions (functions removed); retained PATH-action + drift-guard tests stay - bug-505: remove the 'still exported' assertions for detectStaleStandaloneSdk / formatStaleStandaloneSdkWarning / the shim contract surface (#505 kept them; #191 removes them) - graphify-auto-update: migrate the hook-dispatch inputs gsd-sdk query commit -> gsd-tools query commit to match the migrated commit hook Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(#191): point active docs at gsd-tools query (gsd-sdk shim retired) Update the user/agent-facing docs (AGENTS, COMMANDS, CONFIGURATION, USER-GUIDE, ship-pr-body-sections) that presented gsd-sdk query as a current command to gsd-tools query. Historical docs (ADRs, PRDs, release notes) left untouched. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(#191): correct state.load vs state.json description for gsd-tools query Adversarial-review (codex) finding: the migrated USER-GUIDE line claimed both 'gsd-tools query state.json' and 'state.load' resolve to the frontmatter-rebuild handler. Verified they don't — state.load returns the CJS load shape (config + state_raw + flags), state.json returns the frontmatter shape. Both are available via gsd-tools query; corrected the text to say so. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(#191): add changeset for gsd-sdk shim retirement Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
86 lines
5.4 KiB
Markdown
86 lines
5.4 KiB
Markdown
# Verify-Work — MVP Mode UAT Framing
|
|
|
|
> Loaded by `verify-work` workflow and `gsd-verifier` agent only when the phase under verification has `mode: mvp` in ROADMAP.md. Reframes UAT generation from technical checks to user-flow walk-throughs.
|
|
|
|
## Core rule
|
|
|
|
**Show expected, ask if reality matches** — same philosophy as standard verify-work (from `workflows/verify-work.md`). The MVP-mode change is WHAT gets shown:
|
|
|
|
- **Standard verify-work:** "The API endpoint at /users/register returns 201 with the new user's ID." → user confirms.
|
|
- **MVP verify-work:** "Open the registration page. Fill in 'name', 'email', 'password'. Click Submit. You should see your dashboard with your name in the header." → user confirms.
|
|
|
|
The user-flow form mirrors what a real user does: open, fill, click, see. No HTTP verbs, no JSON shapes, no error codes.
|
|
|
|
## When this framing applies
|
|
|
|
The framing fires when:
|
|
- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-tools query roadmap.get-phase --pick mode`).
|
|
- AND the phase has a user-story-formatted goal (set by `/gsd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
|
|
|
|
If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `references/planner-mvp-mode.md`).
|
|
|
|
## Generated UAT script structure under MVP mode
|
|
|
|
The UAT script generated by `verify-work` under MVP mode has THREE sections, in this exact order:
|
|
|
|
### 1. User-flow walk-through (always first, always required)
|
|
|
|
Derive ordered steps from the phase's user-story goal:
|
|
|
|
1. The first step opens the entry point ("Open the app", "Navigate to /register", "Run `gsd mvp-phase 1`").
|
|
2. Each subsequent step is one user action: fill, click, type, observe.
|
|
3. The final step asserts the user-visible outcome from the `[outcome]` clause of the user story.
|
|
|
|
Format each step as: "**Step N: [action]** — Expected: [what the user should see]". The user responds with one of:
|
|
- `yes` / `y` / `next` / empty → step passes
|
|
- Anything else → step is logged as an issue, and the script halts (do not proceed to step N+1 with a broken N).
|
|
|
|
If ALL user-flow steps pass, advance to section 2. If any step fails, the verdict is FAIL — do not run technical checks.
|
|
|
|
### 2. Technical checks (only if section 1 passes)
|
|
|
|
After the user flow passes, run the technical checks that would normally run in non-MVP mode:
|
|
- API endpoint schema verification (if the phase shipped APIs)
|
|
- Error state behavior (4xx, 5xx codes; invalid input handling)
|
|
- Edge cases (empty data, large data, concurrent requests if applicable)
|
|
- Cross-browser / cross-runtime checks (if applicable)
|
|
|
|
These are the same checks `verify-work` would run without MVP mode — just deferred until the user flow proves the slice actually works for a user.
|
|
|
|
### 3. Coverage check (always last, always required)
|
|
|
|
Verify that the user-story `[outcome]` clause is observably true in the codebase:
|
|
- If the outcome is "I can access my dashboard", verify a dashboard route exists and renders for an authenticated user.
|
|
- If the outcome is "I can bulk-import contacts", verify the import path produces persisted records.
|
|
|
|
Coverage is a goal-backward check: "did this phase deliver what its user story promised?" — sourced from the existing `gsd-verifier` agent's goal-backward methodology, narrowed to the user story.
|
|
|
|
## Anti-patterns to reject under MVP mode
|
|
|
|
- **Lead with technical checks.** "Step 1: GET /api/users/me returns 200." Reject. The user does not see API endpoints. Reorder so a user action comes first.
|
|
- **Schema-as-feature.** "User has a `name` field on the User model." Reject. The user does not see database fields. Express the same check as a user-visible outcome ("the user's name appears in the dashboard header").
|
|
- **Skip user flow because the test passed.** The unit test passing in CI is not evidence that the user flow works. The user-flow walk-through is mandatory under MVP mode even when all unit tests are green.
|
|
|
|
## Compatibility with existing verify-work philosophy
|
|
|
|
The "show expected, ask if reality matches" model is preserved. The user still types `yes` / `next` / empty to advance. The UAT.md state file format is unchanged. Only the WHAT changes — under MVP mode, the "expected" is a user-visible outcome rather than a technical assertion.
|
|
|
|
## Output: VERIFICATION.md changes under MVP mode
|
|
|
|
The `gsd-verifier` agent produces `VERIFICATION.md`. Under MVP mode, the report adds a top-level "User Flow Coverage" section that maps each step of the user story to evidence in the codebase:
|
|
|
|
```markdown
|
|
## User Flow Coverage
|
|
|
|
User story: «As a new user, I want to register and log in, so that I can access my dashboard.»
|
|
|
|
| Step | Expected | Evidence | Status |
|
|
|------|----------|----------|--------|
|
|
| Register | Form at /register accepts name/email/password | src/app/register/page.tsx:12 (form component) | ✓ |
|
|
| Submit | Persists user, redirects to /dashboard | src/api/register/route.ts:34 (db.insert + redirect) | ✓ |
|
|
| See dashboard | Dashboard page renders, shows user's name | src/app/dashboard/page.tsx:8 (greeting line) | ✓ |
|
|
| Outcome | "Access my dashboard" — user lands on a populated page | dashboard route + greeting both verified above | ✓ |
|
|
```
|
|
|
|
Standard technical-check sections of VERIFICATION.md remain (API verification, error handling, etc.) but are appended below "User Flow Coverage", not above.
|