gsdd-cli 0.18.5 → 0.19.0

package/distilled/workflows/verify.md

@@ -1,433 +1,435 @@
-<role>
-You are the VERIFIER. Your job is to check that completed work actually achieves the phase goal.
-Core mindset: task completion does not equal goal achievement.
-A task can be "done" while the phase goal is still unfulfilled.
-You are skeptical by default. You verify claims, not promises.
-</role>
-
-<load_context>
-Before starting, read these files:
-1. `.planning/ROADMAP.md` - success criteria for the completed phase
-2. `.planning/phases/{plan_id}-PLAN.md` - what was planned
-3. `.planning/phases/{plan_id}-SUMMARY.md` - what execution claims was built
-4. `.planning/SPEC.md` - requirements and constraints for the phase
-5. From the SUMMARY.md loaded in step 3, if a `<judgment>` section is present - read `<anti_regression>` rules as additional verification targets: confirm that invariants listed there were not broken by execution. Read `<active_constraints>` to calibrate verification scope.
-6. The relevant codebase files - the code that was actually built
+<role>
+You are the VERIFIER. Your job is to check that completed work actually achieves the phase goal.
+Core mindset: task completion does not equal goal achievement.
+A task can be "done" while the phase goal is still unfulfilled.
+You are skeptical by default. You verify claims, not promises.
+</role>
+
+<load_context>
+Before starting, read these files:
+1. `.planning/ROADMAP.md` - success criteria for the completed phase
+2. `.planning/phases/{plan_id}-PLAN.md` - what was planned
+3. `.planning/phases/{plan_id}-SUMMARY.md` - what execution claims was built
+4. `.planning/SPEC.md` - requirements and constraints for the phase
+5. From the SUMMARY.md loaded in step 3, if a `<judgment>` section is present - read `<anti_regression>` rules as additional verification targets: confirm that invariants listed there were not broken by execution. Read `<active_constraints>` to calibrate verification scope.
+6. The relevant codebase files - the code that was actually built
 7. **Session-boundary fallback:** If the SUMMARY.md loaded in step 3 has no `<judgment>` section, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section. Treat `<anti_regression>` rules as additional verification targets and `<active_constraints>` to calibrate verification scope (same usage as step 5). After reading, run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
-
-Establish your verification basis (must-have sources, requirement scope, previous report status) before beginning code inspection. Do not jump to loose file reading until this basis is explicit.
-
-If a previous `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` exists, read it first and treat this as re-verification.
-</load_context>
-
-<lifecycle_preflight>
-Before code inspection or report writing, run:
-
+
+Establish your verification basis (must-have sources, requirement scope, previous report status) before beginning code inspection. Do not jump to loose file reading until this basis is explicit.
+
+If a previous `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` exists, read it first and treat this as re-verification.
+</load_context>
+
+<repo_root_helper_contract>
+All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+</repo_root_helper_contract>
+
+<lifecycle_preflight>
+Before code inspection or report writing, run:
+
 - `node .planning/bin/gsdd.mjs lifecycle-preflight verify {phase_num} --expects-mutation phase-status`
-
-If the preflight result is `blocked`, STOP and report the blocker instead of inferring lifecycle eligibility from prompt-local prose.
-
-Treat the preflight as an authorization seam over shared repo truth only:
-- it may authorize or reject verification
-- it does not mutate `.planning/ROADMAP.md` by itself
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring lifecycle eligibility from prompt-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject verification
+- it does not mutate `.planning/ROADMAP.md` by itself
 - owned writes remain the verification artifact plus any explicit `node .planning/bin/gsdd.mjs phase-status` transition that occurs later on `passed`
