lee-to/hlv/hlv-validate

HLV Validate — Run Gates, Decide Release

Execute all mandatory validation gates defined in gates-policy.yaml. Collect results, update project status, produce release decision. The gate set depends on the project profile — do NOT assume a fixed number of gates.

Step 0: Read Configuration

Before proceeding, read project.yaml → features and note the flag values:

• features.hlv_markers (default: true)
• features.security_markers (default: true)
• features.legacy_mode (default: false)
• features.index_tracking (default: ignored)

These flags control whether marker-related validation (Step 3b, 3c) is active. If features.legacy_mode is true, read paths.code and treat untouched legacy code as observed context; the full contract and marker flow applies to new or changed milestone work.

Adopt Mode

For adopted projects, run gates against the configured project commands and changed milestone work. Untouched legacy code is not required to gain @hlv or @hlv:sec markers unless the project explicitly enables those marker flags or the file is part of the current change.

Prerequisites

• All tasks in current stage completed
• Code and inline tests live in configured project paths: paths.llm.src/tests for greenfield/generated projects, or paths.code.src/tests for adopted projects without paths.llm.src.
• validation/gates-policy.yaml contains gate definitions
• milestones.yaml exists with current stage status implemented

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 --structural-only --root <REPO_ROOT> for deterministic prerequisites; enforce the full check after runner execution/evidence publication in /hlv-validate.

Input

milestones.yaml               # entry point — read FIRST
project.yaml                  # global config (stack for context)
{paths.llm.src or paths.code.src}     # code (unit tests inline in same files) — read from project.yaml
{paths.llm.tests or paths.code.tests} # integration tests only — read from project.yaml
 
