Validate Phase - Get Shit Done

<purpose> Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md. </purpose>

<required_reading> @~/.claude/get-shit-done/references/ui-brand.md </required_reading>

<available_agent_types> Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):

gsd-nyquist-auditor — Validates verification coverage </available_agent_types>

0. Initialize

bash

INIT=$(gsd-sdk query init.phase-op "${PHASE_ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS_AUDITOR=$(gsd-sdk query agent-skills gsd-nyquist-auditor)

Parse: phase_dir, phase_number, phase_name, phase_slug, padded_phase.

bash

AUDITOR_MODEL=$(gsd-sdk query resolve-model gsd-nyquist-auditor --raw)
NYQUIST_CFG=$(gsd-sdk query config-get workflow.nyquist_validation --raw)

If NYQUIST_CFG is false: exit with "Nyquist validation is disabled. Enable via /gsd:settings."

Display banner: GSD > VALIDATE PHASE {N}: {name}

1. Detect Input State

bash

VALIDATION_FILE=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)

State A (VALIDATION_FILE non-empty): Audit existing
State B (VALIDATION_FILE empty, SUMMARY_FILES non-empty): Reconstruct from artifacts
State C (SUMMARY_FILES empty): Exit — "Phase {N} not executed. Run /gsd:execute-phase {N} ${GSD_WS} first."

2. Discovery

2a. Read Phase Artifacts

Read all PLAN and SUMMARY files. Extract: task lists, requirement IDs, key-files changed, verify blocks.

2b. Build Requirement-to-Task Map

Per task: { task_id, plan_id, wave, requirement_ids, has_automated_command }

2c. Detect Test Infrastructure

State A: Parse from existing VALIDATION.md Test Infrastructure table. State B: Filesystem scan:

bash

find . -name "pytest.ini" -o -name "jest.config.*" -o -name "vitest.config.*" -o -name "pyproject.toml" 2>/dev/null | head -10
find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "*/node_modules/*" 2>/dev/null | head -40

2d. Cross-Reference

Match each requirement to existing tests by filename, imports, test descriptions. Record: requirement → test_file → status.

3. Gap Analysis

Classify each requirement:

Status	Criteria
COVERED	Test exists, targets behavior, runs green
PARTIAL	Test exists, failing or incomplete
MISSING	No test found

Build: { task_id, requirement, gap_type, suggested_test_path, suggested_command }

No gaps → skip to Step 6, set nyquist_compliant: true.

4. Present Gap Plan

Text mode (workflow.text_mode: true in config or --text flag): Set TEXT_MODE=true if --text is present in $ARGUMENTS OR text_mode from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where AskUserQuestion is not available. Call AskUserQuestion with gap table and options:

"Fix all gaps" → Step 5
"Skip — mark manual-only" → add to Manual-Only, Step 6
"Cancel" → exit

5. Spawn gsd-nyquist-auditor

Agent(
  prompt="Read ~/.claude/agents/gsd-nyquist-auditor.md for instructions.\n\n" +
    "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
    "<gaps>{gap list}</gaps>" +
    "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>" +
    "${AGENT_SKILLS_AUDITOR}",
  subagent_type="gsd-nyquist-auditor",
  model="{AUDITOR_MODEL}",
  description="Fill validation gaps for Phase {N}"
)

ORCHESTRATOR RULE — CODEX RUNTIME: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.

Handle return:

## GAPS FILLED → record tests + map updates, Step 6
## PARTIAL → record resolved, move escalated to manual-only, Step 6
## ESCALATE → move all to manual-only, Step 6

6. Generate/Update VALIDATION.md

State B (create):

Read template from ~/.claude/get-shit-done/templates/VALIDATION.md
Fill: frontmatter, Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
Write to ${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md

State A (update):

Update Per-Task Map statuses, add escalated to Manual-Only, update frontmatter
Append audit trail:

markdown

## Validation Audit {date}
| Metric | Count |
|--------|-------|
| Gaps found | {N} |
| Resolved | {M} |
| Escalated | {K} |

7. Commit

bash

git add {test_files}
git commit -m "test(phase-${PHASE}): add Nyquist validation tests"

gsd-sdk query commit "docs(phase-${PHASE}): add/update validation strategy"

8. Results + Routing

Compliant:

GSD > PHASE {N} IS NYQUIST-COMPLIANT
All requirements have automated verification.
▶ Next: /gsd:audit-milestone ${GSD_WS}

Partial:

GSD > PHASE {N} VALIDATED (PARTIAL)
{M} automated, {K} manual-only.
▶ Retry: /gsd:validate-phase {N} ${GSD_WS}

Display /clear reminder.

</process>

<success_criteria>