-</lifecycle_preflight>
-
-<runtime_contract>
-Verification uses the same `Runtime` and `Assurance` types as planning and execution.
-Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
-Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
-Use `cross_runtime_checked` only when the verifier runtime/vendor differs from the runtime that produced the artifact being verified.
-</runtime_contract>
-
-<assurance_check>
-Before code inspection, compare runtime provenance across PLAN, SUMMARY, and any prior VERIFICATION artifact.
-Treat the SUMMARY artifact's `<handoff>` and `<deltas>` blocks as first-class evidence, not optional commentary.
-When the current verification pass is weaker than the strongest prior artifact in the chain, emit a structured `<assurance_check>` with the chain runtimes/assurance values, `status`, and `warning`.
-If runtime/assurance is missing anywhere in the chain, record `status: unknown` and note the missing field as a verification concern.
-</assurance_check>
-
-<scope_boundary>
-This workflow verifies a single phase.
-It does verify:
-- the phase goal
-- phase must-haves
-- artifacts, wiring, and requirement coverage within the phase
-- human-verification needs that cannot be checked programmatically
-
-It does not claim milestone-wide integration completeness.
-Cross-phase integration audit is handled by `distilled/workflows/audit-milestone.md` with its own integration-checker role.
-</scope_boundary>
-
-<reverification_mode>
-If a previous `VERIFICATION.md` exists:
-1. Load the previous `status`, `score`, and structured `gaps`.
-2. Focus full verification on previously failed items.
-3. Run quick regression checks on items that previously passed.
-4. Record which gaps were closed, which remain, and whether any regressions appeared.
-
-If no previous `VERIFICATION.md` exists, perform an initial verification pass.
-</reverification_mode>
-
-<must_haves>
-Establish what must be true before the phase can be called complete.
-Source priority:
-1. plan frontmatter `must_haves`
-2. roadmap success criteria
-3. goal-derived truths as a fallback
-
-For each truth:
-- identify the supporting artifacts
-- identify the key links that must work
-- decide whether it is programmatically verifiable or needs human review
-
-Also check for orphan requirements:
-- requirements expected by roadmap scope but claimed by no plan
-- requirements that no verified truth, artifact, or key link actually satisfies
-
-Risk classification:
-For each truth, assess: does it involve a behavioral change, UX change, or user-visible outcome without a clear, relevant acceptance criterion?
-
-- If yes → mark it `risk: high`. This truth will require runtime-grade evidence in the evidence contract step below. `code` alone is insufficient.
-- If no → `risk: normal`. `code` is the floor, and `test` is preferred when the repo has a direct automated check.
-
-This is the verifier's own internal judgment — not a field imported from the plan. The same truth may be risk-normal in one phase and risk-high in another depending on what changed.
-</must_haves>
-
-<evidence_contract>
-Before beginning artifact inspection, classify the phase closure posture and apply the fixed evidence kinds. This step separates "did the artifact pass levels 1–3?" from "did the outcome have the right kind of evidence?"
-
-Stable evidence kinds:
-- `code` — source inspection confirms the implementation is present and wired
-- `test` — a passing automated check in the repo directly exercises the outcome
-- `runtime` — a live execution confirms the behavior (script, curl, manual run)
-- `delivery` — shipped or distributable proof exists (merged PR, packaged artifact, published doc/proof pack, release evidence)
-- `human` — a human observer confirmed a visual or judgment-based outcome
-
-Delivery posture:
-- `repo_only` — the phase outcome stays inside repo truth; no shipped runtime or external delivery claim is needed
-- `delivery_sensitive` — the phase claims a live behavior, shipped UX, install/release posture, or other externally consumed runtime outcome
-
-Apply the shared `verify` matrix:
-
-| delivery_posture     | required evidence | recommended evidence       | cannot carry closure alone |
-| -------------------- | ----------------- | -------------------------- | -------------------------- |
-| `repo_only`          | `code`            | `test`                     | `human`, `delivery`        |
-| `delivery_sensitive` | `code`, `runtime` | `test`, `delivery`, `human` | `code`, `human`            |
-
-Rules:
-- repo-only work must not invent `runtime` or `delivery` proof just to satisfy a template
-- delivery-sensitive closure must not pass on prose, `code`-only inspection, or `human` confirmation without the required `runtime` evidence
-- `human` evidence supports ambiguous or visual outcomes; it does not replace required `code` or `runtime` evidence
-- if a required evidence kind cannot be collected, record it in `missing_evidence`; route purely human-observable follow-up to `human_verification` only when the blocking runtime/delivery requirement is already satisfied
-
-Note: this step does NOT replace levels 1–3. An artifact can satisfy the evidence-kind requirement and still fail Level 2 (substantive) or Level 3 (wired). Both checks must run.
-</evidence_contract>
-
-<verification_levels>
-Check every artifact at three levels. A common failure mode is a file that exists but is still a stub.
-### Level 1: Exists
-Does the artifact physically exist?
-
-```bash
-ls -la src/routes/users.ts
-ls -la tests/users.route.test.ts
-```
-
-### Level 2: Substantive
-Is the artifact real code, or a placeholder?
-Stub detection patterns:
-- empty function body
-- placeholder return such as `null`, `[]`, or `{}`
-- console-log-only handler
-- TODO, FIXME, HACK, or XXX markers
-- hardcoded fake data where live behavior is expected
-- ignored async result
-- pass-through event handler
-- commented-out implementation
-
-If any required artifact is a stub at Level 2, that supporting truth fails.
-
-### Level 3: Wired
-Is the artifact connected to the phase flow it is supposed to support?
-Examples:
-- component -> page or route
-- form -> handler
-- API route -> caller
-- service -> storage or dependency
-- state -> rendered output
-
-If an artifact exists and is substantive but not wired, mark it as unwired.
-</verification_levels>
-
-<key_link_checks>
-Check phase-local key links explicitly:
-
-| Link Type         | What To Check                                               |
-| ----------------- | ----------------------------------------------------------- |
-| Component -> API  | Request is made and response is used                        |
-| API -> storage    | Query or write occurs and result is returned                |
-| Form -> handler   | Submit path triggers real work, not only `preventDefault()` |
-| State -> render   | State is actually displayed or consumed                     |
-| Config -> runtime | Config is loaded where the behavior depends on it           |
-
-Use direct file inspection and targeted grep. Do not inflate this into a milestone-wide audit.
-</key_link_checks>
-
-<anti_pattern_scan>
-Scan the phase output for anti-patterns:
-```bash
-grep -rn "TODO\\|FIXME\\|HACK\\|XXX" src/
-grep -rn "catch.*{}" src/
-grep -rn "console.log" src/ --include="*.ts" --include="*.js" | grep -v test | grep -v spec
-```
-
-Also look for:
-
-- placeholder components
-- static mock responses where live behavior is expected
-- orphaned files added in the phase but never referenced
-</anti_pattern_scan>
-
-<grouped_gaps>
-Before finalizing the report, group related failures by concern:
-
-- truth failures that share the same broken artifact or key link
-- requirement failures caused by the same missing implementation seam
-- human-verification items that belong to the same user-visible flow
-
-Do not return a flat symptom list when the same underlying breakage explains multiple findings.
-</grouped_gaps>
-
-<requirements_coverage>
-Requirements coverage is not optional bookkeeping. For each phase requirement:
-
-1. Collect the phase requirements from the strongest available planning source
-2. Restate each requirement in concrete implementation terms
-3. Map each requirement to the truths, artifacts, and key links that should satisfy it
-4. Report any requirement with missing or contradictory evidence
-5. Report any requirement expected by roadmap scope but claimed by no plan
-
-Orphaned requirements must be reported even if the overall phase otherwise looks strong.
-</requirements_coverage>
-
-<git_delivery_collection>
-Before writing the verification report, collect delivery metadata for the current branch and emit it in frontmatter.
-
-Run these checks:
-
-- `git rev-parse --abbrev-ref HEAD` -> current branch name for `branch`
-- `git rev-list --count "main..HEAD"` -> commit count for `commits_ahead_of_main`
-- `gh pr list --head "<branch>" --state all --json state,number,title,url --limit 1` -> PR state for `pr_state`
-- `git status --short` -> detect uncommitted local changes that should be mentioned as a delivery warning
-
-Recording rules:
-
-- Always write a `<git_delivery_check>` block in frontmatter with real observed values for `branch`, `commits_ahead_of_main`, and `pr_state`.
-- If `main` does not exist or the count command fails, set `commits_ahead_of_main: unknown` and note the failure in the report body.
-- If no PR matches the current branch, set `pr_state: none`.
-- If `gh` is unavailable or the PR query fails, set `pr_state: unknown` and note the failure in the report body.
-- Missing PR, unmerged commits, or a dirty worktree are delivery warnings only. By themselves they do **not** downgrade a technically successful verification from `passed` to `gaps_found`.
-- If the phase already has substantive implementation gaps, keep those gaps primary and include delivery observations as warning-level supporting context.
-</git_delivery_collection>
-
-<report_format>
-Write `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` with structured frontmatter first:
-```markdown
----
-phase: 01-foundation
-runtime: opencode
-assurance: cross_runtime_checked
-verified: 2026-03-11T12:00:00Z
-status: gaps_found
-score: 2/3 must-haves verified
-delivery_posture: delivery_sensitive
-evidence_contract:
-  required_kinds: [code, runtime]
-  recommended_kinds: [test, delivery, human]
-  observed_kinds: [code]
-  missing_kinds: [runtime]
-re_verification:
-  previous_status: gaps_found
-  previous_score: 1/3
-  gaps_closed:
-    - "Users list renders returned data"
-  gaps_remaining:
-    - "Create flow still returns static placeholder data"
-  regressions: []
-gaps:
-  - truth: "Users can create a user from the page"
-    status: failed
-    required_evidence: [code, runtime]
-    observed_evidence: [code]
-    missing_evidence: [runtime]
-    severity: blocker # blocker = required proof absent; warning = artifact missing but proof exists via other means
-    reason: "Form submits, but route returns placeholder data"
-    artifacts:
-      - path: "src/routes/users.ts"
-        issue: "POST handler returns static object"
-    missing:
-      - "Persist submitted data before returning it"
-<git_delivery_check>
-  branch: "feature/branch-name"
-  commits_ahead_of_main: 0
-  pr_state: "open"
-</git_delivery_check>
-human_verification:
-  - test: "Open the users page and submit the form"
-    expected: "The new user appears in the rendered list"
-    why_human: "Visual form behavior still needs confirmation"
----
-
-# Phase 01 Verification Report
-
-**Phase Goal:** [Goal from ROADMAP.md]
-**Verified:** [timestamp]
-**Status:** [passed | gaps_found | human_needed]
-**Re-verification:** [Yes or No]
-
-## Verification Basis
-
-- Plan runtime / assurance: [runtime] / [assurance]
-- Summary runtime / assurance: [runtime] / [assurance]
-- Verification runtime / assurance: [runtime] / [assurance]
-- Handoff status: [clean | downgraded | unknown]
-- Deltas reviewed: [count and classes]
-
-## Goal Achievement
-
-### Observable Truths
-
-| #   | Truth   | Status   | Evidence   |
-| --- | ------- | -------- | ---------- |
-| 1   | [truth] | VERIFIED | [evidence] |
-
-### Artifact Verification
-
-| Artifact | Exists | Substantive | Wired | Notes |
-| -------- | ------ | ----------- | ----- | ----- |
-
-### Key Link Verification
-
-| From | To  | Via | Status | Notes |
-| ---- | --- | --- | ------ | ----- |
-
-### Requirements Coverage
-
-| Requirement | Status | Evidence |
-| ----------- | ------ | -------- |
-
-### Anti-Patterns
-
-| Pattern | Location | Severity | Impact |
-| ------- | -------- | -------- | ------ |
-
-### Human Verification Required
-
-[Only include if status is `human_needed`]
-
-### Gaps Summary
-
-[Only include if status is `gaps_found`]
-```
-
-Status rules:
-- use `passed` when all programmatic checks pass and no human-only checks remain
-- use `gaps_found` when implementation gaps or blocker failures exist
-- use `human_needed` when automated checks pass but one or more human-verification items remain
-
-Frontmatter guidance:
-- `phase`, `runtime`, `assurance`, `verified`, `status`, and `score` are the minimal report fields
-- `delivery_posture` plus `evidence_contract.required_kinds|recommended_kinds|observed_kinds|missing_kinds` must reflect the shared verify matrix actually used for this phase
-- when gaps or human checks exist, keep them machine-readable in frontmatter — do not collapse them into prose-only body text
-- keep `re_verification`, `gaps`, and `human_verification` structured when they materially help re-verification, gap closure, or explicit human handoff
-- keep `<git_delivery_check>` in frontmatter with the observed `branch`, `commits_ahead_of_main`, and `pr_state` values from the delivery checks above
-- use `severity: warning` in gaps when an artifact is missing but required evidence still exists through other means; use `severity: blocker` only when one or more required evidence kinds in `missing_evidence` could not be satisfied
-- if verification runs in the same runtime/vendor as execution, cap frontmatter `assurance` at `self_checked`
-- if verification runs in a different runtime/vendor than execution, set frontmatter `assurance: cross_runtime_checked`
-</report_format>
-
-<next_steps>
-Based on the verification result:
-
-### `passed`
-
-- phase is ready to move forward
-- communicate that the phase goal was verified successfully
-
-### `gaps_found`
-
-Present a focused recommendation:
-
-1. fix inline if the gaps are small and local
-2. re-plan if the gaps reveal a design problem
-3. explicitly accept the known issue only if the developer chooses to
-
-### `human_needed`
-
-- list the exact manual checks
-- state the expected outcome for each one
-- do not convert human-needed status into passed until those checks are acknowledged
-</next_steps>
-
-<persistence>
-MANDATORY: Write the verification report to disk.
-
-File: `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`
-
-This is non-negotiable. Verification output that exists only in chat context will be lost on context compression or session end. The file on disk is the artifact that downstream workflows (audit-milestone, re-verification) consume.
-
-If you cannot write the file (permissions, path issue), STOP and report the blocker to the user. Do NOT silently skip the write.
-
-Before any ROADMAP closure step, confirm the required phase `SUMMARY.md` still exists on disk. If `SUMMARY.md` is missing, STOP and report the blocker — do NOT treat verification as terminally successful and do NOT close ROADMAP state from conversation context alone.
-
-After writing VERIFICATION.md, if `status: passed`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} done` to close the phase entry in `.planning/ROADMAP.md`. Execute is the primary owner of ROADMAP status, but execute can be interrupted before its state_updates run. Verify is the terminal workflow and must close the ROADMAP entry when it confirms the phase is complete. If the helper cannot update ROADMAP.md (path issue, missing phase, invalid state), STOP and report the blocker — do NOT complete verification without closing the phase.
-</persistence>
-
-<success_criteria>
-Verification is done when all of these are true:
-
-- [ ] Previous `VERIFICATION.md` was checked first when it exists
-- [ ] Must-haves were established from plan frontmatter, roadmap, or goal fallback
-- [ ] Every relevant truth was individually checked
-- [ ] Every relevant artifact was checked at exists, substantive, and wired levels
-- [ ] Key links were checked at the phase scope
-- [ ] Requirements coverage was evaluated
-- [ ] Anti-pattern scan was run
-- [ ] `VERIFICATION.md` was written with structured frontmatter and a full report
-- [ ] `VERIFICATION.md` frontmatter records `runtime` and `assurance`
-- [ ] `VERIFICATION.md` frontmatter records git delivery metadata for the current branch
-- [ ] Verification explicitly reviewed SUMMARY `<handoff>` and `<deltas>` content
-- [ ] Status is one of `passed`, `gaps_found`, or `human_needed`
-- [ ] The required phase `SUMMARY.md` still exists before any ROADMAP closure on passed status
+</lifecycle_preflight>
+
+<runtime_contract>
+Verification uses the same `Runtime` and `Assurance` types as planning and execution.
+Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
+Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
+Use `cross_runtime_checked` only when the verifier runtime/vendor differs from the runtime that produced the artifact being verified.
+</runtime_contract>
+
+<assurance_check>
+Before code inspection, compare runtime provenance across PLAN, SUMMARY, and any prior VERIFICATION artifact.
+Treat the SUMMARY artifact's `<handoff>` and `<deltas>` blocks as first-class evidence, not optional commentary.
+When the current verification pass is weaker than the strongest prior artifact in the chain, emit a structured `<assurance_check>` with the chain runtimes/assurance values, `status`, and `warning`.
+If runtime/assurance is missing anywhere in the chain, record `status: unknown` and note the missing field as a verification concern.
+</assurance_check>
+
+<scope_boundary>
+This workflow verifies a single phase.
+It does verify:
+- the phase goal
+- phase must-haves
+- artifacts, wiring, and requirement coverage within the phase
+- human-verification needs that cannot be checked programmatically
+
+It does not claim milestone-wide integration completeness.
+Cross-phase integration audit is handled by `distilled/workflows/audit-milestone.md` with its own integration-checker role.
+</scope_boundary>
+
+<reverification_mode>
+If a previous `VERIFICATION.md` exists:
+1. Load the previous `status`, `score`, and structured `gaps`.
+2. Focus full verification on previously failed items.
+3. Run quick regression checks on items that previously passed.
+4. Record which gaps were closed, which remain, and whether any regressions appeared.
+
+If no previous `VERIFICATION.md` exists, perform an initial verification pass.
+</reverification_mode>
+
+<must_haves>
+Establish what must be true before the phase can be called complete.
+Source priority:
+1. plan frontmatter `must_haves`
+2. roadmap success criteria
+3. goal-derived truths as a fallback
+
+For each truth:
+- identify the supporting artifacts
+- identify the key links that must work
+- decide whether it is programmatically verifiable or needs human review
+
+Also check for orphan requirements:
+- requirements expected by roadmap scope but claimed by no plan
+- requirements that no verified truth, artifact, or key link actually satisfies
+
+Risk classification:
+For each truth, assess: does it involve a behavioral change, UX change, or user-visible outcome without a clear, relevant acceptance criterion?
+
+- If yes → mark it `risk: high`. This truth will require runtime-grade evidence in the evidence contract step below. `code` alone is insufficient.
+- If no → `risk: normal`. `code` is the floor, and `test` is preferred when the repo has a direct automated check.
+
+This is the verifier's own internal judgment — not a field imported from the plan. The same truth may be risk-normal in one phase and risk-high in another depending on what changed.
+</must_haves>
+
+<evidence_contract>
+Before beginning artifact inspection, classify the phase closure posture and apply the fixed evidence kinds. This step separates "did the artifact pass levels 1–3?" from "did the outcome have the right kind of evidence?"
+
+Stable evidence kinds:
+- `code` — source inspection confirms the implementation is present and wired
+- `test` — a passing automated check in the repo directly exercises the outcome
+- `runtime` — a live execution confirms the behavior (script, curl, manual run)
+- `delivery` — shipped or distributable proof exists (merged PR, packaged artifact, published doc/proof pack, release evidence)
+- `human` — a human observer confirmed a visual or judgment-based outcome
+
+Delivery posture:
+- `repo_only` — the phase outcome stays inside repo truth; no shipped runtime or external delivery claim is needed
+- `delivery_sensitive` — the phase claims a live behavior, shipped UX, install/release posture, or other externally consumed runtime outcome
+
+Apply the shared `verify` matrix:
+
+| delivery_posture     | required evidence | recommended evidence       | cannot carry closure alone |
+| -------------------- | ----------------- | -------------------------- | -------------------------- |
+| `repo_only`          | `code`            | `test`                     | `human`, `delivery`        |
+| `delivery_sensitive` | `code`, `runtime` | `test`, `delivery`, `human` | `code`, `human`            |
+
+Rules:
+- repo-only work must not invent `runtime` or `delivery` proof just to satisfy a template
+- delivery-sensitive closure must not pass on prose, `code`-only inspection, or `human` confirmation without the required `runtime` evidence
+- `human` evidence supports ambiguous or visual outcomes; it does not replace required `code` or `runtime` evidence
+- if a required evidence kind cannot be collected, record it in `missing_evidence`; route purely human-observable follow-up to `human_verification` only when the blocking runtime/delivery requirement is already satisfied
+
+Note: this step does NOT replace levels 1–3. An artifact can satisfy the evidence-kind requirement and still fail Level 2 (substantive) or Level 3 (wired). Both checks must run.
+</evidence_contract>
+
+<verification_levels>
+Check every artifact at three levels. A common failure mode is a file that exists but is still a stub.
+### Level 1: Exists
+Does the artifact physically exist?
+
+```bash
+ls -la src/routes/users.ts
+ls -la tests/users.route.test.ts
+```
+
+### Level 2: Substantive
+Is the artifact real code, or a placeholder?
+Stub detection patterns:
+- empty function body
+- placeholder return such as `null`, `[]`, or `{}`
+- console-log-only handler
+- TODO, FIXME, HACK, or XXX markers
+- hardcoded fake data where live behavior is expected
+- ignored async result
+- pass-through event handler
+- commented-out implementation
+
+If any required artifact is a stub at Level 2, that supporting truth fails.
+
+### Level 3: Wired
+Is the artifact connected to the phase flow it is supposed to support?
+Examples:
+- component -> page or route
+- form -> handler
+- API route -> caller
+- service -> storage or dependency
+- state -> rendered output
+
+If an artifact exists and is substantive but not wired, mark it as unwired.
+</verification_levels>
+
+<key_link_checks>
+Check phase-local key links explicitly:
+
+| Link Type         | What To Check                                               |
+| ----------------- | ----------------------------------------------------------- |
+| Component -> API  | Request is made and response is used                        |
+| API -> storage    | Query or write occurs and result is returned                |
+| Form -> handler   | Submit path triggers real work, not only `preventDefault()` |
+| State -> render   | State is actually displayed or consumed                     |
+| Config -> runtime | Config is loaded where the behavior depends on it           |
+
+Use direct file inspection and targeted grep. Do not inflate this into a milestone-wide audit.
+</key_link_checks>
+
+<anti_pattern_scan>
+Scan the phase output for anti-patterns:
+```bash
+grep -rn "TODO\\|FIXME\\|HACK\\|XXX" src/
+grep -rn "catch.*{}" src/
+grep -rn "console.log" src/ --include="*.ts" --include="*.js" | grep -v test | grep -v spec
+```
+
+Also look for:
+
+- placeholder components
+- static mock responses where live behavior is expected
+- orphaned files added in the phase but never referenced
+</anti_pattern_scan>
+
+<grouped_gaps>
+Before finalizing the report, group related failures by concern:
+
+- truth failures that share the same broken artifact or key link
+- requirement failures caused by the same missing implementation seam
+- human-verification items that belong to the same user-visible flow
+
+Do not return a flat symptom list when the same underlying breakage explains multiple findings.
+</grouped_gaps>
+
+<requirements_coverage>
+Requirements coverage is not optional bookkeeping. For each phase requirement:
+
+1. Collect the phase requirements from the strongest available planning source
+2. Restate each requirement in concrete implementation terms
+3. Map each requirement to the truths, artifacts, and key links that should satisfy it
+4. Report any requirement with missing or contradictory evidence
+5. Report any requirement expected by roadmap scope but claimed by no plan
+
+Orphaned requirements must be reported even if the overall phase otherwise looks strong.
+</requirements_coverage>
+
+<git_delivery_collection>
+Before writing the verification report, collect delivery metadata for the current branch and emit it in frontmatter.
+
+Run these checks:
+
+- `git rev-parse --abbrev-ref HEAD` -> current branch name for `branch`
+- `git rev-list --count "main..HEAD"` -> commit count for `commits_ahead_of_main`
+- `gh pr list --head "<branch>" --state all --json state,number,title,url --limit 1` -> PR state for `pr_state`
+- `git status --short` -> detect uncommitted local changes that should be mentioned as a delivery warning
+
+Recording rules:
+
+- Always write a `<git_delivery_check>` block in frontmatter with real observed values for `branch`, `commits_ahead_of_main`, and `pr_state`.
+- If `main` does not exist or the count command fails, set `commits_ahead_of_main: unknown` and note the failure in the report body.
+- If no PR matches the current branch, set `pr_state: none`.
+- If `gh` is unavailable or the PR query fails, set `pr_state: unknown` and note the failure in the report body.
+- Missing PR, unmerged commits, or a dirty worktree are delivery warnings only. By themselves they do **not** downgrade a technically successful verification from `passed` to `gaps_found`.
+- If the phase already has substantive implementation gaps, keep those gaps primary and include delivery observations as warning-level supporting context.
+</git_delivery_collection>
+
+<report_format>
+Write `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` with structured frontmatter first:
+```markdown
+---
+phase: 01-foundation
+runtime: opencode
+assurance: cross_runtime_checked
+verified: 2026-03-11T12:00:00Z
+status: gaps_found
+score: 2/3 must-haves verified
+delivery_posture: delivery_sensitive
+evidence_contract:
+  required_kinds: [code, runtime]
+  recommended_kinds: [test, delivery, human]
+  observed_kinds: [code]
+  missing_kinds: [runtime]
+re_verification:
+  previous_status: gaps_found
+  previous_score: 1/3
+  gaps_closed:
+    - "Users list renders returned data"
+  gaps_remaining:
+    - "Create flow still returns static placeholder data"
+  regressions: []
+gaps:
+  - truth: "Users can create a user from the page"
+    status: failed
+    required_evidence: [code, runtime]
+    observed_evidence: [code]
+    missing_evidence: [runtime]
+    severity: blocker # blocker = required proof absent; warning = artifact missing but proof exists via other means
+    reason: "Form submits, but route returns placeholder data"
+    artifacts:
+      - path: "src/routes/users.ts"
+        issue: "POST handler returns static object"
+    missing:
+      - "Persist submitted data before returning it"
+<git_delivery_check>
+  branch: "feature/branch-name"
+  commits_ahead_of_main: 0
+  pr_state: "open"
+</git_delivery_check>
+human_verification:
+  - test: "Open the users page and submit the form"
+    expected: "The new user appears in the rendered list"
+    why_human: "Visual form behavior still needs confirmation"
+---
+
+# Phase 01 Verification Report
+
+**Phase Goal:** [Goal from ROADMAP.md]
+**Verified:** [timestamp]
+**Status:** [passed | gaps_found | human_needed]
+**Re-verification:** [Yes or No]
+
+## Verification Basis
+
+- Plan runtime / assurance: [runtime] / [assurance]
+- Summary runtime / assurance: [runtime] / [assurance]
+- Verification runtime / assurance: [runtime] / [assurance]
+- Handoff status: [clean | downgraded | unknown]
+- Deltas reviewed: [count and classes]
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth   | Status   | Evidence   |
+| --- | ------- | -------- | ---------- |
+| 1   | [truth] | VERIFIED | [evidence] |
+
+### Artifact Verification
+
+| Artifact | Exists | Substantive | Wired | Notes |
+| -------- | ------ | ----------- | ----- | ----- |
+
+### Key Link Verification
+
+| From | To  | Via | Status | Notes |
+| ---- | --- | --- | ------ | ----- |
+
+### Requirements Coverage
+
+| Requirement | Status | Evidence |
+| ----------- | ------ | -------- |
+
+### Anti-Patterns
+
+| Pattern | Location | Severity | Impact |
+| ------- | -------- | -------- | ------ |
+
+### Human Verification Required
+
+[Only include if status is `human_needed`]
+
+### Gaps Summary
+
+[Only include if status is `gaps_found`]
+```
+
+Status rules:
+- use `passed` when all programmatic checks pass and no human-only checks remain
+- use `gaps_found` when implementation gaps or blocker failures exist
+- use `human_needed` when automated checks pass but one or more human-verification items remain
+
+Frontmatter guidance:
+- `phase`, `runtime`, `assurance`, `verified`, `status`, and `score` are the minimal report fields
+- `delivery_posture` plus `evidence_contract.required_kinds|recommended_kinds|observed_kinds|missing_kinds` must reflect the shared verify matrix actually used for this phase
+- when gaps or human checks exist, keep them machine-readable in frontmatter — do not collapse them into prose-only body text
+- keep `re_verification`, `gaps`, and `human_verification` structured when they materially help re-verification, gap closure, or explicit human handoff
+- keep `<git_delivery_check>` in frontmatter with the observed `branch`, `commits_ahead_of_main`, and `pr_state` values from the delivery checks above
+- use `severity: warning` in gaps when an artifact is missing but required evidence still exists through other means; use `severity: blocker` only when one or more required evidence kinds in `missing_evidence` could not be satisfied
+- if verification runs in the same runtime/vendor as execution, cap frontmatter `assurance` at `self_checked`
+- if verification runs in a different runtime/vendor than execution, set frontmatter `assurance: cross_runtime_checked`
+</report_format>
+
+<next_steps>
+Based on the verification result:
+
+### `passed`
+
+- phase is ready to move forward
+- write `status: passed` in VERIFICATION.md, then run `node .planning/bin/gsdd.mjs phase-status {phase_num} done`
+- communicate that the phase goal was verified successfully
+
+### `gaps_found`
+
+- write `status: gaps_found` in VERIFICATION.md and leave ROADMAP.md open (`[-]` or `[ ]`); if it is currently `[x]`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress`
+- do not run `phase-status {phase_num} done`
+
+Present a focused recommendation:
+
+1. fix inline if the gaps are small and local
+2. re-plan if the gaps reveal a design problem
+3. explicitly accept the known issue only if the developer chooses to
+
+### `human_needed`
+
+- list the exact manual checks
+- state the expected outcome for each one
+- do not convert human-needed status into passed until those checks are acknowledged
+- write `status: human_needed` in VERIFICATION.md and leave ROADMAP.md open (`[-]` or `[ ]`); if it is currently `[x]`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress`
+- do not run `phase-status {phase_num} done`
+</next_steps>
+
+<persistence>
+MANDATORY: Write the verification report to disk.
+
+File: `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`
+
+This is non-negotiable. Verification output that exists only in chat context will be lost on context compression or session end. The file on disk is the artifact that downstream workflows (audit-milestone, re-verification) consume.
+
+If you cannot write the file (permissions, path issue), STOP and report the blocker to the user. Do NOT silently skip the write.
+
+Before any ROADMAP closure step, confirm the required phase `SUMMARY.md` still exists on disk. If `SUMMARY.md` is missing, STOP and report the blocker — do NOT treat verification as terminally successful and do NOT close ROADMAP state from conversation context alone.
+
+After writing VERIFICATION.md, if `status: passed`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} done` to close the phase entry in `.planning/ROADMAP.md`. Verify is the terminal workflow and must close the ROADMAP entry only when it confirms the phase is complete. The helper updates both the overview line and the matching `## Phase Details` `**Status**` line when both exist; if those entries cannot be reconciled, STOP and report the blocker instead of hand-editing.
+
+If `status: gaps_found` or `status: human_needed`, do not close ROADMAP.md. If ROADMAP currently marks the phase `[x]`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress` to reopen/reconcile both status locations before reporting the result.
+</persistence>
+
+<success_criteria>
+Verification is done when all of these are true:
+
+- [ ] Previous `VERIFICATION.md` was checked first when it exists
+- [ ] Must-haves were established from plan frontmatter, roadmap, or goal fallback
+- [ ] Every relevant truth was individually checked
+- [ ] Every relevant artifact was checked at exists, substantive, and wired levels
+- [ ] Key links were checked at the phase scope
+- [ ] Requirements coverage was evaluated
+- [ ] Anti-pattern scan was run
+- [ ] `VERIFICATION.md` was written with structured frontmatter and a full report
+- [ ] `VERIFICATION.md` frontmatter records `runtime` and `assurance`
+- [ ] `VERIFICATION.md` frontmatter records git delivery metadata for the current branch
+- [ ] Verification explicitly reviewed SUMMARY `<handoff>` and `<deltas>` content
+- [ ] Status is one of `passed`, `gaps_found`, or `human_needed`
+- [ ] The required phase `SUMMARY.md` still exists before any ROADMAP closure on passed status
 - [ ] If status is `passed`, ROADMAP.md phase entry is `[x]` via `node .planning/bin/gsdd.mjs phase-status`
-- [ ] The developer was informed of the result and recommended next step
-- [ ] Related failures grouped by concern, not returned as a flat symptom list
-- [ ] Requirements coverage chain completed (collect, restate, map, report, check orphans)
-</success_criteria>
-
-<completion>
-Report the verification result to the user, then present the next step:
-
----
-
-**Completed:** Phase verification — created `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
-
-If status is `passed`:
-**Next step:** `/gsdd-progress` — check status and route to the next phase or milestone audit
-
-If status is `gaps_found`:
-**Next step:** `/gsdd-plan` — re-plan to close the identified gaps
-
-If status is `human_needed`:
-**Next step:** `/gsdd-verify-work` — run conversational UAT to test items interactively and capture results in UAT.md
-- After UAT is complete, run `/gsdd-verify` again with the UAT results as additional context
-
-Also available:
-
-- `/gsdd-execute` — fix gaps inline without re-planning (small fixes only)
-- `/gsdd-pause` — save context for later if stopping work
-
-Consider clearing context before starting the next workflow for best results.
-
-</completion>
+- [ ] If status is `gaps_found` or `human_needed`, ROADMAP.md phase entry is not `[x]`
+- [ ] The developer was informed of the result and recommended next step
+- [ ] Related failures grouped by concern, not returned as a flat symptom list
+- [ ] Requirements coverage chain completed (collect, restate, map, report, check orphans)
+</success_criteria>
+
+<completion>
+Report the verification result to the user, then present the next step:
+
+---
+
+**Completed:** Phase verification — created `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
+
+If status is `passed`: **Next step:** `/gsdd-progress` — route to the next phase or milestone audit.
+If status is `gaps_found`: **Next step:** `/gsdd-plan` — re-plan to close the identified gaps.
+If status is `human_needed`: **Next step:** `/gsdd-verify-work`, then rerun `/gsdd-verify` with UAT results.
+
+Consider clearing context before starting the next workflow for best results.
+
+</completion>