Hivelore

Hivelore

The deterministic policy gate for agent-written code — it refuses the commit that repeats a mistake your team already paid for.

A repo-native context policy for coding-agent harnesses; the rules live as team memory. Formerly published as hAIve ( @hiveai/* ).

Hivelore is the enforcement layer inside an AI coding-agent harness. It briefs agents with the team's non-obvious knowledge before they act, then turns each hard-won lesson into a deterministic gate — in MCP, Git hooks, and CI — that blocks the change about to repeat it. Same diff, same verdict, on every machine. Memory is the substrate; the gate is the product.

A capable model already knows generic best practice. What it *cannot* guess is your team's arbitrary, repo-specific knowledge: that public ids are id + 100000 prefixed AC-, that the status field must be "OK"/"KO", that you never edit an applied migration. Left to itself, a confident agent invents a plausible answer - clean, tested, green, and wrong by policy. Hivelore carries that unguessable knowledge into the task and blocks the change that's about to violate it.

Hivelore's job is not to replace tests, linters, or observability. It makes the repo-specific knowledge those tools cannot infer available, auditable, and enforceable.

Capture a mistake → attach a validated guard → the commit that repeats it is refused. Same diff, same verdict, on every machine and in CI. Reproduce it in 60 seconds ↓

---

The problem

AI coding agents are powerful, but they often act with incomplete repo context. Compaction, parallel sessions, agent switches, and stale advisory docs all create the same failure mode: the agent changes code without carrying the team's current decisions into the work.

Most teams work around this with instructions and hope:

• *"Please read our architecture decisions first."*
• *"Don't repeat the migration mistake from last sprint."*
• *"Remember to capture what you learned."*
• *"Don't merge code that invalidates a team decision."*

Those rules are easy to skip. Hivelore turns them into repo-native context policy.

---

How it works

AI agent ──▶ Hivelore briefing ──▶ code change ──▶ Hivelore policy gate ──▶ merge

▲ │ └── context breadcrumbs · decisions · gotchas · anchors

1. hivelore init creates a .ai/ context policy layer in your repo.
2. Agents start every session with get_briefing — one MCP call that returns small default context plus deeper breadcrumbs ranked by task relevance.
3. Decisions, gotchas, failed attempts, and session recaps live as Markdown files anchored to the code paths they describe. When code moves, Hivelore detects stale anchors.
4. hivelore enforce check and CI enforcement block unsafe states: missing briefing, stale critical decisions, an anchored anti-pattern your diff is about to repeat, or uncaptured session knowledge.

Memory is the substrate. Context enforcement is the product promise.

AI changes should not enter the codebase without consulting the team's current knowledge.

For the changes prompted by the September 18 client reports, including evidence checks, quieter briefings and completion scoped to a task, see the implementation notes.

Where Hivelore fits in the harness

Harness engineering is about the environment around the model: feedforward guidance before it acts, feedback sensors after it acts, and workflow gates that keep bad states from landing. Hivelore owns the repo-specific context policy part of that harness.

The narrow positioning is intentional: Hivelore is not a general memory database or an agent dashboard. It is the control layer that helps coding agents act with the validated, non-obvious knowledge of the team.

Scope & boundaries — the three harnesses

Harness engineering regulates three different things about agent-written code. Hivelore deliberately covers two of them and treats the third as out of scope, for now.

Why no behaviour harness yet. Verifying functional correctness needs an *oracle* — an independent source of truth for what the code *should* do — and that oracle problem (plus the trap of an agent grading its own work) is the least-mature part of the field. That territory belongs to your tests, property-based checks, and LLM-evals; Hivelore does not try to replace them. What Hivelore *does* do is carry the unguessable intent a behaviour test would otherwise have to encode (status must be OK/KO, public ids = id + 100000) as feedforward context and deterministic sensors — a partial, static slice of behaviour control, not a runtime functional oracle.

The bridge exists (v0.33.0): command sensors. A lesson can carry a *command* instead of a regex — your own test or invariant script. When a diff touches the sensor's paths, the gate executes it and a non-zero exit refuses the commit with the lesson as the message. Hivelore does not invent the oracle (the unsolved problem); it routes the oracle your team already owns to the lesson it protects:

hivelore memory tried \

--what "refund exceeded the captured amount" \ --why-failed "prod incident #442 — refunds must clamp to capture" \ --paths src/payments/ \ --sensor-command "npx vitest run tests/payments/refund-invariants.spec.ts"

→ validated (the oracle must PASS on the current tree), then enforced at commit + CI

Saved team-scoped by default: an enforced lesson must travel to every machine and CI.

Rules that keep it honest: opt-in per repo (enforcement.runCommandSensors: true — it executes repo-authored commands), a proposal whose oracle *fails on the presumed-correct tree* is rejected, an oracle that is still a pending stub cannot arm a block sensor, and an unrunnable command (not found, timeout) warns but never blocks — a broken harness must not masquerade as a failing test. Commands run with a scrubbed environment (test-runner basics only — no cloud credentials or tokens). And you can make the guarantee demonstrable: --red-ref replays the incident in a scratch worktree and requires the oracle to FAIL there — the sensor then records red_proven: true, shown in the prevention receipt. A crash is not a RED: if the oracle errors before reaching its assertion on the incident state (the guarded code doesn't exist yet, an import or syntax error, "no tests found"), the replay reports red-unrunnable and refuses to claim proof. Full behaviour verification (test generation, LLM evals) remains your test suite's job.

Since v0.43.0, prove-RED is mandatory for a blocking shell/test sensor: an oracle without a reproducible incident state remains warn. CI can also set commandSensorUnrunnable: "block" so a missing required oracle fails as a broken harness, and sensorWeakeningGate: "block" so protection cannot be silently demoted or removed.

The on-ramp (v0.36.0): scaffold the test from the incident. A command sensor needs a test to route — so Hivelore generates the skeleton from the lesson. hivelore sensors scaffold (or the scaffold_test MCP tool, so agents do it in-session) detects your test framework (vitest / jest / pytest / go), writes a pending test carrying the incident's provenance in its header, and prints the exact sensors propose --kind test line to arm it. It never arms a sensor itself (propose_sensor stays the sole validated writer); the stub stays pending so the suite is green until you write the assertion. In a monorepo, the framework and location come from the package that owns the lesson's anchor paths (a lesson under packages/api/ scaffolds into packages/api/tests/…), not the repo root — and a lesson that spans several packages scaffolds one pending test per owning package, all armed by a single sensor whose oracle chains their run commands. A scaffold left pending or never armed is an open loop: doctor and enforce finish nudge it (post-incident-test-unarmed) until the oracle is routed.

Pass the incident and the stub writes itself around the fix (v0.46.0). Add --red-ref and the scaffold names the symbols the fix (red_ref..HEAD) actually touched and pre-fills the example around them — import { refund } …, expect(refund(/* incident input */)).toBe(/* post-fix expected */) instead of a blank subjectUnderTest(). It stays a pending, commented stub (no live import, suite stays green) — a deterministic head-start, never an LLM guessing your assertion.

hivelore sensors scaffold 2026-07-03-attempt-refund-exceeds-capture --red-ref <pre-fix-commit>

→ tests/incidents/refund-exceeds-capture.test.ts (pending; names the touched symbols from the fix)

then: fill the assertion → run it → arm it with the printed propose command.

Lower the cost of expressing the invariant (v0.48.0): `--style`. The behaviour harness leaves the *oracle* to you — so the scaffold offers the two deterministic ways to make that cheaper (no LLM guessing your assertion):

• --style property — a fast-check / Hypothesis skeleton: state the invariant once (refund(a, b) ≤ b) and it is checked over many generated inputs.
• --style differential --reference — state no invariant at all: assert the subject *agrees* with a reference implementation (a legacy version, a second impl) for all generated inputs.

hivelore sensors scaffold <lesson> --red-ref <pre-fix-commit> --style property

hivelore sensors scaffold --style differential --reference ../legacy/refund

Both stay pending, commented stubs (the suite stays green) and arm through the same validated prove-RED path once you fill them in.

**Measure the behaviour harness (v0.45.0).*