# Hlv Verify > 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". - Skill: `lee-to/hlv-verify` (Agent Skill) - Install (CLI): `npx skillmds@latest add lee-to/hlv-verify` - Raw SKILL.md: https://api.skillmd.com/api/skills/lee-to/hlv-verify/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: lee-to (https://skillmd.com/u/lee-to) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lee-to/hlv-verify --- # 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: 1. If `project.yaml` exists in the current project root, use greenfield layout: `CONFIG_ROOT = .`, `REPO_ROOT = .`. 2. Else if `.hlv/project.yaml` exists, use adopted layout: `CONFIG_ROOT = .hlv`, `REPO_ROOT = .`. 3. Else search upward for either `project.yaml` or `.hlv/project.yaml`. 4. Read `CONFIG_ROOT/project.yaml` first. HLV-owned paths such as `human/`, `validation/`, `llm/`, and `milestones.yaml` are relative to `CONFIG_ROOT`. 5. In the steps below, bare paths like `milestones.yaml` or `human/` mean `CONFIG_ROOT/milestones.yaml` and `CONFIG_ROOT/human/`. 6. 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 ` for deterministic validation. ## Milestone Resolution Read `milestones.yaml` → get `current.id`. Set `MID = human/milestones/{id}`. 1. Contracts: `{MID}/contracts/` 2. Test specs: `{MID}/test-specs/` 3. Traceability: `{MID}/traceability.yaml` 4. Plan: `{MID}/plan.md` + `{MID}/stage_N.md` 5. Open questions: `{MID}/open-questions.md` 6. Global context (read-only): `human/glossary.yaml`, `human/constraints/`, `validation/gates-policy.yaml` 7. 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 `# v` - [ ] 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`): - [ ] Required fields: id, version, intent, inputs_schema, outputs_schema, errors, invariants, nfr, security - [ ] ID matches filename - [ ] Version is valid semver - [ ] Constraint dependencies exist #### 1b. Validation specs structure For each test spec file (`{MID}/test-specs/*.md`): - [ ] `derived_from` points to existing contract - [ ] Each test case has unique ID format `TST--` 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--` - [ ] 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 ` 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 (`MAP-081`) #### 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] requires 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 #### 2b. Completeness - Every error case from contract has an example - Edge cases cover situations from artifacts (race conditions, concurrent access, boundary values) - NFR are realistic for the described architecture (e.g., 200ms p99 with 5-table JOIN — warn) - Security rules applied to all state-changing contracts #### 2c. Validation specs quality - Test specs cover all invariants, all errors, all edge cases from contract - Property-based tests have meaningful generators (not random bytes) - Integration scenarios cover cross-contract chains - Performance tests have realistic load profiles #### 2d. Plan feasibility - Each task realistically fits in 1 context window (contract + glossary + dependent code < ~100K tokens) - Tasks in parallel groups are truly independent - Phase ordering is logical (domain types → features → integration → NFR) - No tasks without contract linkage #### 2e. Artifacts-to-contracts coverage - Each artifact covered by at least one contract - Each significant assertion in artifact reflected in contract - No "phantom" requirements in contracts unsupported by artifacts ### Step 3: Output report Generate structured report: ``` === /hlv-verify report === ## Structure Validation Contracts: / valid pass/fail Test Specs: / valid pass/fail Traceability: complete/gaps pass/fail Plan: valid/issues pass/fail Open Questions: open / deferred pass if 0 open (deferred = warning) ## Semantic Review Consistency: issues found Completeness: gaps found Validation: issues found Plan: issues found Coverage: / artifacts covered ## Issues ### Critical (blocks /hlv-implement) 1. [CONTRACT] order.cancel expects status `pending` but order.create returns `created` — inconsistent state machine 2. [TRACE] REQ-ORDER-003 has no test mapping ### Warning (should fix) 1. [NFR] order.create p99=200ms with 3 table writes — tight, consider async 2. [COVERAGE] artifacts/research/competitor-analysis.md not covered by any contract ### Info 1. [PLAN] Task 3 and Task 4 could be parallelized (no shared deps) ## Verdict READY for /hlv-implement — or — NEEDS FIXES — critical issues, warnings ``` ## Output - `validation/verify-report.md` — full report - Console summary (abbreviated version) ### Step 4: Update milestone status If all checks pass (no errors, only warnings or info): - Update `milestones.yaml` (schema: `schema/milestones-schema.json`): set current stage status → `verified` - This signals that contracts are verified and ready for `/hlv-implement` If there are errors: - Do NOT update status — stage remains `pending` - List all errors and suggest fixes `/hlv-verify` acts as a quality gate between `/hlv-generate` and `/hlv-implement`. The stage must be `pending` or `verified` for `/hlv-implement` to proceed. ## Re-run `/hlv-verify` can be run repeatedly. Each run: 1. Overwrites `verify-report.md` 2. Shows diff with previous run (issues fixed, new issues) ## Integration with /hlv-generate Typical cycle: ``` /hlv-generate → /hlv-verify → fix issues → /hlv-verify → fix → /hlv-verify → READY ``` `/hlv-verify` never modifies contracts or plan. It only reads and reports. ## Cleanup After the skill completes: 1. Run `hlv doctor` to validate the environment and configuration. 2. Run `hlv check` to validate the project structure. If there are errors — fix them before finishing. Use `hlv explain ` when a diagnostic needs triage. 3. Run `hlv waivers audit` if `validation/waivers.yaml` exists. 4. 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. 5. Suggest the user run `/clear` to free up context window before the next skill.