Headron Software

Contract 3.62.0 · MIT · verdicts carry receipts: headron verify --receipt <file>

• Is: a rule contract and CLI mapping changed files to checks. Hooks are optional; headron verify runs done gates.
• Is not: a coding agent, model, test framework, or proof code is correct. A check that cannot run reports SKIP or NOT RUN, never a pass; the hook lets that commit through.
• Needs: Python >=3.11, pyyaml, defusedxml. No account or key. A package install fetches its matching release from GitHub on first run.
• headron init writes: AGENTS.md, CLAUDE.md, .mcp.json, .codex/config.toml, .git/hooks/pre-commit. Use --no-wiring to skip hooks and configuration; headron enforce uninstall restores a displaced hook.
• Mind API: hosted, paid, needs a key; plans a declared change. The command line works without it.

Agents: llms.txt. Chats: CHAT.md. Evidence.

Why this exists

An agent can report a change as done without running a single check. A check that never ran looksthe 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 whetheran autonomous agent, an IDE extension, a chat assistant, or a developer made the commit.
• A skipped check is never a pass. SKIP and NOT RUN stay out of the pass count.

How it works

headron port <file> tells an agent what a file owes before it edits. atlas.yamlholds those checks; the commit hook and CI report PASS, FAIL, SKIP or NOT RUN. The hostedMind API plans a declared change through headron mind.

$ 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

# install
uv tool install headron-software && headron doctor
# editable, to change Headron itself
git clone --depth 1 --branch v3.62.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor

In your repository:

cd path/to/your-repo && headron init   # finds your checks, wires your agents, installs the commit hook, runs once
headron verify && headron proof <file> --verify   # after a change: verdicts, then a file's proof

With an impact map, headron verify --changed evaluates modified files in seconds.Target a specific profile with headron verify --changed --change <class> (e.g. source_change, api_change, security_sensitive); headron verify remains the final full verdict.

Machines: bootstrap, facts, and JSON schema.Agents: adapters; the MCP interface is read-only.Another repository: CONSUMING.

What it measurably buys

See the instrument limits for their scope.

Entry context: ~1,606 tokens. The 211 documents (697 KiB) load on demand; install: 10 KiB; hash lock with test tools: 8 packages.Field records. Routing data. Measures can overlap.

Where it fits

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

Agent contract

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

• Discover: headron find <query> searches paths, symbols and vocabulary; headron sweep maps topology. Search does not guarantee semantic recall.
• Route: headron port <file>, or parse .agent/bootstrap.json; load only its names.
• Processes: headron process [<id>] --json lists workflows; with an id, its steps and gates.
• Mind: headron mind --route <file> routes; headron mind --receipts lists audit trails.
• Beliefs: headron revise names what rests on a refuted claim; headron propose drafts each fix outside the tree.
• 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.

Find your way

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

Counts, computed

Generated on every build; check refuses drift.

• 52 hard invariants — enforced on every change, zero unowned
• 363 agreement edges — each a file tied to the declaration it answers for
• 95 instruments — each stating what it proves, what it does not, and what closes the gap
• 385 tool entries — across 40 manifests and 5 kinds, validated against tools/tools.schema.json
• 179 harness Python files — every one held by lint · format · typecheck
• 3.62.0 contract version — VERSION, asserted in 10 other files

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.62.0