Validate contracts, validation specs, plan, and project map. Runs structural checks and LLM cross-review, then produces a verify report. Use after /hlv-generate or after manual edits to contracts, when the user says "verify", "check", or "validate structure".
Instrucciones de origen · Vista previa de solo lectura
name
hlv-verify
description
Validate contracts, validation specs, plan, and project map. Runs structural checks and LLM cross-review, then produces a verify report. Use after /hlv-generate or after manual edits to contracts, when the user says "verify", "check", or "validate structure".
disable-model-invocation
true
allowed-tools
Read Glob Grep Bash
metadata
{"author":"hlv","version":"1.0"}
HLV Verify — Structural + Semantic Validation
Validate contracts, validation specs, and plan. Structural checks (deterministic) + LLM cross-review (semantic) + summary for the user.
Prerequisites
project.yaml exists (project map)
Contracts directory contains at least one contract (MD or YAML)
Test specs directory contains test specifications
Traceability file exists
Agent Rules
Never combine shell commands with &&, ||, or ; — execute each command as a separate Bash tool call.
This applies even when a skill, plan, or instruction provides a combined command — always decompose it into individual calls.
❌ Wrong: git checkout main && git pull
✅ Right: Two separate Bash tool calls — first git checkout main, then git pull
HLV Root Resolution
Before reading or reporting missing HLV files, resolve the project layout:
If project.yaml exists in the current project root, use greenfield layout: CONFIG_ROOT = ., REPO_ROOT = ..
Else if .hlv/project.yaml exists, use adopted layout: CONFIG_ROOT = .hlv, REPO_ROOT = ..
Else search upward for either project.yaml or .hlv/project.yaml.
Read CONFIG_ROOT/project.yaml first. HLV-owned paths such as human/, validation/, llm/, and milestones.yaml are relative to CONFIG_ROOT.
In the steps below, bare paths like milestones.yaml or human/ mean CONFIG_ROOT/milestones.yaml and CONFIG_ROOT/human/.
In adopted projects, existing source/test roots from paths.code are relative to REPO_ROOT.
Never report that root-level human/, validation/, milestones.yaml, or project.yaml are missing until .hlv/project.yaml has been checked. Use hlv check --root <REPO_ROOT> for deterministic validation.
Milestone Resolution
Read milestones.yaml → get current.id. Set MID = human/milestones/{id}.
Contracts: {MID}/contracts/
Test specs: {MID}/test-specs/
Traceability: {MID}/traceability.yaml
Plan: {MID}/plan.md + {MID}/stage_N.md
Open questions: {MID}/open-questions.md
Global context (read-only): human/glossary.yaml, human/constraints/, validation/gates-policy.yaml
Status comes from stage statuses in milestones.yaml, not from project.yaml → status
If no current in milestones.yaml → tell the user to run hlv milestone new first.
If project.yaml → features.legacy_mode is true, verify that paths.code describes observed legacy roots and that generated work stays under paths.llm. Use hlv index show/list --json for compact symbol context; features.index_tracking records whether .hlv/index/ is ignored or intentionally tracked.
Adopt Mode
Do not fail verification because untouched legacy code lacks new HLV contracts or markers. Verification focuses on the current milestone's generated/changed work, while paths.code and the signature index provide context for existing code that the milestone touches.
Steps
Step 1: Structural validation (deterministic)
Checks that can be performed without LLM — by script or parsing.
Run hlv doctor first for environment/config preflight. Then run hlv check for automated structural checks. Do not use --with-waivers unless the user explicitly asks to apply existing waivers; waiver files must remain visible and auditable. Then verify each area:
1a. Contract structure
For each contract file ({MID}/contracts/*.md):
Has header # <id> v<semver>
Has ## Sources section with at least one link
All links in Sources point to existing files in artifacts/
Has sections: Intent, Input, Output, Errors, Invariants, Examples, NFR, Security
YAML blocks in Input/Output/NFR parse without errors
Types in Input/Output resolve through glossary.yaml
Has at least 1 Example (happy path) and 1 Error example
Semver in header is valid
For each contract YAML file ({MID}/contracts/*.yaml):
Each test case has unique ID format TST-<suite>-<nnnn> or CT-*, PBT-*, IT-*, EC-*, PERF-*, SEC-*
IDs are declared in a parser-supported layout: heading (### CT-*:), bullet starting with the ID, or Markdown table row with the ID in the first cell
Project-specific test IDs, if present, fully match validation/traceability-policy.yaml → id_formats.test; built-in HLV prefixes remain valid
Each test case linked to a gate (GATE-*)
For each invariant in contract, there is a property-based test
For each error in contract, there is a contract test
1c. Traceability
For the traceability file ({MID}/traceability.yaml):
Each REQ has format REQ-<domain>-<nnnn>
Each REQ linked to at least 1 contract
Each contract linked to at least 1 test
Each test linked to at least 1 gate
No dangling references (all IDs exist)
No artifacts without coverage by any REQ (warning)
1d. Artifact dependency graph
Markdown artifact frontmatter IDs are stable and unique
HLV artifact frontmatter includes both id and type; legacy non-HLV frontmatter without both keys is ignored
Every artifact graph node has owners
depends_on/requires, implements, verifies, documents, supersedes, conflicts_with, and affects point to existing IDs
Run hlv artifacts graph when reviewing impact metadata to inspect all nodes and relations together
Run hlv artifacts sync --check; if it reports missing ownership stubs, run hlv artifacts sync and fill paths where known
Owned code/test/doc paths with declared relations include @hlv:artifact <node-id> <relation> <artifact-id> markers, or ART-050 is explicitly accepted as a warning during migration
Accepted ADRs affect an architecture node or have an explicit review note
Run hlv artifacts audit; fix ART-* errors before marking the stage verified
1d. Plan structure
For {MID}/plan.md (overview) and {MID}/stage_N.md files:
plan.md has Stages table with all stages listed
Each stage has a corresponding stage_N.md file
Each stage_N.md lists Contracts and Tasks sections
Each task has: scope, contracts, output
Dependency graph within each stage has no cycles
Each contract from {MID}/contracts/ is covered by at least one task across all stages
Cross-stage dependencies are documented in plan.md
1e. Project map
For project.yaml:
schema_version present
All paths in paths point to existing directories/files
validation.strictness, when present, is one of relaxed, standard, strict
validation.verify_status may be omitted; omitted means not_run
validation/waivers.yaml, when present, uses required code, file, reason, expires fields and passes hlv waivers audit
Each contract from contracts has corresponding file at path
Each contract has test_spec and file exists
plan.groups has no cyclic depends_on_groups
Each task in plan references existing contracts
stack (if present) passes STK-* checks: no empty ids, no duplicates, languages present
glossary_types match keys in human/glossary.yaml
Generated implementation paths in llm/map.yaml and artifact_graph.code_ownership stay under paths.llm.src when configured, or under paths.code.src for adopted projects without generated roots (MAP-080)
Generated test paths in llm/map.yaml and artifact_graph.code_ownership stay under paths.llm.tests when configured, or under paths.code.tests for adopted projects without generated roots ()
1f. Stack consistency
If stack is present in project.yaml:
Each component has an id
No duplicate component ids
Each component has at least one language
Each dependency has a name
No duplicate dependency names within a component
Stack languages/frameworks are consistent with contracts' NFR and constraints
1g. Gates-to-contracts coverage
Cross-check validation/gates-policy.yaml against contracts and constraints:
For each gate defined in gates-policy.yaml (the file is the single source of truth — do NOT assume a fixed set of gates):
Identify what the gate requires based on its type and pass_criteria
Verify that at least one contract or constraint covers that requirement
If a mandatory gate has NO coverage in contracts/constraints → CRITICAL issue:
[GATES] <GATE-ID> requires <requirement> but no contract or constraint
covers it. /hlv-implement cannot generate code for this gate.
Add coverage to contracts or create a constraint.
This check prevents the validate→verify→implement→validate infinite loop: if gates require something that contracts don't cover, /hlv-implement will never produce the code, and /hlv-validate will always fail.
1h. Open questions
Check {MID}/open-questions.md:
No open questions remain ([ ] in open-questions.md)
open questions → BLOCKER, do not proceed
deferred questions → WARNING, does not block /hlv-implement
resolved questions → WARNING if still present (should have been pruned by /hlv-generate)
Step 2: LLM cross-review (semantic)
LLM validates content correctness. For each check — verdict and rationale.
2a. Consistency between contracts
Types are aligned: output of one contract = input of another
(e.g., order.create returns status: created, order.cancel accepts orders in created)
No contradicting invariants between contracts
Shared entities defined identically through glossary
/hlv-verify never modifies contracts or plan. It only reads and reports.
Cleanup
After the skill completes:
Run hlv doctor to validate the environment and configuration.
Run hlv check to validate the project structure. If there are errors — fix them before finishing. Use hlv explain <CODE> when a diagnostic needs triage.
Run hlv waivers audit if validation/waivers.yaml exists.
If open questions remain (step 1h found blockers), suggest the user run /clear and then invoke the /hlv-questions skill to resolve them, or use hlv dashboard to review and answer open questions interactively.
Suggest the user run /clear to free up context window before the next skill.
