headron-software 3.62.0__tar.gz → 3.63.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. {headron_software-3.62.0/scripts/headron_software.egg-info → headron_software-3.63.0}/PKG-INFO +50 -68
  2. headron_software-3.63.0/README.md +169 -0
  3. headron_software-3.63.0/VERSION +1 -0
  4. {headron_software-3.62.0 → headron_software-3.63.0}/pyproject.toml +10 -28
  5. {headron_software-3.62.0 → headron_software-3.63.0}/scripts/atlas_cli.py +15 -1
  6. {headron_software-3.62.0 → headron_software-3.63.0/scripts/headron_software.egg-info}/PKG-INFO +50 -68
  7. headron_software-3.62.0/README.md +0 -187
  8. headron_software-3.62.0/VERSION +0 -1
  9. {headron_software-3.62.0 → headron_software-3.63.0}/LICENSE +0 -0
  10. {headron_software-3.62.0 → headron_software-3.63.0}/scripts/headron_software.egg-info/SOURCES.txt +0 -0
  11. {headron_software-3.62.0 → headron_software-3.63.0}/scripts/headron_software.egg-info/dependency_links.txt +0 -0
  12. {headron_software-3.62.0 → headron_software-3.63.0}/scripts/headron_software.egg-info/entry_points.txt +0 -0
  13. {headron_software-3.62.0 → headron_software-3.63.0}/scripts/headron_software.egg-info/requires.txt +0 -0
  14. {headron_software-3.62.0 → headron_software-3.63.0}/scripts/headron_software.egg-info/top_level.txt +0 -0
  15. {headron_software-3.62.0 → headron_software-3.63.0}/setup.cfg +0 -0
{headron_software-3.62.0/scripts/headron_software.egg-info → headron_software-3.63.0}/PKG-INFO RENAMED
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: headron-software
3
- Version: 3.62.0
4
- Summary: AI coding-agent verification: tells agents which commands prove a change and fails the build when one was skipped. Polyglot; CLI, MCP server, git hooks, CI.
3
+ Version: 3.63.0
4
+ Summary: Command line tool and rule contract for AI coding agents: each changed file maps to the checks it owes, and a commit whose file fails is refused.
5
5
  License-Expression: MIT
6
- Project-URL: Homepage, https://github.com/HLIntel/Headron
6
+ Project-URL: Homepage, https://headron.tech
7
7
  Project-URL: Documentation, https://github.com/HLIntel/Headron/blob/main/llms.txt
8
8
  Project-URL: Issues, https://github.com/HLIntel/Headron/issues
9
9
  Project-URL: Source, https://github.com/HLIntel/Headron
@@ -28,11 +28,11 @@ Provides-Extra: crosscheck
28
28
  Requires-Dist: jsonschema>=4; extra == "crosscheck"
29
29
  Dynamic: license-file
30
30
 
31
- <!-- AGENTS: do not read this page breadth-first. Plug in: `python scripts/atlas.py port <file>`,
32
- or parse .agent/bootstrap.json — one record back. -->
31
+ <!-- AGENTS: do not read this page breadth-first. Run `headron port <file>` (in a clone,
32
+ `python scripts/atlas.py port <file>`), or parse .agent/bootstrap.json. -->
33
33
  <!-- mcp-name: io.github.HLIntel/headron -->
34
34
  <div align="center">
35
- <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.svg"
35
+ <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.jpg"
36
36
  alt="Headron Software: AI governance and verification"
37
37
  width="992">
38
38
  <h1>Headron Software</h1>
@@ -40,34 +40,32 @@ Dynamic: license-file
40
40
 
41
41
  <!-- BEGIN generated: badges (python scripts/atlas.py index --write) -->
42
42
 
43
- **Contract 3.62.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
43
+ **Contract 3.63.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
44
44
 
45
45
  <!-- END generated: badges -->
46
46
 
47
47
  <!-- BEGIN generated: headline (python scripts/atlas.py index --write) -->
48
48
 
49
- **Protocol:** a change maps to proof; Headron selects evidence and the build enforces the verdict ([evidence](#what-it-measurably-buys)). Agents: [llms.txt](llms.txt); chats: [CHAT.md](CHAT.md).
49
+ - **Is:** a rule contract and CLI mapping changed files to checks. Hooks are optional; `headron verify` runs done gates.
50
+ - **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.
51
+ - **`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.
52
+ - **Mind API:** hosted, paid, needs a key; plans a declared change. The command line works without it.
53
+
54
+ Agents: [llms.txt](llms.txt). Chats: [CHAT.md](CHAT.md). [Evidence](#recorded-results).
50
55
 
51
56
  <!-- END generated: headline -->
52
57
 
53
58
  ## Why this exists
54
59
 
55
- An agent can report a change as done without running a single check. A check that never ran looks
56
- the same as a check that passed. Headron Software closes that gap:
57
-
58
- - **Every change maps to proof.** [`atlas.yaml`](atlas.yaml) lists the checks each kind of file owes,
59
- and the gate runs them before the change is called finished.
60
- - **Refusal happens at commit, for any agent.** A git hook runs the same check-only command whether
61
- an autonomous agent, an IDE extension, a chat assistant, or a developer made the commit.
62
- - **A skipped check is never a pass.** A missing tool is reported as `SKIP` and kept out
63
- of the pass count. Gates report `PASS`, `FAIL` or `NOT RUN`.
60
+ Headron connects changed files to declared checks and reports whether those checks ran. A skipped
61
+ check is not a pass. An optional Git hook can run checks before a commit, whether the change came
62
+ from a developer or an agent.
64
63
 
65
64
  ## How it works
66
65
 
67
- **System 1:** `headron port <file>` routes task context. **System 2:** [`atlas.yaml`](atlas.yaml)
68
- maps changes to gates; hooks and CI emit `PASS`, `FAIL`, `SKIP`, or `NOT RUN`. The
69
- hosted [Mind API](https://headron.tech/mind-api.html) plans a declared change; `headron mind`
70
- adds **classify → route → receipts**.
66
+ `headron port <file>` tells an agent what a file owes before it edits. [`atlas.yaml`](atlas.yaml)
67
+ holds those checks; the commit hook and CI report `PASS`, `FAIL`, `SKIP` or `NOT RUN`. The hosted
68
+ [Mind API](https://headron.tech/mind-api.html) plans a declared change through `headron mind`.
71
69
 
72
70
  <!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
73
71
 
@@ -97,7 +95,7 @@ $ headron gate scripts/doctor.py
97
95
  # install
98
96
  uv tool install headron-software && headron doctor
99
97
  # editable, to change Headron itself
100
- git clone --depth 1 --branch v3.62.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
98
+ git clone --depth 1 --branch v3.63.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
101
99
  ```
102
100
 
103
101
  <!-- END generated: install -->
@@ -105,18 +103,18 @@ git clone --depth 1 --branch v3.62.0 https://github.com/HLIntel/Headron ~/headro
105
103
  In your repository:
106
104
 
107
105
  ```bash
108
- cd path/to/your-repo && headron init # checks, universal multi-agent wiring, first run
109
- headron verify && headron report # after a change: verdicts, then what is unverified
106
+ cd path/to/your-repo && headron init # finds your checks, wires your agents, installs the commit hook, runs once
107
+ headron verify && headron proof <file> --verify # after a change: verdicts, then a file's proof
110
108
  ```
111
109
 
112
- With an impact map, `headron verify --changed` evaluates modified files in seconds.
110
+ With an impact map, `headron verify --changed` evaluates checks for modified files.
113
111
  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.
114
112
 
115
113
  **Machines:** [bootstrap](.agent/bootstrap.json), [facts](.agent/facts.json), and [JSON schema](tools/atlas-output.schema.json).
116
- **Agents:** [entry](llms.txt), [adapters](models/README.md); the MCP interface is read-only.
117
- **Chats:** [no-shell setup](CHAT.md). For another repository, see [CONSUMING](docs/CONSUMING.md).
114
+ **Agents:** [adapters](models/README.md); the MCP interface is read-only.
115
+ **Another repository:** [CONSUMING](docs/CONSUMING.md).
118
116
 
119
- ## What it measurably buys
117
+ ## Recorded results
120
118
 
121
119
  See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove) for their scope.
122
120
 
@@ -125,27 +123,24 @@ See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove)
125
123
  <!-- prettier-ignore -->
