plan-auditor 2.0.1__tar.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.

Potentially problematic release.

This version of plan-auditor might be problematic. Click here for more details.

Files changed (47) hide show
  1. plan_auditor-2.0.1/.gitignore +6 -0
  2. plan_auditor-2.0.1/CHANGELOG.md +17 -0
  3. plan_auditor-2.0.1/CONTRIBUTING.md +19 -0
  4. plan_auditor-2.0.1/LICENSE +21 -0
  5. plan_auditor-2.0.1/PKG-INFO +294 -0
  6. plan_auditor-2.0.1/README.md +272 -0
  7. plan_auditor-2.0.1/SKILL.md +100 -0
  8. plan_auditor-2.0.1/docs/architecture.md +267 -0
  9. plan_auditor-2.0.1/docs/integrations.md +54 -0
  10. plan_auditor-2.0.1/docs/threat-model.md +91 -0
  11. plan_auditor-2.0.1/examples/fib/.plan-auditor/plan.json +25 -0
  12. plan_auditor-2.0.1/examples/fib/fib.py +5 -0
  13. plan_auditor-2.0.1/examples/fib/test_fib.py +14 -0
  14. plan_auditor-2.0.1/hooks/README.md +141 -0
  15. plan_auditor-2.0.1/pyproject.toml +64 -0
  16. plan_auditor-2.0.1/references/plan-format.md +47 -0
  17. plan_auditor-2.0.1/scripts/__init__.py +1 -0
  18. plan_auditor-2.0.1/scripts/audit_check.py +520 -0
  19. plan_auditor-2.0.1/scripts/stop_gate.py +72 -0
  20. plan_auditor-2.0.1/supervisor/__init__.py +53 -0
  21. plan_auditor-2.0.1/supervisor/adversarial.py +195 -0
  22. plan_auditor-2.0.1/supervisor/agents.py +169 -0
  23. plan_auditor-2.0.1/supervisor/cli.py +429 -0
  24. plan_auditor-2.0.1/supervisor/config.py +77 -0
  25. plan_auditor-2.0.1/supervisor/daemon.py +168 -0
  26. plan_auditor-2.0.1/supervisor/events.py +157 -0
  27. plan_auditor-2.0.1/supervisor/evidence.py +115 -0
  28. plan_auditor-2.0.1/supervisor/gate.py +90 -0
  29. plan_auditor-2.0.1/supervisor/goals.py +61 -0
  30. plan_auditor-2.0.1/supervisor/lifecycle.py +108 -0
  31. plan_auditor-2.0.1/supervisor/plan_verifier.py +96 -0
  32. plan_auditor-2.0.1/supervisor/policies.py +152 -0
  33. plan_auditor-2.0.1/supervisor/priority.py +60 -0
  34. plan_auditor-2.0.1/supervisor/requirements.py +85 -0
  35. plan_auditor-2.0.1/supervisor/sealing.py +181 -0
  36. plan_auditor-2.0.1/supervisor/watchdog.py +106 -0
  37. plan_auditor-2.0.1/supervisor/workspace.py +164 -0
  38. plan_auditor-2.0.1/tests/test_adversarial.py +84 -0
  39. plan_auditor-2.0.1/tests/test_agents_gate.py +147 -0
  40. plan_auditor-2.0.1/tests/test_audit_check.py +268 -0
  41. plan_auditor-2.0.1/tests/test_cli.py +85 -0
  42. plan_auditor-2.0.1/tests/test_core_layers.py +140 -0
  43. plan_auditor-2.0.1/tests/test_daemon.py +159 -0
  44. plan_auditor-2.0.1/tests/test_events.py +76 -0
  45. plan_auditor-2.0.1/tests/test_extra_layers.py +162 -0
  46. plan_auditor-2.0.1/tests/test_failure_injection.py +296 -0
  47. plan_auditor-2.0.1/tests/test_hooks.py +79 -0
