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

headron_software-3.63.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: headron-software
+Version: 3.63.0
+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.
+License-Expression: MIT
+Project-URL: Homepage, https://headron.tech
+Project-URL: Documentation, https://github.com/HLIntel/Headron/blob/main/llms.txt
+Project-URL: Issues, https://github.com/HLIntel/Headron/issues
+Project-URL: Source, https://github.com/HLIntel/Headron
+Project-URL: Agent entry, https://raw.githubusercontent.com/HLIntel/Headron/main/.agent/bootstrap.json
+Project-URL: LLM instructions, https://raw.githubusercontent.com/HLIntel/Headron/main/llms.txt
+Project-URL: Changelog, https://github.com/HLIntel/Headron/blob/main/docs/VERSIONING.md
+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
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml<7,>=6.0.3
+Requires-Dist: defusedxml<0.8,>=0.7.1
+Provides-Extra: quality
+Requires-Dist: ruff>=0.6; extra == "quality"
+Provides-Extra: crosscheck
+Requires-Dist: jsonschema>=4; extra == "crosscheck"
+Dynamic: license-file
+
+<!-- AGENTS: do not read this page breadth-first. Run `headron port <file>` (in a clone,
+     `python scripts/atlas.py port <file>`), or parse .agent/bootstrap.json. -->
+<!-- mcp-name: io.github.HLIntel/headron -->
+<div align="center">
+  <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.jpg"
+       alt="Headron Software: AI governance and verification"
+       width="992">
+  <h1>Headron Software</h1>
+</div>
+
+<!-- BEGIN generated: badges (python scripts/atlas.py index --write) -->
+
+**Contract 3.63.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
+
+<!-- END generated: badges -->
+
+<!-- BEGIN generated: headline (python scripts/atlas.py index --write) -->
+
+- **Is:** a rule contract and CLI mapping changed files to checks. Hooks are optional; `headron verify` runs done gates.
+- **Is not:** a coding agent, model, test framework, or proof code is correct. A check that cannot run reports SKIP or NOT RUN, never a pass; the hook lets that commit through.
+- **`headron init` writes:** AGENTS.md, CLAUDE.md, .mcp.json, .codex/config.toml, .git/hooks/pre-commit. Use `--no-wiring` to skip hooks and configuration; `headron enforce uninstall` restores a displaced hook.
+- **Mind API:** hosted, paid, needs a key; plans a declared change. The command line works without it.
+
+Agents: [llms.txt](llms.txt). Chats: [CHAT.md](CHAT.md). [Evidence](#recorded-results).
+
+<!-- END generated: headline -->
+
+## Why this exists
+
+Headron connects changed files to declared checks and reports whether those checks ran. A skipped
+check is not a pass. An optional Git hook can run checks before a commit, whether the change came
+from a developer or an agent.
+
+## How it works
+
+`headron port <file>` tells an agent what a file owes before it edits. [`atlas.yaml`](atlas.yaml)
+holds those checks; the commit hook and CI report `PASS`, `FAIL`, `SKIP` or `NOT RUN`. The hosted
+[Mind API](https://headron.tech/mind-api.html) plans a declared change through `headron mind`.
+
+<!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
+
+<p align="center">
+  <img src="docs/media/headron-proof-flow.svg" width="900"
+       alt="Headron Architecture: contract, targeted evidence, integrity audit, unified verdict.">
+</p>
+
+<!-- END generated: proof-flow -->
+
+<!-- BEGIN generated: gate-example (python scripts/atlas.py index --write) -->
+
+```console
+$ 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
+```
+
+<!-- END generated: gate-example -->
+
+## Quickstart
+
+<!-- BEGIN generated: install (python scripts/atlas.py index --write) -->
+
+```bash
+# install
+uv tool install headron-software && headron doctor
+# editable, to change Headron itself
+git clone --depth 1 --branch v3.63.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
+```
+
+<!-- END generated: install -->
+
+In your repository:
+
+```bash
+cd path/to/your-repo && headron init   # finds your checks, wires your agents, installs the commit hook, runs once
+headron verify && headron proof <file> --verify   # after a change: verdicts, then a file's proof
+```
+
+With an impact map, `headron verify --changed` evaluates checks for modified files.
+Target a specific profile with `headron verify --changed --change <class>` (e.g. `source_change`, `api_change`, `security_sensitive`); `headron verify` remains the final full verdict.
+
+**Machines:** [bootstrap](.agent/bootstrap.json), [facts](.agent/facts.json), and [JSON schema](tools/atlas-output.schema.json).
+**Agents:** [adapters](models/README.md); the MCP interface is read-only.
+**Another repository:** [CONSUMING](docs/CONSUMING.md).
+
+## Recorded results
+
+See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove) for their scope.
+
+<!-- BEGIN generated: measured-benefits (python scripts/atlas.py index --write) -->
+
+<!-- prettier-ignore -->
+| Instrument | Recorded result |
+| :--- | :--- |
+| Enforcement | 31/31 breaks refused across 20 toolchains; **816** declared planted cases |
+| Failure ledger | 128 shapes, 220 sightings; 104 in-tree guarded, 24 host-only |
+| Field ledger | 940 verifications (136 clean); 1133 refusals; 394 landings; 711 lessons; 394 sessions |
+| 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 |
+| Routing experiment | 89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models |
+| Language roles | 360 pairs: 110 runnable, 0 undeclared |
+
+Entry context: ~1,593 tokens. The 211 documents (708 KiB) load on demand; install: 10 KiB; hash lock with test tools: 8 packages.
+[Field records](benchmarks/field-latest.json). [Routing data](benchmarks/ab-latest.json). Measures can overlap.
+
+<!-- END generated: measured-benefits -->
+
+## Where it fits
+
+- **Agents and runtimes:** [adapters](models/README.md) describe supported integrations.
+- **Headron-Harness:** a separate desktop dashboard and runtime; see [product boundaries](docs/PRODUCT-STRATEGY.md).
+- **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).
+- **Languages:** routes declare available checks and identify checks without a tool.
+
+## Agent contract
+
+<!-- BEGIN generated: port-example (python scripts/atlas.py index --write) -->
+
+```console
+$ headron port scripts/doctor.py --line
+◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠2 │ → headron gate scripts/doctor.py
+$ headron port scripts --line
+◎ scripts │ ⠟186 │ ⌂scripts │ → headron brainstorm
+$ headron port . --line
+○ . │ ⠟214 ⠿4 ⠁1 │ → headron check
+```
+
+<!-- END generated: port-example -->
+
+- **Discover:** `headron find <query>` searches paths, symbols and vocabulary; `headron sweep` maps topology. Search does not guarantee semantic recall.
+- **Route:** `headron port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only its names.
+- **Processes:** `headron process [<id>] --json` lists workflows; with an id, its steps and gates.
+- **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` summarizes the latest local verification record.
+- **Beliefs:** `headron revise` names what rests on a refuted claim; `headron propose` drafts each fix outside the tree.
+- **Automate:** add `--json`; records follow [the output schema](tools/atlas-output.schema.json).
+- **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](docs/systems/AGENT-HARNESS.md#judgment-rungs); file breaks with the [`headron` skill](skills/headron/SKILL.md).
+
+## Find your way
+
+- **Every document:** [docs index](docs/INDEX.md) · [wiki](docs/wiki/README.md)
+- **Languages:** [atlas](languages/ATLAS.md) · [routing](docs/wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
+- **Agents:** [harness](docs/systems/AGENT-HARNESS.md) · [`.headron`](docs/HEADRON-LANGUAGE.md) · [runtimes](models/README.md)
+- **Why a rule:** `headron why` · `headron failures` · [instruments](docs/INSTRUMENTS.md)
+- **Companion products:** [desktop, web, enterprise](docs/CONSUMING.md#optional-hlintel-services)
+- **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md) · [contributing](CONTRIBUTING.md)
+
+## Counts, computed
+
+Generated on every build; `check` refuses drift.
+
+<!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
+
+- **52** hard invariants — enforced on every change, zero unowned
+- **368** agreement edges — each a file tied to the declaration it answers for
+- **95** instruments — each stating what it proves, what it does not, and what closes the gap
+- **385** tool entries — across 40 manifests and 5 kinds, validated against `tools/tools.schema.json`
+- **184** harness Python files — every one held by `lint` · `format` · `typecheck`
+- **3.63.0** contract version — `VERSION`, asserted in 10 other files
+
+<!-- END generated: repository-facts -->
+
+## Project
+
+Version tracks the **contract**, not content ([versioning](docs/VERSIONING.md)).
+Built by **HLIntel LLC**, public on purpose ([about](ABOUT.md)). Contributions pass `headron verify`. [MIT License](LICENSE).
+
+Updated: contract v3.63.0

headron_software-3.63.0/README.md

@@ -0,0 +1,169 @@
+<!-- AGENTS: do not read this page breadth-first. Run `headron port <file>` (in a clone,
+     `python scripts/atlas.py port <file>`), or parse .agent/bootstrap.json. -->
+<!-- mcp-name: io.github.HLIntel/headron -->
+<div align="center">
+  <img src="https://raw.githubusercontent.com/HLIntel/Headron/main/docs/media/headron-banner.jpg"
+       alt="Headron Software: AI governance and verification"
+       width="992">
+  <h1>Headron Software</h1>
+</div>
+
+<!-- BEGIN generated: badges (python scripts/atlas.py index --write) -->
+
+**Contract 3.63.0** · MIT · verdicts carry receipts: `headron verify --receipt <file>`
+
+<!-- END generated: badges -->
+
+<!-- BEGIN generated: headline (python scripts/atlas.py index --write) -->
+
+- **Is:** a rule contract and CLI mapping changed files to checks. Hooks are optional; `headron verify` runs done gates.
+- **Is not:** a coding agent, model, test framework, or proof code is correct. A check that cannot run reports SKIP or NOT RUN, never a pass; the hook lets that commit through.
+- **`headron init` writes:** AGENTS.md, CLAUDE.md, .mcp.json, .codex/config.toml, .git/hooks/pre-commit. Use `--no-wiring` to skip hooks and configuration; `headron enforce uninstall` restores a displaced hook.
+- **Mind API:** hosted, paid, needs a key; plans a declared change. The command line works without it.
+
+Agents: [llms.txt](llms.txt). Chats: [CHAT.md](CHAT.md). [Evidence](#recorded-results).
+
+<!-- END generated: headline -->
+
+## Why this exists
+
+Headron connects changed files to declared checks and reports whether those checks ran. A skipped
+check is not a pass. An optional Git hook can run checks before a commit, whether the change came
+from a developer or an agent.
+
+## How it works
+
+`headron port <file>` tells an agent what a file owes before it edits. [`atlas.yaml`](atlas.yaml)
+holds those checks; the commit hook and CI report `PASS`, `FAIL`, `SKIP` or `NOT RUN`. The hosted
+[Mind API](https://headron.tech/mind-api.html) plans a declared change through `headron mind`.
+
+<!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
+
+<p align="center">
+  <img src="docs/media/headron-proof-flow.svg" width="900"
+       alt="Headron Architecture: contract, targeted evidence, integrity audit, unified verdict.">
+</p>
+
+<!-- END generated: proof-flow -->
+
+<!-- BEGIN generated: gate-example (python scripts/atlas.py index --write) -->
+
+```console
+$ 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
+```
+
+<!-- END generated: gate-example -->
+
+## Quickstart
+
+<!-- BEGIN generated: install (python scripts/atlas.py index --write) -->
+
+```bash
+# install
+uv tool install headron-software && headron doctor
+# editable, to change Headron itself
+git clone --depth 1 --branch v3.63.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor
+```
+
+<!-- END generated: install -->
+
+In your repository:
+
+```bash
+cd path/to/your-repo && headron init   # finds your checks, wires your agents, installs the commit hook, runs once
+headron verify && headron proof <file> --verify   # after a change: verdicts, then a file's proof
+```
+
+With an impact map, `headron verify --changed` evaluates checks for modified files.
+Target a specific profile with `headron verify --changed --change <class>` (e.g. `source_change`, `api_change`, `security_sensitive`); `headron verify` remains the final full verdict.
+
+**Machines:** [bootstrap](.agent/bootstrap.json), [facts](.agent/facts.json), and [JSON schema](tools/atlas-output.schema.json).
+**Agents:** [adapters](models/README.md); the MCP interface is read-only.
+**Another repository:** [CONSUMING](docs/CONSUMING.md).
+
+## Recorded results
+
+See the [instrument limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove) for their scope.
+
+<!-- BEGIN generated: measured-benefits (python scripts/atlas.py index --write) -->
+
+<!-- prettier-ignore -->
+| Instrument | Recorded result |
+| :--- | :--- |
+| Enforcement | 31/31 breaks refused across 20 toolchains; **816** declared planted cases |
+| Failure ledger | 128 shapes, 220 sightings; 104 in-tree guarded, 24 host-only |
+| Field ledger | 940 verifications (136 clean); 1133 refusals; 394 landings; 711 lessons; 394 sessions |
+| 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 |
+| Routing experiment | 89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models |
+| Language roles | 360 pairs: 110 runnable, 0 undeclared |
+
+Entry context: ~1,593 tokens. The 211 documents (708 KiB) load on demand; install: 10 KiB; hash lock with test tools: 8 packages.
+[Field records](benchmarks/field-latest.json). [Routing data](benchmarks/ab-latest.json). Measures can overlap.
+
+<!-- END generated: measured-benefits -->
+
+## Where it fits
+
+- **Agents and runtimes:** [adapters](models/README.md) describe supported integrations.
+- **Headron-Harness:** a separate desktop dashboard and runtime; see [product boundaries](docs/PRODUCT-STRATEGY.md).
+- **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).
+- **Languages:** routes declare available checks and identify checks without a tool.
+
+## Agent contract
+
+<!-- BEGIN generated: port-example (python scripts/atlas.py index --write) -->
+
+```console
+$ headron port scripts/doctor.py --line
+◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠2 │ → headron gate scripts/doctor.py
+$ headron port scripts --line
+◎ scripts │ ⠟186 │ ⌂scripts │ → headron brainstorm
+$ headron port . --line
+○ . │ ⠟214 ⠿4 ⠁1 │ → headron check
+```
+
+<!-- END generated: port-example -->
+
+- **Discover:** `headron find <query>` searches paths, symbols and vocabulary; `headron sweep` maps topology. Search does not guarantee semantic recall.
+- **Route:** `headron port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only its names.
+- **Processes:** `headron process [<id>] --json` lists workflows; with an id, its steps and gates.
+- **Mind:** `headron mind --route <file>` routes; `headron mind --receipts` summarizes the latest local verification record.
+- **Beliefs:** `headron revise` names what rests on a refuted claim; `headron propose` drafts each fix outside the tree.
+- **Automate:** add `--json`; records follow [the output schema](tools/atlas-output.schema.json).
+- **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](docs/systems/AGENT-HARNESS.md#judgment-rungs); file breaks with the [`headron` skill](skills/headron/SKILL.md).
+
+## Find your way
+
+- **Every document:** [docs index](docs/INDEX.md) · [wiki](docs/wiki/README.md)
+- **Languages:** [atlas](languages/ATLAS.md) · [routing](docs/wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
+- **Agents:** [harness](docs/systems/AGENT-HARNESS.md) · [`.headron`](docs/HEADRON-LANGUAGE.md) · [runtimes](models/README.md)
+- **Why a rule:** `headron why` · `headron failures` · [instruments](docs/INSTRUMENTS.md)
+- **Companion products:** [desktop, web, enterprise](docs/CONSUMING.md#optional-hlintel-services)
+- **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md) · [contributing](CONTRIBUTING.md)
+
+## Counts, computed
+
+Generated on every build; `check` refuses drift.
+
+<!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
+
+- **52** hard invariants — enforced on every change, zero unowned
+- **368** agreement edges — each a file tied to the declaration it answers for
+- **95** instruments — each stating what it proves, what it does not, and what closes the gap
+- **385** tool entries — across 40 manifests and 5 kinds, validated against `tools/tools.schema.json`
+- **184** harness Python files — every one held by `lint` · `format` · `typecheck`
+- **3.63.0** contract version — `VERSION`, asserted in 10 other files
+
+<!-- END generated: repository-facts -->
+
+## Project
+
+Version tracks the **contract**, not content ([versioning](docs/VERSIONING.md)).
+Built by **HLIntel LLC**, public on purpose ([about](ABOUT.md)). Contributions pass `headron verify`. [MIT License](LICENSE).
+
+Updated: contract v3.63.0

headron_software-3.63.0/VERSION

@@ -0,0 +1 @@
+3.63.0

{headron_software-3.61.0 → headron_software-3.63.0}/pyproject.toml

@@ -1,20 +1,6 @@
 # Headron — Python project declaration.
 #
-# WHY THIS FILE EXISTS (added at contract v1.2.0). `.ruff_cache/` and `.pytest_cache/` were already at the repo
-# root: ruff and pytest have been RUN here for some time while nothing declared them, nothing
-# configured them, and no gate enforced them. That is an undeclared habit, and an undeclared habit
-# is the thing that silently changes. This file declares exactly what is true and REFUSES to
-# declare what is not — because a config that names a gate nobody runs is the same skeleton this
-# repo exists to prevent.
-#
-# MEASURED BEFORE WRITING ANY OF IT (instrument: `ruff check . --show-files`, `ruff format --check`,
-# `python3 -m pytest -q`, all run at v1.2.0):
-#   - ruff saw exactly SIX Python files then; re-measured at v1.3.0 after the harness was
-#     split into modules, it sees 8. The count is not typed into a document: README's
-#     generated facts block computes it from scripts/*.py on every run.
-#   - `ruff check .` -> All checks passed, exit 0. Safe to enforce at that version, and enforced since.
-#   - `ruff format --check` -> enforced at 3.50.0, after one reviewed reformat; see [tool.ruff.format].
-#   - `python3 -m pytest -q` -> "no tests ran". Not adopted; see [tool.pytest] below.
+# Package metadata and the Python harness's checked configuration live here.
 
 # THIS FILE DESCRIBES THE HARNESS, NOT THE REPOSITORY.
 # 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
 dynamic = ["version"]                 # READ FROM VERSION, never typed here: a second declaration goes
                                       # stale first. The installed version is the release tag the CLI
                                       # fetches its atlas from when no root is declared.
-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."
+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."
 readme = "README.md"                   # the PyPI page; carries the registry ownership marker (server.json)
 license = "MIT"
 requires-python = ">=3.11"
@@ -44,7 +30,7 @@ classifiers = ["Development Status :: 4 - Beta", "Intended Audience :: Developer
 # FOUND FROM AN INSTALL. Before 2.28.0 an installed package named no link at all, so an agent
 # handed only `pip show` had no route back to the atlas, its entry or its instructions.
 [project.urls]
-Homepage = "https://github.com/HLIntel/Headron"
+Homepage = "https://headron.tech"
 Documentation = "https://github.com/HLIntel/Headron/blob/main/llms.txt"
 Issues = "https://github.com/HLIntel/Headron/issues"
 Source = "https://github.com/HLIntel/Headron"
@@ -106,7 +92,10 @@ select = ["E", "F", "I",              # pycodestyle errors, pyflakes, import sor
           # if, a returned condition, an any/all loop, a ternary over an if-block, and no else
           # after return/raise/continue — guard clauses. PERF401 was measured too and REJECTED:
           # 31 error-collecting loops with no safe fix, whose messages would hide in generators.
-          "C4", "SIM102", "SIM103", "SIM108", "SIM110", "RET505", "RET506", "RET508"]
+          "C4", "SIM102", "SIM103", "SIM108", "SIM110", "RET505", "RET506", "RET508",
+          # S110, an `except Exception: pass` that hides a programming error. Four hits
+          # (mind.py x3, mind_diagnostics.py x1) were narrowed to the errors each expects, so zero.
+          "S110"]
 ignore = ["E501"]                     # line length is governed by line-length above, not by a lint error
 
 [tool.ruff.lint.isort]
@@ -144,16 +133,9 @@ quote-style = "double"
 skip-magic-trailing-comma = true
 
 # [tool.pytest.ini_options] IS DELIBERATELY ABSENT.
-# A bare `python3 -m pytest -q` here would collect only the planted failing tests under
-# benchmarks/agent/ and read as broken code; the root conftest.py refuses it (exit 4) and names the
-# real commands. A path on the command line still runs that fixture. The contract's mutation tests
-# are a custom harness run directly:
-#
-#     python3 scripts/atlas_test.py     -> "atlas tests: N/N pass" with N asserted, exit 0
-#
-# declared in that file's own docblock and wired into .github/workflows/atlas-ci.yml. Declaring a
-# pytest section now would add a second, empty test surface whose green exit means nothing. When a
-# real pytest suite exists, configure it here and give it a failing case first.
+# A bare invocation could collect planted failures under benchmarks/agent/, so conftest.py refuses
+# it. Explicit paths still work. The artifacts_tests gate selects the artifact and data kit cases;
+# the mutation suite is a separate harness run by verify.
 
 [tool.basedpyright]
 # THE PACK'S DECLARED TYPE CHECKER, RUN ON ITS OWN TREE (3.54.0): gate `typecheck`. Standard mode, the
@@ -162,6 +144,7 @@ include = ["scripts", "examples", "fuzz", "benchmarks"]
 pythonVersion = "3.12"
 typeCheckingMode = "standard"
 reportMissingModuleSource = false
+reportMissingParameterType = "error"
 executionEnvironments = [
     { root = "examples/python", extraPaths = ["examples/python", "scripts"] },
     { root = "examples/webhooks", extraPaths = ["examples/webhooks", "scripts"] },

{headron_software-3.61.0 → headron_software-3.63.0}/scripts/atlas_cli.py

@@ -11,8 +11,10 @@ THAT TREE IS LOCKED (3.54.0): read-only, re-hashed on every run; an edit refuses
 
 from __future__ import annotations
 
+import contextlib
 import hashlib
 import io
+import json
 import os
 import re
 import shutil
@@ -36,7 +38,7 @@ class ConfigError(ValueError):
     """A root flag or consumer config this entry point refuses to guess about."""
 
 
-def _keys(path: Path, node, what: str, allowed=()) -> dict:
+def _keys(path: Path, node: yaml.Node, what: str, allowed: tuple[str, ...] = ()) -> dict:
     if not isinstance(node, yaml.MappingNode):
         raise ConfigError(f"{path}:{node.start_mark.line + 1}: {what} must be a mapping")
     out = {}
@@ -91,7 +93,7 @@ def resolve_root(argv: list[str], cwd: Path) -> tuple[Path, str]:
     value = root_flag(argv)[0]
     if value is not None:
         return Path(value).expanduser().resolve(), f"explicit {FLAG}"
-    for var in ("HEADRON_ROOT", "CODE_DEVELOPMENT_ROOT"):  # the second is the pre-3.0 name
+    for var in ("HEADRON_ROOT", "CODE_DEVELOPMENT_ROOT"):  # second: pre-3.0
         if os.environ.get(var):
             return Path(os.environ[var]).resolve(), f"{var} in the environment"
     config, where = _config(cwd)
@@ -163,7 +165,7 @@ def fetch_atlas(version: str) -> Path:
         (tree / MARKER).write_text("".join(f"{line}\n" for line in [f"{want[0]}  {name}", *_manifest(tree)]))
         for path in tree.rglob("*"):
             if path.is_file():
-                path.chmod(path.stat().st_mode & ~0o222)  # read-only, marker too: an edit fails where it is made
+                path.chmod(path.stat().st_mode & ~0o222)  # read-only, marker too: an edit fails on the spot
         shutil.rmtree(dest, ignore_errors=True)  # an unmarked, interrupted unpack
         os.replace(tree, dest)
         _prune_releases(dest.parent)
@@ -184,7 +186,7 @@ def _resolved(argv: list[str]) -> tuple:
         from importlib.metadata import version  # noqa: PLC0415
 
         root = fetch_atlas(version("headron-software"))
-        # Bytecode goes beside the locked tree, never into it, here and in every child process.
+        # Bytecode goes beside the locked tree, never into it, here and in every child.
         os.environ["PYTHONPYCACHEPREFIX"] = sys.pycache_prefix = str(root.parent / "pycache")
         return root, "its own release, sha256-checked and locked"
     except (ConfigError, FetchError, ImportError) as exc:
@@ -229,7 +231,19 @@ def mcp_main() -> int:
     argv = sys.argv[1:]
     if "--where" in argv:
         return main(argv)
-    if _enter(argv, "headron_mcp.py")[0] is None:
+    said = io.StringIO()
+    with contextlib.redirect_stderr(said):
+        root = _enter(argv, "headron_mcp.py")[0]
+    sys.stderr.write(said.getvalue())
+    if root is None:
+        # REFUSE IN THE HANDSHAKE (3.63.0): exiting before `initialize` showed the client only "Connection closed".
+        try:
+            ask = {} if sys.stdin.isatty() else json.loads(sys.stdin.readline() or "{}")
+        except ValueError:
+            ask = {}
+        if isinstance(ask, dict) and "id" in ask:
+            why = {"code": -32000, "message": "headron-mcp refused: " + " ".join(said.getvalue().split())}
+            print(json.dumps({"jsonrpc": "2.0", "id": ask["id"], "error": why}), flush=True)
         return 2
     import headron_mcp  # noqa: PLC0415 — as in main