126
124
  | Instrument | Recorded result |
127
125
  | :--- | :--- |
128
- | Enforcement | 31/31 breaks refused across 20 toolchains; **754** declared planted cases |
129
- | Failure ledger | 122 shapes, 209 sightings; 99 in-tree guarded, 23 host-only |
130
- | Field ledger | 856 verifications (127 clean); 1133 refusals; 329 landings; 711 lessons; 392 sessions |
131
- | Verification outcomes | 15,206 checks: 6,148 PASS, 1,095 REUSED, 850 FAIL, 7,113 NOT RUN. 464 runs failed; 265 held on an unrun check; 0 clean with a gap |
126
+ | Enforcement | 31/31 breaks refused across 20 toolchains; **816** declared planted cases |
127
+ | Failure ledger | 128 shapes, 220 sightings; 104 in-tree guarded, 24 host-only |
128
+ | Field ledger | 940 verifications (136 clean); 1133 refusals; 394 landings; 711 lessons; 394 sessions |
129
+ | Verification outcomes | 17,397 checks: 7,357 PASS, 1,097 REUSED, 1,278 FAIL, 7,665 NOT RUN. 533 runs failed; 271 stopped with an unrun check; 0 reported clean despite a failed or unrun check |
132
130
  | Routing experiment | 89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models |
133
131
  | Language roles | 360 pairs: 110 runnable, 0 undeclared |
134
132
 
135
- Entry context: ~1,734 tokens. The 200 documents (649 KiB) load on demand; install: 10 KiB, 8 dependencies.
133
+ Entry context: ~1,593 tokens. The 211 documents (708 KiB) load on demand; install: 10 KiB; hash lock with test tools: 8 packages.
136
134
  [Field records](benchmarks/field-latest.json). [Routing data](benchmarks/ab-latest.json). Measures can overlap.
137
135
 
138
136
  <!-- END generated: measured-benefits -->
139
137
 
140
138
  ## Where it fits
141
139
 
