speckit-verify-run

name	speckit-verify-run
description	Perform a non-destructive post-implementation verification gate validating the implementation against spec.md, plan.md, tasks.md, and constitution.md.
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"verify:commands/verify.md"}

User Input

$ARGUMENTS

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

Goal

Validate the implementation against its specification artifacts (spec.md, plan.md, tasks.md, constitution.md). This command MUST run only after /speckit.implement has completed.

Operating Constraints

STRICTLY READ-ONLY: Do not modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).

Constitution Authority: The project constitution (.specify/memory/constitution.md) is non-negotiable within this verification scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, tasks or implementation—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside /speckit.verify.run.

Execution Steps

1. Initialize Verification Context

Run .specify/scripts/bash/check-prerequisites.sh --json --paths-only from repo root.

1. Script succeeds: Parse JSON for FEATURE_DIR and BRANCH. Paths-only mode does not validate the branch; set FEATURE_BRANCH = true only when BRANCH is a feature branch. If BRANCH is detached, main, or otherwise non-feature, scan specs/NNN-*/, ask the user to choose the intended feature, and set FEATURE_BRANCH = false.
2. Script fails: You MUST prompt for available features (Scan specs/NNN-*/ to get available features). Use Codex's structured request_user_input path if it is available; otherwise ask one concise plain-text selection question and wait for the user. Do NOT guess or auto-select a change. Always let the user choose.

Derive absolute paths:

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md.

Abort if any required file is missing (instruct the user to run missing prerequisite command). For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

2. Load Configuration

Run the load-config script (.specify/extensions/verify/scripts/bash/load-config.sh or .specify/extensions/verify/scripts/powershell/load-config.ps1) from the repo root. Parse the max_findings value from its output and store it for use in Step 6. If the script fails, abort and relay its error message to the user.

3. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

From spec.md:

• User Scenarios & Testing (user stories, acceptance scenarios, priorities)
• Edge Cases
• Functional Requirements
• Success Criteria / Measurable Outcomes (performance, security, availability, observability targets)
• Assumptions

From plan.md:

• Architecture/stack choices
• Technical constraints
• Technical Context (language, dependencies, storage, testing, platform, constraints)
• Project Structure (documentation layout and source code layout)

From data-model.md (if present):

• Entity names, fields, and relationships
• Validation rules
• State transitions

From tasks.md:

• Task IDs
• Completion status
• Descriptions
• Phase grouping
• Referenced file paths

From constitution:

• Load .specify/memory/constitution.md for principle validation

4. Identify Implementation Scope

Build the set of files to verify from tasks.md.

• Parse all tasks in tasks.md — both completed ([x]/[X]) and incomplete ([ ])
• Extract file paths referenced in each task description
• Build REVIEW_FILES set from completed task file paths
• Track INCOMPLETE_TASK_FILES from incomplete tasks (used by check C)

5. Build Semantic Models

Create internal representations (do not include raw artifacts in output):

• Task inventory: Each task with ID, completion status, referenced file paths, and phase grouping
• Implementation mapping: Map each completed task to its referenced file paths
• File inventory: All REVIEW_FILES with existence verification — flag any task-referenced file that does not exist on disk
• Requirements inventory: Each functional requirement with a stable key — map to tasks and REVIEW_FILES for implementation evidence (evidence = file in REVIEW_FILES containing keyword/ID match, function signatures, or code paths that address the requirement)
• Spec intent references: User stories, acceptance criteria, scenarios, edge cases, and code-verifiable success criteria from spec.md
• Constitution rule set: Extract principle names and MUST/SHOULD normative statements

6. Verification Checks (Token-Efficient Analysis)

Focus on high-signal findings. Limit to the configured max_findings value (loaded in Step 2); aggregate remainder in overflow summary.

A. Task Completion

• Compare completed ([x]/[X]) vs total tasks
• Flag majority incomplete vs minority incomplete

B. File Existence

• Task-referenced files that do not exist on disk
• Tasks referencing ambiguous or unresolvable paths

C. Requirement Coverage

• Requirements with no implementation evidence in REVIEW_FILES
• Requirements whose tasks are all incomplete

D. Scenario & Test Coverage

• Spec scenarios with no corresponding test or code path
• Edge cases with no corresponding test, guard clause, or error-handling code path
• No test files detected at all in REVIEW_FILES

E. Spec Intent Alignment

• Implementation diverging from spec intent (minor vs fundamental divergence)
• Compare acceptance criteria against actual behaviour in REVIEW_FILES
• Code-verifiable success criteria (performance, security, availability, observability) with no evidence of implementation support — skip business/UX metrics that require post-deployment measurement

F. Constitution Alignment

• Any implementation element conflicting with a constitution MUST principle
• Missing mandated sections or quality gates from constitution

G. Design & Structure Consistency

• Architectural decisions or design patterns from plan.md not reflected in code
• Planned directory/file layout deviating from actual structure
• New code deviating from existing project conventions (naming, module structure, error handling patterns)
• Public APIs/exports/endpoints not described in plan.md

7. Severity Assignment

Use this heuristic to prioritize findings:

• CRITICAL: Violates constitution MUST, majority of tasks incomplete, task-referenced files missing from disk, requirement with zero implementation
• HIGH: Spec intent divergence, fundamental implementation mismatch with acceptance criteria, missing scenario/test coverage
• MEDIUM: Design pattern drift, minor spec intent deviation
• LOW: Structure deviations, naming inconsistencies, minor observations not affecting functionality

8. Produce Compact Verification Report

Output a Markdown report (no file writes) with the following structure.

If FEATURE_BRANCH = false, prepend: > ⚠️ **Non-Feature-Branch Verification** from \` against `<FEATURE_DIR>`. Some checks may be affected by cross-feature interference.`

Verification Report

ID	Category	Severity	Location(s)	Summary	Recommendation
A1	Task Completion	CRITICAL	tasks.md	3 of 12 tasks incomplete	Complete tasks T05, T08, T11
B1	File Existence	CRITICAL	src/auth.ts	Task-referenced file missing	Create file or update task reference
C1	Requirement Coverage	CRITICAL	spec.md:FR-003	No implementation evidence	Implement FR-003

(Add one row per finding; generate stable IDs prefixed by check letter: A1, B1, C1... Reference specific files and line numbers in Location(s) where applicable.)

Task Summary Table:

Task ID	Status	Referenced Files	Notes

Constitution Alignment Issues: (if any)

Metrics:

• Total Tasks (completed / total)
• Requirement Coverage % (requirements with implementation evidence / total)
• Files Verified
• Critical Issues Count

9. Provide Next Actions

At end of report, output a concise Next Actions block:

• If CRITICAL issues exist: Recommend resolving before proceeding
• If HIGH issues exist: Recommend addressing before merge; user may proceed at own risk
• If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
• Provide explicit command suggestions: e.g., "Run /speckit.implement to address findings and re-run verification", "Implementation verified — ready for review or merge"

10. Offer Remediation

Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)

Operating Principles

Context Efficiency

• Minimal high-signal tokens: Focus on actionable findings, not exhaustive documentation
• Progressive disclosure: Load artifacts and source files incrementally; don't dump all content into analysis
• Token-efficient output: Limit findings table to the configured max_findings value; summarize overflow
• Deterministic results: Rerunning without changes should produce consistent IDs and counts

Analysis Guidelines

• NEVER modify files (this is read-only analysis)
• NEVER hallucinate missing sections (if absent, report them accurately)
• Prioritize constitution violations (these are always CRITICAL)
• Use examples over exhaustive rules (cite specific instances, not generic patterns)
• Report zero issues gracefully (emit success report with coverage statistics)