codex-sdd:validate

OpenSpec Validate

Context

Validate is the fourth phase of the OpenSpec workflow. It checks that the implementation aligns with the specification and identifies drift between the planned design and actual code. This is the "catch deviation early" step.

Trigger

Any of these patterns triggers this skill:

• User says "openspec validate" or "openspec:validate"
• User says "check spec" or "validate change"
• All tasks are completed (state auto-transitions to validate)
• User reports unexpected behavior during testing
• openspec_get_status shows phase is validate

Prerequisites

• All implementation tasks completed (or at least started)
• active change artifacts exist under openspec/changes/<changeId>/

Workflow

Step 1: Run Validation

Call openspec_validate to get a programmatic drift report:

openspec_validate({})

This checks:

• All active artifacts exist
• All tasks are marked complete
• Required hooks are complete
• Completed tasks have structured validation evidence when the loop state is active

Also call docs_check_freshness for affected spec domains. Domain specs that do not include the active change should be treated as validation drift and fixed with openspec_sync_specs before archive.

Step 2: Manual Validation Checks

Beyond the automated checks, also verify:

Interface Alignment:

• Do the implemented APIs match the design document?
• Are request/response fields consistent with the spec?
• Are error codes and edge cases handled?

Behavioral Coverage:

• Are the main acceptance scenarios from the proposal covered?
• Are edge cases handled (null inputs, empty states, timeouts)?
• Are concurrency/locking behaviors correct?

Code Quality:

• Are there any obvious issues (hard-coded values, security concerns)?
• Are tests added for new functionality?

Record each concrete validation result with openspec_record_validation_evidence. Use evidence type test, lint, typecheck, manual, hook, spec_alignment, or ci. A task should not be treated as fully accepted until its required behavior has passed evidence or a human review explicitly accepts the gap.