headron-software 3.60.1__py3-none-any.whl
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.
- atlas_cli.py +240 -0
- headron_software-3.60.1.dist-info/METADATA +224 -0
- headron_software-3.60.1.dist-info/RECORD +7 -0
- headron_software-3.60.1.dist-info/WHEEL +5 -0
- headron_software-3.60.1.dist-info/entry_points.txt +4 -0
- headron_software-3.60.1.dist-info/licenses/LICENSE +21 -0
- headron_software-3.60.1.dist-info/top_level.txt +1 -0
atlas_cli.py
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Resolve WHICH atlas, then run the contract's CLI against it.
|
|
3
|
+
|
|
4
|
+
A SEPARATE MODULE (2.11.0) because `atlascore` fixes the root at IMPORT time: this resolves it first,
|
|
5
|
+
exports it, then imports the harness. IT PRINTS THE RULE THAT DECIDED THE ROOT: a flag and a lucky
|
|
6
|
+
fall-through give one answer, trusted unequally. A CONSUMER PINS A REF, NEVER
|
|
7
|
+
`main`, in `.atlas.yaml`: its own diff reviews the pin.
|
|
8
|
+
WITH NO ROOT AND NO CHECKOUT (3.53.0) it fetches its own version's release, sha256-checked; else refuses.
|
|
9
|
+
THAT TREE IS LOCKED (3.54.0): read-only, re-hashed on every run; an edit refuses.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import hashlib
|
|
15
|
+
import io
|
|
16
|
+
import os
|
|
17
|
+
import re
|
|
18
|
+
import shutil
|
|
19
|
+
import sys
|
|
20
|
+
import tarfile
|
|
21
|
+
import tempfile
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
|
|
24
|
+
import yaml
|
|
25
|
+
|
|
26
|
+
CONSUMER_CONFIG = ".atlas.yaml"
|
|
27
|
+
FLAG = "--atlas-root"
|
|
28
|
+
RELEASES = "https://github.com/HLIntel/Headron/releases/download"
|
|
29
|
+
INSTALLED_FROM = "the checkout this entry point was installed from"
|
|
30
|
+
MARKER = ".headron-release.sha256" # written last: an unmarked cache is never used
|
|
31
|
+
# REFUSE RATHER THAN INVENT (3.47.0): a key not known by name is refused at its file:line.
|
|
32
|
+
SECTIONS, PIN = ("atlas", "stack_tiers", "markdown_policy"), ("ref", "root", "task", "change_class", "process")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class ConfigError(ValueError):
|
|
36
|
+
"""A root flag or consumer config this entry point refuses to guess about."""
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _keys(path: Path, node, what: str, allowed=()) -> dict:
|
|
40
|
+
if not isinstance(node, yaml.MappingNode):
|
|
41
|
+
raise ConfigError(f"{path}:{node.start_mark.line + 1}: {what} must be a mapping")
|
|
42
|
+
out = {}
|
|
43
|
+
for key, value in node.value:
|
|
44
|
+
name, line = key.value, key.start_mark.line + 1
|
|
45
|
+
if not isinstance(name, str) or name in out or allowed and name not in allowed:
|
|
46
|
+
raise ConfigError(f"{path}:{line}: bad or repeated key {name!r} in {what}; allowed: {allowed}")
|
|
47
|
+
out[name] = value
|
|
48
|
+
return out
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _pin(path: Path) -> dict[str, str]:
|
|
52
|
+
"""The `atlas:` mapping of one config file, every key checked by name."""
|
|
53
|
+
try:
|
|
54
|
+
doc = yaml.compose(path.read_text(encoding="utf-8"))
|
|
55
|
+
except yaml.YAMLError as exc:
|
|
56
|
+
mark = getattr(exc, "problem_mark", None)
|
|
57
|
+
raise ConfigError(f"{path}:{mark.line + 1 if mark else 1}: not parseable YAML") from None
|
|
58
|
+
sections = _keys(path, doc, CONSUMER_CONFIG, SECTIONS) if doc else {}
|
|
59
|
+
pins = {name: _keys(path, node, name) for name, node in sections.items()}.get("atlas", {})
|
|
60
|
+
for name, value in pins.items():
|
|
61
|
+
if name not in PIN or value.tag != "tag:yaml.org,2002:str" or not value.value.strip():
|
|
62
|
+
raise ConfigError(f"{path}:{value.start_mark.line + 1}: atlas.{name}: want a string in {PIN}")
|
|
63
|
+
return {name: value.value for name, value in pins.items()}
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _config(start: Path) -> tuple[dict, Path | None]:
|
|
67
|
+
"""The pin of the nearest .atlas.yaml at or above `start`; ConfigError on any doubt."""
|
|
68
|
+
for path in (d / CONSUMER_CONFIG for d in [start, *start.parents]):
|
|
69
|
+
if path.exists():
|
|
70
|
+
return _pin(path), path
|
|
71
|
+
return {}, None
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def root_flag(argv: list[str]) -> tuple[str | None, int, int]:
|
|
75
|
+
"""(value, index, width) of the root flag, or (None, -1, 0); refused with no value (3.47.0)."""
|
|
76
|
+
hits = [i for i, arg in enumerate(argv) if arg == FLAG or arg.startswith(FLAG + "=")]
|
|
77
|
+
if not hits:
|
|
78
|
+
return None, -1, 0
|
|
79
|
+
i, eq = hits[0], argv[hits[0]] != FLAG
|
|
80
|
+
value = argv[i].partition("=")[2] if eq else (argv[i + 1 :] or [""])[0]
|
|
81
|
+
if len(hits) > 1 or not value.strip() or value.startswith("-") and not eq:
|
|
82
|
+
raise ConfigError(f"{FLAG} needs one directory, given once; got {value!r}")
|
|
83
|
+
return value, i, 1 if eq else 2
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
CALLER_ENV = dict(os.environ)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def resolve_root(argv: list[str], cwd: Path) -> tuple[Path, str]:
|
|
90
|
+
"""The atlas this invocation runs against, and the rule that decided it. In declared order."""
|
|
91
|
+
value = root_flag(argv)[0]
|
|
92
|
+
if value is not None:
|
|
93
|
+
return Path(value).expanduser().resolve(), f"explicit {FLAG}"
|
|
94
|
+
for var in ("HEADRON_ROOT", "CODE_DEVELOPMENT_ROOT"): # the second is the pre-3.0 name
|
|
95
|
+
if os.environ.get(var):
|
|
96
|
+
return Path(os.environ[var]).resolve(), f"{var} in the environment"
|
|
97
|
+
config, where = _config(cwd)
|
|
98
|
+
if where and config.get("root"):
|
|
99
|
+
base = (where.parent / config["root"]).resolve()
|
|
100
|
+
return base, f"root declared in {where.name} (ref {config.get('ref', 'unpinned')})"
|
|
101
|
+
return Path(__file__).resolve().parents[1], INSTALLED_FROM
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
class FetchError(RuntimeError):
|
|
105
|
+
"""A release atlas refused: unreachable, unverified, or another version."""
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _get(url: str) -> bytes:
|
|
109
|
+
import urllib.request # noqa: PLC0415
|
|
110
|
+
|
|
111
|
+
try:
|
|
112
|
+
with urllib.request.urlopen(url, timeout=60) as r: # noqa: S310 — a fixed https base
|
|
113
|
+
return r.read()
|
|
114
|
+
except (OSError, ValueError) as exc:
|
|
115
|
+
raise FetchError(f"cannot download {url}: {exc}") from None
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def _manifest(tree: Path) -> list[str]:
|
|
119
|
+
"""`sha256sum` lines for every file under `tree` but the marker: `sha256sum -c` re-checks it by hand."""
|
|
120
|
+
files = sorted(p for p in tree.rglob("*") if p.is_file() and p.name != MARKER)
|
|
121
|
+
return [f"{hashlib.sha256(p.read_bytes()).hexdigest()} {p.relative_to(tree).as_posix()}" for p in files]
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
KEPT_RELEASES = 3 # a pruned release re-fetches
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def _prune_releases(cache: Path) -> None:
|
|
128
|
+
for mark in sorted(cache.glob(f"atlas-*/{MARKER}"), key=os.path.getmtime)[:-KEPT_RELEASES]:
|
|
129
|
+
shutil.rmtree(mark.parent, ignore_errors=True)
|
|
130
|
+
shutil.rmtree(cache / "pycache", ignore_errors=True) # bytecode: rebuilt on import
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def release_cache() -> Path:
|
|
134
|
+
return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache", "headron")
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def fetch_atlas(version: str) -> Path:
|
|
138
|
+
"""Release v<version>'s tree, cached or downloaded and sha256-checked; else FetchError."""
|
|
139
|
+
dest = release_cache() / f"atlas-{version}"
|
|
140
|
+
if (dest / MARKER).is_file():
|
|
141
|
+
changed = set((dest / MARKER).read_text().splitlines()[1:]) ^ set(_manifest(dest))
|
|
142
|
+
if changed:
|
|
143
|
+
path = min(changed).partition(" ")[2]
|
|
144
|
+
raise FetchError(f"{dest}: {path} changed after download; remove {dest} to fetch v{version} again")
|
|
145
|
+
return dest
|
|
146
|
+
name = f"headron-v{version}.tar.gz"
|
|
147
|
+
url = f"{RELEASES}/v{version}/{name}"
|
|
148
|
+
want = re.findall(
|
|
149
|
+
rf"^([0-9a-f]{{64}}) [ *]{re.escape(name)}$", _get(url + ".sha256").decode(errors="replace"), re.M
|
|
150
|
+
)
|
|
151
|
+
blob = _get(url)
|
|
152
|
+
if len(want) != 1 or hashlib.sha256(blob).hexdigest() != want[0]:
|
|
153
|
+
raise FetchError(f"{name}: sha256 is not its release's one digest {want}")
|
|
154
|
+
dest.parent.mkdir(parents=True, exist_ok=True)
|
|
155
|
+
work = Path(tempfile.mkdtemp(dir=dest.parent))
|
|
156
|
+
try:
|
|
157
|
+
with tarfile.open(fileobj=io.BytesIO(blob)) as tar:
|
|
158
|
+
tops = {m.name.split("/")[0] for m in tar}
|
|
159
|
+
tar.extractall(work, filter="data") # refuses absolute, climbing and escaping links
|
|
160
|
+
tree = work / tops.pop()
|
|
161
|
+
if tops or (tree / "VERSION").read_text().strip() != version:
|
|
162
|
+
raise FetchError(f"{name} is not one tree of contract {version}")
|
|
163
|
+
(tree / MARKER).write_text("".join(f"{line}\n" for line in [f"{want[0]} {name}", *_manifest(tree)]))
|
|
164
|
+
for path in tree.rglob("*"):
|
|
165
|
+
if path.is_file():
|
|
166
|
+
path.chmod(path.stat().st_mode & ~0o222) # read-only, marker too: an edit fails where it is made
|
|
167
|
+
shutil.rmtree(dest, ignore_errors=True) # an unmarked, interrupted unpack
|
|
168
|
+
os.replace(tree, dest)
|
|
169
|
+
_prune_releases(dest.parent)
|
|
170
|
+
except (tarfile.TarError, OSError, TypeError) as exc: # TypeError: no data filter before 3.11.4
|
|
171
|
+
raise FetchError(f"{name} could not be unpacked: {exc}") from None
|
|
172
|
+
finally:
|
|
173
|
+
shutil.rmtree(work, ignore_errors=True)
|
|
174
|
+
return dest
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def _resolved(argv: list[str]) -> tuple:
|
|
178
|
+
try:
|
|
179
|
+
root, rule = resolve_root(argv, Path.cwd())
|
|
180
|
+
if rule != INSTALLED_FROM or (root / "atlas.yaml").exists():
|
|
181
|
+
return root, rule
|
|
182
|
+
if os.environ.get("HEADRON_NO_FETCH") == "1":
|
|
183
|
+
return root, rule + "; HEADRON_NO_FETCH=1"
|
|
184
|
+
from importlib.metadata import version # noqa: PLC0415
|
|
185
|
+
|
|
186
|
+
root = fetch_atlas(version("headron-software"))
|
|
187
|
+
# Bytecode goes beside the locked tree, never into it, here and in every child process.
|
|
188
|
+
os.environ["PYTHONPYCACHEPREFIX"] = sys.pycache_prefix = str(root.parent / "pycache")
|
|
189
|
+
return root, "its own release, sha256-checked and locked"
|
|
190
|
+
except (ConfigError, FetchError, ImportError) as exc:
|
|
191
|
+
print(f"refused: {exc}", file=sys.stderr)
|
|
192
|
+
return None, None
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def _enter(argv: list[str], script: str) -> tuple:
|
|
196
|
+
"""Resolve, export, put scripts/ first on the path; (None, None) if refused."""
|
|
197
|
+
root, rule = _resolved(argv)
|
|
198
|
+
if root is None:
|
|
199
|
+
return None, None
|
|
200
|
+
# THE HARNESS COMES FROM THE ATLAS, NEVER THE WHEEL (3.7.0): a bundled copy is a second implementation.
|
|
201
|
+
if not (root / "atlas.yaml").exists() or not (root / "scripts" / script).exists():
|
|
202
|
+
hint = f"point at a checkout with {FLAG}, HEADRON_ROOT, or `atlas: root:` in {CONSUMER_CONFIG}"
|
|
203
|
+
print(f"no atlas with scripts/{script} at {root} (resolved by: {rule})\n{hint}", file=sys.stderr)
|
|
204
|
+
return None, None
|
|
205
|
+
os.environ["HEADRON_ROOT"] = os.environ["CODE_DEVELOPMENT_ROOT"] = str(root)
|
|
206
|
+
sys.path.insert(0, str(root / "scripts"))
|
|
207
|
+
return root, rule
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def main(argv: list[str] | None = None) -> int:
|
|
211
|
+
argv = list(sys.argv[1:] if argv is None else argv)
|
|
212
|
+
root, rule = _enter(argv, "atlas.py")
|
|
213
|
+
if root is None:
|
|
214
|
+
return 2
|
|
215
|
+
_, index, width = root_flag(argv)
|
|
216
|
+
del argv[index : index + width]
|
|
217
|
+
if "--where" in argv:
|
|
218
|
+
print(f"atlas root: {root}\nresolved by: {rule}")
|
|
219
|
+
# an agent handed only an install still finds where to start
|
|
220
|
+
print(f"agent entry: {root / '.agent' / 'bootstrap.json'} (then: headron gate <file>)")
|
|
221
|
+
return 0
|
|
222
|
+
import atlas # noqa: PLC0415 — deliberate: the root must be exported before this import
|
|
223
|
+
|
|
224
|
+
return atlas.main(argv or ["check"])
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def mcp_main() -> int:
|
|
228
|
+
"""`headron-mcp`: the same root resolution, then serve the resolved atlas's MCP route on stdio."""
|
|
229
|
+
argv = sys.argv[1:]
|
|
230
|
+
if "--where" in argv:
|
|
231
|
+
return main(argv)
|
|
232
|
+
if _enter(argv, "headron_mcp.py")[0] is None:
|
|
233
|
+
return 2
|
|
234
|
+
import headron_mcp # noqa: PLC0415 — as in main
|
|
235
|
+
|
|
236
|
+
return headron_mcp.serve()
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
if __name__ == "__main__":
|
|
240
|
+
sys.exit(main())
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: headron-software
|
|
3
|
+
Version: 3.60.1
|
|
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.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/HLIntel/Headron
|
|
7
|
+
Project-URL: Documentation, https://github.com/HLIntel/Headron/blob/main/llms.txt
|
|
8
|
+
Project-URL: Issues, https://github.com/HLIntel/Headron/issues
|
|
9
|
+
Project-URL: Source, https://github.com/HLIntel/Headron
|
|
10
|
+
Project-URL: Agent entry, https://raw.githubusercontent.com/HLIntel/Headron/main/.agent/bootstrap.json
|
|
11
|
+
Project-URL: LLM instructions, https://raw.githubusercontent.com/HLIntel/Headron/main/llms.txt
|
|
12
|
+
Project-URL: Changelog, https://github.com/HLIntel/Headron/blob/main/docs/VERSIONING.md
|
|
13
|
+
Keywords: headron,headron-software,headron-layer-intelligence,hlintel,engineering-atlas,polyglot,contract-verification,policy-as-code,ai-agents,ai-coding-agents,mcp,llm,agent-harness,code-verification,developer-tools,static-analysis,supply-chain-security,claude-code,codex,github-copilot,agents-md
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
18
|
+
Classifier: Topic :: Software Development :: Testing
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: pyyaml<7,>=6.0.3
|
|
24
|
+
Requires-Dist: defusedxml<0.8,>=0.7.1
|
|
25
|
+
Provides-Extra: quality
|
|
26
|
+
Requires-Dist: ruff>=0.6; extra == "quality"
|
|
27
|
+
Provides-Extra: crosscheck
|
|
28
|
+
Requires-Dist: jsonschema>=4; extra == "crosscheck"
|
|
29
|
+
Dynamic: license-file
|
|
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. -->
|
|
33
|
+
<!-- mcp-name: io.github.HLIntel/headron -->
|
|
34
|
+
<div align="center">
|
|
35
|
+
<h1>Headron Software</h1>
|
|
36
|
+
<img src="docs/media/headron-banner.png"
|
|
37
|
+
alt="Headron Software Development AI Agents."
|
|
38
|
+
width="992">
|
|
39
|
+
</div>
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<a href="https://github.com/HLIntel/Headron/actions/workflows/atlas-ci.yml"><img
|
|
43
|
+
src="https://github.com/HLIntel/Headron/actions/workflows/atlas-ci.yml/badge.svg?branch=main"
|
|
44
|
+
alt="Atlas CI"></a>
|
|
45
|
+
<a href="https://github.com/HLIntel/Headron/releases/latest"><img
|
|
46
|
+
src="https://img.shields.io/github/v/tag/HLIntel/Headron?label=contract"
|
|
47
|
+
alt="contract version"></a>
|
|
48
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/HLIntel/Headron"><img
|
|
49
|
+
src="https://api.securityscorecards.dev/projects/github.com/HLIntel/Headron/badge"
|
|
50
|
+
alt="OpenSSF Scorecard"></a>
|
|
51
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
|
|
52
|
+
</p>
|
|
53
|
+
|
|
54
|
+
<!-- BEGIN generated: headline (python scripts/atlas.py index --write) -->
|
|
55
|
+
|
|
56
|
+
**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).
|
|
57
|
+
|
|
58
|
+
<!-- END generated: headline -->
|
|
59
|
+
|
|
60
|
+
**Start:** [install/use](#quickstart) · [architecture](#where-it-fits) · [enterprise](#enterprise-and-companion-runtimes) · [agents](llms.txt) · [chat](CHAT.md) · [adapters](models/README.md)
|
|
61
|
+
|
|
62
|
+
## Why this exists
|
|
63
|
+
|
|
64
|
+
An agent can report a change as done without running a single check. A check that never ran looks
|
|
65
|
+
the same as a check that passed. Headron Software closes that gap:
|
|
66
|
+
|
|
67
|
+
- **Every change maps to proof.** [`atlas.yaml`](atlas.yaml) lists the checks each kind of file owes,
|
|
68
|
+
and the gate runs them before the change is called finished.
|
|
69
|
+
- **Refusal happens at commit, for any agent.** A git hook runs the same check-only command whether
|
|
70
|
+
an autonomous agent, an IDE extension, a chat assistant, or a developer made the commit.
|
|
71
|
+
- **A skipped check is never a pass.** A missing tool is reported as `SKIP` and kept out
|
|
72
|
+
of the pass count. Gates report `PASS`, `FAIL` or `NOT RUN`.
|
|
73
|
+
|
|
74
|
+
<!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
|
|
75
|
+
|
|
76
|
+
<p align="center">
|
|
77
|
+
<img src="docs/media/headron-proof-flow.svg" width="900"
|
|
78
|
+
alt="Headron Architecture: contract, targeted evidence, integrity audit, unified verdict.">
|
|
79
|
+
</p>
|
|
80
|
+
|
|
81
|
+
<!-- END generated: proof-flow -->
|
|
82
|
+
|
|
83
|
+
<!-- BEGIN generated: gate-example (python scripts/atlas.py index --write) -->
|
|
84
|
+
|
|
85
|
+
```console
|
|
86
|
+
$ headron gate scripts/doctor.py
|
|
87
|
+
1. formatter: ruff format --check scripts/doctor.py
|
|
88
|
+
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
|
|
89
|
+
3. unit_tests: pytest
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
<!-- END generated: gate-example -->
|
|
93
|
+
|
|
94
|
+
## Quickstart
|
|
95
|
+
|
|
96
|
+
<!-- BEGIN generated: install (python scripts/atlas.py index --write) -->
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
# editable
|
|
100
|
+
git clone --depth 1 --branch v3.60.1 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
<!-- END generated: install -->
|
|
104
|
+
|
|
105
|
+
In your repository:
|
|
106
|
+
|
|
107
|
+
```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
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
With an impact map, `headron verify --changed` runs planted groups with moved dependencies or no record.
|
|
113
|
+
It speeds feedback; `headron verify` remains the final verdict.
|
|
114
|
+
|
|
115
|
+
Agents reach Headron Software through Headron MCP; the current `headron-mcp` command is read-only.
|
|
116
|
+
Enterprise execution gates and host approval hooks live in the companion runtime (HeadronOS).
|
|
117
|
+
No-shell chat: [CHAT.md](CHAT.md). Add Headron Software to another repository:
|
|
118
|
+
[CONSUMING](docs/CONSUMING.md).
|
|
119
|
+
|
|
120
|
+
## Where it fits
|
|
121
|
+
|
|
122
|
+
- **Any agent or runtime.** One sovereign contract across all agent architectures (Google Antigravity,
|
|
123
|
+
Claude Code, Cursor, OpenAI Codex, OpenHands, Windsurf, Hermes, or bare CLI). The adapters in
|
|
124
|
+
[models/README.md](models/README.md) keep native tools intact while enforcing identical deterministic boundaries.
|
|
125
|
+
- **Any repository.** `headron init` wires a repository in one step. Consumers add the reusable CI
|
|
126
|
+
workflow from [CONSUMING](docs/CONSUMING.md) so the verdict on a laptop and in CI is the same command.
|
|
127
|
+
- **Any language we route.** Each language × check pair is either answered by a command or declared
|
|
128
|
+
as having no tool, so an unanswered pair cannot hide.
|
|
129
|
+
|
|
130
|
+
## Enterprise and companion runtimes
|
|
131
|
+
|
|
132
|
+
Headron Software is the core product of HLIntel (Headron Layer Intelligence):
|
|
133
|
+
|
|
134
|
+
- **HeadronOS:** desktop workspace and local runtime.
|
|
135
|
+
- **Headron Web:** browser interface.
|
|
136
|
+
- **Headron Enterprise:** organizational offering across desktop and web.
|
|
137
|
+
- **Headron MCP:** integration connecting agents and developer tools.
|
|
138
|
+
- **HL.Verify:** shared verification capability.
|
|
139
|
+
- *Rules & Gates:* File-targeted proof obligations and pre-commit enforcers.
|
|
140
|
+
- *Failure Ledger:* Past agent failure catalog and regression seeds.
|
|
141
|
+
- **Mind API:** shared orchestration interface.
|
|
142
|
+
|
|
143
|
+
[Companion details](docs/CONSUMING.md#optional-hlintel-services). Product integration remains unproven.
|
|
144
|
+
|
|
145
|
+
<!-- BEGIN generated: port-example (python scripts/atlas.py index --write) -->
|
|
146
|
+
|
|
147
|
+
```console
|
|
148
|
+
$ headron port scripts/doctor.py --line
|
|
149
|
+
◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓3 │ ⚠1 │ → headron gate scripts/doctor.py
|
|
150
|
+
$ headron port scripts --line
|
|
151
|
+
◎ scripts │ ⠟158 │ ⌂scripts │ → headron brainstorm
|
|
152
|
+
$ headron port . --line
|
|
153
|
+
○ . │ ⠟187 ⠁4 ⠿4 │ → headron check
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
<!-- END generated: port-example -->
|
|
157
|
+
|
|
158
|
+
## What it measurably buys
|
|
159
|
+
|
|
160
|
+
What the recorded instruments have caught in real runs. They prove routing and refusals, not end-to-end task success
|
|
161
|
+
([limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove)).
|
|
162
|
+
|
|
163
|
+
<!-- BEGIN generated: measured-benefits (python scripts/atlas.py index --write) -->
|
|
164
|
+
|
|
165
|
+
**Failures caught**
|
|
166
|
+
|
|
167
|
+
- **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).
|
|
168
|
+
- **694** mistake kinds planted in the tests, each refused.
|
|
169
|
+
- **122** failure shapes recorded from real runs: 209 sightings, 47 recurred, 99 now guarded, 23 host-only (3 of them recurred).
|
|
170
|
+
- **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).
|
|
171
|
+
- **24/24** solo commits clean with or without the hook; a planted broken commit is refused.
|
|
172
|
+
- **6** agent controls block, never warn: narrow_tools, sandbox, budget, approval, effects, audit.
|
|
173
|
+
|
|
174
|
+
**Cost**
|
|
175
|
+
|
|
176
|
+
- **1,729** tokens read before routing; 196 more documents (668 KiB) load only when a route names one.
|
|
177
|
+
- **89%** fewer tokens than pasting every tool list; 50% fewer than blind.
|
|
178
|
+
- **10 KiB** install: 1 module, 2 dependency — 8 in total with its own dependencies.
|
|
179
|
+
|
|
180
|
+
**Coverage**
|
|
181
|
+
|
|
182
|
+
- **360** language × check pairs (40 × 9), all answered: 144 by a command, 216 by a declared _no tool_, 0 silent.
|
|
183
|
+
|
|
184
|
+
<!-- END generated: measured-benefits -->
|
|
185
|
+
|
|
186
|
+
## Agent contract
|
|
187
|
+
|
|
188
|
+
- **Discover:** `headron find <query>` for instant search (symbols, prefix, acronym, pointers); `headron sweep` for tier and shard topology.
|
|
189
|
+
- **Route:** `headron port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only its names.
|
|
190
|
+
- **Orchestrate:** `headron mind --route <file>` for System 1 reflex vs System 2 deliberate execution; `headron mind --receipts` for verified audit trails.
|
|
191
|
+
- **Automate:** add `--json`; records follow [the output schema](tools/atlas-output.schema.json).
|
|
192
|
+
- **Before shell:** `headron shell --json "<cmd>"`; exit 3 means its verdict would be misread.
|
|
193
|
+
- **Land:** `python scripts/branchstate.py --land`; check `headron landed <branch>` before deletion.
|
|
194
|
+
- **Judge and report:** use the [judgment rungs](docs/systems/AGENT-HARNESS.md#judgment-rungs); file breaks with the [`headron` skill](skills/headron/SKILL.md).
|
|
195
|
+
|
|
196
|
+
## Counts, computed
|
|
197
|
+
|
|
198
|
+
Generated on every build; `check` refuses drift. Machine-readable: [.agent/facts.json](.agent/facts.json).
|
|
199
|
+
|
|
200
|
+
<!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
|
|
201
|
+
|
|
202
|
+
- **388** tool entries — across 40 manifests and 5 kinds, validated against `tools/tools.schema.json`
|
|
203
|
+
- **352** agreement edges — each a file tied to the declaration it answers for
|
|
204
|
+
- **94** instruments — each stating what it proves, what it does not, and what closes the gap
|
|
205
|
+
- **7** change classes — and 13 task profiles, in `atlas.yaml`
|
|
206
|
+
- **156** harness Python files — every one held by `lint` · `format` · `typecheck`
|
|
207
|
+
- **3.60.1** contract version — `VERSION`, asserted in 8 other files
|
|
208
|
+
|
|
209
|
+
<!-- END generated: repository-facts -->
|
|
210
|
+
|
|
211
|
+
## Find your way
|
|
212
|
+
|
|
213
|
+
- **Every document:** [docs index](docs/INDEX.md) · [wiki](docs/wiki/README.md)
|
|
214
|
+
- **Languages:** [atlas](languages/ATLAS.md) · [routing](docs/wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
|
|
215
|
+
- **Agents:** [harness](docs/systems/AGENT-HARNESS.md) · [`.headron`](docs/HEADRON-LANGUAGE.md) · [runtimes](models/README.md)
|
|
216
|
+
- **Why a rule:** `headron why` · `headron failures` · [instruments](docs/INSTRUMENTS.md)
|
|
217
|
+
- **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md) · [contributing](CONTRIBUTING.md)
|
|
218
|
+
|
|
219
|
+
## Project
|
|
220
|
+
|
|
221
|
+
Version tracks the **contract**, not content ([versioning](docs/VERSIONING.md)).
|
|
222
|
+
Built by **HLIntel LLC**, public on purpose ([about](ABOUT.md)). Contributions pass `headron verify`. [MIT License](LICENSE).
|
|
223
|
+
|
|
224
|
+
Updated: contract v3.60.1
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
atlas_cli.py,sha256=k5xIab4Wu48GiErOp_L-_8rlVLzh8gFrYAFZG24Ha4U,10518
|
|
2
|
+
headron_software-3.60.1.dist-info/licenses/LICENSE,sha256=k-Z5jRt4D0HfDG4warBoDzAKXvlsPmUVDftQNOP8lGQ,1068
|
|
3
|
+
headron_software-3.60.1.dist-info/METADATA,sha256=lxn8aY02Q933oPgZ7YYBlo513Is65QjNU0zaSa-VcxI,11484
|
|
4
|
+
headron_software-3.60.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
5
|
+
headron_software-3.60.1.dist-info/entry_points.txt,sha256=fj7hrio7RQPB-9vsCEE2Z_sQvrKEy81-BHAG1eEe7eI,99
|
|
6
|
+
headron_software-3.60.1.dist-info/top_level.txt,sha256=Bp6WGrJWR4VZKKynPsLldtAZknrfgG843JCdrumGazg,10
|
|
7
|
+
headron_software-3.60.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HLIntel LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
atlas_cli
|