Metadata-Version: 2.4
Name: cortex-loop
Version: 0.1.0a2
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 (native) | `cortex runtime install --profile openai` | Experimental | Honest native App Server surface: one turn, then stop audit. Several critical paths are proven, but positive strict close is still not dependable enough for broader support. |
| OpenAI Codex App Server (assisted) | `cortex runtime install --profile openai-assisted` | Experimental | Explicit bounded assisted mode with a current committed shared-harness pair: Cortex provides session-start context with a short kernel-owned completion preview, one short evidence-expectation line, and one kernel-derived corrective turn. The lane remains supplemental-only, not native-substitutive proof. |

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).

Current product-proof truth: Cortex is strong on truthful completion boundaries,
but the repo still does not earn a net-positive product claim over the raw
model. Phase 9 is landed at a truthful-withheld endpoint rather than an earned
product-proof win.

This repo state is also the final archival v1 reference point for the
enforcement-layer line. The archival package target is `cortex-loop 0.1.0a2`.

## Quickstart

Default public install:

```bash
pipx install cortex-loop
cortex init
cortex runtime install --profile claude
```

Supported advanced alternative:

```bash
uv tool install cortex-loop
```

Before `cortex check`, choose the baseline that matches the repository or the
machine you are using:

- trusted local repo without Docker: add `pytest` to the promoted tool surface
  (`pipx inject cortex-loop pytest` or `uv tool install --with pytest
  cortex-loop`) and 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
```

Install, update, uninstall, and live proof details live in
[docs/INSTALL.md](docs/INSTALL.md).
Guided evaluator onboarding lives in
[docs/ALPHA_TESTER_ONBOARDING.md](docs/ALPHA_TESTER_ONBOARDING.md).
Trust boundary and pack review posture live in
[docs/TRUST_BOUNDARY.md](docs/TRUST_BOUNDARY.md) and
[docs/PACK_POLICY.md](docs/PACK_POLICY.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 native surface. Use `openai-assisted` when you want the current
bounded assisted OpenAI lane: session-start context with a short kernel-owned
completion preview, one short evidence-expectation line, one kernel-derived
corrective turn aimed at the unresolved completion gap, and a current
shared-harness pair that still remains supplemental-only.

## 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.
