Documentation cannot lie about behavior.

Get started

First touch

Run the CLI without installing anything — npx resolves the latest published version and prints the command surface:

npx @kernloop/cli --help

Install globally

For repeated use, install the CLI; its binary is kernloop:

npm i -g @kernloop/cli
kernloop --help

Start the MCP server with kernloop serve. Its surface is bounded to exactly eleven tools — never a twelfth.

CLM-0033

Early v0 (0.1.x) — wiring-complete, not production-ready.

Where the bytes come from

All @kernloop/* packages are published together in lockstep. Every release from 0.1.1 onward is published straight from this repository's CI over npm OIDC trusted publishing — no long-lived token is held — and carries build provenance: an SLSA attestation signed on GitHub Actions, so the published bytes are cryptographically traceable to the exact commit and workflow that built them. (The first release, 0.1.0, was a one-time manual bootstrap and predates this.) That is supply-chain integrity — a guarantee about where the code came from — a different guarantee from the claims gate, which keeps the docs honest about what the code does. The workflow that publishes and signs every release is in the open:

the release workflow

For everything else — the full command set, every package, and the canonical loop in source — see the repository.

The thesis

kernloop is claims-first. Before a capability is implemented, a claim and its acceptance test are written; the claim is the unit of progress and the backlog. A capability is wiring-complete or absent — there are no stub executors, no fail-closed shims, no TODO-wired exports living behind a facade. Incomplete work stays on a branch, not in main behind a stub.

The consequence is the headline above: if a document claims a behavior, the code proves it or the claim does not ship. A small, fully-true repository beats a large, partially-true one. This is a wiring-complete v0 foundation — not a finished product — and it is described here as exactly that.

Architecture

The kernel

The kernel is the dumb, dependable core: router, a hash-chained audit log, the authority ladder, the message bus, and the model adapters. By rule the kernel contains no intelligence — kernel source outside the adapters cannot originate a model call.

CLM-0061

Faculties never import one another; they communicate only through contracts carried over the bus, an isolation the plugin lint enforces.

CLM-0062

The frozen five contracts

Five contracts are frozen and zod-validated at every boundary, with no any crossing a contract edge:

• TaskContract
• Brief
• Verdict
• Outcome
• Manifest

CLM-0001 CLM-0006

The four authority tiers

Anything automated declares its authority in its manifest, drawn from a closed enum of four tiers:

• observe — watches; takes no action.
• suggest — proposes; a human or higher tier decides.
• advisory — emits a non-blocking verdict.
• enforce — gates the loop.

Promotion up the ladder requires evidence plus human ratification and never defaults upward; demotion is automatic when evidence lapses. The review gate ships at advisory and is promotable to enforce per-overlay only via a ratified ladder transition — it is not enforce by default.

CLM-0002 CLM-0016 CLM-0017

The seven faculties

Intelligence lives in governed faculties, each isolated behind contracts:

• compiler
• memory
• gates
• workforce
• observer
• toolsmith
• models

The canonical loop

Work flows through one canonical loop, frozen as data so its shape cannot drift silently:

frame → research → plan → vote → decompose → fan-out [ implement → quality → review → parsimony ] → integrate → retrospect

CLM-0042 CLM-0045

How it stays honest

An immutable audit log

Every behavior that acts appends to a hash-chained audit log — no silent actions. Tampering is detected and attributed: truncating, reordering, or deleting an entry fails verification.

CLM-0009 CLM-0012 CLM-0013

The claims gate

The claims registry is verified in CI. Dangling evidence fails claims:check, and a verified claim with no test evidence fails too.

CLM-0007 CLM-0008

Beyond static resolution, every cited test must actually have run and passed, proven by claims:verify-ran. A claim that names a test which never executed is not honest, so it is not green.

CLM-0180

A bounded MCP surface

The MCP surface is exactly eleven tools — run, status, brief, gate, recall, remember, distill, forge, manifest, audit, observe — and nothing else. Depth ships as skills, never as a twelfth tool.

CLM-0033

What kernloop is not

It is not fully autonomous — a human ratifies every kernel, contract, and claims-semantics change; autonomy is a governed cadence, never a license to weaken a rule. It is not production-ready: it is a wiring-complete v0. It runs on a single machine and trusts its overlay configuration — it is not zero-trust, Byzantine fault tolerant, or distributed.