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 <REPO_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 # <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):

• 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-<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 (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] <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

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:     <N>/<N> valid    pass/fail
Test Specs:    <N>/<N> valid    pass/fail
Traceability:  complete/gaps    pass/fail
Plan:          valid/issues     pass/fail
Open Questions: <N> open / <N> deferred   pass if 0 open (deferred = warning)

## Semantic Review
Consistency:   <N> issues found
Completeness:  <N> gaps found
Validation:    <N> issues found
Plan:          <N> issues found
Coverage:      <N>/<N> 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 — <N> critical issues, <N> 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 <CODE> 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.