OpenSpec Verification

Guide for verifying that implementation matches spec artifacts.

Input Files

Path Enforcement: The specs_path MUST be .scaffolding/conversations/{UUID}/specs/ where {UUID} is a valid UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). NEVER use descriptive folder names.

.scaffolding/conversations/ is a symlink to <share>/projects/<repo-name>/conversations (paths below are unchanged; always go through the symlink).

Three Verification Dimensions

1. Completeness

Question: Are all tasks done and all requirements covered?

2. Correctness

Question: Does the code do what the spec says?

3. Coherence

Question: Does the code match design decisions?

Two-Stage Review

Review in two ordered stages. Do not start stage 2 until stage 1 passes.

Why this order: polishing code that implements the wrong thing is wasted work, and quality findings on code that will change after a spec fix are noise. Stage 1 maps to the Completeness + Correctness + Coherence dimensions above; stage 2 is the code-quality pass layered on top. Report stage results separately.

Receiving Code Review (implementer side)

When acting on review feedback:

1. Read all items first, then address them in order: CRITICAL, WARNING, SUGGESTION.
2. Verify before changing - confirm each finding against the code; do not apply a suggestion blindly.
3. Disagree with evidence - if a finding is wrong or conflicts with the spec, reply with the reason (file/line, spec reference) instead of silently ignoring or complying.
4. One fix, one check - after each change re-run the relevant tests; do not batch unrelated fixes.
5. Ask when unclear - an ambiguous item gets a question, not a guess.
6. Report back per item: fixed / disputed (why) / deferred (why). No performative agreement; state what changed.

Verification Process

1. Load artifacts - Read design.md, tasks.md, proposal.md
2. Check completeness - Parse checkboxes, search for requirement implementations
3. Check correctness - Trace each scenario through code, verify test coverage
4. Check coherence - Compare decisions to implementation, check patterns
5. Generate report - Summarize findings with issue levels

Report Format

## Verification Report

### Summary
| Dimension    | Status              |
|--------------|---------------------|
| Completeness | X/Y tasks, N reqs   |
| Correctness  | M/N scenarios pass   |
| Coherence    | Followed / N issues  |

### Critical Issues
| # | Dimension | Issue | File | Recommendation |
|---|-----------|-------|------|----------------|
| 1 | Completeness | Task 2.3 incomplete | - | Complete or mark blocked |

### Warnings
| # | Dimension | Issue | File | Recommendation |
|---|-----------|-------|------|----------------|
| 1 | Correctness | Scenario X not tested | test_foo.py | Add test case |

### Suggestions
- [Pattern deviation details with file reference]

### Assessment
[CRITICAL: N issues | WARNINGS: N | Ready for archive: Yes/No]

Graceful Degradation

Always note which checks were skipped and why.

Verification Heuristics

• Completeness: Focus on objective items (checkboxes, requirement lists)
• Correctness: Use keyword search + file path analysis; don't require certainty
• Coherence: Look for glaring inconsistencies, don't nitpick style
• False positives: Prefer SUGGESTION over WARNING, WARNING over CRITICAL when uncertain
• Actionability: Every issue must have a specific recommendation with file references