validation/
  gates-policy.yaml            # thresholds and criteria
  scenarios/*.md               # cross-milestone integration scenarios (Phase 2)
 
human/
  glossary.yaml                # domain types
  constraints/*.yaml           # global constraints
  milestones/{id}/
    contracts/*.md             # contracts (for NFR comparison)
    test-specs/*.md            # test specifications
    stage_N.md                 # current stage (for remediation tasks)

Note: project.yaml → stack provides tech stack context (languages, frameworks, databases) which can inform gate execution — e.g., choosing the correct test runner, SAST tool, or dependency scanner per component.

Note: project.yaml → artifact_graph and artifact frontmatter provide impact-analysis context. Before validating a PR-like change, run hlv artifacts impact --changed --base <target-branch> (or hlv artifacts impact --changed for local worktree review) and ensure every downstream item has an explicit review disposition outside HLV (updated, reviewed-ok, deferred, obsolete, or unknown). In CI, make sure the checkout can compute a merge base by fetching the target branch or using sufficient history such as actions/checkout with fetch-depth: 0. Treat missing dispositions as a review blocker even when deterministic gates pass.

Steps

Step 1: Pre-flight and gate status

1. Run hlv doctor to catch missing paths, invalid command strings, cwd problems, schema mismatch, and non-ASCII rendering issues before executing gates.
2. Read project.yaml (global config: stack, paths)

• Note validation.strictness when present (relaxed, standard, strict). Default is standard.

1. Bind code paths from `project.yaml`:

• LLM_SRC = paths.llm.src and LLM_TESTS = paths.llm.tests when present.
• In adopt mode without paths.llm.src, use paths.code.src and paths.code.tests; .hlv/llm/ is metadata only.
• LLM_MAP = paths.llm.map (e.g. llm/map.yaml)

All gate execution, code scanning, and marker checks MUST target configured project roots — not hardcoded paths.

1. Run hlv check --strict --structural-only --json --root <REPO_ROOT> for preflight. Require exit code 0: fix MAP-080/MAP-081, invalid evidence configuration/bindings (PRJ-100, EVD-010), and all other structural/configuration errors before executing gates. This mode executes no gate or constraint commands and reports configured execution evidence as not_checked. Expected missing/stale evidence from a first run or changed inputs is deferred; do not require a successful old run before producing its replacement. Do not use a full hlv check --strict at this step.
2. Read milestones.yaml → get current.id, current.stage, and stage status
3. STATUS GATE (hard stop):

• Allowed stage statuses to proceed: implemented, validating
• implemented — normal validation after /hlv-implement
• validating — re-run, execute failed/skipped gates
• pending, verified, or implementing — stage not ready:

``` STOP. Cannot run /hlv-validate.

Current stage status: <status> Required: implemented

Finish /hlv-implement for this stage first. ```

• validated — this stage already passed, inform user

1. Read validation/gates-policy.yaml
2. Install required tooling: read project.yaml → stack to determine the language/ecosystem, then for each gate that will run, ensure required tools are available. Install missing ones silently:

• Do NOT ask the human to install tools. The human writes artifacts, not pip install.

1. Verify code compiles (cargo build / npm run build / language-appropriate check)
2. Update stage status → validating in milestones.yaml (schema: schema/milestones-schema.json)

Step 2: Execute gates

Capture execution evidence inputs before running

If project.yaml.execution_evidence is configured:

1. After tooling, build preparation and stage-status updates, run hlv evidence snapshot --root <REPO_ROOT> before any test runner executes. Save the original snapshots outside declared input scopes. Capture must succeed; missing/unreadable code or test inputs now block execution even though they may be planned during /hlv-verify.
2. Associate each configured binding with the actual test invocation and its external run/code revision identity. A gate's exit code alone does not establish that every mapped test ran.
3. Run the existing runners below and retain their actual outcomes and observation/report artifacts. Compatible records for bindings that are not rerun may be preserved; every missing/stale binding needs a new run, including those whose old gate status was passed.
4. Publish the records in Step 3, then enforce the full evidence check in Step 3d. Structural preflight success is never release approval.

Two-phase validation

Phase 1 — Milestone gates (automatic): Run all gates from gates-policy.yaml against the contracts and code of the current milestone. Test specs come from {MID}/test-specs/.

Phase 2 — Global gates (with user confirmation): After Phase 1 passes, ask: "Milestone gates passed. Run global integration scenarios? [y/n]" If yes → run validation/scenarios/*.md (cross-milestone integration tests). If no → skip Phase 2. Phase 1 can approve the milestone only if the final check in Step 3d passes; a configured evidence binding for a skipped test must not be marked passed.

Gate execution

Read gates from gates-policy.yaml and execute only the gates defined there, in order. Different projects have different gate sets depending on their profile — do NOT assume a fixed list.

Result per gate: passed | failed | skipped (skipped ONLY if tool install failed, not because tool was missing).

Gate type reference

For each gate, determine how to run it based on its type field:

For each gate in the file:

1. Read type and pass_criteria
2. Look up the runner and source from the table above
3. Execute and collect results
4. Compare against pass_criteria thresholds

Step 3: Collect results

gate_results:
  - gate: GATE-CONTRACT-001
    status: passed
    details:
      total: 12
      passed: 12
      failed: 0
  - gate: GATE-PBT-001
    status: passed
    details:
      invariants_tested: 5
      total_generations: 50000
      counterexamples: 0
  # ... etc.

When execution evidence is configured, also:

1. Capture a second hlv evidence snapshot after execution and compare it with the original pre-run snapshots. If scoped inputs changed, discard the affected success or publish incomplete; rerun against a newly captured snapshot before release.
2. Publish one current record per binding atomically at the configured manifest path. Each new record contains the original snapshot, the actual outcome, run/code revision identities, terminal timestamp and artifact reference. Failed/incomplete/skipped runs remain non-passing; never refresh an old success by replacing its hashes.
3. Keep ordinary runner artifacts in validation/gate-results/ outside input scopes. Use them as evidence references, not as inferred successes.

Step 3b: Constraint rule coverage

Conditional: `features.hlv_markers: true`

If hlv_markers is false in project.yaml, skip the @hlv marker check below. hlv check will not produce CTR-010 diagnostics. Still run check_command-based rules (CST-050/CST-060) as those are independent of markers.