Metadata-Version: 2.4
Name: aepkit
Version: 0.7.5
Summary: Mechanical support for the Auditor/Executor protocol: scaffold, lint, and negative-control the document set for a multi-phase, multi-agent execution.
Author-email: tBeltty <jhonatan@tbelt.online>
License-Expression: MIT
Project-URL: Homepage, https://github.com/tBeltty/auditor-executor-protocol
Project-URL: Repository, https://github.com/tBeltty/auditor-executor-protocol
Project-URL: Issues, https://github.com/tBeltty/auditor-executor-protocol/issues
Project-URL: Changelog, https://github.com/tBeltty/auditor-executor-protocol/blob/main/CHANGELOG.md
Keywords: audit,executor,ai-agents,llm-protocols,quality-assurance,verification,compliance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff==0.17.3; extra == "dev"
Requires-Dist: mypy==2.4.1; extra == "dev"
Requires-Dist: build==1.6.1; extra == "dev"
Requires-Dist: twine==7.0.0; extra == "dev"
Dynamic: license-file

# Auditor/Executor Protocol

[![CI](https://github.com/tBeltty/auditor-executor-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/tBeltty/auditor-executor-protocol/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/aepkit)](https://pypi.org/project/aepkit/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23633244.svg)](https://doi.org/10.5281/zenodo.23633244)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://github.com/tBeltty/auditor-executor-protocol/blob/main/pyproject.toml)

A two-role protocol for running multi-phase work through AI agents without the plan drifting into open-ended discussion and without "all tests pass" masquerading as verification.

The **Auditor** defines what "done" means and proves it independently. The **Executor** implements one numbered task at a time and logs command output. Neither role crosses into the other.

[`SKILL.md`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/SKILL.md) specifies the protocol core; [`references/`](https://github.com/tBeltty/auditor-executor-protocol/tree/main/references) holds the parts an agent loads only when it reaches that step (task and gate writing, handoff templates, Autonomous mode, failure modes and a worked example). `aepkit` is a zero-dependency Python CLI that automates scaffolding, drift linting, negative controls, status tallies, and installing the skill into your agent. On Claude Code, the optional [`aeprogress`](#6-optional-the-claude-code-plugin) mod shows a run's progress beside the chat, holds back Executor launches when the machine is busy, and compacts the Auditor's session when a phase closes.

---

## When to Reach for This

Prompting an agent, scanning a diff, and shipping when it looks right works well for exploratory scripts and prototypes.

That approach fails when late mistakes carry real costs:
* Financial calculations and balance transfers
* Authorization, tenant isolation, and permission boundaries
* Destructive database schema migrations
* Automated background workers that run without human supervision

In these environments, plausible diffs are not evidence. Two failure modes break multi-session work:

1. **Silent Plan Drift:** Implementing agents quietly resolve ambiguities with assumptions instead of stopping to ask.
2. **Superficial Verification:** Reports like "reviewed and looks correct" mask unexecuted checks. Suites stay green because test fixtures bypass the assertion, not because the boundary holds.

The Auditor/Executor Protocol prevents both using a strict four-document paper trail and mandatory negative controls: a security check is not verified until you watch it fail with the protection removed.

---

## The Two Roles

| Role | Owns | Never | Output |
|---|---|---|---|
| **Auditor** | Instructions, gates, verdicts | Writes feature code | Task expansions, verdicts, remediation orders |
| **Executor** | Implementation, terminal evidence | Redesigns architecture, expands scope | Working code, unedited terminal output |

The Auditor never takes the Executor's word for a result: it re-runs every verify command and gate itself before giving a verdict. That is what stops a pasted "tested and working" from closing a task.

One person can run this workflow alone by switching hats between two isolated agent sessions. Keep them isolated, so the Auditor is never checking its own work.

The owner picks one of two modes at the start of a run. In **Guided** mode the owner pastes each handoff into a fresh Executor session and sees every verdict. In **Autonomous** mode the Auditor launches Executors as subagents with an explicit model per task, answers their `BLOCKED` questions with a decision entry in the log, and reports once per closed phase, interrupting the owner only for a numbered critical-risk list ([`references/autonomous-mode.md`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/references/autonomous-mode.md)).

---

## The Four-Document Paper Trail

`aepkit init` generates the first three documents and an empty `annexes/` directory for the fourth. Keeping them separate prevents instructions from turning back into a discussion:

1. **Plan of Record (`plan-of-record.md`):** Explains the *what* and the *why*. Opportunity framing (target outcome, problem/friction, cost of doing nothing), set-based shaping (three evaluated options or an explicit `N/A (Deterministic Fix/Compliance)` bypass), riskiest-assumption prioritization for the first phase, architecture decisions, explicit non-goals, phase roadmaps, and the deferred items ledger. Nobody implements directly from this file.
2. **Execution Guide (`execution-guide.md`):** Explains the *how*. Numbered tasks (`P0-T1`) with target files, steps, literal verify commands, and phase gates (`P0-G1`).
3. **Compliance Log (`compliance-log.md`):** Records evidence. Holds a status board and one report entry per task and gate ID; the template starts with `P0-T1` and `P0-G1`, and you add an entry for each task you write. The Executor pastes verbatim command output here.
4. **Remediation Annexes (`annexes/`):** When an audit yields `CONDITIONAL` or `REJECTED`, the Auditor issues a standalone annex instead of editing tasks in flight. Rapid annex growth signals an under-planned phase.

---

## Quickstart

### 1. Install `aepkit`

Requires Python 3.11+ with zero third-party dependencies:

```bash
pipx install aepkit
```

To run the latest `main` instead, use `pipx install git+https://github.com/tBeltty/auditor-executor-protocol`.

Or from a clone, for development:

```bash
git clone https://github.com/tBeltty/auditor-executor-protocol.git
cd auditor-executor-protocol
pip install -e .
```

### 2. Install the Protocol into Your Agent

Provision `SKILL.md` and its `references/` directory into your workspace or global environment. Cursor rules hold a single file, so Cursor receives one bundled `.mdc` with the references appended:

```bash
aepkit install-skill                     # auto-detects Antigravity, Claude Code, or Cursor
aepkit install-skill --agent antigravity # writes to .agents/skills/auditor-executor-protocol/
aepkit install-skill --agent claude      # writes to .claude/skills/auditor-executor-protocol/
aepkit install-skill --agent cursor      # writes to .cursor/rules/auditor-executor-protocol.mdc
aepkit install-skill --global            # user-level install (Antigravity unless --agent is given)
aepkit install-skill --dest <path>       # explicit destination; a non-SKILL.md file name gets one bundled file
```

Auto-detection checks the target directory for `.agents/` or `.gemini/`, `.claude/`, and `.cursor/`, then agent environment variables, and falls back to Antigravity. With `--global`, the skill goes to `~/.gemini/config/skills/`, `~/.claude/skills/`, or `~/.cursor/rules/`. An existing install is skipped unless you pass `--force`.

On Claude Code you can install the plugin in [section 6](#6-optional-the-claude-code-plugin) instead: it brings the same skill and the `aeprogress` pane.

### 3. Scaffold a Phased Project

```bash
aepkit init docs/<task-name> --name "<Task Name>"
```

Creates `plan-of-record.md`, `execution-guide.md`, `compliance-log.md`, and `annexes/`. `--name` defaults to the directory name; existing documents are kept unless you pass `--force`.

### 4. Track Status and Lint Drift

Inspect open tasks and tallied verdicts:

```bash
aepkit status docs/<task-name>
```

`aepkit status --json docs/<task-name>` prints the same reading as JSON, with each ID's phase, effective state and executor, and the phases with their titles from `execution-guide.md` (and weights from an optional `Weight` column in the plan's phase table), for scripts and tools to use instead of parsing the log.

Cross-check document consistency:

```bash
aepkit lint docs/<task-name>
```

`aepkit lint` catches an empty guide, tasks without a report line, missing report entries, log entries with no matching task, `DONE` reports whose verify output is not pasted in a code block, gates without a stated negative control (hypothetical or waived ones do not count), work reported in a phase before every earlier phase is `APPROVED`, unfilled opportunity/shaping/non-goal fields in `plan-of-record.md` once work is reported `DONE` or audited, open rows in the deferred items ledger for a phase being closed, duplicated log paragraphs, and annex buildup past `--annex-threshold` (default 6 in total, with a per-phase breakdown). It checks that evidence is present and in the right form, not that it is genuine; the Auditor's re-run does that.

### 5. Run a Negative Control

When validating an authorization, tenant, or schema boundary:

```bash
aepkit negcontrol \
  --file server/middleware/auth.js \
  --break-cmd "sed -i '' 's/requireAuth/\/\/requireAuth/' server/middleware/auth.js" \
  --test-cmd "npm test -- auth.test.js" \
  --expect "401|Unauthorized"
```

The `sed -i ''` form above is BSD/macOS sed; on GNU/Linux use `sed -i 's/.../.../' file`.

`negcontrol` backs up the target file, applies the break mutation, confirms the test fails, restores the file with byte-level verification, confirms the test passes, and outputs a transcript ready for `compliance-log.md`. Without `--file`, pass `--restore-cmd` to undo the break yourself; with both, the backup still wins if the file is not byte-identical afterwards. `--file` needs `--break-cmd`, because the backup must be taken before the break. `--timeout` limits each command in seconds, and a test that times out instead of failing fails the control: a hang is not a caught break.

A failure only proves something if it is the failure you meant. A syntax error, a missing import or a mistyped test command also makes the test exit non-zero. `--expect` takes a regular expression that the failing run's output must match, and the control fails if it does not. Without `--expect`, output that looks like a syntax, import, collection or command-not-found error is flagged with a `WARNING` next to the `OK`, and you need to read the transcript to confirm the reason.

### 6. Optional: the Claude Code plugin

On Claude Code, one plugin, `auditor-executor-protocol`, brings the protocol as a skill (the same `SKILL.md` and `references/` that `aepkit install-skill --agent claude` installs) together with `aeprogress`, a mod for runs where the Auditor launches Executors as subagents or as workers of a harness such as Orca. The protocol does not depend on the mod. The mod reads a run made with the protocol, only through `aepkit status --json`, so it needs `aepkit` and a run (sections 1 and 3); without one it shows nothing.

<img src="https://raw.githubusercontent.com/tBeltty/auditor-executor-protocol/main/integrations/claude-code/aeprogress/assets/pane.png" alt="The aeprogress pane: 43.3% overall, a bar per phase, the active phase P2 open with its task chips, P2-T3 in progress on a subagent, P2-T4 awaiting audit and P2-T2 conditional" width="420">

The mod does three things:

1. **A pane beside the chat** with the overall percentage, one bar per phase (weighted by an optional `Weight` column in the plan), who is working on which task ID (Claude Code subagents, Orca workers, or any harness through a command of your own), what awaits audit, what needs attention, and the machine's load. It refreshes after each turn, and every 20 seconds while it is open.
2. **A launch limit.** While a run is found, it refuses to launch another Executor past 2 live workers, 1 building worker, or a machine more than 75% busy for a build, and the refusal says which limit was hit. A handoff that builds nothing carries the line `Load: docs-only` ([`references/handoffs.md`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/references/handoffs.md)) and only answers to the worker count. On macOS it also recommends excluding the project from Spotlight when indexing keeps the machine busy.

   <img src="https://raw.githubusercontent.com/tBeltty/auditor-executor-protocol/main/integrations/claude-code/aeprogress/assets/launch-limit.png" alt="A second building Executor refused: 1 building worker is live (limit 1)">

3. **Compaction when a phase closes.** In Autonomous mode, once a gate is `APPROVED` and the Auditor brief is up to date on disk, the Auditor calls the mod's `compact_and_resume` tool. After its turn, a 40-second countdown lets you cancel; then the session is compacted and the Auditor resumes from its own message. Typing a prompt, pressing Esc or running `/compact` yourself takes over.

   <img src="https://raw.githubusercontent.com/tBeltty/auditor-executor-protocol/main/integrations/claude-code/aeprogress/assets/compact-countdown.png" alt="The countdown band: Compacting in 33s, with Cancel and Compact now">

Install the plugin at the prompt of a Claude Code terminal session, then open the pane on a run:

```
/plugin install auditor-executor-protocol --marketplace tBeltty/auditor-executor-protocol
/aeprogress docs/<task-name>
```

It works in the terminal and in the desktop app's local sessions (in the app: **+** next to the prompt, **Plugins**, **Add marketplace**). Every limit and feature is an option in `/config`. It needs Claude Code 2.1.287 or later and sends no data about you anywhere (its one network request, a daily version check, can be turned off); its README lists every process it starts and everything it can refuse. To get new versions on their own, turn on auto-update once: `/plugin`, **Marketplaces**, `auditor-executor-protocol`, **Enable auto-update**. Setup, options and how each number is computed: [integrations/claude-code/aeprogress](https://github.com/tBeltty/auditor-executor-protocol/tree/main/integrations/claude-code/aeprogress).

---

## CLI Reference

| Command | Options | Description |
|---|---|---|
| `aepkit init <dir>` | `--name`, `--force` | Scaffold the three documents and `annexes/` from templates |
| `aepkit install-skill [dir]` | `--agent`, `--global`, `--dest`, `--force` | Provision `SKILL.md` and `references/` into Antigravity, Claude Code, or Cursor |
| `aepkit lint <dir>` | `--annex-threshold` | Cross-check IDs both ways, flag `DONE` without evidence, detect missing negative controls, and flag log rot |
| `aepkit negcontrol` | `--test-cmd` (required), `--file`, `--break-cmd`, `--restore-cmd`, `--expect`, `--timeout` | Run automated backup, break, fail, restore, and pass cycle |
| `aepkit status <dir>` | `--json` | Combine status board verdicts with reports; list everything not `APPROVED` |

`python -m aepkit` works the same as `aepkit`. Errors go to stderr.

Exit codes: `lint` and `negcontrol` return `0` when clean, `1` when they find a problem, and `2` on a usage error or missing document, so both can gate CI. `status` is informational and returns `0` whenever the compliance log exists.

`aepkit` reads and writes local Markdown files only: no external databases, daemons, or network calls. `negcontrol` runs the shell commands you pass it.

---

## Running Tests

Run the test suite using the standard library runner:

```bash
python3 tests/run.py
```

Or run with `pytest` by installing test extras:

```bash
pip install -e ".[test]"
pytest
```

---

## Contributing

Contributions are welcome. [`CONTRIBUTING.md`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/CONTRIBUTING.md) covers the development setup, the quality gates, and the PR checklist; participation follows the [`CODE_OF_CONDUCT.md`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/CODE_OF_CONDUCT.md). Report vulnerabilities privately as described in [`SECURITY.md`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/SECURITY.md). Changes are listed in [`CHANGELOG.md`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/CHANGELOG.md).

## License

MIT (see [`LICENSE`](https://github.com/tBeltty/auditor-executor-protocol/blob/main/LICENSE)).

---

Made with ♥️ by [tBelt](https://github.com/tBeltty).
