plan-auditor 2.4.3__tar.gz → 2.4.4__tar.gz

{plan_auditor-2.4.3 → plan_auditor-2.4.4}/.gitignore

@@ -44,3 +44,8 @@ pack.json
 # mypy cache from the type ratchet job
 .mypy_cache/
 .ruff_cache/
+
+# Upstream commit lookups cached by .github/scripts/check_action_pins.py. The
+# cache exists so repeated local runs and a cold CI runner do not re-query the
+# API; it is machine-local state and must never be committed.
+.action-pin-cache/

{plan_auditor-2.4.3 → plan_auditor-2.4.4}/CHANGELOG.md

@@ -4,6 +4,138 @@ All notable changes to plan-auditor. Versions are published to PyPI and npm.
 
 ## Unreleased
 
+## 2.4.4 — HMAC check subprocess boundary
+
+### Security
+
+- Do not inherit `PLAN_AUDITOR_HMAC_KEY` or `PLAN_AUDITOR_HMAC_KEY_FILE`
+  into project-controlled behavioral-check subprocesses. The supervisor
+  retains these credentials to authenticate the resulting audit evidence.
+- Add regression tests for both credential variables, benign environment
+  preservation, parent environment preservation, and the public `run_check`
+  path.
+- Clarify that environment sanitisation is defense in depth, **not** OS
+  sandboxing: an untrusted child running as the supervisor's user can still
+  open any HMAC key file that user can read. Deliberately hostile agents need
+  a separately isolated, keyless check-execution identity/container.
+
+### Documentation
+
+- **README reduced from 362 to 248 lines with no surface lost.** The previous
+  release traded a line target for coverage and stopped at 356, on the reasoning
+  that the layer table, command tables and artifact list were the coverage gap.
+  That was right about the priority and wrong about the arithmetic: the reduction
+  had not been attempted. Detail now lives on the docs site and the README keeps a
+  scannable map plus links. Measured against the same 66-surface checklist derived
+  from the code, **0 surfaces are undocumented**: 37 still appear in the README and
+  29 moved to a named docs page.
+  - The L0-L14 layer table became a five-row band map. It still names all fifteen
+    layers, and the two facts that carry the design are now stated in the prose
+    rather than buried in a row: **L10 (`scripts/audit_check.py`) is the only
+    component that can mark a step `verified`** and **L13 (`gate.py`) is the only
+    one that emits a final `PASS`/`FAIL`/`UNKNOWN`**. Per-layer detail was already
+    in `docs/architecture.md`.
+  - The fourteen workspace artifacts moved to a new **`docs/workspace-artifacts.md`**,
+    which also records what is *not* written and why the files are separated
+    (append-only evidence, host-owned input separate from agent-owned state, and a
+    stale verdict being detectable). The README still says the tool writes under
+    `.plan-auditor/` and links the page.
+  - The full command table was already in `docs/cli.md`; the README now names the
+    four entry points and the five check types, and `docs/cli.md` gained an explicit
+    `0`/`1`/`2`/`3` exit-code legend so the codes have one canonical home.
+  - `## Reference` was folded into `## Documentation` rather than kept as a second
+    index. The heading name is unchanged on purpose: a test splits the README on it.
+  - The `## Use it in CI` yaml block became one prose line pointing at
+    `docs/integrations.md`.
+  - The quick start keeps the structure `tests/test_readme_quickstart.py` requires:
+    exactly two JSON blocks, one console block, and the same four commands. Both
+    plan files and the transcript were compressed using the `...` elision the test
+    already tolerates. **The `request_sha256` changed** because the documented
+    `task` string was shortened, and it was re-derived by running the walkthrough,
+    not computed: `d39e577eb0577d8c0c81231fdd7fc559d1c6045ecc5e5bd3a00e7e8f2f49197b`.
+  - `docs/index.md` now links `workspace-artifacts.md` and `release-status.md`,
+    which it did not, so the docs home is a real index rather than a partial one.
+
+- **`docs/check_readme_size.py` guards against re-inflation.** It fails when
+  `README.md` exceeds a recorded line and word budget, **and** when any single
+  `## ` section exceeds its own budget, so one section cannot quietly absorb the
+  whole allowance. `docs/readme_size_baseline.json` holds the recorded budget
+  (248 lines, 1490 words) and `--update` re-records it, printing a warning when a
+  budget is raised rather than lowered. Verified by mutation: appending twelve
+  invented bullets to `Honest limits` exits 1 naming that section, and a four-line
+  prose expansion of `Documentation` exits 1 naming lines, words and that section.
+  **It is not wired into CI by this change** — adding the job means editing
+  `.github/workflows/`, which is outside this work's file ownership. Until it is
+  wired, the guard only runs when invoked by hand.
+
+- The `2.4.3` attestation facts were re-measured rather than assumed: the PyPI
+  per-file provenance endpoint returns `200` for both the wheel and the sdist, and
+  the npm attestations endpoint returns `404`. The README keeps the two-line
+  statement naming both channels, and `test_readme_states_the_npm_attestation_gap`
+  still passes against it.
+
+### Fixed
+
+- **Supply-chain claims are now measured, scoped and separated by mechanism.** The three
+  things that get blurred into "attested" are now named separately wherever they appear
+  in `README.md`, `SECURITY.md` and `docs/release-status.md`:
+  1. a **digest** (`dist.integrity`, `digests.sha256`) proves the bytes match what was
+     published and says nothing about the build;
+  2. npm's **`dist.signatures`** is a registry *transport* signature over the packument,
+     present for every package whether or not it was built in CI, and is never build
+     provenance;
+  3. a **build attestation** (Sigstore/in-toto on npm, PEP 740 on PyPI) is the only one of
+     the three that names a workflow, repository and commit.
+- **The current version was stale at `2.4.2` in the release-status claims** while `2.4.3` is
+  the release on both registries. Refreshed, with the npm `shasum`, integrity, file count
+  and unpacked size, and the PyPI wheel and sdist SHA-256, all re-measured. The npm values
+  were re-checked by running `npm pack` on `main` (`45fd5ee`): integrity reproduces exactly.
+- **The PyPI integrity URL shape is called out explicitly**, because reading the wrong shape
+  is how a false negative gets reported. PyPI serves attestations **per file**, so the path
+  ends in `/<filename>/provenance`. `https://pypi.org/integrity/plan-auditor/2.4.3/` is not
+  an endpoint and returns `404`; that `404` means "no such URL", **not** "no attestation".
+  The per-file endpoint returns `200` with an in-toto v1 statement, predicate type
+  `https://docs.pypi.org/attestations/publish/v1`, publisher
+  `kind=GitHub, repository=Furox-Art/plan-auditor, workflow=release.yml, environment=pypi`,
+  whose subject digest equals the SHA-256 PyPI serves for the file.
+- **The condition for npm provenance is stated as pending**, with the four facts it needs:
+  a trusted publisher on npmjs.com for owner `Furox-Art`, package `plan-auditor`, workflow
+  filename `npm-publish.yml`, and the environment the publish job declares. Nothing in this
+  repository needs to change. Until that record exists, npm consumers verify by digest and
+  the docs keep saying so.
+- `SECURITY.md` gained the per-channel verification commands and the mechanism table, so a
+  reader can check a claim without trusting this repository.
+
+### Added
+
+- **`docs/check_attestation_claims.py`** — a regression guard for supply-chain claims, with
+  its own negative control. It rejects any attestation claim that names no channel, that
+  states no definite status, that presents `dist.signatures` as provenance, or that calls a
+  stale version current. Run it three ways:
+
+  ```bash
+  python docs/check_attestation_claims.py             # scan the docs
+  python docs/check_attestation_claims.py --online    # also re-measure both registries
+  python docs/check_attestation_claims.py --self-test # negative control
+  ```
+
+  The negative control feeds the guard five deliberately false claims and fails unless all
+  five are rejected, plus one correct claim it must accept and two same-word-different-meaning
+  cases (`docs/benchmark.md` measurement provenance, `docs/formal-planning.md` source
+  provenance) it must not flag. A guard that cannot be shown to reject a known lie is not a
+  guard, so `--self-test` is part of the deliverable rather than a nicety.
+
+  It is not wired into CI, because this change set does not touch workflows. Adding one step
+  to `.github/workflows/plan-audit.yml` that runs
+  `python docs/check_attestation_claims.py --self-test && python docs/check_attestation_claims.py`
+  would close that; until then it runs on demand.
+
+### Not claimed
+
+- No security claim is weakened anywhere. npm is still described as digest-only, and the
+  PyPI attestation is still described as present, because that is what the registries
+  return.
+
 ## v2.4.3 - 2026-10-04
 
 A documentation release. The README restructure and the three corrections below

