thea-software 3.53.0__tar.gz

thea_software-3.53.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HLIntel LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thea_software-3.53.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: thea-software
+Version: 3.53.0
+Summary: Contract harness for Thea, the engineering layer for AI. The atlas is polyglot; only this harness is Python.
+Project-URL: Homepage, https://github.com/HLIntel/thea-software
+Project-URL: Documentation, https://github.com/HLIntel/thea-software/blob/main/llms.txt
+Project-URL: Issues, https://github.com/HLIntel/thea-software/issues
+Project-URL: Source, https://github.com/HLIntel/thea-software
+Project-URL: Agent entry, https://raw.githubusercontent.com/HLIntel/thea-software/main/.agent/bootstrap.json
+Project-URL: LLM instructions, https://raw.githubusercontent.com/HLIntel/thea-software/main/llms.txt
+Project-URL: Changelog, https://github.com/HLIntel/thea-software/blob/main/docs/VERSIONING.md
+Keywords: engineering-atlas,polyglot,contract-verification,ai-agents,mcp,llm,agent-harness,code-verification,developer-tools,static-analysis,supply-chain-security,claude-code,agents-md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+License-File: LICENSE
+Requires-Dist: pyyaml<7,>=6.0.3
+Provides-Extra: quality
+Requires-Dist: ruff>=0.6; extra == "quality"
+Dynamic: license-file

thea_software-3.53.0/README.md

