ss-tools/.opencode/command/speckit.validate.md

description: Read-only pre-implementation validation gate. Runs after tasks and analyze: scans for unresolved markers, validates all artifacts, checks Axiom health, and produces a PASS/BLOCKED report at specs//validation.md. No implementation if blocking findings. handoffs: - label: Implement Project agent: speckit.implement prompt: Start implementation now that validation has PASSED send: true

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Required Skills

MANDATORY USE skill({name="semantics-core"}), skill({name="semantics-contracts"}).

Operating Constraints

STRICTLY READ-ONLY: This command MUST NOT modify any feature artifact EXCEPT specs/<feature>/validation.md. It reads everything, validates everything, and reports — but does not implement, fix, or rewrite. The ONLY write is the validation report itself.

Gate Behavior: If any blocking finding is discovered, the report MUST say BLOCKED and /speckit.implement MUST refuse to proceed until the finding is resolved.

Outline

Phase 0: Pre-Flight

1. Setup: Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from repo root. Parse FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN, TASKS.
2. Verify all prerequisite artifacts exist:
   • FEATURE_DIR/spec.md
   • FEATURE_DIR/plan.md
   • FEATURE_DIR/tasks.md
   • FEATURE_DIR/contracts/modules.md (when plan references contracts)
   • FEATURE_DIR/data-model.md (when plan references data model)
   • FEATURE_DIR/research.md (when plan references research)
