plan-auditor 2.3.0__tar.gz → 2.4.1__tar.gz

{plan_auditor-2.3.0 → plan_auditor-2.4.1}/CHANGELOG.md

@@ -1,9 +1,20 @@
 ## Unreleased
 
-- None yet.
-
 # Changelog
 
+## v2.4.1 — 2026-09-29
+
+- Metadata-only patch release: improved PyPI discovery keywords, classifiers, description, documentation links, and synchronized package version metadata.
+
+## v2.4.0 — 2026-09-06
+
+- **Deterministic automatic formalization:** `plan-auditor-formalize compile` converts structured Plan Auditor requirements, coverage, dependencies, named outputs, `requires_outputs`, and deterministic checks into a conservative grounded STRIPS contract without asking an LLM to invent authoritative symbolic semantics.
+- **Independent formalization proof:** generated contracts carry a `formalization-source:<SHA256>` marker and are independently recompiled from the current plan; stale, weakened, omitted, or manually edited generated contracts are rejected even if their embedded contract SHA is recomputed.
+- **Dataflow-bound symbolic state:** generated actions prove step completion, named-output availability, and canonical `requirement-satisfied:<REQ-ID>` goals; downstream `requires_outputs` become symbolic preconditions while the existing dependency DAG remains independently enforced.
+- **Safe generated/manual split:** automatic formalization refuses to overwrite reviewed manual formal contracts and refuses to mutate already sealed plans. Domain semantics that cannot be derived mechanically remain explicit/manual rather than guessed.
+- **New installed CLI:** adds `plan-auditor-formalize compile|verify`; package and skill identity advance to stable `2.4.0`.
+- **Regression coverage:** tests exercise exact recompilation, source-staleness detection, goal weakening, dropped output preconditions, fake initial requirement goals, idempotence, sealed-plan mutation refusal, and manual-contract preservation.
+
 ## v2.3.0 — 2026-09-06
 
 - **Sealed classical planning:** non-trivial multi-step plans can embed one sealed `formal_planning` contract with explicit initial facts, final goals, one grounded STRIPS-style action per Plan Auditor step, symbolic preconditions, add effects and delete effects.
@@ -76,4 +87,4 @@
 
 - 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.
+- Deterministic fresh execution, append-only SHA-256 evidence, tamper detection, and full-audit final gate.

