thea-software

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

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

Start: install · proof · where it fits · every document · website · documentation · Mind API

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

# install
uv tool install headron-software && headron doctor
# editable, to change Headron itself
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.

Machines: bootstrap, facts, and JSON schema. Agents: entry, adapters; the MCP interface is read-only. Chats: no-shell setup. For another repository, see CONSUMING.

What it measurably buys

Recorded results cover enforcement, routing, verification and lessons. See the instrument limits for their scope.

Instrument	Recorded result
Enforcement	31/31 breaks refused across 20 toolchains; 723 declared planted cases
Failure ledger	122 shapes, 209 sightings; 99 in-tree guarded, 23 host-only
Field ledger	781 verifications (102 clean); 1119 refusals; 259 landings; 625 lessons; 353 sessions
Routing experiment	89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models
Language roles	360 pairs: 110 runnable, 250 absent, 0 undeclared

Entry context: ~1,712 tokens. The 199 documents (663 KiB) load on demand; install: 10 KiB, 8 dependencies. Field records capture verification, safeguards and lessons that inform Headron's controls and architecture. Routing data. Measures can overlap.

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.

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 │ ⠟162 │ ⌂scripts │ → headron brainstorm
$ headron port . --line
○ . │ ⠟190 ⠁4 ⠿4 │ → headron check

• Discover: headron find <query> searches paths, symbols and vocabulary with pointers; headron sweep maps topology. Search does not guarantee semantic recall.
• 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.

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

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.

Counts, computed

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

• 385 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
• 160 harness Python files — every one held by lint · format · typecheck
• 3.61.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.61.0