3. Capture input provenance before validation: For every artifact in the validation scope, record its repository-relative path, byte size, modification timestamp, and SHA-256 digest. At minimum include spec.md, plan.md, tasks.md, traceability.md, contracts/modules.md, contracts/openapi.yaml, ux_reference.md, contracts/ux/**, and prototype/manifest.md when present. These values define the exact snapshot covered by the verdict.
4. Load context (progressive disclosure — only load sections needed for each check):
   • All feature artifacts
   • .specify/memory/constitution.md
   • docs/adr/*.md — all ADRs (for decision-memory checks)
   • .opencode/skills/semantics-core/SKILL.md — §VIII Attention Architecture
   • backend/src/ and frontend/src/ — current codebase state (for path validation)

Phase 1: Unresolved Marker Scan

Scan ALL feature artifacts for any of the following blocking markers:

Marker	Pattern	Severity	Action
[NEEDS CLARIFICATION]	spec.md	BLOCKING	Must be resolved in /speckit.clarify before implementation
[NEED_CONTEXT: *]	contracts/modules.md	BLOCKING	Blind dependency — must be resolved before contracts are implementable
TODO (in spec/plan)	spec.md, plan.md	WARNING	Review — may indicate incomplete design
TKTK	any artifact	BLOCKING	Placeholder — must be filled
???	any artifact	WARNING	Ambiguity — review
<placeholder> / TBD / TBC	any artifact	WARNING	Review
[NEEDS CLARIFICATION: ...]	any artifact	BLOCKING	Unresolved from spec

Report: count of each marker type, file locations, severity.

Phase 2: Artifact Completeness

Verify every expected artifact is present and non-empty:

Artifact	Required?	Check
spec.md	ALWAYS	Has ## User Scenarios, ## Requirements, ## Success Criteria
ux_reference.md	ALWAYS	Has personae, narrative, error experience
plan.md	ALWAYS	Has ## Summary, ## Technical Context, ## Constitution Check, ## Project Structure
tasks.md	ALWAYS	Has phases, task IDs, file paths
contracts/modules.md	When plan references contracts	Has #region contracts, @RELATION edges
data-model.md	When plan references data model	Has entity definitions, schemas
research.md	When plan references research	Has decisions, rationale, alternatives
traceability.md	When plan declares RTM	Has Story → Model → API → Task → Test matrix
quickstart.md	When plan references quickstart	Has verification commands
contracts/ux/	When UI surface	Has UX contracts from /speckit.ux
prototype/index.html	When /speckit.prototype was run	Has interactive prototype
contracts/openapi.yaml	When /speckit.openapi was run	Has valid OpenAPI 3.1 spec
fixtures/manifest.md	When plan generated fixtures	Has fixture index

Phase 3: Schema & Contract Validation

1. OpenAPI validation (if contracts/openapi.yaml exists):

   • YAML parseability (Python yaml.safe_load)
   • operationId uniqueness
   • $ref target existence
   • Required keys: openapi, info, paths, components
   • Example coverage for all response classes

2. Contract validation (via Axiom MCP):

   • Run axiom_search({operation="status"}) — confirm index is FRESH
   • Run axiom_audit({operation="audit_contracts"}) — check for invalid tiers, missing metadata, unresolved relations
   • Run axiom_search({operation="workspace_health"}) — check for orphan/unresolved metrics
   • If Axiom MCP is unavailable, fall back to manual grep checks:

     # Find all #region contracts in plan's contract files
     grep -rn "#region" specs/<feature>/contracts/
     # Check every #region has a matching #endregion
     

3. ATTN rules compliance (for contracts/modules.md):

   • ATTN_1: Every #region anchor packs [C:N] [TYPE] [SEMANTICS] on ONE line
   • ATTN_2: Contract IDs are hierarchical (Domain.Sub.Name), not flat
   • ATTN_3: Same-domain contracts share primary @SEMANTICS keyword
   • ATTN_4: No contract exceeds 150 lines, no module exceeds 400 lines

Phase 4: Reference & ADR Integrity

1. ADR continuity check:

   • Every @REJECTED path in any ADR → verify NO task in tasks.md schedules that path
   • Every architectural decision in plan.md → verify it aligns with the governing ADR (or carries <ESCALATION>)
   • Every @RATIONALE in contracts/modules.md → verify it is consistent with upstream ADR rationale

2. Cross-reference integrity:

   • Every file path in tasks.md → verify parent directory exists in backend/src/ or frontend/src/
   • Every @RELATION -> [TargetId] in contracts → verify TargetId exists in contracts/modules.md or is a known existing contract
   • Every $ref in openapi.yaml → verify target exists in the same file
   • Every operationId in openapi.yaml → verify it appears in traceability.md (if RTM exists)

Phase 5: Decision-Memory Continuity

Verify the three-layer chain is intact:

Global ADR → plan/research → contracts → preventive tasks → tests

For each @REJECTED path at any layer:

1. ADR layer: @REJECTED exists → downstream layer must NOT schedule it
2. Plan layer: @RATIONALE justification exists → contracts must propagate it
3. Contract layer: @REJECTED guardrail exists → at least one task must verify the rejection holds
4. Task layer: @RATIONALE / @REJECTED inline → must trace to a contract or ADR

Findings:

• Dangling rationale (downstream missing): WARNING
• Contradictory resurrection (rejected path scheduled): BLOCKING
• Missing guardrail (ADR rejection, no task verification): WARNING
• Unjustified workaround (local @RATIONALE without upstream source): WARNING

Phase 6: Task Dependency & Path Validation

1. Task dependency graph:

   • Phase 1 (Setup) tasks exist before Phase 2 (Foundational)
   • Foundational tasks marked before any User Story phase
   • No cross-story dependency that blocks independent verification
   • Circular dependency check: if T001 depends on T002 and T002 depends on T001 → BLOCKING

2. Path validation:

   • Every task with a file path → path starts with backend/src/, frontend/src/, specs/, docs/, or backend/tests/, frontend/src/lib/**/__tests__/
   • No task path references .kilo/, .ai/, .kilocode/
   • No task path references Rust/MCP (.rs, cargo, src/server/)
   • Every task file path is syntactically valid (no unmatched braces, no absolute / paths outside repo)

Phase 7: UX State Coverage

If the feature has a UI surface (UX contracts or ux_reference.md exists):

1. State matrix coverage: Verify every state class from the edge/failure matrix (speckit.ux.md Phase 2) is accounted for:

   • Each screen's UX contract declares the applicable states
   • No state class was skipped without explicit rationale
   • Every error state has a @UX_RECOVERY path

2. Prototype coverage (if prototype/index.html exists):

   • Every @UX_STATE in contracts → represented in prototype state switcher
   • Every @UX_RECOVERY path → traversable in prototype

3. UX test coverage:

   • Every @UX_STATE declared → at least one @UX_TEST scenario
   • Every error state → at least one @UX_TEST scenario with recovery path
   • Test ownership (L1/L2) assigned from matrix

Phase 8: Axiom Health Check

Run Axiom MCP diagnostics:

1. axiom_search({operation="status"}) — index health: FRESH / STALE / ERROR
2. axiom_search({operation="workspace_health"}) — orphan count, unresolved relations, complexity distribution
3. axiom_audit({operation="audit_belief_protocol"}) — C4/C5 contracts missing @RATIONALE/@REJECTED

Interpretation:

