lee-to/hlv/hlv-implement

HLV Implement — Plan to Code + Tests

Execute the implementation plan: agents perform tasks from milestone stage files in parallel, generating code and tests from contracts.

Step 0: Read Configuration

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

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

These flags control which sections below are active. If project.yaml has no features section, use defaults: the first three booleans are true, legacy_mode is false, and index_tracking is ignored. If features.legacy_mode is true, also read paths.code and query the signature index with hlv index show --json <symbol> or hlv index list --json --file <path> before changing observed legacy code. Legacy code stays in place; only new/changed milestone work must follow the full contract and marker flow.

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.

Adopt Mode

When legacy_mode is enabled, treat paths.code as observed brownfield code and .hlv/llm/ as HLV metadata. Do not relocate legacy files into llm/src or .hlv/llm/src. Before editing a legacy file, use the signature index to identify the relevant symbols, then apply the normal contract-driven workflow to the changed files.

CRITICAL: Code Architecture Philosophy

Conditional: `features.linear_architecture: true`

If linear_architecture is false in project.yaml, skip this entire section. Use your preferred architecture style instead.

The human DOES NOT read the generated code. The code is written FOR machines — LLM agents read it, LLM agents modify it, automated gates validate it.

This changes everything about how code is structured:

1. Comments are for LLM navigation. The contract IS the documentation. Comments in code are navigation markers for LLM, not explanations for humans. Format: // @ctx: stock validation for order.create contract. If something needs explaining — the contract is incomplete, go fix it.

1. Maximize LLM-readability. No layered architecture. Flat module structure. Explicit types everywhere. No "clever" patterns, no metaprogramming, no implicit behavior. No layered architecture — controller/service/repository is a pattern for humans. LLM writes linearly: input → validation → logic → output → errors. One file, one flow. An LLM agent with a 200K context window must understand any module in isolation.

1. One contract = one module boundary. Each contract maps to exactly one directory. All code for order.create lives in one directory. No cross-contract imports except through domain types.

1. Domain types are the shared language. domain/types is the ONLY shared code between features. Everything else is self-contained. Duplication across features is PREFERRED over coupling. Duplication is normal until it hurts: copy-paste between features is not refactored until it causes real problems (behavioral divergence, forgotten updates when contracts change).

