doneproof 0.1.0__py3-none-any.whl

doneproof/__init__.py

@@ -0,0 +1,102 @@
+"""doneproof: accept a task only when its done-ness is proven by evidence.
+
+An agent (or a plan) declares *doneproof* conditions in plain strings. This
+package classifies each one as **passed**, **failed** or **unverifiable** by
+checking real evidence — never the agent's own word that it finished.
+
+Two evidence kinds are understood (the only two that verify without
+interpreting free text):
+
+- ``<path> exists`` — the file exists under the run's root directory. The path
+  is resolved and must stay inside the root (no ``../`` escape).
+- ``human_gate_resolved on <step>`` — a human approval for ``<step>`` was
+  recorded. "Was it recorded?" is answered by a caller-supplied predicate
+  (``gate_resolved``), so this package never depends on any particular event
+  store, queue or database.
+
+A condition in any other shape is **not failed** — it is reported as
+``unverifiable`` so the caller can decide. Refusing to fail on what you cannot
+check by evidence is as important as refusing to pass on an agent's say-so.
+
+    from pathlib import Path
+    from doneproof import evaluate, is_satisfied
+
+    result = evaluate(Path("runs/42"), ["artifacts/report.md exists"])
+    assert is_satisfied(result)
+
+The return value is a plain JSON-serializable dict so it drops straight into a
+log or an event. ``is_satisfied`` is true iff there are no failures;
+unverifiable conditions do not make a run fail.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+__version__ = "0.1.0"
+
+__all__ = ["GateResolved", "__version__", "evaluate", "is_satisfied"]
+
+# "Was the human gate on <step> resolved?" — the one thing this package cannot
+# check from the filesystem. The caller supplies it (bound to its own event log,
+# queue, DB, …). Default: nothing is resolved, so gate conditions fail closed.
+GateResolved = Callable[[str], bool]
+
+_EXISTS = re.compile(r"^(?P<path>\S+)\s+exists$")
+_GATE = re.compile(r"^human_gate_resolved\s+on\s+(?P<step>\S+)$")
+
+
+def evaluate(
+    root: str | Path,
+    conditions: list[str],
+    gate_resolved: GateResolved | None = None,
+) -> dict[str, list[Any]]:
+    """Classify each condition into ``passed``, ``failed`` or ``unverifiable``.
+
+    ``root`` is the run directory that ``<path> exists`` conditions resolve
+    against; a path that escapes it fails. ``gate_resolved(step) -> bool``
+    answers ``human_gate_resolved on <step>``; when omitted, no gate is
+    considered resolved (fail-closed).
+
+    Returns ``{"passed": [...], "failed": [...], "unverifiable": [...]}``.
+    ``passed`` and ``failed`` items are ``{"kind", "target"}``
+    (kind = ``file_exists`` | ``gate_resolved``); ``failed`` items also carry
+    ``{"condition", "reason"}``. ``unverifiable`` keeps the original strings.
+    Passed items omit the original text so a reader scanning for the literal
+    ``human_gate_resolved`` does not confuse an accepted condition with the
+    real approval event.
+    """
+    resolved = gate_resolved if gate_resolved is not None else (lambda _step: False)
+    result: dict[str, list[Any]] = {"passed": [], "failed": [], "unverifiable": []}
+    base = Path(root).resolve()
+    for raw in conditions:
+        cond = str(raw).strip()
+        m = _EXISTS.match(cond)
+        if m:
+            item = {"kind": "file_exists", "target": m.group("path")}
+            target = (base / m.group("path")).resolve()
+            if not target.is_relative_to(base):
+                result["failed"].append({**item, "condition": cond, "reason": "path outside the run directory"})
+            elif target.is_file():
+                result["passed"].append(item)
+            else:
+                result["failed"].append({**item, "condition": cond, "reason": "file missing"})
+            continue
+        m = _GATE.match(cond)
+        if m:
+            item = {"kind": "gate_resolved", "target": m.group("step")}
+            if resolved(m.group("step")):
+                result["passed"].append(item)
+            else:
+                result["failed"].append({**item, "condition": cond, "reason": "gate not resolved"})
+            continue
+        result["unverifiable"].append(cond)
+    return result
+
+
+def is_satisfied(result: dict[str, list[Any]]) -> bool:
+    """True iff nothing failed. Unverifiable conditions do not fail a run."""
+    return not result["failed"]

doneproof/cli.py

@@ -0,0 +1,53 @@
+"""doneproof CLI: check acceptance conditions by evidence, exit 0/1.
+
+    doneproof check <root> [CONDITION ...] [--resolved STEP ...] [--json]
+
+Exit 0 when nothing failed (unverifiable conditions do not fail), 1 otherwise.
+``--resolved STEP`` marks a human gate as resolved (repeatable); without it,
+``human_gate_resolved on <step>`` fails closed. ``--json`` prints the full
+structured result instead of the human summary.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__, evaluate, is_satisfied
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="doneproof", description=__doc__.splitlines()[0])
+    ap.add_argument("--version", action="version", version=f"doneproof {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("check", help="Check conditions against evidence under <root>")
+    c.add_argument("root", help="The run directory that `<path> exists` resolves against")
+    c.add_argument("conditions", nargs="*", help="doneproof conditions, e.g. 'artifacts/r.md exists'")
+    c.add_argument(
+        "--resolved", action="append", default=[], metavar="STEP", help="Mark a human gate as resolved (repeatable)"
+    )
+    c.add_argument("--json", action="store_true", help="Print the full structured result")
+    args = ap.parse_args(argv)
+
+    resolved = set(args.resolved)
+    result = evaluate(args.root, args.conditions, gate_resolved=lambda step: step in resolved)
+
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        for item in result["passed"]:
+            print(f"ok   {item['kind']}: {item['target']}")
+        for item in result["failed"]:
+            print(f"FAIL {item['kind']}: {item['target']} ({item['reason']})")
+        for cond in result["unverifiable"]:
+            print(f"?    unverifiable: {cond}")
+        print(
+            f"doneproof: {'satisfied' if is_satisfied(result) else 'FAILED'} "
+            f"({len(result['failed'])} failed, {len(result['unverifiable'])} unverifiable)"
+        )
+    return 0 if is_satisfied(result) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

doneproof-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: doneproof
+Version: 0.1.0
+Summary: Accept a task only when its done-ness is proven by evidence (a file exists, a human gate was resolved) — never the agent's own word. Plain data, zero dependencies, pluggable into any runner or agent.
+Author: LRNSdigital
+License-Expression: MIT
+Project-URL: Repository, https://github.com/souzalrns/network-agents-setup/tree/main/oss/doneproof
+Project-URL: Issues, https://github.com/souzalrns/network-agents-setup/issues
+Keywords: acceptance,done-criteria,evidence,agents,task-completion,verification,claude-code,plugin,automation,gate
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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 :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing :: Acceptance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# doneproof
+
+**Accept a task only when its done-ness is proven by evidence — never the agent's own word.**
+
+An agent (or a plan) declares *doneproof* conditions as plain strings. `doneproof`
+checks each one against real evidence and reports **passed**, **failed** or
+**unverifiable**. Zero dependencies, pure stdlib, pluggable into any runner or agent.
+
+```python
+from pathlib import Path
+from doneproof import evaluate, is_satisfied
+
+result = evaluate(Path("runs/42"), [
+    "artifacts/report.md exists",
+    "human_gate_resolved on publish",
+], gate_resolved=lambda step: step in resolved_steps)
+
+if not is_satisfied(result):
+    raise SystemExit(f"not done: {result['failed']}")
+```
+
+Or from the shell:
+
+```console
+$ doneproof check runs/42 "artifacts/report.md exists" "human_gate_resolved on publish" --resolved publish
+ok   file_exists: artifacts/report.md
+ok   gate_resolved: publish
+doneproof: satisfied (0 failed, 0 unverifiable)
+```
+
+## Why it exists
+
+Most agent frameworks accept `status: done` because the agent *said* it was done.
+That is the failure mode `doneproof` refuses. A task is accepted only when its
+completion is **verifiable**:
+
+| Condition | Evidence checked |
+|-----------|------------------|
+| `<path> exists` | the file exists under the run's root (no `../` escape) |
+| `human_gate_resolved on <step>` | a human approval for `<step>` was recorded |
+
+Everything else is reported as **unverifiable** — not failed. Refusing to fail on
+what you cannot check by evidence is as important as refusing to pass on a say-so.
+The caller decides what to do with the unverifiable bucket (log it, require review,
+or ignore it).
+
+## The gate seam (store-agnostic)
+
+`doneproof` never talks to an event store, queue or database. "Was the gate on
+`<step>` resolved?" is answered by a predicate you pass in:
+
+```python
+evaluate(root, conditions, gate_resolved=lambda step: my_log.approved(step))
+```
+
+Omit it and gates **fail closed** (nothing is considered resolved). This one seam
+is why the same engine runs inside a governed runner and standalone in a test.
+
+## API
+
+- `evaluate(root, conditions, gate_resolved=None) -> dict` — returns
+  `{"passed": [...], "failed": [...], "unverifiable": [...]}`, JSON-serializable.
+  `passed`/`failed` items are `{"kind", "target"}` (kind = `file_exists` |
+  `gate_resolved`); `failed` items also carry `{"condition", "reason"}`.
+- `is_satisfied(result) -> bool` — true iff nothing failed (unverifiable does not fail).
+- `GateResolved` — the `Callable[[str], bool]` type of the gate predicate.
+
+## How it compares
+
+`doneproof` is an **acceptance primitive** for agent/task runs, not a test runner
+or a BDD framework. See `POSITIONING.md` for the evidence-based comparison with
+pytest, BDD (Gherkin) and shell CI gates, and for what it deliberately does not do.
+
+## Install
+
+```console
+pip install doneproof
+```
+
+MIT licensed. Part of the [network-agents-setup](https://github.com/souzalrns/network-agents-setup)
+ecosystem; extracted from its governed runner so any project can accept tasks by evidence.

doneproof-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+doneproof/__init__.py,sha256=SpLsJznW3cvk-Bx5hJkhicVq5fyfpeQUw9iOgddFQbk,4376
+doneproof/cli.py,sha256=qzYuXURzdCkwJppIaZXzGgfHVMkoR1qSJXCTvpuq5hQ,2201
+doneproof/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+doneproof-0.1.0.dist-info/licenses/LICENSE,sha256=P6Zc-2fxHBXsuWu4oyLoFCnSLMQ_A0m6jji3nvbskAk,1080
+doneproof-0.1.0.dist-info/licenses/NOTICE,sha256=QuyPrql_2DSoi_E90JpMeXcwhWmDaWW4_wzviDSClHI,519
+doneproof-0.1.0.dist-info/METADATA,sha256=X4zYvOeHEnY8IJfqZsegxjGoX0iJxclJRRKaEu_U5jQ,4408
+doneproof-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+doneproof-0.1.0.dist-info/entry_points.txt,sha256=tqXUNU7mhcvzwJEQh9iI95jJavX5pqBOEddExv3qYd0,49
+doneproof-0.1.0.dist-info/top_level.txt,sha256=2muWm1JbGh-o9-p1n8Pvs6xhgL2TVwcsxZakZ6pe3Ng,10
+doneproof-0.1.0.dist-info/RECORD,,

doneproof-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

doneproof-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+doneproof = doneproof.cli:main

doneproof-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LRNSdigital (souzalrns)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

doneproof-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,9 @@
+doneproof
+Copyright (c) 2026 LRNSdigital (souzalrns). Licensed under the MIT License (see LICENSE).
+
+doneproof has no third-party runtime dependencies. The conditions are plain strings and the
+engine is the Python standard library only (re, pathlib). Nothing is bundled or vendored.
+
+Extracted from the governed runner at github.com/souzalrns/network-agents-setup
+(runner/plan_runner/done_when.py). The runner keeps the glue that binds this engine to its
+event log; this package is the standalone, store-agnostic core.

doneproof-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+doneproof