{plan_auditor-2.4.3 → plan_auditor-2.4.4}/CITATION.cff

@@ -21,8 +21,8 @@ authors:
 repository-code: "https://github.com/Furox-Art/plan-auditor"
 url: "https://github.com/Furox-Art/plan-auditor"
 license: MIT
-version: 2.4.3
-date-released: "2026-10-03"
+version: 2.4.4
+date-released: "2026-10-10"
 keywords:
   - AI coding agents
   - deterministic verification

{plan_auditor-2.4.3 → plan_auditor-2.4.4}/CONTRIBUTING.md

@@ -221,7 +221,7 @@ with a non-zero code if Python cannot be started at all.
 - Every command you document must exist. `tests/test_docs_metadata.py` parses
   fenced code blocks and checks the subcommand against the real argument parser.
 - Every transcript must be copied from a real run, and any elision must say what
-  is elided. A `çıktı:` line whose interior depends on your Python version must be
+  is elided. An `output:` line whose interior depends on your Python version must be
   scoped, not quoted.
 - Never add a download count, a star count, a user count or a trust badge. Link to
   the package page instead; the tests reject a copied number.

plan_auditor-2.4.4/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: plan-auditor
+Version: 2.4.4
+Summary: Deterministic verification and evidence auditing for AI coding agents: sealed plans, hash-chained evidence, and an independent completion gate
+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
+Project-URL: Security, https://github.com/Furox-Art/plan-auditor/blob/main/SECURITY.md
+Project-URL: Contributing, https://github.com/Furox-Art/plan-auditor/blob/main/CONTRIBUTING.md
+Project-URL: Citation, https://github.com/Furox-Art/plan-auditor/blob/main/CITATION.cff
+Author: Furox-Art
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,ai-agents,ai-verification,audit-log,auditing,ci,ci-cd,cli,coding-agents,completion-gate,continuous-integration,developer-tools,evidence,formal-methods,formal-verification,hallucination-detection,llm-agents,model-checking,pddl,plan-execution,provenance,quality-assurance,software-testing,static-analysis,strips,supervisor,supply-chain-security,tamper-evident,test-automation,trust-but-verify,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Security
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Software Distribution
+Classifier: Topic :: System :: Systems Administration
+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)
+[![release](https://github.com/Furox-Art/plan-auditor/actions/workflows/release.yml/badge.svg)](https://github.com/Furox-Art/plan-auditor/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/plan-auditor)](https://pypi.org/project/plan-auditor/)
+[![Python](https://img.shields.io/pypi/pyversions/plan-auditor)](https://pypi.org/project/plan-auditor/)
+[![npm](https://img.shields.io/npm/v/plan-auditor)](https://www.npmjs.com/package/plan-auditor)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Download numbers live on the package pages themselves, where they are always current:
+[PyPI](https://pypi.org/project/plan-auditor/) |
+[npm](https://www.npmjs.com/package/plan-auditor)
+
+**An AI agent says "done." This tool makes "done" mean "here is the command output that proves it."**
+
+## The problem
+
+Ask a coding agent to change something and it reports success with confident prose.
+Sometimes it never ran the tests. Sometimes it ran them once, failed, and edited the
+test until it went green. What you are left with is narration, and narration looks
+identical to a result until you re-run everything yourself.
+
+## The solution
+
+Verification runs in a **separate process with its own check implementation**, so the
+implementing agent's claims carry no weight — only sealed command output does.
+
+- Every step is a machine-checkable requirement, not a prose bullet.
+- Every step needs at least one **behavioral** check (`run`, `pytest`, `exec`). A
+  file-existence check can never verify a step on its own.
+- Output is appended to a SHA-256 hash-chained, tamper-evident log.
+- The plan's verification contract is **sealed** on approval and can only be
+  strengthened afterwards, never weakened.
+- A failed check fails closed: `audit` exits non-zero until every check really passes.
+
+There is no LLM in the verification path, and no network call.
+
+## Who it is for
+
+- Anyone who ships AI-generated code and needs receipts before merge.
+- Agent-skill authors who want a gate an agent cannot talk its way past.
+- Teams adding a required CI step for "the agent must prove it".
+- Researchers who want LLM-free STRIPS/PDDL-style reachability checks over a plan.
+
+## Install
+
+```bash
+pipx install plan-auditor          # isolated CLI, recommended
+pip install plan-auditor           # into the current environment / virtualenv
+```
+
+Python 3.10 or newer, no third-party runtime dependencies. The npm package is a thin Node
+launcher for the same CLI and needs Python on `PATH`. The examples call the interpreter
+`python`; on a system that only ships `python3`, use a virtualenv that provides `python`.
+In CI, add `- uses: Furox-Art/plan-auditor@main` with `path: .` — see
+[integrations](https://github.com/Furox-Art/plan-auditor/blob/main/docs/integrations.md).
+
+**Release status:** `2.4.3` is current on both registries. PyPI publishes every artifact
+with a PEP 740 provenance attestation; npm has **no** provenance attestation and its
+attestations endpoint returns `404` for one. Measured per channel in
+[docs/release-status.md](https://github.com/Furox-Art/plan-auditor/blob/main/docs/release-status.md).
+
+## Quick start (verified, 5 minutes)
+
+`tests/test_readme_quickstart.py` runs these commands on every CI run and compares the
+transcript to real output without normalising hash values, so it cannot drift. Copy the
+two files verbatim — `request-source.json` is the input to the `request_sha256` below.
+
+**1. Create the project and the plan.**
+
+```bash
+mkdir plan-auditor-demo && cd plan-auditor-demo
+mkdir .plan-auditor
+```
+
+`.plan-auditor/plan.json`, and `request-source.json` beside it — the host-owned
+statement of what you asked for, sealed on activation so the agent cannot restate it:
+
+```json
+{
+  "task": "Prove README.md exists and prints its first line",
+  "created": "2026-07-24T00:00:00",
+  "requirements": [{ "id": "REQ-001", "description": "README.md must exist in the project root and print its first line.", "priority": "must" }],
+  "steps": [{
+    "id": 1, "title": "README.md exists and is readable", "covers": ["REQ-001"], "status": "pending",
+    "verify": [
+      { "type": "file_exists", "path": "README.md" },
+      { "type": "run", "cmd": "python -c \"print(open('README.md', encoding='utf-8').read().strip())\"", "expect_exit": 0 }
+    ]
+  }]
+}
+```
+
+```json
+{
+  "format_version": 1,
+  "task": "Prove README.md exists and prints its first line",
+  "requirements": [{
+    "id": "REQ-001", "description": "README.md must exist in the project root and print its first line.", "priority": "must",
+    "acceptance_checks": [
+      { "type": "file_exists", "path": "README.md" },
+      { "type": "run", "cmd": "python -c \"print(open('README.md', encoding='utf-8').read().strip())\"", "expect_exit": 0 }
+    ]
+  }]
+}
+```
+
+**2. Run the gate.**
+
+```bash
+plan-auditor request init . --file request-source.json
+plan-auditor plan verify .
+plan-auditor run . 1
+plan-auditor audit .
+```
+
+Real output. A lone `...` marks fields omitted for length; every other line is verbatim,
+and every JSON level that is not elided lists exactly the keys the tool emits.
+
+```console
+$ plan-auditor request init . --file request-source.json
+{
+  "activated": true,
+  "valid": true,
+  "reason": "request contract active",
+  "request_sha256": "d39e577eb0577d8c0c81231fdd7fc559d1c6045ecc5e5bd3a00e7e8f2f49197b",
+  "authenticated": false
+}
+$ plan-auditor plan verify .
+{
+  "plans": {
+    ...
+  },
+  "outcome": "PASS"
+}
+$ plan-auditor run . 1
+[OK ] step 1: README.md exists and is readable (attempt 1/3)
+       - passed | README.md EXISTS
+       - passed | exit=0 (expected 0)
+$ plan-auditor audit .
+...
+{
+  "outcome": "PASS",
+  "plans": {
+    "default": "PASS"
+  },
+  "deterministic_core": "fresh audit PASS for every active plan under workspace-wide freeze",
+  "gate": {
+    "outcome": "PASS",
+    ...
+  }
+}
+```
+
+Scoped omission: the elided fields are the plan-inspection block and `seal`, the per-step
+progress lines and verdict table, and the gate's remaining fields including
+`policy_findings`, `verdict` and `seal_ok`. [docs/cli.md](https://github.com/Furox-Art/plan-auditor/blob/main/docs/cli.md)
+shows each command's full output.
+
+`audit` re-runs every check in a fresh subprocess, and only exit code `0` means the work is
+proven. Progress lines are English human-readable output; the JSON verdict
+is the stable machine interface, so parse `"outcome"`.
+
+## How it works
+
+Fifteen layers, arranged so a weaker signal can never overrule a stronger one. Two
+facts carry the design: **L10 (`scripts/audit_check.py`) is the only component that can
+mark a step `verified`**, and **L13 (`gate.py`) is the only one that emits a final
+`PASS`/`FAIL`/`UNKNOWN`**. Everything else feeds those two.
+
+| Band | Layers | Role |
+|---|---|---|
+| Sense | L0 `events`, L1 `requirements`, L2 `workspace`, L5 `plan_verifier` | Read the task, the tree and the plan |
+| Decide | L3 `policies`, L4 `goals`, L7 `priority` | Deterministic rules; subsumption authority |
+| Protect | L8 `sealing`, L9 `watchdog`, L11 `evidence`, L12 `adversarial` | Seal, monitor, chain, propose |
+| Execute | **L10 `audit_check`**, L6 `lifecycle` | Run real checks; drive the state machine |
+| Gate | **L13 `gate`**, L14 `agents` | Emit the verdict; coordinate parallel agents |
+
+A failure at subsumption level N cannot be overridden by a PASS from any higher level.
+Per-layer detail, profiles (`light`/`standard`/`strict`), run modes
+(`serial`/`parallel-warn`/`parallel-strict`) and LLM tiers (`NO_LLM`, `SMALL_LOCAL`,
+`STRONG_LOCAL`, `REMOTE`) are in
+[docs/architecture.md](https://github.com/Furox-Art/plan-auditor/blob/main/docs/architecture.md).
+
+## Use it as an Agent Skill
+
+The skill is `SKILL.md` plus `scripts/`, `references/` and `hooks/`, either from a
+checkout or from a `pip` install, which ships them under `plan_auditor_skill/`. Copy
+them into your host's skills directory — `~/.claude/`, `~/.commandcode/`,
+`~/.config/opencode/` or `~/.codex/`, each with a `skills/plan-auditor/` subdirectory.
+`hooks/gate_hook.py` is the single authoritative hook gate; there are no per-host
+adapter files, so wire each host's blocking stop or lifecycle hook to that one command.
+Per-host paths and CI wiring:
+[docs/integrations.md](https://github.com/Furox-Art/plan-auditor/blob/main/docs/integrations.md).
+
+## Documentation
+
+Reading order starts at [docs/index.md](https://github.com/Furox-Art/plan-auditor/blob/main/docs/index.md).
+
+| You want | Go to |
+|---|---|
+| A verified task end to end; troubleshooting per real error | [quickstart](https://github.com/Furox-Art/plan-auditor/blob/main/docs/quickstart.md) |
+| Every subcommand, real invocations, exit codes `0`/`1`/`2`/`3` | [cli](https://github.com/Furox-Art/plan-auditor/blob/main/docs/cli.md) |
+| Per-layer detail, profiles, run modes, LLM tiers | [architecture](https://github.com/Furox-Art/plan-auditor/blob/main/docs/architecture.md) |
+| What the tool writes into `.plan-auditor/`, and why | [workspace artifacts](https://github.com/Furox-Art/plan-auditor/blob/main/docs/workspace-artifacts.md) |
+| Step DAGs, formal planning, threat model, deployment isolation | [dependency graph](https://github.com/Furox-Art/plan-auditor/blob/main/docs/dependency-graph.md) · [formal planning](https://github.com/Furox-Art/plan-auditor/blob/main/docs/formal-planning.md) · [threat model](https://github.com/Furox-Art/plan-auditor/blob/main/docs/threat-model.md) · [deployment isolation](https://github.com/Furox-Art/plan-auditor/blob/main/docs/deployment-isolation.md) |
+| Skill hosts, blocking hooks, CI | [integrations](https://github.com/Furox-Art/plan-auditor/blob/main/docs/integrations.md) |
+| Published versions, defects, attestations; what is measurable | [release status](https://github.com/Furox-Art/plan-auditor/blob/main/docs/release-status.md) · [benchmark](https://github.com/Furox-Art/plan-auditor/blob/main/docs/benchmark.md) |
+| Plan schema and check types | [plan-format.md](https://github.com/Furox-Art/plan-auditor/blob/main/references/plan-format.md) |
+
+Entry points: the `plan-auditor` CLI (`request`, `plan`, `evidence`, `integrity`,
+`supervisor`, `task`, `agents`, `run`, `validate`, `audit`, `doctor`); the core
+`python scripts/audit_check.py` (`validate`, `run`, `audit`, `status`, `snapshot`,
+`rollback`); and `plan-auditor-formalize`, `plan-auditor-formal` (`verify`,
+`export-pddl`, `make-check`) and `plan-auditor-migrate-seal`.
+
+Check types are `run`, `exec`, `pytest`, `regex` and `file_exists`; `regex` and
+`file_exists` are non-behavioural and cannot verify a step alone. Exit codes are `0`
+proven, `1` failed, `2` blocked, `3` `UNKNOWN` — and `3` withholds completion rather than
+passing it. The npm launcher mirrors them and fails closed. Runnable example:
+[`examples/fib/`](https://github.com/Furox-Art/plan-auditor/tree/main/examples/fib).
+
+No rendered documentation site exists yet. `mkdocs build --strict` is a required CI check,
+so the Markdown is known to build, but nothing serves it; build it with
+`python -m pip install mkdocs-material && mkdocs serve`. Files GitHub already renders:
+[SKILL.md](https://github.com/Furox-Art/plan-auditor/blob/main/SKILL.md) ·
+[CONTRIBUTING.md](https://github.com/Furox-Art/plan-auditor/blob/main/CONTRIBUTING.md) ·
+[CHANGELOG.md](https://github.com/Furox-Art/plan-auditor/blob/main/CHANGELOG.md) ·
+[SECURITY.md](https://github.com/Furox-Art/plan-auditor/blob/main/SECURITY.md)
+
+## Honest limits
+
+- **Not an OS sandbox.** In a normal install the agent and the verifier run as the
+  same OS user.
+- Evidence is **tamper-evident**, not tamper-proof; HMAC integrity is only as strong
+  as the secrecy of the key.
+- It verifies that *declared, checkable* requirements were met. Domain meaning that
+  cannot be a deterministic check is reviewed by a human, not guessed.
+- The npm package needs Python on `PATH` and carries **no** Sigstore build
+  attestation: the npm attestations endpoint returns `404` for `2.4.3`. Its
+  `dist.signatures` block is a registry transport signature and is **not** build
+  provenance, so verify the npm tarball against `dist.integrity` instead.
+  PyPI does carry a PEP 740 provenance attestation for every artifact.
+- No comparison against other tools has been measured, no telemetry is collected,
+  and no download or usage figure is printed anywhere in this repository.
+- Maintained by one person, pre-1.0, with no external contributors yet. That means
+  slow review, not unwanted contributions.