plan_auditor-2.0.1/.gitignore ADDED
@@ -0,0 +1,6 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .pytest_cache/
4
+ .plan-auditor/evidence.jsonl
5
+ .plan-auditor/*.tmp
6
+ .plan-auditor/archive/
plan_auditor-2.0.1/CHANGELOG.md ADDED
@@ -0,0 +1,17 @@
1
+ # Changelog
2
+
3
+ ## v1.1.0 — 2026-09-03
4
+
5
+ - **Portable skill paths:** `SKILL.md` no longer hardcodes an install path; agents resolve `scripts/audit_check.py` relative to the skill directory. The package now drops into any Agent-Skills tool (Command Code, Claude Code, Codex CLI, Cursor, Grok Build, OpenCode).
6
+ - **Hard attempt cap:** `run` refuses to execute a step that already failed `MAX_ATTEMPTS` (3) times — evidence-based, agent can't grind past it. `--force` overrides explicitly.
7
+ - **Multi-plan support:** `--plan <name>` operates on `.plan-auditor/plans/<name>.json`; the default remains `plan.json`. Evidence records are scoped per plan; `stop_gate.py` checks all active plans.
8
+ - **Snapshot / rollback:** `snapshot` archives the files listed in the plan's optional `snapshot` field (falls back to `git ls-files`) into a zip; `rollback` restores the latest (`--to` to pick one). Both actions are recorded in the evidence chain.
9
+ - **Evidence rotation:** logs over 2 MB are moved to `.plan-auditor/archive/` automatically; the chain restarts cleanly.
10
+ - **Test suite:** 25 unit tests covering schema, checks, chain/tamper, caps, multi-plan, rotation, snapshot/rollback.
11
+
12
+ ## v1.0.0 — 2026-09-03
13
+
14
+ - Initial release: strict plan + independent auditor Agent Skill.
15
+ - `plan.json` schema with machine-checkable `verify` checks (`run`, `exec`, `file_exists`, `regex`, `pytest`).
16
+ - Deterministic auditor: fresh-shell execution, append-only SHA-256 hash-chained evidence log, tamper detection (exit 2), full-audit final gate.
17
+ - Mandatory behavioral check per step; recovery-loop rules; self-audit CI gate (GitHub Actions); Command Code Stop-hook enforcement gate.
plan_auditor-2.0.1/CONTRIBUTING.md ADDED
@@ -0,0 +1,19 @@
1
+ # Contributing
2
+
3
+ ## Rules of the game
4
+
5
+ 1. **The auditor never trusts the agent.** Any change that lets an LLM claim upgrade a failed or missing evidence into a pass is rejected by design. The LLM's judgment may only *tighten* (add stricter checks, downgrade `verified`), never loosen.
6
+ 2. **Evidence is append-only.** The SHA-256 hash chain in `evidence.jsonl` is sacred. PRs that allow editing or reordering past records will be declined.
7
+ 3. **Unverifiable = failed.** Every step needs at least one behavioral check (`run`, `pytest`, or `exec`). File existence or regex alone can never verify a step.
8
+ 4. **Stdlib only.** `scripts/audit_check.py` must stay dependency-free (Python standard library) so the skill stays plug-and-play everywhere.
9
+
10
+ ## Dev workflow
11
+
12
+ ```bash
13
+ python -m pytest tests/ -q # unit suite
14
+ python scripts/audit_check.py audit . # self-audit gate (CI runs this too)
15
+ ```
16
+
17
+ - New check types: add to `CHECK_TYPES`, handle in `run_check`, document in `references/plan-format.md`, add tests.
18
+ - New modes: follow the existing `cmd_*` pattern, keep exit codes (0 pass / 1 fail / 2 tamper).
19
+ - This repo dogfoods: keep `.plan-auditor/plan.json` accurate — CI enforces it on every push.
plan_auditor-2.0.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Furox-Art
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
plan_auditor-2.0.1/PKG-INFO ADDED
@@ -0,0 +1,294 @@
1
+ Metadata-Version: 2.5
2
+ Name: plan-auditor
3
+ Version: 2.0.1
4
+ Summary: Independent multi-layer verification supervisor for AI coding agents
5
+ Project-URL: Homepage, https://github.com/Furox-Art/plan-auditor
6
+ Project-URL: Repository, https://github.com/Furox-Art/plan-auditor
7
+ Project-URL: Issues, https://github.com/Furox-Art/plan-auditor/issues
8
+ Author: Furox-Art
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai-agents,auditing,cli,supervisor,verification
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+
23
+ # plan-auditor
24
+
25
+ [![plan-audit gate](https://github.com/Furox-Art/plan-auditor/actions/workflows/plan-audit.yml/badge.svg)](https://github.com/Furox-Art/plan-auditor/actions/workflows/plan-audit.yml)
26
+
27
+ **An independent, multi-layered verification supervisor for AI coding agents.**
28
+
29
+ AI coding agents routinely leave work half-done or claim "done" when it
30
+ isn't. Root cause: no explicit, machine-checkable plan, and nobody
31
+ verifying the claims. `plan-auditor` fixes both — and goes further: it
32
+ runs **independently** of the main AI, seals plan criteria against
33
+ weakening, watches execution in real time, and refuses to count
34
+ unverified work as done. It supports **parallel / concurrent agents**.
35
+
36
+ ---
37
+
38
+ ## Two modes
39
+
40
+ | Mode | What it is | How you use it |
41
+ |---|---|---|
42
+ | **Skill Mode** | The original Agent Skill (unchanged v1.1 behavior). Copy the folder; the agent follows `SKILL.md`. | Copy to your tool's skills directory. |
43
+ | **Supervisor Mode** | The new layered verification daemon. Independent process, 14 layers, parallel-agent aware. | `plan-auditor supervisor start --profile standard` then `plan-auditor audit <dir>`. |
44
+
45
+ ---
46
+
47
+ ## Architecture
48
+
49
+ ```
50
+ User Task
51
+ │
52
+ ▼
53
+ Main AI Agent ──────────────► proposes plan
54
+ │ │
55
+ │ ▼
56
+ │ ┌──────────────────────────────┐
57
+ └───────────────► │ Independent Supervisor │
58
+ │ (separate process / daemon) │
59
+ └──────────────┬───────────────┘
60
+ │
61
+ ┌─────────────────────┼──────────────────────────┐
62
+ ▼ ▼ ▼
63
+ L0 Event Layer L1 Requirements L5 STRIPS-like
64
+ (pattern detect) (structured reqs) Plan Verifier
65
+ │ │ │
66
+ ▼ ▼ ▼
67
+ L2 World Model L3 Policy Engine L9 Watchdog
68
+ (workspace state) (deterministic rules) (runtime observe)
69
+ │ │ │
70
+ └─────────────────────┼──────────────────────────┘
71
+ ▼
72
+ L10 Deterministic Core (audit_check.py)
73
+ │
74
+ ▼
75
+ L8 Sealing + Monotonic Verification
76
+ │
77
+ ▼
78
+ L13 Completion Gate ──► PASS / FAIL / UNKNOWN
79
+ │
80
+ ▼
81
+ L12 Adversarial AI (optional semantic review)
82
+ ```
83
+
84
+ See [`docs/architecture.md`](docs/architecture.md) for the full data flow
85
+ and layer responsibilities.
86
+
87
+ ---
88
+
89
+ ## Layers
90
+
91
+ | Layer | Responsibility | LLM? |
92
+ |---|---|---|
93
+ | **L0** Event / pattern detection — ELIZA-like. Detects "done", config changes, repeated failures, security signals. Only triggers; never judges. | no |
94
+ | **L1** Requirement interpretation — structured requirements with acceptance criteria and ambiguity flags. | optional |
95
+ | **L2** Workspace / world model — SHRDLU-inspired structured repo state (git, files, tools, agents). | no |
96
+ | **L3** Policy engine — MYCIN/expert-system IF/THEN rules, fail-closed, testable. | no |
97
+ | **L4** BDI goal model — Beliefs/Desires/Intention state container driving audit order. | no |
98
+ | **L5** STRIPS-like plan verifier — preconditions/effects/coverage/contradiction analysis. | optional |
99
+ | **L6** Soar-like lifecycle — task state machine (NEW → … → PASSED/FAILED/UNKNOWN). | no |
100
+ | **L7** Subsumption priority — lower safety layers **override** higher AI judgment. | no |
101
+ | **L8** Plan sealing + monotonic verification — criteria can only tighten, never weaken. | no |
102
+ | **L9** Execution watchdog — fs/git/build/test monitoring, best-effort per platform. | no |
103
+ | **L10** Deterministic core — real checks via fresh subprocess (pytest, build, lint, exit codes). **Only** source of `verified`. | no |
104
+ | **L11** Evidence / integrity — cross-archive anchored, tamper-evident chain. | no |
105
+ | **L12** Adversarial AI — optional second-pass semantic review; proposes new deterministic checks only. | optional |
106
+ | **L13** Completion gate — **only** component that emits PASS/FAIL/UNKNOWN. | no |
107
+ | **L14** Multi-agent orchestrator — parallel agents, file ownership, conflict detection, locking. | no |
108
+
109
+ ### Subsumption priority (authoritative)
110
+
111
+ ```
112
+ LEVEL 0 process / system safety (supervisor alive, no deadlocks)
113
+ LEVEL 1 plan integrity (seal unchanged, monotonic)
114
+ LEVEL 2 deterministic verification (L10 core, real checks)
115
+ LEVEL 3 security policy (L3 rules: secrets, injection)
116
+ LEVEL 4 requirement coverage (all reqs checked)
117
+ LEVEL 5 AI semantic / adversarial judgment (L12)
118
+ ```
119
+
120
+ A failure at level **N** cannot be overridden by a PASS from any level
121
+ **> N**.
122
+
123
+ ---
124
+
125
+ ## Why independent verification?
126
+
127
+ An LLM auditing its own work with prose can hallucinate a pass. The
128
+ evidence engine here is **deterministic code**: subprocess exit codes,
129
+ filesystem facts, regex matches, pytest results. The main AI's judgment
130
+ can only *tighten* the gate, never loosen it.
131
+
132
+ ---
133
+
134
+ ## Parallel / multi-agent support
135
+
136
+ The supervisor is **not** single-agent. Multiple agents can work on the
137
+ same workspace concurrently:
138
+
139
+ - Each plan step declares file ownership (`owns`, inferred from `verify`
140
+ paths if absent).
141
+ - Overlap -> conflict warning (or block in STRICT profile).
142
+ - Heartbeats track liveness; stale ownership auto-releases.
143
+ - Lock files + append-only hashed registry coordinate agents.
144
+
145
+ Modes: `serial` | `parallel-warn` | `parallel-strict`.
146
+
147
+ ---
148
+
149
+ ## Local-first / hardware-adaptive
150
+
151
+ | Tier | What runs | Requirements |
152
+ |---|---|---|
153
+ | TIER 1 — NO LLM | L0-L11, L13, L14 fully | any modern box, no GPU |
154
+ | TIER 2 — SMALL LOCAL | + L12 adversarial (1B-4B quantized) | ~4-8 GB RAM |
155
+ | TIER 3 — STRONG LOCAL | + L1 + L5 (7B-14B+) | capable workstation |
156
+ | TIER 4 — REMOTE | user-provided API model | internet |
157
+
158
+ Core verification **never** requires an LLM. The supervisor is fully
159
+ useful in TIER 1.
160
+
161
+ ## Profiles
162
+
163
+ | Profile | Use case |
164
+ |---|---|
165
+ | LIGHT | small tasks, low overhead |
166
+ | STANDARD | normal repo/coding work |
167
+ | STRICT | bounty / production / security-sensitive |
168
+
169
+ ---
170
+
171
+ ## Install
172
+
173
+ One package, every agent. Copy the `plan-auditor/` folder into the skills
174
+ directory of whichever tool you use. No config, no build — the folder is
175
+ the install.
176
+
177
+ | Tool | User-level path | Invoke |
178
+ |---|---|---|
179
+ | Command Code | `~/.commandcode/skills/plan-auditor/` | `/plan-auditor` |
180
+ | Claude Code | `~/.claude/skills/plan-auditor/` | `/plan-auditor` |
181
+ | Codex CLI | `~/.codex/skills/plan-auditor/` | `$plan-auditor` |
182
+ | OpenCode | `~/.config/opencode/skills/plan-auditor/` | `/plan-auditor` |
183
+ | Cursor | `~/.cursor/skills/plan-auditor/` | `/plan-auditor` |
184
+ | Grok Build | `~/.grok/skills/plan-auditor/` | auto-loads by description |
185
+
186
+ ## How it auto-activates (no extra setup)
187
+
188
+ This works like **any other skill the agent already has**. Two activation paths:
189
+
190
+ ### 1. Automatic via description matching (all tools)
191
+
192
+ Every tool reads `SKILL.md`'s `description` field. When the user's request
193
+ matches it, the skill loads automatically — the agent never needs to be
194
+ told to use it. The current description triggers on phrases like
195
+ "build X", "implement Y", "add a feature", "plan it",
196
+ "don't leave it half-done", "did you actually do it".
197
+
198
+ Example flow:
199
+
200
+ ```
201
+ You: "Build the login form with tests"
202
+ │
203
+ ▼ (Claude Code / Codex / Cursor / Grok / OpenCode sees the request
204
+ matches the skill's description → loads ~/.../skills/plan-auditor/SKILL.md)
205
+ │
206
+ ▼ (Agent follows SKILL.md)
207
+ │ 1. Writes .plan-auditor/plan.json with concrete verify checks
208
+ │ 2. Implements each step
209
+ │ 3. After each step runs: python .../audit_check.py run <dir>
210
+ │ 4. Only finishes when: python .../audit_check.py audit <dir> exits 0
211
+ │
212
+ ▼
213
+ Agent: "audit PASSED — all steps verified" ← not just "done"
214
+ ```
215
+
216
+ No `/plan-auditor` invocation needed — it self-loads. You can also call it
217
+ explicitly (`/plan-auditor "build the login"`) for a one-shot task.
218
+
219
+ ### 2. Platform hook (Command Code — unskippable)
220
+
221
+ Command Code additionally wires `scripts/stop_gate.py` as a `Stop` hook.
222
+ At every turn-end, if any active plan has unverified steps, the turn is
223
+ **blocked** and the model is told to run the auditor. The agent cannot
224
+ finish, skip the audit, or relax a failed check. See
225
+ [`docs/integrations.md`](docs/integrations.md) for the one-block
226
+ `settings.json`.
227
+
228
+ ---
229
+
230
+ ## CLI (Supervisor Mode)
231
+
232
+ ```
233
+ plan-auditor supervisor start [--profile LIGHT|STANDARD|STRICT]
234
+ [--mode serial|parallel-warn|parallel-strict]
235
+ plan-auditor supervisor stop
236
+ plan-auditor supervisor status
237
+ plan-auditor task list | inspect <id>
238
+ plan-auditor plan verify <dir> | inspect <dir>
239
+ plan-auditor audit <dir>
240
+ plan-auditor evidence verify <dir>
241
+ plan-auditor doctor <dir>
242
+ plan-auditor agents list
243
+ ```
244
+
245
+ The existing `audit_check.py` subcommands (`validate`, `run`, `audit`,
246
+ `status`, `snapshot`, `rollback`) remain for Skill Mode.
247
+
248
+ ---
249
+
250
+ ## Threat model
251
+
252
+ See [`docs/threat-model.md`](docs/threat-model.md). Key points:
253
+
254
+ - **Main AI is untrusted.** The supervisor verifies independently.
255
+ - **Same-user limitation.** The supervisor cannot kernel-isolate from a
256
+ malicious same-user agent. This is a documented limitation, not a
257
+ guarantee. Use OS-level isolation for high-assurance cases.
258
+ - **Fail-closed.** Anything unknown resolves to FAIL or UNKNOWN, never
259
+ PASS.
260
+ - **Honest language.** The project uses "tamper-evident",
261
+ "fail-closed where supported", and "best-effort isolation" — never
262
+ "unbreakable" or "immutable".
263
+
264
+ ---
265
+
266
+ ## Guarantees
267
+
268
+ | Claim | Level |
269
+ |---|---|
270
+ | Deterministic check -> real pass/fail | guaranteed |
271
+ | Evidence tamper *detection* | tamper-evident (best-effort protection) |
272
+ | Plan criteria weakening blocked (same run) | guaranteed |
273
+ | Completion claim blocked (platform hook present) | guaranteed |
274
+ | Completion claim blocked (no platform hook) | supervisor state BLOCKED (best-effort) |
275
+ | Malicious same-user agent fully contained | **not guaranteed** |
276
+
277
+ ---
278
+
279
+ ## What's new in v2.0
280
+
281
+ - 14-layer supervisor architecture (L0-L14).
282
+ - Subsumption priority model.
283
+ - Plan sealing + monotonic verification.
284
+ - Multi-agent parallel support.
285
+ - Profiles (LIGHT/STANDARD/STRICT) and hardware tiers (TIER 1-4).
286
+ - Cross-archive evidence anchoring.
287
+ - 117 automated tests including 30 failure-injection / security scenarios.
288
+ - Full backward compatibility with Skill Mode.
289
+
290
+ ---
291
+
292
+ ## License
293
+
294
+ MIT
plan_auditor-2.0.1/README.md ADDED
@@ -0,0 +1,272 @@
1
+ # plan-auditor
2
+
3
+ [![plan-audit gate](https://github.com/Furox-Art/plan-auditor/actions/workflows/plan-audit.yml/badge.svg)](https://github.com/Furox-Art/plan-auditor/actions/workflows/plan-audit.yml)
4
+
5
+ **An independent, multi-layered verification supervisor for AI coding agents.**
6
+
7
+ AI coding agents routinely leave work half-done or claim "done" when it
8
+ isn't. Root cause: no explicit, machine-checkable plan, and nobody
9
+ verifying the claims. `plan-auditor` fixes both — and goes further: it
10
+ runs **independently** of the main AI, seals plan criteria against
11
+ weakening, watches execution in real time, and refuses to count
12
+ unverified work as done. It supports **parallel / concurrent agents**.
13
+
14
+ ---
15
+
16
+ ## Two modes
17
+
18
+ | Mode | What it is | How you use it |
19
+ |---|---|---|
20
+ | **Skill Mode** | The original Agent Skill (unchanged v1.1 behavior). Copy the folder; the agent follows `SKILL.md`. | Copy to your tool's skills directory. |
21
+ | **Supervisor Mode** | The new layered verification daemon. Independent process, 14 layers, parallel-agent aware. | `plan-auditor supervisor start --profile standard` then `plan-auditor audit <dir>`. |
22
+
23
+ ---
24
+
25
+ ## Architecture
26
+
27
+ ```
28
+ User Task
29
+ │
30
+ ▼
31
+ Main AI Agent ──────────────► proposes plan
32
+ │ │
33
+ │ ▼
34
+ │ ┌──────────────────────────────┐
35
+ └───────────────► │ Independent Supervisor │
36
+ │ (separate process / daemon) │
37
+ └──────────────┬───────────────┘
38
+ │
39
+ ┌─────────────────────┼──────────────────────────┐
40
+ ▼ ▼ ▼
41
+ L0 Event Layer L1 Requirements L5 STRIPS-like
42
+ (pattern detect) (structured reqs) Plan Verifier
43
+ │ │ │
44
+ ▼ ▼ ▼
45
+ L2 World Model L3 Policy Engine L9 Watchdog
46
+ (workspace state) (deterministic rules) (runtime observe)
47
+ │ │ │
48
+ └─────────────────────┼──────────────────────────┘
49
+ ▼
50
+ L10 Deterministic Core (audit_check.py)
51
+ │
52
+ ▼
53
+ L8 Sealing + Monotonic Verification
54
+ │
55
+ ▼
56
+ L13 Completion Gate ──► PASS / FAIL / UNKNOWN
57
+ │
58
+ ▼
59
+ L12 Adversarial AI (optional semantic review)
60
+ ```
61
+
62
+ See [`docs/architecture.md`](docs/architecture.md) for the full data flow
63
+ and layer responsibilities.
64
+
65
+ ---
66
+
67
+ ## Layers
68
+
69
+ | Layer | Responsibility | LLM? |
70
+ |---|---|---|
71
+ | **L0** Event / pattern detection — ELIZA-like. Detects "done", config changes, repeated failures, security signals. Only triggers; never judges. | no |
72
+ | **L1** Requirement interpretation — structured requirements with acceptance criteria and ambiguity flags. | optional |
73
+ | **L2** Workspace / world model — SHRDLU-inspired structured repo state (git, files, tools, agents). | no |
74
+ | **L3** Policy engine — MYCIN/expert-system IF/THEN rules, fail-closed, testable. | no |
75
+ | **L4** BDI goal model — Beliefs/Desires/Intention state container driving audit order. | no |
76
+ | **L5** STRIPS-like plan verifier — preconditions/effects/coverage/contradiction analysis. | optional |
77
+ | **L6** Soar-like lifecycle — task state machine (NEW → … → PASSED/FAILED/UNKNOWN). | no |
78
+ | **L7** Subsumption priority — lower safety layers **override** higher AI judgment. | no |
79
+ | **L8** Plan sealing + monotonic verification — criteria can only tighten, never weaken. | no |
80
+ | **L9** Execution watchdog — fs/git/build/test monitoring, best-effort per platform. | no |
81
+ | **L10** Deterministic core — real checks via fresh subprocess (pytest, build, lint, exit codes). **Only** source of `verified`. | no |
82
+ | **L11** Evidence / integrity — cross-archive anchored, tamper-evident chain. | no |
83
+ | **L12** Adversarial AI — optional second-pass semantic review; proposes new deterministic checks only. | optional |
84
+ | **L13** Completion gate — **only** component that emits PASS/FAIL/UNKNOWN. | no |
85
+ | **L14** Multi-agent orchestrator — parallel agents, file ownership, conflict detection, locking. | no |
86
+
87
+ ### Subsumption priority (authoritative)
88
+
89
+ ```
90
+ LEVEL 0 process / system safety (supervisor alive, no deadlocks)
91
+ LEVEL 1 plan integrity (seal unchanged, monotonic)
92
+ LEVEL 2 deterministic verification (L10 core, real checks)
93
+ LEVEL 3 security policy (L3 rules: secrets, injection)
94
+ LEVEL 4 requirement coverage (all reqs checked)
95
+ LEVEL 5 AI semantic / adversarial judgment (L12)
96
+ ```
97
+
98
+ A failure at level **N** cannot be overridden by a PASS from any level
99
+ **> N**.
100
+
101
+ ---
102
+
103
+ ## Why independent verification?
104
+
105
+ An LLM auditing its own work with prose can hallucinate a pass. The
106
+ evidence engine here is **deterministic code**: subprocess exit codes,
107
+ filesystem facts, regex matches, pytest results. The main AI's judgment
108
+ can only *tighten* the gate, never loosen it.
109
+
110
+ ---
111
+
112
+ ## Parallel / multi-agent support
113
+
114
+ The supervisor is **not** single-agent. Multiple agents can work on the
115
+ same workspace concurrently:
116
+
117
+ - Each plan step declares file ownership (`owns`, inferred from `verify`
118
+ paths if absent).
119
+ - Overlap -> conflict warning (or block in STRICT profile).
120
+ - Heartbeats track liveness; stale ownership auto-releases.
121
+ - Lock files + append-only hashed registry coordinate agents.
122
+
123
+ Modes: `serial` | `parallel-warn` | `parallel-strict`.
124
+
125
+ ---
126
+
127
+ ## Local-first / hardware-adaptive
128
+
129
+ | Tier | What runs | Requirements |
130
+ |---|---|---|
131
+ | TIER 1 — NO LLM | L0-L11, L13, L14 fully | any modern box, no GPU |
132
+ | TIER 2 — SMALL LOCAL | + L12 adversarial (1B-4B quantized) | ~4-8 GB RAM |
133
+ | TIER 3 — STRONG LOCAL | + L1 + L5 (7B-14B+) | capable workstation |
134
+ | TIER 4 — REMOTE | user-provided API model | internet |
135
+
136
+ Core verification **never** requires an LLM. The supervisor is fully
137
+ useful in TIER 1.
138
+
139
+ ## Profiles
140
+
141
+ | Profile | Use case |
142
+ |---|---|
143
+ | LIGHT | small tasks, low overhead |
144
+ | STANDARD | normal repo/coding work |
145
+ | STRICT | bounty / production / security-sensitive |
146
+
147
+ ---
148
+
149
+ ## Install
150
+
151
+ One package, every agent. Copy the `plan-auditor/` folder into the skills
152
+ directory of whichever tool you use. No config, no build — the folder is
153
+ the install.
154
+
155
+ | Tool | User-level path | Invoke |
156
+ |---|---|---|
157
+ | Command Code | `~/.commandcode/skills/plan-auditor/` | `/plan-auditor` |
158
+ | Claude Code | `~/.claude/skills/plan-auditor/` | `/plan-auditor` |
159
+ | Codex CLI | `~/.codex/skills/plan-auditor/` | `$plan-auditor` |
160
+ | OpenCode | `~/.config/opencode/skills/plan-auditor/` | `/plan-auditor` |
161
+ | Cursor | `~/.cursor/skills/plan-auditor/` | `/plan-auditor` |
162
+ | Grok Build | `~/.grok/skills/plan-auditor/` | auto-loads by description |
163
+
164
+ ## How it auto-activates (no extra setup)
165
+
166
+ This works like **any other skill the agent already has**. Two activation paths:
167
+
168
+ ### 1. Automatic via description matching (all tools)
169
+
170
+ Every tool reads `SKILL.md`'s `description` field. When the user's request
171
+ matches it, the skill loads automatically — the agent never needs to be
172
+ told to use it. The current description triggers on phrases like
173
+ "build X", "implement Y", "add a feature", "plan it",
174
+ "don't leave it half-done", "did you actually do it".
175
+
176
+ Example flow:
177
+
178
+ ```
179
+ You: "Build the login form with tests"
180
+ │
181
+ ▼ (Claude Code / Codex / Cursor / Grok / OpenCode sees the request
182
+ matches the skill's description → loads ~/.../skills/plan-auditor/SKILL.md)
183
+ │
184
+ ▼ (Agent follows SKILL.md)
185
+ │ 1. Writes .plan-auditor/plan.json with concrete verify checks
186
+ │ 2. Implements each step
187
+ │ 3. After each step runs: python .../audit_check.py run <dir>
188
+ │ 4. Only finishes when: python .../audit_check.py audit <dir> exits 0
189
+ │
190
+ ▼
191
+ Agent: "audit PASSED — all steps verified" ← not just "done"
192
+ ```
193
+
194
+ No `/plan-auditor` invocation needed — it self-loads. You can also call it
195
+ explicitly (`/plan-auditor "build the login"`) for a one-shot task.
196
+
197
+ ### 2. Platform hook (Command Code — unskippable)
198
+
199
+ Command Code additionally wires `scripts/stop_gate.py` as a `Stop` hook.
200
+ At every turn-end, if any active plan has unverified steps, the turn is
201
+ **blocked** and the model is told to run the auditor. The agent cannot
202
+ finish, skip the audit, or relax a failed check. See
203
+ [`docs/integrations.md`](docs/integrations.md) for the one-block
204
+ `settings.json`.
205
+
206
+ ---
207
+
208
+ ## CLI (Supervisor Mode)
209
+
210
+ ```
211
+ plan-auditor supervisor start [--profile LIGHT|STANDARD|STRICT]
212
+ [--mode serial|parallel-warn|parallel-strict]
213
+ plan-auditor supervisor stop
214
+ plan-auditor supervisor status
215
+ plan-auditor task list | inspect <id>
216
+ plan-auditor plan verify <dir> | inspect <dir>
217
+ plan-auditor audit <dir>
218
+ plan-auditor evidence verify <dir>
219
+ plan-auditor doctor <dir>
220
+ plan-auditor agents list
221
+ ```
222
+
223
+ The existing `audit_check.py` subcommands (`validate`, `run`, `audit`,
224
+ `status`, `snapshot`, `rollback`) remain for Skill Mode.
225
+
226
+ ---
227
+
228
+ ## Threat model
229
+
230
+ See [`docs/threat-model.md`](docs/threat-model.md). Key points:
231
+
232
+ - **Main AI is untrusted.** The supervisor verifies independently.
233
+ - **Same-user limitation.** The supervisor cannot kernel-isolate from a
234
+ malicious same-user agent. This is a documented limitation, not a
235
+ guarantee. Use OS-level isolation for high-assurance cases.
236
+ - **Fail-closed.** Anything unknown resolves to FAIL or UNKNOWN, never
237
+ PASS.
238
+ - **Honest language.** The project uses "tamper-evident",
239
+ "fail-closed where supported", and "best-effort isolation" — never
240
+ "unbreakable" or "immutable".
241
+
242
+ ---
243
+
244
+ ## Guarantees
245
+
246
+ | Claim | Level |
247
+ |---|---|
248
+ | Deterministic check -> real pass/fail | guaranteed |
249
+ | Evidence tamper *detection* | tamper-evident (best-effort protection) |
250
+ | Plan criteria weakening blocked (same run) | guaranteed |
251
+ | Completion claim blocked (platform hook present) | guaranteed |
252
+ | Completion claim blocked (no platform hook) | supervisor state BLOCKED (best-effort) |
253
+ | Malicious same-user agent fully contained | **not guaranteed** |
254
+
255
+ ---
256
+
257
+ ## What's new in v2.0
258
+
259
+ - 14-layer supervisor architecture (L0-L14).
260
+ - Subsumption priority model.
261
+ - Plan sealing + monotonic verification.
262
+ - Multi-agent parallel support.
263
+ - Profiles (LIGHT/STANDARD/STRICT) and hardware tiers (TIER 1-4).
264
+ - Cross-archive evidence anchoring.
265
+ - 117 automated tests including 30 failure-injection / security scenarios.
266
+ - Full backward compatibility with Skill Mode.
267
+
268
+ ---
269
+
270
+ ## License
271
+
272
+ MIT