@@ -0,0 +1,198 @@
+<!-- AGENTS: do not read this page breadth-first. Plug in: `python scripts/atlas.py port <file>`,
+     or parse .agent/bootstrap.json — one record back. -->
+<p align="center">
+  <img src="docs/assets/thea.webp"
+       alt="Thea — software development and AI agents, by HLIntel LLC" width="240">
+</p>
+
+<h1 align="center"><picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/title-dark.svg">
+  <img src="docs/assets/title-light.svg" alt="The Heartland Engineering Atlas" width="560">
+</picture></h1>
+
+<p align="center">
+  A machine-readable rulebook for AI coding agents, and the build checks that enforce it.<br>
+  <em>AI proposes a change. The file's own toolchain proves it. The build refuses what skipped a check.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/HLIntel/thea-software/actions/workflows/atlas-ci.yml"><img
+     src="https://github.com/HLIntel/thea-software/actions/workflows/atlas-ci.yml/badge.svg?branch=main"
+     alt="Atlas CI"></a>
+  <a href="https://github.com/HLIntel/thea-software/releases/latest"><img
+     src="https://img.shields.io/github/v/tag/HLIntel/thea-software?label=contract"
+     alt="contract version"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/HLIntel/thea-software"><img
+     src="https://api.securityscorecards.dev/projects/github.com/HLIntel/thea-software/badge"
+     alt="OpenSSF Scorecard"></a>
+</p>
+
+An AI reading this: agents start at [llms.txt](llms.txt), chats at [CHAT.md](CHAT.md).
+
+## What it does
+
+Thea tells an AI coding agent which commands prove a change to a file, and fails the build when a
+change skipped them. One declaration, [`atlas.yaml`](atlas.yaml), answers **what proves this change
+is correct?** It never guesses, and refuses ambiguous input.
+
+<!-- BEGIN generated: proof-flow (python scripts/atlas.py index --write) -->
+```mermaid
+---
+config:
+  theme: base
+  themeVariables:
+    primaryColor: "#ffffff"
+    primaryBorderColor: "#2e7d32"
+    primaryTextColor: "#1b3a1f"
+    lineColor: "#2e7d32"
+    clusterBkg: "#eef7ee"
+    clusterBorder: "#a5d6a7"
+    titleColor: "#1b5e20"
+  flowchart:
+    subGraphTitleMargin: {top: 8, bottom: 16}
+    padding: 14
+---
+flowchart TB
+  accTitle: How Thea proves a change
+  accDescr: 7 runtimes ask, atlas.yaml routes to 1 of 36 packs and 64 gates, the same gates run at commit, in CI and in thea verify, anything but PASS is refused, verdicts feed the failure and success ledgers, a trained judge only advises
+  subgraph thea [" "]
+    direction TB
+    subgraph ask [1 · ask: one declaration answers]
+      direction LR
+      A[7 agent runtimes<br>Claude Code · Codex · Cursor · opencode · Hermes] -->|CLI · MCP · hooks · llms.txt| D[(atlas.yaml<br>82 instruments · 47 invariants)]
+      D -->|route| P[36 language packs] --> K[8 change classes] --> G[64 gates]
+    end
+    subgraph run [2 · prove: the same gates, three places]
+      direction LR
+      H[git hook · commit] & C[CI · pull request] & R[thea verify · agent] --> V{{exit code<br>PASS · FAIL · NOT RUN}}
+      V -->|PASS| M[landed]
+      V -->|not PASS| X[refused]
+    end
+    subgraph learn [3 · learn: every verdict is kept]
+      direction LR
+      F[107 failure shapes<br>40 success moves] --> N[handed back<br>at the next port]
+      F --> J[thea judge · model<br>advises, never decides]
+    end
+    ask --> run --> learn
+  end
+  style thea fill:#f6fbf6,stroke:#2e7d32,stroke-width:2px
+  classDef stop fill:#fdecea,stroke:#c62828,color:#7f1d1d
+  classDef go fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
+  class X stop
+  class M go
+```
+<!-- END generated: proof-flow -->
+
+<!-- BEGIN generated: gate-example (python scripts/atlas.py index --write) -->
+```console
+$ thea 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 -->
+
+**Not** an app framework, a runtime optimizer or a sandbox.
+
+## Quickstart
+
+<!-- BEGIN generated: install (python scripts/atlas.py index --write) -->
+```bash
+git clone --depth 1 --branch v3.53.0 https://github.com/HLIntel/thea-software ~/thea && uv tool install --editable ~/thea && thea doctor
+```
+<!-- END generated: install -->
+
+```bash
+cd ~/thea
+thea port scripts/doctor.py   # route, gates, lessons, next step
+thea gate scripts/doctor.py   # the commands that prove a change
+thea verify                   # every gate; exit 0 only if all PASS
+```
+
+`thea-mcp` serves them read-only. From another repository: [docs/CONSUMING.md](docs/CONSUMING.md).
+Every runtime: [models/README.md](models/README.md).
+
+<!-- BEGIN generated: port-example (python scripts/atlas.py index --write) -->
+```console
+$ thea port scripts/doctor.py --line
+◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓3 │ ⚠1 │ → thea gate scripts/doctor.py
+$ thea port scripts --line
+◎ scripts │ ⠟91 │ ⌂scripts │ → thea brainstorm
+$ thea port . --line
+○ . │ ⠟118 ⠿4 ⠁3 │ → thea check
+```
+<!-- END generated: port-example -->
+
+## What it measurably buys
+
+Recorded runs, each naming its instrument: evidence for routing and refusals, not for end-to-end
+task success ([limits](docs/CERTIFICATION.md#what-the-numbers-do-not-prove)).
+
+<!-- BEGIN generated: measured-benefits (python scripts/atlas.py index --write) -->
+*With Thea*: the model is shown what `thea gate` prints for the file. *Blind*: it gets only the list
+of language names. Token savings are against the usual alternative: pasting in every language's tool list.
+
+**On Claude** (76 questions per model, `abtest.py` v3.49.0)
+- **Opus:** 100% right with Thea, 41% blind; reads 90% fewer tokens.
+- **Sonnet:** 100% right with Thea, 39% blind; reads 90% fewer tokens.
+- **Haiku:** 100% right with Thea, 39% blind; reads 91% fewer tokens.
+- **Claude Code start-up:** loads `CLAUDE.md` and its imports, 1,049 tokens.
+
+**Beyond routing** (blind → with Thea, `taskbench.py` v2.29.0)
+- **Name a failure from its symptom:** Opus 93% → 100%; Sonnet 57% → 100%; Haiku 64% → 96%.
+- **List the checks a change needs:** Opus 12% → 100%; Sonnet 12% → 100%; Haiku 0% → 100%.
+- **Spot a line the build refuses (yes/no, so a coin flip scores 50%):** Opus 60% → 100%; Sonnet 60% → 100%; Haiku 40% → 100%.
+- *Not measured:* visual design, open-ended strategy, arithmetic — nothing declares a right answer.
+
+**Across all 11 models tested** (5 providers, 2,409 questions, `abtest.py` v2.27.0 / v2.28.0 / v3.49.0)
+- **Right answers:** 99% (95% interval 98–99%) with Thea, 59% (95% interval 55–63%) blind; every model 97–100% with Thea. A random guess scores 2.8%.
+- **Tokens:** reads 89% fewer than pasting every tool list, and 51% fewer than asking blind.
+
+**The repository itself** (recomputed on every build)
+- **Before routing:** an agent reads 1,729 tokens. The other 194 documents (701 KiB) load only when a route names one.
+- **Coverage:** all 324 language × check pairs answer — 133 with a command, 191 with a declared *no tool*, 0 silently.
+- **Mistakes caught:** 463 kinds are planted in the tests, and each must be refused.
+- **Enforced at commit:** refused 17 of 17 planted breaks in 12 languages; 11 files untested here (`enforce.py`, v3.6.0).
+- **Agent-to-agent handoffs with the right checks** (schema alone → with Thea): Opus 0/6 → 6/6; Sonnet 0/6 → 6/6; Haiku 0/6 → 6/6 (`workflowbench.py`).
+- **Solo commits:** 24/24 clean with or without the hook on these tasks; a planted broken commit is refused.
+- **Agent controls that block, not warn:** narrow_tools, sandbox, budget, approval, effects, audit.
+- **Install:** 8 KiB, 1 module, 1 dependency — 1 in total with its own dependencies.
+<!-- END generated: measured-benefits -->
+
+## For agents
+
+- **Plug in** with `thea port <file>`, or parse [.agent/bootstrap.json](.agent/bootstrap.json); load only what it names.
+- **Read machine output, not this page.** Add `--json` to any command: one record per gate, frozen in
+  [tools/atlas-output.schema.json](tools/atlas-output.schema.json).
+- **Before a shell command,** `thea shell --json "<cmd>"`: exit 3 means its verdict would be misread.
+- **Land** with `python scripts/branchstate.py --land`; ask `thea landed <branch>` before deleting one.
+- **Judgments** answer on [rules, teacher or a keyless student](systems/AGENT-HARNESS.md#judgment-rungs).
+- **When something breaks,** file it the same turn with the [`thea` skill](skills/thea/SKILL.md).
+
+## Counts, computed
+
+Every number on this page is generated from the tree on each build, and `check` fails when one drifts.
+
+<!-- BEGIN generated: repository-facts (python scripts/atlas.py index --write) -->
+- **contract version:** 3.53.0 — `VERSION`, asserted at a declared line in 7 other files
+- **tool manifests:** 36 — `languages/<route>/tools.yaml`, validated against `tools/tools.schema.json`
+- **declared tool entries:** 373 — distinct entries per manifest, summed; `packprobe.py` classifies every one
+- **entry kinds:** 5 — `tools/tools.schema.json` `$defs.entry.x-kinds`
+- **verification gate classes:** 8 — `atlas.yaml/verification_policy/profiles`
+- **task profiles:** 14 — `atlas.yaml/task_profiles`
+- **python files in the harness:** 90 — `scripts/*.py`, all linted by ruff
+<!-- END generated: repository-facts -->
+
+## Find your way
+
+- **Every document:** [docs index](docs/INDEX.md) · [wiki](wiki/README.md)
+- **Languages:** [atlas](languages/ATLAS.md) · [routing](wiki/CODE-ROUTING.md) · [verification](docs/VERIFY.md)
+- **Agents:** [harness](systems/AGENT-HARNESS.md) · [`.thea`](docs/THEA-LANGUAGE.md) · [runtimes](models/README.md)
+- **Why a rule exists:** `thea why` · `thea failures` · [instruments](docs/INSTRUMENTS.md)
+- **Security:** [policy](SECURITY.md) · [OpenSSF](docs/OPENSSF.md)
+
+## Project
+
+The version tracks the **contract**, not the content: [docs/VERSIONING.md](docs/VERSIONING.md).
+Built by **HLIntel LLC**, public on purpose: **no secret, private path or internal host enters
+it** ([ABOUT.md](ABOUT.md)). Contributions pass `thea verify`. [MIT License](LICENSE).

thea_software-3.53.0/VERSION

@@ -0,0 +1 @@
+3.53.0

thea_software-3.53.0/pyproject.toml

@@ -0,0 +1,151 @@
+# Thea — 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.
+
+# THIS FILE DESCRIBES THE HARNESS, NOT THE REPOSITORY.
+# The atlas is polyglot and is not a Python project; Python is simply what the contract
+# harness happens to be written in. A `pyproject.toml` at the root of a polyglot repository reads
+# as "this is a Python package" to both humans and tooling, so the name says otherwise explicitly.
+# The languages themselves declare their own authority in languages/<lang>/tools.yaml — that is
+# the roster, and it is not Python-shaped. Only the harness CLI installs (see [project.scripts]); the atlas is pointed at.
+
+[project]
+name = "thea-software"                # 3.53.0: the index name a stranger types; formerly thea-harness
+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 = "Contract harness for Thea, the engineering layer for AI. The atlas is polyglot; only this harness is Python."
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0.3,<7"]       # the single runtime dep, mirrored from scripts/requirements.txt
+keywords = ["engineering-atlas", "polyglot", "contract-verification", "ai-agents", "mcp", "llm", "agent-harness",
+            "code-verification", "developer-tools", "static-analysis", "supply-chain-security", "claude-code", "agents-md"]
+classifiers = ["Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License",
+               "Programming Language :: Python :: 3", "Topic :: Software Development :: Quality Assurance",
+               "Topic :: Software Development :: Testing", "Topic :: Scientific/Engineering :: Artificial Intelligence"]
+
+# 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/thea-software"
+Documentation = "https://github.com/HLIntel/thea-software/blob/main/llms.txt"
+Issues = "https://github.com/HLIntel/thea-software/issues"
+Source = "https://github.com/HLIntel/thea-software"
+"Agent entry" = "https://raw.githubusercontent.com/HLIntel/thea-software/main/.agent/bootstrap.json"
+"LLM instructions" = "https://raw.githubusercontent.com/HLIntel/thea-software/main/llms.txt"
+Changelog = "https://github.com/HLIntel/thea-software/blob/main/docs/VERSIONING.md"
+
+[project.optional-dependencies]
+quality = ["ruff>=0.6"]
+
+# THE HARNESS IS INSTALLABLE; THE ATLAS IS POINTED AT. This is the whole external interface, and
+# the split is deliberate. Shipping the policy content inside the wheel would create a second copy
+# that ages exactly like a vendored tree — so the CLI resolves WHICH atlas it is running against
+# (--atlas-root, THEA_ROOT, or a pinned `atlas: root:` in a consumer's .atlas.yaml) and PRINTS
+# the rule that decided it. An explicit pin and a lucky fall-through are the same answer with very
+# different trust, and `atlas --where` is how a consumer tells them apart.
+[project.scripts]
+thea = "atlas_cli:main"
+thea-mcp = "atlas_cli:mcp_main"   # Thea's commands as MCP tools on stdio, read-only
+atlas = "atlas_cli:main"   # the pre-3.7 name, still answered
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools]
+package-dir = {"" = "scripts"}
+# WHAT SHIPS: THE LAUNCHER, AND NOTHING THE ATLAS ALREADY HOLDS (3.7.0). Eleven harness modules used
+# to ship, and `atlas check` then died in an install with "No module named 'identity'": the wheel
+# carried a SECOND COPY of the harness, one version old or new against the pinned atlas it ran on,
+# and missing whatever the check needed next. The launcher now resolves the atlas and runs THAT
+# atlas's own scripts/, so a consumer's pinned ref governs the code as well as the data, and there
+# is no roster of shipped modules left to drift. `atlas.py check` refuses any module added here.
+py-modules = ["atlas_cli"]
+
+[tool.ruff]
+# benchmarks/agent holds DELIBERATELY broken task fixtures (a planted bug, a planted format fault): an agent
+# is scored on fixing them, so linting them would fail the tree for doing its job.
+extend-exclude = ["benchmarks/agent"]
+# AN EXPLICIT PATH STILL OBEYS THE EXCLUDES (3.50.0): `ruff format scripts/atlasgen.py` reflowed an
+# excluded file past the line cap, because ruff only applies excludes to paths it discovers.
+force-exclude = true
+# The harness and the Python examples. `languages/` holds prose and manifests, not a package.
+include = ["scripts/*.py", "examples/**/*.py"]
+line-length = 120                     # matches .editorconfig; column width is a rule of thumb, never a
+                                      # gate — see docs/ENGINEERING-CONCEPTS.md
+
+[tool.ruff.lint]
+# ENFORCED, because it passed clean on the real tree at the version it was added (exit 0, zero
+# findings), and the sweep is re-run on every change. A guard that
+# fires on correct code gets disabled, so nothing is enabled here that this repo does not already
+# satisfy. Widen deliberately, one rule family at a time, each with a clean sweep before it lands.
+select = ["E", "F", "I",              # pycodestyle errors, pyflakes, import sorting
+          # 2.28.0, each measured at ZERO findings first: comprehension idioms, a collapsed nested
+          # 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"]
+ignore = ["E501"]                     # line length is governed by line-length above, not by a lint error
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = false   # agrees with format.skip-magic-trailing-comma
+
+[tool.ruff.lint.per-file-ignores]
+# E402 is WRONG here, and the exemption carries its reason inline rather than being a snooze button.
+# atlas_test.py must `sys.path.insert(0, ROOT/"scripts")` BEFORE `import atlas`, because the module
+# it tests is not installed — you cannot import from a directory that is not yet on the path. Moving
+# that import to the top, as the rule asks, breaks the harness. Scoped to the one file so the rule
+# keeps protecting every other file.
+"scripts/atlas_test.py" = ["E402"]
+# Same reason, same shape: agent_test.py imports the three agent modules after putting
+# scripts/ on the path, because they are not installed either. Two files, one reason,
+# both scoped — never a repository-wide disable of a rule that is right everywhere else.
+"scripts/agent_test.py" = ["E402"]
+
+[tool.ruff.format]
+# ENFORCED: CI runs `ruff format --check .`; the reformat landed as ONE commit, listed in
+# .git-blame-ignore-revs so blame skips it. The exclusions below are files that formatting
+# would push past the code_shape line cap; the cap is never raised, so each leaves this list
+# only when a split brings it back under. The list only shrinks.
+exclude = [
+    "scripts/agent_test.py",
+    "scripts/agentpolicy.py",
+    "scripts/atlas.py",
+    "scripts/atlas_guards_test.py",
+    "scripts/atlas_rules_test.py",
+    "scripts/atlas_test.py",
+    "scripts/atlasgen.py",
+    "scripts/atlasinv.py",
+    "scripts/knowledge.py",
+]
+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.

thea_software-3.53.0/scripts/atlas_cli.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""The installable entry point: resolve WHICH atlas, then run the contract's own CLI against it.
+
+A SEPARATE MODULE (2.11.0) because `atlascore` fixes the root at IMPORT time: this resolves it first,
+exports it, then imports the harness. IT PRINTS THE RULE THAT DECIDED THE ROOT: an explicit flag and
+a lucky fall-through are the same answer with very different trust. A CONSUMER PINS A REF, NEVER
+`main`, in `.atlas.yaml`, so the pin is reviewed in its own diff.
+WITH NO ROOT AND NO CHECKOUT (3.53.0) it fetches its own version's release, sha256-checked; else refuses.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import re
+import shutil
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+
+import yaml
+
+CONSUMER_CONFIG = ".atlas.yaml"
+FLAG = "--atlas-root"
+RELEASES = "https://github.com/HLIntel/thea-software/releases/download"
+INSTALLED_FROM = "the checkout this entry point was installed from"
+MARKER = ".thea-release.sha256"  # written last: an unmarked cache is never used
+# REFUSE RATHER THAN INVENT (3.47.0): a key not known by name is refused at its file:line.
+SECTIONS, PIN = ("atlas", "stack_tiers", "markdown_policy"), ("ref", "root", "task", "change_class", "process")
+
+
+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:
+    if not isinstance(node, yaml.MappingNode):
+        raise ConfigError(f"{path}:{node.start_mark.line + 1}: {what} must be a mapping")
+    out = {}
+    for key, value in node.value:
+        name, line = key.value, key.start_mark.line + 1
+        if not isinstance(name, str) or name in out or allowed and name not in allowed:
+            raise ConfigError(f"{path}:{line}: bad or repeated key {name!r} in {what}; allowed: {allowed}")
+        out[name] = value
+    return out
+
+
+def _pin(path: Path) -> dict[str, str]:
+    """The `atlas:` mapping of one config file, every key checked by name."""
+    try:
+        doc = yaml.compose(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        raise ConfigError(f"{path}:{mark.line + 1 if mark else 1}: not parseable YAML") from None
+    sections = _keys(path, doc, CONSUMER_CONFIG, SECTIONS) if doc else {}
+    pins = {name: _keys(path, node, name) for name, node in sections.items()}.get("atlas", {})
+    for name, value in pins.items():
+        if name not in PIN or value.tag != "tag:yaml.org,2002:str" or not value.value.strip():
+            raise ConfigError(f"{path}:{value.start_mark.line + 1}: atlas.{name}: want a string in {PIN}")
+    return {name: value.value for name, value in pins.items()}
+
+
+def _config(start: Path) -> tuple[dict, Path | None]:
+    """The pin of the nearest .atlas.yaml at or above `start`; ConfigError on any doubt."""
+    for path in (d / CONSUMER_CONFIG for d in [start, *start.parents]):
+        if path.exists():
+            return _pin(path), path
+    return {}, None
+
+
+def root_flag(argv: list[str]) -> tuple[str | None, int, int]:
+    """(value, index, width) of the root flag, or (None, -1, 0); refused with no value (3.47.0)."""
+    hits = [i for i, arg in enumerate(argv) if arg == FLAG or arg.startswith(FLAG + "=")]
+    if not hits:
+        return None, -1, 0
+    i, eq = hits[0], argv[hits[0]] != FLAG
+    value = argv[i].partition("=")[2] if eq else (argv[i + 1 :] or [""])[0]
+    if len(hits) > 1 or not value.strip() or value.startswith("-") and not eq:
+        raise ConfigError(f"{FLAG} needs one directory, given once; got {value!r}")
+    return value, i, 1 if eq else 2
+
+
+def resolve_root(argv: list[str], cwd: Path) -> tuple[Path, str]:
+    """The atlas this invocation runs against, and the rule that decided it. In declared order."""
+    value = root_flag(argv)[0]
+    if value is not None:
+        return Path(value).expanduser().resolve(), f"explicit {FLAG}"
+    for var in ("THEA_ROOT", "CODE_DEVELOPMENT_ROOT"):  # the second is the pre-3.0 name, still honoured
+        if os.environ.get(var):
+            return Path(os.environ[var]).resolve(), f"{var} in the environment"
+    config, where = _config(cwd)
+    if config.get("root"):
+        base = (where.parent / config["root"]).resolve()
+        return base, f"root declared in {where.name} (ref {config.get('ref', 'unpinned')})"
+    return Path(__file__).resolve().parents[1], INSTALLED_FROM
+
+
+class FetchError(RuntimeError):
+    """A release atlas refused: unreachable, unverified, or another version."""
+
+
+def _get(url: str) -> bytes:
+    import urllib.request  # noqa: PLC0415
+
+    try:
+        with urllib.request.urlopen(url, timeout=60) as r:  # noqa: S310 — a fixed https base
+            return r.read()
+    except (OSError, ValueError) as exc:
+        raise FetchError(f"cannot download {url}: {exc}") from None
+
+
+def fetch_atlas(version: str) -> Path:
+    """Release v<version>'s tree, cached or downloaded and sha256-checked; else FetchError."""
+    dest = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache", "thea", f"atlas-{version}")
+    if (dest / MARKER).is_file():
+        return dest
+    name = f"thea-v{version}.tar.gz"
+    url = f"{RELEASES}/v{version}/{name}"
+    want = re.findall(
+        rf"^([0-9a-f]{{64}}) [ *]{re.escape(name)}$", _get(url + ".sha256").decode(errors="replace"), re.M
+    )
+    blob = _get(url)
+    if len(want) != 1 or hashlib.sha256(blob).hexdigest() != want[0]:
+        raise FetchError(f"{name}: sha256 is not its release's one digest {want}")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(dir=dest.parent))
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob)) as tar:
+            tops = {m.name.split("/")[0] for m in tar}
+            tar.extractall(work, filter="data")  # refuses absolute, climbing and escaping links
+        tree = work / tops.pop()
+        if tops or (tree / "VERSION").read_text().strip() != version:
+            raise FetchError(f"{name} is not one tree of contract {version}")
+        (tree / MARKER).write_text(f"{want[0]}  {name}\n")
+        shutil.rmtree(dest, ignore_errors=True)  # an unmarked, interrupted unpack
+        os.replace(tree, dest)
+    except (tarfile.TarError, OSError, TypeError) as exc:  # TypeError: no data filter before 3.11.4
+        raise FetchError(f"{name} could not be unpacked: {exc}") from None
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    return dest
+
+
+def _resolved(argv: list[str]) -> tuple:
+    try:
+        root, rule = resolve_root(argv, Path.cwd())
+        if rule != INSTALLED_FROM or (root / "atlas.yaml").exists():
+            return root, rule
+        if os.environ.get("THEA_NO_FETCH") == "1":
+            return root, rule + "; THEA_NO_FETCH=1"
+        from importlib.metadata import version  # noqa: PLC0415
+
+        return fetch_atlas(version("thea-software")), "its own release, sha256-checked"
+    except (ConfigError, FetchError, ImportError) as exc:
+        print(f"refused: {exc}", file=sys.stderr)
+        return None, None
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    root, rule = _resolved(argv)
+    if root is None:
+        return 2
+    _, index, width = root_flag(argv)
+    del argv[index : index + width]
+    if not (root / "atlas.yaml").exists():
+        print(f"no atlas at {root} (resolved by: {rule})", file=sys.stderr)
+        print(f"point at a checkout with {FLAG}, THEA_ROOT, or `atlas: root:` in {CONSUMER_CONFIG}", file=sys.stderr)
+        return 2
+    os.environ["THEA_ROOT"] = os.environ["CODE_DEVELOPMENT_ROOT"] = str(root)
+    # THE HARNESS COMES FROM THE ATLAS, NEVER THE WHEEL (3.7.0): a bundled copy is a second implementation.
+    harness = root / "scripts"
+    if not (harness / "atlas.py").exists():
+        print(f"{root} has an atlas.yaml and no scripts/atlas.py — not a Thea checkout", file=sys.stderr)
+        return 2
+    sys.path.insert(0, str(harness))
+    if "--where" in argv:
+        print(f"atlas root: {root}")
+        print(f"resolved by: {rule}")
+        # An agent handed only an install must still find where to start: the resolved atlas's entry.
+        print(f"agent entry: {root / '.agent' / 'bootstrap.json'}  (then: thea gate <file>)")
+        return 0
+    import atlas  # noqa: PLC0415 — deliberate: the root must be exported before this import
+
+    return atlas.main(argv or ["check"])
+
+
+def mcp_main() -> int:
+    """`thea-mcp`: the same root resolution, then serve the resolved atlas's MCP route on stdio."""
+    argv = sys.argv[1:]
+    if "--where" in argv:
+        return main(argv)
+    root, rule = _resolved(argv)
+    if root is None:
+        return 2
+    if not (root / "scripts" / "thea_mcp.py").exists():
+        print(f"no Thea MCP server at {root} (resolved by: {rule})", file=sys.stderr)
+        return 2
+    os.environ["THEA_ROOT"] = os.environ["CODE_DEVELOPMENT_ROOT"] = str(root)
+    sys.path.insert(0, str(root / "scripts"))
+    import thea_mcp  # noqa: PLC0415 — deliberate: the root must be exported before this import
+
+    return thea_mcp.serve()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

