Sdd Verify

sdd-verify

Verifies that the implementation complies with the specs, design, and task

plan. The quality gate before archiving.

Triggers: /sdd-verify <change-name>, verify implementation, quality gate, validate change, sdd verify

---

Purpose

Verification objectively validates that what was implemented meets what was specified. It fixes nothing — it only reports.

Sibling reference file

• REPORT_TEMPLATE.md — persisted compact format + conversational detail blocks.

Skill resolution

Project-local → global, in order:

1. .claude/skills/sdd-verify/SKILL.md     (project-local — highest priority)
2. ~/.claude/skills/sdd-verify/SKILL.md   (global catalog — fallback)

See docs/SKILL-RESOLUTION.md for the full algorithm.

---

Process

Step 0 — Preload

Follow skills/_shared/sdd-phase-common.md Section F (Project Context Load) and Section G (Spec Context Preload). Both non-blocking.

Step 1 — Load all artifacts

Read in this order:

• Tasks — mem_search(query: "sdd/{change-name}/tasks") → mem_get_observation(id). Engram unreachable → orchestrator passes inline.
• Spec — same pattern with sdd/{change-name}/spec.
• Design — same pattern with sdd/{change-name}/design.
• Code files created/modified.

Step 2 — Completeness check

Count total tasks vs completed. Emit Completeness block from REPORT_TEMPLATE.md.

Severity:

• Incomplete core logic tasks → CRITICAL.
• Incomplete cleanup/docs tasks → WARNING.

Step 3 — Correctness check (specs)

For each requirement in the spec: 1. Look for evidence in the code that it is implemented. 2. For each Given/When/Then scenario:

• GIVEN handled (precondition/guard)?
• WHEN implemented (action/endpoint)?
• THEN verifiable (correct result)?

Emit Correctness + Scenario Coverage blocks from REPORT_TEMPLATE.md.

Step 4 — Coherence check (design)

Verify design decisions were followed. Emit Coherence block from REPORT_TEMPLATE.md.

Step 5 — Testing check

Verify test presence and scenario coverage. Emit Testing block from REPORT_TEMPLATE.md.

Step 6 — Run tests

Three-level priority model. Check config.yaml at project root in order:

Level 1 — `verify_commands` (highest priority, checked first):

• Present → use the listed commands in order; do NOT check levels 2–3; for each command run via Bash, capture exit code + stdout/stderr; record in ## Tool Execution with source label "verify_commands (config level 1)".
• Absent → proceed to Level 2.

verify_commands is NOT additive — it overrides all lower levels. Commands are assumed non-destructive; the user is responsible for this.

Level 2 — `verify.test_commands` (when Level 1 is absent):

Level 3 — auto-detection (only when 1 and 2 are absent or invalid). First match wins:

Execution: run via Bash, capture exit code (0 = pass) + stdout/stderr, record runner name + command + exit + failure summary.

Error handling:

Save the full test output for Steps 8 and 9.

Step 7 — Build & type check

Detect and execute build/type-check command.

Config overrides (checked before auto-detection):

Both overrides are independent — one can be set without the other.

Build command auto-detection (when override absent or invalid). First match wins:

Execution: run via Bash, capture exit code, capture error output.

Error handling:

Step 8 — Coverage validation (optional)

Active ONLY when coverage.threshold is configured. Advisory only — never CRITICAL, never blocks.

1. Read config.yaml for coverage.threshold (e.g., coverage: { threshold: 80 }). 2. Not configured → "Coverage Validation: SKIPPED — no threshold configured". 3. Configured:

• Parse coverage % from Step 6 test output.
• Actual ≥ threshold → "Coverage: [X]% (threshold: [Y]%) — PASS".
• Actual < threshold → "Coverage: [X]% (threshold: [Y]%) — BELOW THRESHOLD". Status WARNING.

4. Cannot parse coverage data → "Coverage Validation: SKIPPED — could not parse coverage from test output". Status WARNING.

Step 9 — Spec Compliance Matrix

Cross-reference every Given/When/Then scenario from the change's spec files against verification evidence.