1. Tests live next to code. Tests are in the same file as the code (#[cfg(test)] mod tests {} in Rust, equivalents in other languages). Every test traces back to a contract invariant, error case, or NFR via @hlv marker. No "just in case" tests. No test helpers that hide behavior. Test code is as explicit as production code. hlv check verifies every error code, invariant, and constraint rule has an @hlv <ID> marker in code. A separate configured integration-tests directory, when present, is only for cross-contract scenarios.

1. File names are arbitrary. `map.yaml` is the navigator. Files can be named 01.rs, handler.rs, f3a.rs — any name is valid. The file map (paths.llm.map from project.yaml) is the single source of truth about what each file does. LLM finds code by reading descriptions in map.yaml, not by file names. Descriptions MUST be sufficient to choose a file without reading it. Each file does one thing, <300 lines, fully replaceable by an LLM without understanding neighboring files.

1. No abstraction layers "for the future." No base classes, no generic frameworks, no plugin systems unless the contract explicitly requires extensibility. Write the simplest code that satisfies the contract. Three similar lines of code are better than a premature abstraction.

1. Error paths are first-class. Every error from the contract's Errors table has an explicit code path. No catch-all error handlers. No unwrap() / expect() in production code.

1. Deterministic PUBLIC API, free internal structure. Given the same contract, two different LLM agents MUST produce code with the same public API (function signatures, error types, inputs/outputs). Internal file structure, naming, and organization are at the agent's discretion. map.yaml describes what lives where.

1. Machine-verifiable correctness. Every invariant must be testable by property-based tests. Every NFR must be measurable. If it can't be automatically verified — it doesn't belong in code, it belongs in the contract's open questions.

Prerequisites

• /hlv-verify passed without critical issues
• Plan contains tasks
• All open questions closed (or deferred with waiver)

• milestones.yaml exists with a current section
• Current stage status is pending, verified, or validating (remediation)
• Stage file ({MID}/stage_N.md) contains tasks

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

Input

milestones.yaml              # entry point — read FIRST
project.yaml                 # global config (stack, paths)
{paths.llm.map}              # project file map — update when creating files (read path from project.yaml)
human/
  glossary.yaml              # domain types (read-only)
  constraints/*.yaml         # global constraints (read-only)
  milestones/{id}/
    contracts/*.md           # contracts to implement
    contracts/*.yaml         # contracts (YAML format)
    test-specs/*.md          # test specifications
    plan.md                  # overview (stages table)
    stage_N.md               # current stage — tasks, dependencies
validation/
  gates-policy.yaml          # gate thresholds
  scenarios/*.md             # cross-milestone integration scenarios

Steps

Step 1: Read project map and load milestone context

1. Read project.yaml (global config: stack, paths)

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

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

• Greenfield/generated projects: LLM_SRC = paths.llm.src and LLM_TESTS = paths.llm.tests when configured.
• Adopted projects without paths.llm.src: use paths.code.src / paths.code.tests as the editable project code roots; do not create .hlv/llm/src.
• LLM_MAP = paths.llm.map (e.g. llm/map.yaml)

All subsequent steps MUST use these variables. Never assume `llm/src/` — always use the configured project paths.

> HARD CONSTRAINT — Output directory isolation > In greenfield mode, generated code and tests MUST stay inside configured paths.llm roots. > In adopt mode, existing project code roots from paths.code are editable; .hlv/llm/ is metadata, not source code. > hlv check enforces this mechanically with MAP-080 for implementation paths outside LLM_SRC and MAP-081 for test paths outside LLM_TESTS.

1. Read milestones.yaml → get current.id and current.stage (current stage number)
2. Set MID = human/milestones/{current.id}
3. Find the current stage in current.stages[] by matching the stage number
4. STATUS GATE (hard stop):

• Read stage status
• Allowed values to proceed: pending, verified, implementing, validating
• pending — implementation without prior /hlv-verify
• verified — normal implementation after /hlv-verify passed
• implementing — re-run, continue from pending tasks
• validating — remediation: /hlv-validate found gate failures and added FIX tasks to stage_N.md Remediation section. Execute only pending remediation tasks.
• implemented or validated — this stage is done. Check if there's a next stage to advance to, or inform user.

1. Update stage status → implementing in milestones.yaml (schema: schema/milestones-schema.json)
2. Read {MID}/stage_N.md — load tasks for the current stage
3. Read project.yaml → stack.components — understand target languages, frameworks
4. Read project.yaml → artifact_graph.code_ownership when present. New or changed implementation/test/doc paths must preserve ownership mappings and relation fields (implements, verifies, documents, requires) so hlv artifacts impact can route downstream review.

• code-* ownership and implements paths must remain under LLM_SRC.
• tests-* ownership and verifies paths must remain under LLM_TESTS.

1. For every new or changed file under an artifact ownership path, add file-level evidence markers for the relevant relation, e.g. @hlv:artifact code-auth implements spec-auth, @hlv:artifact tests-auth verifies spec-auth, or @hlv:artifact docs-auth documents spec-auth. Use the native comment syntax for the file type.

Step 2: Execute tasks

/hlv-implement works on ONE stage at a time. The current stage is determined by milestones.yaml → current.stage.

Tasks within a stage execute based on their dependency graph (topological sort):

• Tasks without unresolved depends_on → execute in parallel
• Tasks with depends_on → wait for predecessors

stage = read {MID}/stage_N.md
ready_tasks = tasks with no pending depends_on
 
while ready_tasks not empty:
  for task in ready_tasks (parallel):
    1. Load context: contract from {MID}/contracts/, glossary, test spec from {MID}/test-specs/, dependency outputs
    2. Generate code + tests within declared output paths (`LLM_SRC`, `LLM_TESTS`)
    3. Run local checks: compile, lint, unit tests
    4. Mark task completed in stage_N.md
 
  ready_tasks = recalculate from remaining pending tasks
 
Boundary: git commit after all stage tasks completed
Update milestones.yaml: stage status → implemented

After completing a stage, inform the user: "Stage N complete. Run /hlv-validate to check gates, or /hlv-implement for the next stage."

Step 3: Agent protocol

Each agent when executing a task: