5869febb16
* enhance(#4155): invalidate verification results when covered inputs change readVerificationStatus() now recomputes a deterministic sha256 fingerprint over a VERIFICATION.md's declared covered_files (phase PLAN/SUMMARY, requirements, implementation files in the verified change set) and returns stale on any mismatch, fail-closed when a covered file is missing, unreadable, or escapes the project root. Legacy reports with no fingerprint metadata keep the prior SUMMARY-mtime staleness check unchanged. The verifier computes covered_digest via the new verification.fingerprint CLI command rather than by hand, since a digest is deterministic math, not an LLM-estimated value. * chore(#4155): backfill fork PR number in changeset * fix(#4155): trim gsd-verifier.md fingerprint instructions to fit LARGE tier byte cap * fix(#4155): address CodeRabbit findings on fingerprint fail-closed behavior Partial fingerprint metadata (one of covered_files/covered_digest present, the other missing or malformed) now fails closed to stale instead of silently downgrading to the legacy mtime-only check. computeCoveredDigest also canonicalizes with realpathSync before re-confining, so an in-root symlink whose target escapes the project root can no longer produce a matching digest. gsd-verifier.md restores the completeness requirement and checklist item trimmed by the earlier size-budget fix, within the LARGE tier byte cap. * chore(#4155): acknowledge gsd-verifier.md growth for the #4155 fingerprint instructions Emitted-Drift-Ack-Growth: gsd-verifier.md — adds the covered-input fingerprint instructions and frontmatter fields the #4155 verification staleness mechanism requires; trimmed to stay within the LARGE tier byte cap * fix(#4155): address gemini adversarial review findings computeCoveredDigest now threads the caller-supplied opts.fs seam through its confinement and read paths instead of always using raw node:fs — a caller like planning-inspect.cts's containmentEnforcingVerificationFs (GAP 2, #2790 follow-up) was silently bypassed for covered-input reads. The project-root anchor itself still canonicalizes through real fs (it is a trusted value the caller derived, not attacker-influenced covered-input data); only per-file candidate reads go through the injected seam. Covered-file paths are now canonicalized (./ prefixes, redundant slashes, internal .. segments) before becoming dedup/sort/hash keys or confinement subjects — closes both a spurious-stale false positive (two spellings of the same file hashing differently) and a confinement gap (an internal .. segment that doesn't start the string). gsd-verifier.md now states covered-file paths are project-root-relative, not phaseDir-relative, closing an ambiguity that would have made a real verifier agent's first fingerprint invocation fail closed. defaultFsImpl's methods now late-bind through fs.<method> rather than capturing function references at module load — the earlier direct-capture form was invisible to existing tests' t.mock.method(fs, 'statSync', ...) seams, a real regression caught by the full suite (not the reviewer). * fix(#4155): catch a plan/summary added to the phase dir after verification but never declared The content digest only recomputes hashes for paths the verifier actually declared in covered_files — it had no way to notice a plan or summary added to the phase directory after verification if that new file was never declared, silently regressing behind the legacy mtime check it replaces (which scans the live directory, not a declared list). findUncoveredCurrentArtifact re-scans the live phase directory for every current *-PLAN.md/*-SUMMARY.md and requires each to be represented in covered_files, closing that gap; a directory scan failure fails closed to stale rather than silently skipping the check. CONTEXT.md's Verification Module entry corrected to describe the fingerprint path's stricter fail-closed FS-error contract (routes to stale) instead of the module's original degrade-to-safe one (missing / not-stale), which only the legacy path still keeps. * refactor(#4155): extract canonicalizeCoveredFiles, add real nested-project e2e test computeCoveredDigest and cmdVerificationFingerprint each normalized/deduped/ sorted covered_files independently — one shared helper now backs both (gemini review's ponytail-lens finding). Adds one CLI-to-readVerificationStatus test against a genuine .planning/phases/NN-x/ project with an implementation file outside .planning/ entirely, closing the review finding that prior #4155 unit fixtures put phaseDir directly under an ownerless tmpdir (findProjectRoot falls back to phaseDir itself there) and never exercised real multi-level path resolution. * fix(#4155): route computeCoveredDigest through real fs, fail closed on unreadable plans/ Two independent review rounds (opus critical-reviewer + opus ponytail + agy, run twice) found two instances of the same fail-open class: - computeCoveredDigest's per-file reads routed through the caller's injected fsImpl. planning-inspect.cts passes a `.planning/`-confined containment fs into readVerificationStatus's opts.fs, so any covered implementation file outside `.planning/` (mandatory per the issue) made the confinement wrapper throw, which was caught and turned into a stale digest -- reporting every fingerprinted phase permanently stale via `planning.inspect`, regardless of actual drift. Per-file reads now always use real node:fs, matching the pre-existing treatment of root canonicalization; the realRel-vs-realRoot check is the real confinement boundary for this data and needs no seam. - allCurrentArtifactsCovered's try/catch never fired (scanPhasePlans reports readdir failures via a `scope` field, it never throws), so an unreadable nested plans/ dir was silently treated as "zero artifacts, all covered" instead of failing closed. Now branches on scope !== SCOPE.COMPLETE. Also, per ponytail's second-round findings: reverted an unwarranted FINGERPRINT_VERSION bump and digest length-prefix from the first fix (no v1 digest has ever existed -- the feature is unreleased -- and the prefix closed a collision that grants no capability beyond what a writer of covered_files already has more cheaply); removed a verifier-facing escape-hatch instruction whose own example was a case that should trigger staleness, not bypass it; corrected CONTEXT.md references to the renamed allCurrentArtifactsCovered and a stale "unconditional" rescan claim; simplified the isStale derivation, removed dead FsLike members, and tightened test coverage. Regression tests for both fail-open bugs are included and were each confirmed to fail against the pre-fix code before the fix landed. full test suite: 2558/2560 pass, 2 skipped, 0 fail * fix(#4155): trim gsd-verifier.md under the LARGE size cap Fork CI caught what my local runs missed: the superseded/nested-plans instruction added earlier pushed gsd-verifier.md to 49299 bytes, 147 over the LARGE tier's 49152-byte hard cap (tests/agent-size-budget.test.cjs). Tightened the #4155 instruction's wording and dropped a redundant inline comment tag; no content lost. * chore(#4155): point changeset at the upstream PR number pr: 19 was the fork PR opened for internal review-lane CI; now that open-gsd/gsd-core#4290 exists, the changeset field must match it per CONTRIBUTING.md's release-notes convention. --------- Co-authored-by: Test <test@test.com> Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
5.7 KiB
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
/gsd-verify-work 1
GSD 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 — GSD 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 /gsd-verify-work 1 and GSD offers to resume from the last checkpoint.
When failures are found: auto-diagnose and fix planning
If any tests report issues, GSD proceeds automatically:
- Diagnoses root causes — spawns parallel debug agents, one per issue, and updates
UAT.mdwith root causes. - Plans gap closure — spawns a
gsd-plannerin gap-closure mode, which readsUAT.md(with diagnoses) and writes newPLAN.mdfiles. - Verifies the fix plans — spawns a
gsd-plan-checkerto ensure the plans are executable. If issues are found, the planner and checker iterate up to three times. - Presents next step — when plans pass the checker:
Plans verified and ready for execution.
`/clear` then `/gsd-execute-phase 1 --gaps-only`
Run the suggested command to apply fixes, then re-run /gsd-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.
/gsd-ship 1
GSD runs preflight checks (verification status, clean working tree, branch, remote, gh CLI authentication), pushes the branch, and creates a PR:
/gsd-ship 1 # Ready-for-review PR
/gsd-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.mdfiles 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
/gsd-ship does not run a code review automatically, but you can slot one in at any point:
Before verification (catches issues before UAT):
/gsd-code-review 1 # Standard review
/gsd-code-review 1 --fix # Review then auto-fix Critical + Warning findings
After the PR is open (to gate on quality before merge):
/gsd-code-review 1 --depth=deep # Cross-file analysis including import graphs
See Set up cross-AI review to configure Gemini, 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:
/gsd-pr-branch # Filter against main
/gsd-pr-branch develop # Filter against develop
/gsd-pr-branch creates a new branch with only code changes — planning artefact commits are excluded. Run this before /gsd-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.mdfiles, 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 reportsstale. This catches drift even when nothing touchesSUMMARY.mditself — an implementation file edited after verification is enough. - Legacy SUMMARY-mtime check. A
*-VERIFICATION.mdwritten before this fingerprint existed has no digest to check, so it keeps the older rule:stalewhen aSUMMARY.mdis newer than the verification report.
Either way, stale routes the same as any other incomplete state: re-run /gsd-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:
/gsd-audit-milestone # Verify all requirements shipped
/gsd-complete-milestone # Archive, create git tag
/gsd-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.