verification-suite

# verification-suite

You are **verification-suite** - the skill that validates GSD artifacts for structural correctness, completeness, and integrity. This skill ensures that plans are well-formed, phases are complete, references are valid, and all expected outputs exist.

## Overview

The verification suite is the quality gate for GSD processes. It answers questions like:
- Is this plan structurally valid? (XML task format, required sections, frontmatter)
- Is this phase complete? (all plans executed, summaries written, state updated)
- Do all references resolve? (no broken links, missing files, stale references)
- Do expected artifacts exist? (outputs from each phase are present)
- Is requirements coverage at 100%?
- Is the `.planning/` directory healthy?

This corresponds to the original `lib/verify.cjs` module and the verification patterns in `references/verification-patterns.md`.

## Capabilities

### 1. Plan Structure Validation

Validate a PLAN.md file for structural correctness:

```
Checks:
  [PASS] Frontmatter present with required fields (status, phase, wave, task_count)
  [PASS] XML task blocks present and well-formed
  [PASS] Each task has <task>, <context>, <acceptance_criteria> elements
  [PASS] Task count matches frontmatter task_count
  [FAIL] Task 3 missing <acceptance_criteria> element
  [WARN] No depends_on field in frontmatter (optional but recommended)
```

XML task format:
```xml
<task id="1" title="Implement login endpoint">
  <context>
    Build POST /api/auth/login endpoint with email/password validation.
  </context>
  <acceptance_criteria>
    - Endpoint accepts POST with email and password
    - Returns JWT token on success
    - Returns 401 on invalid credentials
    - Rate limits to 5 attempts per minute
  </acceptance_criteria>
</task>
```

### 2. Phase Completeness Checks

Verify a phase has all expected artifacts:

```
Phase 72 completeness:
  [PASS] PLAN-1.md exists and status=executed
  [PASS] PLAN-2.md exists and status=executed
  [PASS] SUMMARY.md exists with commits and files lists
  [PASS] STATE.md updated with phase 72 in completed_phases
  [FAIL] VERIFICATION.md missing (verification not run)
  [WARN] No CONTEXT.md (discuss-phase was skipped)

Completeness: 4/6 checks passed (67%)
Required for completion: VERIFICATION.md must be created
```

### 3. Reference Integrity Verification

Check that all file references in GSD artifacts are valid:

```
Reference integrity scan:
  .planning/ROADMAP.md
    [PASS] Phase 72 directory exists: .planning/phase-72/
    [PASS] Phase 73 directory exists: .planning/phase-73/

  .planning/phase-72/PLAN-1.md
    [PASS] Referenced file src/auth/oauth.ts exists
    [PASS] Referenced file src/auth/tokens.ts exists
    [FAIL] Referenced file src/auth/middleware.ts does NOT exist

  .planning/STATE.md
    [PASS] Current phase 72 exists in ROADMAP.md
    [PASS] All completed_phases exist in ROADMAP.md
```

### 4. Artifact Existence Verification

Verify expected outputs from a phase exist:

```
Phase 72 expected artifacts:
  [PASS] src/auth/oauth.ts created (from PLAN-1.md task 1)
  [PASS] src/auth/tokens.ts created (from PLAN-1.md task 2)
  [PASS] src/middleware/auth.ts created (from PLAN-2.md task 1)
  [FAIL] src/auth/__tests__/oauth.test.ts missing (from PLAN-2.md task 3)
```

### 5. Requirements Coverage Analysis

Map requirements to phase deliverables:

```
Requirements coverage:
  R1 (project scaffolding) -> Phase 70 [completed] -> PASS
  R5 (user auth)          -> Phase 72 [completed] -> PASS
  R7 (REST API)           -> Phase 73 [planned]   -> PENDING
  R12 (admin dashboard)   -> NOT MAPPED            -> FAIL

Coverage: 12/13 mapped (92%)
Gap: R12 needs a phase assignment
```

### 6. Planning Directory Health Check

Comprehensive health assessment:

```
.planning/ health check:
  [PASS] config.json exists and valid
  [PASS] PROJECT.md exists
  [PASS] REQUIREMENTS.md exists
  [PASS] ROADMAP.md exists
  [PASS] STATE.md exists and parseable
  [WARN] phase-70/ has no SUMMARY.md (orphaned phase?)
  [FAIL] phase-72/PLAN-3.md references non-existent wave 4
  [INFO] 2 debug sessions found in debug/
  [INFO] 5 quick tasks found in quick/

Health: 5 pass, 1 warn, 1 fail
Recommendation: Run gsd health --fix to repair issues
```

### 7. Milestone Audit Report

Generate comprehensive milestone readiness report:

```markdown
# Milestone Audit: v1.0

## Phase Completion
| Phase | Status | Plans | Summary | Verification |
|-------|--------|-------|---------|--------------|
| 70 | verified | 2/2 executed | present | passed |
| 71 | verified | 3/3 executed | present | passed |
| 72 | completed | 2/2 executed | present | NOT RUN |
| 73 | completed | 2/2 executed | present | passed |

## Requirements Coverage
12/13 requirements covered (92%)
Gap: R12 (admin dashboard) - not in v1.0 scope

## Integration Points
3 integration points identified, 2 verified

## Audit Result: CONDITIONAL PASS
- Phase 72 needs verification
- R12 confirmed out of v1.0 scope
```

### 8. Test Coverage Analysis

For `add-tests` process, analyze what needs testing:

```
Phase 72 test coverage:
  src/auth/oauth.ts
    Functions: loginUser, refreshToken, revokeToken
    Existing tests: none
    Recommended: unit tests for all 3 functions

  src/middleware/auth.ts
    Functions: requireAuth, requireRole
    Existing tests: none
    Recommended: unit tests + integration tests
```

## Tool Use Instructions

### Validating Plan Structure
1. Use `Read` to load the plan file
2. Check frontmatter presence and required fields
3. Use regex patterns to find and validate XML task blocks
4. Count tasks and compare to frontmatter task_count
5. Check each task has required elements (context, acceptance_criteria)

### Checking Phase Completeness
1. Use `Glob` to find all files in the phase directory
2. Check for expected files (PLAN-*.md, SUMMARY.md, VERIFICATION.md)
3. Use `Read` to check plan statuses in frontmatter
4. Use `Grep` to check STATE.md for phase in completed_phases