{"id":46963650,"url":"https://github.com/lee-to/hlv","last_synced_at":"2026-06-27T11:00:25.910Z","repository":{"id":343660965,"uuid":"1177076404","full_name":"lee-to/hlv","owner":"lee-to","description":"Specs first. Code second. Proof always.  You define the what. LLMs generate the how. hlv validates the proof.","archived":false,"fork":false,"pushed_at":"2026-06-08T09:16:26.000Z","size":5510,"stargazers_count":74,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-08T11:13:39.248Z","etag":null,"topics":["ai","aiworkflow","sdd","spec-driven-development","vsdd"],"latest_commit_sha":null,"homepage":"https://hlv.cutcode.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lee-to.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-09T17:08:36.000Z","updated_at":"2026-06-08T09:15:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lee-to/hlv","commit_stats":null,"previous_names":["lee-to/hlv"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/lee-to/hlv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lee-to%2Fhlv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lee-to%2Fhlv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lee-to%2Fhlv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lee-to%2Fhlv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lee-to","download_url":"https://codeload.github.com/lee-to/hlv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lee-to%2Fhlv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34850575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","aiworkflow","sdd","spec-driven-development","vsdd"],"created_at":"2026-03-11T10:07:23.431Z","updated_at":"2026-06-27T11:00:25.897Z","avatar_url":"https://github.com/lee-to.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![logo](https://github.com/lee-to/hlv/raw/master/docs/assets/promo.png)\n\n# hlv\n\n[![Test](https://github.com/lee-to/hlv/actions/workflows/test.yml/badge.svg)](https://github.com/lee-to/hlv/actions/workflows/test.yml)\n[![Lint](https://github.com/lee-to/hlv/actions/workflows/lint.yml/badge.svg)](https://github.com/lee-to/hlv/actions/workflows/lint.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**Specs first. Code second. Proof always.**\n\n\u003e [!WARNING]\n\u003e This project is under active development. Breaking changes may happen between releases.\n\nYou define the *what*. LLMs generate the *how*. hlv validates the *proof*.\n\nA compiled Rust binary that keeps LLM-generated code on a leash — validating every file, every milestone, every gate in seconds. Because prompts are not guarantees.\n\n```\nintent → artifacts → contracts → code → hlv check → proof\n```\n\n## The problem\n\nYou paste context into chat, hope the agent understood everything, then spend days chasing inconsistencies across files you barely reviewed.\n\nLLMs generate code fast. But without machine-checkable invariants, you're left with:\n- **No traceability** — which requirement produced which code?\n- **No verification** — did the LLM actually follow the spec?\n- **No gates** — what stops broken code from advancing?\n\n## The solution: three layers, hard boundaries\n\nHLV separates every project into three layers with strict ownership:\n\n| Layer | Owner | Responsibility |\n|-------|-------|----------------|\n| **WHAT** | Human | Artifacts, constraints, milestones — everything the LLM needs, expressed in declarative files |\n| **HOW** | LLM | All code. Every line. Generated from specs, disposable, regenerated on demand |\n| **PROOF** | hlv | Machine-checkable validation. Every field, type, constraint, and invariant verified |\n\n\u003e Code is never the source of truth. Contracts are.\n\n## What hlv does\n\nhlv is a compiled Rust binary. It doesn't call the LLM. It doesn't generate code. It makes sure LLM output matches the spec.\n\n```\n$ hlv check\n\n── Contracts ──\n  ✓  14 contracts found, all valid\n  ✓  acceptance criteria present on every contract\n  ✖  contract/api-auth.md missing dependency link\n\n── Traceability ──\n  ✓  all code files traced to a contract\n  ✓  no unlinked deliverables detected\n\n── Status ──\n  FAILED · 29/30 passed, 1 failure\n```\n\n### 30+ validations across 8 domains\n\n| Domain | What it checks |\n|--------|---------------|\n| **Project map** | `project.yaml` structure and paths |\n| **Contracts** | MD sections, YAML blocks, glossary refs, version alignment |\n| **Test specs** | `derived_from` refs, unique IDs, gate coverage |\n| **Traceability** | REQ → CTR → TST → GATE chains, no dangling refs |\n| **Plan** | DAG without cycles, contract coverage |\n| **Code traceability** | `@hlv` markers in code match contract rules (skipped when `features.hlv_markers: false`) |\n| **Security markers** | `@hlv:sec` attention markers by category (skipped when `features.security_markers: false`) |\n| **LLM map** | every `map.yaml` entry exists on disk; generated source/tests stay inside `paths.llm` |\n| **Constraints** | rule IDs, severity validation |\n\nPhase-aware: checks expected at the current phase are automatically downgraded to info. Use `hlv check --strict` in CI to promote warnings to errors.\n\n### Key commands\n\n| Command | What it does |\n|---------|-------------|\n| `hlv init` | Scaffold the full HLV directory structure (asks for feature flags) |\n| `hlv doctor` | Preflight paths, schema compatibility, command portability, cwd values, and rendering |\n| `hlv check` | Run the full validation suite — specs, gates, deps, coverage |\n| `hlv explain \u003cCODE\u003e` | Explain a diagnostic and common fixes |\n| `hlv waivers` | List and audit explicit expiring diagnostic waivers |\n| `hlv milestone` | Track progress across milestones |\n| `hlv workflow` | See where you are and what the next step is |\n| `hlv gates` | Enforce quality gates before milestone transitions |\n| `hlv constraints` | Define cross-cutting rules as YAML configs |\n| `hlv dashboard` | Full TUI with 5 tabs — Status, Contracts, Plan, Gates, Questions |\n| `hlv trace --visual` | Visualize REQ → CTR → TST → GATE chains |\n| `hlv plan --visual` | ASCII dependency graph with critical path |\n| `hlv task` | Task lifecycle (start/done/block/unblock) |\n| `hlv mcp` | Start MCP server (stdio or HTTP) |\n| `hlv workspace` | Manage MCP workspace (init/add/remove/list) |\n| `hlv update` | Self-update to the latest release from GitHub |\n\nAll commands support `--json` for programmatic access.\n\n## 5-minute quickstart\n\n```bash\n# 1. Create milestone\n$ hlv milestone new add-payments\n✓ Milestone created: add-payments\n\n# 2. Capture intent (AI-driven interview)\n$ /artifacts\n✓ Intent captured: 8 decisions recorded\n\n# 3. Generate specs\n$ /generate\n✓ Generated: contracts, plan (4 stages), gates-policy\n\n# 4. Resolve questions, verify, check\n$ /questions \u0026\u0026 /verify \u0026\u0026 hlv check\n✓ All gates passed — ready to implement\n\n# 5. Implement stage by stage\n$ /implement\n◐ stage 1/4 ████████████████████ ✓ validated\n  stage 2/4 ████████████░░░░░░░░ implementing\n\n# 6. Validate and ship\n$ /validate\n✓ All gates passed across all 4 stages\n\n$ hlv milestone done add-payments\n✓ Ready to ship.\n```\n\n## Why strictly typed languages\n\nHLV is designed for **Rust, Go, TypeScript strict, Kotlin, Java** — languages where the compiler is another enforcement layer.\n\nEach layer catches a different class of drift:\n- **Contracts** catch requirement drift\n- **Type system** catches structural drift\n- **`@hlv` markers** catch traceability drift\n- **`hlv check`** catches coverage drift\n- **Validation gates** catch integration drift\n\n\u003e The compiler doesn't care that the LLM was pretty sure. Neither does hlv.\n\n## Feature flags\n\nHLV ships with opinionated defaults, but you can opt out via `project.yaml`:\n\n```yaml\nfeatures:\n  linear_architecture: true   # flat module structure, no layered arch\n  hlv_markers: true            # @hlv code traceability markers + CTR-010/CTR-001\n  security_markers: true       # @hlv:sec security attention markers + SEC-010\n```\n\nAll default to `true`. Set to `false` to use your preferred architecture style, skip `@hlv` markers, or disable security attention markers. `hlv init` asks about these during project setup.\n\n## Your best practices are LLM anti-patterns\n\n| Developer pattern | LLM problem | HLV alternative |\n|-------------------|-------------|-----------------|\n| Dependency Injection | Magic wiring — LLM can't see what gets injected | Direct imports, explicit construction |\n| Deep directory trees | Context burn — LLM wastes tokens navigating | Flat structure, everything discoverable |\n| Convention over config | Magic paths — LLM guesses file locations | Explicit config, no guessing |\n| Abstract factories | Hidden code paths — LLM can't trace what runs | Direct construction, visible types |\n| ORM magic | Hidden SQL — LLM generates without seeing queries | Explicit queries, typed results |\n| Lots of small files | Context hops — LLM loses coherence | Fewer, larger files with clear boundaries |\n\nThe `llm/` layer is designed for LLM generation: flat structure, explicit everything, direct code, errors as values, types as documentation.\n\n\u003e Code in llm/ is optimized for one reader: the next LLM invocation. And for one validator: hlv.\n\n## How HLV compares\n\n| Criteria | Chat + Copilot | Autonomous agents | **HLV** |\n|----------|---------------|-------------------|---------|\n| Spec approach | Ad-hoc prompts | Agent infers | **Formal contracts with invariants** |\n| Who writes code | Human+AI mixed | Agent alone | **LLM writes all — within verified specs** |\n| Verification | Manual review | Agent self-checks | **Independent Rust binary** |\n| Context control | Entire codebase | Agent picks files | **One stage at a time** |\n| Traceability | None | None | **REQ → contract → test → gate → code** |\n| When LLM drifts | Hope you catch it | Hope agent catches itself | **hlv check shows what diverged** |\n| Release criteria | \"Looks good\" | \"Agent says done\" | **All mandatory gates passed** |\n\n## MCP integration\n\nHLV includes a built-in [MCP](https://modelcontextprotocol.io/) server. Claude Code, web dashboards, and custom tools get full programmatic access to your project.\n\n```json\n{\n  \"mcpServers\": {\n    \"hlv\": {\n      \"command\": \"hlv\",\n      \"args\": [\"mcp\", \"--root\", \"/path/to/your/hlv-project\"]\n    }\n  }\n}\n```\n\nAlternatively, set the MCP server `cwd` to the HLV project root and use `args: [\"mcp\"]`.\n\n```bash\n# Or start SSE server for web clients\nhlv mcp --transport sse --port 3000\n```\n\n12 resources + 27 tools + change notifications. See [docs/MCP.md](docs/MCP.md) for details.\n\n**Web Dashboard example:** [hlv-dashboard-example](https://github.com/lee-to/hlv-dashboard-example) — a reference implementation of the [Dashboard spec](docs/specs/SPEC_DASHBOARD.md) built with HLV MCP.\n\n**Build your own:** the [docs/specs/](docs/specs/) directory contains detailed specifications you can use to build custom integrations on top of HLV MCP.\n\n## AI agent skills\n\nBuilt-in skills drive the full development lifecycle:\n\n| Skill | What it does |\n|-------|-------------|\n| `/artifacts` | Interview to capture domain context, stack, and constraints |\n| `/generate` | Generate contracts, test specs, stages, and gates |\n| `/implement` | Implement one stage at a time with validation cycles |\n| `/validate` | Verify code against contracts, auto-create fix tasks on failure |\n| `/verify` | Cross-check contracts for completeness and consistency |\n| `/questions` | Surface open questions that block progress |\n\nSkills are installed automatically by `hlv init`.\n\n## Looking for something simpler?\n\nIf HLV feels like overkill for your current workflow, start with [AI Factory](https://github.com/lee-to/ai-factory) — a lighter approach to working with AI agents.\n\n## Installation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emacOS (Apple Silicon)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ncurl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-aarch64-apple-darwin.tar.gz | sudo tar xz -C /usr/local/bin\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emacOS (Intel)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ncurl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-apple-darwin.tar.gz | sudo tar xz -C /usr/local/bin\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLinux (x86_64)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ncurl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-unknown-linux-gnu.tar.gz | sudo tar xz -C /usr/local/bin\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLinux (aarch64)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ncurl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-aarch64-unknown-linux-gnu.tar.gz | sudo tar xz -C /usr/local/bin\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindows (x86_64, PowerShell)\u003c/b\u003e\u003c/summary\u003e\n\n```powershell\nInvoke-WebRequest -Uri \"https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-pc-windows-msvc.zip\" -OutFile hlv.zip\nExpand-Archive hlv.zip -DestinationPath \"$env:USERPROFILE\\bin\" -Force\n```\n\nAdd `%USERPROFILE%\\bin` to `PATH` if needed.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBuild from source\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/lee-to/hlv.git\ncd hlv\ncargo install --path .\n```\n\u003c/details\u003e\n\n### Updating\n\n```bash\nhlv update            # download and install the latest release\nhlv update --check    # only check if a new version is available\n```\n\nThen bootstrap a project:\n\n```bash\nhlv init --project my-service --owner backend-team\nhlv check\n```\n\n## Project structure\n\n```\nmy-project/\n├── project.yaml              # Project configuration\n├── gates-policy.yaml          # Quality gates\n├── map.yaml                   # File → contract traceability\n├── human/\n│   ├── glossary.yaml          # Domain glossary\n│   ├── artifacts/             # Global artifacts (shared)\n│   │   ├── context.md\n│   │   ├── stack.md\n│   │   └── constraints.md\n│   └── milestones/\n│       └── 001/\n│           ├── plan.md        # Implementation plan\n│           ├── stage_1.md     # Stage details\n│           ├── contracts/     # Formal specifications\n│           └── artifacts/     # Milestone-specific context\n└── milestones.yaml            # Milestone \u0026 task tracking\n```\n\n## Architecture\n\nSee [docs/ARCH.md](docs/ARCH.md) for the full architecture description.\n\n## Development\n\n```bash\ncargo build\ncargo test\ncargo clippy\ncargo fmt --check\n```\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flee-to%2Fhlv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flee-to%2Fhlv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flee-to%2Fhlv/lists"}