1. Read all spec content from the active persistence mode (same source as Step 1). 2. Extract every Given/When/Then scenario. 3. For each scenario, cross-reference against:

• Code implementation evidence from Step 3 (Correctness).
• Test results from Step 6 — when tests were executed.

4. Assign a compliance status per scenario (see status definitions in REPORT_TEMPLATE.md).

Emit the matrix using the template from REPORT_TEMPLATE.md. The matrix MUST include scenarios from ALL spec domains affected by the change.

Step 10 — Create verify-report.md

Evidence rule — applies to every criterion in the report:

A criterion MUST only be marked [x] when: 1. A tool command was run and its output confirms the criterion, OR 2. The user provided an explicit evidence statement.

Neither met → leave [ ] with "Manual confirmation required — no tool output available". Abstract reasoning or code inspection alone MUST NOT suffice to mark [x].

The ## Tool Execution section is mandatory in every report — even when skipped. When skipped: "Test Execution: SKIPPED — no test runner detected".

Persistence — call mem_save with topic_key: sdd/{change-name}/verify-report, type: architecture, project: {project}, content = full persisted-compact markdown from REPORT_TEMPLATE.md. Do NOT write any file.

Engram unreachable → skip persistence; return report content inline only.

Conversational output — the full detail sections (Completeness, Correctness, Coherence, Testing, Spec Compliance Matrix, Coverage Validation, SUGGESTIONS) are presented in the conversational response using the detail-block templates from REPORT_TEMPLATE.md. The user must see the full analysis; only the persisted artifact is compact.

---

Verdict criteria

Severities

Verdict calculation: only the four original dimensions (Completeness, Correctness, Coherence, Testing) plus Test Execution and Spec Compliance contribute CRITICAL/WARNING. SKIPPED and INFO statuses do NOT count toward verdict. Preserves identical verdict behavior for projects without test infrastructure.

---

Output to orchestrator

{
  "status": "ok|warning|failed",
  "summary": "Verification [change-name]: [verdict]. [N] critical, [M] warnings.",
  "artifacts": ["engram:sdd/{change-name}/verify-report"],
  "test_execution": {
    "runner": "[detected runner or null]",
    "command": "[command or null]",
    "exit_code": "[0/1/N or null]",
    "result": "PASS|FAILING|ERROR|SKIPPED"
  },
  "build_check": {
    "command": "[command or null]",
    "exit_code": "[0/1/N or null]",
    "result": "PASS|FAILING|ERROR|SKIPPED"
  },
  "compliance_matrix": {
    "total_scenarios": "[N]",
    "compliant": "[N]",
    "failing": "[N]",
    "untested": "[N]",
    "partial": "[N]"
  },
  "next_recommended": ["sdd-archive (if PASS or PASS WITH WARNINGS)"],
  "risks": ["CRITICAL: [description if any]"]
}

After the report:

Continue with archive? Reply **yes** to proceed or **no** to pause.
_(Manual: `/sdd-archive <slug>`)_

---

Rules

• ONLY report — fix nothing during verification.
• Read real code — do NOT assume something works because the file exists.
• Objective: report what IS, not what should be.
• Evaluate documented deviations in tasks.md with context.
• A FAIL is information for improvement, not a personal failure.
• Run tests if possible (via Bash). Report actual results.
• ## Tool Execution is mandatory in every report — even when skipped. When skipped state: "Test Execution: SKIPPED — no test runner detected".
• A criterion marked [x] MUST have verifiable evidence: tool output OR explicit user evidence statement. Abstract reasoning or code inspection alone MUST NOT suffice.
• Test command resolution: Level 1 (verify_commands) > Level 2 (verify.test_commands) > Level 3 (auto-detection). Each level consulted ONLY when all higher levels are absent or invalid.
• Empty verify.test_commands: [] falls through to auto-detection — NEVER treated as zero-command success.
• verify.build_command and verify.type_check_command override their auto-detected commands when present AND strings. Non-string values emit WARNING and fall back to auto-detection.

sdd-verify — Report Templates

Reference file consumed by SKILL.md Step 10. Contains the persisted-to-engram