thea_software-3.53.0/scripts/thea_software.egg-info/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: thea-software
+Version: 3.53.0
+Summary: Contract harness for Thea, the engineering layer for AI. The atlas is polyglot; only this harness is Python.
+Project-URL: Homepage, https://github.com/HLIntel/thea-software
+Project-URL: Documentation, https://github.com/HLIntel/thea-software/blob/main/llms.txt
+Project-URL: Issues, https://github.com/HLIntel/thea-software/issues
+Project-URL: Source, https://github.com/HLIntel/thea-software
+Project-URL: Agent entry, https://raw.githubusercontent.com/HLIntel/thea-software/main/.agent/bootstrap.json
+Project-URL: LLM instructions, https://raw.githubusercontent.com/HLIntel/thea-software/main/llms.txt
+Project-URL: Changelog, https://github.com/HLIntel/thea-software/blob/main/docs/VERSIONING.md
+Keywords: engineering-atlas,polyglot,contract-verification,ai-agents,mcp,llm,agent-harness,code-verification,developer-tools,static-analysis,supply-chain-security,claude-code,agents-md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+License-File: LICENSE
+Requires-Dist: pyyaml<7,>=6.0.3
+Provides-Extra: quality
+Requires-Dist: ruff>=0.6; extra == "quality"
+Dynamic: license-file

thea_software-3.53.0/scripts/thea_software.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+VERSION
+pyproject.toml
+scripts/atlas_cli.py
+scripts/thea_software.egg-info/PKG-INFO
+scripts/thea_software.egg-info/SOURCES.txt
+scripts/thea_software.egg-info/dependency_links.txt
+scripts/thea_software.egg-info/entry_points.txt
+scripts/thea_software.egg-info/requires.txt
+scripts/thea_software.egg-info/top_level.txt

thea_software-3.53.0/scripts/thea_software.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

thea_software-3.53.0/scripts/thea_software.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+atlas = atlas_cli:main
+thea = atlas_cli:main
+thea-mcp = atlas_cli:mcp_main

thea_software-3.53.0/scripts/thea_software.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyyaml<7,>=6.0.3
+
+[quality]
+ruff>=0.6

thea_software-3.53.0/scripts/thea_software.egg-info/top_level.txt

@@ -0,0 +1 @@
+atlas_cli

thea_software-3.53.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+