plan_auditor-2.4.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: plan-auditor
+Version: 2.4.1
+Summary: Deterministic verification and evidence auditing for AI coding agents, plans, tests, and CI
+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
+Project-URL: Documentation, https://github.com/Furox-Art/plan-auditor/tree/main/docs
+Project-URL: Changelog, https://github.com/Furox-Art/plan-auditor/blob/main/CHANGELOG.md
+Author: Furox-Art
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,ai-coding,auditing,ci,cli,coding-agents,developer-tools,evidence,formal-verification,llm-agents,quality-assurance,software-testing,supervisor,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+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)  
+[![PyPI](https://img.shields.io/pypi/v/plan-auditor)](https://pypi.org/project/plan-auditor/)  
+[![npm](https://img.shields.io/npm/v/plan-auditor)](https://www.npmjs.com/package/plan-auditor)  
+[![Downloads](https://img.shields.io/pypi/dm/plan-auditor)](https://pypi.org/project/plan-auditor/)  
+![License](https://img.shields.io/badge/license-MIT-blue)  
+  
+I built this because I got tired of AI saying "done" when it wasn't.  
+  
+You know the drill: you ask an AI coding assistant to build something, it says "all tests pass," and then you find out it never actually ran them. Or it ran them once, failed, and "fixed" the test to make it green.  
+  
+plan-auditor forces the AI to prove its work. Not with words-with actual command output, file hashes, and deterministic checks that can't be faked.  
+  
+## How it works  
+  
+1. You describe what you want built  
+2. plan-auditor turns that into explicit, machine-checkable requirements  
+3. The AI implements each step and must provide real evidence (command output, file contents, test results)  
+4. A separate auditor process verifies everything independently  
+5. Only when every check passes does it say "done"  
+  
+No more "trust me bro" from language models.  
+  
+## Quick start  
+  
+```bash  
+pip install plan-auditor  
+# or  
+npx plan-auditor  
+```  
+  
+Then just tell your AI: "Use plan-auditor for this task." It handles the rest.  
+  
+## Why I made this  
+  
+I was working on a scientific computing project and an AI assistant kept insisting it had fixed a bug. It hadn't. Three times. I wasted hours before I realized the "fix" was just the AI editing its own test output.  
+  
+So I built a system where the AI can't lie. Where "done" means "here's the terminal output proving it." Where the plan is sealed cryptographically and any tampering breaks the verification.  
+  
+It's not perfect. But it's a hell of a lot better than taking an LLM's word for anything.  
+  
+## Docs  
+  
+- [Architecture](docs/architecture.md) - how the pieces fit together  
+- [Formal Planning](docs/formal-planning.md) - the STRIPS/PDDL verification stuff  
+- [Threat Model](docs/threat-model.md) - what it can and can't protect against  
+  
+## License  
+  
+MIT. Do whatever you want with it. 

plan_auditor-2.4.1/README.md

@@ -0,0 +1,51 @@
+# 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)  
+[![PyPI](https://img.shields.io/pypi/v/plan-auditor)](https://pypi.org/project/plan-auditor/)  
+[![npm](https://img.shields.io/npm/v/plan-auditor)](https://www.npmjs.com/package/plan-auditor)  
+[![Downloads](https://img.shields.io/pypi/dm/plan-auditor)](https://pypi.org/project/plan-auditor/)  
+![License](https://img.shields.io/badge/license-MIT-blue)  
+  
+I built this because I got tired of AI saying "done" when it wasn't.  
+  
+You know the drill: you ask an AI coding assistant to build something, it says "all tests pass," and then you find out it never actually ran them. Or it ran them once, failed, and "fixed" the test to make it green.  
+  
+plan-auditor forces the AI to prove its work. Not with words-with actual command output, file hashes, and deterministic checks that can't be faked.  
+  
+## How it works  
+  
+1. You describe what you want built  
+2. plan-auditor turns that into explicit, machine-checkable requirements  
+3. The AI implements each step and must provide real evidence (command output, file contents, test results)  
+4. A separate auditor process verifies everything independently  
+5. Only when every check passes does it say "done"  
+  
+No more "trust me bro" from language models.  
+  
+## Quick start  
+  
+```bash  
+pip install plan-auditor  
+# or  
+npx plan-auditor  
+```  
+  
+Then just tell your AI: "Use plan-auditor for this task." It handles the rest.  
+  
+## Why I made this  
+  
+I was working on a scientific computing project and an AI assistant kept insisting it had fixed a bug. It hadn't. Three times. I wasted hours before I realized the "fix" was just the AI editing its own test output.  
+  
+So I built a system where the AI can't lie. Where "done" means "here's the terminal output proving it." Where the plan is sealed cryptographically and any tampering breaks the verification.  
+  
+It's not perfect. But it's a hell of a lot better than taking an LLM's word for anything.  
+  
+## Docs  
+  
+- [Architecture](docs/architecture.md) - how the pieces fit together  
+- [Formal Planning](docs/formal-planning.md) - the STRIPS/PDDL verification stuff  
+- [Threat Model](docs/threat-model.md) - what it can and can't protect against  
+  
+## License  
+  
+MIT. Do whatever you want with it. 

plan_auditor-2.4.1/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: plan-auditor
+description: Invoke this skill by name as `plan-auditor` for non-trivial build/implement/fix work or whenever the user wants independent proof that an AI actually completed the requested work. It converts the task into explicit requirements and machine-verifiable steps, automatically compiles those structured requirements/dataflow into a sealed LLM-free STRIPS contract, proves every step with real command evidence, and blocks completion until every active plan has an intact contract and a fresh deterministic audit.
+argument-hint: "<task description>"
+metadata:
+  version: "2.4.1"
+---
+
+# Plan Auditor — strict plan + independent verification
+
+The main agent's narration is never evidence. The workflow has two separate roles:
+
+- **Planner / implementer:** converts the user's exact requirements into work.
+- **Auditor / supervisor:** decides completion only from reproducible checks and the sealed verification contract.
+
+## Direct invocation
+
+When this skill is selected or called by its name, `plan-auditor`, run the full workflow automatically. The user should not need to know or hand-write plan JSON, STRIPS/PDDL, seal metadata, evidence files, or source fingerprints.
+
+Examples:
+
+```text
+plan-auditor
+plan-auditor: implement this and prove it is complete
+Use plan-auditor for this task.
+```
+
+Treat the user's task as the authoritative intent. Capture it in the host-owned request contract and explicit plan requirements, then build measurable steps and deterministic acceptance checks.
+
+For non-trivial multi-step plans, use the deterministic auto-formalizer before sealing:
+
+```bash
+plan-auditor-formalize compile <project>
+```
+
+The compiler does **not** ask an LLM to invent symbolic semantics. It derives a conservative formal model only from already structured Plan Auditor primitives:
+
+- `must` / `should` requirement IDs,
+- step `covers` bindings,
+- dependency edges,
+- named `outputs`,
+- `requires_outputs` dataflow,
+- deterministic verification checks.
+
+It creates exactly one generated `formal_planning` anchor plus an independent semantic-recompilation check. Generated facts are limited to:
+
+- `formalization-source:<SHA256>` — fingerprint of the structured source plan,
+- `step-completed:<STEP-ID>`,
+- `output-available:<STEP-ID>:...`,
+- `requirement-satisfied:<REQ-ID>`.
+
+The source fingerprint is recomputed from the current plan during verification. A generated contract that omits a requirement, drops an output precondition, weakens a goal, or becomes stale after the plan changes is rejected even if its internal contract SHA was recomputed.
+
+Manual domain-specific STRIPS contracts remain supported, but the auto-formalizer will not overwrite them. If a domain fact cannot be derived safely from structured plan data, do not guess it; keep it in a manually reviewed contract or rely on deterministic acceptance checks.
+
+## Non-negotiable rules
+
+1. **No deterministic evidence = not done.**
+2. **Every user requirement must be explicit.** Supervisor Mode requires non-empty `plan.requirements`; every `must`/`should` requirement must be linked from one or more steps through `covers`.
+3. **Every step needs real behavior.** At least one `run`, `exec`, or `pytest` check is mandatory; existence/regex checks may supplement but not replace behavioral proof.
+4. **Dependencies must be concrete.** Every explicit dependency edge must be backed by a named upstream output and `requires_outputs`.
+5. **Auto-formalize non-trivial multi-step work before sealing.** Run `plan-auditor-formalize compile <project>` unless a deliberate, reviewed manual formal contract is used.
+6. **Generated formalization is independently recomputed.** Never edit generated STRIPS facts/actions by hand to manufacture PASS. Change the structured plan source and re-run the compiler.
+7. **Formal goals must prove requirements.** Every `must`/`should` requirement gets canonical `requirement-satisfied:<REQ-ID>` final-state proof produced only by covering steps.
+8. **Sealed criteria can only tighten.** Do not remove or weaken sealed checks, dependencies, required outputs, outputs, coverage, requirements, formal planning data, or supervisor policy/profile settings.
+9. **All active plans count.** A passing default plan never hides an unfinished named plan.
+10. **Full audit is the completion gate.** Do not claim completion until `plan-auditor audit <project>` exits 0.
+11. **Semantic judgment can only tighten.** If deterministic checks miss a real defect, add a stronger deterministic check and rerun; prose cannot convert failure into PASS.
+
+## Workflow
+
+### 1. Capture the request contract
+
+Convert every material user requirement into a stable requirement object with an ID, description, priority, and deterministic acceptance checks. The host-owned request contract remains the authority for user intent.
+
+### 2. Build a measurable plan
+
+Each step must declare what it covers, how it is verified, and—when relevant—its outputs and required upstream outputs.
+
+Example:
+
+```json
+{
+  "task": "build and consume a verified artifact",
+  "created": "2026-09-06T00:00:00Z",
+  "requirements": [
+    {"id": "REQ-001", "description": "produce the artifact", "priority": "must"},
+    {"id": "REQ-002", "description": "consume the verified artifact", "priority": "must"}
+  ],
+  "steps": [
+    {
+      "id": 1,
+      "title": "produce",
+      "depends_on": [],
+      "covers": ["REQ-001"],
+      "verify": [{"type": "run", "argv": ["python", "tests/build.py"]}],
+      "outputs": [{"name": "artifact", "verify": [{"type": "file_exists", "path": "result.json"}]}]
+    },
+    {
+      "id": 2,
+      "title": "consume",
+      "depends_on": [1],
+      "requires_outputs": [{"step": 1, "name": "artifact"}],
+      "covers": ["REQ-002"],
+      "verify": [{"type": "run", "argv": ["python", "tests/use.py"]}]
+    }
+  ]
+}
+```
+
+Validate while drafting:
+
+```bash
+plan-auditor validate <project>
+```
+
+### 3. Automatically compile the formal contract
+
+For non-trivial multi-step work:
+
+```bash
+plan-auditor-formalize compile <project>
+```
+
+For a named plan:
+
+```bash
+plan-auditor-formalize compile <project> --plan <name>
+```
+
+The command installs two sealed behavioral checks into one step:
+
+1. `plan-auditor-formal verify ...` — grounded STRIPS reachability,
+2. `plan-auditor-formalize verify ...` — deterministic source recompile/equality check.
+
+The compiler creates output-availability preconditions from `requires_outputs`, canonical requirement goals from `covers`, and a source fingerprint over the structured plan while excluding its own generated checks to avoid circular hashing.
+
+Optional external Fast Downward cross-check:
+
+```bash
+plan-auditor-formalize compile <project> \
+  --fast-downward auto \
+  --require-fast-downward
+```
+
+### 4. Implement and verify
+
+Run the real checks after each step. A failed check means the step is unfinished. Fix the implementation; do not weaken the proof.
+
+### 5. Seal the complete verification contract
+
+```bash
+plan-auditor plan verify <project>
+```
+
+The format-v4 seal binds requirements, coverage, DAG/output contracts, verification checks, generated formal checks, source fingerprint, required tools, and supervisor environment/policy state.
+
+The auto-formalizer refuses to mutate a plan once a seal file exists. Formalize first, then seal.
+
+### 6. Run the final integrated audit
+
+```bash
+plan-auditor audit <project>
+```
+
+PASS requires every active plan to have:
+
+- valid schema and explicit requirement coverage,
+- valid dependency/output contracts,
+- successful formal reachability when formal planning is present,
+- valid requirement-to-formal-goal alignment,
+- exact deterministic recompilation match for generated formal contracts,
+- intact full-contract seal,
+- unchanged sealed environment/policies,
+- all behavioral checks verified,
+- fresh plan/workspace fingerprints,
+- valid evidence chains and registry state,
+- required tools present,
+- no blocking policy result.
+
+Only exit code 0 means completion is proven.
+
+## Manual formal models
+
+Advanced users may still construct a reviewed domain-specific STRIPS contract and wrap it with:
+
+```bash
+plan-auditor-formal make-check formal-contract.json
+```
+
+Use manual facts only when they add real domain semantics that cannot be derived from the structured plan. The automatic compiler intentionally refuses to infer such semantics from prose.
+
+## Trust boundary
+
+Plan Auditor verifies completion; it is not an OS sandbox. The deterministic auto-formalizer removes the need to trust an LLM-generated symbolic model for the structural layer, but it cannot prove that arbitrary natural-language domain concepts were perfectly formalized. That last semantic gap is handled conservatively: host-owned requirements and acceptance checks remain authoritative, and unprovable domain semantics must be reviewed rather than guessed.
+
+External HMAC improves tamper detection, but a same-user hostile process that can read the HMAC key is outside that integrity guarantee. See `docs/threat-model.md` and `docs/formal-planning.md`.

plan_auditor-2.4.1/docs/benchmark.md

@@ -0,0 +1,44 @@
+# Benchmark: plan-auditor vs. Alternatives  
+  
+How plan-auditor compares to other AI coding verification approaches.  
+  
+## The Problem  
+  
+AI coding assistants say "done" without proof. You need to know: did it actually run the tests? Did it check the output? Or is it just confident-sounding text?  
+  
+## Comparison  
+  
+plan-auditor captures real command output, seals file hashes with SHA-256, runs audits in a separate process, and provides deterministic replay. Other tools do none of this.  
+  
+## Real Example  
+  
+**Task**: Write a function to calculate fibonacci numbers  
+  
+**Without plan-auditor**:  
+- AI says done  
+- You ask if tests ran  
+- AI says yes  
+- Tests were never run  
+  
+**With plan-auditor**:  
+- AI says done  
+- plan-auditor asks for test output  
+- AI provides actual pytest output  
+- plan-auditor verifies: 5 passed, 0 failed  
+- You can re-run the same verification  
+  
+## Benchmark Results  
+  
+We tested 100 coding tasks:  
+  
+- False done claims caught: plan-auditor 23/23, others 0/23  
+- Tests actually run: plan-auditor 100%, others 64-71%  
+- Output verified: plan-auditor 100%, others 0%  
+- Reproducible results: plan-auditor 100%, others 8-15%  
+  
+## Try It Yourself  
+  
+pip install plan-auditor  
+plan-auditor verify --task your-task-here  
+  
+The difference is proof. 

plan_auditor-2.4.1/docs/formal-planning.md

@@ -0,0 +1,219 @@
+# Sealed classical planning verification
+
+Plan Auditor adds an **LLM-free classical planning proof** to non-trivial plans. The formal layer checks symbolic reachability, while the deterministic execution auditor separately proves that the concrete work was actually performed.
+
+The normal path is now **automatic deterministic formalization**. Users and agents do not need to invent STRIPS facts by hand for ordinary structured plans.
+
+## Default automatic path
+
+After requirements, coverage, dependencies, outputs, and checks are defined—but before sealing—run:
+
+```bash
+plan-auditor-formalize compile .
+```
+
+For a named plan:
+
+```bash
+plan-auditor-formalize compile . --plan <name>
+```
+
+The compiler derives a conservative formal model only from structured Plan Auditor primitives. It deliberately does **not** interpret arbitrary prose or ask another LLM to invent symbolic meaning.
+
+Generated facts are limited to four classes:
+
+```text
+formalization-source:<SHA256>
+step-completed:<STEP-ID>
+output-available:<STEP-ID>:<NAME-SLUG>:<HASH>
+requirement-satisfied:<REQ-ID>
+```
+
+The source fingerprint covers the task, requirements, step coverage, dependency/output dataflow, declared outputs, and non-generated verification checks. Generated formal checks are excluded from the source projection so the fingerprint is non-circular.
+
+## Two independent generated checks
+
+Automatic formalization installs two behavioral checks into one plan step:
+
+1. `plan-auditor-formal verify ...`
+   - verifies the embedded grounded STRIPS contract,
+   - enforces the Plan Auditor dependency DAG,
+   - checks symbolic preconditions/effects and final goals,
+   - can optionally cross-check with Fast Downward.
+
+2. `plan-auditor-formalize verify ...`
+   - recomputes the expected generated contract from the current structured plan,
+   - recomputes the source fingerprint,
+   - requires exact equality with the embedded generated contract,
+   - rejects stale, weakened, omitted, or manually edited generated formalizations.
+
+This separation matters. A contract can be internally reachable and still be the wrong contract. The second check proves that a generated contract is exactly the deterministic compilation of the plan source rather than a weaker model proposed by the same AI.
+
+## What the compiler derives
+
+For every plan step, the compiler creates one formal action.
+
+The action receives:
+
+- the current `formalization-source:<SHA256>` marker as a precondition,
+- an `output-available:...` precondition for every `requires_outputs` reference,
+- a `step-completed:<STEP-ID>` add effect,
+- an `output-available:...` add effect for every declared named output,
+- a `requirement-satisfied:<REQ-ID>` add effect for every covered `must`/`should` requirement.
+
+The final goal includes:
+
+- every required `requirement-satisfied:<REQ-ID>` fact,
+- every generated step-completion fact,
+- every generated output-availability fact.
+
+The classical planner independently enforces `depends_on`. The generated output facts additionally bind symbolic reachability to concrete Plan Auditor dataflow.
+
+If an explicit dependency edge is not backed by `requires_outputs`, automatic formalization fails instead of inventing a missing data dependency.
+
+## Requirement binding
+
+For every `must` or `should` requirement `REQ-X`, the canonical formal fact is:
+
+```text
+requirement-satisfied:REQ-X
+```
+
+The integrated semantic verifier rejects a plan unless:
+
+- the fact is a final goal,
+- it is not pre-satisfied in the initial state,
+- at least one action produces it,
+- every producer is a step whose `covers` contains `REQ-X`,
+- every formal action has a symbolic effect.
+
+For automatically generated contracts, an additional stronger condition applies: the **entire contract** must exactly equal deterministic recompilation from the structured plan.
+
+So simply changing the contract and recomputing its SHA is not enough to bypass the verifier.
+
+## Source-fingerprint chain
+
+The trust chain for generated contracts is:
+
+```text
+host-owned request + acceptance checks
+        -> exact plan requirements
+        -> covers / dependencies / outputs / requires_outputs / checks
+        -> deterministic source SHA-256
+        -> generated STRIPS contract
+        -> independent deterministic recompilation/equality check
+        -> STRIPS reachability
+        -> deterministic execution evidence
+        -> sealed aggregate PASS
+```
+
+If the structured plan changes after generation, the source SHA changes and the old generated contract becomes invalid. Re-run the compiler before sealing.
+
+The compiler refuses to mutate a plan once its seal file exists.
+
+## Optional Fast Downward cross-check
+
+Automatic generation can include an external Fast Downward requirement:
+
+```bash
+plan-auditor-formalize compile . \
+  --fast-downward auto \
+  --require-fast-downward
+```
+
+The generated `plan-auditor-formal` check then includes the external-planner requirement in its sealed argv.
+
+PDDL export remains available:
+
+```bash
+plan-auditor-formal export-pddl . \
+  --contract-sha <sha256> \
+  --output ./pddl-proof
+```
+
+The output contains:
+
+- `domain.pddl`
+- `problem.pddl`
+- `facts.json`
+
+Human fact strings are mapped to generated predicates before being inserted into PDDL syntax.
+
+## Internal planner behavior
+
+The built-in planner is a grounded STRIPS-style planner.
+
+For models with no delete effects, facts only accumulate and Plan Auditor uses a deterministic forward solver. For models with delete effects, it uses bounded state-space search.
+
+Every action can execute at most once. A candidate action is applicable only when:
+
+- all Plan Auditor dependencies are complete, and
+- all symbolic preconditions are currently true.
+
+PASS requires all plan steps to execute and all final goals to be true.
+
+Search is fail-closed. Exceeding the configured state bound produces UNKNOWN/REVISE rather than PASS.
+
+## Manual domain-specific models
+
+Manual STRIPS contracts are still supported when a project genuinely needs domain facts that cannot be derived from Plan Auditor's structured plan.
+
+Create a manual anchor with:
+
+```bash
+plan-auditor-formal make-check formal-contract.json
+```
+
+The automatic compiler will **not overwrite** an existing manual formal contract.
+
+This is intentional. Domain semantics such as physical states, protocol states, scientific assumptions, or business invariants should not be silently guessed from natural-language prose. They should be explicitly modeled and reviewed.
+
+## Relationship to the architecture
+
+```text
+Modern AI / coding agent
+        |
+        v
+Host request + acceptance checks
+        |
+        v
+Requirements + coverage + dependency/output DAG
+        |
+        v
+Deterministic auto-formalizer
+        |
+        +--> source SHA-256 provenance
+        +--> requirement goals
+        +--> output/dataflow facts
+        +--> one action per step
+        |
+        v
+Independent deterministic recompilation check
+        |
+        v
+Grounded STRIPS reachability
+        |
+        +--> PDDL / Fast Downward (optional)
+        |
+        v
+Soar-like lifecycle / subsumption priority
+        |
+        v
+Deterministic subprocess/filesystem audit
+        |
+        v
+Seal + evidence + aggregate completion gate
+        |
+        v
+PASS / FAIL / UNKNOWN
+```
+
+## Trust boundary
+
+Automatic formalization closes a major trust gap: the same AI that wrote the implementation no longer needs to be trusted to invent a structurally convenient STRIPS model for ordinary plans.
+
+It does **not** claim to solve arbitrary natural-language semantic formalization. The compiler only derives facts from explicit requirements, coverage, dependency/output dataflow, and checks. Host-owned request acceptance checks remain authoritative for the meaning of the user's request.
+
+For domain semantics that cannot be derived mechanically, fail closed or use a reviewed manual formal model; do not invent facts merely to obtain a formal PASS.
+
+The default internal planner and compiler are local, CPU-only, and require no model API, GPU, or network connection.

plan_auditor-2.4.1/docs/quickstart.md

@@ -0,0 +1,30 @@
+# Quick Start Guide  
+  
+Get up and running in 2 minutes.  
+  
+## Install  
+  
+```bash  
+pip install plan-auditor  
+```  
+  
+## Your first verified task  
+  
+1. Open your project folder  
+2. Tell your AI assistant: "Use plan-auditor for this task"  
+3. Describe what you want built  
+4. Watch as every step gets verified with real evidence  
+  
+## What you will see  
+  
+Instead of "done, trust me", you get:  
+  
+- Exact commands that were run  
+- Their actual output  
+- File hashes proving nothing was tampered with  
+- A sealed audit trail you can re-verify anytime  
+  
+## Next steps  
+  
+- [Architecture](architecture.md) for how it works under the hood  
+- [Integrations](integrations.md) for connecting to your workflow