• Index STALE: WARNING — recent changes may not be indexed
• High orphan count (>10%): WARNING — structural drift
• Unresolved relations: BLOCKING if the unresolved target is in this feature's scope
• Missing belief protocol tags: WARNING — will block C4/C5 implementation

Phase 9: Produce Validation Report

Write specs/<feature>/validation.md:

#region Std.Opencode.ValidationReport [C:3] [TYPE ADR] [SEMANTICS validation,gate,[DOMAIN]]
@defgroup Validation Pre-implementation validation gate for [FEATURE].

## Status: [PASS / BLOCKED]

**Date**: [DATE]
**Feature**: [feature name]
**Branch**: [branch]

## Validated Inputs

| Artifact | Size (bytes) | Modified (UTC) | SHA-256 |
|----------|-------------:|----------------|---------|
| spec.md | [size] | [timestamp] | `[digest]` |
| plan.md | [size] | [timestamp] | `[digest]` |
| tasks.md | [size] | [timestamp] | `[digest]` |
| ... applicable artifacts ... | | | |

The verdict is stale and MUST NOT authorize implementation when any listed artifact is missing or its current digest differs. New applicable artifacts created after this report also make the verdict stale.

## Blocking Findings

> If BLOCKED, these MUST be resolved before `/speckit.implement`.

| ID | Check | Severity | Location | Finding |
|----|-------|:--------:|----------|---------|
| B01 | Unresolved Marker | BLOCKING | spec.md:L42 | [NEEDS CLARIFICATION: auth mechanism] |
| B02 | ADR Resurrection | BLOCKING | tasks.md:T017 | Task schedules `@REJECTED` path from ADR-0007 |

*If no blocking findings:* "✅ No blocking findings. Proceed to `/speckit.implement`."

## Warning Findings

| ID | Check | Severity | Location | Finding |
|----|-------|:--------:|----------|---------|
| W01 | Missing Guardrail | WARNING | contracts/modules.md:Api.Export | ADR-0004 @REJECTED path has no verification task |
| W02 | Dangling Rationale | WARNING | plan.md:§Decisions | @RATIONALE exists but no contract propagates it |

## Check Results

### Phase 1: Unresolved Markers
- [NEEDS CLARIFICATION]: N
- [NEED_CONTEXT]: N
- TODO/TKTK/???: N
- **Status**: ✅ PASS / ❌ BLOCKED

### Phase 2: Artifact Completeness
| Artifact | Expected | Present | Status |
|----------|:--------:|:-------:|:------:|
| spec.md | required | ✅ | PASS |
| plan.md | required | ✅ | PASS |
| tasks.md | required | ✅ | PASS |
| traceability.md | required | ✅ | PASS |
| ... | | | |

### Phase 3: Schema & Contract Validation
- YAML parse: ✅ / ❌
- operationId uniqueness: ✅ / ❌
- Contract audit: N warnings, N errors
- ATTN rules: N/N contracts pass

### Phase 4: Reference & ADR Integrity
- ADR continuity: N ADRs checked, N issues
- Cross-reference integrity: N $refs/resolved, N broken

### Phase 5: Decision-Memory Continuity
- Three-layer chain: N chains checked
- Dangling rationale: N
- Contradictory resurrection: N
- Missing guardrail: N

### Phase 6: Task Dependency & Path
- Task count: N
- Invalid paths: N
- Circular dependencies: N

### Phase 7: UX State Coverage
- State matrix coverage: N/N state classes evaluated
- Prototype coverage: N/N @UX_STATEs represented
- UX test coverage: N/N states have tests

### Phase 8: Axiom Health
- Index status: FRESH / STALE
- Orphans: N
- Unresolved relations: N

## Gate Decision

**Verdict**: ✅ PASS — `/speckit.implement` may proceed.
OR
**Verdict**: ❌ BLOCKED — resolve N blocking findings before implementation.

## Resolution Instructions

If BLOCKED:
- B01: Run `/speckit.clarify` to resolve [NEEDS CLARIFICATION] markers.
- B02: Remove or re-scope T017 to avoid the rejected path, or file `<ESCALATION>` to ADR-0007.
- ...

#endregion Std.Opencode.ValidationReport

Phase 10: Report

Report:

• Validation report path: specs/<feature>/validation.md
• Status: PASS or BLOCKED
• Blocking findings: N
• Warning findings: N
• Checks executed: 8 phases, N individual checks
• If PASS: "Ready for /speckit.implement"
• If BLOCKED: "Resolve N blocking findings, re-run /speckit.validate"