PyPI - aepkit - Versions diffs - 0.7.1__tar.gz → 0.7.3__tar.gz - Mend

aepkit 0.7.1tar.gz → 0.7.3tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (45) hide show

{aepkit-0.7.1 → aepkit-0.7.3}/CHANGELOG.md RENAMED Viewed

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.7.3] - 2026-11-08
+No change to the package's code. This release puts the new README on PyPI: the protocol's
+Guided and Autonomous modes, the `aeprogress` section with screenshots, and the DOI badge.
+### Changed
+- CI runs `claude plugin validate` (the mod and the marketplace) and `claude plugin test` for
+  `aeprogress`, on Claude Code 2.1.319, the release the mod is tested against.
+- Dev dependencies: ruff 0.17.3, mypy 2.4.1; GitHub Actions bumped (Dependabot #20, #22).
+- `CITATION.cff` and the README carry the Zenodo concept DOI, 10.5281/zenodo.23633244, which
+  resolves to the latest archived release.
+- `aeprogress` 0.3.1: a worker's name in the pane no longer repeats the task ID it carries
+  (`P2-T3  Executor P2-T3` is now `P2-T3  Executor`), for subagents, Orca workers and lines
+  from a workers command. README screenshots of the pane, the launch limit and the
+  compaction countdown.
+## [0.7.2] - 2026-11-08
+### Added
+- `references/autonomous-mode.md`: an optional step at a phase's close. Once the gate is
+  `APPROVED`, the work is pushed and the Auditor brief is up to date, the Auditor may compact
+  its own session and resume itself from the brief.
+- `aeprogress` 0.3.0: a `compact_and_resume` tool for the Auditor. After its turn ends, a band
+  counts down 40 seconds with Cancel and Compact now; at zero the session is compacted and the
+  Auditor resumed with its own `resume` message. A prompt typed by the owner, Esc on the turn,
+  or Cancel drops it; a manual `/compact` during the countdown resumes once; a refused or vetoed
+  compaction resumes nothing. Options for the seconds and to turn it off.
 ## [0.7.1] - 2026-11-08
 ### Added
@@ -50,6 +78,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   that used it showed the task as awaiting audit in `aepkit status`. The four sentences
   now say `APPROVED`.
+## [0.6.1] - 2026-10-25
+### Added
+- `CITATION.cff`, so each GitHub release is archived on Zenodo with citation metadata. This
+  release is the first archived one (10.5281/zenodo.23633245). No code changes, and it was not
+  published to PyPI: the package still reported 0.6.0.
 ## [0.6.0] - 2026-10-24
 ### Added
@@ -334,9 +369,12 @@ Fixes from an independent review of 0.3.0.
 - Multi-framework agent installation support for Antigravity, Claude Code, and Cursor.
 - Zero-dependency test runner (`tests/run.py`).
-[Unreleased]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.7.3...HEAD
+[0.7.3]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.7.2...v0.7.3
+[0.7.2]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.6.0...v0.7.0
+[0.6.1]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.4.0...v0.5.0

{aepkit-0.7.1/src/aepkit.egg-info → aepkit-0.7.3}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aepkit
-Version: 0.7.1
+Version: 0.7.3
 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
@@ -30,8 +30,8 @@ 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.16.10; extra == "dev"
-Requires-Dist: mypy==2.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
@@ -44,13 +44,14 @@ Dynamic: license-file
 [![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.
+[`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-aeprogress-for-claude-code) 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.
 ---
@@ -84,6 +85,8 @@ The Auditor never takes the Executor's word for a result: it re-runs every verif
 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
@@ -176,16 +179,31 @@ The `sed -i ''` form above is BSD/macOS sed; on GNU/Linux use `sed -i 's/.../...
 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.
-### Optional: Progress Pane for Claude Code
+### 6. Optional: `aeprogress` for Claude Code
+`aeprogress` is a Claude Code 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 it, and it reads the run only through `aepkit status --json`.
+<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, P2-T3 in progress on a subagent, P2-T4 awaiting audit, P2-T2 conditional, and the machine at 31% with 1 of 2 workers live" width="420">
+It 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">
-`aeprogress` is a Claude Code mod that keeps a pane beside the chat with the run's overall percentage, a bar per phase, who is working on which task ID (Claude Code subagents, Orca workers, or any other harness through a command of your own), what awaits audit, what needs attention, and the machine's load. It reads the log through `aepkit status --json` and refreshes after each turn, and every 20 seconds while the pane is open. While a run is found it also holds back launching another Executor past a worker count or a machine load (2 workers, 1 building, 75% busy by default; a handoff marked `Load: docs-only` does not count as a build), and on macOS it recommends excluding the project from Spotlight when indexing keeps the machine busy. The protocol does not depend on it.
+Install it at the prompt of a Claude Code terminal session, then open it:
 ```
 /plugin install aeprogress --marketplace tBeltty/auditor-executor-protocol
 /aeprogress docs/<task-name>
 ```
-It works in the terminal and in the desktop app's local sessions. Claude Code's mod API is early access, so a Claude Code release can break it. Setup, options and how the percentage is computed: [integrations/claude-code/aeprogress](https://github.com/tBeltty/auditor-executor-protocol/tree/main/integrations/claude-code/aeprogress).
+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`. Claude Code marks its mod API as early access, so a Claude Code release can break it. 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).
 ---

{aepkit-0.7.1 → aepkit-0.7.3}/README.md RENAMED Viewed

@@ -6,13 +6,14 @@
 [![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.
+[`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-aeprogress-for-claude-code) 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.
 ---
@@ -46,6 +47,8 @@ The Auditor never takes the Executor's word for a result: it re-runs every verif
 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
@@ -138,16 +141,31 @@ The `sed -i ''` form above is BSD/macOS sed; on GNU/Linux use `sed -i 's/.../...
 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.
-### Optional: Progress Pane for Claude Code
+### 6. Optional: `aeprogress` for Claude Code
+`aeprogress` is a Claude Code 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 it, and it reads the run only through `aepkit status --json`.
+<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, P2-T3 in progress on a subagent, P2-T4 awaiting audit, P2-T2 conditional, and the machine at 31% with 1 of 2 workers live" width="420">
+It 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">
-`aeprogress` is a Claude Code mod that keeps a pane beside the chat with the run's overall percentage, a bar per phase, who is working on which task ID (Claude Code subagents, Orca workers, or any other harness through a command of your own), what awaits audit, what needs attention, and the machine's load. It reads the log through `aepkit status --json` and refreshes after each turn, and every 20 seconds while the pane is open. While a run is found it also holds back launching another Executor past a worker count or a machine load (2 workers, 1 building, 75% busy by default; a handoff marked `Load: docs-only` does not count as a build), and on macOS it recommends excluding the project from Spotlight when indexing keeps the machine busy. The protocol does not depend on it.
+Install it at the prompt of a Claude Code terminal session, then open it:
 ```
 /plugin install aeprogress --marketplace tBeltty/auditor-executor-protocol
 /aeprogress docs/<task-name>
 ```
-It works in the terminal and in the desktop app's local sessions. Claude Code's mod API is early access, so a Claude Code release can break it. Setup, options and how the percentage is computed: [integrations/claude-code/aeprogress](https://github.com/tBeltty/auditor-executor-protocol/tree/main/integrations/claude-code/aeprogress).
+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`. Claude Code marks its mod API as early access, so a Claude Code release can break it. 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).
 ---

{aepkit-0.7.1 → aepkit-0.7.3}/pyproject.toml RENAMED Viewed

@@ -50,8 +50,8 @@ test = [
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
-    "ruff==0.16.10",
-    "mypy==2.4.0",
+    "ruff==0.17.3",
+    "mypy==2.4.1",
     "build==1.6.1",
     "twine==7.0.0",
 ]

{aepkit-0.7.1 → aepkit-0.7.3}/references/autonomous-mode.md RENAMED Viewed

@@ -94,6 +94,12 @@ each handoff. The shape that has worked here:
    yet expanded, expand it (tasks, gate, model per task, log sections) before launching
    its first task.
+Optional, at a phase's close: once the gate is `APPROVED`, the work is pushed and the
+Auditor brief is up to date on disk, the Auditor may compact its own session and resume
+itself from the brief, so a long run does not carry every earlier phase in its context.
+On Claude Code the optional `aeprogress` mod offers this as a tool that waits out a short
+countdown the owner can cancel. The protocol does not depend on it.
 Do not end a turn between a verdict and the next launch unless something on the
 critical-risk list is open. A run that stops to report an `APPROVED` and wait is Guided
 mode by accident.

aepkit-0.7.3/src/aepkit/__init__.py ADDED Viewed

	@@ -0,0 +1 @@
1	+ __version__ = "0.7.3"

{aepkit-0.7.1 → aepkit-0.7.3}/src/aepkit/skill/references/autonomous-mode.md RENAMED Viewed

@@ -94,6 +94,12 @@ each handoff. The shape that has worked here:
    yet expanded, expand it (tasks, gate, model per task, log sections) before launching
    its first task.
+Optional, at a phase's close: once the gate is `APPROVED`, the work is pushed and the
+Auditor brief is up to date on disk, the Auditor may compact its own session and resume
+itself from the brief, so a long run does not carry every earlier phase in its context.
+On Claude Code the optional `aeprogress` mod offers this as a tool that waits out a short
+countdown the owner can cancel. The protocol does not depend on it.
 Do not end a turn between a verdict and the next launch unless something on the
 critical-risk list is open. A run that stops to report an `APPROVED` and wait is Guided
 mode by accident.

{aepkit-0.7.1 → aepkit-0.7.3/src/aepkit.egg-info}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aepkit
-Version: 0.7.1
+Version: 0.7.3
 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
@@ -30,8 +30,8 @@ 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.16.10; extra == "dev"
-Requires-Dist: mypy==2.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
@@ -44,13 +44,14 @@ Dynamic: license-file
 [![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.
+[`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-aeprogress-for-claude-code) 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.
 ---
@@ -84,6 +85,8 @@ The Auditor never takes the Executor's word for a result: it re-runs every verif
 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
@@ -176,16 +179,31 @@ The `sed -i ''` form above is BSD/macOS sed; on GNU/Linux use `sed -i 's/.../...
 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.
-### Optional: Progress Pane for Claude Code
+### 6. Optional: `aeprogress` for Claude Code
+`aeprogress` is a Claude Code 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 it, and it reads the run only through `aepkit status --json`.
+<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, P2-T3 in progress on a subagent, P2-T4 awaiting audit, P2-T2 conditional, and the machine at 31% with 1 of 2 workers live" width="420">
+It 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">
-`aeprogress` is a Claude Code mod that keeps a pane beside the chat with the run's overall percentage, a bar per phase, who is working on which task ID (Claude Code subagents, Orca workers, or any other harness through a command of your own), what awaits audit, what needs attention, and the machine's load. It reads the log through `aepkit status --json` and refreshes after each turn, and every 20 seconds while the pane is open. While a run is found it also holds back launching another Executor past a worker count or a machine load (2 workers, 1 building, 75% busy by default; a handoff marked `Load: docs-only` does not count as a build), and on macOS it recommends excluding the project from Spotlight when indexing keeps the machine busy. The protocol does not depend on it.
+Install it at the prompt of a Claude Code terminal session, then open it:
 ```
 /plugin install aeprogress --marketplace tBeltty/auditor-executor-protocol
 /aeprogress docs/<task-name>
 ```
-It works in the terminal and in the desktop app's local sessions. Claude Code's mod API is early access, so a Claude Code release can break it. Setup, options and how the percentage is computed: [integrations/claude-code/aeprogress](https://github.com/tBeltty/auditor-executor-protocol/tree/main/integrations/claude-code/aeprogress).
+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`. Claude Code marks its mod API as early access, so a Claude Code release can break it. 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).
 ---