plan-auditor 2.0.2__tar.gz → 2.2.0__tar.gz

{plan_auditor-2.0.2 → plan_auditor-2.2.0}/.gitignore

@@ -1,11 +1,21 @@
 __pycache__/
 *.pyc
 .pytest_cache/
+build/
+dist/
+*.egg-info/
 .plan-auditor/evidence.jsonl
+.plan-auditor/evidence.head.json
+.plan-auditor/evidence.write.lock
+.plan-auditor/audit.freeze.lock
+.plan-auditor/request.json
+.plan-auditor/activation.json
+.plan-auditor/integrity.json
 .plan-auditor/*.tmp
 .plan-auditor/archive/
 .plan-auditor/snapshots/
 .plan-auditor/seal.json
+.plan-auditor/seals/
 .plan-auditor/supervisor-runtime.json
 .plan-auditor/supervisor-assessment.json
 .plan-auditor/supervisor.stop

plan_auditor-2.2.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+## Unreleased
+
+- None yet.
+
+# Changelog
+
+## v2.2.0 — 2026-09-05
+
+- **Physical control-plane confinement:** existing `.plan-auditor`, plan, seal, request/activation and policy path components are inspected with `lstat`; symlinked parents/leaves cannot redefine the workspace trust root.
+- **Policy read confinement:** `load_config` authorizes only symlink-free workspace policy directories before policy loading; a resolved external symlink target is rejected before its files are read.
+- **Sealed scope freeze:** automatic monotonic strengthening remains available for extra deterministic checks/prerequisites, but new steps, requirements, tools, coverage assignments or declared outputs now require a new host-approved request generation.
+- **Safe v3→v4 migration:** `plan-auditor-migrate-seal` provides a representation-only migration path for exact full-contract v3 seals. It requires authoritative request alignment and refuses any plan-scope change.
+- **Seal self-consistency:** v3/v4 seals validate their contract hash and criteria count on load/save before being trusted or authenticated.
+- **Streaming evidence verification:** JSONL verification, hashing and HMAC migration retain one record/chunk at a time instead of reading complete evidence/archive files into RAM.
+- **PID-aware registry locking:** registry transaction locks carry PID + random token; live owners are never evicted because of age alone, and stale cleanup requires a provably dead PID plus unchanged lock identity.
+- **Activation semantics:** a lone `.plan-auditor/supervisor.json`, log or cache no longer makes a plans-free workspace look like an activated failed task; request/seal/evidence/plan/integrity/registry state still prevents deletion from degrading to `NO_PLAN`.
+- **Single audit freeze implementation:** the unused `workspace.audit.lock` implementation was removed; `audit.freeze.lock`/`final_audit_session` remains the sole workspace final-audit freeze path.
+- **Version identity:** source/package version advances to `2.2.0`, preventing post-v2.1.0 hardening from producing a different wheel under the already-published `2.1.0` version.
+- **Trust-boundary documentation:** deliberate same-OS-user interference is explicitly treated as an OS isolation problem; separate account/container/VM deployment is required when that attacker is in scope.
+- **Regression coverage:** new tests cover plan/policy symlink escapes, scope expansion, config-only activation, PID-aware registry locks, streaming evidence verification and exact legacy-seal migration.
+
+## v2.1.0 — 2026-09-05
+
+- **Aggregate multi-plan completion:** the integrated supervisor now enumerates the default plan and every safe `.plan-auditor/plans/<name>.json` plan. Global PASS requires every active plan to PASS; a passing default plan cannot hide an unfinished named plan, and a named-only workspace is no longer misclassified as `NO_PLAN`.
+- **Explicit requirement coverage:** Supervisor Mode requires explicit requirements and deterministic `covers` links from steps. Every `must`/`should` requirement must be covered; omitted user requirements, unknown coverage IDs and duplicate requirement contracts block plan approval/PASS.
+- **Full-contract format-v3 seals:** seals bind task, requirements, required tools, step identity/order/title, requirement coverage, dependencies, required outputs, output contracts/checks, step checks, and the supervisor profile/mode/tier/policy fingerprint. Existing criteria may only be strengthened.
+- **Authenticated seals:** external-key HMAC integrity authenticates plan seals in addition to evidence, checkpoints, registry state and the integrity marker. Seal tampering or missing/wrong key material fails closed after integrity initialization.
+- **Configuration/policy downgrade prevention:** malformed supervisor configuration and configured policy files are explicit blocking errors. Profile/mode/tier and policy-file fingerprint are part of the sealed environment contract, so a post-seal downgrade is detected.
+- **Evidence concurrency and rotation continuity:** evidence append/rotation uses a cross-process exclusive lock, active evidence links the latest archive tail, and failed-attempt limits are counted across archived plus active evidence instead of resetting after rotation.
+- **Complete evidence verification:** `plan-auditor evidence verify` checks both active evidence and anchored archives.
+- **Safe plan addressing:** named plan IDs are validated as safe basenames and cannot use lexical `..` traversal outside `.plan-auditor/plans`.
+- **Canonical multi-agent ownership:** agent IDs are safe basenames and ownership paths are canonical workspace-relative paths before conflict comparison, preventing alternate spellings from evading `parallel-strict` overlap detection.
+- **Transactional full-scope rollback:** default snapshots carry a manifest with file type, mode and hash; rollback restores that state and removes files introduced after the snapshot. Explicit snapshot lists remain intentionally scoped.
+- **Stronger fresh-audit fingerprint:** workspace fingerprints include directories, file type and mode/executable bits in addition to contents and symlink targets.
+- **Internal shell removal:** workspace/world-model and watchdog Git probes use structured argv with `shell=False`; behavioral plan checks still require explicit `shell: true` for shell interpretation.
+- **Bounded verifier output:** command output is spooled/bounded instead of being captured without limit in memory; output-limit overflow fails the check.
+- **Doctor fail-closed exit codes:** `doctor` recomputes a current assessment and returns nonzero on FAIL/UNKNOWN instead of hiding a failed assessment behind exit 0.
+- **Authoritative hook unification:** `hooks/gate_hook.py` is the single integrated gate. `scripts/stop_gate.py` remains only as an exit-code-2 compatibility adapter and delegates to the same multi-plan full-contract assessment instead of trusting `status=verified`.
+- **Three-platform packaging and release gates:** real wheels are built and installed in clean virtual environments on Ubuntu, Windows and macOS. Smoke tests exercise multi-plan discovery, DAG/output dependencies, requirement coverage, full-contract seals, external-key HMAC, integrated audit, doctor, and evidence/integrity CLI paths. PyPI publishing waits for the same three-platform wheel preflight.
+- **Versioning:** development version advanced to `2.1.0` so the hardened source cannot be confused with the already-published `2.0.2` artifact.
+- **Regression hardening:** dedicated failure-injection tests cover named-plan bypasses, seal-contract weakening, environment downgrade, HMAC seal tampering, invalid config/policies, path traversal, evidence races/rotation/retry history, active-log tampering, rollback cleanup, executable-bit fingerprint changes, canonical agent conflicts, missing tools and bounded verifier output.
+- **Observational final audit:** a full audit fails if a verifier mutates product workspace content, type, or mode. Verification must prove pre-existing implementation state rather than creating the claimed result during the audit itself.
+
+## v2.0.2 — 2026-09-05
+
+- **Integrated supervisor pipeline:** new `supervisor/orchestrator.py` wires plan validation, requirements, workspace state, policies, sealing, deterministic evidence, adversarial review, completion gating, lifecycle state, and multi-agent state into one fail-closed assessment.
+- **Real hook enforcement:** `hooks/gate_hook.py` no longer trusts `status=verified` or fabricated integrity flags; PASS requires a valid seal and matching fresh full-audit evidence.
+- **Deterministic audit freshness:** full audits record SHA-256 fingerprints of the verification contract and workspace contents instead of relying on filesystem mtimes.
+- **Cross-archive evidence anchoring:** rotations write archive anchors and L11 verifies internal JSONL hash chains and links between archives.
+- **Persistent multi-agent state:** ownership and heartbeat updates are written to the shared registry; separate processes see the same state, and `parallel-strict` rejects overlapping file claims.
+- **Adversarial gate integration:** high/critical L12 findings with no deterministic follow-up prevent PASS and produce UNKNOWN instead of being ignored.
+- **User policy loading:** deterministic JSON/TOML policies load from configured policy directories.
+- **Workspace safety:** file checks and rollback are path-confined; workspace observation is read-only and uses `shutil.which()` instead of shell redirections that could create files.
+- **Daemon integration:** the background supervisor persists an integrated assessment and final gate outcome on every observation cycle.
+
+## v1.1.0 — 2026-09-03
+
+- **Portable skill paths:** `SKILL.md` resolves auditor scripts relative to the skill directory.
+- **Hard attempt cap:** `run` refuses a step after the configured failed-attempt cap unless explicitly forced.
+- **Multi-plan core support:** `--plan <name>` operates on `.plan-auditor/plans/<name>.json`; evidence is scoped per plan.
+- **Snapshot / rollback:** snapshot and rollback support were introduced and recorded in evidence.
+- **Evidence rotation:** large evidence logs rotate into `.plan-auditor/archive/`.
+
+## v1.0.0 — 2026-09-03
+
+- Initial strict plan + independent auditor Agent Skill.
+- Machine-checkable `verify` checks (`run`, `exec`, `file_exists`, `regex`, `pytest`).
+- Deterministic fresh execution, append-only SHA-256 evidence, tamper detection, and full-audit final gate.

plan_auditor-2.2.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.5
+Name: plan-auditor
+Version: 2.2.0
+Summary: Independent multi-layer verification supervisor for AI coding agents
+Project-URL: Homepage, https://github.com/Furox-Art/plan-auditor
+Project-URL: Repository, https://github.com/Furox-Art/plan-auditor
+Project-URL: Issues, https://github.com/Furox-Art/plan-auditor/issues
+Author: Furox-Art
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,auditing,cli,supervisor,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# plan-auditor
+
+[![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)
+
+**Independent deterministic verification for AI coding-agent plans.**
+
+`plan-auditor` is designed to answer a narrow question reliably:
+
+> Did the AI actually complete the user's requirements and its approved plan, or
+> did it only say that it did?
+
+The main agent's narration and persisted `status=verified` labels are not enough.
+PASS requires reproducible behavioral checks, explicit requirement coverage, an
+intact sealed verification contract, fresh audit evidence, and a valid aggregate
+completion gate across **every active plan**.
+
+## Core completion model
+
+```text
+User requirements
+      │
+      ▼
+Explicit requirement IDs ──► plan steps (`covers`)
+      │                         │
+      │                         ├─ depends_on
+      │                         ├─ outputs
+      │                         └─ requires_outputs
+      │
+      ▼
+Format-v3 full-contract seal
+      │
+      ▼
+Deterministic execution / tests
+      │
+      ▼
+Hash-chained evidence + fresh workspace/plan fingerprint
+      │
+      ▼
+Aggregate supervisor gate
+      │
+      ├─ default plan PASS
+      ├─ named plan A PASS
+      ├─ named plan B PASS
+      └─ policies / tools / registry / integrity PASS
+      │
+      ▼
+PASS / FAIL / UNKNOWN
+```
+
+## What a PASS means
+
+In Supervisor Mode, PASS requires all active plans to satisfy all of the
+following:
+
+- valid plan schema,
+- explicit non-empty `requirements`,
+- every `must`/`should` requirement covered by at least one step,
+- at least one behavioral check (`run`, `exec`, `pytest`) per step,
+- valid dependency DAG,
+- concrete output contract for every explicit dependency edge,
+- intact format-v3 seal,
+- unchanged sealed supervisor profile/mode/tier/policy fingerprint,
+- all steps verified in a fresh full audit,
+- current plan contract matches the audited plan fingerprint,
+- current workspace content/type/mode matches the audited workspace fingerprint,
+- active and archived evidence chains valid,
+- agent registry valid,
+- required tools present,
+- no blocking policy result.
+
+If any active named plan is unfinished, the whole workspace is non-PASS. A
+passing `plan.json` cannot hide `.plan-auditor/plans/backend.json`.
+
+## Deterministic checks
+
+Checks run as real subprocesses/filesystem assertions. Structured `argv` is
+preferred:
+
+```json
+{
+  "type": "run",
+  "argv": ["python", "-m", "pytest", "tests/", "-q"],
+  "expect_exit": 0
+}
+```
+
+Shell interpretation is disabled by default. Legacy `cmd` strings are parsed into
+an argument vector. Shell behavior requires explicit `"shell": true` and cannot
+be combined with `argv`.
+
+Verifier output is bounded to avoid unbounded-memory capture.
+
+## Requirements, dependencies, and outputs
+
+Example plan fragment:
+
+```json
+{
+  "task": "build and consume a verified model artifact",
+  "created": "2026-09-05T00:00:00Z",
+  "requirements": [
+    {"id": "REQ-001", "description": "produce the model artifact", "priority": "must"},
+    {"id": "REQ-002", "description": "consume the verified artifact", "priority": "must"}
+  ],
+  "required_tools": ["python"],
+  "steps": [
+    {
+      "id": 1,
+      "title": "produce artifact",
+      "depends_on": [],
+      "covers": ["REQ-001"],
+      "verify": [{"type": "run", "argv": ["python", "tests/build_artifact.py"]}],
+      "outputs": [
+        {
+          "name": "artifact",
+          "verify": [{"type": "file_exists", "path": "results/model.json"}]
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "title": "consume artifact",
+      "depends_on": [1],
+      "requires_outputs": [{"step": 1, "name": "artifact"}],
+      "covers": ["REQ-002"],
+      "verify": [{"type": "run", "argv": ["python", "tests/use_artifact.py"]}]
+    }
+  ]
+}
+```
+
+A downstream step cannot pass until the prerequisite passed and the upstream
+output contract is independently rechecked.
+
+## Full-contract sealing
+
+```bash
+plan-auditor plan verify .
+```
+
+The v3 seal binds:
+
+- task and requirements,
+- required tools,
+- step identity/order/title,
+- `covers`,
+- dependencies and required outputs,
+- outputs and their checks,
+- step verification checks,
+- supervisor `profile`, `mode`, `tier`,
+- configured-policy fingerprint.
+
+Existing criteria may be strengthened, but removing/changing sealed criteria or
+downgrading the sealed environment blocks completion.
+
+## Evidence integrity
+
+Evidence records are append-only JSONL records with SHA-256 `prev + hash`
+continuity. The chain spans log rotations; the active log links the latest archive
+tail. Concurrent evidence append/rotation is serialized with an exclusive lock.
+Failed-attempt limits are counted across archived and active evidence.
+
+Optional external-key HMAC adds authentication and signed tail checkpoints for:
+
+- active/archive evidence records,
+- evidence head,
+- agent registry records/head,
+- plan seals,
+- integrity marker.
+
+Initialize after sealing:
+
+```bash
+# set PLAN_AUDITOR_HMAC_KEY or PLAN_AUDITOR_HMAC_KEY_FILE first
+plan-auditor plan verify .
+plan-auditor integrity init .
+plan-auditor audit .
+```
+
+A key file must resolve outside the workspace.
+
+## Multi-agent state
+
+The persisted agent registry uses `format_version + seq + prev + hash` and an
+anti-truncation head checkpoint. Agent IDs are safe basenames and ownership paths
+are canonical workspace-relative paths, so spellings such as
+`src/../src/shared.py` and `./src/shared.py` cannot evade conflict detection.
+
+Modes:
+
+- `serial`
+- `parallel-warn`
+- `parallel-strict`
+
+## Snapshot / rollback
+
+Default snapshots capture the full workspace product state while excluding
+`.git`, `.plan-auditor`, and cache metadata. The snapshot manifest stores file
+type, mode and hash. Full-scope rollback restores the snapshot and removes files
+introduced afterwards. A plan's explicit `snapshot` list deliberately creates a
+narrower rollback scope.
+
+## CLI
+
+```text
+plan-auditor plan verify <dir> [--plan NAME] [--reseal]
+plan-auditor plan inspect <dir> [--plan NAME]
+plan-auditor validate <dir> [--plan NAME]
+plan-auditor run <dir> [step ids ...] [--plan NAME]
+plan-auditor audit <dir> [--plan NAME]
+plan-auditor evidence verify <dir>
+plan-auditor integrity init|status <dir>
+plan-auditor doctor <dir>
+plan-auditor task list <dir>
+plan-auditor agents list|register|heartbeat|claim|release ...
+plan-auditor supervisor start|stop|status ...
+```
+
+With no `--plan`, `plan verify` and the integrated final gate operate across all
+active default/named plans.
+
+`doctor` exits nonzero when an active workspace assessment is FAIL/UNKNOWN; JSON
+consumers no longer need to detect a hidden failed assessment behind exit code 0.
+
+## Hooks
+
+`hooks/gate_hook.py` is the platform-neutral authoritative gate. It uses the same
+aggregate supervisor assessment as the CLI.
+
+`scripts/stop_gate.py` is only a compatibility adapter for hosts whose Stop hook
+expects exit code `2`; it delegates to the same integrated gate and no longer
+implements status-only verification.
+
+See `docs/integrations.md`.
+
+## Cross-platform packaging gate
+
+GitHub Actions builds a real wheel independently on:
+
+- Ubuntu,
+- Windows,
+- macOS.
+
+Each job installs the wheel into a clean virtual environment outside the source
+checkout and exercises the installed console script through:
+
+- multi-plan discovery,
+- explicit DAG/output contracts,
+- requirement coverage,
+- full-contract sealing,
+- external-key HMAC initialization,
+- integrated audit,
+- doctor PASS,
+- evidence/integrity verification.
+
+Release publishing is additionally gated on the same three-platform wheel smoke,
+so PyPI publishing cannot race ahead of platform packaging validation.
+
+## Architecture
+
+The supervisor combines deterministic layers for requirements, workspace state,
+policy evaluation, plan/DAG validation, lifecycle, sealing, watchdog observation,
+evidence integrity, completion gating, and multi-agent coordination. Optional
+semantic/adversarial review may propose stronger deterministic checks but cannot
+create PASS.
+
+See:
+
+- `docs/architecture.md`
+- `docs/dependency-graph.md`
+- `docs/threat-model.md`
+- `references/plan-format.md`
+
+## Trust boundary
+
+Plan Auditor verifies completion; it is not an OS sandbox. External-key HMAC
+protects against workspace-only rewriting while the untrusted process cannot read
+the key. A deliberately malicious same-user process that can obtain the key is
+outside that guarantee. See the threat model for exact boundaries.
+
+## Version
+
+Current development version: **2.1.0**.
+
+## License
+
+MIT

plan_auditor-2.2.0/README.md

@@ -0,0 +1,287 @@
+# plan-auditor
+
+[![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)
+
+**Independent deterministic verification for AI coding-agent plans.**
+
+`plan-auditor` is designed to answer a narrow question reliably:
+
+> Did the AI actually complete the user's requirements and its approved plan, or
+> did it only say that it did?
+
+The main agent's narration and persisted `status=verified` labels are not enough.
+PASS requires reproducible behavioral checks, explicit requirement coverage, an
+intact sealed verification contract, fresh audit evidence, and a valid aggregate
+completion gate across **every active plan**.
+
+## Core completion model
+
+```text
+User requirements
+      │
+      ▼
+Explicit requirement IDs ──► plan steps (`covers`)
+      │                         │
+      │                         ├─ depends_on
+      │                         ├─ outputs
+      │                         └─ requires_outputs
+      │
+      ▼
+Format-v3 full-contract seal
+      │
+      ▼
+Deterministic execution / tests
+      │
+      ▼
+Hash-chained evidence + fresh workspace/plan fingerprint
+      │
+      ▼
+Aggregate supervisor gate
+      │
+      ├─ default plan PASS
+      ├─ named plan A PASS
+      ├─ named plan B PASS
+      └─ policies / tools / registry / integrity PASS
+      │
+      ▼
+PASS / FAIL / UNKNOWN
+```
+
+## What a PASS means
+
+In Supervisor Mode, PASS requires all active plans to satisfy all of the
+following:
+
+- valid plan schema,
+- explicit non-empty `requirements`,
+- every `must`/`should` requirement covered by at least one step,
+- at least one behavioral check (`run`, `exec`, `pytest`) per step,
+- valid dependency DAG,
+- concrete output contract for every explicit dependency edge,
+- intact format-v3 seal,
+- unchanged sealed supervisor profile/mode/tier/policy fingerprint,
+- all steps verified in a fresh full audit,
+- current plan contract matches the audited plan fingerprint,
+- current workspace content/type/mode matches the audited workspace fingerprint,
+- active and archived evidence chains valid,
+- agent registry valid,
+- required tools present,
+- no blocking policy result.
+
+If any active named plan is unfinished, the whole workspace is non-PASS. A
+passing `plan.json` cannot hide `.plan-auditor/plans/backend.json`.
+
+## Deterministic checks
+
+Checks run as real subprocesses/filesystem assertions. Structured `argv` is
+preferred:
+
+```json
+{
+  "type": "run",
+  "argv": ["python", "-m", "pytest", "tests/", "-q"],
+  "expect_exit": 0
+}
+```
+
+Shell interpretation is disabled by default. Legacy `cmd` strings are parsed into
+an argument vector. Shell behavior requires explicit `"shell": true` and cannot
+be combined with `argv`.
+
+Verifier output is bounded to avoid unbounded-memory capture.
+
+## Requirements, dependencies, and outputs
+
+Example plan fragment:
+
+```json
+{
+  "task": "build and consume a verified model artifact",
+  "created": "2026-09-05T00:00:00Z",
+  "requirements": [
+    {"id": "REQ-001", "description": "produce the model artifact", "priority": "must"},
+    {"id": "REQ-002", "description": "consume the verified artifact", "priority": "must"}
+  ],
+  "required_tools": ["python"],
+  "steps": [
+    {
+      "id": 1,
+      "title": "produce artifact",
+      "depends_on": [],
+      "covers": ["REQ-001"],
+      "verify": [{"type": "run", "argv": ["python", "tests/build_artifact.py"]}],
+      "outputs": [
+        {
+          "name": "artifact",
+          "verify": [{"type": "file_exists", "path": "results/model.json"}]
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "title": "consume artifact",
+      "depends_on": [1],
+      "requires_outputs": [{"step": 1, "name": "artifact"}],
+      "covers": ["REQ-002"],
+      "verify": [{"type": "run", "argv": ["python", "tests/use_artifact.py"]}]
+    }
+  ]
+}
+```
+
+A downstream step cannot pass until the prerequisite passed and the upstream
+output contract is independently rechecked.
+
+## Full-contract sealing
+
+```bash
+plan-auditor plan verify .
+```
+
+The v3 seal binds:
+
+- task and requirements,
+- required tools,
+- step identity/order/title,
+- `covers`,
+- dependencies and required outputs,
+- outputs and their checks,
+- step verification checks,
+- supervisor `profile`, `mode`, `tier`,
+- configured-policy fingerprint.
+
+Existing criteria may be strengthened, but removing/changing sealed criteria or
+downgrading the sealed environment blocks completion.
+
+## Evidence integrity
+
+Evidence records are append-only JSONL records with SHA-256 `prev + hash`
+continuity. The chain spans log rotations; the active log links the latest archive
+tail. Concurrent evidence append/rotation is serialized with an exclusive lock.
+Failed-attempt limits are counted across archived and active evidence.
+
+Optional external-key HMAC adds authentication and signed tail checkpoints for:
+
+- active/archive evidence records,
+- evidence head,
+- agent registry records/head,
+- plan seals,
+- integrity marker.
+
+Initialize after sealing:
+
+```bash
+# set PLAN_AUDITOR_HMAC_KEY or PLAN_AUDITOR_HMAC_KEY_FILE first
+plan-auditor plan verify .
+plan-auditor integrity init .
+plan-auditor audit .
+```
+
+A key file must resolve outside the workspace.
+
+## Multi-agent state
+
+The persisted agent registry uses `format_version + seq + prev + hash` and an
+anti-truncation head checkpoint. Agent IDs are safe basenames and ownership paths
+are canonical workspace-relative paths, so spellings such as
+`src/../src/shared.py` and `./src/shared.py` cannot evade conflict detection.
+
+Modes:
+
+- `serial`
+- `parallel-warn`
+- `parallel-strict`
+
+## Snapshot / rollback
+
+Default snapshots capture the full workspace product state while excluding
+`.git`, `.plan-auditor`, and cache metadata. The snapshot manifest stores file
+type, mode and hash. Full-scope rollback restores the snapshot and removes files
+introduced afterwards. A plan's explicit `snapshot` list deliberately creates a
+narrower rollback scope.
+
+## CLI
+
+```text
+plan-auditor plan verify <dir> [--plan NAME] [--reseal]
+plan-auditor plan inspect <dir> [--plan NAME]
+plan-auditor validate <dir> [--plan NAME]
+plan-auditor run <dir> [step ids ...] [--plan NAME]
+plan-auditor audit <dir> [--plan NAME]
+plan-auditor evidence verify <dir>
+plan-auditor integrity init|status <dir>
+plan-auditor doctor <dir>
+plan-auditor task list <dir>
+plan-auditor agents list|register|heartbeat|claim|release ...
+plan-auditor supervisor start|stop|status ...
+```
+
+With no `--plan`, `plan verify` and the integrated final gate operate across all
+active default/named plans.
+
+`doctor` exits nonzero when an active workspace assessment is FAIL/UNKNOWN; JSON
+consumers no longer need to detect a hidden failed assessment behind exit code 0.
+
+## Hooks
+
+`hooks/gate_hook.py` is the platform-neutral authoritative gate. It uses the same
+aggregate supervisor assessment as the CLI.
+
+`scripts/stop_gate.py` is only a compatibility adapter for hosts whose Stop hook
+expects exit code `2`; it delegates to the same integrated gate and no longer
+implements status-only verification.
+
+See `docs/integrations.md`.
+
+## Cross-platform packaging gate
+
+GitHub Actions builds a real wheel independently on:
+
+- Ubuntu,
+- Windows,
+- macOS.
+
+Each job installs the wheel into a clean virtual environment outside the source
+checkout and exercises the installed console script through:
+
+- multi-plan discovery,
+- explicit DAG/output contracts,
+- requirement coverage,
+- full-contract sealing,
+- external-key HMAC initialization,
+- integrated audit,
+- doctor PASS,
+- evidence/integrity verification.
+
+Release publishing is additionally gated on the same three-platform wheel smoke,
+so PyPI publishing cannot race ahead of platform packaging validation.
+
+## Architecture
+
+The supervisor combines deterministic layers for requirements, workspace state,
+policy evaluation, plan/DAG validation, lifecycle, sealing, watchdog observation,
+evidence integrity, completion gating, and multi-agent coordination. Optional
+semantic/adversarial review may propose stronger deterministic checks but cannot
+create PASS.
+
+See:
+
+- `docs/architecture.md`
+- `docs/dependency-graph.md`
+- `docs/threat-model.md`
+- `references/plan-format.md`
+
+## Trust boundary
+
+Plan Auditor verifies completion; it is not an OS sandbox. External-key HMAC
+protects against workspace-only rewriting while the untrusted process cannot read
+the key. A deliberately malicious same-user process that can obtain the key is
+outside that guarantee. See the threat model for exact boundaries.
+
+## Version
+
+Current development version: **2.1.0**.
+
+## License
+
+MIT