Metadata-Version: 2.4
Name: cortex-loop
Version: 0.1.0a1
Summary: Runtime-agnostic enforcement layer for AI coding agents
Author: Cortex contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/cortex-loop/cortex-loop
Project-URL: Repository, https://github.com/cortex-loop/cortex-loop
Project-URL: Issues, https://github.com/cortex-loop/cortex-loop/issues
Keywords: ai,coding-agent,enforcement,verification,runtime-agnostic
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: repomap
Requires-Dist: grep-ast==0.9.0; extra == "repomap"
Requires-Dist: numpy>=2.0; extra == "repomap"
Requires-Dist: networkx==3.4.2; extra == "repomap"
Requires-Dist: tree-sitter-language-pack==0.13.0; extra == "repomap"
Requires-Dist: tree-sitter==0.25.2; extra == "repomap"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Dynamic: license-file

![cortex-loop banner](docs/assets/cortex-loop-banner.webp)

# Cortex

Cortex is a runtime-agnostic enforcement layer for AI coding agents. It verifies completion claims through a deterministic stop path instead of trusting summaries, so "done" only lands when the evidence is real. Coding agents can sound finished before reality has caught up; Cortex turns that completion claim into something the system can prove or deny.

With Cortex, the path of least resistance becomes the path of best practice: the easiest way to finish is to do the work, satisfy the evidence boundary, and let the stop path close honestly.

The stop path is the product. Cortex is not a planning framework, generic memory layer, or workflow wrapper. It exists to make completion claims legible, checkable, and hard to bluff.

## Runtime Status

| Runtime | Install profile | Status | Notes |
| --- | --- | --- | --- |
| Claude Code | `cortex runtime install --profile claude` | Shipped | Strongest current runtime. The truthful boundary is live-proven; remaining caveats are minor. |
| Gemini CLI | `cortex runtime install --profile gemini` | Shipped with watchlist | The truthful boundary is live-proven. One operational watchlist remains: blocked malformed stops can leave Gemini CLI resident until operator termination. |
| OpenAI Codex App Server | `cortex runtime install --profile openai` | Experimental | Several critical paths are proven on the latest stable surface, but positive strict close is still not dependable enough for broader support. |

Status labels in this table:
- `Shipped`: live-proven on the shared harness; remaining caveats are non-critical.
- `Shipped with watchlist`: live-proven, but one named runtime quirk still creates real operator risk.
- `Experimental`: several important paths are proven, but one boundary-critical guarantee remains unproven or unstable.

Detailed runtime release evidence lives in [docs/ADAPTER_VALIDATION.md](docs/ADAPTER_VALIDATION.md) plus committed provenance under [tests/fixtures/adapter_validation/claude/PROVENANCE.json](tests/fixtures/adapter_validation/claude/PROVENANCE.json), [tests/fixtures/adapter_validation/gemini/PROVENANCE.json](tests/fixtures/adapter_validation/gemini/PROVENANCE.json), and [tests/fixtures/adapter_validation/openai/PROVENANCE.json](tests/fixtures/adapter_validation/openai/PROVENANCE.json).

## Quickstart

As of 2026-03-07, `cortex-loop` is not yet published on PyPI. Until live
package publication is proven, the truthful first-run path is from a repo
checkout:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install . pytest
cortex init
cortex runtime install --profile claude
```

Before `cortex check`, choose the baseline that matches the repository:

- trusted local repo: switch `cortex.toml` to the trusted-host baseline in
  [docs/SECURE_DEFAULTS.md](docs/SECURE_DEFAULTS.md)
- untrusted or container baseline: keep the defaults and ensure Docker is on
  `PATH`

Then run:

```bash
cortex check
```

The staged public install posture, update and uninstall commands, and the PyPI
publication gate live in [docs/INSTALL.md](docs/INSTALL.md).

For a first evaluation, keep `claude`. Use `gemini` when you want the shipped
watchlist surface. Use `openai` only when you are explicitly evaluating the
experimental surface.

## What Cortex Enforces

- Stop-claim normalization and strict payload handling ([tests/test_stop_contract.py](tests/test_stop_contract.py))
- Challenge coverage across active categories ([tests/test_challenges.py](tests/test_challenges.py))
- Invariant execution outside model output ([tests/test_invariants.py](tests/test_invariants.py))
- Deterministic verdict policy ([tests/test_stop_policy.py](tests/test_stop_policy.py))
- Session-scoped failure memory and retry controls ([tests/test_retry.py](tests/test_retry.py), [tests/test_graveyard.py](tests/test_graveyard.py))

## What Cortex Is Not

- not a generic multi-agent framework
- not prompt theater that trusts summaries
- not a workflow layer whose main job is planning or project management

## Read Next

1. [START_HERE.md](START_HERE.md)
2. [ARCHITECTURE.md](ARCHITECTURE.md)
3. [MISSION.md](MISSION.md)
4. [docs/README.md](docs/README.md)
5. [CONTRIBUTING.md](CONTRIBUTING.md)

## Repository Boundaries

- Product-critical code lives in `cortex/`, `cortex_ops_cli/`, `cortex_repomap/`, runtime profile templates, and core tests.
- Extension manifests live in `packs/`; this repo's pack validation suites live in `tests/packs/`.
- `eval/` is internal and historical validation only. It is not a downstream product interface or product design authority.
- `docs/archive/` and `_governance_archive/` are historical context, not active authority.

v0.1 remains kernel-first: one hardened kernel, one reference pack, and runtime adapters with capture-backed tests.
