Headron Software

Protocol: a change maps to proof; Headron selects evidence and the build enforces the verdict (evidence). Agents: llms.txt; chats: CHAT.md.

Start: install/use · architecture · enterprise · agents · chat · adapters

Why this exists

An agent can report a change as done without running a single check. A check that never ran looks the same as a check that passed. Headron Software closes that gap:

• Every change maps to proof. atlas.yaml lists the checks each kind of file owes, and the gate runs them before the change is called finished.
• Refusal happens at commit, for any agent. A git hook runs the same check-only command whether an autonomous agent, an IDE extension, a chat assistant, or a developer made the commit.
• A skipped check is never a pass. A missing tool is reported as SKIP and kept out of the pass count. Gates report PASS, FAIL or NOT RUN.

$ headron gate scripts/doctor.py
1. formatter: ruff format --check scripts/doctor.py
2. compiler_or_typechecker: python3 -c 'import ast,sys; [ast.parse(open(f, encoding="utf-8").read(), f) for f in sys.argv[1:]]' scripts/doctor.py
3. unit_tests: pytest

Quickstart

# editable
git clone --depth 1 --branch v3.61.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor

In your repository:

cd path/to/your-repo && headron init   # checks, universal multi-agent wiring, first run
headron verify && headron report          # after a change: verdicts, then what is unverified

With an impact map, headron verify --changed runs planted groups with moved dependencies or no record. It speeds feedback; headron verify remains the final verdict.

Agents reach Headron Software through Headron MCP; the current headron-mcp command is read-only. Enterprise execution gates and host approval hooks live in the companion runtime (HeadronOS). No-shell chat: CHAT.md. Add Headron Software to another repository: CONSUMING.

Where it fits

• Any agent or runtime. One sovereign contract across all agent architectures (Google Antigravity, Claude Code, Cursor, OpenAI Codex, OpenHands, Windsurf, Hermes, or bare CLI). The adapters in models/README.md keep native tools intact while enforcing identical deterministic boundaries.
• Any repository. headron init wires a repository in one step. Consumers add the reusable CI workflow from CONSUMING so the verdict on a laptop and in CI is the same command.
• Any language we route. Each language × check pair is either answered by a command or declared as having no tool, so an unanswered pair cannot hide.

Enterprise and companion runtimes

Headron Software is the core product of HLIntel (Headron Layer Intelligence):

• HeadronOS: desktop workspace and local runtime.
• Headron Web: browser interface.
• Headron Enterprise: organizational offering across desktop and web.
• Headron MCP: integration connecting agents and developer tools.
• HL.Verify: shared verification capability.
  • Rules & Gates: File-targeted proof obligations and pre-commit enforcers.
  • Failure Ledger: Past agent failure catalog and regression seeds.
• Mind API: shared orchestration interface.

Companion details. Product integration remains unproven.

$ headron port scripts/doctor.py --line
◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓3 │ ⚠1 │ → headron gate scripts/doctor.py
$ headron port scripts --line
◎ scripts │ ⠟159 │ ⌂scripts │ → headron brainstorm
$ headron port . --line
○ . │ ⠟188 ⠁4 ⠿4 │ → headron check

What it measurably buys

What the recorded instruments have caught in real runs. They prove routing and refusals, not end-to-end task success (limits).

Failures caught

• 31/31 planted breaks refused at commit, across 20 of 40 languages. 20 more have an example its toolchain has not run; 0 have none yet (enforce.py v3.60.0).
• 695 mistake kinds planted in the tests, each refused.
• 122 failure shapes recorded from real runs: 209 sightings, 47 recurred, 99 now guarded, 23 host-only (3 of them recurred).
• 1076 refusals in daily use (37 shapes, 654 re-fired). Verify: 39 passed and 187 failed, of 485 runs. 112 of 115 lands armed; 701 lessons shown (agents.py --field v3.59.0).
• 24/24 solo commits clean with or without the hook; a planted broken commit is refused.
• 6 agent controls block, never warn: narrow_tools, sandbox, budget, approval, effects, audit.

Cost

• 1,729 tokens read before routing; 196 more documents (668 KiB) load only when a route names one.
• 89% fewer tokens than pasting every tool list; 50% fewer than blind.
• 10 KiB install: 1 module, 2 dependency — 8 in total with its own dependencies.

Coverage

• 360 language × check pairs (40 × 9), all answered: 144 by a command, 216 by a declared no tool, 0 silent.

Agent contract

• Discover: headron find <query> for instant search (symbols, prefix, acronym, pointers); headron sweep for tier and shard topology.
• Route: headron port <file>, or parse .agent/bootstrap.json; load only its names.
• Orchestrate: headron mind --route <file> for System 1 reflex vs System 2 deliberate execution; headron mind --receipts for verified audit trails.
• Automate: add --json; records follow the output schema.
• Before shell: headron shell --json "<cmd>"; exit 3 means its verdict would be misread.
• Land: python scripts/branchstate.py --land; check headron landed <branch> before deletion.
• Judge and report: use the judgment rungs; file breaks with the headron skill.

Counts, computed

Generated on every build; check refuses drift. Machine-readable: .agent/facts.json.

• 388 tool entries — across 40 manifests and 5 kinds, validated against tools/tools.schema.json
• 353 agreement edges — each a file tied to the declaration it answers for
• 94 instruments — each stating what it proves, what it does not, and what closes the gap
• 7 change classes — and 13 task profiles, in atlas.yaml
• 157 harness Python files — every one held by lint · format · typecheck
• 3.61.0 contract version — VERSION, asserted in 8 other files

Find your way

• Every document: docs index · wiki
• Languages: atlas · routing · verification
• Agents: harness · .headron · runtimes
• Why a rule: headron why · headron failures · instruments
• Security: policy · OpenSSF · contributing

Project

Version tracks the contract, not content (versioning). Built by HLIntel LLC, public on purpose (about). Contributions pass headron verify. MIT License.

Updated: contract v3.61.0