aepkit 0.6.0__py3-none-any.whl

aepkit-0.6.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: aepkit
+Version: 0.6.0
+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.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=1.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/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](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`](SKILL.md) specifies the protocol core; [`references/`](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.
+
+---
+
+## 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 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`.
+
+### 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>
+```
+
+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, overall or per phase). 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. `--timeout` limits each command in seconds.
+
+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, timeout 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.
+
+---
+
+## 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>` | | 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`](CONTRIBUTING.md) covers the development setup, the quality gates, and the PR checklist; participation follows the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Report vulnerabilities privately as described in [`SECURITY.md`](SECURITY.md). Changes are listed in [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+MIT (see [`LICENSE`](LICENSE)).
+
+---
+
+Made with ♥️ by [tBelt](https://github.com/tBeltty).

aepkit-0.6.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+aepkit/__init__.py,sha256=cID1jLnC_vj48GgMN6Yb1FA3JsQ95zNmCHmRYE8TFhY,22
+aepkit/__main__.py,sha256=_wq3Lf03Y14NLlgHiwKqQb0v2VypXPnzCewUSKl04QI,87
+aepkit/cli.py,sha256=84_KSQm-acfNjKbaU7keIevthzHbCHjR5lTVzyKMD9M,5032
+aepkit/install_skill.py,sha256=LKXqWvH00SgJR3BRm0amwpa32XtrUvIm3_sfX_GjDUM,4216
+aepkit/lint.py,sha256=BYvjfDvXYEHniNqFfeDwd9hT1OrJc2hHjUsRzyrblDM,24500
+aepkit/negcontrol.py,sha256=v42L3k0vXLFdNDL-6vnPr54yHSuBVUWNkJXcwKaOXsI,9035
+aepkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aepkit/scaffold.py,sha256=T_P8OcHvAdfNZgVjSxP_ogQKJjTIQFLysPKCGxqIhYY,1287
+aepkit/status.py,sha256=gum6hmQjm_y7wfa2Ir1t5jmgFEiiYuq_zA-NCkeSC90,4421
+aepkit/skill/SKILL.md,sha256=Sv5Uy1l0oLuEZ3qOmgLNeW7IqDCly46IIP8KozZJ5Ps,28230
+aepkit/skill/references/autonomous-mode.md,sha256=4KxUoLmJVeJ800eJaoX95AC2l24Co_bwan9I9dFEE3o,8007
+aepkit/skill/references/failure-modes-and-example.md,sha256=iK2jYDjBdaJ8E-HDIKrCFAiTgMRAZVwH5NUowVg68s8,5608
+aepkit/skill/references/handoffs.md,sha256=vMokSiRXhsf_we9Dotb1jtLghr5LRolY4AMesJff_ek,6611
+aepkit/skill/references/tasks-and-gates.md,sha256=3ViWt6BPxdtCD2tPapJMOmgl0WtEqUpxyQSwGUSqIpk,5199
+aepkit/templates/compliance-log.md,sha256=xTmvSAjb-_S6ZBNb_JjtlNHiV28-JusEj_8hfQ-KfrQ,730
+aepkit/templates/execution-guide.md,sha256=njGvCRDLMtVu71dmtjksNtzSmh-82jKzHXDEkJ8-fxk,2323
+aepkit/templates/plan-of-record.md,sha256=vR7A7rS0yUhTtSg7DBTSCYmhCEPux3a-a0LPTsJheV4,3278
+aepkit-0.6.0.dist-info/licenses/LICENSE,sha256=502xuJPh3Afdx3kE4pZcYLAO59VoDcrbx_Vv2pTWtR0,1064
+aepkit-0.6.0.dist-info/METADATA,sha256=c8vUYyHuDP9vZIKFobzBz41FEDqN4ZlknX91jVJzy6c,12419
+aepkit-0.6.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+aepkit-0.6.0.dist-info/entry_points.txt,sha256=DtXHN4n3ecUvpQ9UnwAh--mca5LO2z8heoFMaY-GG0c,43
+aepkit-0.6.0.dist-info/top_level.txt,sha256=ZFYVzwFoP9sxxSOCyuGrF5xh78aO1l17MlDKqe1o8OE,7
+aepkit-0.6.0.dist-info/RECORD,,

aepkit-0.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aepkit-0.6.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aepkit = aepkit.cli:main

aepkit-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tBeltty
+
+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.

aepkit-0.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aepkit