compact format and the per-dimension detail blocks emitted to the

conversational output.

Persisted to engram (compact)

Saved via mem_save with topic_key: sdd/{change-name}/verify-report, type: architecture, project: {project}. Only this content is persisted.

# Verification Report: [change-name]

Date: [YYYY-MM-DD]
Verdict: PASS / PASS WITH WARNINGS / FAIL

## Summary
| Dimension       | Status                          |
|-----------------|---------------------------------|
| Completeness    | OK / WARNING / CRITICAL         |
| Correctness     | OK / WARNING / CRITICAL         |
| Coherence       | OK / WARNING / CRITICAL         |
| Testing         | OK / WARNING / CRITICAL         |
| Test Execution  | OK / WARNING / CRITICAL / SKIPPED |
| Build           | OK / WARNING / SKIPPED          |

## Tool Execution
| Command       | Exit Code | Result               |
|---------------|-----------|----------------------|
| [command]     | [code]    | [PASS/FAIL/SKIPPED]  |

## Issues

### CRITICAL
- [issue description]
[or: "None."]

### WARNINGS
- [issue description]
[or: "None."]

The ## Tool Execution section is mandatory even when skipped. When skipped: "Test Execution: SKIPPED — no test runner detected".

Conversational output (NOT persisted)

These detail blocks are shown to the user only — they do NOT go in the persisted artifact. They cover Steps 2–9 of the audit and give the user full visibility.

Completeness block

### Completeness

| Metric               | Value |
|----------------------|-------|
| Total tasks          | [N]   |
| Completed tasks [x]  | [M]   |
| Incomplete tasks [ ] | [K]   |

Incomplete tasks:
- [ ] [number and description of each one]

Correctness block

### Correctness (Specs)

| Requirement | Status             | Notes                                 |
|-------------|--------------------|---------------------------------------|
| [Req 1]     | ✅ Implemented      |                                       |
| [Req 2]     | ⚠️ Partial          | Missing 401 error scenario            |
| [Req 3]     | ❌ Not implemented  | Endpoint /auth/refresh does not exist |

### Scenario Coverage

| Scenario                           | Status                               |
|------------------------------------|--------------------------------------|
| Successful login                   | ✅ Covered                            |
| Failed login — incorrect password  | ✅ Covered                            |
| Failed login — user does not exist | ⚠️ Partial — implemented but no test  |
| Expired token                      | ❌ Not covered                        |

Coherence block

### Coherence (Design)

| Decision            | Followed?     | Notes                                  |
|---------------------|---------------|----------------------------------------|
| Validation with Zod | ✅ Yes         |                                        |
| JWT with RS256      | ⚠️ Deviation   | HS256 used. Dev documented in tasks.   |
| Repository pattern  | ✅ Yes         |                                        |

Testing block

### Testing

| Area                | Tests Exist | Scenarios Covered |
|---------------------|-------------|-------------------|
| AuthService.login() | ✅ Yes       | 3/4 scenarios     |
| AuthController      | ✅ Yes       | Happy paths only  |
| JWT Middleware      | ❌ No        | —                 |

Spec Compliance Matrix

## Spec Compliance Matrix

| Spec Domain | Requirement        | Scenario        | Status     | Evidence                                       |
|-------------|--------------------|-----------------|------------|------------------------------------------------|
| [domain]    | [requirement name] | [scenario name] | COMPLIANT  | [evidence description]                         |
| [domain]    | [requirement name] | [scenario name] | FAILING    | [failing test name or output]                  |
| [domain]    | [requirement name] | [scenario name] | UNTESTED   | No test coverage found                         |
| [domain]    | [requirement name] | [scenario name] | PARTIAL    | [which clauses are covered and which are not]  |

Compliance statuses:

When no test runner exists: matrix is still produced using code inspection evidence from Step 3. Scenarios verified by code inspection only receive COMPLIANT or PARTIAL (never UNTESTED — code evidence was checked).

Suggestions block

### WARNINGS (should be resolved):
- [description]
  [or: "None."]

### SUGGESTIONS (optional improvements):
- [description]
  [or: "None."]