142
- - **Any agent or runtime.** One sovereign contract across all agent architectures (Google Antigravity,
143
- Claude Code, Cursor, OpenAI Codex, OpenHands, Windsurf, Hermes, or bare CLI). The adapters in
144
- [models/README.md](models/README.md) keep native tools intact while enforcing identical deterministic boundaries.
145
- - **Any repository.** `headron init` wires a repository in one step. Consumers add the reusable CI
146
- workflow from [CONSUMING](docs/CONSUMING.md) so the verdict on a laptop and in CI is the same command.
147
- - **Any language we route.** Each language × check pair is either answered by a command or declared
148
- as having no tool, so an unanswered pair cannot hide.
140
+ - **Agents and runtimes:** [adapters](models/README.md) describe supported integrations.
141
+ - **Headron-Harness:** a separate desktop dashboard and runtime; see [product boundaries](docs/PRODUCT-STRATEGY.md).
142
+ - **Other repositories:** `headron init` sets up a repository; [CONSUMING](docs/CONSUMING.md) covers CI, the [GitHub Action](docs/CONSUMING.md#as-a-github-action) and the [hosted MCP](docs/CONSUMING.md#hosted-mind-api--mcp).
143
+ - **Languages:** routes declare available checks and identify checks without a tool.
149
144
 
150
145
  ## Agent contract
151
146
 
@@ -153,19 +148,20 @@ Entry context: ~1,734 tokens. The 200 documents (649 KiB) load on demand; instal
153
148
 
154
149
  ```console
155
150
  $ headron port scripts/doctor.py --line
156
- ◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠1 │ → headron gate scripts/doctor.py
151
+ ◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠2 │ → headron gate scripts/doctor.py
157
152
  $ headron port scripts --line
158
- ◎ scripts │ ⠟171 │ ⌂scripts │ → headron brainstorm
153
+ ◎ scripts │ ⠟186 │ ⌂scripts │ → headron brainstorm
159
154
  $ headron port . --line
160
- ○ . │ ⠟199 ⠁4 ⠿4 │ → headron check
155
+ ○ . │ ⠟214 ⠿4 ⠁1 │ → headron check
161
156
  ```
162
157
 
163
158
  <!-- END generated: port-example -->
164
159
 
165
- - **Discover:** `headron find <query>` searches paths, symbols and vocabulary with pointers; `headron sweep` maps topology. Search does not guarantee semantic recall.
160
+ - **Discover:** `headron find <query>` searches paths, symbols and vocabulary; `headron sweep` maps topology. Search does not guarantee semantic recall.
166
161
  - **Route:** `headron port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only its names.
167
- - **Processes:** `headron process --json` lists workflows; `headron process <id> --json` gives steps and gates. These are references, not an executor.
168
- - **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` retrieves audit trails.
162
+ - **Processes:** `headron process [<id>] --json` lists workflows; with an id, its steps and gates.
163
+ - **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` summarizes the latest local verification record.
164
+ - **Beliefs:** `headron revise` names what rests on a refuted claim; `headron propose` drafts each fix outside the tree.
169
165
  - **Automate:** add `--json`; records follow [the output schema](tools/atlas-output.schema.json).
170
166
  - **Before shell:** `headron shell --json "<cmd>"`; exit 3 means its verdict would be misread.
171
167
  - **Land:** `python scripts/branchstate.py --land`; check `headron landed <branch>` before deletion.
@@ -177,35 +173,21 @@ $ headron port . --line
177
173
  - **Languages:** [atlas](languages/ATLAS.md) · [routing](docs/wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
178
174
  - **Agents:** [harness](docs/systems/AGENT-HARNESS.md) · [`.headron`](docs/HEADRON-LANGUAGE.md) · [runtimes](models/README.md)
179
175
  - **Why a rule:** `headron why` · `headron failures` · [instruments](docs/INSTRUMENTS.md)
176
+ - **Companion products:** [desktop, web, enterprise](docs/CONSUMING.md#optional-hlintel-services)
180
177
  - **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md) · [contributing](CONTRIBUTING.md)
181
178
 
182
- ## Enterprise and companion runtimes
183
-
184
- Headron Software is the core product of HLIntel (Headron Layer Intelligence):
185
-
186
- - **HeadronOS:** desktop workspace and local runtime.
187
- - **Headron Web:** browser interface.
188
- - **Headron Enterprise:** organizational offering across desktop and web.
189
- - **Headron MCP:** integration connecting agents and developer tools.
190
- - **HL.Verify:** shared verification capability.
191
- - _Rules & Gates:_ File-targeted proof obligations and pre-commit enforcers.
192
- - _Failure Ledger:_ Past agent failure catalog and regression seeds.
193
- - **Mind API:** shared orchestration interface.
194
-
195
- [Companion details](docs/CONSUMING.md#optional-hlintel-services).
196
-
197
179
  ## Counts, computed
198
180
 
199
- Generated on every build; `check` refuses drift. Machine-readable: [.agent/facts.json](.agent/facts.json).
181
+ Generated on every build; `check` refuses drift.
200
182
 
201
183
  <!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
202
184
 
203
- - **49** hard invariants — enforced on every change, zero unowned
204
- - **354** agreement edges — each a file tied to the declaration it answers for
205
- - **94** instruments — each stating what it proves, what it does not, and what closes the gap
185
+ - **52** hard invariants — enforced on every change, zero unowned
186
+ - **368** agreement edges — each a file tied to the declaration it answers for
187
+ - **95** instruments — each stating what it proves, what it does not, and what closes the gap
206
188
  - **385** tool entries — across 40 manifests and 5 kinds, validated against `tools/tools.schema.json`
207
- - **169** harness Python files — every one held by `lint` · `format` · `typecheck`
208
- - **3.62.0** contract version — `VERSION`, asserted in 10 other files
189
+ - **184** harness Python files — every one held by `lint` · `format` · `typecheck`
190
+ - **3.63.0** contract version — `VERSION`, asserted in 10 other files
209
191
 
210
192
  <!-- END generated: repository-facts -->
211
193
 
@@ -214,4 +196,4 @@ Generated on every build; `check` refuses drift. Machine-readable: [.agent/facts
214
196
  Version tracks the **contract**, not content ([versioning](docs/VERSIONING.md)).
215
197
  Built by **HLIntel LLC**, public on purpose ([about](ABOUT.md)). Contributions pass `headron verify`. [MIT License](LICENSE).
216
198
 
217
- Updated: contract v3.62.0
199
+ Updated: contract v3.63.0
headron_software-3.63.0/README.md ADDED
@@ -0,0 +1,169 @@
1
+ <!-- AGENTS: do not read this page breadth-first. Run `headron port <file>` (in a clone,
2
+ `python scripts/atlas.py port <file>`), or parse .agent/bootstrap.json. -->
3
+ <!-- mcp-name: io.github.HLIntel/headron -->
4
+ <div align="center">
5
+ <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.jpg"
6
+ alt="Headron Software: AI governance and verification"
7
+ width="992">
8
+ <h1>Headron Software</h1>
9
+ </div>
10
+
11
+ <!-- BEGIN generated: badges (python scripts/atlas.py index --write) -->
12
+
13
+ **Contract 3.63.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
14
+
15
+ <!-- END generated: badges -->
16
+
17
+ <!-- BEGIN generated: headline (python scripts/atlas.py index --write) -->
18
+
19
+ - **Is:** a rule contract and CLI mapping changed files to checks. Hooks are optional; `headron verify` runs done gates.
20
+ - **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.
21
+ - **`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.
22
+ - **Mind API:** hosted, paid, needs a key; plans a declared change. The command line works without it.
23
+
24
+ Agents: [llms.txt](llms.txt). Chats: [CHAT.md](CHAT.md). [Evidence](#recorded-results).
25
+
26
+ <!-- END generated: headline -->
27
+
28
+ ## Why this exists
29
+
30
+ Headron connects changed files to declared checks and reports whether those checks ran. A skipped
31
+ check is not a pass. An optional Git hook can run checks before a commit, whether the change came
32
+ from a developer or an agent.
33
+
34
+ ## How it works
35
+
36
+ `headron port <file>` tells an agent what a file owes before it edits. [`atlas.yaml`](atlas.yaml)
37
+ holds those checks; the commit hook and CI report `PASS`, `FAIL`, `SKIP` or `NOT RUN`. The hosted
38
+ [Mind API](https://headron.tech/mind-api.html) plans a declared change through `headron mind`.
39
+
40
+ <!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
41
+
42
+ <p align="center">
43
+ <img src="docs/media/headron-proof-flow.svg" width="900"
44
+ alt="Headron Architecture: contract, targeted evidence, integrity audit, unified verdict.">
45
+ </p>
46
+
47
+ <!-- END generated: proof-flow -->
48
+
49
+ <!-- BEGIN generated: gate-example (python scripts/atlas.py index --write) -->
50
+
51
+ ```console
52
+ $ headron gate scripts/doctor.py
53
+ 1. formatter: ruff format --check scripts/doctor.py
54
+ 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
55
+ 3. unit_tests: pytest
56
+ ```
57
+
58
+ <!-- END generated: gate-example -->
59
+
60
+ ## Quickstart
61
+
62
+ <!-- BEGIN generated: install (python scripts/atlas.py index --write) -->
63
+
64
+ ```bash
65
+ # install
66
+ uv tool install headron-software && headron doctor
67
+ # editable, to change Headron itself
68
+ git clone --depth 1 --branch v3.63.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
69
+ ```
70
+
71
+ <!-- END generated: install -->
72
+
73
+ In your repository:
74
+
75
+ ```bash
76
+ cd path/to/your-repo && headron init # finds your checks, wires your agents, installs the commit hook, runs once
77
+ headron verify && headron proof <file> --verify # after a change: verdicts, then a file's proof
78
+ ```
79
+
80
+ With an impact map, `headron verify --changed` evaluates checks for modified files.
81
+ 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.
82
+
83
+ **Machines:** [bootstrap](.agent/bootstrap.json), [facts](.agent/facts.json), and [JSON schema](tools/atlas-output.schema.json).
84
+ **Agents:** [adapters](models/README.md); the MCP interface is read-only.
85
+ **Another repository:** [CONSUMING](docs/CONSUMING.md).
86
+
87
+ ## Recorded results
88
+
89
+ See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove) for their scope.
90
+
91
+ <!-- BEGIN generated: measured-benefits (python scripts/atlas.py index --write) -->
92
+
93
+ <!-- prettier-ignore -->
94
+ | Instrument | Recorded result |
95
+ | :--- | :--- |
96
+ | Enforcement | 31/31 breaks refused across 20 toolchains; **816** declared planted cases |
97
+ | Failure ledger | 128 shapes, 220 sightings; 104 in-tree guarded, 24 host-only |
98
+ | Field ledger | 940 verifications (136 clean); 1133 refusals; 394 landings; 711 lessons; 394 sessions |
99
+ | Verification outcomes | 17,397 checks: 7,357 PASS, 1,097 REUSED, 1,278 FAIL, 7,665 NOT RUN. 533 runs failed; 271 stopped with an unrun check; 0 reported clean despite a failed or unrun check |
100
+ | Routing experiment | 89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models |
101
+ | Language roles | 360 pairs: 110 runnable, 0 undeclared |
102
+
103
+ Entry context: ~1,593 tokens. The 211 documents (708 KiB) load on demand; install: 10 KiB; hash lock with test tools: 8 packages.
104
+ [Field records](benchmarks/field-latest.json). [Routing data](benchmarks/ab-latest.json). Measures can overlap.
105
+
106
+ <!-- END generated: measured-benefits -->
107
+
108
+ ## Where it fits
109
+
110
+ - **Agents and runtimes:** [adapters](models/README.md) describe supported integrations.
111
+ - **Headron-Harness:** a separate desktop dashboard and runtime; see [product boundaries](docs/PRODUCT-STRATEGY.md).
112
+ - **Other repositories:** `headron init` sets up a repository; [CONSUMING](docs/CONSUMING.md) covers CI, the [GitHub Action](docs/CONSUMING.md#as-a-github-action) and the [hosted MCP](docs/CONSUMING.md#hosted-mind-api--mcp).
113
+ - **Languages:** routes declare available checks and identify checks without a tool.
114
+
115
+ ## Agent contract
116
+
117
+ <!-- BEGIN generated: port-example (python scripts/atlas.py index --write) -->
118
+
119
+ ```console
120
+ $ headron port scripts/doctor.py --line
121
+ ◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠2 │ → headron gate scripts/doctor.py
122
+ $ headron port scripts --line
123
+ ◎ scripts │ ⠟186 │ ⌂scripts │ → headron brainstorm
124
+ $ headron port . --line
125
+ ○ . │ ⠟214 ⠿4 ⠁1 │ → headron check
126
+ ```
127
+
128
+ <!-- END generated: port-example -->
129
+
130
+ - **Discover:** `headron find <query>` searches paths, symbols and vocabulary; `headron sweep` maps topology. Search does not guarantee semantic recall.
131
+ - **Route:** `headron port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only its names.
132
+ - **Processes:** `headron process [<id>] --json` lists workflows; with an id, its steps and gates.
133
+ - **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` summarizes the latest local verification record.
134
+ - **Beliefs:** `headron revise` names what rests on a refuted claim; `headron propose` drafts each fix outside the tree.
135
+ - **Automate:** add `--json`; records follow [the output schema](tools/atlas-output.schema.json).
136
+ - **Before shell:** `headron shell --json "<cmd>"`; exit 3 means its verdict would be misread.
137
+ - **Land:** `python scripts/branchstate.py --land`; check `headron landed <branch>` before deletion.
138
+ - **Judge and report:** use the [judgment rungs](docs/systems/AGENT-HARNESS.md#judgment-rungs); file breaks with the [`headron` skill](skills/headron/SKILL.md).
139
+
140
+ ## Find your way
141
+
142
+ - **Every document:** [docs index](docs/INDEX.md) · [wiki](docs/wiki/README.md)
143
+ - **Languages:** [atlas](languages/ATLAS.md) · [routing](docs/wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
144
+ - **Agents:** [harness](docs/systems/AGENT-HARNESS.md) · [`.headron`](docs/HEADRON-LANGUAGE.md) · [runtimes](models/README.md)
145
+ - **Why a rule:** `headron why` · `headron failures` · [instruments](docs/INSTRUMENTS.md)
146
+ - **Companion products:** [desktop, web, enterprise](docs/CONSUMING.md#optional-hlintel-services)
147
+ - **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md) · [contributing](CONTRIBUTING.md)
148
+
149
+ ## Counts, computed
150
+
151
+ Generated on every build; `check` refuses drift.
152
+
153
+ <!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
154
+
155
+ - **52** hard invariants — enforced on every change, zero unowned
156
+ - **368** agreement edges — each a file tied to the declaration it answers for
157
+ - **95** instruments — each stating what it proves, what it does not, and what closes the gap
158
+ - **385** tool entries — across 40 manifests and 5 kinds, validated against `tools/tools.schema.json`
159
+ - **184** harness Python files — every one held by `lint` · `format` · `typecheck`
160
+ - **3.63.0** contract version — `VERSION`, asserted in 10 other files
161
+
162
+ <!-- END generated: repository-facts -->
163
+
164
+ ## Project
165
+
166
+ Version tracks the **contract**, not content ([versioning](docs/VERSIONING.md)).
167
+ Built by **HLIntel LLC**, public on purpose ([about](ABOUT.md)). Contributions pass `headron verify`. [MIT License](LICENSE).
168
+
169
+ Updated: contract v3.63.0
headron_software-3.63.0/VERSION ADDED
@@ -0,0 +1 @@
1
+ 3.63.0
{headron_software-3.62.0 → headron_software-3.63.0}/pyproject.toml RENAMED
@@ -1,20 +1,6 @@
1
1
  # Headron — Python project declaration.
2
2
  #
3
- # WHY THIS FILE EXISTS (added at contract v1.2.0). `.ruff_cache/` and `.pytest_cache/` were already at the repo
4
- # root: ruff and pytest have been RUN here for some time while nothing declared them, nothing
5
- # configured them, and no gate enforced them. That is an undeclared habit, and an undeclared habit
6
- # is the thing that silently changes. This file declares exactly what is true and REFUSES to
7
- # declare what is not — because a config that names a gate nobody runs is the same skeleton this
8
- # repo exists to prevent.
9
- #
10
- # MEASURED BEFORE WRITING ANY OF IT (instrument: `ruff check . --show-files`, `ruff format --check`,
11
- # `python3 -m pytest -q`, all run at v1.2.0):
12
- # - ruff saw exactly SIX Python files then; re-measured at v1.3.0 after the harness was
13
- # split into modules, it sees 8. The count is not typed into a document: README's
14
- # generated facts block computes it from scripts/*.py on every run.
15
- # - `ruff check .` -> All checks passed, exit 0. Safe to enforce at that version, and enforced since.
16
- # - `ruff format --check` -> enforced at 3.50.0, after one reviewed reformat; see [tool.ruff.format].
17
- # - `python3 -m pytest -q` -> "no tests ran". Not adopted; see [tool.pytest] below.
3
+ # Package metadata and the Python harness's checked configuration live here.
18
4
 
19
5
  # THIS FILE DESCRIBES THE HARNESS, NOT THE REPOSITORY.
20
6
  # The atlas is polyglot and is not a Python project; Python is simply what the contract
@@ -28,7 +14,7 @@ name = "headron-software" # 3.53.0: the index name a stranger typ
28
14
  dynamic = ["version"] # READ FROM VERSION, never typed here: a second declaration goes
29
15
  # stale first. The installed version is the release tag the CLI
30
16
  # fetches its atlas from when no root is declared.
31
- description = "AI coding-agent verification: tells agents which commands prove a change and fails the build when one was skipped. Polyglot; CLI, MCP server, git hooks, CI."
17
+ description = "Command line tool and rule contract for AI coding agents: each changed file maps to the checks it owes, and a commit whose file fails is refused."
32
18
  readme = "README.md" # the PyPI page; carries the registry ownership marker (server.json)
33
19
  license = "MIT"
34
20
  requires-python = ">=3.11"
@@ -44,7 +30,7 @@ classifiers = ["Development Status :: 4 - Beta", "Intended Audience :: Developer
44
30
  # FOUND FROM AN INSTALL. Before 2.28.0 an installed package named no link at all, so an agent
45
31
  # handed only `pip show` had no route back to the atlas, its entry or its instructions.
46
32
  [project.urls]
47
- Homepage = "https://github.com/HLIntel/Headron"
33
+ Homepage = "https://headron.tech"
48
34
  Documentation = "https://github.com/HLIntel/Headron/blob/main/llms.txt"
49
35
  Issues = "https://github.com/HLIntel/Headron/issues"
50
36
  Source = "https://github.com/HLIntel/Headron"
@@ -106,7 +92,10 @@ select = ["E", "F", "I", # pycodestyle errors, pyflakes, import sor
106
92
  # if, a returned condition, an any/all loop, a ternary over an if-block, and no else
107
93
  # after return/raise/continue — guard clauses. PERF401 was measured too and REJECTED:
108
94
  # 31 error-collecting loops with no safe fix, whose messages would hide in generators.
109
- "C4", "SIM102", "SIM103", "SIM108", "SIM110", "RET505", "RET506", "RET508"]
95
+ "C4", "SIM102", "SIM103", "SIM108", "SIM110", "RET505", "RET506", "RET508",
96
+ # S110, an `except Exception: pass` that hides a programming error. Four hits
97
+ # (mind.py x3, mind_diagnostics.py x1) were narrowed to the errors each expects, so zero.
98
+ "S110"]
110
99
  ignore = ["E501"] # line length is governed by line-length above, not by a lint error
111
100
 
112
101
  [tool.ruff.lint.isort]
@@ -144,16 +133,9 @@ quote-style = "double"
144
133
  skip-magic-trailing-comma = true
145
134
 
146
135
  # [tool.pytest.ini_options] IS DELIBERATELY ABSENT.
147
- # A bare `python3 -m pytest -q` here would collect only the planted failing tests under
148
- # benchmarks/agent/ and read as broken code; the root conftest.py refuses it (exit 4) and names the
149
- # real commands. A path on the command line still runs that fixture. The contract's mutation tests
150
- # are a custom harness run directly:
151
- #
152
- # python3 scripts/atlas_test.py -> "atlas tests: N/N pass" with N asserted, exit 0
153
- #
154
- # declared in that file's own docblock and wired into ci/atlas-ci.yml. Declaring a
155
- # pytest section now would add a second, empty test surface whose green exit means nothing. When a
156
- # real pytest suite exists, configure it here and give it a failing case first.
136
+ # A bare invocation could collect planted failures under benchmarks/agent/, so conftest.py refuses
137
+ # it. Explicit paths still work. The artifacts_tests gate selects the artifact and data kit cases;
138
+ # the mutation suite is a separate harness run by verify.
157
139
 
158
140
  [tool.basedpyright]
159
141
  # THE PACK'S DECLARED TYPE CHECKER, RUN ON ITS OWN TREE (3.54.0): gate `typecheck`. Standard mode, the
{headron_software-3.62.0 → headron_software-3.63.0}/scripts/atlas_cli.py RENAMED
@@ -11,8 +11,10 @@ THAT TREE IS LOCKED (3.54.0): read-only, re-hashed on every run; an edit refuses
11
11
 
12
12
  from __future__ import annotations
13
13
 
14
+ import contextlib
14
15
  import hashlib
15
16
  import io
17
+ import json
16
18
  import os
17
19
  import re
18
20
  import shutil
@@ -229,7 +231,19 @@ def mcp_main() -> int:
229
231
  argv = sys.argv[1:]
230
232
  if "--where" in argv:
231
233
  return main(argv)
232
- if _enter(argv, "headron_mcp.py")[0] is None:
234
+ said = io.StringIO()
235
+ with contextlib.redirect_stderr(said):
236
+ root = _enter(argv, "headron_mcp.py")[0]
237
+ sys.stderr.write(said.getvalue())
238
+ if root is None:
239
+ # REFUSE IN THE HANDSHAKE (3.63.0): exiting before `initialize` showed the client only "Connection closed".
240
+ try:
241
+ ask = {} if sys.stdin.isatty() else json.loads(sys.stdin.readline() or "{}")
242
+ except ValueError:
243
+ ask = {}
244
+ if isinstance(ask, dict) and "id" in ask:
245
+ why = {"code": -32000, "message": "headron-mcp refused: " + " ".join(said.getvalue().split())}
246
+ print(json.dumps({"jsonrpc": "2.0", "id": ask["id"], "error": why}), flush=True)
233
247
  return 2
234
248
  import headron_mcp # noqa: PLC0415 — as in main
235
249
 
{headron_software-3.62.0 → headron_software-3.63.0/scripts/headron_software.egg-info}/PKG-INFO RENAMED
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: headron-software
3
- Version: 3.62.0
4
- Summary: AI coding-agent verification: tells agents which commands prove a change and fails the build when one was skipped. Polyglot; CLI, MCP server, git hooks, CI.
3
+ Version: 3.63.0
4
+ Summary: Command line tool and rule contract for AI coding agents: each changed file maps to the checks it owes, and a commit whose file fails is refused.
5
5
  License-Expression: MIT
6
- Project-URL: Homepage, https://github.com/HLIntel/Headron
6
+ Project-URL: Homepage, https://headron.tech
7
7
  Project-URL: Documentation, https://github.com/HLIntel/Headron/blob/main/llms.txt
8
8
  Project-URL: Issues, https://github.com/HLIntel/Headron/issues
9
9
  Project-URL: Source, https://github.com/HLIntel/Headron
@@ -28,11 +28,11 @@ Provides-Extra: crosscheck
28
28
  Requires-Dist: jsonschema>=4; extra == "crosscheck"
29
29
  Dynamic: license-file
30
30
 
31
- <!-- AGENTS: do not read this page breadth-first. Plug in: `python scripts/atlas.py port <file>`,
32
- or parse .agent/bootstrap.json — one record back. -->
31
+ <!-- AGENTS: do not read this page breadth-first. Run `headron port <file>` (in a clone,
32
+ `python scripts/atlas.py port <file>`), or parse .agent/bootstrap.json. -->
33
33
  <!-- mcp-name: io.github.HLIntel/headron -->
34
34
  <div align="center">
35
- <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.svg"
35
+ <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.jpg"
36
36
  alt="Headron Software: AI governance and verification"
37
37
  width="992">
38
38
  <h1>Headron Software</h1>
@@ -40,34 +40,32 @@ Dynamic: license-file
40
40
 
41
41
  <!-- BEGIN generated: badges (python scripts/atlas.py index --write) -->
42
42
 
43
- **Contract 3.62.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
43
+ **Contract 3.63.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
44
44
 
45
45
  <!-- END generated: badges -->
46
46
 
47
47
  <!-- BEGIN generated: headline (python scripts/atlas.py index --write) -->
48
48
 
49
- **Protocol:** a change maps to proof; Headron selects evidence and the build enforces the verdict ([evidence](#what-it-measurably-buys)). Agents: [llms.txt](llms.txt); chats: [CHAT.md](CHAT.md).
49
+ - **Is:** a rule contract and CLI mapping changed files to checks. Hooks are optional; `headron verify` runs done gates.
50
+ - **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.
51
+ - **`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.
52
+ - **Mind API:** hosted, paid, needs a key; plans a declared change. The command line works without it.
53
+
54
+ Agents: [llms.txt](llms.txt). Chats: [CHAT.md](CHAT.md). [Evidence](#recorded-results).
50
55
 
51
56
  <!-- END generated: headline -->
52
57
 
53
58
  ## Why this exists
54
59
 
55
- An agent can report a change as done without running a single check. A check that never ran looks
56
- the same as a check that passed. Headron Software closes that gap:
57
-
58
- - **Every change maps to proof.** [`atlas.yaml`](atlas.yaml) lists the checks each kind of file owes,
59
- and the gate runs them before the change is called finished.
60
- - **Refusal happens at commit, for any agent.** A git hook runs the same check-only command whether
61
- an autonomous agent, an IDE extension, a chat assistant, or a developer made the commit.
62
- - **A skipped check is never a pass.** A missing tool is reported as `SKIP` and kept out
63
- of the pass count. Gates report `PASS`, `FAIL` or `NOT RUN`.
60
+ Headron connects changed files to declared checks and reports whether those checks ran. A skipped
61
+ check is not a pass. An optional Git hook can run checks before a commit, whether the change came
62
+ from a developer or an agent.
64
63
 
65
64
  ## How it works
66
65
 
67
- **System 1:** `headron port <file>` routes task context. **System 2:** [`atlas.yaml`](atlas.yaml)
68
- maps changes to gates; hooks and CI emit `PASS`, `FAIL`, `SKIP`, or `NOT RUN`. The
69
- hosted [Mind API](https://headron.tech/mind-api.html) plans a declared change; `headron mind`
70
- adds **classify → route → receipts**.
66
+ `headron port <file>` tells an agent what a file owes before it edits. [`atlas.yaml`](atlas.yaml)
67
+ holds those checks; the commit hook and CI report `PASS`, `FAIL`, `SKIP` or `NOT RUN`. The hosted
68
+ [Mind API](https://headron.tech/mind-api.html) plans a declared change through `headron mind`.
71
69
 
72
70
  <!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
73
71
 
@@ -97,7 +95,7 @@ $ headron gate scripts/doctor.py
97
95
  # install
98
96
  uv tool install headron-software && headron doctor
99
97
  # editable, to change Headron itself
100
- git clone --depth 1 --branch v3.62.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
98
+ git clone --depth 1 --branch v3.63.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
101
99
  ```
102
100
 
103
101
  <!-- END generated: install -->
@@ -105,18 +103,18 @@ git clone --depth 1 --branch v3.62.0 https://github.com/HLIntel/Headron ~/headro
105
103
  In your repository:
106
104
 
107
105
  ```bash
108
- cd path/to/your-repo && headron init # checks, universal multi-agent wiring, first run
109
- headron verify && headron report # after a change: verdicts, then what is unverified
106
+ cd path/to/your-repo && headron init # finds your checks, wires your agents, installs the commit hook, runs once
107
+ headron verify && headron proof <file> --verify # after a change: verdicts, then a file's proof
110
108
  ```
111
109
 
112
- With an impact map, `headron verify --changed` evaluates modified files in seconds.
110
+ With an impact map, `headron verify --changed` evaluates checks for modified files.
113
111
  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.
114
112
 
115
113
  **Machines:** [bootstrap](.agent/bootstrap.json), [facts](.agent/facts.json), and [JSON schema](tools/atlas-output.schema.json).
116
- **Agents:** [entry](llms.txt), [adapters](models/README.md); the MCP interface is read-only.
117
- **Chats:** [no-shell setup](CHAT.md). For another repository, see [CONSUMING](docs/CONSUMING.md).
114
+ **Agents:** [adapters](models/README.md); the MCP interface is read-only.
115
+ **Another repository:** [CONSUMING](docs/CONSUMING.md).
118
116
 
119
- ## What it measurably buys
117
+ ## Recorded results
120
118
 
121
119
  See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove) for their scope.
122
120
 
@@ -125,27 +123,24 @@ See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove)
125
123
  <!-- prettier-ignore -->
126
124
  | Instrument | Recorded result |
127
125
  | :--- | :--- |
128
- | Enforcement | 31/31 breaks refused across 20 toolchains; **754** declared planted cases |
129
- | Failure ledger | 122 shapes, 209 sightings; 99 in-tree guarded, 23 host-only |
130
- | Field ledger | 856 verifications (127 clean); 1133 refusals; 329 landings; 711 lessons; 392 sessions |
131
- | Verification outcomes | 15,206 checks: 6,148 PASS, 1,095 REUSED, 850 FAIL, 7,113 NOT RUN. 464 runs failed; 265 held on an unrun check; 0 clean with a gap |
126
+ | Enforcement | 31/31 breaks refused across 20 toolchains; **816** declared planted cases |
127
+ | Failure ledger | 128 shapes, 220 sightings; 104 in-tree guarded, 24 host-only |
128
+ | Field ledger | 940 verifications (136 clean); 1133 refusals; 394 landings; 711 lessons; 394 sessions |
129
+ | Verification outcomes | 17,397 checks: 7,357 PASS, 1,097 REUSED, 1,278 FAIL, 7,665 NOT RUN. 533 runs failed; 271 stopped with an unrun check; 0 reported clean despite a failed or unrun check |
132
130
  | Routing experiment | 89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models |
133
131
  | Language roles | 360 pairs: 110 runnable, 0 undeclared |
134
132
 
135
- Entry context: ~1,734 tokens. The 200 documents (649 KiB) load on demand; install: 10 KiB, 8 dependencies.
133
+ Entry context: ~1,593 tokens. The 211 documents (708 KiB) load on demand; install: 10 KiB; hash lock with test tools: 8 packages.
136
134
  [Field records](benchmarks/field-latest.json). [Routing data](benchmarks/ab-latest.json). Measures can overlap.
137
135
 
138
136
  <!-- END generated: measured-benefits -->
139
137
 
140
138
  ## Where it fits
141
139
 
142
- - **Any agent or runtime.** One sovereign contract across all agent architectures (Google Antigravity,
143
- Claude Code, Cursor, OpenAI Codex, OpenHands, Windsurf, Hermes, or bare CLI). The adapters in
144
- [models/README.md](models/README.md) keep native tools intact while enforcing identical deterministic boundaries.
145
- - **Any repository.** `headron init` wires a repository in one step. Consumers add the reusable CI
146
- workflow from [CONSUMING](docs/CONSUMING.md) so the verdict on a laptop and in CI is the same command.
147
- - **Any language we route.** Each language × check pair is either answered by a command or declared
148
- as having no tool, so an unanswered pair cannot hide.
140
+ - **Agents and runtimes:** [adapters](models/README.md) describe supported integrations.
141
+ - **Headron-Harness:** a separate desktop dashboard and runtime; see [product boundaries](docs/PRODUCT-STRATEGY.md).
142
+ - **Other repositories:** `headron init` sets up a repository; [CONSUMING](docs/CONSUMING.md) covers CI, the [GitHub Action](docs/CONSUMING.md#as-a-github-action) and the [hosted MCP](docs/CONSUMING.md#hosted-mind-api--mcp).
143
+ - **Languages:** routes declare available checks and identify checks without a tool.
149
144
 
150
145
  ## Agent contract
151
146
 
@@ -153,19 +148,20 @@ Entry context: ~1,734 tokens. The 200 documents (649 KiB) load on demand; instal
153
148
 
154
149
  ```console
155
150
  $ headron port scripts/doctor.py --line
156
- ◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠1 │ → headron gate scripts/doctor.py
151
+ ◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠2 │ → headron gate scripts/doctor.py
157
152
  $ headron port scripts --line
158
- ◎ scripts │ ⠟171 │ ⌂scripts │ → headron brainstorm
153
+ ◎ scripts │ ⠟186 │ ⌂scripts │ → headron brainstorm
159
154
  $ headron port . --line
160
- ○ . │ ⠟199 ⠁4 ⠿4 │ → headron check
155
+ ○ . │ ⠟214 ⠿4 ⠁1 │ → headron check
161
156
  ```
162
157
 
163
158
  <!-- END generated: port-example -->
164
159
 
165
- - **Discover:** `headron find <query>` searches paths, symbols and vocabulary with pointers; `headron sweep` maps topology. Search does not guarantee semantic recall.
160
+ - **Discover:** `headron find <query>` searches paths, symbols and vocabulary; `headron sweep` maps topology. Search does not guarantee semantic recall.
166
161
  - **Route:** `headron port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only its names.
167
- - **Processes:** `headron process --json` lists workflows; `headron process <id> --json` gives steps and gates. These are references, not an executor.
168
- - **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` retrieves audit trails.
162
+ - **Processes:** `headron process [<id>] --json` lists workflows; with an id, its steps and gates.
163
+ - **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` summarizes the latest local verification record.
164
+ - **Beliefs:** `headron revise` names what rests on a refuted claim; `headron propose` drafts each fix outside the tree.
169
165
  - **Automate:** add `--json`; records follow [the output schema](tools/atlas-output.schema.json).
170
166
  - **Before shell:** `headron shell --json "<cmd>"`; exit 3 means its verdict would be misread.
171
167
  - **Land:** `python scripts/branchstate.py --land`; check `headron landed <branch>` before deletion.
@@ -177,35 +173,21 @@ $ headron port . --line
177
173
  - **Languages:** [atlas](languages/ATLAS.md) · [routing](docs/wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
178
174
  - **Agents:** [harness](docs/systems/AGENT-HARNESS.md) · [`.headron`](docs/HEADRON-LANGUAGE.md) · [runtimes](models/README.md)
179
175
  - **Why a rule:** `headron why` · `headron failures` · [instruments](docs/INSTRUMENTS.md)
176
+ - **Companion products:** [desktop, web, enterprise](docs/CONSUMING.md#optional-hlintel-services)
180
177
  - **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md) · [contributing](CONTRIBUTING.md)
181
178
 
182
- ## Enterprise and companion runtimes
183
-
184
- Headron Software is the core product of HLIntel (Headron Layer Intelligence):
185
-
186
- - **HeadronOS:** desktop workspace and local runtime.
187
- - **Headron Web:** browser interface.
188
- - **Headron Enterprise:** organizational offering across desktop and web.
189
- - **Headron MCP:** integration connecting agents and developer tools.
190
- - **HL.Verify:** shared verification capability.
191
- - _Rules & Gates:_ File-targeted proof obligations and pre-commit enforcers.
192
- - _Failure Ledger:_ Past agent failure catalog and regression seeds.
193
- - **Mind API:** shared orchestration interface.
194
-
195
- [Companion details](docs/CONSUMING.md#optional-hlintel-services).
196
-
197
179
  ## Counts, computed
198
180
 
199
- Generated on every build; `check` refuses drift. Machine-readable: [.agent/facts.json](.agent/facts.json).
181
+ Generated on every build; `check` refuses drift.
200
182
 
201
183
  <!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
202
184
 
203
- - **49** hard invariants — enforced on every change, zero unowned
204
- - **354** agreement edges — each a file tied to the declaration it answers for
205
- - **94** instruments — each stating what it proves, what it does not, and what closes the gap
185
+ - **52** hard invariants — enforced on every change, zero unowned
186
+ - **368** agreement edges — each a file tied to the declaration it answers for
187
+ - **95** instruments — each stating what it proves, what it does not, and what closes the gap
206
188
  - **385** tool entries — across 40 manifests and 5 kinds, validated against `tools/tools.schema.json`
207
- - **169** harness Python files — every one held by `lint` · `format` · `typecheck`
208
- - **3.62.0** contract version — `VERSION`, asserted in 10 other files
189
+ - **184** harness Python files — every one held by `lint` · `format` · `typecheck`
190
+ - **3.63.0** contract version — `VERSION`, asserted in 10 other files
209
191
 
210
192
  <!-- END generated: repository-facts -->
211
193
 
@@ -214,4 +196,4 @@ Generated on every build; `check` refuses drift. Machine-readable: [.agent/facts
214
196
  Version tracks the **contract**, not content ([versioning](docs/VERSIONING.md)).
215
197
  Built by **HLIntel LLC**, public on purpose ([about](ABOUT.md)). Contributions pass `headron verify`. [MIT License](LICENSE).
216
198
 
217
- Updated: contract v3.62.0
199
+ Updated: contract v3.63.0
headron_software-3.62.0/README.md DELETED
@@ -1,187 +0,0 @@
1
- <!-- AGENTS: do not read this page breadth-first. Plug in: `python scripts/atlas.py port <file>`,
2
- or parse .agent/bootstrap.json — one record back. -->
3
- <!-- mcp-name: io.github.HLIntel/headron -->
4
- <div align="center">
5
- <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.svg"
6
- alt="Headron Software: AI governance and verification"
7
- width="992">
8
- <h1>Headron Software</h1>
9
- </div>
10
-
11
- <!-- BEGIN generated: badges (python scripts/atlas.py index --write) -->
12
-
13
- **Contract 3.62.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
14
-
15
- <!-- END generated: badges -->
16
-
17
- <!-- BEGIN generated: headline (python scripts/atlas.py index --write) -->
18
-
19
- **Protocol:** a change maps to proof; Headron selects evidence and the build enforces the verdict ([evidence](#what-it-measurably-buys)). Agents: [llms.txt](llms.txt); chats: [CHAT.md](CHAT.md).
20
-
21
- <!-- END generated: headline -->
22
-
23
- ## Why this exists
24
-
25
- An agent can report a change as done without running a single check. A check that never ran looks
26
- the same as a check that passed. Headron Software closes that gap:
27
-
28
- - **Every change maps to proof.** [`atlas.yaml`](atlas.yaml) lists the checks each kind of file owes,
29
- and the gate runs them before the change is called finished.
30
- - **Refusal happens at commit, for any agent.** A git hook runs the same check-only command whether
31
- an autonomous agent, an IDE extension, a chat assistant, or a developer made the commit.
32
- - **A skipped check is never a pass.** A missing tool is reported as `SKIP` and kept out
33
- of the pass count. Gates report `PASS`, `FAIL` or `NOT RUN`.
34
-
35
- ## How it works
36
-
37
- **System 1:** `headron port <file>` routes task context. **System 2:** [`atlas.yaml`](atlas.yaml)
38
- maps changes to gates; hooks and CI emit `PASS`, `FAIL`, `SKIP`, or `NOT RUN`. The
39
- hosted [Mind API](https://headron.tech/mind-api.html) plans a declared change; `headron mind`
40
- adds **classify → route → receipts**.
41
-
42
- <!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
43
-
44
- <p align="center">
45
- <img src="docs/media/headron-proof-flow.svg" width="900"
46
- alt="Headron Architecture: contract, targeted evidence, integrity audit, unified verdict.">
47
- </p>
48
-
49
- <!-- END generated: proof-flow -->
50
-
51
- <!-- BEGIN generated: gate-example (python scripts/atlas.py index --write) -->
52
-
53
- ```console
54
- $ headron gate scripts/doctor.py
55
- 1. formatter: ruff format --check scripts/doctor.py
56
- 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
57
- 3. unit_tests: pytest
58
- ```
59
-
60
- <!-- END generated: gate-example -->
61
-
62
- ## Quickstart
63
-
64
- <!-- BEGIN generated: install (python scripts/atlas.py index --write) -->
65
-
66
- ```bash
67
- # install
68
- uv tool install headron-software && headron doctor
69
- # editable, to change Headron itself
70
- git clone --depth 1 --branch v3.62.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
71
- ```
72
-
73
- <!-- END generated: install -->
74
-
75
- In your repository:
76
-
77
- ```bash
78
- cd path/to/your-repo && headron init # checks, universal multi-agent wiring, first run
79
- headron verify && headron report # after a change: verdicts, then what is unverified
80
- ```
81
-
82
- With an impact map, `headron verify --changed` evaluates modified files in seconds.
83
- 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.
84
-
85
- **Machines:** [bootstrap](.agent/bootstrap.json), [facts](.agent/facts.json), and [JSON schema](tools/atlas-output.schema.json).
86
- **Agents:** [entry](llms.txt), [adapters](models/README.md); the MCP interface is read-only.
87
- **Chats:** [no-shell setup](CHAT.md). For another repository, see [CONSUMING](docs/CONSUMING.md).
88
-
89
- ## What it measurably buys
90
-
91
- See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove) for their scope.
92
-
93
- <!-- BEGIN generated: measured-benefits (python scripts/atlas.py index --write) -->
94
-
95
- <!-- prettier-ignore -->
96
- | Instrument | Recorded result |
97
- | :--- | :--- |
98
- | Enforcement | 31/31 breaks refused across 20 toolchains; **754** declared planted cases |
99
- | Failure ledger | 122 shapes, 209 sightings; 99 in-tree guarded, 23 host-only |
100
- | Field ledger | 856 verifications (127 clean); 1133 refusals; 329 landings; 711 lessons; 392 sessions |
101
- | Verification outcomes | 15,206 checks: 6,148 PASS, 1,095 REUSED, 850 FAIL, 7,113 NOT RUN. 464 runs failed; 265 held on an unrun check; 0 clean with a gap |
102
- | Routing experiment | 89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models |
103
- | Language roles | 360 pairs: 110 runnable, 0 undeclared |
104
-
105
- Entry context: ~1,734 tokens. The 200 documents (649 KiB) load on demand; install: 10 KiB, 8 dependencies.
106
- [Field records](benchmarks/field-latest.json). [Routing data](benchmarks/ab-latest.json). Measures can overlap.
107
-
108
- <!-- END generated: measured-benefits -->
109
-
110
- ## Where it fits
111
-
112
- - **Any agent or runtime.** One sovereign contract across all agent architectures (Google Antigravity,
113
- Claude Code, Cursor, OpenAI Codex, OpenHands, Windsurf, Hermes, or bare CLI). The adapters in
114
- [models/README.md](models/README.md) keep native tools intact while enforcing identical deterministic boundaries.
115
- - **Any repository.** `headron init` wires a repository in one step. Consumers add the reusable CI
116
- workflow from [CONSUMING](docs/CONSUMING.md) so the verdict on a laptop and in CI is the same command.
117
- - **Any language we route.** Each language × check pair is either answered by a command or declared
118
- as having no tool, so an unanswered pair cannot hide.
119
-
120
- ## Agent contract
121
-
122
- <!-- BEGIN generated: port-example (python scripts/atlas.py index --write) -->
123
-
124
- ```console
125
- $ headron port scripts/doctor.py --line
126
- ◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠1 │ → headron gate scripts/doctor.py
127
- $ headron port scripts --line
128
- ◎ scripts │ ⠟171 │ ⌂scripts │ → headron brainstorm
129
- $ headron port . --line
130
- ○ . │ ⠟199 ⠁4 ⠿4 │ → headron check
131
- ```
132
-
133
- <!-- END generated: port-example -->
134
-
135
- - **Discover:** `headron find <query>` searches paths, symbols and vocabulary with pointers; `headron sweep` maps topology. Search does not guarantee semantic recall.
136
- - **Route:** `headron port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only its names.
137
- - **Processes:** `headron process --json` lists workflows; `headron process <id> --json` gives steps and gates. These are references, not an executor.
138
- - **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` retrieves audit trails.
139
- - **Automate:** add `--json`; records follow [the output schema](tools/atlas-output.schema.json).
140
- - **Before shell:** `headron shell --json "<cmd>"`; exit 3 means its verdict would be misread.
141
- - **Land:** `python scripts/branchstate.py --land`; check `headron landed <branch>` before deletion.
142
- - **Judge and report:** use the [judgment rungs](docs/systems/AGENT-HARNESS.md#judgment-rungs); file breaks with the [`headron` skill](skills/headron/SKILL.md).
143
-
144
- ## Find your way
145
-
146
- - **Every document:** [docs index](docs/INDEX.md) · [wiki](docs/wiki/README.md)
147
- - **Languages:** [atlas](languages/ATLAS.md) · [routing](docs/wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
148
- - **Agents:** [harness](docs/systems/AGENT-HARNESS.md) · [`.headron`](docs/HEADRON-LANGUAGE.md) · [runtimes](models/README.md)
149
- - **Why a rule:** `headron why` · `headron failures` · [instruments](docs/INSTRUMENTS.md)
150
- - **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md) · [contributing](CONTRIBUTING.md)
151
-
152
- ## Enterprise and companion runtimes
153
-
154
- Headron Software is the core product of HLIntel (Headron Layer Intelligence):
155
-
156
- - **HeadronOS:** desktop workspace and local runtime.
157
- - **Headron Web:** browser interface.
158
- - **Headron Enterprise:** organizational offering across desktop and web.
159
- - **Headron MCP:** integration connecting agents and developer tools.
160
- - **HL.Verify:** shared verification capability.
161
- - _Rules & Gates:_ File-targeted proof obligations and pre-commit enforcers.
162
- - _Failure Ledger:_ Past agent failure catalog and regression seeds.
163
- - **Mind API:** shared orchestration interface.
164
-
165
- [Companion details](docs/CONSUMING.md#optional-hlintel-services).
166
-
167
- ## Counts, computed
168
-
169
- Generated on every build; `check` refuses drift. Machine-readable: [.agent/facts.json](.agent/facts.json).
170
-
171
- <!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
172
-
173
- - **49** hard invariants — enforced on every change, zero unowned
174
- - **354** agreement edges — each a file tied to the declaration it answers for
175
- - **94** instruments — each stating what it proves, what it does not, and what closes the gap
176
- - **385** tool entries — across 40 manifests and 5 kinds, validated against `tools/tools.schema.json`
177
- - **169** harness Python files — every one held by `lint` · `format` · `typecheck`
178
- - **3.62.0** contract version — `VERSION`, asserted in 10 other files
179
-
180
- <!-- END generated: repository-facts -->
181
-
182
- ## Project
183
-
184
- Version tracks the **contract**, not content ([versioning](docs/VERSIONING.md)).
185
- Built by **HLIntel LLC**, public on purpose ([about](ABOUT.md)). Contributions pass `headron verify`. [MIT License](LICENSE).
186
-
187
- Updated: contract v3.62.0
headron_software-3.62.0/VERSION DELETED
@@ -1 +0,0 @@
1
- 3.62.0