Kova

Kova is an LLM-driven engineering pipeline. A local model (Qwen3.8-27B served over llama.cpp) does the thinking; a deterministic Rust engine owns the state. The engine drives a four-phase pipeline (Research → Verification → Scaffolding → Implementation), gates phase advancement with logit reads of the model's yes/no distribution, runs deterministic checks (cargo) in a sandboxed process group, and exposes the whole thing over a small REST API with an embedded single-page GUI.

The core design rule: the model proposes, the state machine disposes. The model can never advance a phase, write pipeline state, or open files outside its declared surface — the engine enforces all of it deterministically.

Workspace layout

Nine crates in the workspace (virtual manifest, Rust edition 2021):

Crate	Role
kova-primitives	Deterministic core: Phase / PhaseStatus / PipelineState / PipelineEvent, logit types (LogitVector, TokenProb), gate decisions (Noul / Choice / Score), plan-artifact paths, KovaError
kova-core	KovaEngine — the user-gated pipeline state machine; sled state store (a state row + an append-only event log); research budget guard; CLI + kovarc.toml config loading
kova-router	LLM backend abstraction (LlmBackend): chat, tool-aware chat, and raw /completion (the path that drives logit gate reads)
kova-mcp	Model-Context-Protocol server: JSON-RPC 2.0 dispatch (initialize, tools/list, tools/call) over a name-keyed in-process tool registry (listings sorted by name)
kova-sandbox	Sandboxed execution of phase check commands: host process-group isolation (default) or opt-in youki OCI container
kova-actor	Worker-dispatch types (WorkOrder, VramBudget); the ractor-based actor pool lands with the worker implementation
kova-api	Axum REST surface (/health, /pipeline/*) + embedded GUI serving
kova-gui	GUI assets embedded at compile time via rust-embed
kova-docs-lint	Docs linter binary (kova-docs-lint): frontmatter schema, symbol/path resolution, Tier1→Tier2 link check, write-limits boundary + plan gateway (lint / check-writes / check-plan)

The pipeline in one paragraph

The pipeline sits in exactly one of four phases with one of six statuses (Idle, Working, Checking, ReadyToAdvance, Failed, Complete). Research is the only model-driven phase today: the model explores the codebase through MCP tools and must emit one plan artifact (research/plans/<kebab-case-name>.md) before the phase can be marked ready. Advancing a phase is user-gated: POST /pipeline/advance is rejected unless the status is ReadyToAdvance. Each phase carries deterministic check commands (e.g. cargo check --workspace --all-targets for Verification, cargo test --workspace for Implementation) and a circuit-break target that a failed phase regresses to.

Current status

Honest state of the tree (full ledger with file:line evidence in plans/kova-qwen-clean-start-v3.md):

• Implemented & green: deterministic engine, logit gate, sandboxed checks, REST surface, embedded GUI. cargo test --workspace → 97/97 passing.
• Placeholder: the research loop runs a PlaceholderRunner; the real MCP tool loop (9 research tools, budget-guarded turn loop) is specified in plans/kova-research-phase-mcp-tool-layer.md and sub-plans 03a–03c, not yet in the tree.
• Not yet wired: server-sent events (polling GET /pipeline/events instead), automated backward circuit breaking (the target table exists and is unit-tested but the engine never calls it), the ractor actor pool, a vendored youki binary, root README.md / openapi.json.

Documentation map

• Getting Started — run the engine against a local Qwen server.
• Pipeline Specification — phases, statuses, gates, events, REST surface, and the divergence ledger.
• Agent Docs Concept — the machine-readable two-tier contract system under docs/agent/ that the research phase consumes.
• Contributing — repo layout, conventions, build & test.

Machine-readable agent docs live in docs/agent/ (tier 1 module contracts, tier 2 side-effect surfaces, code-flow execution chains). They are not part of this MkDocs site on purpose — they are consumed by the research agent and linted by the docs CI, not browsed by humans.