aepkit 0.6.0__tar.gz

aepkit-0.6.0/CHANGELOG.md

@@ -0,0 +1,286 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.6.0] - 2026-10-24
+
+### Added
+- `plan-of-record.md` template and `SKILL.md`: Opportunity & Shaping gate (`Target outcome`,
+  `Problem / friction`, `Cost of doing nothing`, three-option set-based comparison with
+  `Selected option & rationale`, `Riskiest assumption & first-phase validation`, `Explicit
+  non-goals`, and the `Deferred items ledger` table), plus a fast-track bypass
+  (`N/A (Deterministic Fix/Compliance)`) for bugfixes, security patches, migrations, and
+  strict compliance work.
+- `aepkit lint` flags `[unfilled plan]` when `plan-of-record.md` is present and work has
+  been reported `DONE` or given a verdict while required opportunity, shaping, riskiest-assumption,
+  or non-goal fields remain empty, deferred, or placeholders (unless the shaping/assumption
+  fields declare `N/A (Deterministic Fix/Compliance)`).
+- `aepkit lint` flags `[open deferred item]` when a row in the deferred items ledger of
+  `plan-of-record.md` references a closing task ID that does not exist in `execution-guide.md`
+  or remains open when its target phase is being closed.
+
+### Changed
+- **Breaking:** Renamed the PyPI distribution, Python package, and CLI binary to `aepkit`
+  (`pipx install aepkit`, `aepkit`, `python -m aepkit`) to eliminate naming collisions with
+  external `auditkit` packages and binaries.
+
+## [0.5.0] - 2026-10-02
+
+### Added
+- `auditkit negcontrol --expect REGEX`: the failing run's output must match the expression, so
+  a test that fails for an unrelated reason (a syntax error, a missing import, a mistyped
+  command) fails the control instead of passing it.
+- Without `--expect`, `negcontrol` adds a `WARNING` to its verdict when the failing output looks
+  like a syntax, import, collection, timeout or command-not-found error, rather than the
+  protection being caught.
+
+### Changed
+- **Breaking (Python API only):** `auditkit.negcontrol.run()` takes every argument after
+  `test_cmd` by keyword. The `auditkit negcontrol` command is unchanged.
+
+## [0.4.0] - 2026-10-01
+
+### Added
+- `python -m auditkit` runs the CLI.
+- A release workflow publishes to PyPI through trusted publishing when a `v*` tag is pushed,
+  then creates the GitHub release from this changelog.
+- `CODE_OF_CONDUCT.md`, and an issue chooser that routes vulnerability reports to private
+  disclosure.
+- `auditkit lint` flags `[phase order]`: work reported in a phase before every earlier phase is
+  `APPROVED`.
+- Tests that check the README's CLI reference, exit codes, `install-skill` destinations,
+  `negcontrol` behavior, and its promises: unevidenced `DONE`, waived controls, unplanned
+  reports, and tests that cannot fail are caught.
+
+### Changed
+- The distribution is named `auditor-executor-protocol`, because `auditkit` on PyPI belongs to
+  an unrelated project. The command and the import package are still `auditkit`. The README
+  installs it from PyPI.
+- **Breaking:** `auditkit lint` counts verify output only inside a fenced code block, so prose
+  such as "all tests pass" or "looks correct" is reported as `DONE` without evidence. Logs that
+  pasted output without a fence fail until it is wrapped in a ``` block; the lint message says
+  how.
+- `auditkit lint` rejects hypothetical negative controls ("could", "should", "may") and ones
+  whose action removes nothing.
+- README states that the Auditor re-runs every check in its own session and that `lint` checks
+  the form of evidence, not whether it is genuine.
+- Errors and warnings go to stderr; stdout carries only results and transcripts.
+- Every `auditkit` option has help text. Each subcommand module no longer carries its own copy
+  of the argument parser, so `auditkit <command> --help` is the single, complete reference.
+- Dependabot only raises a pip minimum when it no longer admits the latest release.
+- CI pins every action to a commit SHA, cancels superseded runs, and checks the built
+  distributions with `twine check --strict`.
+- Package metadata lists supported Python versions, `Development Status`, and `Typing :: Typed`;
+  the version is defined once, in `auditkit.__version__`.
+- `.gitignore` covers common virtualenv, coverage, tox/nox, and editor files; the PR template
+  matches the CONTRIBUTING checklist.
+
+### Removed
+- Python 3.9 and 3.10 support (end of life in October 2025 and October 2026). `auditkit` now
+  requires Python 3.11+.
+
+### Fixed
+- `AGENTS.md` imported itself and said nothing, because `GEMINI.md` was a symlink to it. It is
+  now a short, generic agent guide that points to `CONTRIBUTING.md`; tool-specific instruction
+  files (`CLAUDE.md`, `GEMINI.md`) are no longer tracked.
+- README: the compliance log template, `install-skill` detection and `--global`/`--dest`, every
+  command's options, exit codes, and the BSD-only `sed -i ''` in the `negcontrol` example now match
+  the CLI.
+
+## [0.3.9] - 2026-09-26
+
+### Fixed
+- `auditkit lint` accepted hypothetical, waived, and action-negated negative controls.
+- `auditkit lint` rejected some valid negative controls.
+
+## [0.3.8] - 2026-09-26
+
+### Changed
+- `auditkit lint` recognizes a stated negative control by what it says, not by a list of
+  excuses to reject: it must name the action that removes the protection (or feeds the input it
+  must stop) and the failure that follows, with no deferral and no negated failure. Waivers and
+  refusals in any wording ("waived by the tech lead", "out of scope", "does not apply") no longer
+  pass.
+
+## [0.3.7] - 2026-09-26
+
+### Fixed
+- `auditkit lint` accepted refusals written as the negative control ("No control; ...",
+  "deliberately omitted", "could not break it", "nothing to show").
+
+## [0.3.6] - 2026-09-25
+
+### Fixed
+- `auditkit lint` accepted passive or scheduled deferrals as a negative control ("will be added
+  in P1", "TBC", "to follow", "coming soon", "planned for the next release").
+
+## [0.3.5] - 2026-09-25
+
+### Fixed
+- `auditkit lint` accepted a negative control that only deferred or pointed elsewhere
+  ("will add later", "TBA", "see above"). A stated control now needs at least a short sentence
+  (four words) with no deferral in it.
+
+## [0.3.4] - 2026-09-25
+
+### Fixed
+- `auditkit lint` accepted deferred controls written in the plural ("Negative controls: none").
+- The scaffolded gate stated a generic negative control ("A negative control — remove the
+  protection, ..."), so a gate reported `DONE` without ever writing one passed lint. The
+  template now has a `**Negative control:**` placeholder, and a gate still exactly as scaffolded
+  is skipped only until it is reported `DONE`.
+
+## [0.3.3] - 2026-09-25
+
+### Fixed
+- `auditkit lint` counted any mention of "negative control" as a stated one, so an empty label
+  (`**Negative control:**`), a dash, a template placeholder, "to be written", or "N.A." passed.
+  A mention now needs text after it (on the same line or the next ones) that is not a
+  placeholder, punctuation, or a deferral.
+- `auditkit lint` accepted `DONE` reports whose verify output was only punctuation ("-", "…") or
+  "None yet".
+
+## [0.3.2] - 2026-09-25
+
+Fixes from a second independent review.
+
+### Fixed
+- `auditkit lint` accepted a deferred negative control written as a bold field
+  (`**Negative control:** n/a`, `**Negative control**: none`); only up to three punctuation
+  characters were allowed between the label and the deferral.
+- `auditkit lint` counted a `DONE` report whose verify output was only a deferral ("n/a", "TBD",
+  "pending") as pasted output.
+- `auditkit negcontrol --timeout` killed only the shell; processes the command started kept
+  running and could change the file after the restore check. Each command now runs in its own
+  process group, which is killed as a whole on timeout.
+
+## [0.3.1] - 2026-09-25
+
+Fixes from an independent review of 0.3.0.
+
+### Fixed
+- `auditkit lint` reported "clean" for an execution guide with no tasks, or with tasks that have no
+  `**Report:**` line, so empty documents passed. Both are now reported.
+- `auditkit lint` accepted deferred negative controls ("Negative control: TBD", "skipped",
+  "the negative control step was not done") as stated ones.
+- `auditkit negcontrol --file` crashed and deleted the backup when the break command deleted or
+  moved the file. The file is now recreated from the backup, and the backup is kept unless the
+  file is verified byte-identical.
+- `auditkit status` let a status board verdict silently override a later, different report-header
+  verdict. Such items are now listed as `CONFLICT` and stay open.
+- `auditkit install-skill --dest <directory>` skipped, crashed with `--force`, or wrote a file
+  named after the directory. A directory destination now receives `SKILL.md` and `references/`.
+- The sdist now includes `SKILL.md` and `references/`, so its own test suite passes.
+
+### Changed
+- `.gitattributes` normalizes line endings to LF, so checkouts on Windows match other platforms
+  byte for byte (the framework vendors `SKILL.md`, `references/`, and the templates).
+- Build requirement raised to `setuptools>=77`, which supports the SPDX `license` string.
+- `SKILL.md` states that lint checks that evidence is present, not that it is authentic.
+
+## [0.3.0] - 2026-09-25
+
+### Added
+- `auditkit lint` reports compliance-log entries with no matching task or gate in the
+  execution guide.
+- `auditkit negcontrol --timeout` bounds each command.
+- `auditkit lint` flags `DONE` reports in `compliance-log.md` whose `**Verify output:**`
+  field is missing, empty, or only a template placeholder. The protocol already records
+  these as `FAILED`; the check makes that mechanical.
+- README: install `auditkit` without cloning via `pipx install git+https://github.com/tBeltty/auditor-executor-protocol`.
+- Conventional Commits specification documented in `CONTRIBUTING.md` and enforced in `AGENTS.md`.
+- `SKILL.md`: optional Guided/Autonomous operating mode, with the autonomy charter, per-task
+  model-tier assignment, the per-task cycle, and an Auditor-brief template for starting an
+  autonomous run.
+- `SKILL.md`: a deferred items ledger in the plan of record and a reserved-to-Auditor steps
+  list in the execution guide, so cross-phase promises and recurring sandbox blocks are
+  tracked as structured document state instead of prose an Auditor has to remember.
+- `SKILL.md`: a `Blast radius` field on the task template covering both meaning-changing
+  edits to a shared field and steps that empty/delete/replace shared code a later task
+  still depends on.
+- `SKILL.md`: gate-writing rules for compound gates (re-run every check, never cite a
+  partial prior pass), realistic test fixtures (a minimal fixture shape hides bugs a
+  realistic one would catch), and channel-crossing checks (a restriction proven on one
+  transport/channel is not proven on all of them).
+- `SKILL.md`: a "Worked example" section showing a filled-in, fictional Autonomous-mode
+  run end to end.
+
+### Changed
+- `SKILL.md` split into a core file (24 KB, down from 47 KB) and four on-demand files in
+  `references/`: `tasks-and-gates.md`, `handoffs.md`, `autonomous-mode.md`, and
+  `failure-modes-and-example.md`. The core indexes each file with the step that needs it,
+  so an agent that triggers the skill loads about half the tokens it did before.
+- `auditkit install-skill` copies `references/` beside `SKILL.md`. Destinations that hold a
+  single file (Cursor `.mdc`, or a `--dest` not named `SKILL.md`) get one bundled file.
+- The packaged skill moved from `src/auditkit/templates/SKILL.md` to `src/auditkit/skill/`.
+- `GEMINI.md` imports `AGENTS.md` instead of duplicating it, so the agent rules have one
+  source of truth.
+- Bumped `actions/checkout` and `actions/setup-python` to v7 in GitHub Actions CI workflow.
+- Configured grouped updates in `.github/dependabot.yml` to bundle action and pip dependency bumps.
+
+### Fixed
+- `auditkit install-skill` shipped a stale 500-line copy of the protocol that predated the
+  Autonomous mode, deferred items ledger, and gate-writing rules. `tests/test_skill_sync.py`
+  now fails whenever the packaged copy differs from the repository root.
+- `auditkit lint` returned "clean" (exit 0) for a missing directory or missing documents.
+  It now exits 2 and names the missing file; linting nothing proves nothing.
+- `auditkit status` ignored the Verdict column of the status board and counted a `DONE`
+  self-report as closed, so a `REJECTED` task could appear closed. It now combines board
+  verdicts with the latest report per ID; only `APPROVED` closes an item and `DONE` without
+  a verdict is listed as awaiting audit.
+- `auditkit negcontrol --file ... --restore-cmd ...` deleted the backup even when the
+  restore command failed, leaving the file broken. With `--file`, the file must end
+  byte-identical to the backup or it is restored from it, and the backup is kept if that
+  still fails. The restore exit code is recorded.
+- `auditkit lint` accepted a negated mention ("negative control: n/a") as a stated negative
+  control.
+- CLI help: `init` described four documents (it writes three plus `annexes/`), and
+  `install-skill --dest` described a file path only.
+
+## [0.2.0] - 2026-09-19
+
+### Added
+- PEP 561 marker (`src/auditkit/py.typed`) for inline static typing support.
+- Complete test suite for `auditkit.cli` entry point (`tests/test_cli.py`).
+- 90%+ test coverage enforcement across the repository.
+- GitHub Actions CI workflow hardening: explicit token permissions, dedicated lint/format/typecheck job, package distribution verification, and weekly Dependabot configuration.
+- Open-source governance files: `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, PR and issue templates.
+- Agent rule specifications (`AGENTS.md`, `GEMINI.md`) establishing mandatory changelog updates and test verification gates on every task.
+
+### Changed
+- Conformed all Python code to Ruff formatting and PEP 8 import conventions.
+- Annotated all CLI runner entry points with strict parameter types (`argv: list[str] | None = None`).
+- Standardized `pyproject.toml` metadata (SPDX license expression, project URLs, and keywords).
+- Updated maintainer contact email to `jhonatan@tbelt.online` in `SECURITY.md` and `pyproject.toml`.
+
+### Fixed
+- Fixed cross-platform Windows newline and whitespace handling in negative control tests.
+
+## [0.1.0] - 2026-08-30
+
+### Added
+- Initial release of Auditor/Executor Protocol specification (`SKILL.md`).
+- `auditkit` CLI tool featuring `init`, `lint`, `negcontrol`, `status`, and `install-skill` subcommands.
+- 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.6.0...HEAD
+[0.6.0]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.9...v0.4.0
+[0.3.9]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.8...v0.3.9
+[0.3.8]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.7...v0.3.8
+[0.3.7]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.6...v0.3.7
+[0.3.6]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.5...v0.3.6
+[0.3.5]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.4...v0.3.5
+[0.3.4]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/tBeltty/auditor-executor-protocol/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/tBeltty/auditor-executor-protocol/releases/tag/v0.2.0

aepkit-0.6.0/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/MANIFEST.in

@@ -0,0 +1,6 @@
+# The sdist ships the canonical skill so tests/test_skill_sync.py can run from it.
+include SKILL.md
+recursive-include references *.md
+# README tells sdist users to run tests/run.py; setuptools only picks up test_*.py on its own.
+include tests/run.py
+include CHANGELOG.md

aepkit-0.6.0/PKG-INFO

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